@comms-id/asx 0.2.0

package/dist/generated/types.d.ts

@@ -0,0 +1,135 @@
+/** The body of lookup. */
+export type LookupRequest = {
+    /** The ASX ticker, for example 'BHP'. */
+    readonly ticker: string;
+    /** live: ASX now; snapshot: the stored directory; live-first: ASX, then the snapshot on failure. */
+    readonly mode?: "live" | "snapshot" | "live-first";
+};
+/** The reply of lookup. */
+export type LookupResponse = {
+    readonly status: "found";
+    readonly source: "live";
+    readonly observation: {
+        readonly company: {
+            readonly raw?: Readonly<Record<string, unknown>>;
+            readonly ticker: string;
+            readonly sourceId: string;
+            readonly companyName: string;
+            readonly address: string | null;
+            readonly tel: string | null;
+            readonly fax: string | null;
+            readonly website: string | null;
+            readonly description: string | null;
+            readonly issueType: string | null;
+            readonly foreignExempt: boolean | null;
+            readonly people: ReadonlyArray<{
+                readonly sourceName: string;
+                readonly displayName: string;
+                readonly title: string;
+                readonly sourceCategory: "directors" | "secretaries";
+            }>;
+        };
+        readonly startedAt: string;
+        readonly observedAt: string;
+        readonly lastChangedAt: string;
+    };
+} | {
+    readonly status: "missing";
+    readonly source: "live";
+    readonly startedAt: string;
+    readonly observedAt: string;
+} | {
+    readonly status: "found";
+    readonly source: "snapshot";
+    readonly observation: {
+        readonly company: {
+            readonly raw?: Readonly<Record<string, unknown>>;
+            readonly ticker: string;
+            readonly sourceId: string;
+            readonly companyName: string;
+            readonly address: string | null;
+            readonly tel: string | null;
+            readonly fax: string | null;
+            readonly website: string | null;
+            readonly description: string | null;
+            readonly issueType: string | null;
+            readonly foreignExempt: boolean | null;
+            readonly people: ReadonlyArray<{
+                readonly sourceName: string;
+                readonly displayName: string;
+                readonly title: string;
+                readonly sourceCategory: "directors" | "secretaries";
+            }>;
+        };
+        readonly startedAt: string;
+        readonly observedAt: string;
+        readonly lastChangedAt: string;
+    };
+    readonly generation: string;
+    readonly enrichment?: {
+        readonly ticker: string;
+        readonly sourceId: string;
+        readonly abn: string;
+        readonly acn: string | null;
+        readonly legalName: string;
+        readonly identityEvidence: {
+            readonly url: string;
+            readonly sha256: string;
+            readonly observedAt: string;
+            readonly kind: "issuer-filing" | "issuer-website";
+        };
+        readonly abrEvidence: {
+            readonly source: "abr-live" | "abr-snapshot";
+            readonly observedAt: string;
+        };
+        readonly website: {
+            readonly url: string;
+            readonly evidence: {
+                readonly url: string;
+                readonly sha256: string;
+                readonly observedAt: string;
+                readonly kind: "issuer-filing" | "issuer-website";
+            };
+        } | null;
+    };
+    readonly requiresRecheck: boolean;
+    readonly fallbackReason?: "INVALID_INPUT" | "PARSE_FAILED" | "SOURCE_MISMATCH" | "TRANSPORT_FAILED" | "TIMEOUT" | "RATE_LIMITED" | "UPSTREAM_UNAVAILABLE" | "CONFIGURATION_ERROR" | "SNAPSHOT_UNAVAILABLE" | "CANCELLED" | "INTERNAL_ERROR" | "ACCESS_DENIED" | "UPSTREAM_REJECTED" | "PERSISTENCE_FAILED" | "PUBLICATION_CONFLICT" | "COVERAGE_REJECTED";
+} | {
+    readonly status: "missing";
+    readonly source: "snapshot";
+    readonly generation: string;
+};
+/** The body of suggest. */
+export type SuggestRequest = {
+    /** live: ASX now; snapshot: the stored directory; live-first: ASX, then the snapshot on failure. */
+    readonly mode?: "live" | "snapshot" | "live-first";
+    /** A ticker or company name prefix. */
+    readonly query: string;
+    /** How many suggestions to return, 1 to 10. */
+    readonly limit?: number;
+};
+/** The reply of suggest. */
+export type SuggestResponse = {
+    readonly source: "live";
+    readonly directoryObservedAt: string;
+    readonly suggestions: ReadonlyArray<{
+        readonly ticker: string;
+        readonly companyName: string;
+        readonly industryGroup: string | null;
+        readonly listingDate: string | null;
+        readonly marketCapitalisation: number | "Infinity" | "-Infinity" | "NaN" | null;
+    }>;
+} | {
+    readonly source: "snapshot";
+    readonly generation: string;
+    readonly directoryObservedAt: string;
+    readonly requiresRecheck: boolean;
+    readonly suggestions: ReadonlyArray<{
+        readonly ticker: string;
+        readonly companyName: string;
+        readonly industryGroup: string | null;
+        readonly listingDate: string | null;
+        readonly marketCapitalisation: number | "Infinity" | "-Infinity" | "NaN" | null;
+    }>;
+    readonly fallbackReason?: "INVALID_INPUT" | "PARSE_FAILED" | "SOURCE_MISMATCH" | "TRANSPORT_FAILED" | "TIMEOUT" | "RATE_LIMITED" | "UPSTREAM_UNAVAILABLE" | "CONFIGURATION_ERROR" | "SNAPSHOT_UNAVAILABLE" | "CANCELLED" | "INTERNAL_ERROR" | "ACCESS_DENIED" | "UPSTREAM_REJECTED" | "PERSISTENCE_FAILED" | "PUBLICATION_CONFLICT" | "COVERAGE_REJECTED";
+};

