@cuvo-health-us/api 0.1.0-next.0

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@cuvo-health-us/api`: the TypeScript client for the Cuvo Integrations API.
+ *
+ * Every type in here is generated from `api/openapi/v1.yaml`, which is generated from the zod
+ * schemas the server validates with. Nothing about the contract is written by hand twice.
+ */
+export { type CuvoClient, type CuvoClientOptions, createCuvoClient, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, } from "./client.js";
+export { CuvoApiError, type Problem, type ProblemIssue, unwrap } from "./errors.js";
+export { type CuvoEvent, type CuvoEventOf, type CuvoEventResourceOf, type CuvoEventResourceType, type CuvoEventResourceTypeOf, type CuvoEventType, type CuvoTypedEvent, type ExpandedResource, expandEvent, typedEvent, } from "./events.js";
+export type { components, operations, paths } from "./generated/v1.js";
+export { type ListPage, paginate } from "./pagination.js";
+export { DEFAULT_TOLERANCE_SECONDS, parseEvent, type VerifySignatureOptions, verifySignature, } from "./webhooks.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@cuvo-health-us/api`: the TypeScript client for the Cuvo Integrations API.
+ *
+ * Every type in here is generated from `api/openapi/v1.yaml`, which is generated from the zod
+ * schemas the server validates with. Nothing about the contract is written by hand twice.
+ */
+export { createCuvoClient, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, } from "./client.js";
+export { CuvoApiError, unwrap } from "./errors.js";
+export { expandEvent, typedEvent, } from "./events.js";
+export { paginate } from "./pagination.js";
+export { DEFAULT_TOLERANCE_SECONDS, parseEvent, verifySignature, } from "./webhooks.js";

package/dist/pagination.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Every list in the contract answers the same envelope and pages on the id of the last row.
+ * There is no total, so a caller who wants "all of them" writes the same loop every time. This
+ * is that loop.
+ */
+export interface ListPage<Item> {
+    data: Item[];
+    has_more: boolean;
+}
+/**
+ * Walk a list endpoint to its end, one item at a time.
+ *
+ * ```ts
+ * const cases = paginate((starting_after) =>
+ *   unwrap(
+ *     await cuvo.GET("/v1/cases", {
+ *       params: { query: { limit: 100, status: "in_review", starting_after } },
+ *     }),
+ *   ),
+ * );
+ * for await (const item of cases) console.log(item.id);
+ * ```
+ *
+ * The callback takes the cursor and returns a page, rather than this taking the filters itself,
+ * so the filters stay contextually typed by the endpoint: `status: "in_review"` is checked
+ * against that operation's enum instead of widening to `string`.
+ *
+ * The iterator is lazy. It fetches the next page only when the consumer asks for an item past
+ * the end of the current one, so `break` costs nothing.
+ */
+export declare function paginate<Item extends {
+    id: string;
+}>(listPage: (cursor: string | undefined) => Promise<ListPage<Item>>): AsyncGenerator<Item, void, undefined>;

package/dist/pagination.js

@@ -0,0 +1,46 @@
+/**
+ * Every list in the contract answers the same envelope and pages on the id of the last row.
+ * There is no total, so a caller who wants "all of them" writes the same loop every time. This
+ * is that loop.
+ */
+/**
+ * Walk a list endpoint to its end, one item at a time.
+ *
+ * ```ts
+ * const cases = paginate((starting_after) =>
+ *   unwrap(
+ *     await cuvo.GET("/v1/cases", {
+ *       params: { query: { limit: 100, status: "in_review", starting_after } },
+ *     }),
+ *   ),
+ * );
+ * for await (const item of cases) console.log(item.id);
+ * ```
+ *
+ * The callback takes the cursor and returns a page, rather than this taking the filters itself,
+ * so the filters stay contextually typed by the endpoint: `status: "in_review"` is checked
+ * against that operation's enum instead of widening to `string`.
+ *
+ * The iterator is lazy. It fetches the next page only when the consumer asks for an item past
+ * the end of the current one, so `break` costs nothing.
+ */
+export async function* paginate(listPage) {
+    let cursor;
+    for (;;) {
+        const page = await listPage(cursor);
+        for (const item of page.data)
+            yield item;
+        const last = page.data.at(-1);
+        // An empty page that still claims there is more would loop forever on the same cursor. The
+        // server does not do that; a proxy answering from a stale cache might.
+        if (!page.has_more || last === undefined)
+            return;
+        // The other way to loop forever is a callback that ignores the cursor it was handed. That
+        // is a mistake in the caller's query, and it is worth saying so rather than paging silently
+        // over page one until the process dies.
+        if (last.id === cursor) {
+            throw new Error(`paginate() was handed the same page twice at ${cursor}. Pass the cursor through to the query as starting_after.`);
+        }
+        cursor = last.id;
+    }
+}

