@comms-id/website-logo 0.0.0-stage → 0.3.2

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,172 @@
+// 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 deadlineMs = options.deadlineMs ?? transport.deadlineMs ?? DEFAULT_DEADLINE_MS;
+    const startedAt = performance.now();
+    const deadline = AbortSignal.timeout(deadlineMs);
+    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);
+        // A retry that cannot start within this call's budget must not replace a real
+        // service failure (notably 429) with a later timeout or violate Retry-After.
+        if (delay >= deadlineMs - (performance.now() - startedAt)) {
+            throw result.error;
+        }
+        try {
+            await sleep(delay, signal);
+        }
+        catch {
+            throw abortError(options.signal);
+        }
+    }
+};

package/dist/runtime/image-controller.d.ts

@@ -0,0 +1,7 @@
+import type { ImageController, ImageControllerOptions, ImageProfile, ImageState } from "./image-types.js";
+/** True when the URL is https and on one of the allowed origins. Anything else is never loaded. */
+export declare const isAllowedImage: (url: string, origins: readonly string[]) => boolean;
+/** The state of an image with no site. */
+export declare const initialImageState: <R>(profile: ImageProfile<never, R>, site?: string) => ImageState<R>;
+/** Creates the controller. Nothing is called until a site is set. */
+export declare const createImageController: <C, R>(options: ImageControllerOptions<C, R>) => ImageController<R>;

package/dist/runtime/image-controller.js

@@ -0,0 +1,184 @@
+// Runtime template: copied into a generated client package as src/runtime/image-controller.ts.
+// The headless controller of an image: it asks the service about a site and decides what to show,
+// with no framework and no markup. The React package and the web element both run on it.
+//
+// An image is shown only when the service named one on an https URL of an allowed origin; anything
+// else, a missing image, a blocked address, a failed load, a failed call, shows the letter in the
+// same box. The product-specific part is the profile (src/local/profile.ts).
+import { isCommsIdError, outcomeOf } from "./errors.js";
+const errorMessage = (service, code, outcome) => {
+    if (code === "FAIR_USE_CEILING") {
+        return `The ${service.toLowerCase()} limit is reached. Try again later.`;
+    }
+    if (outcome === "source-unavailable") {
+        return `${service} is unavailable. Try again later.`;
+    }
+    return `${service} failed. Try again.`;
+};
+const toError = (service, cause) => {
+    const outcome = outcomeOf(cause);
+    const base = isCommsIdError(cause)
+        ? { code: cause.code, detail: cause.message, outcome, retryable: cause.retryable, requestId: cause.requestId }
+        : {
+            code: "UNKNOWN",
+            detail: cause instanceof Error ? cause.message : String(cause),
+            outcome,
+            retryable: false,
+            requestId: undefined,
+        };
+    return { ...base, message: errorMessage(service, base.code, outcome) };
+};
+const isOurAbort = (cause) => isCommsIdError(cause) && cause.code === "ABORTED";
+/** True when the URL is https and on one of the allowed origins. Anything else is never loaded. */
+export const isAllowedImage = (url, origins) => {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "https:" && origins.includes(parsed.origin);
+    }
+    catch {
+        return false;
+    }
+};
+/** The state of an image with no site. */
+export const initialImageState = (profile, site = "") => ({
+    site,
+    status: "idle",
+    url: undefined,
+    reason: undefined,
+    error: undefined,
+    record: undefined,
+    label: profile.label(site),
+    monogram: profile.monogram(site),
+});
+/** Creates the controller. Nothing is called until a site is set. */
+export const createImageController = (options) => {
+    const { client, profile } = options;
+    const origins = [...profile.allowedOrigins, ...(options.extraOrigins ?? [])];
+    let state = initialImageState(profile);
+    const listeners = new Set();
+    let sequence = 0;
+    let inFlight;
+    let retryAction;
+    let disposed = false;
+    const notify = () => {
+        for (const listener of [...listeners]) {
+            listener();
+        }
+    };
+    const set = (patch) => {
+        state = { ...state, ...patch };
+        notify();
+    };
+    /** Starts a new generation: a call still in flight becomes stale. */
+    const supersede = () => {
+        sequence += 1;
+        inFlight?.abort();
+        inFlight = undefined;
+        return sequence;
+    };
+    /** A consumer's callback must not corrupt the state: its error goes to the page. */
+    const tell = (callback) => {
+        try {
+            callback();
+        }
+        catch (thrown) {
+            queueMicrotask(() => {
+                throw thrown;
+            });
+        }
+    };
+    const fallBack = (reason) => {
+        set({ status: "fallback", reason, url: undefined });
+        tell(() => options.onFallback?.(reason));
+    };
+    const answer = (resolved) => {
+        if (resolved.url !== undefined && isAllowedImage(resolved.url, origins)) {
+            set({ status: "ready", url: resolved.url, reason: undefined, error: undefined, record: resolved.record });
+        }
+        else {
+            state = { ...state, record: resolved.record, error: undefined };
+            fallBack(resolved.url === undefined ? "missing" : "blocked");
+        }
+        tell(() => options.onResult?.(resolved.record));
+    };
+    const call = async (generation, run) => {
+        const controller = new AbortController();
+        inFlight = controller;
+        retryAction = () => {
+            const next = supersede();
+            set({ status: "loading", error: undefined });
+            call(next, run).catch(() => undefined);
+        };
+        let resolved;
+        try {
+            resolved = await run(client, { signal: controller.signal });
+        }
+        catch (cause) {
+            if (generation !== sequence || disposed || isOurAbort(cause)) {
+                return;
+            }
+            const error = toError(profile.service, cause);
+            set({ status: "error", error, url: undefined, reason: undefined });
+            tell(() => options.onError?.(error));
+            return;
+        }
+        if (generation !== sequence || disposed) {
+            return;
+        }
+        answer(resolved);
+    };
+    const setSite = (site) => {
+        if (disposed || (site === state.site && state.status !== "idle")) {
+            return;
+        }
+        const generation = supersede();
+        const reading = profile.read(site);
+        const base = initialImageState(profile, site);
+        if (reading.kind === "idle") {
+            state = base;
+            notify();
+            return;
+        }
+        if (reading.kind === "invalid") {
+            state = { ...base, status: "invalid" };
+            notify();
+            return;
+        }
+        state = { ...base, status: "loading" };
+        notify();
+        call(generation, reading.run).catch(() => undefined);
+    };
+    const imageFailed = () => {
+        if (disposed || state.status !== "ready") {
+            return;
+        }
+        fallBack("failed");
+    };
+    const retry = () => {
+        if (disposed || state.status !== "error") {
+            return;
+        }
+        retryAction?.();
+    };
+    const dispose = () => {
+        disposed = true;
+        supersede();
+        listeners.clear();
+    };
+    if (options.site !== undefined) {
+        setSite(options.site);
+    }
+    return {
+        getState: () => state,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        setSite,
+        imageFailed,
+        retry,
+        dispose,
+    };
+};

