Configuration

The APSO SDK is configured through the ApsoClientConfig object passed to ApsoClientFactory.getClient(). This page covers every available option.

Creating a Client

Use ApsoClientFactory.getClient() to create a client instance. The factory implements the singleton pattern — calling it with the same baseURL and apiKey returns the same instance, preventing duplicate connections:


import { ApsoClientFactory } from '@apso/sdk';
 
const client = ApsoClientFactory.getClient({
  baseURL: 'https://your-service.apso.cloud',
  apiKey: 'your-api-key',
});

The factory key is ${baseURL}-${apiKey}, so different API keys or URLs produce separate client instances.

Clearing Clients

To reset all cached client instances (useful in tests or when rotating API keys):


import { ApsoClientFactory } from '@apso/sdk';
 
ApsoClientFactory.clearClients();

Configuration Reference


interface ApsoClientConfig {
  baseURL: string;                      // Required -- your service API URL
  apiKey: string;                       // Required -- API key for authentication
  client?: 'axios' | 'fetch';          // HTTP transport (default: 'fetch')
  timeout?: number;                     // Request timeout in ms (default: 30000)
  retry?: RetryConfig | boolean;       // Retry configuration (default: disabled)
  headers?: Record<string, string>;    // Custom headers added to every request
  debug?: boolean;                     // Log requests to console (default: false)
}

Option	Type	Default	Description
`baseURL`	`string`	required	The full URL of your APSO service API
`apiKey`	`string`	required	API key sent as the `x-api-key` header
`client`	`'axios' \| 'fetch'`	`'fetch'`	Which HTTP transport to use
`timeout`	`number`	`30000`	Request timeout in milliseconds
`retry`	`RetryConfig \| boolean`	`false`	Retry configuration (see below)
`headers`	`Record<string, string>`	`{}`	Custom headers merged into every request
`debug`	`boolean`	`false`	When `true`, logs every request URL to the console

Authentication

All requests include the x-api-key header automatically. The SDK also sets Content-Type: application/json on every request.


// These headers are sent with every request:
{
  'x-api-key': 'your-api-key',
  'Content-Type': 'application/json',
  // ...plus any custom headers you configure
}

API Key

Your APSO service API key authenticates all requests. You can find this key in the APSO dashboard under your service settings.


const client = ApsoClientFactory.getClient({
  baseURL: process.env.APSO_API_URL!,
  apiKey: process.env.APSO_API_KEY!,
});

Security: Never hard-code your API key in source files. Always load it from environment variables or a secrets manager.

HTTP Transport

The SDK supports two HTTP transport layers.

fetch (Default)

The default transport uses the native fetch API. It works in Node.js 18+, browsers, and edge runtimes with no additional dependencies:


const client = ApsoClientFactory.getClient({
  baseURL: 'https://your-service.apso.cloud',
  apiKey: 'your-api-key',
  // client: 'fetch' is the default -- no need to specify
});

The fetch transport uses AbortController for request timeouts.

axios

Use axios when you need its features (interceptors, progress events, or if your test tooling requires it):


const client = ApsoClientFactory.getClient({
  baseURL: 'https://your-service.apso.cloud',
  apiKey: 'your-api-key',
  client: 'axios',
});

When client: 'axios' is set, the SDK creates a shared axios instance with the configured baseURL, timeout, and headers. This is also required for testing with axios-mock-adapter.

Timeout

Configure how long the SDK waits for a response before aborting the request:


const client = ApsoClientFactory.getClient({
  baseURL: 'https://your-service.apso.cloud',
  apiKey: 'your-api-key',
  timeout: 10000, // 10 seconds
});

The default timeout is 30 seconds (30000 ms). When a request times out, it throws an error. If retry is enabled, timed-out requests are retried.

Retry Configuration

Enable automatic retries for transient failures. When a request fails with a retryable status code, the SDK waits and retries with exponential backoff.

Enable Default Retry

Pass retry: true to use the default retry configuration:


const client = ApsoClientFactory.getClient({
  baseURL: 'https://your-service.apso.cloud',
  apiKey: 'your-api-key',
  retry: true,
});

Default retry settings:

Setting	Default	Description
`attempts`	`3`	Maximum number of retry attempts
`delay`	`1000`	Base delay in milliseconds (multiplied by attempt number)
`statusCodes`	`[408, 429, 500, 502, 503, 504]`	HTTP status codes that trigger a retry

Custom Retry Configuration


interface RetryConfig {
  attempts?: number;       // Max retry attempts (default: 3)
  delay?: number;          // Base delay in ms (default: 1000)
  statusCodes?: number[];  // Retryable status codes
}


const client = ApsoClientFactory.getClient({
  baseURL: 'https://your-service.apso.cloud',
  apiKey: 'your-api-key',
  retry: {
    attempts: 5,
    delay: 2000,
    statusCodes: [429, 502, 503, 504],
  },
});

The backoff is linear: the delay for attempt n is delay * n milliseconds. For example, with delay: 1000, the retries occur after 1s, 2s, 3s, and so on.

Network errors (AbortError, ECONNABORTED) are also retried regardless of the statusCodes list.

Disable Retry

Retry is disabled by default. You can also explicitly disable it:


const client = ApsoClientFactory.getClient({
  baseURL: 'https://your-service.apso.cloud',
  apiKey: 'your-api-key',
  retry: false,
});

Custom Headers

Add custom headers to every request made by the client:


const client = ApsoClientFactory.getClient({
  baseURL: 'https://your-service.apso.cloud',
  apiKey: 'your-api-key',
  headers: {
    'X-Workspace-Id': 'ws-12345',
    'X-Request-Source': 'frontend',
  },
});

Custom headers are merged with the default headers (x-api-key and Content-Type). If you set a header that conflicts with a default, your custom value takes precedence.

Debug Mode

Enable debug mode to log every outgoing request URL to the console:


const client = ApsoClientFactory.getClient({
  baseURL: 'https://your-service.apso.cloud',
  apiKey: 'your-api-key',
  debug: true,
});

This produces output like:


[ApsoClient][DEBUG] GET https://your-service.apso.cloud/Users?filter=status||$eq||Active&limit=10
[ApsoClient][DEBUG] POST https://your-service.apso.cloud/Users
[ApsoClient][DEBUG] PUT https://your-service.apso.cloud/Users/user-123
[ApsoClient][DEBUG] DELETE https://your-service.apso.cloud/Users/user-123

Tip: Only enable debug mode in development. The logs include the full URL with query parameters, which may contain sensitive filter values.

Environment-Based Configuration

A common pattern is to vary configuration by environment:

lib/apso.ts


import { ApsoClientFactory } from '@apso/sdk';
 
const isDev = process.env.NODE_ENV === 'development';
 
export const apso = ApsoClientFactory.getClient({
  baseURL: isDev
    ? 'http://localhost:3001'
    : process.env.APSO_API_URL!,
  apiKey: process.env.APSO_API_KEY!,
  client: isDev ? 'axios' : 'fetch',
  timeout: isDev ? 60000 : 30000,
  retry: isDev ? false : { attempts: 3 },
  debug: isDev,
});

Complete Example