@distyra/sdk 0.5.0 → 0.6.1

package/dist/index.d.ts

@@ -7,8 +7,18 @@
  *   - `paths` — generated types from the OpenAPI snapshot in
  *     apps/saas-api/openapi.json. Re-exported so callers can write their own
  *     openapi-fetch client if they need non-default behavior.
- *   - `createDistyraClient()` — opinionated factory that wires up bearer auth
- *     and a default base URL, returning a typed openapi-fetch client.
+ *   - `createDistyraClient()` — opinionated factory that wires up bearer auth,
+ *     a default base URL, and a request timeout, returning a typed
+ *     openapi-fetch client.
+ *
+ * Plus three ergonomic helpers on top of the typed client:
+ *
+ *   - a default request timeout (AbortController) — parity with the Python SDK's
+ *     30s default; previously the JS client had none (a hung origin hung the
+ *     caller forever).
+ *   - `idempotencyKey()` — sets the spec-conformant `Idempotency-Key` header so
+ *     retried POSTs dedup server-side.
+ *   - `paginate()` — auto-iterates the cursor-paginated list endpoints.
  *
  * Consumers: the banking backend internally (shadow-mode and cutover paths,
  * v2 plan §16.4 weeks 6–9) plus external API customers via the published
@@ -26,12 +36,19 @@ import { type Client, type ClientOptions } from 'openapi-fetch';
 import type { paths } from './generated';
 export type { paths } from './generated';
 export type { components, operations } from './generated';
+export { verifyWebhook, SIGNATURE_HEADER, DEFAULT_TOLERANCE_SECONDS } from './webhook';
+export type { VerifyResult, VerifyWebhookOptions } from './webhook';
 /**
  * Production base URL. Mirrors the OpenAPI `servers[0]` entry; kept in sync by
  * hand because the SDK shouldn't have to parse the spec at runtime. The API and
  * CDN stay on `.com`; only the Distyra website and customer portal use `.eu`.
  */
 export declare const PRODUCTION_BASE_URL = "https://api.distyra.com";
+/**
+ * Default per-request timeout, in milliseconds. Matches the Python SDK's 30s so
+ * the two clients behave identically. Set `timeoutMs: 0` to disable.
+ */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
 export interface DistyraClientOptions extends Omit<ClientOptions, 'baseUrl' | 'headers'> {
     /** API key (`sk_…`). Required. */
     apiKey: string;
@@ -39,6 +56,29 @@ export interface DistyraClientOptions extends Omit<ClientOptions, 'baseUrl' | 'h
     baseUrl?: string;
     /** Extra headers merged on every request (rarely needed; useful for tracing). */
     headers?: Record<string, string>;
+    /**
+     * Per-request timeout in milliseconds (default {@link DEFAULT_TIMEOUT_MS}).
+     * The request is aborted with a `TimeoutError` when it elapses. Set to `0`
+     * to disable the timeout entirely. A caller-supplied `signal` on an
+     * individual request still wins — aborting it aborts the request early, and
+     * the timeout is layered on top.
+     */
+    timeoutMs?: number;
+}
+/**
+ * A non-2xx API response (or a thrown transport error) surfaced by the helper
+ * layer (`paginate`). Mirrors the Python SDK's `DistyraError`: carries the
+ * parsed `{ error, detail }` envelope so callers don't re-parse the body.
+ *
+ * The base `createDistyraClient()` client itself still returns the openapi-fetch
+ * `{ data, error }` union on ordinary calls — this is only thrown by helpers
+ * that can't express a partial result (an iterator can't yield an error union).
+ */
+export declare class DistyraApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly detail?: string;
+    constructor(status: number, body: unknown);
 }
 /**
  * Create a typed openapi-fetch client pre-bound to the Distyra API.
@@ -52,5 +92,57 @@ export interface DistyraClientOptions extends Omit<ClientOptions, 'baseUrl' | 'h
  *
  * `data` is fully typed against the EnrichResponse schema. `error` carries
  * the standard `{ error, detail? }` envelope on 4xx/5xx.
+ *
+ * Retry-safe POSTs: spread {@link idempotencyKey}() into the request options.
+ * Long list endpoints: use {@link paginate} to iterate every page.
  */
 export declare function createDistyraClient(opts: DistyraClientOptions): Client<paths>;
