@microfox/rest-sdk

v1.3.0

Published

6 months ago

A powerful, type-safe HTTP client for TypeScript applications with support for multiple response types, retry mechanisms, and extensive configuration options.

0High
0Medium
0Low

subhakar-tikkireddy

vishwaj33t

microfox

Microfox REST SDK

A powerful, type-safe HTTP client for TypeScript applications with support for multiple response types, retry mechanisms, and extensive configuration options.

Features

🚀 Full TypeScript support with type inference
🔄 Configurable retry mechanism
📝 Multiple content type support (JSON, FormData, URL-encoded, etc.)
🎯 Chainable response methods
⚡ Automatic timeout handling
🛡️ Comprehensive error handling
🔍 Request/Response interceptors
📦 Zero dependencies (except for Zod)

Installation

npm install @microfox/rest-sdk
# or
yarn add @microfox/rest-sdk

Quick Start

import { createRestSDK } from '@microfox/rest-sdk';

// Create SDK instance
const api = createRestSDK({
  baseUrl: 'https://api.example.com',
});

// Make requests
const data = await api.get('/users').json();

Basic Usage

Making Requests

// GET request
const users = await api.get('/users').json();

// POST request with JSON body
const newUser = await api
  .post('/users', {
    name: 'John Doe',
    email: '[email protected]',
  })
  .json();

// PUT request
const updated = await api
  .put('/users/1', {
    name: 'Jane Doe',
  })
  .json();

// DELETE request
await api.delete('/users/1').json();

Response Types

// JSON response
const jsonData = await api.get('/data').json();

// Text response
const textData = await api.get('/text').text();

// Binary data
const binaryData = await api.get('/file').blob();

// Form data
const formData = await api.get('/form').formData();

// Access headers
const headers = await api.get('/data').headers();

// Get raw response
const response = await api.get('/data').raw();

Request Options

const response = await api
  .get('/users', {
    // Query parameters
    query: {
      page: 1,
      limit: 10,
      filter: ['active', 'verified'],
    },

    // Custom headers
    headers: {
      'X-Custom-Header': 'value',
    },

    // Content type
    contentType: 'application/json',

    // Retry configuration
    retry: {
      attempts: 3,
      delay: 1000,
      backoff: 2,
    },

    // Request configuration
    cache: 'no-cache',
    credentials: 'include',
    mode: 'cors',
  })
  .json();

Different Content Types

// Form Data
const formData = new FormData();
formData.append('file', fileBlob);
formData.append('name', 'test.txt');

const uploadResult = await api
  .post('/upload', formData, {
    contentType: 'multipart/form-data',
  })
  .json();

// URL-encoded form
const formResult = await api
  .post(
    '/submit',
    {
      key: 'value',
    },
    {
      contentType: 'application/x-www-form-urlencoded',
    },
  )
  .json();

// Binary data
const binaryResult = await api
  .post('/binary', binaryBlob, {
    contentType: 'application/octet-stream',
  })
  .json();

Error Handling

try {
  const data = await api.get('/data').json();
} catch (error) {
  if (APICallError.isInstance(error)) {
    // Handle API errors (4xx, 5xx)
    console.error('API Error:', {
      message: error.message,
      statusCode: error.statusCode,
      url: error.url,
    });
  } else if (MicrofoxSDKError.isInstance(error)) {
    // Handle SDK-specific errors
    console.error('SDK Error:', {
      name: error.name,
      message: error.message,
    });
  } else {
    // Handle other errors
    console.error('Unknown error:', error);
  }
}

TypeScript Support

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

interface CreateUser {
  name: string;
  email: string;
}

// Type-safe requests
const user = await api.get<User>('/users/1').json();
const newUser = await api
  .post<User, CreateUser>('/users', {
    name: 'John',
    email: '[email protected]',
  })
  .json();

Advanced Configuration

Creating Authenticated Clients

const authenticatedApi = createRestSDK({
  baseUrl: 'https://api.example.com',
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: 'application/json',
  },
});

Environment-Specific Configuration

const createApiClient = (environment: 'development' | 'production') => {
  const config = {
    development: {
      baseUrl: 'https://dev-api.example.com',
      timeout: 10000,
    },
    production: {
      baseUrl: 'https://api.example.com',
      timeout: 5000,
    },
  };

  return createRestSDK(config[environment]);
};

Error Types

APICallError

Thrown when the server returns a non-2xx status code.

Properties:

message: Error message
statusCode: HTTP status code
url: Request URL
responseHeaders: Response headers
requestBodyValues: Request body (if any)

MicrofoxSDKError

Thrown for SDK-specific errors (timeout, invalid response type, etc.).