@cosmoops/connect-sdk 0.30.1 → 0.33.0

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/esm/server/resources/visitor.js

@@ -0,0 +1,222 @@
+import { request } from "../http.js";
+/**
+ * The header a bridge forwards the visitor's own address on.
+ *
+ * It exists because `x-forwarded-for` cannot do this job here: by the time your
+ * backend calls Connect, that header describes the hop from *your server*, and
+ * the address Connect's per-visitor limiter needs is the one on the hop before
+ * it - which only your bridge has seen.
+ *
+ * **What it is and is not trusted for.** It partitions your own application's
+ * budget fairly between visitors; it does not grant anything. A caller sending a
+ * fresh value per request defeats only the per-visitor limiter and is still
+ * bounded by the per-key burst limit and the per-application daily ceiling -
+ * which are the two that actually cap spending, and neither is client-supplied.
+ * Omit it and every visitor shares one bucket, which is a stricter limit rather
+ * than an exemption.
+ */
+const VISITOR_IP_HEADER = "x-connect-visitor-ip";
+function visitorHeaders(options) {
+    return options?.visitorIp ? { [VISITOR_IP_HEADER]: options.visitorIp } : {};
+}
+/**
+ * The public chat bubble on your own marketing site.
+ *
+ * The one resource here whose caller is **not** one of your users. There is no
+ * `asUser`, no `workspaceId` and no session anywhere in it: the counterpart is a
+ * stranger who has no account, and everything the assistant may say or do is
+ * configuration a platform admin set on your application record.
+ *
+ * That is why none of these methods takes an id naming anything. The workspace a
+ * call books into, the event type it books, the knowledge it answers from and the
+ * daily budget it spends are all read from your application - so nothing a
+ * visitor types, and nothing an injection attempt in your own chat window
+ * achieves, reaches a different tenant.
+ *
+ * **Never call these from a browser.** They take your API key, like every other
+ * resource on this client. `createConnectHandler` already exposes them on your
+ * own origin for `<ConnectVisitorChat>` to use, which is how the credential stays
+ * server-side.
+ */
+export class VisitorResource {
+    transport;
+    /**
+     * The knowledge base behind the assistant - see `VisitorKnowledgeResource`.
+     *
+     * Nested rather than a top-level resource, because it is meaningless on its
+     * own: it exists to decide what *this* assistant may say.
+     */
+    knowledge;
+    constructor(transport) {
+        this.transport = transport;
+        this.knowledge = new VisitorKnowledgeResource(transport);
+    }
+    /**
+     * Open a conversation, or reopen one.
+     *
+     * Generates nothing - the greeting and the suggested questions come off the
+     * application record - so this is the one call in the flow that is always fast,
+     * which is what lets a bubble paint real copy instead of a spinner.
+     *
+     * Pass `resume` with a `sessionId` you kept and the transcript comes back with
+     * it. A `resume` that is expired, unknown or another application's silently
+     * starts a fresh conversation rather than failing: the token is the only thing
+     * being offered and it is being rejected, so there is nothing for the visitor
+     * to do about an error.
+     */
+    startSession(input, options = {}) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/visitor/session",
+            json: {
+                workspaceId: input.workspaceId,
+                page: input.page ?? null,
+                resume: input.resume ?? null,
+            },
+            headers: visitorHeaders(options),
+            signal: options.signal,
+        });
+    }
+    /**
+     * One turn, streamed.
+     *
+     * Returns the raw `Response` rather than a parsed body, the same way
+     * `ai.chat` does: this answers server-sent events, and buffering them here
+     * would throw away the only reason to stream. The events are `delta`
+     * (`{text}`), `done` (`VisitorTurnDone`) and `error` (`{message}`).
+     *
+     * **The transcript is not a parameter**, which is the security property this
+     * endpoint is built around: the caller is ultimately a browser on a public
+     * page, and a client that can supply its own transcript can supply one in
+     * which anything has already been established. Only the conversation id and
+     * the new message travel.
+     */
+    chat(input, options = {}) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/visitor/chat",
+            json: input,
+            headers: visitorHeaders(options),
+            raw: true,
+            signal: options.signal,
+        });
+    }
+    /**
+     * Book the call a visitor chose.
+     *
+     * `startAt` must be a time the turn's own slot lookup returned - an arbitrary
+     * instant is refused. That, plus a name and phone collected in real fields,
+     * is what makes it impossible to book an appointment at a time nobody offered
+     * or with a phone number a model parsed out of prose.
+     *
+     * A conversation books at most one appointment; a second call answers `409`.
+     */
+    book(input, options = {}) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/visitor/book",
+            headers: visitorHeaders(options),
+            signal: options.signal,
+            json: {
+                ...input,
+                startAt: input.startAt instanceof Date ? input.startAt.toISOString() : input.startAt,
+                email: input.email ?? null,
+                notes: input.notes ?? null,
+            },
+        });
+    }
+}
+/**
+ * A subscribing workspace's **public** knowledge base - what their website chat
+ * may tell strangers.
+ *
+ * ## It is deliberately not their Context Index
+ *
+ * `ai.chat` answers from a workspace's Drive-fed corpus, for a signed-in member
+ * of that workspace. This is a separate store that holds only what somebody
+ * explicitly published, and the separation is the reason a publishable widget
+ * credential is safe to publish: everything the widget can reach was already
+ * meant for the public.
+ *
+ * Do not try to fill it by uploading to Drive. Nothing reaches this store as a
+ * side effect of anything else - that is the invariant, not an inconvenience.
+ *
+ * ## Publishing is its own call
+ *
+ * `save` always writes a draft. `publish` is what makes text readable by
+ * strangers, so no edit can do it by accident, and `unpublish` can fail - which
+ * means the item is **still live**, not that the call was pointless.
+ */
+export class VisitorKnowledgeResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Everything, drafts included - the list a customer audits. */
+    list(workspaceId) {
+        return request(this.transport, {
+            method: "GET",
+            path: "/visitor/knowledge",
+            query: { workspaceId },
+        });
+    }
+    /**
+     * Create or edit a draft.
+     *
+     * A body over the cap is **refused rather than truncated** - split a long page
+     * into sections, which is also what makes retrieval work.
+     */
+    async save(input) {
+        const result = await request(this.transport, {
+            method: "POST",
+            path: "/visitor/knowledge",
+            json: {
+                ...input,
+                itemId: input.itemId ?? null,
+                sourceRef: input.sourceRef ?? null,
+            },
+        });
+        return result.item;
+    }
+    /**
+     * Make one item readable by strangers.
+     *
+     * May be slow: the publish that outgrows the prompt provisions a retrieval
+     * corpus and indexes everything published so far. An indexing failure still
+     * publishes and comes back with `indexState: "failed"` and `indexError` set,
+     * so a provider hiccup never makes your button look broken.
+     */
+    async publish(input) {
+        const result = await request(this.transport, {
+            method: "POST",
+            path: "/visitor/knowledge/publish",
+            json: input,
+        });
+        return result.item;
+    }
+    /**
+     * Take one item out of what strangers can read.
+     *
+     * **A failure means it is still live.** The retrievable copy is removed before
+     * the record is flipped, so a provider that refuses the delete aborts rather
+     * than leaving an item your screen shows as withdrawn that the widget goes on
+     * quoting. Surface the error and let them retry; do not grey the row out
+     * optimistically.
+     */
+    async unpublish(input) {
+        const result = await request(this.transport, {
+            method: "POST",
+            path: "/visitor/knowledge/unpublish",
+            json: input,
+        });
+        return result.item;
+    }
+    /** Remove it entirely. A published item is unpublished first. */
+    async delete(input) {
+        await request(this.transport, {
+            method: "POST",
+            path: "/visitor/knowledge/delete",
+            json: input,
+        });
+    }
+}