+/**
+ * A request-options fragment that sets the `Idempotency-Key` header. Spread it
+ * into any POST so a retried call dedups server-side instead of double-charging
+ * or double-creating:
+ *
+ *   const key = crypto.randomUUID();
+ *   await sdk.POST('/v1/enrich/batch', { body, ...idempotencyKey(key) });
+ *   // ...on a network error, retry with the SAME fragment — the server replays
+ *   //    the original response instead of re-running the batch.
+ *
+ * Call with no argument to mint a fresh v4 UUID (useful for a one-shot request
+ * you won't retry). To make retries safe you must REUSE the same key across the
+ * original and every retry, so capture it once and pass it back in.
+ *
+ * The header is the spec-conformant `Idempotency-Key` (no `X-` prefix). The
+ * legacy `X-Idempotency-Key` still works server-side but is deprecated.
+ */
+export declare function idempotencyKey(key?: string): {
+    headers: {
+        'Idempotency-Key': string;
+    };
+};
+/**
+ * The cursor-paginated list endpoints. Each returns `{ <items>: [...],
+ * next_cursor: string | null }` and accepts a `cursor` query param; the cursor
+ * is an opaque `<iso-timestamp>|<uuid>` string. {@link paginate} auto-advances
+ * it until `next_cursor` is null.
+ */
+export type CursorListPath = '/v1/underwrite/analyses' | '/v1/underwrite/ingestions' | '/v1/underwrite/collection-links';
+export interface PaginateOptions {
+    /** Extra query params (e.g. `limit`) applied to every page request. `cursor` is managed for you and any value passed here is ignored. */
+    query?: Record<string, unknown>;
+    /** Optional AbortSignal to stop iterating between pages. */
+    signal?: AbortSignal;
+}
+/**
+ * Async-iterate every item across all pages of a cursor-paginated list
+ * endpoint, transparently following `next_cursor`:
+ *
+ *   for await (const link of paginate(sdk, '/v1/underwrite/collection-links')) {
+ *     console.log(link.id, link.status);
+ *   }
+ *
+ * Yields the individual items (not pages) — it auto-detects the single array
+ * field in each response (`analyses` / `ingestions` / `collection_links`).
+ * Throws {@link DistyraApiError} on any non-2xx page so a mid-iteration failure
+ * surfaces instead of silently truncating.
+ */
+export declare function paginate<Item = Record<string, unknown>>(client: Client<paths>, path: CursorListPath, options?: PaginateOptions): AsyncGenerator<Item, void, unknown>;

package/dist/index.js

@@ -8,8 +8,18 @@
  *   - `paths` — generated types from the OpenAPI snapshot in
  *     apps/saas-api/openapi.json. Re-exported so callers can write their own
  *     openapi-fetch client if they need non-default behavior.
- *   - `createDistyraClient()` — opinionated factory that wires up bearer auth
- *     and a default base URL, returning a typed openapi-fetch client.
+ *   - `createDistyraClient()` — opinionated factory that wires up bearer auth,
+ *     a default base URL, and a request timeout, returning a typed
+ *     openapi-fetch client.
+ *
+ * Plus three ergonomic helpers on top of the typed client:
+ *
+ *   - a default request timeout (AbortController) — parity with the Python SDK's
+ *     30s default; previously the JS client had none (a hung origin hung the
+ *     caller forever).
+ *   - `idempotencyKey()` — sets the spec-conformant `Idempotency-Key` header so
+ *     retried POSTs dedup server-side.
+ *   - `paginate()` — auto-iterates the cursor-paginated list endpoints.
  *
  * Consumers: the banking backend internally (shadow-mode and cutover paths,
  * v2 plan §16.4 weeks 6–9) plus external API customers via the published