package/dist/generated/types.js

@@ -0,0 +1,2 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+export {};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { AsxClient } from "./generated/client.js";
+export { errorCodes, operations } from "./generated/operations.js";
+export type { OperationName } from "./generated/operations.js";
+export type { LookupRequest, LookupResponse, SuggestRequest, SuggestResponse } from "./generated/types.js";
+export { CommsIdError, isCommsIdError, outcomeOf } from "./runtime/errors.js";
+export type { Outcome } from "./runtime/errors.js";
+export type { CallOptions } from "./runtime/http.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+// Browser-safe entry: types, errors and the operation table. No signing code is imported here.
+export { errorCodes, operations } from "./generated/operations.js";
+export { CommsIdError, isCommsIdError, outcomeOf } from "./runtime/errors.js";

package/dist/runtime/browser-core.d.ts

@@ -0,0 +1,23 @@
+import { type Environment } from "./environment.js";
+import type { TransportConfig } from "./http.js";
+interface Common {
+    readonly deadlineMs?: number;
+    readonly fetch?: typeof fetch;
+    readonly maxRetries?: number;
+}
+/** Calls the consumer's own server route, which signs for the app (the relay). */
+export interface RelayOptions extends Common {
+    /** For example "/api/comms-id/address". The operation name is appended. */
+    readonly relayUrl: string;
+}
+/** Calls the hosted service with a short-lived capability that the caller supplies. */
+export interface CapabilityOptions extends Common {
+    /** Another host. It wins over `environment`. */
+    readonly baseUrl?: string;
+    /** "live" (the default) or "test". */
+    readonly environment?: Environment;
+    readonly getCapability: () => Promise<string>;
+}
+export type BrowserOptions = RelayOptions | CapabilityOptions;
+export declare const createBrowserTransport: (options: BrowserOptions) => TransportConfig;
+export {};

package/dist/runtime/browser-core.js

