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

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2026 COMMS.ID PTY LTD. Proprietary software; not open source.
+
+Subject to the Comms.ID policy agreement, you may install, copy, bundle, run and
+deliver this client or component within your applications, adapt the supplied
+component source, and use the designated local functions and fixtures offline.
+Hosted operations are provided by the Comms.ID service.
+
+You may keep replies for your own customers and transactions, and your registered
+application may relay requests for its own users.
+
+You may not republish these packages as a standalone offering, resell access, offer
+a substitute lookup service, or harvest replies to reconstruct or redistribute a
+source dataset.
+
+Preserve this notice and any applicable third-party notices.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @comms-id/website-logo
 
-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.
+Typed client for the Comms.ID Website logo API (`https://api.comms.id/logo/v1`): a company's logo, resolved from its website address.
+
+`src/` is generated from the Website logo contract (`packages/website-logo-service/openapi/website-logo.v1.json`) by `@comms-id/forge-transformers`. Do not edit it: change the contract and run `pnpm --filter @comms-id/forge-transformers generate`.
+
+```ts
+import { createWebsiteLogoClient } from "@comms-id/website-logo/server";
+
+const client = createWebsiteLogoClient({
+  clientId: process.env.COMMS_ID_CLIENT_ID!,
+  privateJwk: JSON.parse(process.env.COMMS_ID_PRIVATE_JWK!),
+});
+const reply = await client.resolve({"hostname": "example.com", "mode": "direct-favicon"});
+```
+
+## Operations
+
+- `resolve`: Resolve a website logo using the selected source or named composition. A genuine miss is a 200 reply with status missing; source failures remain distinct.
+
+Every operation is a read, safe to repeat, and is retried after a retryable failure. A reply that is not a match is one of the outcomes of the reply convention: an error with `outcomeOf(error)` of `no-match`, `source-unavailable` or `failed`; an outage is never a "no match".
+
+## Test it first
+
+`createWebsiteLogoFixtureClient()` from `@comms-id/website-logo/fixtures` answers from the contract's own examples with no network and says so (`fixture: true`). To call the TEST service (synthetic replies, your development app's key), pass `environment: "test"`; going live changes only the environment and the key.
+
+`COMMS_ID_PRIVATE_JWK` is an ML-DSA-87 private JWK (`kty` `AKP`, with `priv` and `pub`). The server entry needs Node.js 24.7 or later, or a Cloudflare Worker with the compatibility flag `webcrypto_modern_algorithms`.
+
+Entries: `.` (types and errors, safe in a browser), `./server` (signs each call), `./browser` (your relay route; never signs), `./fixtures` (LOCAL FIXTURES, no network), `./descriptor` (what `@comms-id/relay` may forward).
+
+`LICENSE` is the consumer client licence.
+
+## The image
+
+`@comms-id/website-logo/controller` is the headless controller of a Website logo image: it asks the service about a site and decides what to show, and it refuses any image outside the Comms.ID hosts. It has no framework and no DOM. `@comms-id/website-logo-react` (a hook and a component) and `<comms-id-website-logo>` (a web element) run on it, and so can your own UI.
+
+```ts
+import { createWebsiteLogoController } from "@comms-id/website-logo/controller";
+
+const controller = createWebsiteLogoController({ client, site: "example.com" });
+controller.subscribe(() => render(controller.getState())); // state.url is the image to load, or the letter state.monogram
+```
+
+`src/local/profile.ts` is the only product-specific part: it reads the site, prepares the call and takes the Comms.ID image from the reply. Everything else is generated.

package/dist/browser.d.ts

@@ -0,0 +1,5 @@
+import { type WebsiteLogoClient } from "./generated/client.js";
+import { type BrowserOptions } from "./runtime/browser-core.js";
+export type { Environment } from "./runtime/environment.js";
+export type { BrowserOptions, CapabilityOptions, RelayOptions } from "./runtime/browser-core.js";
+export declare const createWebsiteLogoBrowserClient: (options: BrowserOptions) => WebsiteLogoClient;

package/dist/browser.js

@@ -0,0 +1,6 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+// Browser entry: it never signs and holds no secret. Use the consumer's relay route, or a
+// short-lived capability that the caller supplies.
+import { buildClient } from "./generated/client.js";
+import { createBrowserTransport } from "./runtime/browser-core.js";
+export const createWebsiteLogoBrowserClient = (options) => buildClient(createBrowserTransport(options));

