@dsptch-work/api-client

A generated, typed TypeScript client for the DSPTCH public REST API. It replaces hand-rolled fetch wrappers with one class per resource, method names that match the API's operationIds, fully typed request/response shapes, and a bundled fetch client that wires up the base URL and X-Api-Key auth for you.

Status: pre-1.0, published to the public npm registry. The API is still catching up to the DSPTCH web app, so releases stay in the 0.x range and may ship breaking changes between minor versions (0.5.x → 0.6.0) — pin a version you have tested.

Installing

npm install @dsptch-work/api-client   # or: pnpm add @dsptch-work/api-client · yarn add @dsptch-work/api-client

It is a public package: installing needs no registry configuration and no authentication. Making authenticated API calls does require a DSPTCH API key — see Usage.

Usage

import { Jobs } from '@dsptch-work/api-client';
import { client } from '@dsptch-work/api-client/client';

// Configure auth once. The returned string is sent as the `X-Api-Key` header on every
// authenticated request. A function is used so the key can be resolved lazily — e.g.
// read from `process.env` in a Node script, or from a secret store.
client.setConfig({ auth: () => apiKey });

// One class per tag; each method is named by the operation's operationId.
const { data, error } = await Jobs.listJobs({
  query: { 'filter[project_id]': projectId },
});

if (error) {
  throw new Error(`Failed to list jobs: ${JSON.stringify(error)}`);
}

console.log(data);

The base URL (https://api.dsptch.app) is baked in from the spec's servers entry, so there is nothing to configure for production. Override it per environment with client.setConfig({ baseUrl: '…' }).

A runnable, type-checked version of the above lives in examples/basic-usage.ts.

Paginating list endpoints

List endpoints are cursor-paginated: each response carries a meta.page.next_cursor, and a null cursor is the last page. Instead of looping on that by hand, hand a list method to paginate and iterate every item across every page:

import { Jobs, paginate, collect } from '@dsptch-work/api-client';

for await (const job of paginate(Jobs.listJobs, { query: { 'filter[project_id]': projectId } })) {
  process(job); // `job` is typed as the Jobs list element
}

// Or, when every page fits in memory, drain it into an array:
const jobs = await collect(paginate(Jobs.listJobs));

The item type is inferred from the method, and the options keep the method's own shape — required where the endpoint needs a path id (paginate(ApprenticeshipApprentices.listApprentices, { path: { program_id } })), optional otherwise. paginate sends each page's next_cursor as the next page[cursor] and throws if the endpoint returns an error.

What's exported

Maintaining the client itself (regenerating from the spec, building, releasing) is documented for contributors in the repository: DEVELOPMENT.md and RELEASING.md.