@@ -27,15 +37,49 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PRODUCTION_BASE_URL = void 0;
+exports.DistyraApiError = exports.DEFAULT_TIMEOUT_MS = exports.PRODUCTION_BASE_URL = exports.DEFAULT_TOLERANCE_SECONDS = exports.SIGNATURE_HEADER = exports.verifyWebhook = void 0;
 exports.createDistyraClient = createDistyraClient;
+exports.idempotencyKey = idempotencyKey;
+exports.paginate = paginate;
 const openapi_fetch_1 = __importDefault(require("openapi-fetch"));
+// Webhook signature verification (server-side; node:crypto). Isolated in
+// ./webhook so importing the client alone doesn't require a Node runtime.
+var webhook_1 = require("./webhook");
+Object.defineProperty(exports, "verifyWebhook", { enumerable: true, get: function () { return webhook_1.verifyWebhook; } });
+Object.defineProperty(exports, "SIGNATURE_HEADER", { enumerable: true, get: function () { return webhook_1.SIGNATURE_HEADER; } });
+Object.defineProperty(exports, "DEFAULT_TOLERANCE_SECONDS", { enumerable: true, get: function () { return webhook_1.DEFAULT_TOLERANCE_SECONDS; } });
 /**
  * Production base URL. Mirrors the OpenAPI `servers[0]` entry; kept in sync by
  * hand because the SDK shouldn't have to parse the spec at runtime. The API and
  * CDN stay on `.com`; only the Distyra website and customer portal use `.eu`.
  */
 exports.PRODUCTION_BASE_URL = 'https://api.distyra.com';
