TypeScript SDK

@voltstack/voltclient is a small HTTP client for the VOLT API. It adds the bearer token to each request, unwraps the server's { status, data } envelope, normalizes paginated lists, and turns error responses into a typed ApiError. It runs on Node.js 18 or later and in browsers, on the native fetch, with no required dependencies. The VOLT web app makes its requests with it.

It is a transport, not a typed model of every route: you give it paths, and the route contracts tell you which exist and what they return.

Install

npm install @voltstack/voltclient
npm install axios   # optional: only for upload-progress events

The package ships ESM and CommonJS builds with type declarations. Its source is packages/sdk/voltclient in the VOLT monorepo.

Quick start

Create a secret key for your team, then:

import { createVoltClient, secretKey } from '@voltstack/voltclient';

const root = createVoltClient('https://volt.example.com/api', {
    credential: secretKey(process.env.VOLT_SECRET_KEY!)
});

// The key tells you which team it belongs to.
const teams = root.withBasePath('/teams');
const key = await teams.getUnwrapped<{ team: string; name: string }>('/secret-keys/me');

// Requests scoped to that team: /api/teams/<team>/...
const team = teams.withTeam(key.team);
const page = await team.getPaginated<{ _id: string; name: string }>('/trajectories', { page: 1, limit: 20 });

console.log(page.pagination.total, page.data.map((trajectory) => trajectory.name));

The base URL is the server's origin followed by /api. Every request goes to the base URL, then the client's base path, then the path you pass.

Creating a client

createVoltClient(baseUrl, options?)

Credentials

A CredentialProvider is { getToken(): string | null | Promise<string | null> }, called before every request. The token is sent as Authorization: Bearer <token>; a null token sends no header.

Adapters

FetchHttpClient and AxiosHttpClient both implement HttpClient, { request<T>(req: HttpRequest): Promise<T> }, and take { baseUrl, credential?, timeout? }. Build a VoltClient on either, or on your own HttpClient:

import { VoltClient, FetchHttpClient, secretKey } from '@voltstack/voltclient';

const http = new FetchHttpClient({ baseUrl: 'https://volt.example.com/api', credential: secretKey(key) });
const teams = new VoltClient(http, '/teams');

HttpRequest has method, url, and optional query, body, headers, signal, responseType (json, blob, text or arraybuffer) and onUploadProgress. A FormData body is sent as is; any other body is sent as JSON. Query values that are arrays repeat the key; null and undefined values are dropped.

VoltClient

new VoltClient(http, basePath, options?). The options are useRBAC, getTeamId and dedupeGetRequests.

Scoping

useRBAC: true with getTeamId: () => string | null does the same with a team ID read per request; the request fails with VoltClient: missing teamId for RBAC when it returns nothing.

Requests

Concurrent identical get calls (same URL and query) share one request. Pass dedupeGetRequests: false to send each one. With the fetch adapter, a 204 response, or one with Content-Length: 0, resolves to undefined.

getPaginated accepts both shapes the server uses for lists: data as the array with a separate pagination (it throws VoltClient: paginated response missing pagination metadata when that is missing), or data as { data, total, page, totalPages, limit }. pagination is { page, limit, total, totalPages, hasMore }.

Declarative services

For many endpoints, describe them once with createService(config, methods, factory) and call them as functions. factory(basePath, options) builds the client each method uses; derive it from a client you already have:

import { VoltClient, FetchHttpClient, createService, paginated, get, post, download, secretKey, type ClientFactory } from '@voltstack/voltclient';

const root = new VoltClient(new FetchHttpClient({ baseUrl: 'https://volt.example.com/api', credential: secretKey(key) }), '');
const factory: ClientFactory = (basePath, options) => root.withBasePath(basePath, options);

const trajectories = createService('/teams', {
    list: paginated<{ teamId: string; page?: number; limit?: number }, Trajectory>('/:teamId/trajectories'),
    get: get<{ teamId: string; trajectoryId: string }, Trajectory>('/:teamId/trajectories/:trajectoryId'),
    download: download<{ teamId: string; trajectoryId: string }>('GET', '/:teamId/trajectories/:trajectoryId/download')
}, factory);

const page = await trajectories.list({ teamId, page: 2 });          // GET /teams/<teamId>/trajectories?page=2
const one = await trajectories.get({ teamId, trajectoryId });      // the envelope's data
const file = await trajectories.download({ teamId, trajectoryId }); // a Blob

Path parameters (:name) are filled from the argument object. The remaining fields become the query string of a GET or DELETE, and the JSON body of a POST or PATCH. A missing path parameter throws Missing path param: <name>.

path may also be a function of the parameters. The method options:

config is a base path, { basePath, useRBAC? }, or { clients: { <name>: { basePath, useRBAC?, getTeamId?(params) } } } for a service that spans several base paths; methods use the default client, or the first, unless they name another.

Errors

Every failure is an ApiError with a code, the HTTP status when there was a response, and the originalError. The code is the server's error code (for example SecretKey::Invalid or Team::AccessDenied, see Responses); when the response carries none, it is Http::<status> for 400, 401, 403, 404, 409, 429, 500, 502, 503 and 504, else Internal::Server::Error. Network failures are Network::Timeout and Network::ConnectionError. Aborted requests reject with the abort error itself.

import { ApiError } from '@voltstack/voltclient';

try {
    await team.getUnwrapped(`/trajectories/${trajectoryId}`);
} catch (error) {
    if (error instanceof ApiError && error.status === 404) {
        // not found
    }
    throw error;
}

The package also exports ERROR_CODE_MESSAGES, getErrorMessage(code, fallback?) and extractServerCode(body).