Skip to content

proxy.md

Latest commit

 

History

History
518 lines (390 loc) · 11.3 KB

proxy.md

File metadata and controls

518 lines (390 loc) · 11.3 KB
Raw

Proxy Configuration Guide

This guide explains how to configure HTTP/HTTPS proxies with the Shopee SDK for routing API requests through proxy servers.

Overview

The SDK supports proxy configuration through Node.js HTTP/HTTPS agents. This is useful for:

  • Routing traffic through corporate proxies
  • Using proxy services for IP rotation
  • Testing with proxy tools like Charles or Fiddler
  • Bypassing rate limits (use responsibly)
  • Accessing region-specific APIs

Setting Up a Proxy

Using https-proxy-agent

The most common approach is using the https-proxy-agent package:

Installation

npm install https-proxy-agent

Basic Usage

import { ShopeeSDK } from '@congminh1254/shopee-sdk';
import { HttpsProxyAgent } from 'https-proxy-agent';

// Create proxy agent
const proxyAgent = new HttpsProxyAgent('http://proxy.example.com:8080');

// Initialize SDK
const sdk = new ShopeeSDK({
  partner_id: 123456,
  partner_key: 'your-key',
  agent: proxyAgent, // Set proxy agent
});

// All API calls will now go through the proxy
const products = await sdk.product.getItemList({
  offset: 0,
  page_size: 20,
});

Dynamic Proxy Configuration

You can change the proxy agent after SDK initialization:

import { HttpsProxyAgent } from 'https-proxy-agent';

const sdk = new ShopeeSDK({
  partner_id: 123456,
  partner_key: 'your-key',
});

// Set proxy later
const proxyAgent = new HttpsProxyAgent('http://proxy.example.com:8080');
sdk.setFetchAgent(proxyAgent);

// Make requests through proxy
await sdk.product.getItemList({ offset: 0, page_size: 20 });

// Remove proxy
sdk.setFetchAgent(undefined);

// Direct requests (no proxy)
await sdk.product.getItemList({ offset: 0, page_size: 20 });

Proxy Types

HTTP Proxy

import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://proxy.example.com:8080');
const sdk = new ShopeeSDK({
  partner_id: 123456,
  partner_key: 'your-key',
  agent,
});

HTTPS Proxy

import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('https://secure-proxy.example.com:8443');
const sdk = new ShopeeSDK({
  partner_id: 123456,
  partner_key: 'your-key',
  agent,
});

SOCKS Proxy

For SOCKS proxies, use the socks-proxy-agent package:

npm install socks-proxy-agent
import { SocksProxyAgent } from 'socks-proxy-agent';

// SOCKS5 proxy
const agent = new SocksProxyAgent('socks5://proxy.example.com:1080');

const sdk = new ShopeeSDK({
  partner_id: 123456,
  partner_key: 'your-key',
  agent,
});

Authenticated Proxy

For proxies requiring authentication:

import { HttpsProxyAgent } from 'https-proxy-agent';

// Include username and password in URL
const agent = new HttpsProxyAgent(
  'http://username:password@proxy.example.com:8080'
);

const sdk = new ShopeeSDK({
  partner_id: 123456,
  partner_key: 'your-key',
  agent,
});

Proxy Configuration Examples

Corporate Proxy

import { HttpsProxyAgent } from 'https-proxy-agent';

// Corporate proxy with authentication
const proxyUrl = process.env.CORPORATE_PROXY || 'http://proxy.corp.com:8080';
const agent = new HttpsProxyAgent(proxyUrl);

const sdk = new ShopeeSDK({
  partner_id: 123456,
  partner_key: 'your-key',
  agent,
});

Rotating Proxy Service

import { HttpsProxyAgent } from 'https-proxy-agent';

class RotatingProxySDK {
  private sdk: ShopeeSDK;
  private proxyList: string[];
  private currentIndex: number = 0;

  constructor(config: ShopeeConfig, proxies: string[]) {
    this.proxyList = proxies;
    this.sdk = new ShopeeSDK(config);
    this.rotateProxy();
  }