package/dist/retry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The retry ladder.
+ *
+ * It wraps `fetch` rather than sitting in openapi-fetch middleware, because middleware runs once
+ * per call and a retry has to re-issue the request the middleware already finished building:
+ * headers, idempotency key and all. Wrapping the transport means every attempt sends the exact
+ * bytes of the first one, which is the whole reason a replay is safe.
+ */
+export declare const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+export interface RetryingFetchOptions {
+    fetch: typeof globalThis.fetch;
+    /** Attempts after the first. `0` disables retrying. */
+    maxRetries: number;
+    /** Injected by the tests; a ladder measured in real seconds is otherwise untestable. */
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+    now?: () => number;
+}
+/**
+ * `Retry-After` is either a whole number of seconds or an HTTP date. Anything else is ignored
+ * rather than guessed at, and the caller falls back to the backoff ladder.
+ */
+export declare function parseRetryAfter(value: string | null, nowMs: number): number | undefined;
+export declare function createRetryingFetch(options: RetryingFetchOptions): typeof globalThis.fetch;

package/dist/retry.js

@@ -0,0 +1,81 @@
+/**
+ * The retry ladder.
+ *
+ * It wraps `fetch` rather than sitting in openapi-fetch middleware, because middleware runs once
+ * per call and a retry has to re-issue the request the middleware already finished building:
+ * headers, idempotency key and all. Wrapping the transport means every attempt sends the exact
+ * bytes of the first one, which is the whole reason a replay is safe.
+ */
+/** Doubling from here, capped, so three retries cost under four seconds. */
+const BASE_DELAY_MS = 500;
+const MAX_DELAY_MS = 8_000;
+/** A server may name any delay; we will not sit on a socket for longer than this. */
+const MAX_RETRY_AFTER_MS = 60_000;
+/** The writes that need a key before a replay is safe. GET and HEAD are always replayable. */
+const WRITE_METHODS = new Set(["POST", "PATCH", "PUT", "DELETE"]);
+export const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+/**
+ * Retryable statuses: the rate limit, and the server faults that a second attempt can clear.
+ *
+ * 501 is excluded although it is a 5xx. The contract uses it for `live_not_available`, a
+ * permanent answer for the whole of Phase 1, so retrying it would add seconds of backoff to
+ * every live call that was never going to succeed.
+ */
+function isRetryable(status) {
+    return status === 429 || (status >= 500 && status !== 501);
+}
+/**
+ * `Retry-After` is either a whole number of seconds or an HTTP date. Anything else is ignored
+ * rather than guessed at, and the caller falls back to the backoff ladder.
+ */
+export function parseRetryAfter(value, nowMs) {
+    if (value === null)
+        return undefined;
+    const header = value.trim();
+    if (header.length === 0)
+        return undefined;
+    const seconds = /^\d+$/.test(header) ? Number(header) : Number.NaN;
+    const milliseconds = Number.isNaN(seconds) ? Date.parse(header) - nowMs : seconds * 1000;
+    if (Number.isNaN(milliseconds))
+        return undefined;
+    return Math.min(Math.max(milliseconds, 0), MAX_RETRY_AFTER_MS);
+}
+/**
+ * Equal jitter: half the ceiling, plus a random share of the other half. Full jitter can return
+ * a delay of nearly zero, which turns a fleet of clients retrying a 503 back into the stampede
+ * the backoff exists to break up.
+ */
+function backoffMs(attempt, random) {
+    const ceiling = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** attempt);
+    return ceiling / 2 + random() * (ceiling / 2);
+}
+/**
+ * A write without an `Idempotency-Key` must never be retried: the first attempt may have been
+ * applied and answered into a socket that died, and a second one would create a second patient.
+ * The client mints a key for every write, so in practice this refuses only a request that
+ * reached the transport some other way.
+ */
+function mayRetry(request) {
+    if (!WRITE_METHODS.has(request.method.toUpperCase()))
+        return true;
+    return request.headers.has(IDEMPOTENCY_KEY_HEADER);
+}
+export function createRetryingFetch(options) {
+    const { fetch: transport, maxRetries, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), random = Math.random, now = Date.now, } = options;
+    return async (input, init) => {
+        // openapi-fetch always hands the transport a fully built Request; the other shapes are here
+        // so this stays a drop-in `fetch`.
+        const request = input instanceof Request && init === undefined ? input : new Request(input, init);
+        for (let attempt = 0;; attempt += 1) {
+            // A Request body can only be read once, so each attempt gets its own copy.
+            const response = await transport(request.clone());
+            if (attempt >= maxRetries || !isRetryable(response.status) || !mayRetry(request)) {
+                return response;
+            }
+            // Nothing will read this body, and an unread one holds the connection open.
+            await response.body?.cancel().catch(() => undefined);
+            const named = parseRetryAfter(response.headers.get("Retry-After"), now());
+            await sleep(named ?? backoffMs(attempt, random));
+        }
+    };
+}

