@cosmoops/connect-sdk 0.30.1 → 0.32.0

package/dist/esm/client/use-push.js

@@ -0,0 +1,136 @@
+"use client";
+import { useCallback, useState, useSyncExternalStore } from "react";
+import { useConnect } from "./provider.js";
+/**
+ * Read the browser's own permission as external state.
+ *
+ * Not `useState` in an effect: the permission belongs to the browser, it can
+ * change from the address bar while the page is open, and it does not exist
+ * during a server render. `useSyncExternalStore` is the primitive for exactly
+ * that - a server snapshot of `"checking"` and a live client one.
+ */
+function subscribeToPermission(onChange) {
+    let status = null;
+    let cancelled = false;
+    // Absent on some Safari builds, and throws on others. Neither is fatal:
+    // without the subscription the snapshot is still correct on every render, it
+    // simply will not update by itself.
+    navigator.permissions
+        ?.query({ name: "notifications" })
+        .then((result) => {
+        if (cancelled)
+            return;
+        status = result;
+        result.addEventListener("change", onChange);
+    })
+        .catch(() => { });
+    return () => {
+        cancelled = true;
+        status?.removeEventListener("change", onChange);
+    };
+}
+function permissionSnapshot() {
+    if (typeof navigator === "undefined" ||
+        !("serviceWorker" in navigator) ||
+        typeof window === "undefined" ||
+        !("PushManager" in window) ||
+        !("Notification" in window)) {
+        return "unsupported";
+    }
+    if (Notification.permission === "denied")
+        return "denied";
+    return Notification.permission === "granted" ? "granted" : "prompt";
+}
+const serverSnapshot = () => "checking";
+/**
+ * Register this browser for the platform's notifications.
+ *
+ * The subscription is **Connect's, not your application's**: a member who
+ * turns notifications on in one app has turned them on for the platform, and
+ * the same device receives every other app's notifications and Connect's own.
+ * That is the point of centralising it - one browser prompt instead of one per
+ * app, and one place to turn everything off.
+ *
+ * Your application needs a service worker at its own origin that handles the
+ * `push` event; the SDK does not install one, because a worker is a
+ * site-wide concern with caching implications only the host can decide.
+ *
+ * @param serviceWorkerUrl Where your worker lives. Root-scoped by convention.
+ */
+export function useConnectPush(serviceWorkerUrl = "/sw.js") {
+    const { fetchResource, mutateResource } = useConnect();
+    const permission = useSyncExternalStore(subscribeToPermission, permissionSnapshot, serverSnapshot);
+    const [isEnabling, setIsEnabling] = useState(false);
+    const [error, setError] = useState(null);
+    const [unconfigured, setUnconfigured] = useState(false);
+    const enable = useCallback(async () => {
+        setError(null);
+        setIsEnabling(true);
+        try {
+            /*
+             * The key first, and the order matters: if the platform cannot send,
+             * asking for permission spends the member's one prompt on a feature
+             * that will never deliver - and a denial cannot be re-asked.
+             */
+            const key = await fetchResource("/push/key");
+            if (!key.configured || !key.publicKey) {
+                setUnconfigured(true);
+                return null;
+            }
+            if ((await Notification.requestPermission()) !== "granted")
+                return null;
+            const registration = await navigator.serviceWorker.register(serviceWorkerUrl);
+            // `ready` rather than the registration itself: one that is still
+            // installing has no `pushManager`, and subscribing against it throws in
+            // a way that reads as a permission problem.
+            await navigator.serviceWorker.ready;
+            const subscription = await registration.pushManager.subscribe({
+                // Required, and it may not be false - a silent push is reserved for
+                // sites with a far higher engagement bar, and asking for one here has
+                // the browser refuse the subscription outright.
+                userVisibleOnly: true,
+                applicationServerKey: base64UrlToBytes(key.publicKey),
+            });
+            const json = subscription.toJSON();
+            const registered = await mutateResource("/push/subscribe", {
+                endpoint: json.endpoint,
+                keys: { p256dh: json.keys?.p256dh, auth: json.keys?.auth },
+            });
+            return registered.id;
+        }
+        catch {
+            setError("This browser would not register for notifications. Reload the page and try again.");
+            return null;
+        }
+        finally {
+            setIsEnabling(false);
+        }
+    }, [fetchResource, mutateResource, serviceWorkerUrl]);
+    const disable = useCallback(async (deviceId) => {
+        await mutateResource("/push/unsubscribe", { id: deviceId });
+    }, [mutateResource]);
+    return {
+        status: unconfigured && permission !== "denied" ? "unconfigured" : permission,
+        isEnabling,
+        error,
+        enable,
+        disable,
+    };
+}
+/**
+ * The VAPID public key as the bytes `pushManager.subscribe()` wants.
+ *
+ * It travels base64url and the API takes a `BufferSource`. Spelled out rather
+ * than inlined because getting it wrong produces an `InvalidAccessError` that
+ * reads as a permissions fault rather than an encoding one - and the explicit
+ * `ArrayBuffer` matters too: `Uint8Array.from` widens to `ArrayBufferLike`,
+ * which `applicationServerKey` will not accept.
+ */
+function base64UrlToBytes(base64) {
+    const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), "=");
+    const raw = atob(padded.replace(/-/g, "+").replace(/_/g, "/"));
+    const bytes = new Uint8Array(new ArrayBuffer(raw.length));
+    for (let index = 0; index < raw.length; index += 1)
+        bytes[index] = raw.charCodeAt(index);
+    return bytes;
+}