@@ -0,0 +1,41 @@
+// Runtime template: copied into every generated client package as src/runtime/browser-core.ts.
+// Browser entry: it never signs and never holds a secret. It either calls the consumer's own
+// relay route, or sends a short-lived capability that the caller obtains by other means.
+import { resolveBaseUrl } from "./environment.js";
+import { CommsIdError } from "./errors.js";
+const TRAILING_SLASHES = /\/+$/;
+const passThrough = (options) => ({
+    ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+    ...(options.deadlineMs === undefined ? {} : { deadlineMs: options.deadlineMs }),
+    ...(options.maxRetries === undefined ? {} : { maxRetries: options.maxRetries }),
+});
+/** A browser client with neither a relay nor a capability source has no identified caller. */
+const requireCaller = (options) => {
+    const relay = options.relayUrl;
+    const capability = options.getCapability;
+    if ((typeof relay !== "string" || relay === "") && typeof capability !== "function") {
+        throw new CommsIdError({
+            code: "NOT_CONFIGURED",
+            message: "Set relayUrl (your server route) or getCapability: the browser holds no credential of its own.",
+            status: 0,
+            retryable: false,
+        });
+    }
+};
+export const createBrowserTransport = (options) => {
+    requireCaller(options);
+    if ("relayUrl" in options) {
+        const relay = options.relayUrl.replace(TRAILING_SLASHES, "");
+        return {
+            urlFor: (operation) => `${relay}/${operation.name}`,
+            headers: () => Promise.resolve({}),
+            ...passThrough(options),
+        };
+    }
+    const base = resolveBaseUrl(options.environment, options.baseUrl).replace(TRAILING_SLASHES, "");
+    return {
+        urlFor: (operation) => `${base}${operation.path}`,
+        headers: async () => ({ authorization: `Bearer ${await options.getCapability()}` }),
+        ...passThrough(options),
+    };
+};

package/dist/runtime/environment.d.ts

@@ -0,0 +1,5 @@
+export type Environment = "live" | "test";
+export declare const BASE_URLS: Readonly<Record<Environment, string>>;
+export declare const isEnvironment: (value: unknown) => value is Environment;
+/** The base URL: an explicit one wins, then the environment (live by default). */
+export declare const resolveBaseUrl: (environment: unknown, baseUrl: string | undefined) => string;

package/dist/runtime/environment.js

@@ -0,0 +1,30 @@
+// Runtime template: copied into every generated client package as src/runtime/environment.ts.
+// The two environments of the hosted API (platform #515, T4). They differ in the base URL and in
+// the keys the service knows: TEST answers with synthetic replies for apps registered in the
+// development directory; LIVE answers with real data for apps registered in production. The API,
+// the errors and the authentication are the same, so going live changes only the environment and
+// the key.
+import { CommsIdError } from "./errors.js";
+export const BASE_URLS = {
+    live: "https://api.comms.id",
+    test: "https://api-test.comms.id",
+};
+export const isEnvironment = (value) => value === "live" || value === "test";
+/** The base URL: an explicit one wins, then the environment (live by default). */
+export const resolveBaseUrl = (environment, baseUrl) => {
+    if (baseUrl !== undefined) {
+        return baseUrl;
+    }
+    if (environment === undefined) {
+        return BASE_URLS.live;
+    }
+    if (!isEnvironment(environment)) {
+        throw new CommsIdError({
+            code: "NOT_CONFIGURED",
+            message: 'environment must be "test" or "live".',
+            status: 0,
+            retryable: false,
+        });
+    }
+    return BASE_URLS[environment];
+};

package/dist/runtime/errors.d.ts

@@ -0,0 +1,29 @@
+/** The three results a lookup can have besides a match. */
+export type Outcome = "no-match" | "source-unavailable" | "failed";
+export interface ErrorInit {
+    /** The reply's own body, when the service answered an error status with a structured reply instead of an error body. */
+    readonly body?: unknown;
+    readonly code: string;
+    readonly message: string;
+    readonly requestId?: string | undefined;
+    readonly retryable: boolean;
+    /** The HTTP status, or 0 when no reply was received or the call never left the client. */
+    readonly status: number;
+}
+/**
+ * Every failure of a call. The service sends `code`, `message`, `retryable` and `requestId`.
+ * The client adds the codes INVALID_REQUEST (refused before any request), NETWORK, TIMEOUT,
+ * ABORTED and INVALID_RESPONSE.
+ */
+export declare class CommsIdError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly retryable: boolean;
+    readonly requestId: string | undefined;
+    /** The structured reply of a status such as 503 whose body is an outcome, not an error body (code HTTP_<status>). */
+    readonly body: unknown;
+    constructor(init: ErrorInit);
+}
+export declare const isCommsIdError: (value: unknown) => value is CommsIdError;
+/** Maps an error to the outcome that the reply convention names. A match never reaches this. */
+export declare const outcomeOf: (error: unknown) => Outcome;

