@cosmoops/connect-sdk 0.32.0 → 0.34.0

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";
@@ -52,6 +52,11 @@ export { normalizeNav, flattenNav, normalizePath, resolveActivePath, isNavItemAc
 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

@@ -196,7 +196,21 @@ export interface ConnectProviderProps {
      * not a Connect URL - it is your backend that exchanges the code.
      */
     redirectUri?: string;
-    /** Override for non-production Connect instances. */
+    /**
+     * Override for non-production Connect instances. Defaults to
+     * `https://connect.cosmoops.com`.
+     *
+     * The twin of `CONNECT_APP_URL`, and *not* derived from it - that variable
+     * is read on your server and never reaches the browser. This value is where
+     * the user menu's Profile, Billing and Invoices destinations open, where
+     * `ConnectAppsGrid` sends an unsubscribed application, where checkout
+     * opens, and - if you pass `redirectUri` and so build the authorize URL
+     * here rather than in your own `/signin` route - where sign-in goes. Point
+     * the server somewhere else and leave this alone and the two halves
+     * disagree, so pass both or neither. Your root layout is a Server
+     * Component, so `appUrl={process.env.CONNECT_APP_URL}` is enough and needs
+     * no browser-visible variable.
+     */
     appUrl?: string;
     /**
      * Replace the `fetch` used to reach your bridge. The browser-side twin of
@@ -245,6 +259,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;
 /**
@@ -306,11 +341,20 @@ export declare function useConnectEntitlements(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -326,11 +370,20 @@ export declare function useConnectAddonUsage(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -340,11 +393,20 @@ export declare function useConnectPlans(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -363,11 +425,20 @@ export declare function useConnectCompanyProfile(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -379,11 +450,20 @@ export declare function useConnectApps(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -402,11 +482,20 @@ export declare function useConnectWorkspaces(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -421,11 +510,20 @@ export declare function useConnectWorkspaceMembers(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -435,11 +533,20 @@ export declare function useConnectIntegrations(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -455,11 +562,20 @@ export declare function useConnectSessions(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -491,11 +607,20 @@ export declare function useConnectResource<T>(path: string, options?: Readonly<U
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };

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

@@ -77,6 +77,23 @@ export interface CheckoutUrlOptions {
     subscriptionId?: string | null;
     /** Carried into Connect's checkout, where it is validated against the real cart. */
     coupon?: string | null;
+    /**
+     * Where Connect sends the customer once the subscription is live - an
+     * absolute URL on your own origin.
+     *
+     * **Without it they do not come back.** Connect's default destination is
+     * the new subscription's own billing page, which is the right answer for
+     * someone who started in Connect and the wrong one for someone who started
+     * on your pricing page: they pay, land on a billing screen for a product
+     * they were in the middle of adopting, and nothing on it points home.
+     *
+     * Connect validates the origin against the redirect URIs registered for
+     * your Connect client and silently ignores anything else, so a value it
+     * does not recognise costs the return trip and never redirects your
+     * customer somewhere you did not register. Register the origin you intend
+     * to use; the path and query are yours.
+     */
+    next?: string | null;
 }
 /**
  * The Connect URL that cancels a subscription.
@@ -103,4 +120,4 @@ export declare function buildCancelUrl({ appUrl, subscriptionId }: {
  * prefix that has never served this page. Building the other one is what
  * sent every first-time subscriber from a partner's pricing page to a 404.
  */
-export declare function buildCheckoutUrl({ appUrl, applicationId, planId, subscriptionId, coupon, }: CheckoutUrlOptions): string;
+export declare function buildCheckoutUrl({ appUrl, applicationId, planId, subscriptionId, coupon, next, }: CheckoutUrlOptions): string;

package/dist/types/helpers.d.ts

@@ -1,4 +1,4 @@
-import type { PlanFeature, ReadinessBlocker, ReadinessResponse } from "./types.js";
+import type { PlanFeature, PlanLimit, ReadinessBlocker, ReadinessResponse } from "./types.js";
 /**
  * The blockers that actually deny access, in the order to show them.
  *
@@ -31,3 +31,38 @@ export type WirePlanFeature = string | PlanFeature;
  * hand-rolled a bridge instead of using `createConnectHandler`.
  */
 export declare function normalizePlanFeatures(features: readonly WirePlanFeature[] | undefined): PlanFeature[];
+/**
+ * What a key the plan carries no answer for reads as - see
+ * `SubscribedPlan.limits`, which is sparse.
+ *
+ * `"none"` rather than `"unlimited"`: a plan that was never asked about a
+ * limit has not sold it, and defaulting the other way would hand an unbounded
+ * allowance to every tier that predates the question.
+ */
+export declare const NO_PLAN_LIMIT: PlanLimit;
+/**
+ * One plan's answer for one limit key, with the sparse-map default applied.
+ *
+ * Indexing `plan.limits` directly is what makes a missing key `undefined`,
+ * which then reads as unlimited through the first `?.` somebody writes. This
+ * returns a `PlanLimit` either way.
+ */
+export declare function planLimitFor(limits: Readonly<Record<string, PlanLimit>> | undefined, key: string): PlanLimit;
+/**
+ * Whether `additional` more of the resource fit under this limit, given how
+ * many the subscriber already has. The comparison, written once.
+ *
+ * Every way of writing it at a call site is wrong in a different direction:
+ * `count < limit.value` is off by one as soon as you add more than one row,
+ * `if (!limit.value)` refuses the unlimited tier, and
+ * `limit.value ?? Infinity` grants unlimited to a plan that allows none. This
+ * is the same implementation Connect's own server uses to validate a plan.
+ *
+ * ```ts
+ * const limit = await connect.entitlements.getLimit(workspaceId, "sites");
+ * if (!planLimitAllows(limit, await countSites(workspaceId))) {
+ *   throw new Error("Your plan's site limit is reached.");
+ * }
+ * ```
+ */
+export declare function planLimitAllows(limit: PlanLimit, currentCount: number, additional?: number): boolean;

package/dist/types/index.d.ts

@@ -15,6 +15,7 @@
  */
 export { ConnectError, isConnectError } from "./errors.js";
 export { blockingBlockers, normalizePlanFeatures } from "./helpers.js";
+export { NO_PLAN_LIMIT, planLimitAllows, planLimitFor } from "./helpers.js";
 export { arrayRemove, arrayUnion, deleteField, documentExists, increment, serverTimestamp, storeIndexFor, storeIndexSignature, unchangedSince, } from "./store.js";
 export type { StoreIndexDirection, StoreIndexField } from "./store.js";
 export { describeQueryRejection, storeIndexCovers } from "./store-schema.js";

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 { VisitorResource } from "./resources/visitor.js";
 import { PushResource } from "./resources/push.js";
 export declare const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 export interface ConnectClientOptions {
@@ -111,6 +112,11 @@ 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;
     /**
@@ -132,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.32.0";
+export declare const SDK_VERSION = "0.34.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>;