Skip to content
BranchesTags

Repository files navigation

ApiService

A robust TypeScript API service framework for making authenticated API calls with advanced features:

  • ✅ Multiple authentication strategies (token, API key, basic auth, custom)
  • ✅ Request caching with configurable time periods
  • ✅ In-flight deduplication for concurrent GET and HEAD requests
  • ✅ Advanced retry mechanisms with exponential backoff
  • ✅ Status code-specific hooks for handling errors
  • ✅ Account state tracking
  • ✅ File upload support
  • ✅ Support for multiple accounts or a single default account
  • ✅ Automatic token refresh for 401 errors (if supported by provider)
  • ✅ Reusable multi-provider account runtime with app-owned UI event handling

Installation

npm install @rendomnet/apiservice

Testing

ApiService includes a comprehensive test suite using Jest. To run the tests:

# Run tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode during development
npm run test:watch

Usage

import ApiService from 'apiservice';
import { TokenAuthProvider, ApiKeyAuthProvider, BasicAuthProvider } from 'apiservice';

// Token-based (OAuth2, etc.)
const tokenProvider = new TokenAuthProvider(myTokenService);

// API key in header
const apiKeyHeaderProvider = new ApiKeyAuthProvider({ apiKey: 'my-key', headerName: 'x-api-key' });

// API key in query param
const apiKeyQueryProvider = new ApiKeyAuthProvider({ apiKey: 'my-key', queryParamName: 'api_key' });

// Basic Auth
const basicProvider = new BasicAuthProvider({ username: 'user', password: 'pass' });

// Create and setup the API service
const api = new ApiService();
api.setup({
  provider: 'my-service',
  authProvider: tokenProvider, // or apiKeyHeaderProvider, apiKeyQueryProvider, basicProvider
  hooks: {
    // You can define custom hooks here,
    // or use the default token refresh handler for 401 errors (if supported)
  },
  cacheTime: 30000, // 30 seconds
  baseUrl: 'https://api.example.com', // Set default base URL
  logger: process.env.NODE_ENV === 'development' ? console : undefined
});

// Make API calls with specific account ID and use default baseUrl
const result = await api.call({
  accountId: 'user123',
  method: 'GET',
  route: '/users',
  useAuth: true
});

// Override default baseUrl for specific calls
const customResult = await api.call({
  method: 'GET',
  base: 'https://api2.example.com', // Override default baseUrl
  route: '/users',
  useAuth: true
});

// Or omit accountId to use the default account ('default')
const defaultResult = await api.call({
  method: 'GET',
  route: '/users',
  useAuth: true
});

Reusable provider accounts

Apps that share a connected-account model can create one provider-neutral runtime and inject it into dedicated clients:

import {
  GoogleApi,
  MicrosoftApi,
  ProviderApiRuntime,
} from '@rendomnet/apiservice';

const shared = new ProviderApiRuntime({
  account: {
    get: ({ accountId }) => accountStore.get(accountId),
    update: ({ accountId }, patch) => accountStore.update(accountId, patch),
    refresh: ({ provider, accountId }, account) =>
      oauthBackend.refresh(provider, accountId, account.refresh_token),
  },
  httpClient,
  openLink: ({ url }) => openUrl(url),
  onEvent: (event) => {
    // Stable code + ProviderApiError. The app decides whether to show UI.
    if (event.code === 'REAUTHORIZATION_REQUIRED') {
      showReconnectToast(event.provider);
    }
  },
});

const googleApi = new GoogleApi({ shared, cacheTime: 0 });
const microsoftApi = new MicrosoftApi({ shared, cacheTime: 0 });

await googleApi.call({
  accountId: 'google-account-id',
  base: 'https://www.googleapis.com/calendar/v3/',
  route: 'users/me/calendarList',
  method: 'GET',
});

The clients are intentionally domain-neutral: callers supply the base URL and route for tasks, calendars, mail, or any other provider API. The runtime owns account lookup, refresh coordination, persistence, and normalized terminal events; the app owns storage, OAuth refresh calls, links, navigation, and visual notifications.

SharedApiService is available as an alias of ProviderApiRuntime.

See Provider Account System for invariants, event codes, migration guidance, and instructions for adding providers.