package/dist/runtime/image-types.d.ts

@@ -0,0 +1,112 @@
+import type { Outcome } from "./errors.js";
+import type { CallOptions } from "./http.js";
+/** A call the profile prepared: it runs against the client as soon as the site is known. */
+export type Run<C, T> = (client: C, options: CallOptions) => Promise<T>;
+/** What the service answered. */
+export interface Resolved<R> {
+    /** What the consumer receives. */
+    readonly record: R;
+    /** The image to show, or undefined when the service has none. Only a Comms.ID URL is ever shown. */
+    readonly url: string | undefined;
+}
+/** What the profile makes of the site the page gave. */
+export type ImageReading<C, R> = 
+/** Nothing to show yet. */
+{
+    readonly kind: "idle";
+}
+/** The site is not valid. Nothing is sent. */
+ | {
+    readonly kind: "invalid";
+    readonly message: string;
+} | {
+    readonly kind: "resolve";
+    readonly run: Run<C, Resolved<R>>;
+};
+/** The only product-specific part of an image: written by hand in the package (src/local/profile.ts). */
+export interface ImageProfile<C, R> {
+    /** Origins an image may be loaded from, for example "https://api.comms.id". Nothing else is ever shown. */
+    readonly allowedOrigins: readonly string[];
+    /** The accessible name of the image for a site: "Stripe logo". */
+    readonly label: (site: string) => string;
+    /** The letter or two shown when there is no image. */
+    readonly monogram: (site: string) => string;
+    readonly read: (site: string) => ImageReading<C, R>;
+    /** The service in a failure message: "Logo lookup". */
+    readonly service: string;
+}
+export type ImageStatus = 
+/** No site. */
+"idle"
+/** The service is being asked. */
+ | "loading"
+/** There is an image to show. It may still fail to load: see `imageFailed`. */
+ | "ready"
+/** There is no image: the letter is shown. `reason` says why. */
+ | "fallback"
+/** The site is not valid. The letter is shown. */
+ | "invalid"
+/** The call failed; `error` says how. The letter is shown. */
+ | "error";
+/** Why the letter is shown instead of an image. */
+export type FallbackReason = 
+/** The image failed to load in the browser. */
+"failed"
+/** The service has no image for the site. */
+ | "missing"
+/** The service named an image outside the hosts the profile allows: it was never loaded. */
+ | "blocked";
+export interface ImageError {
+    readonly code: string;
+    /** What the technical error said, for a developer: never shown to the end user. */
+    readonly detail: string;
+    readonly message: string;
+    /** A failed call is never shown as "no image". */
+    readonly outcome: Outcome;
+    readonly requestId: string | undefined;
+    readonly retryable: boolean;
+}
+export interface ImageState<R> {
+    readonly error: ImageError | undefined;
+    /** The accessible name of the image. */
+    readonly label: string;
+    /** The letter shown when there is no image. */
+    readonly monogram: string;
+    /** Set with the status "fallback". */
+    readonly reason: FallbackReason | undefined;
+    /** The answer, once the service has given one. */
+    readonly record: R | undefined;
+    readonly site: string;
+    readonly status: ImageStatus;
+    /** The image to load, set with the status "ready". Always on an allowed origin. */
+    readonly url: string | undefined;
+}
+export interface ImageControllerOptions<C, R> {
+    /** Any client of the product's API: server, browser (relay) or fixtures. */
+    readonly client: C;
+    /** Origins to allow besides the profile's, for a development host. */
+    readonly extraOrigins?: readonly string[];
+    /** Called when the call failed, after the state is updated. */
+    readonly onError?: (error: ImageError) => void;
+    /** Called when the letter is shown instead of an image, after the state is updated. */
+    readonly onFallback?: (reason: FallbackReason) => void;
+    /** Called once when the service has answered, after the state is updated. */
+    readonly onResult?: (record: R) => void;
+    readonly profile: ImageProfile<C, R>;
+    /** The site to start with. */
+    readonly site?: string;
+}
+export interface ImageController<R> {
+    /** Stops every call. The controller does nothing afterwards. */
+    dispose: () => void;
+    /** The current state. The same object until the state changes. */
+    getState: () => ImageState<R>;
+    /** Tells the controller that the browser could not load the image: the letter is shown. */
+    imageFailed: () => void;
+    /** Runs again the call that failed. */
+    retry: () => void;
+    /** The site the image is for. The service is asked at once; a late answer for an earlier site is dropped. */
+    setSite: (site: string) => void;
+    /** Calls the listener after every change. Returns the function that stops it. */
+    subscribe: (listener: () => void) => () => void;
+}

package/dist/runtime/image-types.js

@@ -0,0 +1,8 @@
+// Runtime template: copied into a generated client package as src/runtime/image-types.ts, with
+// image-controller.ts, when the product has an image element (generate.config.json, "ui", kind
+// "image"). The types of the headless image controller and of the per-product profile.
+//
+// An image element shows a picture of a website (a logo) that the service resolved. The browser only
+// ever loads an image from a Comms.ID host the profile names, so a visitor's address never reaches a
+// third party, and it always has something to show: a letter in the same box when there is no image.
+export {};

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

@@ -0,0 +1,12 @@
+import { type Environment } from "./environment.js";
+import type { TransportConfig } from "./http.js";
+export interface PublicOptions {
+    /** Another host. It wins over `environment`. */
+    readonly baseUrl?: string;
+    readonly deadlineMs?: number;
+    /** "live" (the default) or "test". */
+    readonly environment?: Environment;
+    readonly fetch?: typeof fetch;
+    readonly maxRetries?: number;
+}
+export declare const createPublicTransport: (options?: PublicOptions) => TransportConfig;