package/dist/webhooks.d.ts

@@ -0,0 +1,43 @@
+import { type CuvoTypedEvent } from "./events.js";
+/**
+ * Webhook verification, the receiving half of the recipe in api/lib/webhooks/sign.ts:
+ *
+ *   Cuvo-Signature: t=<unix seconds>,v1=<hex hmac_sha256(secret, `${t}.${rawBody}`)>
+ *
+ * Two properties this depends on. The digest covers `t`, so a captured delivery cannot be
+ * replayed under a fresh timestamp; and it covers the RAW body, so the bytes must be verified
+ * before any JSON parse. Read the body as text off the request and pass that string, never
+ * `JSON.stringify(req.body)`. A re-serialization changes key order and whitespace and every
+ * signature fails.
+ *
+ * During the 24 hour grace after a rotation the header carries TWO `v1=` values, the new secret
+ * first. Accepting when ANY of them matches is what lets a receiver move to the new secret
+ * whenever it likes inside that window.
+ */
+/** The contract's replay window, in seconds. */
+export declare const DEFAULT_TOLERANCE_SECONDS = 300;
+export interface VerifySignatureOptions {
+    /** The delivery body as the exact bytes that arrived. */
+    rawBody: string;
+    /** The `Cuvo-Signature` header. A missing header is a failed verification, not a throw. */
+    signatureHeader: string | null | undefined;
+    /** The endpoint's signing secret, `whsec_…`. */
+    secret: string;
+    toleranceSeconds?: number;
+    /** Injected by the tests; a signature over a clock is otherwise untestable. */
+    now?: () => number;
+}
+/**
+ * True when the delivery was signed with this secret, recently. Reject the delivery with a 400
+ * when it is false, and never act on an unverified body.
+ */
+export declare function verifySignature(options: VerifySignatureOptions): boolean;
+/**
+ * Parse a verified delivery body into an event keyed by its `type`, so a handler branching on
+ * `event.type` gets the resource that type carries without a cast.
+ *
+ * Verify first. This does not check the signature, and it does not validate the payload against
+ * the contract; it checks only that the body is the shape an event has, so a proxy's error page
+ * fails here rather than three property accesses later.
+ */
+export declare function parseEvent(rawBody: string): CuvoTypedEvent;

package/dist/webhooks.js

