@quicore/api-client

Production-ready HTTP and FHIR API client for Node.js with retry, timeout, cancellation, and lifecycle hook support.

Installation

npm install @quicore/api-client

Classes

APIClient

Generic HTTP client built on top of axios.

Features:

• Configurable retry policy with exponential backoff + jitter
• Retry-After header support (absolute date and delta-seconds)
• Per-request and per-status-code lifecycle hooks
• Fluent builder API

import { APIClient } from '@quicore/api-client';

const client = new APIClient('https://api.example.com')
  .setAccessToken('my-token')
  .setRetryPolicy({ maxRetries: 3, initialDelayMs: 500 })
  .setOnAccessDenied(async (result) => { /* refresh token */ });

const result = await client.executeWithRetry({
  method: 'get',
  url: '/patients'
});

FHIRClient

FHIR R4 client extending APIClient with bundle pagination and FHIR-specific URL building.

Features:

• Automatic application/fhir+json content negotiation
• Bundle pagination (hasMoreData() / getNextPageData())
• Resource type, ID, operation, and patient search parameter helpers

import { FHIRClient } from '@quicore/api-client';
// or: import { FHIRClient } from '@quicore/api-client/fhir';

const client = new FHIRClient('https://fhir.example.com', 'Observation')
  .setAccessToken('my-token')
  .searchByPatient('patient-123')
  .searchByParameters({ category: 'laboratory' });

let result = await client.execute();

while (client.hasMoreData()) {
  result = await client.getNextPageData();
  // process result.data
}

API Reference

APIClient

| Method | Description | |--------|-------------| | setHeaders(key, value) | Set a request header | | setAccessToken(token) | Set Authorization: Bearer <token> | | setContentType(type) | Set the Accept header | | setBody(data) | Set the request body | | setParameters(params) | Merge query parameters | | setTimeout(ms) | Set request timeout in milliseconds | | setRetryPolicy(policy) | Override the default retry policy | | setOnRequest(fn) | Hook called before each request | | setOnResponse(fn) | Hook called on successful response | | setOnError(fn) | Hook called on error | | setOnAccessDenied(fn) | Hook called on 401/403 | | setOnRateLimit(fn) | Hook called on 429 | | addStatusCodeHook(code, fn) | Hook called for a specific status code | | executeOnce(config, signal) | Execute without retry | | executeWithRetry(config, opts) | Execute with retry policy |

Default Retry Policy

{
  maxRetries: 3,
  initialDelayMs: 300,
  maxDelayMs: 3000,
  retryOnStatuses: [429, 500, 502, 503, 504],
  retryOnNetworkError: true
}

FHIRClient

Inherits all APIClient methods, plus:

| Method | Description | |--------|-------------| | setResourceType(type, method) | Set FHIR resource type and HTTP method | | searchById(id) | Append resource ID to the URL | | searchByPatient(patientId) | Add patient query parameter | | searchByParameters(params) | Merge FHIR search parameters | | setOperation(operation) | Append a FHIR operation (e.g. $everything) | | execute(useRetry) | Build URL and execute the request | | hasMoreData() | Returns true if a next bundle link exists | | getNextPageData(useRetry) | Fetch the next page using the bundle next link |

Build

npm run build

Outputs CommonJS to dist/ via Babel.

License

MIT