package/dist/runtime/errors.js

@@ -0,0 +1,40 @@
+// Runtime template: copied into every generated client package as src/runtime/errors.ts.
+// It has no imports, so the copy is identical to this file.
+/**
+ * Every failure of a call. The service sends `code`, `message`, `retryable` and `requestId`.
+ * The client adds the codes INVALID_REQUEST (refused before any request), NETWORK, TIMEOUT,
+ * ABORTED and INVALID_RESPONSE.
+ */
+export class CommsIdError extends Error {
+    code;
+    status;
+    retryable;
+    requestId;
+    /** The structured reply of a status such as 503 whose body is an outcome, not an error body (code HTTP_<status>). */
+    body;
+    constructor(init) {
+        super(init.message);
+        this.name = "CommsIdError";
+        this.code = init.code;
+        this.status = init.status;
+        this.retryable = init.retryable;
+        this.requestId = init.requestId;
+        this.body = init.body;
+    }
+}
+export const isCommsIdError = (value) => value instanceof CommsIdError;
+/** HTTP statuses that say the source or the path to it is down: 502, 503 and 504. The client's own failures have status 0. */
+const GATEWAY_STATUSES = new Set([502, 503, 504]);
+/** Maps an error to the outcome that the reply convention names. A match never reaches this. */
+export const outcomeOf = (error) => {
+    if (!isCommsIdError(error)) {
+        return "failed";
+    }
+    if (error.code === "NOT_FOUND") {
+        return "no-match";
+    }
+    if (error.code === "UNAVAILABLE" || GATEWAY_STATUSES.has(error.status)) {
+        return "source-unavailable";
+    }
+    return "failed";
+};

package/dist/runtime/fixture-core.d.ts

@@ -0,0 +1,7 @@
+import type { TransportConfig } from "./http.js";
+/** Every fixture reply carries this header, and every fixture client exposes it. */
+export declare const FIXTURE_HEADER = "x-comms-id-fixture";
+export declare const FIXTURE_NOTICE = "LOCAL FIXTURE: fake data, no network call was made.";
+/** A fetch that answers each operation path with its canned reply. */
+export declare const createFixtureFetch: (replies: Readonly<Record<string, unknown>>) => typeof fetch;
+export declare const createFixtureTransport: (replies: Readonly<Record<string, unknown>>) => TransportConfig;

package/dist/runtime/fixture-core.js

@@ -0,0 +1,26 @@
+// Runtime template: copied into every generated client package as src/runtime/fixture-core.ts.
+// LOCAL FIXTURES: no network. The client runs the same request and reply checks as a real call.
+/** Every fixture reply carries this header, and every fixture client exposes it. */
+export const FIXTURE_HEADER = "x-comms-id-fixture";
+export const FIXTURE_NOTICE = "LOCAL FIXTURE: fake data, no network call was made.";
+/** A fetch that answers each operation path with its canned reply. */
+export const createFixtureFetch = (replies) => (input) => {
+    const url = new URL(typeof input === "string" || input instanceof URL ? input : input.url, "http://fixture.invalid");
+    const reply = replies[url.pathname];
+    if (reply === undefined) {
+        return Promise.resolve(new Response(JSON.stringify({ code: "NOT_FOUND", message: "No fixture for this operation.", retryable: false }), {
+            status: 404,
+            headers: { "content-type": "application/json", [FIXTURE_HEADER]: FIXTURE_NOTICE },
+        }));
+    }
+    return Promise.resolve(new Response(JSON.stringify(reply), {
+        status: 200,
+        headers: { "content-type": "application/json", [FIXTURE_HEADER]: FIXTURE_NOTICE },
+    }));
+};
+export const createFixtureTransport = (replies) => ({
+    urlFor: (operation) => operation.path,
+    headers: () => Promise.resolve({}),
+    fetch: createFixtureFetch(replies),
+    maxRetries: 0,
+});

package/dist/runtime/http.d.ts