In-flight request deduplication

Concurrent GET and HEAD calls with the same request key share one network request by default. Streaming requests, requests with an AbortSignal, and mutations are never deduplicated automatically.

const [first, second] = await Promise.all([
  api.call({ method: 'GET', route: '/users/me' }),
  api.call({ method: 'GET', route: '/users/me' }),
]);

// Opt out for a specific idempotent request.
await api.call({ method: 'GET', route: '/users/me', dedupe: false });

Transport logging is disabled by default. Pass a logger with optional debug, warn, and error methods to setup() when diagnostics are needed. Response bodies are only passed to the configured debug logger.

Authentication Providers

ApiService supports multiple authentication strategies via the AuthProvider interface. You can use built-in providers or implement your own.

TokenAuthProvider (OAuth2, Bearer Token)

import { TokenAuthProvider } from 'apiservice';

const tokenService = {
  async get(accountId = 'default') {
    // Get token from storage
    return storedToken;
  },
  async set(token, accountId = 'default') {
    // Save token to storage
  },
  async refresh(refreshToken, accountId = 'default') {
    // Refresh the token with your OAuth provider
    // ...
    return newToken;
  }
};

const tokenProvider = new TokenAuthProvider(tokenService);

ApiKeyAuthProvider (Header or Query Param)

import { ApiKeyAuthProvider } from 'apiservice';

// API key in header
const apiKeyHeaderProvider = new ApiKeyAuthProvider({ apiKey: 'my-key', headerName: 'x-api-key' });

// API key in query param
const apiKeyQueryProvider = new ApiKeyAuthProvider({ apiKey: 'my-key', queryParamName: 'api_key' });

BasicAuthProvider

import { BasicAuthProvider } from 'apiservice';

const basicProvider = new BasicAuthProvider({ username: 'user', password: 'pass' });

Custom AuthProvider

You can implement your own provider by implementing the AuthProvider interface:

interface AuthProvider {
  getAuthHeaders(accountId?: string): Promise<Record<string, string>>;
  getAuthCacheKey?(accountId?: string): Promise<string | undefined>;
  refreshAuth?(accountId?: string, context?: AuthRefreshContext): Promise<void>;
  /** @deprecated Implement refreshAuth() instead. */
  refresh?(refreshToken: string, accountId?: string): Promise<any>;
}

Automatic Token Refresh

If your provider supports token refresh (like TokenAuthProvider), ApiService includes a built-in handler for 401 (Unauthorized) errors that automatically refreshes tokens. This feature:

  1. Detects 401 errors from the API
  2. Calls the provider's refreshAuth method once for concurrent failures
  3. Retries the original API request with the new token

To use this feature:

  • Use a provider that implements refreshAuth (like TokenAuthProvider)
  • Don't specify a custom 401 hook (the default will be used automatically)

refreshAuth must resolve only after getAuthHeaders can return the refreshed credentials. Custom providers serving multiple signed-in principals should also implement getAuthCacheKey so cached and in-flight responses cannot cross user sessions. The legacy refresh(refreshToken, accountId) contract remains available as a migration fallback.

If you prefer to handle token refresh yourself, you can either:

  1. Provide your own handler for 401 errors which will override the default
  2. Disable the default handler by setting hooks: { 401: null }
api.setup({
  provider: 'my-service',
  authProvider: tokenProvider,
  hooks: {
    401: null // Explicitly disable the default handler
  },
  cacheTime: 30000
});

Account Management

ApiService supports multiple accounts through the accountId parameter. This allows you to:

  1. Manage multiple tokens - Maintain separate authentication tokens for different users or services
  2. Track state by account - Each account has its own state tracking (request times, failures)
  3. Apply account-specific retry logic - Hooks can behave differently based on the account

For simple applications that only need a single account, you can omit the accountId parameter:

// Make calls without specifying accountId - uses 'default' automatically
const result = await api.call({
  method: 'GET',
  route: '/users'
});

If no accountId is provided, ApiService automatically uses 'default' as the account ID.

Request Cancellation

ApiService supports request cancellation using the standard AbortController API. This allows you to cancel ongoing API requests, including those that are being retried.

// Create an AbortController
const controller = new AbortController();