package/dist/esm/server/client.js

@@ -20,6 +20,7 @@ import { AnalyticsResource } from "./resources/analytics.js";
 import { OtpResource } from "./resources/otp.js";
 import { SessionsResource } from "./resources/sessions.js";
 import { PlatformResource } from "./resources/platform.js";
+import { PushResource } from "./resources/push.js";
 export const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 const APPLICATION_API_PREFIX = "/api/v1/application";
 /**
@@ -113,6 +114,11 @@ export class ConnectClient {
     workspaces;
     /** The platform's own legal identity and DPDP grievance channel - see `PlatformResource`. */
     platform;
+    /**
+     * Web Push. Connect holds the VAPID keys, the devices and the member's own
+     * preferences; you supply a title, a body and a URL. See `PushResource`.
+     */
+    push;
     /**
      * Relays one `/data/*` or `/kv/*` request verbatim - `createConnectHandler`'s
      * store route and nothing else. See `storePassthrough`.
@@ -157,8 +163,9 @@ export class ConnectClient {
         this.integrations = new IntegrationsResource(transport);
         this.workspaces = new WorkspacesResource(transport);
         this.platform = new PlatformResource(transport);
+        this.push = new PushResource(transport);
         this.storeRelay = (spec) => storePassthrough(transport, spec);
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.30.1";
+export const SDK_VERSION = "0.32.0";

package/dist/esm/server/handler.js

@@ -513,6 +513,60 @@ export function createConnectHandler(options) {
          * switching is simply absent for them rather than half-working - the same
          * treatment `/signin` and `/callback` already get.
          */