@@ -0,0 +1,78 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { typedEvent } from "./events.js";
+/**
+ * Webhook verification, the receiving half of the recipe in api/lib/webhooks/sign.ts:
+ *
+ *   Cuvo-Signature: t=<unix seconds>,v1=<hex hmac_sha256(secret, `${t}.${rawBody}`)>
+ *
+ * Two properties this depends on. The digest covers `t`, so a captured delivery cannot be
+ * replayed under a fresh timestamp; and it covers the RAW body, so the bytes must be verified
+ * before any JSON parse. Read the body as text off the request and pass that string, never
+ * `JSON.stringify(req.body)`. A re-serialization changes key order and whitespace and every
+ * signature fails.
+ *
+ * During the 24 hour grace after a rotation the header carries TWO `v1=` values, the new secret
+ * first. Accepting when ANY of them matches is what lets a receiver move to the new secret
+ * whenever it likes inside that window.
+ */
+/** The contract's replay window, in seconds. */
+export const DEFAULT_TOLERANCE_SECONDS = 300;
+/** Constant-time hex compare that tolerates a length mismatch instead of throwing on one. */
+function matches(candidate, expected) {
+    const left = Buffer.from(candidate, "utf8");
+    const right = Buffer.from(expected, "utf8");
+    if (left.length !== right.length)
+        return false;
+    return timingSafeEqual(left, right);
+}
+/**
+ * True when the delivery was signed with this secret, recently. Reject the delivery with a 400
+ * when it is false, and never act on an unverified body.
+ */
+export function verifySignature(options) {
+    const { rawBody, signatureHeader, secret, toleranceSeconds = DEFAULT_TOLERANCE_SECONDS, now = Date.now, } = options;
+    if (!signatureHeader)
+        return false;
+    let timestamp;
+    const candidates = [];
+    for (const part of signatureHeader.split(",")) {
+        const separator = part.indexOf("=");
+        if (separator === -1)
+            continue;
+        const key = part.slice(0, separator).trim();
+        const value = part.slice(separator + 1).trim();
+        if (key === "t")
+            timestamp = value;
+        else if (key === "v1")
+            candidates.push(value);
+    }
+    if (timestamp === undefined || candidates.length === 0)
+        return false;
+    if (!/^\d+$/.test(timestamp))
+        return false;
+    const age = Math.abs(now() / 1000 - Number(timestamp));
+    if (age >= toleranceSeconds)
+        return false;
+    const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
+    // Every candidate is compared; the set of signatures on the wire is not a secret, so there is
+    // nothing to leak by the number of comparisons, only by their duration.
+    return candidates.some((candidate) => matches(candidate, expected));
+}
+/**
+ * Parse a verified delivery body into an event keyed by its `type`, so a handler branching on
+ * `event.type` gets the resource that type carries without a cast.
+ *
+ * Verify first. This does not check the signature, and it does not validate the payload against
+ * the contract; it checks only that the body is the shape an event has, so a proxy's error page
+ * fails here rather than three property accesses later.
+ */
+export function parseEvent(rawBody) {
+    const body = JSON.parse(rawBody);
+    const event = body;
+    if (typeof event?.id !== "string" ||
+        typeof event.type !== "string" ||
+        typeof event.resource?.id !== "string") {
+        throw new Error("The body is not a Cuvo event.");
+    }
+    return typedEvent(event);
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@cuvo-health-us/api",
+  "version": "0.1.0-next.0",
+  "type": "module",
+  "description": "TypeScript client for the Cuvo Integrations API, generated from the v1 contract.",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "openapi-fetch": "^0.17.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.16",
+    "@types/node": "^20",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "knip": "^6.15.0",
+    "openapi-typescript": "^7.13.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5",
+    "vitest": "^4.1.10",
+    "yaml": "^2.9.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "generate": "tsx scripts/generate-types.ts",
+    "check:generated": "tsx scripts/generate-types.ts --check",
+    "build": "tsc -p tsconfig.build.json && mkdir -p dist/generated && cp src/generated/v1.d.ts dist/generated/v1.d.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "test": "vitest run",
+    "gates": "pnpm typecheck && pnpm lint && pnpm exec knip && pnpm test && pnpm check:generated"
+  }
+}