package/dist/controller.d.ts

@@ -0,0 +1,13 @@
+import type { WebsiteLogoClient } from "./generated/client.js";
+import { type ProductRecord, profile } from "./local/profile.js";
+import type { ImageController, ImageControllerOptions, ImageState } from "./runtime/image-types.js";
+export { initialImageState, isAllowedImage } from "./runtime/image-controller.js";
+export type { FallbackReason, ImageError, ImageProfile, ImageReading, ImageState, ImageStatus, Resolved, Run, } from "./runtime/image-types.js";
+export type { WebsiteLogoClient } from "./generated/client.js";
+export { profile };
+export type { ProductRecord as WebsiteLogoRecord };
+export type WebsiteLogoController = ImageController<ProductRecord>;
+export type WebsiteLogoControllerOptions = Omit<ImageControllerOptions<WebsiteLogoClient, ProductRecord>, "profile">;
+export type WebsiteLogoState = ImageState<ProductRecord>;
+/** Creates the controller. Nothing is called until a site is set. */
+export declare const createWebsiteLogoController: (options: WebsiteLogoControllerOptions) => WebsiteLogoController;

package/dist/controller.js

@@ -0,0 +1,9 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+// Controller entry: the headless controller of the Comms.ID Website logo image and the product's profile.
+// No framework, no DOM. The React package and the web element run on it.
+import { profile } from "./local/profile.js";
+import { createImageController } from "./runtime/image-controller.js";
+export { initialImageState, isAllowedImage } from "./runtime/image-controller.js";
+export { profile };
+/** Creates the controller. Nothing is called until a site is set. */
+export const createWebsiteLogoController = (options) => createImageController({ ...options, profile });

package/dist/descriptor.d.ts

@@ -0,0 +1,11 @@
+export declare const websiteLogoProduct: {
+    readonly product: "website-logo";
+    readonly audience: "website-logo";
+    readonly scope: "website-logo";
+    readonly maxBodyBytes: 16384;
+    readonly operations: readonly [{
+        readonly name: "resolve";
+        readonly method: "POST";
+        readonly path: "/website-logo/v1/resolve";
+    }];
+};

package/dist/descriptor.js

@@ -0,0 +1,15 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+// The product descriptor that @comms-id/relay reads: which operations may be forwarded.
+export const websiteLogoProduct = {
+    product: "website-logo",
+    audience: "website-logo",
+    scope: "website-logo",
+    maxBodyBytes: 16_384,
+    operations: [
+        {
+            "name": "resolve",
+            "method": "POST",
+            "path": "/website-logo/v1/resolve"
+        }
+    ],
+};

package/dist/fixtures.d.ts

@@ -0,0 +1,5 @@
+import { type WebsiteLogoClient } from "./generated/client.js";
+export { FIXTURE_HEADER, FIXTURE_NOTICE } from "./runtime/fixture-core.js";
+export declare const createWebsiteLogoFixtureClient: () => WebsiteLogoClient & {
+    readonly fixture: true;
+};

package/dist/fixtures.js

@@ -0,0 +1,10 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+// LOCAL FIXTURES: no network. The client runs the same request and reply checks as a real call.
+import { buildClient } from "./generated/client.js";
+import { fixtures } from "./generated/fixtures.js";
+import { createFixtureTransport } from "./runtime/fixture-core.js";
+export { FIXTURE_HEADER, FIXTURE_NOTICE } from "./runtime/fixture-core.js";
+export const createWebsiteLogoFixtureClient = () => ({
+    ...buildClient(createFixtureTransport(fixtures)),
+    fixture: true,
+});

package/dist/generated/client.d.ts

@@ -0,0 +1,8 @@
+import { type CallOptions, type TransportConfig } from "../runtime/http.js";
+import type { ResolveRequest, ResolveResponse } from "./types.js";
+/** The client of Comms.ID Website logo: one method for each operation. */
+export interface WebsiteLogoClient {
+    /** Resolve a website logo using the selected source or named composition. A genuine miss is a 200 reply with status missing; source failures remain distinct. */
+    readonly resolve: (input: ResolveRequest, options?: CallOptions) => Promise<ResolveResponse>;
+}
+export declare const buildClient: (transport: TransportConfig) => WebsiteLogoClient;

