stock-bot/libs/http

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

bun add @stock-bot/http

Basic Usage

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

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

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

SOCKS Proxy

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

Rate Limiting

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

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

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

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

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

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:

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

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

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