@@ -0,0 +1,34 @@
+import { type Schema } from "./validate.js";
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** A hand-written check that a schema cannot state. It returns the reason to refuse, or undefined. */
+export type Guard = (input: unknown) => string | undefined;
+/** One hosted operation, as the generator writes it from the OpenAPI document. */
+export interface Operation {
+    /** Run after the schema check and before any request (for example an ABN check digit). */
+    readonly guard?: Guard | undefined;
+    readonly method: HttpMethod;
+    readonly name: string;
+    readonly path: string;
+    readonly request: Schema | undefined;
+    readonly response: Schema;
+    /** From x-comms-id-safe-to-retry: only such an operation is ever sent twice. */
+    readonly safeToRetry: boolean;
+}
+export interface CallOptions {
+    /** Overrides the deadline for this call, in milliseconds. */
+    readonly deadlineMs?: number;
+    /** Cancels the call. The error code is ABORTED. */
+    readonly signal?: AbortSignal;
+}
+export interface TransportConfig {
+    /** The deadline for the whole call, retries included. 10 seconds by default. */
+    readonly deadlineMs?: number;
+    readonly fetch?: typeof fetch;
+    readonly headers: () => Promise<Readonly<Record<string, string>>>;
+    /** Extra tries of a safe operation after a retryable failure. 2 by default. */
+    readonly maxRetries?: number;
+    readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    readonly urlFor: (operation: Operation) => string;
+}
+/** Sends one operation and returns its decoded reply, or throws a CommsIdError. */
+export declare const call: <Reply>(transport: TransportConfig, operation: Operation, input: unknown, options?: CallOptions) => Promise<Reply>;

package/dist/runtime/http.js

