npm package: @relayer-ws/ping-proxy-residential
Description: TypeScript client for Ping Proxies residential proxy API
Author: Relayer WS
Latest version: 2.0.3

# @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

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

## Quick Start

```typescript
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

```typescript
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.

```typescript
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).

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

##### getResidentialProxies(count, params?)

Get multiple residential proxies with a specific count.

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

## Examples

### Basic Usage

```typescript
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

```typescript
// 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

```typescript
// 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

```typescript
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

```typescript
// 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](https://documentation.pingproxies.com/api-reference/residential/create-residential-list)
- [NPM Package](https://www.npmjs.com/package/@relayer-ws/ping-proxy-residential)