  private rotateProxy(): void {
    const proxyUrl = this.proxyList[this.currentIndex];
    const agent = new HttpsProxyAgent(proxyUrl);
    this.sdk.setFetchAgent(agent);
    
    this.currentIndex = (this.currentIndex + 1) % this.proxyList.length;
  }

  async makeRequest<T>(apiCall: () => Promise<T>): Promise<T> {
    try {
      return await apiCall();
    } catch (error) {
      // Rotate proxy and retry on failure
      this.rotateProxy();
      return await apiCall();
    }
  }
}

// Usage
const proxies = [
  'http://proxy1.example.com:8080',
  'http://proxy2.example.com:8080',
  'http://proxy3.example.com:8080',
];

const rotatingSDK = new RotatingProxySDK(config, proxies);

const products = await rotatingSDK.makeRequest(() =>
  sdk.product.getItemList({ offset: 0, page_size: 20 })
);

Environment-Based Proxy

import { HttpsProxyAgent } from 'https-proxy-agent';

function createSDK(config: ShopeeConfig): ShopeeSDK {
  const proxyUrl = process.env.HTTPS_PROXY || process.env.HTTP_PROXY;
  
  if (proxyUrl) {
    console.log(`Using proxy: ${proxyUrl}`);
    const agent = new HttpsProxyAgent(proxyUrl);
    return new ShopeeSDK({ ...config, agent });
  }
  
  console.log('No proxy configured, using direct connection');
  return new ShopeeSDK(config);
}

// Automatically uses proxy if environment variables are set
const sdk = createSDK({
  partner_id: 123456,
  partner_key: 'your-key',
});

Proxy with Custom Options

import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://proxy.example.com:8080', {
  // Custom timeout
  timeout: 30000,
  
  // TLS options
  rejectUnauthorized: false, // Accept self-signed certificates
  
  // Keep alive
  keepAlive: true,
  keepAliveMsecs: 1000,
});

const sdk = new ShopeeSDK({
  partner_id: 123456,
  partner_key: 'your-key',
  agent,
});

Debugging with Proxy Tools

Charles Proxy

Configure the SDK to route through Charles for debugging:

import { HttpsProxyAgent } from 'https-proxy-agent';

// Charles typically runs on localhost:8888
const agent = new HttpsProxyAgent('http://localhost:8888', {
  rejectUnauthorized: false, // Required for Charles SSL proxying
});

const sdk = new ShopeeSDK({
  partner_id: 123456,
  partner_key: 'your-key',
  agent,
});

// All requests will now be visible in Charles
await sdk.product.getItemList({ offset: 0, page_size: 20 });

Fiddler

import { HttpsProxyAgent } from 'https-proxy-agent';

// Fiddler typically runs on localhost:8888
const agent = new HttpsProxyAgent('http://localhost:8888', {
  rejectUnauthorized: false,
});

const sdk = new ShopeeSDK({
  partner_id: 123456,
  partner_key: 'your-key',
  agent,
});

mitmproxy

import { HttpsProxyAgent } from 'https-proxy-agent';

// mitmproxy default port is 8080
const agent = new HttpsProxyAgent('http://localhost:8080', {
  rejectUnauthorized: false,
});

const sdk = new ShopeeSDK({
  partner_id: 123456,
  partner_key: 'your-key',
  agent,
});

Testing Proxy Configuration

Verify Proxy Connection

import { HttpsProxyAgent } from 'https-proxy-agent';

async function testProxy(proxyUrl: string): Promise<boolean> {
  try {
    const agent = new HttpsProxyAgent(proxyUrl);
    const sdk = new ShopeeSDK({
      partner_id: 123456,
      partner_key: 'your-key',
      agent,
    });
    
    // Try a simple API call
    await sdk.public.getShopeeIpRange();
    console.log('✅ Proxy connection successful');
    return true;
  } catch (error) {
    console.error('❌ Proxy connection failed:', error.message);
    return false;
  }
}