@@ -0,0 +1,165 @@
+// Runtime template: copied into every generated client package as src/runtime/http.ts.
+// One call: validate the request, send it with a deadline and a cancel signal, retry only an
+// operation that is safe to repeat, validate the reply. No dependencies, no Comms.ID logic
+// beyond the reply convention.
+import { CommsIdError } from "./errors.js";
+import { validate } from "./validate.js";
+const DEFAULT_DEADLINE_MS = 10_000;
+const DEFAULT_MAX_RETRIES = 2;
+const BASE_DELAY_MS = 200;
+const MAX_DELAY_MS = 2000;
+const fail = (code, message, status, retryable, requestId, body) => new CommsIdError({ code, message, status, retryable, requestId, body });
+const summarize = (issues) => issues
+    .slice(0, 3)
+    .map((issue) => `${issue.path} ${issue.message}`)
+    .join("; ");
+const defaultSleep = (ms, signal) => new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener("abort", () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+    }, { once: true });
+});
+const abortError = (user) => user?.aborted === true
+    ? fail("ABORTED", "The call was cancelled.", 0, false)
+    : fail("TIMEOUT", "The call passed its deadline.", 0, true);
+const retryAfterMs = (response) => {
+    const header = response.headers.get("retry-after");
+    const seconds = header === null ? Number.NaN : Number(header);
+    return Number.isInteger(seconds) && seconds >= 0 ? seconds * 1000 : undefined;
+};
+const readFailure = async (response) => {
+    const headerId = response.headers.get("x-request-id") ?? undefined;
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        body = undefined;
+    }
+    const record = typeof body === "object" && body !== null ? body : {};
+    if (typeof record.code === "string" && typeof record.message === "string" && typeof record.retryable === "boolean") {
+        const requestId = typeof record.requestId === "string" ? record.requestId : headerId;
+        return fail(record.code, record.message, response.status, record.retryable, requestId);
+    }
+    const gateway = response.status >= 502 && response.status <= 504;
+    return fail(`HTTP_${response.status}`, `The service answered ${response.status}.`, response.status, gateway, headerId, 
+    // A structured reply with an error status (an unavailable or partial outcome) keeps its body.
+    Object.keys(record).length > 0 ? record : undefined);
+};
+const readSuccess = async (operation, response) => {
+    const requestId = response.headers.get("x-request-id") ?? undefined;
+    let value;
+    try {
+        value = await response.json();
+    }
+    catch {
+        return {
+            ok: false,
+            error: fail("INVALID_RESPONSE", "The reply is not JSON.", response.status, false, requestId),
+            retryAfterMs: undefined,
+        };
+    }
+    const issues = validate(operation.response, value, "response");
+    if (issues.length > 0) {
+        return {
+            ok: false,
+            error: fail("INVALID_RESPONSE", `The reply does not match the contract: ${summarize(issues)}`, response.status, false, requestId),
+            retryAfterMs: undefined,
+        };
+    }
+    return { ok: true, value };
+};
+/**
+ * Builds the credential headers. A failure here is not a network failure: a CommsIdError (for
+ * example a refused public key) is passed on as it is, and anything else is a configuration
+ * error. Neither is sent anywhere.
+ */
+const credentialHeaders = async (transport) => {
+    try {
+        return { ok: true, headers: await transport.headers() };
+    }
+    catch (cause) {
+        if (cause instanceof CommsIdError) {
+            return { ok: false, error: cause };
+        }
+        const reason = cause instanceof Error ? cause.message : "unknown error";
+        return { ok: false, error: fail("NOT_CONFIGURED", `Could not prepare the credentials: ${reason}`, 0, false) };
+    }
+};
+const attemptOnce = async (transport, operation, body, signal, user) => {
+    if (signal.aborted) {
+        throw abortError(user);
+    }
+    const credentials = await credentialHeaders(transport);
+    // A cancel that arrives while the credentials are built must not reach fetch.
+    if (signal.aborted) {
+        throw abortError(user);
+    }
+    if (!credentials.ok) {
+        return { ok: false, error: credentials.error, retryAfterMs: undefined };
+    }
+    const headers = {
+        accept: "application/json",
+        ...(body === undefined ? {} : { "content-type": "application/json" }),
+        ...credentials.headers,
+    };
+    let response;
+    try {
+        response = await (transport.fetch ?? fetch)(transport.urlFor(operation), {
+            method: operation.method,
+            headers,
+            body,
+            signal,
+        });
+    }
+    catch (cause) {
+        if (signal.aborted) {
+            throw abortError(user);
+        }
+        const reason = cause instanceof Error ? cause.message : "The request failed.";
+        return { ok: false, error: fail("NETWORK", reason, 0, true), retryAfterMs: undefined };
+    }
+    if (response.ok) {
+        return await readSuccess(operation, response);
+    }
+    return { ok: false, error: await readFailure(response), retryAfterMs: retryAfterMs(response) };
+};
+const prepare = (operation, input) => {
+    if (operation.request === undefined) {
+        return undefined;
+    }
+    const issues = validate(operation.request, input, "request");
+    if (issues.length > 0) {
+        throw fail("INVALID_REQUEST", `The request is not valid: ${summarize(issues)}`, 0, false);
+    }
+    const refusal = operation.guard?.(input);
+    if (refusal !== undefined) {
+        throw fail("INVALID_REQUEST", `The request is not valid: ${refusal}`, 0, false);
+    }
+    return JSON.stringify(input);
+};
+/** Sends one operation and returns its decoded reply, or throws a CommsIdError. */
+export const call = async (transport, operation, input, options = {}) => {
+    const body = prepare(operation, input);
+    const deadline = AbortSignal.timeout(options.deadlineMs ?? transport.deadlineMs ?? DEFAULT_DEADLINE_MS);
+    const signal = options.signal === undefined ? deadline : AbortSignal.any([options.signal, deadline]);
+    const maxRetries = operation.safeToRetry ? (transport.maxRetries ?? DEFAULT_MAX_RETRIES) : 0;
+    const sleep = transport.sleep ?? defaultSleep;
+    for (let attempt = 0;; attempt += 1) {
+        const result = await attemptOnce(transport, operation, body, signal, options.signal);
+        if (result.ok) {
+            return result.value;
+        }
+        if (attempt >= maxRetries || !result.error.retryable) {
+            throw result.error;
+        }
+        const delay = result.retryAfterMs ?? Math.min(BASE_DELAY_MS * 2 ** attempt, MAX_DELAY_MS);
+        try {
+            await sleep(delay, signal);
+        }
+        catch {
+            throw abortError(options.signal);
+        }
+    }
+};

package/dist/runtime/server-core.d.ts

