@north-light/comms 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,258 @@
-# Temporary Holding Version
+# @north-light/comms
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Texting for your app. People text your app's phone number (an iMessage line under your app's name and avatar), Comms delivers each text to your server as a signed webhook, and your server answers through one HTTPS send API. This package is everything on your side of that line:
+
+- a typed client for the send API (`CommsClient`),
+- webhook verification (`verifyWebhook`),
+- a local fake Comms for building without an account (`comms fake`),
+- optional helpers: signup, an agent bridge, batching, typing and reply formatting.
+
+It has no runtime dependencies. Node 22 or later.
+
+## Install
+
+```sh
+npm install @north-light/comms
+```
+
+The agent bridge (`continueInRuntime`) drives a run in the person's runtime through `@north-light/sdk`, an optional peer dependency. Install it only if you use that helper:
+
+```sh
+npm install @north-light/sdk@0.3.457
+```
+
+## Build in fake mode
+
+You need no approval, no account setup and no network to start. `comms fake` runs a local Comms that serves the send API's paths and bodies, keeps contacts in memory with fictional `+1555…` numbers, logs every send and reaction to its stdout, and delivers webhooks to your server signed with a secret it prints.
+
+```sh
+npx @north-light/comms fake --webhook http://localhost:3000/hook
+```
+
+```
+comms fake [--port 7481] --webhook <url> [--secret whsec_…]
+```
+
+- `--port` the fake's port. Default `7481`.
+- `--webhook` where the fake delivers events. Required.
+- `--secret` the signing secret. Without it the fake generates one and prints it; copy it into your app.
+
+Simulate a person texting your app, from a second terminal:
+
+```sh
+npx @north-light/comms fake send --from +15550001 --text "hi" [--port 7481]
+```
+
+Your server receives a signed `message.received` with `contact.user` set to `null` (the sender is not a user of your app yet). `STOP`, `START` and `HELP` behave as they do in production: after `STOP`, a send to that contact answers `403 opted_out`.
+
+Point the client at the fake. It accepts any bearer token and ignores `environment`:
+
+```ts
+import { CommsClient } from "@north-light/comms";
+
+const comms = new CommsClient({
+  baseUrl: "http://localhost:7481",
+  token: "fake",
+});
+```
+
+The fake only calls the network to reach your webhook URL.
+
+## Receive texts: verify webhooks
+
+Every delivery carries the headers `webhook-id`, `webhook-timestamp` and `webhook-signature`, following [Standard Webhooks](https://www.standardwebhooks.com/). Verify the **raw** request body, exactly as it arrived, before you parse or act on it:
+
+```ts
+import express from "express";
+import { verifyWebhook, WebhookVerificationError } from "@north-light/comms";
+
+const SECRETS = [process.env.COMMS_WEBHOOK_SECRET!]; // whsec_…, one per environment
+const seen = new Set<string>(); // use a database in production
+
+express()
+  .post(
+    "/hook",
+    express.raw({ type: "application/json" }),
+    async (req, res) => {
+      let event;
+      try {
+        event = verifyWebhook(req.headers, req.body, SECRETS);
+      } catch (error) {
+        if (error instanceof WebhookVerificationError)
+          return void res.sendStatus(401);
+        throw error;
+      }
+      res.sendStatus(200); // acknowledge within 15 seconds
+      if (seen.has(event.id)) return; // deliveries are at least once
+      seen.add(event.id);
+      // …handle event
+    },
+  )
+  .listen(3000);
+```
+
+- `verifyWebhook(headers, rawBody, secrets)` returns the parsed, typed `WebhookEvent` or throws `WebhookVerificationError` (its `code` says which check failed). It refuses timestamps more than 5 minutes off.
+- Pass every secret you still trust. When you rotate a secret, Comms signs each delivery with both the old and the new secret for 24 hours, so listing both keeps deliveries verifying through the change.
+- Respond `2xx` within 15 seconds to acknowledge. Anything else is retried with exponential backoff for 24 hours, then the event is marked failed.
+- Deduplicate on `event.id`. Order is not guaranteed.
+
+Events: `message.received`, `message.status`, `contact.opted_out`, `contact.opted_in`, `contact.user_linked`, `contact.deleted` (the types are exported).
+
+## Reply: the send API
+
+```ts
+await comms.sendMessage({
+  environment: "test",
+  to: { contact_id: event.data.contact.id },
+  text: "Got it!",
+  idempotency_key: `reply:${event.id}`,
+});
+```
+
+- Address a person by `contact_id` or `user_id`, never by raw phone number.
+- You can text only a contact who texted your number first in that environment and has not sent STOP. Otherwise the call fails with a `CommsError` whose `code` is `not_texted_first` or `opted_out`.
+- The same `idempotency_key` returns the first answer and sends nothing, so retrying is safe. Derive it from the event you are answering.
+- `sendReaction`, `getMessage`, `getContact`, `setTyping`, `createSignInLink` and `getPublicNumber` complete the API. Delivery results arrive later as `message.status` events; a failure carries Photon's code in `reason`.
+
+## Environments
+
+|              | Fake                           | Test                                                    | Production                                                     |
+| ------------ | ------------------------------ | ------------------------------------------------------- | -------------------------------------------------------------- |
+| Where        | `comms fake` on your machine   | Comms, a free shared-pool line                          | Comms, your app's own dedicated numbers                        |
+| Needs        | Nothing                        | An approved request and a provisioned test line         | An approved request and a working card on your billing account |
+| Numbers      | Fictional `+1555…`             | Each tester texts a pool number that differs per tester | Your app's numbers                                             |
+| Who can text | You, through `comms fake send` | Up to 10 testers you add                                | Anyone                                                         |
+| Sends        | Logged, never delivered        | Real texts, to testers who texted first                 | Real texts                                                     |
+
+Each environment has its own webhook URL, signing secret, contacts and STOP state. Every send-API call names its environment (`"test"` or `"production"`); the fake ignores the field. Until an environment is set up, calls for it answer `409 environment_not_ready`.
+
+To call a real Comms, authenticate with your app's own key:
+
+```ts
+const comms = new CommsClient({
+  baseUrl: "https://comms.northlight.ai",
+  issuer: "https://account.northlight.ai",
+  clientId: "your-app-id",
+  privateKeyJwk: JSON.parse(process.env.COMMS_PRIVATE_JWK!),
+});
+```
+
+The client mints a short-lived token for you and renews it before it expires.
+
+## Helpers
+
+All optional; none is needed to use the client.
+
+### Sign-up
+
+A person who texts your app may not have an account yet (`contact.user === null`). `sendSignInLink` creates the link and texts it:
+
+```ts
+import { sendSignInLink, onUserLinked } from "@north-light/comms";
+
+await sendSignInLink(comms, event.data.contact, {
+  environment: event.environment,
+});
+// default text: "Tap to finish signing up: {url}"
+
+const handle = onUserLinked(async ({ contact_id, user }) => {
+  // the person tapped the link and now has an account: store contact_id ↔ user.id
+});
+await handle(event); // call with every verified event
+```
+
+The link page and the pages after it carry your app's name and logo. `sendSignInLink` throws a `CommsError` for `already_user`, `no_phone` (an email handle) and `opted_out`. Options: `text` (must contain `{url}`), `returnTo` (must be on your app's host), `idempotencyKey`.
+
+### Agent bridge
+
+`continueInRuntime` starts a run in the person's runtime for their first text and continues it for later ones, under your app's own grant:
+
+```ts
+import { continueInRuntime } from "@north-light/comms";
+
+const { runId, reply } = await continueInRuntime({
+  runtimeUrl, // the person's runtime, from their grant
+  appToken, // your app's token for it, or a function returning a fresh one
+  message: text,
+  runId: savedRunId, // omit for the first text
+  idempotencyKey: event.id,
+});
+const { text: answer } = await reply.collect();
+```
+
+It uses `@north-light/sdk` (`runs.start` with a first `message`, `runs.message`, then `runs.reply`). Pass `client` instead of `runtimeUrl` and `appToken` to use a client you already hold.
+
+### Batching
+
+People send several texts in a row. A batcher joins one contact's texts that arrive within a window (default 2 seconds, closing after at most 30 seconds) and hands them over together:
+
+```ts
+import { createBatcher } from "@north-light/comms";
+
+const batcher = createBatcher<string>({
+  onBatch: async (contactId, texts) => {
+    /* one agent turn for texts.join("\n") */
+  },
+  onError: (error) => console.error(error),
+});
+batcher.add(contact.id, text);
+```
+
+Batches for one contact never overlap. Call `await batcher.flushAll()` on shutdown.
+
+### Typing
+
+```ts
+import { withTyping } from "@north-light/comms";
+
+const answer = await withTyping(comms, contact.id, { environment }, () =>
+  runAgent(text),
+);
+```
+
+The indicator is renewed every 5 seconds while the work runs and switched off when it ends. A failed typing call goes to `onError` and never fails the work. `keepTyping` returns the stop function if you need manual control.
+
+### Formatting and mapping
+
+Agents write markdown; a text message is plain.
+
+```ts
+import {
+  formatReply,
+  tapbackEmoji,
+  replyTo,
+  describeReceived,
+} from "@north-light/comms";
+
+for (const part of formatReply(agentMarkdown)) {
+  await comms.sendMessage({
+    environment,
+    to: { contact_id: contact.id },
+    text: part,
+    ...replyTo(event.data), // thread under the message you are answering
+    idempotency_key: `reply:${event.id}:${part.length}`,
+  });
+}
+await comms.sendReaction(event.data.message_id, {
+  environment,
+  reaction: tapbackEmoji("love"),
+  idempotency_key: `react:${event.id}`,
+});
+```
+
+- `formatReply` strips markdown to plain text (links become `label (url)`) and splits anything over the 10,000-character limit.
+- `tapbackEmoji` / `tapbackName` map `love`, `like`, `dislike`, `laugh`, `emphasize`, `question` to the six iMessage tapbacks.
+- `describeReceived` turns a received text, reaction or attachment (and a threaded reply) into one line an agent can read.
+
+## Keeping your line healthy
+
+Comms enforces who may be texted. Photon's limits on the lines themselves are yours to respect, and ignoring them mostly risks your own numbers. Good practice:
+
+- Let the person text first. Texting first is what permits you to text them, and your numbers fare best when the conversation starts with them.
+- Offer your contact card after the first exchange, not in the first message.
+- Keep follow-ups to two or three, spread over days.
+- Do not send at night.
+- Do not send bursts, and do not pace sends per second beyond what Photon enforces.
+- Keep the first reply free of links and media.
+- Photon rejects sends past its limits (5,000 sends per day per server, 50 new conversations per line per day, per-recipient and send/receive-ratio limits) and Comms passes the rejection to you as `message.status` `failed` with Photon's code (`dailyLimitExceeded`, `recipientLimitExceeded`, `sendReceiveRatioExceeded`). Treat those as a signal to slow down, not a retry.
+- A line is comfortable at about 400 to 500 people for moderate use, and 200 to 400 for heavy use. Photon adds lines as they fill and routes new people to the best one; publish your number with `comms.getPublicNumber()`, for example as an `sms:` link.