+        /*
+         * Push notifications - the browser half, and deliberately only that half.
+         *
+         * **There is no `POST /push` here**, and its absence is the design: a
+         * notification anybody can trigger from a devtools console is one an
+         * attacker can trigger from a compromised page, wearing the styling of an
+         * app the person trusts. Sending is a server-to-server act with your API
+         * key; Connect's own route refuses the session-token path outright.
+         *
+         * What a browser legitimately does is register itself, because
+         * `pushManager.subscribe()` produces a subscription no server can make on
+         * its behalf. All three routes resolve the member from their session, so
+         * there is no `userId` anywhere on this surface - a page cannot register a
+         * device against somebody else's account, nor list theirs.
+         */
+        "GET /push/key": async (request) => json(await client.push.key({ asUser: await requireToken(request) })),
+        "POST /push/subscribe": async (request) => {
+            const token = await requireToken(request);
+            const body = (await request.json().catch(() => null));
+            // Shape-checked here rather than relayed blindly, so a malformed
+            // subscription fails with a sentence naming what is missing instead of
+            // a Zod message from a server the page cannot see.
+            if (typeof body?.endpoint !== "string" ||
+                typeof body.keys?.p256dh !== "string" ||
+                typeof body.keys?.auth !== "string") {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "endpoint and keys.p256dh/keys.auth are required",
+                    endpoint: "POST /push/subscribe",
+                });
+            }
+            return json(await client.push.registerDevice({
+                endpoint: body.endpoint,
+                keys: { p256dh: body.keys.p256dh, auth: body.keys.auth },
+                // Taken from the request rather than the body: a page can put
+                // anything in a field, and this one is shown back on a device
+                // list where a spoofed entry would be the point of spoofing it.
+                userAgent: (request.headers.get("user-agent") ?? "").slice(0, 512),
+            }, { asUser: token }));
+        },
+        "POST /push/unsubscribe": async (request) => {
+            const token = await requireToken(request);
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.id !== "string") {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "id is required",
+                    endpoint: "POST /push/unsubscribe",
+                });
+            }
+            return json(await client.push.revokeDevice(body.id, { asUser: token }));
+        },
         "GET /workspaces": async (request) => json({ workspaces: await client.workspaces.list({ asUser: await requireToken(request) }) }),
         "GET /workspaces/members": async (request) => json({ members: await client.workspaces.members({ asUser: await requireToken(request) }) }),
         "POST /workspaces/switch": async (request) => {

package/dist/esm/server/resources/ai.js

@@ -104,4 +104,39 @@ export class AiResource {
         });
         return result.data;
     }
+    /**
+     * Draft every section of a platform-defined assessment from one sentence.
+     *
+     * The intended flow is draft first, then let the person correct it section
+     * by section: a blank questionnaire is the reason most people abandon one,
+     * and editing a strawman is a far smaller ask than authoring from nothing.
+     *
+     * Unattributed - assessments run against platform-wide definitions and the
+     * first consumers run before anyone has signed in, so there is no `asUser`
+     * and no workspace here.
+     */
+    async draftAssessment(input) {
+        const result = await request(this.transport, {
+            method: "POST",
+            path: "/ai/assessment/draft",
+            json: input,
+        });
+        return result.data;
+    }
+    /**
+     * Critique a completed assessment - the tensions between sections, the
+     * riskiest assumption, and a coarse score.
+     *
+     * Unknown section keys in `answers` are ignored rather than rejected, so a
+     * definition changing under a half-finished assessment costs the reader
+     * nothing.
+     */
+    async reviewAssessment(input) {
+        const result = await request(this.transport, {
+            method: "POST",
+            path: "/ai/assessment/review",
+            json: input,
+        });
+        return result.data;
+    }
 }

package/dist/esm/server/resources/enrichment.js

@@ -49,4 +49,52 @@ export class EnrichmentResource {
             signal: options.signal,
         });
     }
+    /**
+     * What the company at a domain **looks like** - logo, palette, typefaces,
+     * and the radius, spacing and breakpoint scales its own stylesheets declare.
+     *
+     * The sibling of `company()` above: that one answers what a company does,
+     * this one answers what it looks like. Useful for white-labelling a portal
+     * to a customer's brand, pre-filling a design brief, or showing a real
+     * account card instead of a grey placeholder.
+     *
+     * Needs an API key scoped to **`enrichment:brand`** - separate from
+     * `enrichment:read` because it is far more expensive: it crawls
+     * stylesheets, may render the page in a headless browser, and caches image
+     * bytes.
+     *
+     * ```ts
+     * const result = await connect.enrichment.brand({ domain: "acme.com" });
+     * if (result.status === "extracted") {
+     *   const primary = result.profile.brandKit.palette.find((c) => c.role === "primary");
+     * }
+     * ```
+     *
+     * Three things to know before wiring it in:
+     *
+     * - **Set your client timeout to at least 90 seconds.** A cold read runs
+     *   the whole extraction before answering and can take up to a minute; many
+     *   HTTP clients default to 30s and abandon a request that was about to
+     *   succeed. Cached reads return in milliseconds, and cached is the normal
+     *   case - profiles are held for 90 days, so you pay the cold path roughly
+     *   once per domain.
+     * - **Never store `brandKit.logos[].url`.** It is a short-lived signed URL
+     *   minted per read. Render it directly or re-read the profile; persist
+     *   `sourceUrl` if you need something stable.
+     * - **The values were measured, not generated.** Check `palette[].source` -
+     *   a `css-var` entry is the company naming its own colour, a `frequency`
+     *   entry is a ranked count and much weaker.
+     */
+    brand(input, options = {}) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/enrichment/brand",
+            json: {
+                domain: input.domain,
+                ...(input.refresh ? { refresh: true } : {}),
+            },
+            headers: actingAs(input.asUser),
+            signal: options.signal,
+        });
+    }
 }

