stock-bot/libs/http/README.md

# HTTP Client Library

A comprehensive HTTP client library for the Stock Bot platform with built-in support for:

- ✅ **Fetch API** - Modern, promise-based HTTP requests
- ✅ **Proxy Support** - HTTP, HTTPS, SOCKS4, and SOCKS5 proxies
- ✅ **Rate Limiting** - Configurable request rate limiting
- ✅ **Timeout Handling** - Request timeouts with abort controllers
- ✅ **Retry Logic** - Automatic retries with exponential backoff
- ✅ **TypeScript** - Full TypeScript support with type safety
- ✅ **Logging Integration** - Optional logger integration

## Installation

```bash
bun add @stock-bot/http
```

## Basic Usage

```typescript
import { HttpClient } from '@stock-bot/http';

// Create a client with default configuration
const client = new HttpClient();

// Make a GET request
const response = await client.get('https://api.example.com/data');
console.log(response.data);

// Make a POST request
const postResponse = await client.post('https://api.example.com/users', {
  name: 'John Doe',
  email: 'john@example.com'
});
```

## Advanced Configuration

```typescript
import { HttpClient } from '@stock-bot/http';
import { logger } from '@stock-bot/logger';

const client = new HttpClient({
  baseURL: 'https://api.example.com',
  timeout: 10000, // 10 seconds
  retries: 3,
  retryDelay: 1000, // 1 second base delay
  defaultHeaders: {
    'Authorization': 'Bearer token',
    'User-Agent': 'Stock-Bot/1.0'
  },
  validateStatus: (status) => status < 400
}, logger);
```

## Proxy Support

### HTTP/HTTPS Proxy

```typescript
const client = new HttpClient({
  proxy: {
    type: 'http',
    host: 'proxy.example.com',
    port: 8080,
    username: 'user', // optional
    password: 'pass'  // optional
  }
});
```

### SOCKS Proxy

```typescript
const client = new HttpClient({
  proxy: {
    type: 'socks5',
    host: 'socks-proxy.example.com',
    port: 1080,
    username: 'user', // optional
    password: 'pass'  // optional
  }
});
```

## Rate Limiting

```typescript
const client = new HttpClient({
  rateLimit: {
    maxRequests: 100,           // Max 100 requests
    windowMs: 60 * 1000,        // Per 1 minute
    skipSuccessfulRequests: false,
    skipFailedRequests: true    // Don't count failed requests
  }
});

// Check rate limit status
const status = client.getRateLimitStatus();
console.log(`${status.currentCount}/${status.maxRequests} requests used`);
```

## Request Methods

```typescript
// GET request
const getData = await client.get('/api/data');

// POST request with body
const postData = await client.post('/api/users', {
  name: 'John',
  email: 'john@example.com'
});

// PUT request
const putData = await client.put('/api/users/1', updatedUser);

// DELETE request
const deleteData = await client.delete('/api/users/1');

// PATCH request
const patchData = await client.patch('/api/users/1', { name: 'Jane' });

// Custom request
const customResponse = await client.request({
  method: 'POST',
  url: '/api/custom',
  headers: { 'X-Custom': 'value' },
  body: { data: 'custom' },
  timeout: 5000
});
```

## Error Handling

```typescript
import { HttpError, TimeoutError, RateLimitError } from '@stock-bot/http';

try {
  const response = await client.get('/api/data');
} catch (error) {
  if (error instanceof TimeoutError) {
    console.log('Request timed out');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited: retry after ${error.retryAfter}ms`);
  } else if (error instanceof HttpError) {
    console.log(`HTTP error ${error.status}: ${error.message}`);
  }
}
```

## Retry Configuration

```typescript
const client = new HttpClient({
  retries: 3,           // Retry up to 3 times
  retryDelay: 1000,     // Base delay of 1 second
  // Exponential backoff: 1s, 2s, 4s
});

// Or per-request retry configuration
const response = await client.get('/api/data', {
  retries: 5,
  retryDelay: 500
});
```

## Timeout Handling

```typescript
// Global timeout
const client = new HttpClient({
  timeout: 30000 // 30 seconds
});

// Per-request timeout
const response = await client.get('/api/data', {
  timeout: 5000 // 5 seconds for this request
});
```

## Custom Status Validation

```typescript
const client = new HttpClient({
  validateStatus: (status) => {
    // Accept 2xx and 3xx status codes
    return status >= 200 && status < 400;
  }
});

// Or per-request validation
const response = await client.get('/api/data', {
  validateStatus: (status) => status === 200 || status === 404
});
```

## TypeScript Support

The library is fully typed with TypeScript:

```typescript
interface User {
  id: number;
  name: string;
  email: string;
}

// Response data is properly typed
const response = await client.get<User[]>('/api/users');
const users: User[] = response.data;

// Request configuration is validated
const config: RequestConfig = {
  method: 'POST',
  url: '/api/users',
  body: { name: 'John' },
  timeout: 5000
};
```

## Integration with Logger

```typescript
import { logger } from '@stock-bot/logger';
import { HttpClient } from '@stock-bot/http';

const client = new HttpClient({
  baseURL: 'https://api.example.com'
}, logger);

// All requests will be logged with debug/warn/error levels
```

## Testing

```bash
# Run tests
bun test

# Run with coverage
bun test --coverage

# Watch mode
bun test --watch
```

## Features

### Proxy Support
- HTTP and HTTPS proxies
- SOCKS4 and SOCKS5 proxies
- Authentication support
- Automatic agent creation

### Rate Limiting
- Token bucket algorithm
- Configurable window and request limits
- Skip successful/failed requests options
- Real-time status monitoring

### Retry Logic
- Exponential backoff
- Configurable retry attempts
- Smart retry conditions (5xx errors only)
- Per-request retry override

### Error Handling
- Typed error classes
- Detailed error information
- Request/response context
- Timeout detection

### Performance
- Built on modern Fetch API
- Minimal dependencies
- Tree-shakeable exports
- TypeScript optimization

## License

MIT License - see LICENSE file for details.