package/bin/comms.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { run, UsageError } from "../dist/fake/cli.js";
+
+try {
+  const server = await run(process.argv.slice(2), {
+    out: (line) => console.log(line),
+  });
+  if (server) {
+    const stop = () => void server.close().then(() => process.exit(0));
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+  }
+} catch (error) {
+  if (!(error instanceof UsageError)) throw error;
+  console.error(error.message);
+  process.exitCode = 2;
+}

package/dist/client.d.ts

@@ -0,0 +1,73 @@
+import type { Contact, CommsErrorCode, Environment, MessageRecord, PublicNumber, QueuedMessage, SendMessageRequest, SendReactionRequest, SignInLink, SignInLinkRequest, TypingRequest } from "./types.js";
+/** The `resource` that selects the Comms audience when minting a directory token. */
+export declare const DEFAULT_RESOURCE = "https://comms.northlight.ai";
+/** A private ES256 (P-256) JWK, as registered with the directory. */
+export interface PrivateKeyJwk {
+    kty: "EC";
+    crv: "P-256";
+    x: string;
+    y: string;
+    d: string;
+    kid?: string;
+    alg?: string;
+    [member: string]: unknown;
+}
+export interface CommsClientOptions {
+    /** Comms' base URL, for example `https://comms.northlight.ai` or the fake `http://localhost:7481`. */
+    baseUrl: string;
+    /** The directory's issuer URL; its `/.well-known/openid-configuration` names the token endpoint. */
+    issuer?: string;
+    /** Your app's id, which is also your `client_id` at the directory. */
+    clientId?: string;
+    privateKeyJwk?: PrivateKeyJwk;
+    /** The audience to mint for. Default `https://comms.northlight.ai`. */
+    resource?: string;
+    /** A fixed bearer token. With it (or `getToken`) the client never contacts a directory; the fake server accepts any bearer. */
+    token?: string;
+    /** Called before each request for a bearer token. */
+    getToken?: () => string | Promise<string>;
+    /** Request timeout in milliseconds for every call, token requests included. Default 30000. */
+    timeoutMs?: number;
+    /** A replacement for the global `fetch`. */
+    fetch?: typeof fetch;
+    /** The current time in milliseconds; for tests. */
+    now?: () => number;
+}
+/** A refusal from Comms (or the directory while minting a token), or a failure to reach it. */
+export declare class CommsError extends Error {
+    readonly name = "CommsError";
+    readonly code: CommsErrorCode;
+    /** HTTP status; `0` when no response arrived. */
+    readonly status: number;
+    readonly retryable: boolean;
+    readonly requestId: string | undefined;
+    readonly param: string | undefined;
+    readonly details: unknown;
+    readonly retryAfterS: number | undefined;
+    constructor(code: CommsErrorCode, message: string, status: number, extra?: {
+        retryable?: boolean;
+        requestId?: string;
+        param?: string;
+        details?: unknown;
+        retryAfterS?: number;
+        cause?: unknown;
+    });
+}
+export declare class CommsClient {
+    #private;
+    constructor(options: CommsClientOptions);
+    /** `POST /v1/messages` → `202`. Refusals arrive as a `CommsError` (`opted_out`, `not_texted_first`, …). */
+    sendMessage(request: SendMessageRequest): Promise<QueuedMessage>;
+    /** `POST /v1/messages/<id>/reactions` → `202`; the answer's `message_id` is the reaction's own. */
+    sendReaction(messageId: string, request: SendReactionRequest): Promise<QueuedMessage>;
+    /** `GET /v1/messages/<id>`. */
+    getMessage(messageId: string): Promise<MessageRecord>;
+    /** `GET /v1/contacts/<id>?environment=`. */
+    getContact(contactId: string, environment: Environment): Promise<Contact>;
+    /** `POST /v1/contacts/<id>/typing` → `204`. Best effort: never queued, never retried. */
+    setTyping(contactId: string, request: TypingRequest): Promise<void>;
+    /** `POST /v1/contacts/<id>/sign-in-link` → `201`. `already_user`, `no_phone` and `opted_out` arrive as a `CommsError`. */
+    createSignInLink(contactId: string, request: SignInLinkRequest): Promise<SignInLink>;
+    /** `GET /v1/numbers/public?environment=`: the number to publish for new people. */
+    getPublicNumber(environment?: Environment): Promise<PublicNumber>;
+}

