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

package/README.md

@@ -0,0 +1,264 @@
+# `@cuvo-health-us/api`
+
+The TypeScript client for the [Cuvo Integrations API](https://developers.cuvo.co): create
+patients, record consents, file cases for a licensed clinician to decide, and follow
+prescriptions and orders through events and webhooks.
+
+Every type in this package is generated from `api/openapi/v1.yaml`, which is itself generated
+from the schemas the server validates with. If it compiles, it speaks the deployed contract.
+
+> Prerelease. Published under the `next` tag while the developer product settles; `0.1.x` may
+> still move.
+
+## Install
+
+```sh
+pnpm add @cuvo-health-us/api@next
+```
+
+Requires Node 20 or newer. `verifySignature` uses `node:crypto`; the client itself runs anywhere
+there is a `fetch`.
+
+## Authenticate
+
+Two credentials reach the same API, and both arrive as `Authorization: Bearer …`.
+
+**An API key** is what one integration uses for its own traffic. Mint it in the developer portal;
+`cuvo_sk_test_…` reaches the sandbox and `cuvo_sk_live_…` reaches production. Never ship a live key
+to a browser.
+
+```ts
+import { createCuvoClient } from "@cuvo-health-us/api";
+
+const cuvo = createCuvoClient({
+  apiKey: process.env.CUVO_API_KEY!,
+  // organization: "org_…",  // only when the credential is granted to more than one
+});
+```
+
+**An OAuth client** is what a platform uses to act for the organizations that granted it access.
+Exchange the client id and secret for a token at
+`https://developers.cuvo.co/api/auth/oauth2/token` with `grant_type=client_credentials`, ask for
+the scopes you need, and hand the access token to the same option. The client id and secret go in
+the `Authorization` header as HTTP Basic credentials, which is the one method a client is
+registered for:
+
+```ts
+const basic = Buffer.from(
+  `${process.env.CUVO_CLIENT_ID}:${process.env.CUVO_CLIENT_SECRET}`,
+).toString("base64");
+
+const response = await fetch("https://developers.cuvo.co/api/auth/oauth2/token", {
+  method: "POST",
+  headers: {
+    "content-type": "application/x-www-form-urlencoded",
+    authorization: `Basic ${basic}`,
+  },
+  body: new URLSearchParams({
+    grant_type: "client_credentials",
+    scope: "patients:write cases:write events:read",
+    resource: "https://api.cuvo.co",
+  }),
+});
+const { access_token } = (await response.json()) as { access_token: string };
+
+const cuvo = createCuvoClient({ apiKey: access_token, organization: "org_…" });
+```
+
+`resource` is not optional. It is what the provider reads to set the token's audience, and the API
+refuses a token whose audience does not name it, so an exchange without it mints a token that fails
+on the first call.
+
+Scopes are per credential and are intersected with what the organization granted: a key with
+`cases:write` acting for an organization that granted only `cases:read` may read and nothing more.
+Tokens are short lived, so mint one per run rather than caching it past its expiry.
+
+`Cuvo-Organization` names the organization you are acting for. It is required whenever the
+credential holds more than one grant, and the client sends it on every call once you name it.
+
+The client adds three things to every call, which is most of why it exists:
+
+- `Authorization: Bearer <key>`, and `Cuvo-Organization` when you named one.
+- An `Idempotency-Key` on every POST, PATCH and DELETE. Pass your own to make a retry from your
+  own job queue replay instead of creating a second row.
+- Retries on 429 and on the server faults a second attempt can clear, with exponential backoff,
+  jitter, and `Retry-After` when the server names a delay. A write with no idempotency key is
+  never retried.
+
+## File a case
+
+```ts
+import { createCuvoClient, unwrap } from "@cuvo-health-us/api";
+
+const cuvo = createCuvoClient({ apiKey: process.env.CUVO_API_KEY! });
+
+const patient = unwrap(
+  await cuvo.POST("/v1/patients", {
+    body: {
+      first_name: "Ada",
+      last_name: "Lovelace",
+      date_of_birth: "1990-04-14",
+      sex_at_birth: "female",
+      email: "ada@example.com",
+      phone: "+14155550123",
+      address: {
+        line1: "1 Market St",
+        city: "San Francisco",
+        state: "CA",
+        postal_code: "94105",
+      },
+    },
+  }),
+);
+
+// A case needs the consents the patient gave before it can be filed.
+const consents = await Promise.all(
+  (["telehealth", "privacy"] as const).map(async (kind) =>
+    unwrap(
+      await cuvo.POST("/v1/patients/{id}/consents", {
+        params: { path: { id: patient.id } },
+        body: { kind, version: "2026-01" },
+      }),
+    ),
+  ),
+);
+
+const filed = unwrap(
+  await cuvo.POST("/v1/cases", {
+    body: {
+      patient: patient.id,
+      requested_medications: [
+        {
+          medication_id: "med_sema_0_25",
+          quantity: 4,
+          refills: 0,
+          days_supply: 28,
+          directions: "Inject 0.25 mg subcutaneously once weekly.",
+        },
+      ],
+      answers: [
+        { id: "q_pregnant", question: "Are you pregnant?", answer: false, type: "boolean" },
+      ],
+      consent_ids: consents.map((consent) => consent.id),
+      hold: false,
+    },
+  }),
+);
+
+console.log(filed.id, filed.status); // case_… queued
+```
+
+`unwrap` turns a failure into a thrown `CuvoApiError` carrying `status`, `code`, `issues` and
+`requestId`. Drop it and use the generated `{ data, error }` pair instead when you would rather
+branch than catch.
+
+## Page through a list
+
+```ts
+import { paginate, unwrap } from "@cuvo-health-us/api";
+
+const inReview = paginate(async (starting_after) =>
+  unwrap(
+    await cuvo.GET("/v1/cases", {
+      params: { query: { limit: 100, status: "in_review", starting_after } },
+    }),
+  ),
+);
+
+for await (const item of inReview) {
+  console.log(item.id, item.status);
+}
+```
+
+The iterator is lazy and follows `starting_after` until the API says there is no more. Pass the
+cursor into your own query rather than handing the filters over, so `status` stays checked
+against that endpoint's enum instead of widening to `string`.
+
+## Receive a webhook
+
+Verify before you parse, and verify the raw bytes. Re-serializing the body changes key order and
+every signature fails.
+
+```ts
+import { expandEvent, parseEvent, verifySignature } from "@cuvo-health-us/api";
+
+export async function POST(request: Request) {
+  const rawBody = await request.text();
+
+  const verified = verifySignature({
+    rawBody,
+    signatureHeader: request.headers.get("Cuvo-Signature"),
+    secret: process.env.CUVO_WEBHOOK_SECRET!,
+  });
+  if (!verified) return new Response("bad signature", { status: 400 });
+
+  const event = parseEvent(rawBody);
+
+  // Delivery is at-least-once: dedupe on event.id before you act.
+  if (await alreadyHandled(event.id)) return new Response(null, { status: 200 });
+
+  if (event.type === "case.approved.v1") {
+    // Events are thin. This returns the embedded resource when the endpoint opted into
+    // include_resource, and reads it back otherwise.
+    const approved = await expandEvent(cuvo, event);
+    console.log(approved);
+  }
+
+  return new Response(null, { status: 200 });
+}
+```
+
+During the 24 hour grace after a secret rotation a delivery carries two signatures.
+`verifySignature` accepts a match against either, so you can move to the new secret whenever you
+like inside the window.
+
+`parseEvent` returns the event keyed by its `type`, so the branch above knows `event.data` is a
+`Case` and `expandEvent` answers with one. An event read from `GET /v1/events` arrives as the
+contract's single `Event` shape instead, because that is what one schema for the whole catalog
+can say; pass it through `typedEvent` for the same narrowing:
+
+```ts
+import { paginate, typedEvent, unwrap } from "@cuvo-health-us/api";
+
+for await (const row of paginate(async (starting_after) =>
+  unwrap(await cuvo.GET("/v1/events", { params: { query: { since, starting_after } } })),
+)) {
+  const event = typedEvent(row);
+  if (event.type === "order.shipped.v1") console.log(event.resource.id);
+}
+```
+
+`typedEvent` also refuses a body that pairs an event type with the wrong resource, which no
+delivery from Cuvo does.
+
+`expandEvent` returns `undefined` for messages, prescriptions, consents and charges: v1 reads
+those through their case or patient rather than on their own id. Turn on `include_resource` on the
+endpoint, or pass `include_resource: true` to `GET /v1/events`, and the resource arrives embedded
+as `data` with no second call.
+
+## Development
+
+```sh
+pnpm install
+pnpm generate         # rewrite src/generated/v1.d.ts from api/openapi/v1.yaml
+pnpm check:generated  # fail if the committed types no longer match the contract
+pnpm gates            # typecheck, lint, dead code, tests, drift
+pnpm build            # compile src to dist, the published shape
+```
+
+`src/generated/v1.d.ts` is committed and never edited by hand. `pnpm build` compiles everything
+but the tests into `dist` and copies that declaration file beside the output, because a
+declaration-only input produces no emit of its own.
+
+## Publishing
+
+The package publishes from `dist`, under the `next` tag, at the prerelease version in
+`package.json`. `pnpm pack` builds the tarball without sending anything.
+
+```sh
+pnpm pack                 # inspect the tarball first
+npm publish --tag next    # requires an npm login with access to the @cuvo scope
+```
+
+Nothing goes out under `latest` until the contract is stable and the founder says so: a stable tag
+is what a partner's `pnpm add @cuvo-health-us/api` resolves to by default.

package/dist/client.d.ts

@@ -0,0 +1,31 @@
+import { type Client } from "openapi-fetch";
+import type { paths } from "./generated/v1.js";
+/** The public API. Test and live mode are selected by the key, not by the host. */
+export declare const DEFAULT_BASE_URL = "https://api.cuvo.co";
+export declare const DEFAULT_MAX_RETRIES = 3;
+export interface CuvoClientOptions {
+    /**
+     * `cuvo_sk_test_…`, `cuvo_sk_live_…`, or an OAuth access token: the API takes all three as the
+     * same bearer, so `@cuvo-health-us/cli` passes the token it was issued straight into this option. Never
+     * ship a live key to a browser.
+     */
+    apiKey: string;
+    baseUrl?: string;
+    /** Required when the credential holds a grant to more than one organization. */
+    organization?: string;
+    /** Swap the transport, for a proxy, a test double, or a runtime without a global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Attempts after the first, on 429 and retryable 5xx. `0` disables retrying. */
+    maxRetries?: number;
+}
+/** The generated client: one method per HTTP verb, typed by path from the v1 contract. */
+export type CuvoClient = Client<paths>;
+/**
+ * Build a client for one credential.
+ *
+ * ```ts
+ * const cuvo = createCuvoClient({ apiKey: process.env.CUVO_API_KEY! });
+ * const { data, error } = await cuvo.POST("/v1/patients", { body: patient });
+ * ```
+ */
+export declare function createCuvoClient(options: CuvoClientOptions): CuvoClient;

package/dist/client.js

@@ -0,0 +1,50 @@
+import createClient, {} from "openapi-fetch";
+import { createRetryingFetch, IDEMPOTENCY_KEY_HEADER } from "./retry.js";
+/** The public API. Test and live mode are selected by the key, not by the host. */
+export const DEFAULT_BASE_URL = "https://api.cuvo.co";
+export const DEFAULT_MAX_RETRIES = 3;
+/** The methods the contract requires an `Idempotency-Key` on. */
+const WRITE_METHODS = new Set(["POST", "PATCH", "DELETE"]);
+/**
+ * Authorization, the acting organization, and an idempotency key for every write.
+ *
+ * The key matters most. The contract requires one on every POST, PATCH and DELETE, and a caller
+ * who has to invent one per call will eventually reuse a constant and turn every create after
+ * the first into a replay. A caller who wants their own key still wins: this only fills a gap.
+ */
+function cuvoHeaders(apiKey, organization) {
+    return {
+        onRequest({ request }) {
+            request.headers.set("Authorization", `Bearer ${apiKey}`);
+            if (organization !== undefined)
+                request.headers.set("Cuvo-Organization", organization);
+            if (WRITE_METHODS.has(request.method.toUpperCase()) &&
+                !request.headers.has(IDEMPOTENCY_KEY_HEADER)) {
+                request.headers.set(IDEMPOTENCY_KEY_HEADER, globalThis.crypto.randomUUID());
+            }
+            return request;
+        },
+    };
+}
+/**
+ * Build a client for one credential.
+ *
+ * ```ts
+ * const cuvo = createCuvoClient({ apiKey: process.env.CUVO_API_KEY! });
+ * const { data, error } = await cuvo.POST("/v1/patients", { body: patient });
+ * ```
+ */
+export function createCuvoClient(options) {
+    const { apiKey, baseUrl = DEFAULT_BASE_URL, organization, maxRetries = DEFAULT_MAX_RETRIES, } = options;
+    if (apiKey.length === 0)
+        throw new Error("createCuvoClient needs an API key.");
+    const client = createClient({
+        baseUrl,
+        fetch: createRetryingFetch({
+            fetch: options.fetch ?? globalThis.fetch,
+            maxRetries,
+        }),
+    });
+    client.use(cuvoHeaders(apiKey, organization));
+    return client;
+}

package/dist/errors.d.ts

@@ -0,0 +1,34 @@
+import type { components } from "./generated/v1.js";
+/** RFC 9457 problem details, the one error body every endpoint answers with. */
+export type Problem = components["schemas"]["Problem"];
+/** One validation failure, addressed by the dotted path of the field that produced it. */
+export type ProblemIssue = NonNullable<Problem["issues"]>[number];
+/**
+ * A request the API refused, or an answer it could not have sent.
+ *
+ * `code` is the stable machine string to branch on; `message` is the problem's `detail`, which
+ * the contract guarantees is safe to show an end user. `problem` carries the body verbatim for
+ * the RFC's `type` and `title`, which nothing branches on but a bug report wants.
+ */
+export declare class CuvoApiError extends Error {
+    /** The stable machine string, for example `case_not_found` or `idempotency_key_reused`. */
+    readonly code: string;
+    readonly status: number;
+    /** Present on a 400: the fields that failed validation. Empty on every other status. */
+    readonly issues: readonly ProblemIssue[];
+    /** The server's id for this request. Quote it in a support ticket. */
+    readonly requestId: string | undefined;
+    readonly problem: Problem;
+    constructor(problem: Problem);
+}
+/**
+ * Turn openapi-fetch's `{ data, error }` into a value or a throw.
+ *
+ * The generated client returns errors rather than throwing, which is right for a caller that
+ * wants to branch on both. Everything inside this SDK, and most callers, want the throwing form.
+ */
+export declare function unwrap<Data>(result: {
+    data?: Data;
+    error?: unknown;
+    response: Response;
+}): Data;

package/dist/errors.js

@@ -0,0 +1,59 @@
+/**
+ * A request the API refused, or an answer it could not have sent.
+ *
+ * `code` is the stable machine string to branch on; `message` is the problem's `detail`, which
+ * the contract guarantees is safe to show an end user. `problem` carries the body verbatim for
+ * the RFC's `type` and `title`, which nothing branches on but a bug report wants.
+ */
+export class CuvoApiError extends Error {
+    /** The stable machine string, for example `case_not_found` or `idempotency_key_reused`. */
+    code;
+    status;
+    /** Present on a 400: the fields that failed validation. Empty on every other status. */
+    issues;
+    /** The server's id for this request. Quote it in a support ticket. */
+    requestId;
+    problem;
+    constructor(problem) {
+        super(problem.detail);
+        this.name = "CuvoApiError";
+        this.code = problem.code;
+        this.status = problem.status;
+        this.issues = problem.issues ?? [];
+        this.requestId = problem.request_id;
+        this.problem = problem;
+    }
+}
+/**
+ * Coerce whatever came back into problem details. A gateway between the caller and the API can
+ * answer with HTML or nothing at all, and an SDK that throws `undefined.code` on a 502 is worse
+ * than useless during exactly the incident it should be explaining.
+ */
+function toProblem(status, body) {
+    const candidate = body;
+    if (candidate && typeof candidate.code === "string" && typeof candidate.detail === "string") {
+        return { ...candidate, status: candidate.status ?? status };
+    }
+    return {
+        type: "about:blank",
+        title: "Unexpected response",
+        status,
+        code: "unexpected_response",
+        detail: `The API answered ${status} with a body that is not problem details.`,
+    };
+}
+/**
+ * Turn openapi-fetch's `{ data, error }` into a value or a throw.
+ *
+ * The generated client returns errors rather than throwing, which is right for a caller that
+ * wants to branch on both. Everything inside this SDK, and most callers, want the throwing form.
+ */
+export function unwrap(result) {
+    if (result.error !== undefined) {
+        throw new CuvoApiError(toProblem(result.response.status, result.error));
+    }
+    if (result.data === undefined) {
+        throw new CuvoApiError(toProblem(result.response.status, undefined));
+    }
+    return result.data;
+}

package/dist/events.d.ts

@@ -0,0 +1,126 @@
+import type { CuvoClient } from "./client.js";
+import type { components } from "./generated/v1.js";
+/**
+ * An event: what happened, to which resource, and the status that resource is in now. This is
+ * the body of every webhook delivery and every row of `GET /v1/events`.
+ *
+ * This is the contract's own shape, where `data` is `unknown` because one schema describes every
+ * event in the catalog. `CuvoTypedEvent` below is the same thing keyed by `type`, which is what a
+ * handler wants.
+ */
+export type CuvoEvent = components["schemas"]["Event"];
+/** The catalog, for example `case.approved.v1`. Versioned, so a payload change is a new type. */
+export type CuvoEventType = CuvoEvent["type"];
+export type CuvoEventResourceType = CuvoEvent["resource"]["type"];
+/**
+ * THE TABLE: which resource each event in the catalog is about.
+ *
+ * It mirrors `RESOURCE_OF` in api/lib/events/clinical-refs.ts, and for the same reason: the
+ * prefix of an event name is USUALLY its resource, and `case.message_created.v1` is the one
+ * where it is not. The fact is about a message; the case it belongs to rides in the payload.
+ *
+ * `satisfies Record<CuvoEventType, …>` is the gate. An event type added to the contract, or one
+ * renamed, fails to compile here until this table names its resource, which is what keeps
+ * `CuvoTypedEvent` honest without a second source of truth.
+ */
+declare const RESOURCE_OF: {
+    readonly "patient.created.v1": "patient";
+    readonly "patient.updated.v1": "patient";
+    readonly "patient.deleted.v1": "patient";
+    readonly "case.received.v1": "case";
+    readonly "case.queued.v1": "case";
+    readonly "case.in_review.v1": "case";
+    readonly "case.waiting_on_patient.v1": "case";
+    readonly "case.waiting_on_integration.v1": "case";
+    readonly "case.approved.v1": "case";
+    readonly "case.declined.v1": "case";
+    readonly "case.cancelled.v1": "case";
+    readonly "case.withdrawn.v1": "case";
+    readonly "case.question_asked.v1": "case";
+    readonly "case.message_created.v1": "message";
+    readonly "prescription.created.v1": "prescription";
+    readonly "prescription.updated.v1": "prescription";
+    readonly "order.created.v1": "order";
+    readonly "order.at_pharmacy.v1": "order";
+    readonly "order.shipped.v1": "order";
+    readonly "order.delivered.v1": "order";
+    readonly "order.blocked.v1": "order";
+    readonly "order.failed.v1": "order";
+    readonly "consent.recorded.v1": "consent";
+    readonly "file.attached.v1": "file";
+    readonly "charge.created.v1": "charge";
+    readonly "webhook_endpoint.disabled.v1": "webhook_endpoint";
+};
+/** The resource type `T` is about, at the type level: `"case.approved.v1"` is a `"case"`. */
+export type CuvoEventResourceTypeOf<T extends CuvoEventType> = (typeof RESOURCE_OF)[T];
+/**
+ * Each resource type as the API returns it.
+ *
+ * `charge` is `never`: v1 publishes no charge DTO, so nothing the contract describes can be
+ * embedded in a charge event or read back for one. Saying `unknown` there would swallow every
+ * other member of the union at the first `|`.
+ */
+interface ResourceDtos {
+    patient: components["schemas"]["Patient"];
+    case: components["schemas"]["Case"];
+    message: components["schemas"]["Message"];
+    prescription: components["schemas"]["Prescription"];
+    order: components["schemas"]["Order"];
+    consent: components["schemas"]["Consent"];
+    file: components["schemas"]["File"];
+    charge: never;
+    webhook_endpoint: components["schemas"]["WebhookEndpoint"];
+}
+/** The resource DTO an event of type `T` carries and points at. */
+export type CuvoEventResourceOf<T extends CuvoEventType> = ResourceDtos[CuvoEventResourceTypeOf<T>];
+/** Every resource an event can point at, as the API returns it. */
+export type ExpandedResource = ResourceDtos[CuvoEventResourceType];
+/** One event of the catalog, with its resource type and its embedded resource both pinned. */
+export type CuvoEventOf<T extends CuvoEventType> = Omit<CuvoEvent, "type" | "resource" | "data"> & {
+    type: T;
+    resource: {
+        type: CuvoEventResourceTypeOf<T>;
+        id: string;
+    };
+    /** Present when the endpoint opted into `include_resource`, absent otherwise. */
+    data?: CuvoEventResourceOf<T>;
+};
+/**
+ * The catalog as a union discriminated by `type`.
+ *
+ * ```ts
+ * if (event.type === "case.approved.v1") {
+ *   event.data?.decided_at; // a Case, checked. No cast, no second lookup table.
+ * }
+ * ```
+ */
+export type CuvoTypedEvent = {
+    [T in CuvoEventType]: CuvoEventOf<T>;
+}[CuvoEventType];
+/**
+ * Key an event by its `type`, checking the one thing the type system cannot see: that the
+ * resource the body names is the resource that event type is about.
+ *
+ * `parseEvent` runs this over every webhook body. Call it on an event read from
+ * `GET /v1/events`, whose generated type is the contract's single `Event` shape, to get the same
+ * narrowing there. A body that pairs a type with the wrong resource did not come from Cuvo, and
+ * a cast that assumed otherwise would hand a handler a `Case` that is really a `Message`.
+ */
+export declare function typedEvent(event: CuvoEvent): CuvoTypedEvent;
+/**
+ * Fetch the resource an event is about.
+ *
+ * Events are thin on purpose: ids, type, status, timestamps. An endpoint that opted into
+ * `include_resource` already carries the resource as `data`, and this returns that without a
+ * round trip. Otherwise it reads the resource back.
+ *
+ * The return type follows the event: hand it a `case.approved.v1` and you get a `Case`, with no
+ * second narrowing at the call site.
+ *
+ * `undefined` means the v1 contract has no read addressed by that id alone: messages,
+ * prescriptions and consents are listed through their case or patient, and charges have no
+ * public read until billing ships. Turn on `include_resource` for endpoints that need those, or
+ * read the parent case. The return type says `| undefined` so this cannot be forgotten.
+ */
+export declare function expandEvent<T extends CuvoEventType>(client: CuvoClient, event: CuvoEventOf<T>): Promise<CuvoEventResourceOf<T> | undefined>;
+export {};

package/dist/events.js

@@ -0,0 +1,100 @@
+import { unwrap } from "./errors.js";
+/**
+ * THE TABLE: which resource each event in the catalog is about.
+ *
+ * It mirrors `RESOURCE_OF` in api/lib/events/clinical-refs.ts, and for the same reason: the
+ * prefix of an event name is USUALLY its resource, and `case.message_created.v1` is the one
+ * where it is not. The fact is about a message; the case it belongs to rides in the payload.
+ *
+ * `satisfies Record<CuvoEventType, …>` is the gate. An event type added to the contract, or one
+ * renamed, fails to compile here until this table names its resource, which is what keeps
+ * `CuvoTypedEvent` honest without a second source of truth.
+ */
+const RESOURCE_OF = {
+    "patient.created.v1": "patient",
+    "patient.updated.v1": "patient",
+    "patient.deleted.v1": "patient",
+    "case.received.v1": "case",
+    "case.queued.v1": "case",
+    "case.in_review.v1": "case",
+    "case.waiting_on_patient.v1": "case",
+    "case.waiting_on_integration.v1": "case",
+    "case.approved.v1": "case",
+    "case.declined.v1": "case",
+    "case.cancelled.v1": "case",
+    "case.withdrawn.v1": "case",
+    "case.question_asked.v1": "case",
+    "case.message_created.v1": "message",
+    "prescription.created.v1": "prescription",
+    "prescription.updated.v1": "prescription",
+    "order.created.v1": "order",
+    "order.at_pharmacy.v1": "order",
+    "order.shipped.v1": "order",
+    "order.delivered.v1": "order",
+    "order.blocked.v1": "order",
+    "order.failed.v1": "order",
+    "consent.recorded.v1": "consent",
+    "file.attached.v1": "file",
+    "charge.created.v1": "charge",
+    "webhook_endpoint.disabled.v1": "webhook_endpoint",
+};
+/**
+ * Key an event by its `type`, checking the one thing the type system cannot see: that the
+ * resource the body names is the resource that event type is about.
+ *
+ * `parseEvent` runs this over every webhook body. Call it on an event read from
+ * `GET /v1/events`, whose generated type is the contract's single `Event` shape, to get the same
+ * narrowing there. A body that pairs a type with the wrong resource did not come from Cuvo, and
+ * a cast that assumed otherwise would hand a handler a `Case` that is really a `Message`.
+ */
+export function typedEvent(event) {
+    const expected = RESOURCE_OF[event.type];
+    if (expected === undefined) {
+        throw new Error(`${event.type} is not an event type this version of the SDK knows.`);
+    }
+    if (event.resource.type !== expected) {
+        throw new Error(`${event.type} is an event about a ${expected}, but this one names a ${event.resource.type}.`);
+    }
+    return event;
+}
+/**
+ * Fetch the resource an event is about.
+ *
+ * Events are thin on purpose: ids, type, status, timestamps. An endpoint that opted into
+ * `include_resource` already carries the resource as `data`, and this returns that without a
+ * round trip. Otherwise it reads the resource back.
+ *
+ * The return type follows the event: hand it a `case.approved.v1` and you get a `Case`, with no
+ * second narrowing at the call site.
+ *
+ * `undefined` means the v1 contract has no read addressed by that id alone: messages,
+ * prescriptions and consents are listed through their case or patient, and charges have no
+ * public read until billing ships. Turn on `include_resource` for endpoints that need those, or
+ * read the parent case. The return type says `| undefined` so this cannot be forgotten.
+ */
+export async function expandEvent(client, event) {
+    if (event.data !== undefined)
+        return event.data;
+    const params = { path: { id: event.resource.id } };
+    // The read is chosen by the resource the event names, and `RESOURCE_OF` has already tied that
+    // to `T`. The generated client types each path's answer independently, so the assignment back
+    // to `CuvoEventResourceOf<T>` is the one place this file asserts what the table proved.
+    const resourceType = event.resource.type;
+    const resource = await (async () => {
+        switch (resourceType) {
+            case "patient":
+                return unwrap(await client.GET("/v1/patients/{id}", { params }));
+            case "case":
+                return unwrap(await client.GET("/v1/cases/{id}", { params }));
+            case "order":
+                return unwrap(await client.GET("/v1/orders/{id}", { params }));
+            case "file":
+                return unwrap(await client.GET("/v1/files/{id}", { params }));
+            case "webhook_endpoint":
+                return unwrap(await client.GET("/v1/webhook_endpoints/{id}", { params }));
+            default:
+                return undefined;
+        }
+    })();
+    return resource;
+}