package/dist/generated/client.js

@@ -0,0 +1,6 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+import { call } from "../runtime/http.js";
+import { operations } from "./operations.js";
+export const buildClient = (transport) => ({
+    resolve: (input, options) => call(transport, operations.resolve, input, options),
+});

package/dist/generated/fixtures.d.ts

@@ -0,0 +1,2 @@
+/** LOCAL FIXTURES: one canned reply for each operation path. Fake data. */
+export declare const fixtures: Readonly<Record<string, unknown>>;

package/dist/generated/fixtures.js

@@ -0,0 +1,27 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+// Every reply is the example in the contract.
+/** LOCAL FIXTURES: one canned reply for each operation path. Fake data. */
+export const fixtures = {
+    "/website-logo/v1/resolve": {
+        "mode": "direct-favicon",
+        "status": "found",
+        "resolution": {
+            "resolved": true,
+            "logoUrl": "https://example.com/favicon.ico",
+            "source": "direct-favicon",
+            "hostname": "example.com",
+            "canonicalUrl": "https://example.com",
+            "redirectHostname": null,
+            "iframeBlocked": null,
+            "cached": false,
+            "imageUrl": "https://api.comms.id/website-logo/v1/image/ZGlyZWN0LWZhdmljb258ZXhhbXBsZS5jb218MTc5MTYzMzYwMA.c2lnbmF0dXJlLWV4YW1wbGUtc2lnbmF0dXJlLWV4YW1wbGUtMDA"
+        },
+        "outcomes": [
+            {
+                "source": "direct-favicon",
+                "outcome": "hit",
+                "code": null
+            }
+        ]
+    }
+};

package/dist/generated/operations.d.ts

@@ -0,0 +1,6 @@
+import type { Operation } from "../runtime/http.js";
+export type OperationName = "resolve";
+/** The operations of Comms.ID Website logo, with the schemas the client checks. */
+export declare const operations: Readonly<Record<OperationName, Operation>>;
+/** The error codes the contract documents for each operation. */
+export declare const errorCodes: Readonly<Record<OperationName, readonly string[]>>;

package/dist/generated/operations.js

