@cosmoops/connect-sdk 0.19.0 → 0.21.0

package/dist/esm/client/provider.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { clearOneTapSuppression, suppressOneTapAfterSignOut } from "./components/one-tap-state.js";
 export const CONNECT_APP_URL = "https://connect.cosmoops.com";
 const ConnectContext = createContext(null);
 /** Marks that this tab has already spent its one silent attempt - see `ConnectProviderProps.silentSignIn`. */
@@ -185,8 +186,91 @@ export function ConnectProvider({ clientId = "", basePath = "/api/connect", redi
             credentials: "same-origin",
         }).catch(() => { });
         cache.current.clear();
+        // Someone who just signed out must not be offered the same account back on
+        // the next render - see `suppressOneTapAfterSignOut`.
+        suppressOneTapAfterSignOut();
         setResult({ session: { user: null, subscription: null, role: null, permissions: [], staff: false, audience: null }, error: null });
     }, [basePath, fetchImpl]);
+    /**
+     * Where Connect answers One Tap, taken from the session read rather than
+     * assembled here - the bridge knows the `client_id` and the browser need not.
+     */
+    const oneTapEndpoints = result?.session.oneTap ?? null;
+    const readOneTapHint = useCallback(async () => {
+        if (!oneTapEndpoints)
+            return null;
+        try {
+            // `credentials: "include"` because this is the one request in the SDK
+            // that leaves the application's own origin. It carries the visitor's
+            // Connect cookie only when the two are same-site; everywhere else it is
+            // simply sent without one and comes back `signed_out`.
+            const response = await (fetchImpl ?? globalThis.fetch)(oneTapEndpoints.hintUrl, {
+                credentials: "include",
+                headers: { accept: "application/json" },
+            });
+            if (!response.ok)
+                return null;
+            return (await response.json());
+        }
+        catch {
+            // Offline, blocked, or Connect is down. None of those is evidence about
+            // whether this visitor has a session, so the honest answer is silence.
+            return null;
+        }
+    }, [fetchImpl, oneTapEndpoints]);
+    const oneTapSignIn = useCallback(async () => {
+        if (!oneTapEndpoints)
+            return { ok: false, reason: "unavailable" };
+        try {
+            // 1. The bridge mints the PKCE pair and keeps the verifier in an
+            //    `HttpOnly` cookie on this origin.
+            const start = await mutateResource("/one-tap/start");
+            // 2. Connect mints a code against that challenge. The custom header is
+            //    what forces the preflight, so an origin this client has not
+            //    registered is refused before the request is ever sent.
+            const authorize = await (fetchImpl ?? globalThis.fetch)(oneTapEndpoints.authorizeUrl, {
+                method: "POST",
+                credentials: "include",
+                headers: {
+                    accept: "application/json",
+                    "content-type": "application/json",
+                    "x-connect-one-tap": "1",
+                },
+                body: JSON.stringify({
+                    redirect_uri: start.redirectUri,
+                    code_challenge: start.codeChallenge,
+                }),
+            });
+            const body = (await authorize.json().catch(() => null));
+            if (!authorize.ok || !body?.code) {
+                // Connect names the reason, and each one has a different next step -
+                // `consent_required` wants the interactive screen, `rate_limited` wants
+                // to be left alone. Anything unrecognised is reported as a plain
+                // failure rather than guessed at.
+                const reason = body?.error;
+                return {
+                    ok: false,
+                    reason: reason === "login_required" ||
+                        reason === "consent_required" ||
+                        reason === "interaction_required" ||
+                        reason === "rate_limited"
+                        ? reason
+                        : "failed",
+                };
+            }
+            // 3. The bridge exchanges the code with the verifier the page never saw,
+            //    and stores the session.
+            await mutateResource("/one-tap/complete", { code: body.code });
+            // The prompt was accepted, so whatever backoff earlier dismissals had
+            // accumulated is spent - it described reluctance that no longer holds.
+            clearOneTapSuppression();
+            await refresh();
+            return { ok: true };
+        }
+        catch {
+            return { ok: false, reason: "failed" };
+        }
+    }, [fetchImpl, mutateResource, oneTapEndpoints, refresh]);
     const value = useMemo(() => ({
         clientId,
         appUrl,
@@ -200,6 +284,8 @@ export function ConnectProvider({ clientId = "", basePath = "/api/connect", redi
         mutateResource,
         invalidateResource,
         streamResource,
+        readOneTapHint,
+        oneTapSignIn,
     }), [
         clientId,
         appUrl,
@@ -213,6 +299,8 @@ export function ConnectProvider({ clientId = "", basePath = "/api/connect", redi
         mutateResource,
         invalidateResource,
         streamResource,
+        readOneTapHint,
+        oneTapSignIn,
     ]);
     return _jsx(ConnectContext.Provider, { value: value, children: children });
 }

package/dist/esm/server/client.js

@@ -5,6 +5,8 @@ import { DataResource, storePassthrough } from "./resources/data.js";
 import { WorkspacesResource } from "./resources/workspaces.js";
 import { SchedulingResource } from "./resources/scheduling.js";
 import { ContactsResource } from "./resources/contacts.js";
+import { ChannelsResource } from "./resources/channels.js";
+import { CallsResource } from "./resources/calls.js";
 import { KvResource } from "./resources/kv.js";
 import { BillingResource } from "./resources/billing.js";
 import { DriveResource } from "./resources/drive.js";
@@ -82,6 +84,10 @@ export class ConnectClient {
     scheduling;
     /** Who a workspace already knows how to reach, by phone or by id. */
     contacts;
+    /** The phone numbers Connect has assigned to your application, and where each one routes. */
+    channels;
+    /** The calls that arrived on those channels, with their transcripts. */
+    calls;
     /** RAG chat and structured extraction. */
     ai;
     /** Your application's own document store - see `DataResource`. */
@@ -132,6 +138,8 @@ export class ConnectClient {
         this.drive = new DriveResource(transport);
         this.scheduling = new SchedulingResource(transport);
         this.contacts = new ContactsResource(transport);
+        this.channels = new ChannelsResource(transport);
+        this.calls = new CallsResource(transport);
         this.ai = new AiResource(transport);
         this.data = new DataResource(transport);
         this.kv = new KvResource(transport);
@@ -146,4 +154,4 @@ export class ConnectClient {
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.19.0";
+export const SDK_VERSION = "0.21.0";

package/dist/esm/server/handler.js

@@ -1,5 +1,5 @@
 import { ConnectError } from "../errors.js";
-import { createState } from "./resources/identity.js";
+import { createPkcePair, createState } from "./resources/identity.js";
 /**
  * A sentinel origin to resolve a candidate destination against. Never reached -
  * `.invalid` is reserved by RFC 2606 precisely so it cannot resolve.
@@ -102,6 +102,7 @@ export function createConnectHandler(options) {
     const defaultRedirect = options.defaultRedirect ?? "/";
     const stateCookieName = options.stateCookieName ?? "connect_oauth_state";
     const silentCookieName = `${stateCookieName}_silent`;
+    const pkceCookieName = `${stateCookieName}_pkce`;
     const callbackPath = `${basePath}/callback`;
     /**
      * Short-lived, httpOnly, and `SameSite=Lax` - `Strict` would not be sent on
@@ -148,6 +149,35 @@ export function createConnectHandler(options) {
             .filter(Boolean)
             .join("; ");
     }
+    /**
+     * Holds the One Tap PKCE **verifier** for the few seconds between the tap and
+     * the exchange.
+     *
+     * This is the cookie the whole no-navigation flow rests on. Connect hands the
+     * authorization code to the *page*, so the code alone must not be enough to
+     * mint a session - the verifier is what completes it, and it never leaves
+     * this origin's cookie jar. `SameSite=Lax` is sufficient and correct: unlike
+     * the state cookie there is no cross-site redirect that has to carry it, and
+     * `Lax` additionally means a cross-site `POST` to `/one-tap/complete` arrives
+     * without it and simply fails.
+     *
+     * Five minutes, not the state cookie's fifteen: it is minted on the tap and
+     * spent on the next request, so a long window is only a longer chance for a
+     * stale one to be lying around.
+     */
+    function pkceCookie(value, secure) {
+        const cleared = value === "";
+        return [
+            `${pkceCookieName}=${encodeURIComponent(value)}`,
+            `Path=${basePath}`,
+            "HttpOnly",
+            "SameSite=Lax",
+            secure ? "Secure" : "",
+            cleared ? "Max-Age=0" : "Max-Age=300",
+        ]
+            .filter(Boolean)
+            .join("; ");
+    }
     async function requireToken(request) {
         const token = await session.read(request);
         if (!token) {
@@ -255,6 +285,14 @@ export function createConnectHandler(options) {
             },
         });
     }
+    /**
+     * Where the browser asks Connect about the visitor, and where it asks for a
+     * code once they tap - or `null` when this deployment cannot run One Tap at
+     * all (no `clientId`, or a session store that cannot `write`, in which case
+     * `/one-tap/complete` does not exist and offering the prompt would strand
+     * anyone who used it).
+     */
+    const oneTapEndpoints = session.write ? client.identity.oneTapEndpoints() : null;
     const routes = {
         "GET /session": async (request) => {
             const token = await session.read(request);
@@ -264,9 +302,21 @@ export function createConnectHandler(options) {
             // the client never has to tell "signed out" from "signed in with no
             // role" by which keys happen to be present.
             if (!token) {
-                return json({ user: null, subscription: null, role: null, permissions: [], staff: false });
+                return json({
+                    user: null,
+                    subscription: null,
+                    role: null,
+                    permissions: [],
+                    staff: false,
+                    // Carried on the read the provider already makes on mount, so One Tap
+                    // costs no extra round trip to discover where to ask. Present on both
+                    // branches even though only the signed-out one can use it: a response
+                    // whose shape depends on the answer is a response consumers start
+                    // testing for key presence instead of value.
+                    oneTap: oneTapEndpoints,
+                });
             }
-            return json(await client.identity.getUser(token));
+            return json({ ...(await client.identity.getUser(token)), oneTap: oneTapEndpoints });
         },
         "GET /entitlements": async (request) => {
             const { workspaceId } = await requireWorkspace(request);
@@ -701,6 +751,74 @@ export function createConnectHandler(options) {
             await session.write(request, response, result.sessionToken);
             return response;
         },
+        /**
+         * One Tap, step one: mint the PKCE pair, keep the verifier here, hand the
+         * challenge to the page.
+         *
+         * Called on the *tap*, not on mount, so the five-minute verifier is minted
+         * seconds before it is spent rather than sitting in a cookie for as long as
+         * someone leaves the prompt on screen.
+         *
+         * A `POST` despite reading nothing: it sets a cookie, and a `GET` that
+         * changes state is both wrong and prefetchable - a link prefetcher or a
+         * scanner would silently rotate the verifier out from under an open prompt.
+         */
+        "POST /one-tap/start": async (request) => {
+            const url = new URL(request.url);
+            const { verifier, challenge } = await createPkcePair();
+            const response = json({
+                codeChallenge: challenge,
+                // The already-registered callback URI. One Tap never navigates to it -
+                // it is the value the code is *bound* to, and it must be byte-identical
+                // at `/one-tap/complete`, so both ends derive it the same way the
+                // redirect flow does rather than accepting it from the page.
+                redirectUri: `${url.origin}${callbackPath}`,
+            });
+            response.headers.append("set-cookie", pkceCookie(verifier, url.protocol === "https:"));
+            return response;
+        },
+        /**
+         * One Tap, step two: trade the page's code for a session, using the
+         * verifier the page never saw.
+         *
+         * This is `GET /callback`'s body without the navigation - same exchange,
+         * same verify-before-store ordering, same session store. The verifier is
+         * what makes the difference: a code lifted out of the browser cannot be
+         * redeemed anywhere else, because the exchange is refused without it.
+         */
+        "POST /one-tap/complete": async (request) => {
+            const url = new URL(request.url);
+            const secure = url.protocol === "https:";
+            const clearPkce = pkceCookie("", secure);
+            const verifier = readCookie(request, pkceCookieName);
+            if (!verifier) {
+                // The prompt sat unanswered past the cookie's life, or a cross-site
+                // `POST` arrived without it. Either way there is nothing to complete,
+                // and the client falls back to the interactive flow.
+                const expired = json({ error: "expired" }, 400);
+                expired.headers.append("set-cookie", clearPkce);
+                return expired;
+            }
+            const body = (await request.json().catch(() => null));
+            const code = typeof body?.code === "string" ? body.code : null;
+            if (!code) {
+                const invalid = json({ error: "invalid_request" }, 400);
+                invalid.headers.append("set-cookie", clearPkce);
+                return invalid;
+            }
+            const result = await client.identity.exchangeCode({
+                code,
+                redirectUri: `${url.origin}${callbackPath}`,
+                codeVerifier: verifier,
+            });
+            // Verified before the session is stored, exactly as the callback does -
+            // an unverifiable token must never become a signed-in user.
+            await client.identity.verifyIdToken(result.idToken);
+            const response = json({ ok: true });
+            response.headers.append("set-cookie", clearPkce);
+            await session.write(request, response, result.sessionToken);
+            return response;
+        },
         "POST /logout": async (request) => {
             const token = await session.read(request);
             const response = json({ ok: true });
@@ -719,6 +837,12 @@ export function createConnectHandler(options) {
     if (!session.write) {
         delete routes["GET /signin"];
         delete routes["GET /callback"];
+        // Same reason, and `oneTapEndpoints` is already `null` above so the client
+        // never offers the prompt in the first place - this is the second half of
+        // that, so a hand-written call cannot reach a route that would throw on
+        // `session.write!`.
+        delete routes["POST /one-tap/start"];
+        delete routes["POST /one-tap/complete"];
         // A switch rotates the session token. Without somewhere to persist the new
         // one, the old one would be revoked and the user silently signed out - so
         // the route does not exist rather than working once and breaking.

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

@@ -0,0 +1,53 @@
+import { request } from "../http.js";
+/**
+ * Every call that arrived on a channel assigned to your application.
+ *
+ * The application is resolved from your API key and is never a parameter, so
+ * there is no request that reads another partner's calls.
+ *
+ * `channelId` is the only filter, and that is a budget decision rather than an
+ * oversight: each filter costs a Firestore composite index against a project
+ * already near its ceiling. Filter the rest client-side, or read the
+ * aggregates from `analytics`.
+ */
+export class CallsResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Your calls, newest first, across all of your subscribing workspaces.
+     *
+     * **Page until `hasMore` is `false`; do not stop on an empty `items`.** A
+     * page can come back empty with more behind it.
+     */
+    list(input = {}) {
+        return request(this.transport, {
+            method: "GET",
+            path: "/calls",
+            query: {
+                channelId: input.channelId,
+                cursor: input.cursor,
+                limit: input.limit === undefined ? undefined : String(input.limit),
+            },
+        });
+    }
+    /**
+     * One call and every transcript turn, ordered by `sequence` - which is the
+     * sort to trust, since two turns can share a millisecond.
+     *
+     * `recordingFileId` and `transcriptFileId` are Drive file ids, readable with
+     * a `drive:read` key. Both are `null` until the carrier posts the audio,
+     * which is the normal state for a call that has only just ended - branch on
+     * `recordingStatus` rather than treating `null` as a failure.
+     *
+     * Throws `ConnectError` with `code: "not_found"` for a call that does not
+     * exist *or* belongs to another application.
+     */
+    get(callId) {
+        return request(this.transport, {
+            method: "GET",
+            path: `/calls/${encodeURIComponent(callId)}`,
+        });
+    }
+}

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

@@ -0,0 +1,111 @@
+import { request } from "../http.js";
+/**
+ * The phone numbers Connect has assigned to your application.
+ *
+ * **Inventory is platform-owned.** A number is a regulated asset bought under
+ * Connect's carrier account and reassignable between workspaces, so your
+ * application never provisions, prices or releases one - it claims from a pool
+ * it cannot see, and reads back what it was given. That is why `claim` takes a
+ * workspace and a kind rather than a number, and why nothing here exposes a
+ * carrier, a provider reference or a monthly rate.
+ *
+ * The application is resolved from your API key and is never a parameter, so
+ * no request shape here can reach another partner's channels. A channel
+ * belonging to someone else answers `404`, not `403` - confirming it exists
+ * would make these reads an oracle for enumerating their channel ids.
+ */
+export class ChannelsResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Every channel assigned to your application, across all of your subscribing
+     * workspaces.
+     *
+     * Page until `hasMore` is `false`.
+     */
+    list(input = {}) {
+        return request(this.transport, {
+            method: "GET",
+            path: "/channels",
+            query: {
+                workspaceId: input.workspaceId,
+                cursor: input.cursor,
+                limit: input.limit === undefined ? undefined : String(input.limit),
+            },
+        });
+    }
+    /**
+     * The channel behind an id you already hold - a webhook's `channelId`, or a
+     * call record's.
+     *
+     * Throws `ConnectError` with `code: "not_found"` for an id that does not
+     * exist *or* belongs to another application.
+     */
+    get(channelId) {
+        return request(this.transport, {
+            method: "GET",
+            path: `/channels/${encodeURIComponent(channelId)}`,
+        });
+    }
+    /**
+     * Takes a number out of Connect's inventory and binds it to one of your
+     * subscribing workspaces.
+     *
+     * **You do not pick the number.** A workspace may hold exactly one, across
+     * every application it uses, and it is then fixed for the life of the
+     * engagement - there is no re-claim and no swap. Only a Connect operator can
+     * unassign one.
+     *
+     * Two different `409`s, and they need different handling: the workspace
+     * already holds a channel of this kind (fix the call), or the pool is empty
+     * right now (retry - Connect is notified, and this is not permanent).
+     *
+     * The claimed channel comes back without routing, because it has none yet.
+     * Call `setRouting` next, or the number refuses every call that reaches it.
+     */
+    claim(input) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/channels/claim",
+            json: { workspaceId: input.workspaceId, kind: input.kind ?? "voice" },
+        });
+    }
+    /**
+     * Points a channel at wherever inbound conversations should go.
+     *
+     * `destination` is yours: Connect stores it verbatim and never reads into
+     * it. It **replaces** the stored record rather than merging, so send the
+     * whole destination each time; it must serialize to 16 KB or fewer.
+     *
+     * Throws `code: "conflict"` when the channel is suspended or released - use
+     * `clearRouting` to stop a suspended number answering, which is deliberately
+     * still allowed.
+     */
+    setRouting(channelId, destination) {
+        return request(this.transport, {
+            method: "PUT",
+            path: `/channels/${encodeURIComponent(channelId)}/routing`,
+            json: { destination },
+        });
+    }
+    /**
+     * Takes a number out of service without giving it up - the channel stays
+     * assigned to you and stays billable, and inbound calls are refused until
+     * you write routing again.
+     *
+     * This is the only way to say "stop answering": overwriting `destination`
+     * can only ever point the number somewhere *else*, and unassigning it is a
+     * Console action that returns the number to Connect's inventory.
+     *
+     * Idempotent - clearing already-clear routing answers `200` with
+     * `routing: null`, so a retry after a lost response is safe.
+     */
+    clearRouting(channelId) {
+        return request(this.transport, {
+            method: "DELETE",
+            path: `/channels/${encodeURIComponent(channelId)}/routing`,
+        });
+    }
+}

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

@@ -12,6 +12,23 @@ function base64UrlEncode(bytes) {
         binary += String.fromCharCode(byte);
     return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
+/**
+ * Mints a PKCE pair for the One Tap flow.
+ *
+ * The redirect flow can take PKCE or leave it, because the code is delivered
+ * to the application's server on a redirect the browser only forwards. One Tap
+ * hands the code *to the page*, so the verifier is the thing that makes a
+ * stolen code worthless - it stays in an `HttpOnly` cookie on the application's
+ * own origin and is never sent to the browser.
+ *
+ * `crypto.subtle` rather than a Node hash, so this stays isomorphic and the
+ * `./next` entry keeps loading on the edge runtime as well as Node.
+ */
+export async function createPkcePair() {
+    const verifier = createState(32);
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+    return { verifier, challenge: base64UrlEncode(new Uint8Array(digest)) };
+}
 function base64UrlDecode(value) {
     const padded = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
     const binary = atob(padded);
@@ -50,6 +67,28 @@ export class IdentityResource {
         }
         return url.toString();
     }
+    /**
+     * The two Connect endpoints One Tap talks to **from the browser**, or `null`
+     * when this client has no `clientId` configured and the flow cannot run.
+     *
+     * Handed out by the bridge rather than built in the page, so One Tap needs no
+     * client-side configuration at all - a `./next` application sets
+     * `CONNECT_CLIENT_ID` server-side and nothing else. Both URLs carry only the
+     * public `client_id`; neither is a credential.
+     *
+     * Returning `null` rather than throwing (as `authorizeUrl` does) because this
+     * is read on the `/session` route, which must keep answering for an
+     * application that has no OAuth client configured at all.
+     */
+    oneTapEndpoints() {
+        if (!this.clientId)
+            return null;
+        const hint = new URL("/api/sso/session-hint", this.appBaseUrl);
+        hint.searchParams.set("client_id", this.clientId);
+        const authorize = new URL("/api/sso/authorize/one-tap", this.appBaseUrl);
+        authorize.searchParams.set("client_id", this.clientId);
+        return { hintUrl: hint.toString(), authorizeUrl: authorize.toString() };
+    }
     /** Step 2 - trade the one-time `code` for a session. Server-side only. */
     async exchangeCode(input) {
         const wire = await this.post("/sso/token", {

package/dist/types/client/components/apps-grid.d.ts

@@ -14,14 +14,21 @@ export interface ConnectAppsGridProps {
     variant?: "row" | "icon";
 }
 /**
- * The Google-style app launcher: a grid icon in your top bar that opens a
- * modal of every Connect application this workspace can actually open.
+ * The Google-style app launcher: a grid icon that opens every Connect
+ * application this workspace has, and every one it could have.
  *
- * Only launchable apps appear, so no tile is a dead end - a paused
- * subscription still shows, badged, because a dunning cycle should not make a
- * product look deleted. The current app is pinned first and marked, rather
- * than filtered out, so the grid never has a hole where "you are here" should
- * be.
+ * Two sections, because they are two different actions. **Your apps** is what
+ * the workspace can open right now - the current application pinned first and
+ * marked, so the grid never has a hole where "you are here" should be, and a
+ * paused subscription still listed but badged, because a dunning cycle should
+ * not make a product look deleted. **Explore** is the rest of the active
+ * catalog, minus anything this workspace's type could never subscribe to, and
+ * a tile there opens that application's page on Connect.
+ *
+ * It used to show subscriptions only, with a "Browse all applications" link
+ * under the grid pointing at a Connect route that does not exist - so a
+ * workspace with one subscription saw one tile and had no working way to find
+ * anything else. Discovery belongs in the grid.
  *
  * Renders nothing when signed out: a launcher with nothing to launch is just a
  * button that opens an empty box.

package/dist/types/client/components/identity.d.ts

@@ -0,0 +1,17 @@
+/**
+ * How a person is rendered when there is no photo to render.
+ *
+ * Shared rather than copied because two surfaces showing *different* initials
+ * for the same account reads as a bug in the account, not in the component -
+ * and the One Tap prompt and the user menu are frequently on screen within
+ * seconds of each other.
+ */
+/**
+ * Up to two letters standing for a person.
+ *
+ * Splits on the punctuation an email address uses as well as whitespace, so
+ * `priya.nair@acme.test` yields `PN` rather than `PR` - an account with no
+ * display name is exactly the case the fallback exists for, and taking the
+ * first two characters of a local part would make it useless there.
+ */
+export declare function initials(name: string | null, email?: string | null): string;

package/dist/types/client/components/one-tap-state.d.ts

@@ -0,0 +1,39 @@
+/**
+ * How long One Tap stays quiet, and why.
+ *
+ * A prompt that reappears on every page load after being closed is not a
+ * convenience, it is an interstitial. Two things silence it, both stored in the
+ * application's own `localStorage` - nothing here leaves the browser, and
+ * nothing here is a security control:
+ *
+ * - **Dismissal, escalating.** Closing it once is "not now"; closing it three
+ *   times is "stop asking". The backoff says that back.
+ * - **Signing out.** Someone who has just signed out of this application does
+ *   not want to be offered the same account back on the next render. That is a
+ *   different fact from a dismissal, so it does not consume a dismissal, but it
+ *   buys a day of quiet.
+ *
+ * Every access is wrapped: `localStorage` throws outright in some embedded and
+ * privacy-restricted contexts, and a prompt is never worth breaking a page for.
+ * A read that fails reads as "not suppressed", which is the same state a fresh
+ * browser is in.
+ */
+/**
+ * Whether the prompt may be shown at all.
+ *
+ * Read once when the component mounts, never during render: `localStorage` is
+ * external mutable state, and reading it in a render body is impure - with the
+ * React Compiler on, exactly the kind of thing that can be hoisted into the
+ * wrong answer. Same reasoning as `ConnectProvider`'s `silentAttemptSpent`.
+ */
+export declare function oneTapSuppressed(): boolean;
+/** Records a close, and escalates how long the next quiet period lasts. */
+export declare function dismissOneTap(): void;
+/**
+ * Silences the prompt after an explicit sign-out, without spending a dismissal.
+ * Signing out is not a complaint about the prompt, so it must not push someone
+ * closer to the seven-day backoff.
+ */
+export declare function suppressOneTapAfterSignOut(): void;
+/** Clears the record once a sign-in actually happens - the prompt did its job. */
+export declare function clearOneTapSuppression(): void;