+/**
+ * Default per-request timeout, in milliseconds. Matches the Python SDK's 30s so
+ * the two clients behave identically. Set `timeoutMs: 0` to disable.
+ */
+exports.DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * A non-2xx API response (or a thrown transport error) surfaced by the helper
+ * layer (`paginate`). Mirrors the Python SDK's `DistyraError`: carries the
+ * parsed `{ error, detail }` envelope so callers don't re-parse the body.
+ *
+ * The base `createDistyraClient()` client itself still returns the openapi-fetch
+ * `{ data, error }` union on ordinary calls — this is only thrown by helpers
+ * that can't express a partial result (an iterator can't yield an error union).
+ */
+class DistyraApiError extends Error {
+    constructor(status, body) {
+        const env = (body ?? {});
+        const code = env.error ?? 'unknown_error';
+        super(`HTTP ${status}: ${code}${env.detail ? ` — ${env.detail}` : ''}`);
+        this.name = 'DistyraApiError';
+        this.status = status;
+        this.code = code;
+        this.detail = env.detail;
+    }
+}
+exports.DistyraApiError = DistyraApiError;
 /**
  * Create a typed openapi-fetch client pre-bound to the Distyra API.
  *
@@ -48,14 +92,22 @@ exports.PRODUCTION_BASE_URL = 'https://api.distyra.com';
  *
  * `data` is fully typed against the EnrichResponse schema. `error` carries
  * the standard `{ error, detail? }` envelope on 4xx/5xx.
+ *
+ * Retry-safe POSTs: spread {@link idempotencyKey}() into the request options.
+ * Long list endpoints: use {@link paginate} to iterate every page.
  */
 function createDistyraClient(opts) {
-    const { apiKey, baseUrl = exports.PRODUCTION_BASE_URL, headers, ...rest } = opts;
+    const { apiKey, baseUrl = exports.PRODUCTION_BASE_URL, headers, timeoutMs = exports.DEFAULT_TIMEOUT_MS, fetch: fetchImpl, ...rest } = opts;
     if (!apiKey) {
         throw new Error('createDistyraClient: apiKey is required');
     }
+    // openapi-fetch always calls `fetch` with a single Request object, so the
+    // custom-fetch slot is narrower than the global `fetch` signature.
+    const baseFetch = fetchImpl ?? globalThis.fetch;
+    const clientFetch = timeoutMs > 0 ? (input) => fetchWithTimeout(baseFetch, input, timeoutMs) : baseFetch;
     return (0, openapi_fetch_1.default)({
         baseUrl,
+        fetch: clientFetch,
         headers: {
             Authorization: `Bearer ${apiKey}`,
             'Content-Type': 'application/json',
@@ -64,3 +116,101 @@ function createDistyraClient(opts) {
         ...rest,
     });
 }
+/**
+ * A request-options fragment that sets the `Idempotency-Key` header. Spread it
+ * into any POST so a retried call dedups server-side instead of double-charging
+ * or double-creating:
+ *
+ *   const key = crypto.randomUUID();
+ *   await sdk.POST('/v1/enrich/batch', { body, ...idempotencyKey(key) });
+ *   // ...on a network error, retry with the SAME fragment — the server replays
+ *   //    the original response instead of re-running the batch.
+ *
+ * Call with no argument to mint a fresh v4 UUID (useful for a one-shot request
+ * you won't retry). To make retries safe you must REUSE the same key across the
+ * original and every retry, so capture it once and pass it back in.
+ *
+ * The header is the spec-conformant `Idempotency-Key` (no `X-` prefix). The
+ * legacy `X-Idempotency-Key` still works server-side but is deprecated.
+ */
+function idempotencyKey(key) {
+    return { headers: { 'Idempotency-Key': key ?? randomUuid() } };
+}
+/**
+ * Async-iterate every item across all pages of a cursor-paginated list
+ * endpoint, transparently following `next_cursor`:
+ *
+ *   for await (const link of paginate(sdk, '/v1/underwrite/collection-links')) {
+ *     console.log(link.id, link.status);
+ *   }
+ *
+ * Yields the individual items (not pages) — it auto-detects the single array
+ * field in each response (`analyses` / `ingestions` / `collection_links`).
+ * Throws {@link DistyraApiError} on any non-2xx page so a mid-iteration failure
+ * surfaces instead of silently truncating.
+ */
+async function* paginate(client, path, options = {}) {
+    const baseQuery = { ...(options.query ?? {}) };
+    delete baseQuery.cursor; // cursor is managed here; ignore any caller value
+    let cursor;
+    for (;;) {
+        const query = cursor ? { ...baseQuery, cursor } : baseQuery;
+        // openapi-fetch's GET is per-path typed; the generic helper spans several
+        // paths, so we go through the untyped call and re-type the page below.
+        const { data, error, response } = await client.GET(path, { params: { query }, signal: options.signal });
+        if (error !== undefined || data === undefined) {
+            throw new DistyraApiError(response?.status ?? 0, error);
+        }
+        const page = data;
+        const items = Object.values(page).find((v) => Array.isArray(v)) ?? [];
+        for (const item of items) {
+            yield item;
+        }
+        const next = page.next_cursor;
+        if (typeof next !== 'string' || next.length === 0) {
+            break;
+        }
+        cursor = next;
+    }
+}
+/**
+ * Wrap a fetch call in an AbortController-driven timeout while still honoring a
+ * caller-supplied `signal` on the incoming Request (aborting either one aborts
+ * the request).
+ */
+function fetchWithTimeout(baseFetch, input, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort(new DOMException(`Request timed out after ${timeoutMs}ms`, 'TimeoutError'));
+    }, timeoutMs);
+    const callerSignal = input.signal;
+    if (callerSignal) {
+        if (callerSignal.aborted) {
+            controller.abort(callerSignal.reason);
+        }
+        else {
+            callerSignal.addEventListener('abort', () => controller.abort(callerSignal.reason), {
+                once: true,
+            });
+        }
+    }
+    return baseFetch(new Request(input, { signal: controller.signal })).finally(() => clearTimeout(timer));
+}
+/** RFC-4122 v4 UUID via WebCrypto, with graceful fallbacks for old runtimes. */
+function randomUuid() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID) {
+        return c.randomUUID();
+    }
+    if (c?.getRandomValues) {
+        const b = c.getRandomValues(new Uint8Array(16));
+        b[6] = (b[6] & 0x0f) | 0x40;
+        b[8] = (b[8] & 0x3f) | 0x80;
+        const hex = Array.from(b, (x) => x.toString(16).padStart(2, '0'));
+        return `${hex.slice(0, 4).join('')}-${hex.slice(4, 6).join('')}-${hex
+            .slice(6, 8)
+            .join('')}-${hex.slice(8, 10).join('')}-${hex.slice(10, 16).join('')}`;
+    }
+    // Last resort — non-crypto, but idempotency keys only need to be unique.
+    return 'idem-' + Date.now().toString(16) + '-' + Math.random().toString(16).slice(2);
+}