package/dist/client.js

@@ -0,0 +1,307 @@
+/** The `resource` that selects the Comms audience when minting a directory token. */
+export const DEFAULT_RESOURCE = "https://comms.northlight.ai";
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** A cached token is replaced this long before it expires. */
+const REFRESH_MARGIN_MS = 30_000;
+const ASSERTION_LIFETIME_S = 60;
+/** A refusal from Comms (or the directory while minting a token), or a failure to reach it. */
+export class CommsError extends Error {
+    name = "CommsError";
+    code;
+    /** HTTP status; `0` when no response arrived. */
+    status;
+    retryable;
+    requestId;
+    param;
+    details;
+    retryAfterS;
+    constructor(code, message, status, extra = {}) {
+        super(message, extra.cause === undefined ? undefined : { cause: extra.cause });
+        this.code = code;
+        this.status = status;
+        this.retryable =
+            extra.retryable ?? (status === 0 || status === 429 || status >= 500);
+        this.requestId = extra.requestId;
+        this.param = extra.param;
+        this.details = extra.details;
+        this.retryAfterS = extra.retryAfterS;
+    }
+}
+const base64url = (bytes) => Buffer.from(bytes).toString("base64url");
+const json = (value) => base64url(new TextEncoder().encode(JSON.stringify(value)));
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export class CommsClient {
+    #baseUrl;
+    #issuer;
+    #clientId;
+    #jwk;
+    #resource;
+    #fixedToken;
+    #getToken;
+    #timeoutMs;
+    #fetch;
+    #now;
+    #key;
+    #tokenEndpoint;
+    #cached;
+    #inflight;
+    constructor(options) {
+        this.#baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.#issuer = options.issuer?.replace(/\/+$/, "");
+        this.#clientId = options.clientId;
+        this.#jwk = options.privateKeyJwk;
+        this.#resource = options.resource ?? DEFAULT_RESOURCE;
+        this.#fixedToken = options.token;
+        this.#getToken = options.getToken;
+        this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.#fetch = options.fetch ?? ((input, init) => fetch(input, init));
+        this.#now = options.now ?? Date.now;
+        if (this.#fixedToken === undefined && this.#getToken === undefined) {
+            if (!this.#issuer || !this.#clientId || !this.#jwk)
+                throw new TypeError("CommsClient needs `issuer`, `clientId` and `privateKeyJwk`, or a `token` / `getToken`");
+            const jwk = this.#jwk;
+            if (jwk.kty !== "EC" || jwk.crv !== "P-256" || !jwk.d || !jwk.x || !jwk.y)
+                throw new TypeError("privateKeyJwk must be a private ES256 (P-256) JWK");
+            if (jwk.alg !== undefined && jwk.alg !== "ES256")
+                throw new TypeError("privateKeyJwk.alg must be ES256");
+        }
+    }
+    // ---- Send API -----------------------------------------------------------
+    /** `POST /v1/messages` → `202`. Refusals arrive as a `CommsError` (`opted_out`, `not_texted_first`, …). */
+    sendMessage(request) {
+        return this.#call("POST", "/v1/messages", { body: request });
+    }
+    /** `POST /v1/messages/<id>/reactions` → `202`; the answer's `message_id` is the reaction's own. */
+    sendReaction(messageId, request) {
+        return this.#call("POST", `/v1/messages/${encodeURIComponent(messageId)}/reactions`, {
+            body: request,
+        });
+    }
+    /** `GET /v1/messages/<id>`. */
+    getMessage(messageId) {
+        return this.#call("GET", `/v1/messages/${encodeURIComponent(messageId)}`);
+    }
+    /** `GET /v1/contacts/<id>?environment=`. */
+    getContact(contactId, environment) {
+        return this.#call("GET", `/v1/contacts/${encodeURIComponent(contactId)}`, {
+            query: { environment },
+        });
+    }
+    /** `POST /v1/contacts/<id>/typing` → `204`. Best effort: never queued, never retried. */
+    async setTyping(contactId, request) {
+        await this.#call("POST", `/v1/contacts/${encodeURIComponent(contactId)}/typing`, {
+            body: request,
+        });
+    }
+    /** `POST /v1/contacts/<id>/sign-in-link` → `201`. `already_user`, `no_phone` and `opted_out` arrive as a `CommsError`. */
+    createSignInLink(contactId, request) {
+        return this.#call("POST", `/v1/contacts/${encodeURIComponent(contactId)}/sign-in-link`, {
+            body: request,
+        });
+    }
+    /** `GET /v1/numbers/public?environment=`: the number to publish for new people. */
+    getPublicNumber(environment = "production") {
+        return this.#call("GET", "/v1/numbers/public", { query: { environment } });
+    }
+    // ---- Transport ----------------------------------------------------------
+    async #call(method, path, init = {}) {
+        const url = new URL(this.#baseUrl + path);
+        for (const [name, value] of Object.entries(init.query ?? {}))
+            url.searchParams.set(name, value);
+        // A minted token the server no longer accepts (revoked, rotated key) is replaced once.
+        for (let attempt = 0;; attempt++) {
+            const token = await this.#bearer();
+            const response = await this.#send(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    Accept: "application/json",
+                    ...(init.body === undefined
+                        ? {}
+                        : { "Content-Type": "application/json" }),
+                },
+                ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+            });
+            if (response.status === 401 && attempt === 0 && this.#mints()) {
+                this.#cached = undefined;
+                await response.body?.cancel();
+                continue;
+            }
+            if (!response.ok)
+                throw await errorFrom(response);
+            if (response.status === 204)
+                return undefined;
+            const text = await response.text();
+            try {
+                return JSON.parse(text);
+            }
+            catch (cause) {
+                throw new CommsError("unexpected_response", "Comms answered with a body that is not JSON", response.status, { retryable: false, cause });
+            }
+        }
+    }
+    async #send(url, init) {
+        try {
+            return await this.#fetch(url, {
+                ...init,
+                signal: AbortSignal.timeout(this.#timeoutMs),
+            });
+        }
+        catch (cause) {
+            if (cause instanceof Error &&
+                (cause.name === "TimeoutError" || cause.name === "AbortError"))
+                throw new CommsError("timeout", `Request timed out after ${this.#timeoutMs} ms`, 0, {
+                    cause,
+                });
+            throw new CommsError("network_error", `Request failed: ${describe(cause)}`, 0, { cause });
+        }
+    }
+    // ---- Directory token ----------------------------------------------------
+    #mints() {
+        return this.#fixedToken === undefined && this.#getToken === undefined;
+    }
+    async #bearer() {
+        if (this.#fixedToken !== undefined)
+            return this.#fixedToken;
+        if (this.#getToken)
+            return this.#getToken();
+        const cached = this.#cached;
+        if (cached && this.#now() < cached.expiresAtMs - REFRESH_MARGIN_MS)
+            return cached.value;
+        // Concurrent callers share one token request.
+        this.#inflight ??= this.#mint().finally(() => {
+            this.#inflight = undefined;
+        });
+        return this.#inflight;
+    }
+    async #endpoint() {
+        this.#tokenEndpoint ??= this.#discover().catch((error) => {
+            this.#tokenEndpoint = undefined;
+            throw error;
+        });
+        return this.#tokenEndpoint;
+    }
+    async #discover() {
+        const url = `${this.#issuer}/.well-known/openid-configuration`;
+        const response = await this.#send(url, {
+            headers: { Accept: "application/json" },
+        });
+        const body = await response.json().catch(() => null);
+        if (!response.ok ||
+            !isRecord(body) ||
+            typeof body["token_endpoint"] !== "string")
+            throw new CommsError("token_discovery_failed", `Could not read the token endpoint from ${url}`, response.status, { retryable: response.status >= 500 });
+        return body["token_endpoint"];
+    }
+    async #signingKey() {
+        const jwk = this.#jwk;
+        if (!jwk)
+            throw new TypeError("no private key");
+        this.#key ??= crypto.subtle.importKey("jwk", { kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y, d: jwk.d }, { name: "ECDSA", namedCurve: "P-256" }, false, ["sign"]);
+        return this.#key;
+    }
+    async #assertion(audience) {
+        const clientId = this.#clientId;
+        if (!clientId)
+            throw new TypeError("no client id");
+        const iat = Math.floor(this.#now() / 1000);
+        const header = {
+            alg: "ES256",
+            typ: "JWT",
+            ...(this.#jwk?.kid ? { kid: this.#jwk.kid } : {}),
+        };
+        const claims = {
+            iss: clientId,
+            sub: clientId,
+            aud: audience,
+            iat,
+            exp: iat + ASSERTION_LIFETIME_S,
+            jti: crypto.randomUUID(),
+        };
+        const input = `${json(header)}.${json(claims)}`;
+        // WebCrypto's ECDSA output is the raw r||s form JWS requires.
+        const signature = await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, await this.#signingKey(), new TextEncoder().encode(input));
+        return `${input}.${base64url(new Uint8Array(signature))}`;
+    }
+    async #mint() {
+        const endpoint = await this.#endpoint();
+        const requestedAt = this.#now();
+        const response = await this.#send(endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
+            body: new URLSearchParams({
+                grant_type: "client_credentials",
+                resource: this.#resource,
+                client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
+                client_assertion: await this.#assertion(endpoint),
+            }),
+        });
+        const body = await response.json().catch(() => null);
+        if (!response.ok) {
+            const error = isRecord(body) && typeof body["error"] === "string"
+                ? body["error"]
+                : undefined;
+            const description = isRecord(body) && typeof body["error_description"] === "string"
+                ? body["error_description"]
+                : undefined;
+            throw new CommsError(error ?? "token_request_failed", `The directory refused the token request${description ? `: ${description}` : ""}`, response.status, 
+            // An invalid_client will not heal on retry; a directory outage will.
+            { retryable: response.status >= 500 || response.status === 429 });
+        }
+        if (!isRecord(body) ||
+            typeof body["access_token"] !== "string" ||
+            typeof body["expires_in"] !== "number")
+            throw new CommsError("token_request_failed", "The directory's token response had no access_token and expires_in", response.status, { retryable: false });
+        this.#cached = {
+            value: body["access_token"],
+            expiresAtMs: requestedAt + body["expires_in"] * 1000,
+        };
+        return body["access_token"];
+    }
+}
+function describe(error) {
+    if (error instanceof Error) {
+        const cause = error.cause instanceof Error ? `: ${error.cause.message}` : "";
+        return `${error.message}${cause}`;
+    }
+    return String(error);
+}
+async function errorFrom(response) {
+    const text = await response.text().catch(() => "");
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = undefined;
+    }
+    const error = isRecord(body)
+        ? body.error
+        : undefined;
+    const retryAfterHeader = Number(response.headers.get("retry-after"));
+    if (isRecord(error) &&
+        typeof error.code === "string" &&
+        typeof error.message === "string")
+        return new CommsError(error.code, error.message, response.status, {
+            ...(typeof error.retryable === "boolean"
+                ? { retryable: error.retryable }
+                : {}),
+            ...(typeof error.request_id === "string"
+                ? { requestId: error.request_id }
+                : {}),
+            ...(typeof error.param === "string" ? { param: error.param } : {}),
+            ...(error.details === undefined ? {} : { details: error.details }),
+            ...(typeof error.retry_after_s === "number"
+                ? { retryAfterS: error.retry_after_s }
+                : Number.isFinite(retryAfterHeader) &&
+                    response.headers.has("retry-after")
+                    ? { retryAfterS: retryAfterHeader }
+                    : {}),
+        });
+    return new CommsError("unexpected_response", `Comms answered ${response.status} with a body that is not the error envelope`, response.status);
+}

package/dist/fake/cli.d.ts

@@ -0,0 +1,14 @@
+import { type FakeServer } from "./server.js";
+export declare class UsageError extends Error {
+    readonly name = "UsageError";
+}
+export interface CliIo {
+    out: (line: string) => void;
+    /** Resolves when the server should stop (a signal). Default: never, until the process is signalled. */
+    stopped?: Promise<void>;
+}
+/**
+ * Runs the CLI. `comms fake` resolves with the running server (the caller keeps the process
+ * alive); `comms fake send` resolves with `undefined` once the fake has answered.
+ */
+export declare function run(argv: readonly string[], io: CliIo): Promise<FakeServer | undefined>;