universal-api-handler

A lightweight TypeScript-based HTTP API handler with built-in retry logic, request/response interceptors, and file download support.

Features

• 🔄 Automatic Retry: Retry failed requests with configurable delays
• 🔗 Request/Response Interceptors: Intercept and modify requests and responses
• 📥 File Downloads: Download files with progress tracking
• 🔒 TypeScript Support: Fully typed for better IDE support
• 🪶 Lightweight: Minimal dependencies, uses native Fetch API
• 🛡️ Error Handling: Built-in error handling and status code detection

Installation

npm install universal-api-handler

Usage

Basic Setup

import ApiHandler from 'universal-api-handler';

const api = ApiHandler({
  baseUrl: 'https://api.example.com',
  headers: {
    'Authorization': 'Bearer token'
  }
});

GET Request

const response = await api.get('/users', {
  params: {
    page: '1',
    limit: '10'
  }
});
console.log(response.data);

POST Request

const response = await api.post('/users', {
  payload: {
    name: 'John Doe',
    email: '[email protected]'
  }
});

PUT Request

const response = await api.put('/users/1', {
  payload: {
    name: 'Jane Doe'
  }
});

Retry Configuration

const api = ApiHandler({
  baseUrl: 'https://api.example.com',
  errorRetry: {
    retryTimes: 3,
    retryDelay: 1000,
    onRetry: (info) => {
      console.log(`Retrying ${info.method} ${info.api}`);
    }
  }
});

Request/Response Interceptors

const api = ApiHandler({
  baseUrl: 'https://api.example.com'
});

// Modify requests before sending
api.config.request((options) => {
  options.headers = {
    ...options.headers,
    'X-Custom-Header': 'value'
  };
  return options;
});

// Modify responses
api.config.response((response) => {
  console.log('Response received:', response);
  return response;
});

File Downloads

await api.download('/files/document.pdf', {
  fileName: 'document.pdf',
  onDownloadProgress: (percentage) => {
    console.log(`Downloaded: ${percentage}%`);
  }
});

API Reference

ApiHandler(options)

Creates and returns an API handler instance.

Options:

• baseUrl (string): The base URL for all requests
• headers (HeadersInit, optional): Default headers to include in all requests
• config (RequestInit, optional): Default fetch configuration
• errorRetry (ErrorRetryConfig, optional): Retry configuration

Methods

• get(endpoint, options): Send a GET request
• post(endpoint, options): Send a POST request
• put(endpoint, options): Send a PUT request
• download(endpoint, options): Download a file

Options:

• params (Record<string, string>): Query parameters
• payload (any): Request body (for POST/PUT)
• headers (HeadersInit): Additional headers for this request
• retryTimes (number): Override retry times for this request
• retryDelay (number): Override retry delay for this request
• onRetry (function): Callback when a retry occurs
• fileName (string): File name for downloads
• onDownloadProgress (function): Callback for download progress

License

MIT