package/dist/webhook.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Webhook signature verification for Distyra webhook deliveries.
+ *
+ * Distyra signs every delivery with a Stripe-shape header:
+ *
+ *     X-Distyra-Signature: t=<unix>,v1=<hmac_sha256_hex>
+ *
+ * where the HMAC-SHA256 input is the literal string "<t>.<raw_body>", keyed by
+ * your endpoint's signing secret (the value returned when you create or rotate
+ * the endpoint). The `t` prefix defends against replay: the verifier rejects
+ * timestamps outside a tolerance window (5 minutes by default).
+ *
+ * Always verify against the RAW request body, before JSON parsing — any
+ * re-serialization changes the bytes and invalidates the HMAC.
+ *
+ * This module uses `node:crypto` and is intended for server-side webhook
+ * receivers (Node 18+). It is kept in its own module so importing the API
+ * client (`@distyra/sdk`) in a non-Node runtime does not pull in `node:crypto`.
+ */
+/** The header Distyra sends the signature in. */
+export declare const SIGNATURE_HEADER = "X-Distyra-Signature";
+/** Default replay-protection window, in seconds. */
+export declare const DEFAULT_TOLERANCE_SECONDS: number;
+export type VerifyResult = {
+    ok: true;
+    timestamp: number;
+} | {
+    ok: false;
+    reason: 'malformed' | 'stale' | 'no_match';
+};
+export interface VerifyWebhookOptions {
+    /** Reject a signature whose timestamp is more than this many seconds from now (default 300). */
+    toleranceSeconds?: number;
+    /** Override "now" (unix seconds). For testing. */
+    now?: number;
+}
+/**
+ * Verify a Distyra webhook signature.
+ *
+ * @param secret          Your endpoint's signing secret.
+ * @param payload         The RAW request body string, exactly as received. Do
+ *                        NOT `JSON.parse` then re-`stringify` — verify the raw bytes.
+ * @param signatureHeader The value of the `X-Distyra-Signature` header.
+ * @returns `{ ok: true, timestamp }` when valid; otherwise `{ ok: false, reason }`
+ *          where reason is `'malformed'` (unparseable/absent header), `'stale'`
+ *          (outside the tolerance window), or `'no_match'` (signature mismatch).
+ *
+ * @example
+ * import { verifyWebhook } from '@distyra/sdk';
+ *
+ * const raw = await readRawBody(req); // the exact bytes, before JSON.parse
+ * const result = verifyWebhook(secret, raw, req.headers['x-distyra-signature']);
+ * if (!result.ok) return res.status(400).end();
+ * const event = JSON.parse(raw);
+ */
+export declare function verifyWebhook(secret: string, payload: string, signatureHeader: string | null | undefined, options?: VerifyWebhookOptions): VerifyResult;