// Make an API call with the controller's signal
const apiPromise = api.call({
  method: 'GET',
  route: '/users',
  abortSignal: controller.signal
});

// Cancel the request at any time
controller.abort();

try {
  await apiPromise;
} catch (error) {
  if (error.name === 'AbortError' || error.message === 'Request aborted') {
    console.log('Request was successfully aborted');
  } else {
    console.error('An error occurred:', error);
  }
}

The abort functionality works with all features of ApiService:

  • Cancels ongoing requests immediately
  • Prevents retry attempts from starting
  • Works with cached and non-cached requests
  • Compatible with all authentication providers

AuthProvider Interface

interface AuthProvider {
  getAuthHeaders(accountId?: string): Promise<Record<string, string>>;
  getAuthCacheKey?(accountId?: string): Promise<string | undefined>;
  refreshAuth?(accountId?: string, context?: AuthRefreshContext): Promise<void>;
  /** @deprecated Implement refreshAuth() instead. */
  refresh?(refreshToken: string, accountId?: string): Promise<any>;
}

Example: Complete Authorization Flow (TokenAuthProvider)

import ApiService from 'apiservice';
import { TokenAuthProvider } from 'apiservice';

const tokenService = {
  async get(accountId = 'default') {
    // ...
  },
  async set(token, accountId = 'default') {
    // ...
  },
  async refresh(refreshToken, accountId = 'default') {
    // ...
  }
};

const api = new ApiService();
api.setup({
  provider: 'example-api',
  authProvider: new TokenAuthProvider(tokenService),
  cacheTime: 30000,
  baseUrl: 'https://api.example.com',
  hooks: {
    403: {
      shouldRetry: false,
      handler: async (accountId, response) => {
        // ...
        return null;
      }
    }
  }
});

// Use the API service
async function fetchUserData(userId) {
  return await api.call({
    method: 'GET',
    route: `/users/${userId}`,
    useAuth: true
  });
}

Hook Options

Hooks can be configured to handle specific HTTP status codes:

const hooks = {
  401: {
    shouldRetry: true,
    useRetryDelay: true,
    maxRetries: 3,
    preventConcurrentCalls: true,
    handler: async (accountId, response) => {
      // ...
      return { /* updated parameters */ };
    },
    onMaxRetriesExceeded: async (accountId, error) => {
      // ...
    },
    onHandlerError: async (accountId, error) => {
      // ...
    },
    delayStrategy: {
      calculate: (attempt, response) => 1000 * Math.pow(2, attempt - 1)
    },
    maxDelay: 30000
  }
}

Architecture

The codebase is built around a main ApiService class that coordinates several component managers:

  • HttpClient: Handles the actual HTTP request creation and execution
  • CacheManager: Implements data caching with customizable expiration times
  • RetryManager: Manages retry logic with exponential backoff and other delay strategies
  • HookManager: Provides a way to hook into specific status codes and handle them
  • AccountManager: Tracks account state and handles account-specific data

Advanced Usage

Multiple API Providers

import { ApiService, TokenAuthProvider, ApiKeyAuthProvider } from 'apiservice';

const primaryProvider = new TokenAuthProvider(primaryTokenService);
const secondaryProvider = new ApiKeyAuthProvider({ apiKey: 'secondary-key', headerName: 'x-api-key' });

const api = new ApiService();
api.setup({
  provider: 'primary-api',
  authProvider: primaryProvider,
  cacheTime: 30000,
  baseUrl: 'https://api.primary.com'
});

api.setup({
  provider: 'secondary-api',
  authProvider: secondaryProvider,
  cacheTime: 60000,
  baseUrl: 'https://api.secondary.com'
});

// Use different providers in API calls
async function fetchCombinedData() {
  const [primaryData, secondaryData] = await Promise.all([
    api.call({
      provider: 'primary-api',
      method: 'GET',
      route: '/data',
      useAuth: true
    }),
    api.call({
      provider: 'secondary-api',
      method: 'GET',
      route: '/data',
      useAuth: true
    }),
    api.call({
      provider: 'primary-api',
      method: 'GET',
      route: '/special-data',
      useAuth: true,
      base: 'https://special-api.primary.com'
    })
  ]);
  return { primaryData, secondaryData };
}

About

API service

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages