@relayer-ws/ping-proxy-residential

A TypeScript client for the Ping Proxies residential proxy API. This package provides a simple and type-safe way to interact with the Ping Proxies API to generate and manage residential proxy lists.

Features

• 🚀 TypeScript Support - Full TypeScript support with comprehensive type definitions
• 🔒 Type Safety - All API parameters and responses are fully typed
• 📦 Zero Dependencies - Uses native fetch and Headers (no external dependencies)
• 🎯 Simple API - Easy-to-use methods for common operations
• 🌍 Location Filtering - Filter proxies by country, city, zip code, and subdivision
• 🔄 Session Management - Support for both sticky and rotating sessions
• 🛡️ Error Handling - Comprehensive error handling with custom error types

Installation

npm install @relayer-ws/ping-proxy-residential

Quick Start

import { PingProxiesClient } from "@relayer-ws/ping-proxy-residential";

const client = new PingProxiesClient({
  privateKey: "your-private-key",
  publicKey: "your-public-key",
});

// Get a list of residential proxies
const proxies = await client.getResidentialList({
  list_count: 10,
  list_format: "socks5h",
  country_id: "US",
  list_session_type: "sticky",
});

console.log(proxies.data); // Array of proxy URLs

API Reference

PingProxiesClient

The main client class for interacting with the Ping Proxies API.

Constructor

new PingProxiesClient(config: PingProxiesConfig)

Parameters:

• config.privateKey (string, required): Your private API key
• config.publicKey (string, required): Your public API key
• config.baseUrl (string, optional): Base URL for the API (defaults to https://api.pingproxies.com/1.0)

Methods

getResidentialList(params?)

Generate a list of residential proxies based on filter parameters.

async getResidentialList(params?: ResidentialListParams): Promise<ResidentialListResponse>

Parameters:

• list_count (number, optional): Number of proxies to return (1-1000, default: 100)
• list_format (string, optional): Proxy format - 'standard', 'http', 'socks5', 'socks5h' (default: 'standard')
• proxy_user_id (string, optional): ID of the proxy user for authentication
• list_session_type (string, optional): Session type - 'sticky' or 'rotating' (default: 'sticky')
• country_id (string, optional): ISO country code (e.g., 'US', 'GB')
• city_id (number, optional): City ID
• city_alias (string, optional): City alias
• zip_code_id (number, optional): Zip code ID
• subdivision_id (number, optional): US subdivision ID
• list_smartpath_enabled (boolean, optional): Enable SmartPath
• list_session_ttl (string, optional): Session TTL
• list_mode (string, optional): Network optimization mode - 'general', 'size', 'speed' (default: 'general')

Returns: Promise resolving to ResidentialListResponse

getSingleResidentialProxy(params?)

Get a single residential proxy (convenience method).

async getSingleResidentialProxy(params?: ResidentialListParams): Promise<string | null>

getResidentialProxies(count, params?)

Get multiple residential proxies with a specific count.

async getResidentialProxies(
  count: number,
  params?: Omit<ResidentialListParams, 'list_count'>
): Promise<ResidentialListResponse>

Examples

Basic Usage

import { PingProxiesClient } from "@relayer-ws/ping-proxy-residential";

const client = new PingProxiesClient({
  privateKey: process.env.PING_PROXIES_PRIVATE_KEY!,
  publicKey: process.env.PING_PROXIES_PUBLIC_KEY!,
});

// Get 10 US proxies in SOCKS5 format
const result = await client.getResidentialList({
  list_count: 10,
  list_format: "socks5h",
  country_id: "US",
  list_session_type: "sticky",
});

console.log("Proxies:", result.data);
console.log("Message:", result.message);

Location-Specific Proxies

// Get proxies from a specific city
const cityProxies = await client.getResidentialList({
  list_count: 5,
  city_alias: "new-york",
  list_format: "http",
});

// Get proxies from a specific zip code
const zipProxies = await client.getResidentialList({
  list_count: 3,
  zip_code_id: 10001,
  list_format: "socks5",
});

Rotating vs Sticky Sessions

// Sticky session (same IP for the session duration)
const stickyProxies = await client.getResidentialList({
  list_count: 5,
  list_session_type: "sticky",
  list_session_ttl: "3600", // 1 hour
});

// Rotating session (IP changes with each request)
const rotatingProxies = await client.getResidentialList({
  list_count: 5,
  list_session_type: "rotating",
});

Error Handling

import {
  PingProxiesClient,
  PingProxiesAPIError,
} from "@relayer-ws/ping-proxy-residential";

const client = new PingProxiesClient({
  privateKey: "your-private-key",
  publicKey: "your-public-key",
});

try {
  const proxies = await client.getResidentialList({
    list_count: 10,
    country_id: "US",
  });
  console.log("Success:", proxies.data);
} catch (error) {
  if (error instanceof PingProxiesAPIError) {
    console.error("API Error:", error.message);
    console.error("Status:", error.status);
    console.error("Code:", error.code);
  } else {
    console.error("Unexpected error:", error);
  }
}

Cloudflare Workers Usage

// worker.ts
import { PingProxiesClient } from "@relayer-ws/ping-proxy-residential";

export default {
  async fetch(request: Request): Promise<Response> {
    const client = new PingProxiesClient({
      privateKey: "your-private-key",
      publicKey: "your-public-key",
    });

    try {
      const proxies = await client.getResidentialList({
        list_count: 5,
        country_id: "US",
        list_format: "socks5h",
      });

      return new Response(JSON.stringify(proxies), {
        headers: { "Content-Type": "application/json" },
      });
    } catch (error) {
      return new Response(JSON.stringify({ error: error.message }), {
        status: 500,
        headers: { "Content-Type": "application/json" },
      });
    }
  },
};

Types

The package exports comprehensive TypeScript types:

• PingProxiesConfig - Configuration for the client
• ResidentialListParams - Parameters for the residential list API
• ResidentialListResponse - Response from the residential list API
• ListFormat - Available proxy formats
• SessionType - Available session types
• ListMode - Available optimization modes
• PingProxiesAPIError - Custom error class

Requirements

• Node.js 18.0.0 or higher (or Cloudflare Workers runtime)
• TypeScript 5.0 or higher (for TypeScript projects)
• Native fetch and Headers support (available in modern browsers, Node.js 18+, and Cloudflare Workers)

License

MIT

Links

• Ping Proxies API Documentation
• NPM Package