@@ -0,0 +1,214 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+/** The operations of Comms.ID Website logo, with the schemas the client checks. */
+export const operations = {
+    resolve: {
+        name: "resolve",
+        method: "POST",
+        path: "/website-logo/v1/resolve",
+        safeToRetry: true,
+        request: {
+            "t": "obj",
+            "props": {
+                "hostname": {
+                    "t": "str",
+                    "max": 253
+                },
+                "url": {
+                    "t": "str",
+                    "max": 2048
+                },
+                "fresh": {
+                    "t": "bool"
+                },
+                "mode": {
+                    "t": "str",
+                    "values": [
+                        "composed",
+                        "microlink",
+                        "logo-dev",
+                        "direct-favicon"
+                    ]
+                }
+            },
+            "req": [],
+            "extra": false
+        },
+        response: {
+            "t": "obj",
+            "props": {
+                "mode": {
+                    "t": "str",
+                    "values": [
+                        "composed",
+                        "microlink",
+                        "logo-dev",
+                        "direct-favicon"
+                    ]
+                },
+                "status": {
+                    "t": "str",
+                    "values": [
+                        "found",
+                        "missing"
+                    ]
+                },
+                "resolution": {
+                    "t": "obj",
+                    "props": {
+                        "resolved": {
+                            "t": "bool"
+                        },
+                        "logoUrl": {
+                            "t": "any_of",
+                            "of": [
+                                {
+                                    "t": "str"
+                                },
+                                {
+                                    "t": "null"
+                                }
+                            ]
+                        },
+                        "source": {
+                            "t": "any_of",
+                            "of": [
+                                {
+                                    "t": "str",
+                                    "values": [
+                                        "microlink",
+                                        "logo.dev",
+                                        "direct-favicon"
+                                    ]
+                                },
+                                {
+                                    "t": "null"
+                                }
+                            ]
+                        },
+                        "hostname": {
+                            "t": "str"
+                        },
+                        "canonicalUrl": {
+                            "t": "any_of",
+                            "of": [
+                                {
+                                    "t": "str"
+                                },
+                                {
+                                    "t": "null"
+                                }
+                            ]
+                        },
+                        "redirectHostname": {
+                            "t": "any_of",
+                            "of": [
+                                {
+                                    "t": "str"
+                                },
+                                {
+                                    "t": "null"
+                                }
+                            ]
+                        },
+                        "iframeBlocked": {
+                            "t": "any_of",
+                            "of": [
+                                {
+                                    "t": "bool"
+                                },
+                                {
+                                    "t": "null"
+                                }
+                            ]
+                        },
+                        "cached": {
+                            "t": "bool"
+                        },
+                        "imageUrl": {
+                            "t": "any_of",
+                            "of": [
+                                {
+                                    "t": "str"
+                                },
+                                {
+                                    "t": "null"
+                                }
+                            ]
+                        }
+                    },
+                    "req": [
+                        "resolved",
+                        "logoUrl",
+                        "source",
+                        "hostname",
+                        "canonicalUrl",
+                        "redirectHostname",
+                        "iframeBlocked",
+                        "cached",
+                        "imageUrl"
+                    ],
+                    "extra": false
+                },
+                "outcomes": {
+                    "t": "arr",
+                    "of": {
+                        "t": "obj",
+                        "props": {
+                            "source": {
+                                "t": "str",
+                                "values": [
+                                    "microlink",
+                                    "logo.dev",
+                                    "direct-favicon"
+                                ]
+                            },
+                            "outcome": {
+                                "t": "str",
+                                "values": [
+                                    "hit",
+                                    "miss",
+                                    "error",
+                                    "timeout",
+                                    "skipped"
+                                ]
+                            },
+                            "code": {
+                                "t": "any_of",
+                                "of": [
+                                    {
+                                        "t": "str",
+                                        "values": [
+                                            "UPSTREAM_ERROR",
+                                            "TIMEOUT",
+                                            "MISSING_CREDENTIALS"
+                                        ]
+                                    },
+                                    {
+                                        "t": "null"
+                                    }
+                                ]
+                            }
+                        },
+                        "req": [
+                            "source",
+                            "outcome",
+                            "code"
+                        ],
+                        "extra": false
+                    }
+                }
+            },
+            "req": [
+                "mode",
+                "status",
+                "resolution",
+                "outcomes"
+            ],
+            "extra": false
+        },
+    },
+};
+/** The error codes the contract documents for each operation. */
+export const errorCodes = {
+    resolve: ["INVALID_INPUT", "UNAUTHORIZED", "ORIGIN_NOT_ALLOWED", "NOT_FOUND", "METHOD_NOT_ALLOWED", "LIMIT_REACHED", "FAIR_USE_CEILING", "CANCELLED", "INTERNAL_ERROR", "CONFIGURATION_ERROR", "UNAVAILABLE_MODE", "RESIDENCY_UNAVAILABLE", "HTTP_503"],
+};

package/dist/generated/types.d.ts

@@ -0,0 +1,29 @@
+/** The body of resolve. */
+export type ResolveRequest = {
+    readonly hostname?: string;
+    readonly url?: string;
+    readonly fresh?: boolean;
+    readonly mode?: "composed" | "microlink" | "logo-dev" | "direct-favicon";
+};
+/** The reply of resolve. */
+export type ResolveResponse = {
+    readonly mode: "composed" | "microlink" | "logo-dev" | "direct-favicon";
+    readonly status: "found" | "missing";
+    readonly resolution: {
+        readonly resolved: boolean;
+        readonly logoUrl: string | null;
+        readonly source: "microlink" | "logo.dev" | "direct-favicon" | null;
+        readonly hostname: string;
+        readonly canonicalUrl: string | null;
+        readonly redirectHostname: string | null;
+        readonly iframeBlocked: boolean | null;
+        readonly cached: boolean;
+        /** The image served by Comms.ID (https://api.comms.id/website-logo/v1/image/<id>), valid for seven days; null when nothing resolved. Show this one, not logoUrl. */
+        readonly imageUrl: string | null;
+    };
+    readonly outcomes: ReadonlyArray<{
+        readonly source: "microlink" | "logo.dev" | "direct-favicon";
+        readonly outcome: "hit" | "miss" | "error" | "timeout" | "skipped";
+        readonly code: "UPSTREAM_ERROR" | "TIMEOUT" | "MISSING_CREDENTIALS" | null;
+    }>;
+};

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 { WebsiteLogoClient } from "./generated/client.js";
+export { errorCodes, operations } from "./generated/operations.js";
+export type { OperationName } from "./generated/operations.js";
+export type { ResolveRequest, ResolveResponse } 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/local/profile.d.ts

