@sub-zero/sdk

Typed client for SubZero's /v2 API.

npm i @sub-zero/sdk

import { SubZeroClient, SubZeroError } from '@sub-zero/sdk';

const subzero = new SubZeroClient({ token: process.env.SUBZERO_TOKEN! });

// Filing an incident from a cron: the idempotency key means a retry, or a
// second delivery of the same job, returns the original ticket instead of
// filing another one.
try {
  const incident = await subzero.createIncident(
    {
      projectKey: 'ACME',
      subject: 'Nightly sync failed',
      description: 'ETIMEDOUT talking to the warehouse API.',
      service: 'ACME-CRON',
      priority: 'P2',
    },
    { idempotencyKey: `nightly-${new Date().toISOString().slice(0, 10)}` },
  );
  console.log(incident.code); // ACME-42
} catch (error) {
  if (error instanceof SubZeroError && error.code === 'PROJECT_NOT_IN_KEY_SCOPE') {
    // the key cannot write to that project; branch on `code`, never on the message
  }
  throw error;
}

// Paging is handled for you.
for await (const incident of subzero.incidents({ status: 'open', priority: 'P1' })) {
  console.log(incident.code, incident.subject);
}

What it does for you

Validates both directions. Requests are checked against @sub-zero/contract before they leave, so a bad payload fails in your process with the payload in hand rather than as a 400 from the server. Responses are checked as they arrive: a field that changes shape raises SubZeroResponseError instead of quietly handing you undefined.

Retries only where a retry is safe. Reads and writes carrying an Idempotency-Key are retried on a 429, a 5xx or a dropped connection, honouring Retry-After and backing off with jitter otherwise. A write without a key is never retried, because a repeat would file a second incident.

Errors you can branch on. SubZeroError carries code, status, requestId and details. 402 and 403 both mean "you cannot do this", and only one of them is fixed by buying more seats.

Options

| | | |---|---| | token | A project ingest key (szk_live_…) or a user session token. Required. | | baseUrl | Defaults to https://api.sub-zero.dev. | | timeoutMs | Per request, default 15000. | | maxRetries | Default 2. Applies only where retrying is safe. | | userAgent | Appended to the SDK's own, e.g. acme-cron/1.4. | | fetch | Swap in for tests or a proxy-aware implementation. |

Coverage

Every /v2 endpoint in the contract: createIncident, listIncidents, incidents (paging), getIncident, listProjects, createProject, updateProject, listProblems, createProblem.

Machine credentials cannot create projects or problems — that is the server's rule, and it will answer FORBIDDEN.