@rynn-k/proxy-agent/index.d.ts

Efficient proxy rotation agent for Node.js with seamless axios integration

import { HttpsProxyAgent } from 'https-proxy-agent';
import { HttpProxyAgent } from 'http-proxy-agent';
import { SocksProxyAgent } from 'socks-proxy-agent';

declare namespace ProxyAgent {
  interface ProxyInfo {
    index: number;
    ip: string;
    port: number;
    hasAuth: boolean;
    protocol: 'http' | 'https' | 'socks4' | 'socks5';
    current?: boolean;
  }

  interface CurrentProxyInfo {
    ip: string;
    port: number;
    hasAuth: boolean;
    protocol: 'http' | 'https' | 'socks4' | 'socks5';
    index: number;
  }

  interface ProxyStats {
    total: number;
    auth: number;
    noAuth: number;
    protocols: Record<string, number>;
    currentIndex: number;
    lastUsedIndex: number;
    random: boolean;
    file: string;
    autoReload: boolean;
    currentProxy: CurrentProxyInfo | null;
  }

  interface TestResult {
    success: boolean;
    proxy: string;
    time?: number;
    data?: any;
    error?: string;
  }

  interface AxiosConfig {
    httpsAgent: HttpsProxyAgent | HttpProxyAgent | SocksProxyAgent;
    httpAgent: HttpsProxyAgent | HttpProxyAgent | SocksProxyAgent;
    proxy: false;
  }

  interface Options {
    /**
     * Use random proxy selection instead of sequential
     * @default false
     */
    random?: boolean;
    
    /**
     * Enable logging
     * @default true
     */
    log?: boolean;
    
    /**
     * File encoding
     * @default 'utf-8'
     */
    encoding?: string;
    
    /**
     * Auto reload proxies when file changes
     * @default false
     */
    autoReload?: boolean;
    
    /**
     * Default proxy type when not specified in proxy string
     * @default 'http'
     */
    type?: 'http' | 'https' | 'socks4' | 'socks5';
  }
}

declare class ProxyAgent {
  /**
   * Create a ProxyAgent instance
   * @param proxyFilePath Path to proxy file (default: 'proxies.txt')
   * @param options Configuration options
   */
  constructor(proxyFilePath?: string, options?: ProxyAgent.Options);
  
  /**
   * Get axios configuration with proxy agents
   * @returns Axios config object with proxy agents
   */
  config(): ProxyAgent.AxiosConfig;
  
  /**
   * Get HTTPS proxy agent
   * @returns HTTPS proxy agent (or SOCKS agent for SOCKS proxies)
   */
  https(): HttpsProxyAgent | SocksProxyAgent;
  
  /**
   * Get HTTP proxy agent
   * @returns HTTP proxy agent (or SOCKS agent for SOCKS proxies)
   */
  http(): HttpProxyAgent | SocksProxyAgent;
  
  /**
   * Get current proxy information
   * @returns Current proxy info or null
   */
  getCurrentProxy(): ProxyAgent.CurrentProxyInfo | null;
  
  /**
   * Get all available proxies
   * @returns Array of proxy info objects
   */
  list(): ProxyAgent.ProxyInfo[];
  
  /**
   * Get proxy statistics
   * @returns Statistics object
   */
  stats(): ProxyAgent.ProxyStats;
  
  /**
   * Reload proxies from file
   */
  reload(): void;
  
  /**
   * Test proxy connectivity
   * @param testUrl URL to test (default: 'https://httpbin.org/ip')
   * @param timeout Request timeout in milliseconds (default: 10000)
   * @param useCurrentProxy Use current proxy or get next (default: true)
   * @returns Test results
   */
  test(testUrl?: string, timeout?: number, useCurrentProxy?: boolean): Promise<ProxyAgent.TestResult>;
  
  /**
   * Cleanup resources
   */
  destroy(): void;
}

export = ProxyAgent;