package/dist/types/client/components/visitor-chat.d.ts

@@ -0,0 +1,120 @@
+export interface ConnectVisitorChatProps {
+    /**
+     * The customer whose website this widget is on.
+     *
+     * Required, and it is the one field that decides whose published knowledge the
+     * assistant answers from and whose diary it books into. Your bridge checks it
+     * against your own subscriptions before it reaches Connect.
+     */
+    workspaceId: string;
+    /**
+     * What the assistant calls itself, and the copy shown before anybody types.
+     *
+     * **Yours, not Connect's.** These never reach the model and are rendered from
+     * your own store, which is what lets the bubble paint its first frame with no
+     * network call at all. Connect holds what it enforces; you hold what you draw.
+     */
+    assistantName?: string;
+    greeting?: string;
+    /** Opening questions offered as buttons. Three is what fits above a phone keyboard. */
+    suggestions?: readonly string[];
+    /** A published event type slug in that workspace, to offer a call. Omit for no booking. */
+    bookingEventTypeSlug?: string | null;
+    /**
+     * Where `createConnectHandler` is mounted. Defaults to `/api/connect`, which
+     * is its own default.
+     *
+     * Passed explicitly here, rather than only inherited from `ConnectProvider`,
+     * because this component is built to work on a page that has no provider -
+     * see the component's own note.
+     */
+    basePath?: string;
+    /**
+     * The page the visitor is on, passed to Connect as context.
+     *
+     * Left unset it uses `location.pathname`. Pass something more meaningful - a
+     * page title, a product slug - where the path is not descriptive.
+     */
+    page?: string;
+    /** The bubble's accessible label, and the panel's heading. */
+    title?: string;
+    /** Start open. The panel owns its state after that. */
+    defaultOpen?: boolean;
+    /**
+     * Show the bubble even to a signed-in user. Off by default.
+     *
+     * The default is the useful one: a signed-in member has your product's own
+     * support surfaces and, if you mount it, `<ConnectAskAi>` - which is grounded
+     * in their actual workspace and can therefore answer things this assistant
+     * cannot. Two bubbles in the same corner is also the one layout bug this
+     * component could cause, since `<ConnectAskAi>` sits at the same `z-30`
+     * bottom-right position.
+     *
+     * Turn it on for a marketing site that is a separate surface from the
+     * application, where "signed in" says nothing about what the visitor is
+     * reading.
+     */
+    showWhenSignedIn?: boolean;
+    /**
+     * Replaces `fetch`, for a mount with **no `ConnectProvider`** around it.
+     *
+     * Inside a provider this is not needed and not read: the component goes
+     * through `mutateResource`/`streamResource`, which already use whatever
+     * `fetch` that provider was given - so Storybook and the docs site work by
+     * wrapping it, with nothing passed here.
+     */
+    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+}
+/**
+ * The public chat bubble: a visitor with no account asks about your product,
+ * books a call, or gets started.
+ *
+ * ## It runs on pages that have no `ConnectProvider`
+ *
+ * Deliberately, and it is the main thing separating this component from every
+ * other one here. A marketing page usually has no session to hold and nothing
+ * on it that needs one, so requiring the provider would mean wrapping a
+ * landing page in an auth context to put a chat bubble on it. It reads the
+ * context through `useConnectOptional` and uses it only for `basePath` and the
+ * injected `fetch`; both have props, and both have defaults.
+ *
+ * ## Nothing happens until somebody opens it
+ *
+ * The conversation is minted on first open, never on mount. On a busy marketing
+ * site mounting would mean one Firestore write and one wasted session row per
+ * *page view*, for a bubble most visitors never touch - and the bubble itself
+ * needs no server state to render. The greeting arrives with that first call
+ * and is stored copy rather than generated, so opening costs one fast round
+ * trip and the visitor is reading real words immediately.
+ *
+ * ## It is built for a phone first
+ *
+ * Open, it is a full-height sheet on a narrow viewport and an anchored panel
+ * from `sm` up - a marketing chat that covers a desktop browser is harder to
+ * use, and one that does not cover a phone has nowhere to put a keyboard.
+ * `h-dvh` rather than `h-screen`, so the sheet tracks the visual viewport when
+ * the keyboard opens; `env(safe-area-inset-bottom)` on the composer, so the
+ * send button is not under a home indicator.
+ *
+ * The composer's input type is **the server's decision**, not a guess from what
+ * the assistant said - see `VisitorField`. That is what puts an `@` on the
+ * keyboard when an email is wanted and lets iOS offer a verification code
+ * straight from the notification.
+ *
+ * ## The times are drawn from the tool result, never the prose
+ *
+ * A turn that looked up availability carries the slots as structured data, and
+ * the buttons come from that. So a time the visitor taps is one the server
+ * offered, which is the property `/visitor/book` relies on and cannot check for
+ * itself.
+ *
+ * ## Replies render as text, not markdown
+ *
+ * `<ConnectAskAi>` lazy-loads a markdown renderer because it answers questions
+ * about a workspace's documents, where tables and code blocks carry meaning.
+ * This answers three-sentence questions about a product on a marketing page.
+ * Shipping 462 KB of renderer to a landing page for prose that is deliberately
+ * kept to a couple of lines is the wrong trade, so line breaks are preserved
+ * and nothing else is parsed.
+ */
+export declare function ConnectVisitorChat({ workspaceId, assistantName, greeting, suggestions, bookingEventTypeSlug, basePath, page, title, defaultOpen, showWhenSignedIn, fetch: fetchProp, }: ConnectVisitorChatProps): import("react").JSX.Element | null;