// Test your proxy
await testProxy('http://proxy.example.com:8080');

Proxy Failover

import { HttpsProxyAgent } from 'https-proxy-agent';

class ProxyFailoverSDK {
  private sdk: ShopeeSDK;
  private proxies: string[];

  constructor(config: ShopeeConfig, proxies: string[]) {
    this.sdk = new ShopeeSDK(config);
    this.proxies = proxies;
  }

  async makeRequestWithFailover<T>(
    apiCall: (sdk: ShopeeSDK) => Promise<T>
  ): Promise<T> {
    // Try each proxy in order
    for (const proxyUrl of this.proxies) {
      try {
        const agent = new HttpsProxyAgent(proxyUrl);
        this.sdk.setFetchAgent(agent);
        
        return await apiCall(this.sdk);
      } catch (error) {
        console.warn(`Proxy ${proxyUrl} failed, trying next...`);
      }
    }
    
    // Try direct connection as last resort
    try {
      this.sdk.setFetchAgent(undefined);
      console.log('All proxies failed, trying direct connection...');
      return await apiCall(this.sdk);
    } catch (error) {
      throw new Error('All connection attempts failed');
    }
  }
}

// Usage
const failoverSDK = new ProxyFailoverSDK(config, [
  'http://proxy1.example.com:8080',
  'http://proxy2.example.com:8080',
]);

const products = await failoverSDK.makeRequestWithFailover((sdk) =>
  sdk.product.getItemList({ offset: 0, page_size: 20 })
);

Best Practices

1. Secure Proxy Credentials

Never hardcode proxy credentials:

// ✅ Good: Use environment variables
const proxyUrl = process.env.PROXY_URL;
const agent = new HttpsProxyAgent(proxyUrl);

// ❌ Bad: Hardcoded credentials
const agent = new HttpsProxyAgent('http://user:pass@proxy.com:8080');

2. Handle Proxy Errors Gracefully

async function makeProxiedRequest<T>(
  apiCall: () => Promise<T>
): Promise<T> {
  try {
    return await apiCall();
  } catch (error) {
    if (error.code === 'ECONNREFUSED') {
      console.error('Proxy connection refused');
    } else if (error.code === 'ENOTFOUND') {
      console.error('Proxy host not found');
    } else if (error.statusCode === 407) {
      console.error('Proxy authentication required');
    }
    throw error;
  }
}

3. Configure Timeouts

import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://proxy.example.com:8080', {
  timeout: 30000, // 30 second timeout
});

4. Use Connection Pooling

import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://proxy.example.com:8080', {
  keepAlive: true,
  keepAliveMsecs: 1000,
  maxSockets: 100, // Connection pool size
});

5. Log Proxy Usage

import { HttpsProxyAgent } from 'https-proxy-agent';

function createProxiedSDK(config: ShopeeConfig, proxyUrl: string): ShopeeSDK {
  console.log(`[PROXY] Routing requests through: ${proxyUrl}`);
  
  const agent = new HttpsProxyAgent(proxyUrl);
  return new ShopeeSDK({ ...config, agent });
}

Common Issues

Issue: Proxy Authentication Failed

Error: 407 Proxy Authentication Required

Solution:

// Include credentials in proxy URL
const agent = new HttpsProxyAgent(
  'http://username:password@proxy.example.com:8080'
);

Issue: SSL Certificate Verification Failed

Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE

Solution:

const agent = new HttpsProxyAgent('http://proxy.example.com:8080', {
  rejectUnauthorized: false, // Only use for debugging!
});

Issue: Connection Timeout

Error: ETIMEDOUT

Solution:

const agent = new HttpsProxyAgent('http://proxy.example.com:8080', {
  timeout: 60000, // Increase timeout to 60 seconds
});

Issue: Proxy Not Being Used

Solution: Verify agent is set correctly:

const config = sdk.getConfig();
console.log('Agent configured:', !!config.agent);

Next Steps