@@ -0,0 +1,12 @@
+import type { WebsiteLogoClient } from "../generated/client.js";
+import type { ResolveRequest, ResolveResponse } from "../generated/types.js";
+import type { ImageProfile } from "../runtime/image-types.js";
+/** The reply of the lookup: the resolution of the site, with its outcomes. */
+export type ProductRecord = ResolveResponse;
+/** The hosts an image may be loaded from: the live and the TEST API. */
+export declare const IMAGE_ORIGINS: readonly ["https://api.comms.id", "https://api-test.comms.id"];
+/** The hostname of a site given as a hostname or a URL, or undefined when it is neither. */
+export declare const hostnameOf: (site: string) => string | undefined;
+/** The request for a site, or undefined when the site is not valid. */
+export declare const requestOf: (site: string) => ResolveRequest | undefined;
+export declare const profile: ImageProfile<WebsiteLogoClient, ProductRecord>;

package/dist/local/profile.js

@@ -0,0 +1,77 @@
+// The Website logo image's profile: the only logo-specific code of the image. It reads the site the
+// page gave (a hostname such as example.com, or a URL), prepares the call, and takes from the reply the
+// one image the browser may load: the Comms.ID copy named in `resolution.imageUrl`, never the
+// upstream `logoUrl`. The controller, the React package and the web element are generated and know
+// nothing else.
+//
+// The browser contacts only Comms.ID. The controller refuses any image outside `allowedOrigins`, so a
+// reply that names another host is shown as the letter, and a visitor's address is never sent to a
+// third party.
+/** The hosts an image may be loaded from: the live and the TEST API. */
+export const IMAGE_ORIGINS = ["https://api.comms.id", "https://api-test.comms.id"];
+const MAX_HOSTNAME = 253;
+const MAX_URL = 2048;
+const SCHEME = /^[a-z][a-z0-9+.-]*:\/\//i;
+const WWW = /^www\./;
+const HOSTNAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+const FIRST_LETTER = /[a-z0-9]/i;
+const TRAILING_DOT = /\.$/;
+/** The hostname of a site given as a hostname or a URL, or undefined when it is neither. */
+export const hostnameOf = (site) => {
+    const text = site.trim();
+    if (text === "") {
+        return;
+    }
+    if (SCHEME.test(text)) {
+        try {
+            const url = new URL(text);
+            return (url.protocol === "https:" || url.protocol === "http:") && url.hostname !== ""
+                ? url.hostname.toLowerCase()
+                : undefined;
+        }
+        catch {
+            return;
+        }
+    }
+    const host = text.toLowerCase().replace(TRAILING_DOT, "");
+    return host.length <= MAX_HOSTNAME && HOSTNAME.test(host) ? host : undefined;
+};
+/** The request for a site, or undefined when the site is not valid. */
+export const requestOf = (site) => {
+    const text = site.trim();
+    if (hostnameOf(text) === undefined) {
+        return;
+    }
+    if (SCHEME.test(text)) {
+        return text.length <= MAX_URL ? { url: text } : undefined;
+    }
+    return { hostname: text.toLowerCase().replace(TRAILING_DOT, "") };
+};
+export const profile = {
+    allowedOrigins: IMAGE_ORIGINS,
+    service: "Logo lookup",
+    label: (site) => {
+        const host = hostnameOf(site);
+        return host === undefined ? "Logo" : `${host.replace(WWW, "")} logo`;
+    },
+    monogram: (site) => {
+        const host = hostnameOf(site)?.replace(WWW, "");
+        return (host === undefined ? "" : (FIRST_LETTER.exec(host)?.[0] ?? "")).toUpperCase();
+    },
+    read: (site) => {
+        if (site.trim() === "") {
+            return { kind: "idle" };
+        }
+        const request = requestOf(site);
+        if (request === undefined) {
+            return { kind: "invalid", message: "Enter a website address such as example.com." };
+        }
+        return {
+            kind: "resolve",
+            run: async (client, options) => {
+                const record = await client.resolve(request, options);
+                return { record, url: record.resolution.imageUrl ?? undefined };
+            },
+        };
+    },
+};

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;