package/dist/esm/server/resources/push.js

@@ -0,0 +1,88 @@
+import { request } from "../http.js";
+import { actingAs } from "./acting-as.js";
+/**
+ * Web Push, with Connect holding everything that makes it work.
+ *
+ * Your application supplies a title, a body, a URL and the members to reach.
+ * Connect owns the VAPID keys it signs with, the devices each member has
+ * registered across every application on the platform, that member's own
+ * notification preferences, and the bookkeeping when a browser goes away.
+ *
+ * So you never hold a push credential, never store an endpoint, and cannot
+ * reach anybody who is not an active member of the workspace you name -
+ * membership is re-checked on every send rather than trusted from the ids you
+ * pass.
+ *
+ * ## Two halves, and only `send` belongs on your server
+ *
+ * Registering a device happens in the **browser**, because a subscription is
+ * produced by `pushManager.subscribe()` against the member's own browser and
+ * no server can make one for them. `registerDevice` and `revokeDevice` below
+ * therefore take a session token and are what the SDK bridge calls on the
+ * browser's behalf - see `createConnectHandler`. You will normally reach them
+ * through `useConnectPush()` in `@cosmoops/connect-sdk/client` rather than
+ * directly.
+ */
+export class PushResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Notify members of a workspace.
+     *
+     * **`delivered: 0` is a success, not a failure.** The member may have
+     * registered no device, silenced notifications from their apps, or denied
+     * the browser prompt - all ordinary. A caller that retries on zero will
+     * retry forever against somebody who has opted out.
+     *
+     * Treat every send as a nudge toward something already true in your own
+     * data, and never let a failure here fail the thing that triggered it: the
+     * reminder is worth less than the record it is about.
+     *
+     * `url` must be absolute and on an origin this application registered as an
+     * SSO redirect URI. Connect refuses anything else, because a URL it did not
+     * check is an open redirect delivered to a lock screen.
+     */
+    send(input) {
+        return request(this.transport, { method: "POST", path: "/push", json: input });
+    }
+    /**
+     * The VAPID public key a browser needs before it can subscribe, and whether
+     * the platform can send at all.
+     *
+     * Safe to hand to any signed-in caller: it is the verification half of the
+     * pair, so holding it lets a browser *receive* what Connect signs and never
+     * send anything.
+     */
+    key(options) {
+        return request(this.transport, {
+            method: "GET",
+            path: "/push/subscriptions",
+            headers: actingAs(options.asUser),
+        });
+    }
+    /** Register one browser, from a subscription that browser just produced. */
+    registerDevice(input, options) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/push/subscriptions",
+            json: input,
+            headers: actingAs(options.asUser),
+        });
+    }
+    /**
+     * Stop notifications on one browser.
+     *
+     * The id is the one `registerDevice` returned. Connect re-checks that it
+     * belongs to the calling member, so a guessed id is a refusal rather than
+     * somebody else's device going quiet.
+     */
+    revokeDevice(id, options) {
+        return request(this.transport, {
+            method: "DELETE",
+            path: `/push/subscriptions?id=${encodeURIComponent(id)}`,
+            headers: actingAs(options.asUser),
+        });
+    }
+}

package/dist/types/client/index.d.ts

@@ -41,6 +41,13 @@ export type { ConnectShellContextValue } from "./components/shell-context.js";
 export { ConnectSidebarNav, ConnectSideNav } from "./components/side-nav.js";
 export type { ConnectSidebarNavProps, ConnectSideNavProps } from "./components/side-nav.js";
 export { useActivePath } from "./use-active-path.js";
