JavaScript SDK

@regsn/api is a small, dependency-free JavaScript client for the API — one ESM module plus TypeScript type definitions.

Property	Value
Package	`@regsn/api`, version 0.2.0
Runtime	Node 18+ (uses the built-in `fetch`)
Module format	ESM only (`import`)
Dependencies	None
Types	Bundled (`index.d.ts`)

Availability. @regsn/api is source-available; publication to the public npm registry is pending, so npm install @regsn/api does not work yet. Until it lands, call the HTTP API directly — every page in this reference carries copy-pasteable curl, and the surface is small. This page documents the SDK for teams who already have the source.

Setup


import { RegSn } from '@regsn/api';
 
const client = new RegSn({ apiKey: 'regsn_live_…' });

Constructor option	Default	Notes
`apiKey`	`process.env.REGSN_API_KEY`	Required, one way or the other.
`baseUrl`	`https://api.regsn.app`	Override for testing.
`timeoutMs`	`180000`	Per-request timeout (aborts the request).

Methods

The client exposes four resources mirroring the HTTP surface:

Method	Calls	Notes
`client.scans.create(config, opts?)`	`POST /v1/scans`	`opts`: `mode` (`'sync'` default), `idempotencyKey`, `pollUntilDone` (`true` default). If the API returns `202`, polls until terminal.
`client.scans.createAsync(config, opts?)`	`POST /v1/scans?mode=async`	Returns the `202` body immediately — no polling.
`client.scans.get(scanId)`	`GET /v1/scans/{id}`
`client.scans.wait(scanId, opts?)`	polls `GET /v1/scans/{id}`	`opts`: `pollMs` (5 000), `timeoutMs` (720 000). Resolves with `{ scan_id, status, snapshot_id, snapshot }` — `snapshot` is the full `GET /v1/snapshots/{id}` body. Throws on failure or timeout.
`client.snapshots.list(filters?)`	`GET /v1/snapshots`	`filters` become query parameters (`from`, `to`, `jurisdiction`, `area`, `limit`, `offset`).
`client.snapshots.get(id)`	`GET /v1/snapshots/{id}`
`client.snapshots.getItems(id)` / `getTrends(id)` / `getExecutiveSummary(id)`	sub-resources
`client.snapshots.getExecutiveNarrative(id, { language })`	`GET …/executive-narrative`	`language` defaults `'en'`.
`client.snapshots.getDrift(id)`	`GET …/drift`
`client.exports.create({ snapshot_id, artifact_type, provider, options }, opts?)`	`POST /v1/exports`	`opts.idempotencyKey` optional.
`client.exports.get(id)`	`GET /v1/exports/{id}`
`client.usage.get(filters?)`	`GET /v1/usage`	`from`, `to`, `group_by`.

0.2.0 also wraps scans.estimate, scans.cancel, export list/download/delete (exports.list / exports.download / exports.delete), usage.budget, and the five /v1/meta/* reads (meta.engines / models / jurisdictions / areas / exportTypes). Still not wrapped: the SSE stream — use EventSource or any SSE client. Key management is excluded by design: keys are minted and revoked only in a signed-in dashboard session at api.regsn.app, never with an API key, so there is nothing for an SDK to wrap.

End to end

scan-and-read.mjs


import { RegSn } from '@regsn/api';
 
const client = new RegSn(); // reads REGSN_API_KEY
 
const result = await client.scans.create({
  jurisdictions: ['UK', 'EU'],
  areas: ['AML / KYC'],
  horizon: 12,
});
 
// Deterministic envelope shape regardless of sync/async path:
const snap = await client.snapshots.get(result.snapshot_id);
console.log(snap.data.executive_narrative);
 
const job = await client.exports.create({
  snapshot_id: result.snapshot_id,
  provider: 'internal-pdf',
  artifact_type: 'pdf',
});
console.log(job.status_url);

Envelope shapes. A fast sync scan resolves with the envelope flat under snapshot; when create had to poll, snapshot is the full GET /v1/snapshots/{id} body (envelope nested under data). Re-fetching by snapshot_id, as above, always gives the nested shape.

Retries, idempotency, timeouts

Every POST gets an auto-generated UUID Idempotency-Key unless you pass idempotencyKey — the SDK’s own retries can never duplicate a scan or export.
Up to 3 retries on network errors, 5xx, and 429. Retry-After is honoured, capped at 60 seconds per wait, with exponential backoff and jitter otherwise.
Requests abort after timeoutMs (default 180 s) via AbortController.

Errors

Failures throw RegSnError:


import { RegSn, RegSnError } from '@regsn/api';
 
try {
  await client.scans.create({ jurisdictions: ['UK'], areas: ['Payments'], horizon: 6 });
} catch (err) {
  if (err instanceof RegSnError) {
    console.error(err.status);    // e.g. 402
    console.error(err.code);      // e.g. 'budget_exhausted'
    console.error(err.requestId); // 'req_…' — quote this in support requests
    console.error(err.body);      // full problem-details document
  }
}

SDK-generated codes (no HTTP status): network_error, retry_exceeded, scan_failed (from wait when a scan ends failed), wait_timeout. Everything else is the API’s own code.