@@ -0,0 +1,26 @@
+import { type Environment } from "./environment.js";
+import type { TransportConfig } from "./http.js";
+import { type PrivateJwk } from "./sign.js";
+export declare const DEFAULT_BASE_URL: string;
+export interface ServerOptions {
+    /** Another host. It wins over `environment`. */
+    readonly baseUrl?: string;
+    /** The registered app id (COMMS_ID_CLIENT_ID). */
+    readonly clientId: string;
+    readonly deadlineMs?: number;
+    /** "live" (the default) or "test": synthetic replies for apps registered in the development directory. */
+    readonly environment?: Environment;
+    readonly fetch?: typeof fetch;
+    readonly maxRetries?: number;
+    readonly now?: () => number;
+    /** The app's private Ed25519 key (COMMS_ID_PRIVATE_JWK). */
+    readonly privateJwk: PrivateJwk;
+    /** Seconds each signed token stays valid: 120 by default, 600 at most. */
+    readonly tokenLifetimeSeconds?: number;
+}
+/** What the service verifies: its audience and scope, written into the generated client. */
+export interface ServerTarget {
+    readonly audience: string;
+    readonly scope: string;
+}
+export declare const createServerTransport: (options: ServerOptions, target: ServerTarget) => TransportConfig;

package/dist/runtime/server-core.js

@@ -0,0 +1,39 @@
+// Runtime template: copied into every generated client package as src/runtime/server-core.ts.
+// Server entry only. The private key never leaves the consumer's server.
+import { BASE_URLS, resolveBaseUrl } from "./environment.js";
+import { CommsIdError } from "./errors.js";
+import { createTokenSigner } from "./sign.js";
+export const DEFAULT_BASE_URL = BASE_URLS.live;
+const TRAILING_SLASHES = /\/+$/;
+/** A transport that signs a fresh short-lived token for every call. */
+const notConfigured = (message) => new CommsIdError({ code: "NOT_CONFIGURED", message, status: 0, retryable: false });
+/** A client with no identified caller is a configuration error: it never sends an unsigned request. */
+const requireCaller = (options) => {
+    if (typeof options.clientId !== "string" || options.clientId.trim() === "") {
+        throw notConfigured("clientId is empty: set COMMS_ID_CLIENT_ID to your registered app id.");
+    }
+    const key = options.privateJwk;
+    if (key?.kty !== "OKP" || key.crv !== "Ed25519" || typeof key.x !== "string" || typeof key.d !== "string") {
+        throw notConfigured("privateJwk is missing or not an Ed25519 private key: set COMMS_ID_PRIVATE_JWK.");
+    }
+};
+export const createServerTransport = (options, target) => {
+    requireCaller(options);
+    const sign = createTokenSigner(options.privateJwk);
+    const base = resolveBaseUrl(options.environment, options.baseUrl).replace(TRAILING_SLASHES, "");
+    return {
+        urlFor: (operation) => `${base}${operation.path}`,
+        headers: async () => ({
+            authorization: `Bearer ${await sign({
+                clientId: options.clientId,
+                audience: target.audience,
+                scope: target.scope,
+                ...(options.tokenLifetimeSeconds === undefined ? {} : { lifetimeSeconds: options.tokenLifetimeSeconds }),
+                ...(options.now === undefined ? {} : { now: options.now }),
+            })}`,
+        }),
+        ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+        ...(options.deadlineMs === undefined ? {} : { deadlineMs: options.deadlineMs }),
+        ...(options.maxRetries === undefined ? {} : { maxRetries: options.maxRetries }),
+    };
+};

package/dist/runtime/sign.d.ts

@@ -0,0 +1,22 @@
+/** An Ed25519 private key as a JWK: the key pair's private half stays on the consumer's server. */
+export interface PrivateJwk {
+    readonly crv: "Ed25519";
+    readonly d: string;
+    readonly kty: "OKP";
+    readonly x: string;
+}
+export interface TokenInput {
+    /** The service the token is for. */
+    readonly audience: string;
+    /** The registered app id, sent as the token issuer. */
+    readonly clientId: string;
+    /** Seconds the token stays valid: 120 by default, 600 at most. */
+    readonly lifetimeSeconds?: number;
+    readonly now?: () => number;
+    readonly scope: string;
+}
+/**
+ * Returns a function that signs one short-lived token for each call. The key is imported once.
+ * The token is a JWT with alg EdDSA and the claims iss, aud, sub, jti, iat, exp and scope.
+ */
+export declare const createTokenSigner: (privateJwk: PrivateJwk) => ((input: TokenInput) => Promise<string>);