+/**
+ * Web Push. The hook owns the browser half - permission, the worker, the
+ * subscription - and Connect owns the keys, the devices and the member's
+ * preferences. Sending is server-side, through `connect.push.send`.
+ */
+export { useConnectPush } from "./use-push.js";
+export type { ConnectPushStatus, UseConnectPush } from "./use-push.js";
 export { normalizeNav, flattenNav, normalizePath, resolveActivePath, isNavItemActive, gateExemptPaths, filterNavForAudience, } from "./components/nav.js";
 export type { ConnectNav, ConnectNavItem, ConnectNavSection, ConnectNavLinkProps, ConnectLinkRenderer, } from "./components/nav.js";
 export type { ConnectScreen } from "../types.js";

package/dist/types/client/use-push.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Whether this browser can show notifications, and whether it has been asked.
+ *
+ * Five states, not a boolean - and that is the whole reason this hook exists
+ * rather than a `<Switch>`:
+ *
+ * - `unsupported` - no service worker or no Push API. On iOS this is every
+ *   browser until the site is added to the home screen, which is worth saying
+ *   out loud because it is most of the phones in some markets.
+ * - `unconfigured` - the platform has no VAPID keys, so nothing could be
+ *   delivered even if permission were granted.
+ * - `denied` - **and this one cannot be undone by script.** A browser will not
+ *   show the prompt again once told no; only the site-settings panel in the
+ *   address bar can reverse it. A control that silently does nothing when
+ *   pressed is the worst version of this screen, so the state is surfaced and
+ *   the UI is expected to explain it.
+ * - `prompt` - askable.
+ * - `granted` - permission held. It does **not** follow that this browser is
+ *   registered with Connect; permission and registration are separate facts,
+ *   and a member who cleared site data holds the first without the second.
+ */
+export type ConnectPushStatus = "checking" | "unsupported" | "unconfigured" | "denied" | "prompt" | "granted";
+export interface UseConnectPush {
+    status: ConnectPushStatus;
+    /** True while `enable()` is in flight. */
+    isEnabling: boolean;
+    /** The last failure, in words a person can act on. Cleared by the next attempt. */
+    error: string | null;
+    /**
+     * Ask for permission, register this browser with Connect, and resolve the
+     * device id - or `null` if the member declined or anything refused.
+     *
+     * Must be called from a user gesture: browsers refuse
+     * `Notification.requestPermission()` outside one, and the refusal is
+     * indistinguishable from the member saying no.
+     */
+    enable: () => Promise<string | null>;
+    /** Stop notifications on one browser, by the id `enable()` returned. */
+    disable: (deviceId: string) => Promise<void>;
+}
+/**
+ * Register this browser for the platform's notifications.
+ *
+ * The subscription is **Connect's, not your application's**: a member who
+ * turns notifications on in one app has turned them on for the platform, and
+ * the same device receives every other app's notifications and Connect's own.
+ * That is the point of centralising it - one browser prompt instead of one per
+ * app, and one place to turn everything off.
+ *
+ * Your application needs a service worker at its own origin that handles the
+ * `push` event; the SDK does not install one, because a worker is a
+ * site-wide concern with caching implications only the host can decide.
+ *
+ * @param serviceWorkerUrl Where your worker lives. Root-scoped by convention.
+ */
+export declare function useConnectPush(serviceWorkerUrl?: string): UseConnectPush;

package/dist/types/server/client.d.ts

@@ -21,6 +21,7 @@ import { AnalyticsResource } from "./resources/analytics.js";
 import { OtpResource } from "./resources/otp.js";
 import { SessionsResource } from "./resources/sessions.js";
 import { PlatformResource } from "./resources/platform.js";
