npm package: @nexon.js/proxy-agent
Description: Efficient proxy rotation agent for Node.js with seamless axios integration
Author: Kens Ransyah
Latest version: 0.1.4

# @nexon.js/proxy-agent

Efficient proxy rotation agent for Node.js with seamless axios integration. Supports both authenticated and non-authenticated proxies with automatic rotation, health checking, and comprehensive error handling.

## 🚀 Features

- ✅ **Smart Proxy Rotation** - Sequential or random proxy selection
- ✅ **Multiple Auth Types** - Support for authenticated and non-authenticated proxies  
- ✅ **Axios Integration** - Drop-in replacement for axios HTTP/HTTPS agents
- ✅ **Auto Validation** - Built-in IP and port validation
- ✅ **Health Checking** - Test proxy connectivity and response times
- ✅ **Auto Reload** - Dynamic proxy file reloading
- ✅ **Multiple Formats** - Flexible proxy file format support
- ✅ **TypeScript Ready** - Full TypeScript definitions included
- ✅ **Zero Dependencies** - Only requires https-proxy-agent and http-proxy-agent

## 📦 Installation

```bash
npm install @nexon.js/proxy-agent
```

## 🔧 Quick Start

### 1. Create Proxy File

Create `proxies.txt` with your proxy list:

```txt
# Basic proxies (ip:port)
192.168.1.1:8080
10.0.0.1:3128

# Authenticated proxies (ip:port:username:password)  
192.168.1.2:8080:user123:pass456
proxy.example.com:3128:myuser:mypass

# Protocol-specific (protocol:ip:port)
http:192.168.1.3:8080
https:secure-proxy.com:8080

# Authenticated with protocol (protocol:ip:port:username:password)
http:192.168.1.4:8080:user:pass
```

### 2. Basic Usage

```javascript
const ProxyAgent = require('@nexon.js/proxy-agent');
const axios = require('axios');

// Initialize proxy agent
const proxy = new ProxyAgent('./proxies.txt');

// Use with axios
const response = await axios.get('https://httpbin.org/ip', proxy.config());
console.log('Your IP:', response.data.origin);
```

### 3. Advanced Configuration

```javascript
const proxy = new ProxyAgent('./proxies.txt', {
  random: true,        // Random proxy selection (default: false)
  log: true,          // Enable logging (default: true)  
  autoReload: true,   // Auto-reload on file change (default: false)
  encoding: 'utf-8'   // File encoding (default: 'utf-8')
});
```

## 📖 API Documentation

### Constructor

```javascript
new ProxyAgent(proxyFilePath, options)
```

**Parameters:**
- `proxyFilePath` (string): Path to proxy file (default: 'proxies.txt')
- `options` (object): Configuration options

**Options:**
- `random` (boolean): Use random proxy selection instead of sequential
- `log` (boolean): Enable/disable logging  
- `autoReload` (boolean): Auto-reload proxy file on changes
- `encoding` (string): File encoding for reading proxy file

### Methods

#### `config()`
Returns axios configuration object with proxy agents configured.

```javascript
const response = await axios.get('https://example.com', proxy.config());
```

#### `https()`
Returns HTTPS proxy agent for manual configuration.

```javascript
const httpsAgent = proxy.https();
const response = await axios.get('https://example.com', { httpsAgent });
```

#### `http()`
Returns HTTP proxy agent for manual configuration.

```javascript
const httpAgent = proxy.http();
```

#### `test(testUrl, timeout)`
Test proxy connectivity and measure response time.

```javascript
const result = await proxy.test('https://httpbin.org/ip', 5000);
console.log(result);
// { success: true, proxy: '192.168.1.1:8080', time: 245, data: {...} }
```

#### `list()`
Get information about all loaded proxies.

```javascript
const proxies = proxy.list();
console.log(proxies);
// [{ index: 0, ip: '192.168.1.1', port: 8080, hasAuth: false, protocol: 'http' }]
```

#### `stats()`
Get proxy agent statistics.

```javascript
const stats = proxy.stats();
console.log(stats);
// {
//   total: 10,
//   auth: 5,
//   noAuth: 5,
//   current: 2,
//   random: false,
//   file: '/path/to/proxies.txt',
//   autoReload: false
// }
```

#### `reload()`
Manually reload proxies from file.

```javascript
proxy.reload();
```

#### `destroy()`
Clean up resources and stop file watching.

```javascript
proxy.destroy();
```

## 💡 Usage Examples

### Basic Rotation

```javascript
const ProxyAgent = require('@nexon.js/proxy-agent');
const axios = require('axios');

const proxy = new ProxyAgent('./proxies.txt');

// Each request uses the next proxy in rotation
for (let i = 0; i < 5; i++) {
  try {
    const response = await axios.get('https://httpbin.org/ip', proxy.config());
    console.log(`Request ${i + 1}:`, response.data.origin);
  } catch (error) {
    console.error(`Request ${i + 1} failed:`, error.message);
  }
}
```

### Error Handling & Retry

```javascript
async function robustRequest(url, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await axios.get(url, {
        ...proxy.config(),
        timeout: 10000
      });
      return response.data;
    } catch (error) {
      console.log(`Attempt ${attempt} failed:`, error.message);
      
      if (attempt === maxRetries) {
        throw new Error(`All ${maxRetries} attempts failed`);
      }
      
      // Wait before retry with different proxy
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
  }
}

// Usage
try {
  const data = await robustRequest('https://api.example.com/data');
  console.log(data);
} catch (error) {
  console.error('Request failed after all retries:', error.message);
}
```

### Axios Instance Integration

```javascript
const axiosWithProxy = axios.create({
  timeout: 15000,
  headers: {
    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
  }
});

// Add proxy rotation to every request
axiosWithProxy.interceptors.request.use(config => {
  const proxyConfig = proxy.config();
  config.httpsAgent = proxyConfig.httpsAgent;
  config.httpAgent = proxyConfig.httpAgent;
  config.proxy = false;
  return config;
});

// Now all requests automatically use rotating proxies
const response = await axiosWithProxy.get('https://api.example.com/data');
```

### Health Checking

```javascript
// Test all proxies and filter working ones
const proxy = new ProxyAgent('./proxies.txt');
const workingProxies = [];

for (const proxy of proxy.list()) {
  const result = await proxy.test();
  if (result.success) {
    workingProxies.push({
      ...proxy,
      responseTime: result.time
    });
    console.log(`✅ ${proxy.ip}:${proxy.port} - ${result.time}ms`);
  } else {
    console.log(`❌ ${proxy.ip}:${proxy.port} - ${result.error}`);
  }
}

console.log(`Found ${workingProxies.length} working proxies`);
```

## 🔧 Proxy File Formats

The library supports multiple proxy formats:

```txt
# Basic format (ip:port)
192.168.1.1:8080
proxy.example.com:3128

# With authentication (ip:port:username:password)
192.168.1.2:8080:user123:password123
proxy.example.com:3128