package/dist/webhook.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Webhook signature verification for Distyra webhook deliveries.
+ *
+ * Distyra signs every delivery with a Stripe-shape header:
+ *
+ *     X-Distyra-Signature: t=<unix>,v1=<hmac_sha256_hex>
+ *
+ * where the HMAC-SHA256 input is the literal string "<t>.<raw_body>", keyed by
+ * your endpoint's signing secret (the value returned when you create or rotate
+ * the endpoint). The `t` prefix defends against replay: the verifier rejects
+ * timestamps outside a tolerance window (5 minutes by default).
+ *
+ * Always verify against the RAW request body, before JSON parsing — any
+ * re-serialization changes the bytes and invalidates the HMAC.
+ *
+ * This module uses `node:crypto` and is intended for server-side webhook
+ * receivers (Node 18+). It is kept in its own module so importing the API
+ * client (`@distyra/sdk`) in a non-Node runtime does not pull in `node:crypto`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TOLERANCE_SECONDS = exports.SIGNATURE_HEADER = void 0;
+exports.verifyWebhook = verifyWebhook;
+const node_crypto_1 = require("node:crypto");
+/** The header Distyra sends the signature in. */
+exports.SIGNATURE_HEADER = 'X-Distyra-Signature';
+/** Default replay-protection window, in seconds. */
+exports.DEFAULT_TOLERANCE_SECONDS = 5 * 60;
+/**
+ * Verify a Distyra webhook signature.
+ *
+ * @param secret          Your endpoint's signing secret.
+ * @param payload         The RAW request body string, exactly as received. Do
+ *                        NOT `JSON.parse` then re-`stringify` — verify the raw bytes.
+ * @param signatureHeader The value of the `X-Distyra-Signature` header.
+ * @returns `{ ok: true, timestamp }` when valid; otherwise `{ ok: false, reason }`
+ *          where reason is `'malformed'` (unparseable/absent header), `'stale'`
+ *          (outside the tolerance window), or `'no_match'` (signature mismatch).
+ *
+ * @example
+ * import { verifyWebhook } from '@distyra/sdk';
+ *
+ * const raw = await readRawBody(req); // the exact bytes, before JSON.parse
+ * const result = verifyWebhook(secret, raw, req.headers['x-distyra-signature']);
+ * if (!result.ok) return res.status(400).end();
+ * const event = JSON.parse(raw);
+ */
+function verifyWebhook(secret, payload, signatureHeader, options = {}) {
+    if (!signatureHeader)
+        return { ok: false, reason: 'malformed' };
+    const tolerance = options.toleranceSeconds ?? exports.DEFAULT_TOLERANCE_SECONDS;
+    const now = options.now ?? Math.floor(Date.now() / 1000);
+    const parsed = parseSignatureHeader(signatureHeader);
+    if (!parsed)
+        return { ok: false, reason: 'malformed' };
+    if (Math.abs(now - parsed.t) > tolerance) {
+        return { ok: false, reason: 'stale' };
+    }
+    const expected = (0, node_crypto_1.createHmac)('sha256', secret).update(`${parsed.t}.${payload}`).digest();
+    for (const v of parsed.signatures) {
+        const candidate = Buffer.from(v, 'hex');
+        if (candidate.length !== expected.length)
+            continue;
+        if ((0, node_crypto_1.timingSafeEqual)(candidate, expected)) {
+            return { ok: true, timestamp: parsed.t };
+        }
+    }
+    return { ok: false, reason: 'no_match' };
+}
+function parseSignatureHeader(header) {
+    let t = null;
+    const signatures = [];
+    for (const part of header.split(',')) {
+        const eq = part.indexOf('=');
+        if (eq < 0)
+            return null;
+        const key = part.slice(0, eq).trim();
+        const value = part.slice(eq + 1).trim();
+        if (key === 't') {
+            const n = Number.parseInt(value, 10);
+            if (!Number.isFinite(n))
+                return null;
+            t = n;
+        }
+        else if (key === 'v1') {
+            signatures.push(value);
+        }
+        // Unknown keys (future v2, etc.) are ignored — forward-compat.
+    }
+    if (t === null || signatures.length === 0)
+        return null;
+    return { t, signatures };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@distyra/sdk",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "TypeScript SDK for the Distyra Transaction Enrichment & SME Underwriting API. Generated from the committed OpenAPI spec; thin, typed wrapper around openapi-fetch.",
   "license": "MIT",
   "author": "Brightfield Software",