+import { PushResource } from "./resources/push.js";
 export declare const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 export interface ConnectClientOptions {
     /**
@@ -112,6 +113,11 @@ export declare class ConnectClient {
     readonly workspaces: WorkspacesResource;
     /** The platform's own legal identity and DPDP grievance channel - see `PlatformResource`. */
     readonly platform: PlatformResource;
+    /**
+     * Web Push. Connect holds the VAPID keys, the devices and the member's own
+     * preferences; you supply a title, a body and a URL. See `PushResource`.
+     */
+    readonly push: PushResource;
     /**
      * Relays one `/data/*` or `/kv/*` request verbatim - `createConnectHandler`'s
      * store route and nothing else. See `storePassthrough`.
@@ -126,4 +132,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.30.1";
+export declare const SDK_VERSION = "0.32.0";

package/dist/types/server/resources/ai.d.ts

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { AiConversationDetail, AiConversationList, ChatMessage, ConnectScreen } from "../../types.js";
+import type { AiConversationDetail, AiConversationList, AssessmentAnswers, AssessmentDraft, AssessmentReview, ChatMessage, ConnectScreen } from "../../types.js";
 /**
  * RAG chat and structured extraction against a workspace's data.
  *
@@ -87,4 +87,31 @@ export declare class AiResource {
         schemaId: string;
         fileUrl: string;
     }): Promise<T>;
+    /**
+     * Draft every section of a platform-defined assessment from one sentence.
+     *
+     * The intended flow is draft first, then let the person correct it section
+     * by section: a blank questionnaire is the reason most people abandon one,
+     * and editing a strawman is a far smaller ask than authoring from nothing.
+     *
+     * Unattributed - assessments run against platform-wide definitions and the
+     * first consumers run before anyone has signed in, so there is no `asUser`
+     * and no workspace here.
+     */
+    draftAssessment(input: {
+        assessmentKey: string;
+        seed: string;
+    }): Promise<AssessmentDraft>;
+    /**
+     * Critique a completed assessment - the tensions between sections, the
+     * riskiest assumption, and a coarse score.
+     *
+     * Unknown section keys in `answers` are ignored rather than rejected, so a
+     * definition changing under a half-finished assessment costs the reader
+     * nothing.
+     */
+    reviewAssessment(input: {
+        assessmentKey: string;
+        answers: AssessmentAnswers;
+    }): Promise<AssessmentReview>;
 }

package/dist/types/server/resources/enrichment.d.ts

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { CompanyEnrichmentResult } from "../../types.js";
+import type { BrandExtractionResult, CompanyEnrichmentResult } from "../../types.js";
 /**
  * What Connect knows about the company at a domain.
  *
@@ -41,4 +41,49 @@ export declare class EnrichmentResource {
     }, options?: {
         signal?: AbortSignal;
     }): Promise<CompanyEnrichmentResult>;
+    /**
+     * What the company at a domain **looks like** - logo, palette, typefaces,
+     * and the radius, spacing and breakpoint scales its own stylesheets declare.
+     *
+     * The sibling of `company()` above: that one answers what a company does,
+     * this one answers what it looks like. Useful for white-labelling a portal
+     * to a customer's brand, pre-filling a design brief, or showing a real
+     * account card instead of a grey placeholder.
+     *
+     * Needs an API key scoped to **`enrichment:brand`** - separate from
+     * `enrichment:read` because it is far more expensive: it crawls
+     * stylesheets, may render the page in a headless browser, and caches image
+     * bytes.
+     *
+     * ```ts
+     * const result = await connect.enrichment.brand({ domain: "acme.com" });
+     * if (result.status === "extracted") {
+     *   const primary = result.profile.brandKit.palette.find((c) => c.role === "primary");
+     * }
+     * ```
+     *
+     * Three things to know before wiring it in:
+     *
+     * - **Set your client timeout to at least 90 seconds.** A cold read runs
+     *   the whole extraction before answering and can take up to a minute; many
+     *   HTTP clients default to 30s and abandon a request that was about to
+     *   succeed. Cached reads return in milliseconds, and cached is the normal
+     *   case - profiles are held for 90 days, so you pay the cold path roughly
+     *   once per domain.
+     * - **Never store `brandKit.logos[].url`.** It is a short-lived signed URL
+     *   minted per read. Render it directly or re-read the profile; persist
+     *   `sourceUrl` if you need something stable.
+     * - **The values were measured, not generated.** Check `palette[].source` -
+     *   a `css-var` entry is the company naming its own colour, a `frequency`
+     *   entry is a ranked count and much weaker.
+     */
+    brand(input: {
+        /** A domain or a URL in any form - `acme.com`, `www.acme.com`, `https://acme.com/pricing`. */
+        domain: string;
+        asUser?: string;
+        /** Re-extract even if Connect has a fresh profile cached. For an operator pressing "refresh" - not for automatic calls. */
+        refresh?: boolean;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<BrandExtractionResult>;
 }