package/dist/types/client/components/visitor-stream.d.ts

@@ -0,0 +1,42 @@
+import type { VisitorSlotOffer, VisitorToolCall, VisitorTurnDone } from "../../types.js";
+/**
+ * The visitor turn's wire format, read.
+ *
+ * **A named-event reader, where `<ConnectAskAi>`'s is data-only.** That one
+ * consumes the AI SDK's UI message stream, where every frame is a `data:` line
+ * carrying a `type` field. This endpoint answers `event:`/`data:` pairs instead,
+ * for the reason the route explains: the UI message protocol exists for
+ * `useChat`, which owns the message list client-side, and this surface
+ * deliberately does not let the client own the transcript.
+ *
+ * Kept out of the component and pure so it can be tested without a DOM. The
+ * three behaviours worth pinning are all here: a frame split across two network
+ * reads, a malformed frame, and a stream that ends without its `done`.
+ */
+export interface VisitorStreamHandlers {
+    onDelta(text: string): void;
+    onDone(done: VisitorTurnDone): void;
+    /**
+     * A failure the server reported *after* the stream opened.
+     *
+     * It arrives as an event rather than a status because the status was already
+     * sent, and the message is written as a sentence for the same reason - it is
+     * shown to the visitor verbatim.
+     */
+    onError(message: string): void;
+}
+export declare function readVisitorStream(response: Response, handlers: VisitorStreamHandlers): Promise<void>;
+/**
+ * The times a turn looked up, lifted out of its tool calls.
+ *
+ * **This is what the buttons are drawn from, never the assistant's sentence.** A
+ * time the visitor taps is then one the server offered, which is what makes it
+ * impossible to book an appointment at a time nobody gave - the property
+ * `/visitor/book` depends on and cannot check for itself.
+ *
+ * `null` when the turn looked nothing up, and also when the lookup *refused* -
+ * a tool answering `ok: false` is the assistant being told there is nothing
+ * available, and it says so in prose. Rendering an empty slot list under that
+ * would be a second, emptier way of saying the same thing.
+ */
+export declare function visitorSlotOfferFrom(toolCalls: readonly VisitorToolCall[]): VisitorSlotOffer | null;

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

@@ -10,7 +10,7 @@
  * whatever theme the host application platform already configured, and one theme
  * change lands identically in all of them.
  */
-export { ConnectProvider, useConnect, useConnectUser, useConnectWorkspaceType, useConnectAudience, useConnectPlatformAccess, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectCompanyProfile, useConnectAddonUsage, useConnectSessions, useConnectIntegrations, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
+export { ConnectProvider, useConnect, useConnectOptional, useConnectUser, useConnectWorkspaceType, useConnectAudience, useConnectPlatformAccess, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectCompanyProfile, useConnectAddonUsage, useConnectSessions, useConnectIntegrations, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
 export type { ConnectProviderProps, ConnectContextValue, ConnectSession, ConnectOneTapHint, ConnectOneTapFailure, UseConnectResourceOptions, } from "./provider.js";
 export { blockingBlockers, normalizePlanFeatures } from "../helpers.js";
 export type { WirePlanFeature } from "../helpers.js";
@@ -41,10 +41,22 @@ 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";
 export { matchConnectScreen, isLinkableConnectScreen, } from "./components/ai-screens.js";
+export { ConnectVisitorChat } from "./components/visitor-chat.js";
+export type { ConnectVisitorChatProps } from "./components/visitor-chat.js";
+export { readVisitorStream, visitorSlotOfferFrom } from "./components/visitor-stream.js";
+export type { VisitorStreamHandlers } from "./components/visitor-stream.js";
+export type { VisitorAppointment, VisitorBooking, VisitorField, VisitorMessage, VisitorSession, VisitorSlot, VisitorSlotOffer, VisitorToolCall, VisitorTurnDone, } from "../types.js";
 export { ConnectAppsGrid } from "./components/apps-grid.js";
 export type { ConnectAppsGridProps } from "./components/apps-grid.js";
 export { ConnectAskAi } from "./components/ask-ai.js";

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

@@ -245,6 +245,27 @@ export interface ConnectProviderProps {
  */
 export declare function ConnectProvider({ clientId, basePath, redirectUri, appUrl, fetch: fetchImpl, silentSignIn, children, }: ConnectProviderProps): import("react").JSX.Element;
 export declare function useConnect(): ConnectContextValue;
+/**
+ * The context when there is one, `null` when there is not.
+ *
+ * **For a component that must work on a page with no provider**, which is a
+ * real case rather than defensive coding: `<ConnectVisitorChat>` goes on a
+ * public marketing page, and those pages frequently have no `ConnectProvider`
+ * anywhere near them - there is no session to hold and nothing on the page that
+ * needs one. `useConnect()` throwing is right for every component that reads a
+ * session; it is wrong for one whose whole purpose is the visitor who has none.
+ *
+ * What inheriting the context buys such a component, when it is inside one, is
+ * `basePath` and the injected `fetch` - so the same component renders against
+ * Storybook's mock bridge and the docs site's canned fetch without either of
+ * them having to pass anything.
+ *
+ * Do not reach for this to make an ordinary component tolerant of a missing
+ * provider. A session-reading component that silently renders a signed-out
+ * state because somebody forgot to wrap their app is a bug that looks like a
+ * product decision.
+ */
+export declare function useConnectOptional(): ConnectContextValue | null;
 /** The signed-in user, or `null`. Sugar over `useConnect().session`. */
 export declare function useConnectUser(): ConnectUser | null;
 /**

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,8 @@ 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 { VisitorResource } from "./resources/visitor.js";
+import { PushResource } from "./resources/push.js";
 export declare const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 export interface ConnectClientOptions {
     /**
@@ -110,8 +112,18 @@ export declare class ConnectClient {
     readonly integrations: IntegrationsResource;
     /** Which workspaces the signed-in user belongs to, switching between them, and the team - see `WorkspacesResource`. */
     readonly workspaces: WorkspacesResource;
+    /**
+     * The public chat bubble on your own site - see `VisitorResource`. The one
+     * resource here whose caller is not one of your users.
+     */
+    readonly visitor: VisitorResource;
     /** 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 +138,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/handler.d.ts

@@ -40,28 +40,4 @@ export interface ConnectHandlerOptions {
      */
     stateCookieName?: string;
 }
-/**
- * The browser half of this SDK cannot hold an API key - so it does not.
- *
- * `@cosmoops/connect-sdk/client` talks only to your own origin, and this
- * handler is what answers. It lives in your backend, holds the key, and
- * exposes a fixed, named set of reads plus sign-out and session revocation.
- * Nothing here proxies arbitrary paths: a generic passthrough would hand the
- * browser your whole API surface under your credentials, which is the same
- * leak with extra steps.
- *
- * Framework-agnostic - `Request` in, `Response` out, so it mounts anywhere
- * that shape exists.
- *
- * ```ts
- * // app/api/connect/[...route]/route.ts
- * const handler = createConnectHandler({ client, session });
- * export { handler as GET, handler as POST };
- * ```
- *
- * Every route resolves the workspace from the caller's *own* session, never
- * from a query parameter. A browser must not be able to ask about an
- * workspace it is not signed into, and a client-supplied `workspaceId`
- * is exactly that hole.
- */
 export declare function createConnectHandler(options: ConnectHandlerOptions): (request: Request) => Promise<Response>;