@cosmoops/connect-sdk 0.41.0 → 0.42.0

package/dist/esm/client/components/user-menu.js

@@ -3,7 +3,6 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Avatar, Button, Chip, Modal, Skeleton, ToggleButton, ToggleButtonGroup, } from "@heroui/react";
 import { ChevronsUpDown, CreditCard, ExternalLink, Laptop, LogOut, Moon, ReceiptText, Sun, UserRound, } from "lucide-react";
 import { useConnect } from "../provider.js";
-import { connectPortalUrl } from "../portal-links.js";
 import { ConnectMark } from "../mark.js";
 import { initials } from "./identity.js";
 import { ConnectAccountSessions } from "./account-sessions.js";
@@ -16,6 +15,12 @@ const THEME_OPTIONS = [
     { value: "dark", label: "Dark", icon: Moon },
     { value: "system", label: "System", icon: Laptop },
 ];
+/**
+ * Connect's front page, which is a destination rather than a task - nothing to
+ * finish, so nothing to come back from. Every *task* destination here (Profile,
+ * Billing, Invoices) goes through `openConnect` instead, which brings the
+ * visitor back when they are done.
+ */
 function openExternal(url) {
     window.open(url, "_blank", "noopener,noreferrer");
 }
@@ -90,8 +95,8 @@ function subscriptionChip(subscription) {
  * 44%, and takes the tile down to ~88px while making its contents read
  * bigger, not smaller.
  */
-function DestinationTile({ icon, label, url, }) {
-    return (_jsxs(Button, { variant: "tertiary", "aria-label": `${label} (opens in a new tab)`, className: `relative h-auto w-full flex-col items-center justify-center gap-2 rounded-xl border border-border ${PANEL_FILL} p-3 hover:border-accent hover:bg-surface-secondary`, onPress: () => openExternal(url), children: [_jsx(ExternalLink, { className: "absolute end-2 top-2 size-3.5 text-muted", "aria-hidden": "true" }), _jsx("span", { className: `flex ${MEDALLION} items-center justify-center rounded-xl bg-surface text-muted`, children: icon }), _jsx("span", { className: "text-xs font-medium text-foreground", children: label })] }));
+function DestinationTile({ icon, label, onPress, newTab, }) {
+    return (_jsxs(Button, { variant: "tertiary", "aria-label": newTab ? `${label} (opens in a new tab)` : label, className: `relative h-auto w-full flex-col items-center justify-center gap-2 rounded-xl border border-border ${PANEL_FILL} p-3 hover:border-accent hover:bg-surface-secondary`, onPress: onPress, children: [newTab && _jsx(ExternalLink, { className: "absolute end-2 top-2 size-3.5 text-muted", "aria-hidden": "true" }), _jsx("span", { className: `flex ${MEDALLION} items-center justify-center rounded-xl bg-surface text-muted`, children: icon }), _jsx("span", { className: "text-xs font-medium text-foreground", children: label })] }));
 }
 /**
  * The account modal's contents - identity card, the three Connect
@@ -112,14 +117,14 @@ function DestinationTile({ icon, label, url, }) {
  * three navigations.
  */
 function ProfileSurface({ onSignOut, theme, onThemeChange, }) {
-    const { session, signOut, appUrl, clientId } = useConnect();
+    const { session, signOut, appUrl, openConnect, handoffMode } = useConnect();
     const user = session?.user;
     if (!user)
         return null;
     const label = user.displayName ?? user.email ?? "Account";
     const role = session?.role ?? null;
     const planChip = subscriptionChip(session?.subscription ?? null);
-    return (_jsx(Modal.Backdrop, { children: _jsx(Modal.Container, { size: "md", scroll: "inside", children: _jsxs(Modal.Dialog, { children: [_jsx(Modal.CloseTrigger, {}), _jsx(Modal.Header, { children: _jsx(Modal.Heading, { children: "Account" }) }), _jsxs(Modal.Body, { className: "flex flex-col gap-5", children: [_jsxs("div", { className: `flex items-start gap-3 rounded-xl border border-border ${PANEL_FILL} p-4`, children: [_jsx(UserAvatar, { user: user, size: "lg" }), _jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-0.5", children: [_jsx("p", { className: "truncate text-sm font-semibold text-foreground", children: label }), user.email && _jsx("p", { className: "truncate text-xs text-muted", children: user.email }), _jsx("p", { className: "truncate text-xs text-muted", children: user.workspaceName }), (role || planChip || !user.emailVerified) && (_jsxs("div", { className: "mt-1.5 flex flex-wrap items-center gap-1.5", children: [role && (_jsx(Chip, { size: "sm", variant: "soft", color: "accent", children: humanizeRole(role) })), planChip, !user.emailVerified && (_jsx(Chip, { size: "sm", variant: "soft", color: "warning", children: "Email unverified" }))] }))] })] }), _jsxs("div", { className: "grid grid-cols-3 gap-2", children: [_jsx(DestinationTile, { icon: _jsx(UserRound, { className: ICON, "aria-hidden": "true" }), label: "Profile", url: connectPortalUrl(appUrl, clientId, "/profile") }), _jsx(DestinationTile, { icon: _jsx(CreditCard, { className: ICON, "aria-hidden": "true" }), label: "Billing", url: `${appUrl}/billing` }), _jsx(DestinationTile, { icon: _jsx(ConnectMark, { className: ICON }), label: "Connect", url: appUrl })] }), theme && onThemeChange && (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx("p", { className: "text-sm font-medium text-foreground", children: "Appearance" }), _jsx(ToggleButtonGroup, { fullWidth: true, "aria-label": "Theme", selectionMode: "single", disallowEmptySelection: true, selectedKeys: [theme], onSelectionChange: (keys) => {
+    return (_jsx(Modal.Backdrop, { children: _jsx(Modal.Container, { size: "md", scroll: "inside", children: _jsxs(Modal.Dialog, { children: [_jsx(Modal.CloseTrigger, {}), _jsx(Modal.Header, { children: _jsx(Modal.Heading, { children: "Account" }) }), _jsxs(Modal.Body, { className: "flex flex-col gap-5", children: [_jsxs("div", { className: `flex items-start gap-3 rounded-xl border border-border ${PANEL_FILL} p-4`, children: [_jsx(UserAvatar, { user: user, size: "lg" }), _jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-0.5", children: [_jsx("p", { className: "truncate text-sm font-semibold text-foreground", children: label }), user.email && _jsx("p", { className: "truncate text-xs text-muted", children: user.email }), _jsx("p", { className: "truncate text-xs text-muted", children: user.workspaceName }), (role || planChip || !user.emailVerified) && (_jsxs("div", { className: "mt-1.5 flex flex-wrap items-center gap-1.5", children: [role && (_jsx(Chip, { size: "sm", variant: "soft", color: "accent", children: humanizeRole(role) })), planChip, !user.emailVerified && (_jsx(Chip, { size: "sm", variant: "soft", color: "warning", children: "Email unverified" }))] }))] })] }), _jsxs("div", { className: "grid grid-cols-3 gap-2", children: [_jsx(DestinationTile, { icon: _jsx(UserRound, { className: ICON, "aria-hidden": "true" }), label: "Profile", onPress: () => openConnect("/profile"), newTab: handoffMode === "popup" }), _jsx(DestinationTile, { icon: _jsx(CreditCard, { className: ICON, "aria-hidden": "true" }), label: "Billing", onPress: () => openConnect("/billing"), newTab: handoffMode === "popup" }), _jsx(DestinationTile, { icon: _jsx(ConnectMark, { className: ICON }), label: "Connect", onPress: () => openExternal(appUrl), newTab: true })] }), theme && onThemeChange && (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx("p", { className: "text-sm font-medium text-foreground", children: "Appearance" }), _jsx(ToggleButtonGroup, { fullWidth: true, "aria-label": "Theme", selectionMode: "single", disallowEmptySelection: true, selectedKeys: [theme], onSelectionChange: (keys) => {
                                             const [next] = [...keys];
                                             if (typeof next === "string")
                                                 onThemeChange(next);
@@ -197,8 +202,8 @@ export function ConnectUserMenu({ compact = false, ...rest }) {
  * state, a settings page.
  */
 export function ConnectManageSubscriptionButton({ className }) {
-    const { appUrl } = useConnect();
-    return (_jsxs(Button, { variant: "secondary", className: className, onPress: () => openExternal(`${appUrl}/billing`), children: [_jsx(CreditCard, { className: "size-4 shrink-0" }), "Manage subscription", _jsx(ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
+    const { openConnect } = useConnect();
+    return (_jsxs(Button, { variant: "secondary", className: className, onPress: () => openConnect("/billing"), children: [_jsx(CreditCard, { className: "size-4 shrink-0" }), "Manage subscription", _jsx(ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
 }
 /**
  * Invoices and payment history, on Connect.
@@ -211,10 +216,10 @@ export function ConnectManageSubscriptionButton({ className }) {
  * version of a record that must have exactly one.
  */
 export function ConnectInvoicesButton({ className }) {
-    const { session, appUrl } = useConnect();
+    const { session, openConnect } = useConnect();
     if (!session?.user)
         return null;
-    return (_jsxs(Button, { variant: "tertiary", className: className, onPress: () => openExternal(`${appUrl}/billing/invoices`), children: [_jsx(ReceiptText, { className: "size-4 shrink-0" }), "Invoices", _jsx(ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
+    return (_jsxs(Button, { variant: "tertiary", className: className, onPress: () => openConnect("/billing/invoices"), children: [_jsx(ReceiptText, { className: "size-4 shrink-0" }), "Invoices", _jsx(ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
 }
 /**
  * The "Profile" action on its own - the third of the three Connect
@@ -226,10 +231,10 @@ export function ConnectInvoicesButton({ className }) {
  * and got no `return_to`, so the user had no way back.
  */
 export function ConnectProfileButton({ className }) {
-    const { session, appUrl, clientId } = useConnect();
+    const { session, openConnect } = useConnect();
     if (!session?.user)
         return null;
-    return (_jsxs(Button, { variant: "tertiary", className: className, onPress: () => openExternal(connectPortalUrl(appUrl, clientId, "/profile")), children: [_jsx(UserRound, { className: "size-4 shrink-0" }), "Profile", _jsx(ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
+    return (_jsxs(Button, { variant: "tertiary", className: className, onPress: () => openConnect("/profile"), children: [_jsx(UserRound, { className: "size-4 shrink-0" }), "Profile", _jsx(ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
 }
 /** A plain "Open Connect" button, for a footer or a help menu. */
 export function ConnectHomeButton({ className }) {

package/dist/esm/client/handoff.js

@@ -0,0 +1,72 @@
+/**
+ * The hand-off contract with Connect's portal - the pure half, so the rules
+ * can be tested without a browser. `openConnect` (on `useConnect()`) is the
+ * half that touches `window`.
+ *
+ * Every time this SDK sends somebody to Connect for a task - a plan, a
+ * payment method, their profile - it appends three params, and Connect's
+ * portal brings them back when the task is done:
+ *
+ * | Param | |
+ * |---|---|
+ * | `client_id` | Names this application. Connect only honours a `return_to` whose origin is registered for that client. |
+ * | `return_to` | The page they left. |
+ * | `mode` | `popup` - Connect closes its window when done and posts the outcome to this page first. `redirect` - Connect navigates back here with `?connect_result=`. |
+ */
+/** `MessageEvent.data.type` of the message Connect posts before closing a popup. */
+export const CONNECT_HANDOFF_MESSAGE_TYPE = "connect:handoff";
+/** The query param Connect adds when it redirects back. */
+export const CONNECT_HANDOFF_RESULT_PARAM = "connect_result";
+const RESULTS = ["completed", "cancelled", "closed"];
+function isResult(value) {
+    return typeof value === "string" && RESULTS.includes(value);
+}
+/**
+ * `target` - a path (`"/billing"`) or an absolute Connect URL (a readiness
+ * blocker's `resolveUrl`) - with the hand-off params set.
+ *
+ * Throws for a URL on any other origin: these params tell Connect where to
+ * send somebody back, and stamping them onto a third party's URL would hand
+ * that party the page this visitor was on.
+ */
+export function buildHandoffUrl(target, { appUrl, clientId, mode, returnTo }) {
+    const url = new URL(target, appUrl);
+    if (url.origin !== new URL(appUrl).origin) {
+        throw new Error(`openConnect only opens Connect URLs (${new URL(appUrl).origin}), not ${url.origin}.`);
+    }
+    if (clientId)
+        url.searchParams.set("client_id", clientId);
+    url.searchParams.set("return_to", returnTo);
+    url.searchParams.set("mode", mode);
+    // `next` is the older spelling Connect still honours, and a stale one left
+    // on a server-built URL would compete with `return_to` - so it goes.
+    url.searchParams.delete("next");
+    return url.toString();
+}
+/**
+ * The result a `message` event carries, or `null` when it is not Connect's
+ * hand-off message. The origin check is the whole security story: any page
+ * can `postMessage` this window, and only Connect's verdict may trigger work.
+ */
+export function readHandoffMessage(event, appUrl) {
+    if (event.origin !== new URL(appUrl).origin)
+        return null;
+    const data = event.data;
+    if (!data || typeof data !== "object")
+        return null;
+    const { type, result } = data;
+    return type === CONNECT_HANDOFF_MESSAGE_TYPE && isResult(result) ? result : null;
+}
+/**
+ * The result a redirect-mode return carries in `href`, and `href` with it
+ * removed - so a reload does not report the same trip twice and the param
+ * does not end up in a link somebody shares.
+ */
+export function takeHandoffResult(href) {
+    const url = new URL(href);
+    const result = url.searchParams.get(CONNECT_HANDOFF_RESULT_PARAM);
+    if (!isResult(result))
+        return null;
+    url.searchParams.delete(CONNECT_HANDOFF_RESULT_PARAM);
+    return { result, cleaned: url.toString() };
+}

package/dist/esm/client/index.js

@@ -15,6 +15,7 @@ export { ConnectProvider, useConnect,
 // For a component that must render on a page with no provider - see its own
 // note. `<ConnectVisitorChat>` is the case it exists for.
 useConnectOptional, useConnectUser, useConnectWorkspaceType, useConnectAudience, useConnectPlatformAccess, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectCompanyProfile, useConnectAddonUsage, useConnectSessions, useConnectIntegrations, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
+export { CONNECT_HANDOFF_MESSAGE_TYPE, CONNECT_HANDOFF_RESULT_PARAM } from "./handoff.js";
 // Re-exported from the root entry rather than kept there alone: it is a pure
 // helper, but every caller is UI code, and making a component file reach two
 // entry points for one function is friction with nothing behind it.
@@ -32,9 +33,9 @@ ConnectUserMenu, ConnectManageSubscriptionButton, ConnectInvoicesButton, Connect
 // `ConnectUserMenu` was the only thing that could render it.
 export { ConnectAccountSessions } from "./components/account-sessions.js";
 // A link to *any* Connect portal page that offers a `"Back to <your app>"` way
-// home - what `ConnectProfileButton` builds for `/profile` internally, made
-// reusable for a host linking out to a different Connect page (e.g.
-// `/calendar/settings`) on its own.
+// home, for a host that needs a real `<a href>` (a server-rendered link, a
+// middle-click). For a button, prefer `useConnect().openConnect`, which also
+// brings the visitor back when the task is done.
 export { connectPortalUrl, useConnectPortalUrl } from "./portal-links.js";
 // The frame the rest of these components live inside. Exported next to the
 // pieces it composes rather than in a section of its own - an integration

package/dist/esm/client/provider.js

@@ -2,6 +2,8 @@
 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";
+import { ConnectError } from "../errors.js";
+import { buildHandoffUrl, readHandoffMessage, takeHandoffResult, } from "./handoff.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`. */
@@ -20,7 +22,7 @@ const SILENT_ATTEMPT_KEY = "connect_silent_attempted";
  * </ConnectProvider>
  * ```
  */
-export function ConnectProvider({ clientId = "", basePath = "/api/connect", redirectUri, appUrl = CONNECT_APP_URL, fetch: fetchImpl, silentSignIn = false, children, }) {
+export function ConnectProvider({ clientId = "", basePath = "/api/connect", redirectUri, appUrl = CONNECT_APP_URL, fetch: fetchImpl, silentSignIn = false, handoff = "popup", onHandoffResult, children, }) {
     // One state cell, not three. `isLoading` is *derived* from "no result yet"
     // rather than set - a `setIsLoading(true)` at the top of an effect is a
     // synchronous setState inside that effect, which cascades an extra render
@@ -122,7 +124,17 @@ export function ConnectProvider({ clientId = "", basePath = "/api/connect", redi
         });
         if (!response.ok) {
             const envelope = await response.json().catch(() => null);
-            throw new Error(envelope?.error?.message ?? `Connect bridge returned ${response.status}`);
+            // A `ConnectError` rather than a bare `Error`, so a caller can branch
+            // on the status and code - a signed-out 401 and a throttled 429 need
+            // different words in front of a person. Same message as before, so
+            // anything already reading it sees no change.
+            throw new ConnectError({
+                message: envelope?.error?.message ?? `Connect bridge returned ${response.status}`,
+                status: response.status,
+                code: typeof envelope?.error?.code === "string" ? envelope.error.code : "unknown",
+                endpoint: `POST ${path}`,
+                body: envelope,
+            });
         }
         return response;
     }, [basePath, fetchImpl]);
@@ -172,6 +184,61 @@ export function ConnectProvider({ clientId = "", basePath = "/api/connect", redi
         // eslint-disable-next-line react-hooks/set-state-in-effect
         void refresh();
     }, [refresh]);
+    /*
+     * Hand-offs to Connect - see `ConnectContextValue.openConnect`.
+     *
+     * The provider's own `clientId` prop wins; otherwise the bridge's, which is
+     * what makes this work for the common integration that never passes one.
+     */
+    const handoffClientId = clientId || session?.clientId || "";
+    const openConnect = useCallback((target, options = {}) => {
+        const returnTo = window.location.href;
+        if (handoff === "popup") {
+            // Deliberately no `noopener`: with it, `window.open` returns `null`
+            // by specification and Connect gets no `opener` - so it could
+            // neither tell this page it finished nor close itself (a browser
+            // only lets script close a window script opened). The opener it is
+            // handed is this page, and cross-origin that permits navigating it
+            // and posting to it - neither of which Connect does uninvited.
+            const opened = window.open(buildHandoffUrl(target, { appUrl, clientId: handoffClientId, mode: "popup", returnTo }), options.name ?? "_blank", options.features);
+            if (opened)
+                return opened;
+            // Blocked. A same-tab trip still gets them there and back, where a
+            // "your browser blocked the window" note leaves them to sort it out.
+        }
+        window.location.assign(buildHandoffUrl(target, { appUrl, clientId: handoffClientId, mode: "redirect", returnTo }));
+        return null;
+    }, [appUrl, handoff, handoffClientId]);
+    // Latest callback without re-subscribing the listener on every render of a
+    // host that passes an inline function.
+    const onHandoffResultRef = useRef(onHandoffResult);
+    useEffect(() => {
+        onHandoffResultRef.current = onHandoffResult;
+    });
+    useEffect(() => {
+        // Back from a redirect-mode trip. The page is a fresh load, so every read
+        // is already fresh - this only reports the outcome and tidies the URL.
+        // `replaceState` rather than a router call: this package imports no
+        // router, and Next's App Router honours a native `replaceState`.
+        const returned = takeHandoffResult(window.location.href);
+        if (returned) {
+            window.history.replaceState(window.history.state, "", returned.cleaned);
+            onHandoffResultRef.current?.(returned.result);
+        }
+        // A popup reporting in before it closes. `readHandoffMessage` checks the
+        // origin, which is what stops any other window driving this.
+        const onMessage = (event) => {
+            const result = readHandoffMessage(event, appUrl);
+            if (!result)
+                return;
+            // Session-wide: the plan, the readiness, the seat count - whatever the
+            // trip changed, every Connect component on the page re-reads it.
+            void refresh();
+            onHandoffResultRef.current?.(result);
+        };
+        window.addEventListener("message", onMessage);
+        return () => window.removeEventListener("message", onMessage);
+    }, [appUrl, refresh]);
     useEffect(() => {
         // `silentPending` already encodes settled-and-signed-out, no prior
         // attempt, and no bridge error - a failed bridge read says nothing about
@@ -293,8 +360,10 @@ export function ConnectProvider({ clientId = "", basePath = "/api/connect", redi
         }
     }, [fetchImpl, mutateResource, oneTapEndpoints, refresh]);
     const value = useMemo(() => ({
-        clientId,
+        clientId: handoffClientId,
         appUrl,
+        handoffMode: handoff,
+        openConnect,
         session,
         isLoading,
         error,
@@ -308,8 +377,10 @@ export function ConnectProvider({ clientId = "", basePath = "/api/connect", redi
         readOneTapHint,
         oneTapSignIn,
     }), [
-        clientId,
+        handoffClientId,
         appUrl,
+        handoff,
+        openConnect,
         session,
         isLoading,
         error,

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

@@ -1,5 +1,6 @@
 "use client";
 import { useCallback, useEffect, useRef, useState } from "react";
+import { readHandoffMessage } from "./handoff.js";
 import { useConnect } from "./provider.js";
 /** How often `/entitlements` is re-read while a checkout is open. */
 const POLL_INTERVAL_MS = 3_000;
@@ -30,7 +31,7 @@ const CLOSE_GRACE_MS = 12_000;
  * period rather than ending the run.
  */
 export function useConnectCheckout() {
-    const { fetchResource, invalidateResource, refresh } = useConnect();
+    const { appUrl, fetchResource, invalidateResource, refresh, openConnect } = useConnect();
     const [state, setState] = useState({ status: "idle", url: null });
     // Everything the poll loop needs lives in a ref: it runs from a timer, and
     // re-creating the loop whenever a piece of it changed identity would
@@ -51,20 +52,18 @@ export function useConnectCheckout() {
         // an await is what pop-up blockers exist to stop, and it would be
         // blocked in every browser regardless of the user's settings.
         //
-        // No `noopener`: with it set, `window.open` returns `null` by
-        // specification, and this hook would then read every successfully
-        // opened checkout as blocked. The handle is the whole point - it is
-        // how the grace period below knows the customer closed the window.
-        // The window it hands an `opener` to is Connect's own origin, and
-        // cross-origin access is limited to navigating this page, which
-        // Connect does not do.
-        const opened = window.open(url, "connect_checkout", "popup,width=520,height=780");
-        if (!opened) {
-            // Not a failure to report as an error: the customer can still get
-            // there, they just have to click the link themselves.
-            setState({ status: "blocked", url });
+        // Through `openConnect`, which stamps the way back on the URL: Connect
+        // then closes this window itself once the change lands, instead of
+        // leaving the customer on a billing page they have to close by hand.
+        // The handle is still what the grace period below watches.
+        //
+        // `null` means it did not open a window - the provider is in `redirect`
+        // mode, or the popup was blocked and it fell back to one - and this
+        // page is navigating away. Nothing to watch; the trip back is a fresh
+        // load that reads the new entitlement on its own.
+        const opened = openConnect(url, { name: "connect_checkout", features: "popup,width=520,height=780" });
+        if (!opened)
             return;
-        }
         run.current = {
             url,
             isSettled,
@@ -74,7 +73,7 @@ export function useConnectCheckout() {
             generation: generation.current,
         };
         setState({ status: "waiting", url });
-    }, [stop]);
+    }, [openConnect, stop]);
     useEffect(() => {
         // One interval for the hook's whole life rather than one per run: it does
         // nothing while `run.current` is null, and a run that starts from a press
@@ -130,11 +129,19 @@ export function useConnectCheckout() {
                 void poll();
         };
         document.addEventListener("visibilitychange", onVisible);
+        // Connect saying it is done is a stronger hint still - read now, before
+        // the window has even finished closing.
+        const onMessage = (event) => {
+            if (readHandoffMessage(event, appUrl))
+                void poll();
+        };
+        window.addEventListener("message", onMessage);
         return () => {
             clearInterval(interval);
             document.removeEventListener("visibilitychange", onVisible);
+            window.removeEventListener("message", onMessage);
         };
-    }, [fetchResource, invalidateResource, refresh, stop]);
+    }, [appUrl, fetchResource, invalidateResource, refresh, stop]);
     return { ...state, start, reset };
 }
 /**

package/dist/esm/server/client.js

@@ -22,6 +22,7 @@ import { SessionsResource } from "./resources/sessions.js";
 import { PlatformResource } from "./resources/platform.js";
 import { VisitorResource } from "./resources/visitor.js";
 import { PushResource } from "./resources/push.js";
+import { WhatsAppResource } from "./resources/whatsapp.js";
 export const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 const APPLICATION_API_PREFIX = "/api/v1/application";
 /**
@@ -125,6 +126,8 @@ export class ConnectClient {
      * preferences; you supply a title, a body and a URL. See `PushResource`.
      */
     push;
+    /** Your application's own approved WhatsApp templates, to a workspace's customers. */
+    whatsapp;
     /**
      * Relays one `/data/*` or `/kv/*` request verbatim - `createConnectHandler`'s
      * store route and nothing else. See `storePassthrough`.
@@ -171,8 +174,9 @@ export class ConnectClient {
         this.visitor = new VisitorResource(transport);
         this.platform = new PlatformResource(transport);
         this.push = new PushResource(transport);
+        this.whatsapp = new WhatsAppResource(transport);
         this.storeRelay = (spec) => storePassthrough(transport, spec);
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.41.0";
+export const SDK_VERSION = "0.42.0";

package/dist/esm/server/handler.js

@@ -408,6 +408,8 @@ export function createConnectHandler(options) {
      * anyone who used it).
      */
     const oneTapEndpoints = session.write ? client.identity.oneTapEndpoints() : null;
+    /** See `IdentityResource.publicClientId` - what lets the browser name this application on a hand-off. */
+    const clientId = client.identity.publicClientId();
     const routes = {
         "GET /session": async (request) => {
             const token = await session.read(request);
@@ -429,9 +431,10 @@ export function createConnectHandler(options) {
                     // whose shape depends on the answer is a response consumers start
                     // testing for key presence instead of value.
                     oneTap: oneTapEndpoints,
+                    clientId,
                 });
             }
-            return json({ ...(await client.identity.getUser(token)), oneTap: oneTapEndpoints });
+            return json({ ...(await client.identity.getUser(token)), oneTap: oneTapEndpoints, clientId });
         },
         "GET /entitlements": async (request) => {
             const { workspaceId } = await requireWorkspace(request);

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

@@ -89,6 +89,18 @@ export class IdentityResource {
         authorize.searchParams.set("client_id", this.clientId);
         return { hintUrl: hint.toString(), authorizeUrl: authorize.toString() };
     }
+    /**
+     * This client's public `client_id`, or `null` when none is configured.
+     *
+     * The bridge hands it to the browser on `/session` so `openConnect` can name
+     * the application on every hand-off without the host passing `clientId` to
+     * `<ConnectProvider>` too - Connect only honours a `return_to` it can match
+     * against *a client's* registered redirect origins. Public by definition:
+     * it already rides on every authorize URL.
+     */
+    publicClientId() {
+        return this.clientId;
+    }
     /** 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/esm/server/resources/whatsapp.js

@@ -0,0 +1,54 @@
+import { request } from "../http.js";
+/**
+ * Your application's own WhatsApp templates, sent to a workspace's customers
+ * through Connect's WhatsApp sender - no WhatsApp Business account of your
+ * own.
+ *
+ * Templates are written and submitted to Meta in Console under your
+ * application; you name them here by slug and Connect resolves
+ * `app_<yourApplicationKey>_<slug>` from your key, so a key can never send
+ * another application's message or one of Connect's own. There is no free
+ * text: outside a customer's 24-hour window WhatsApp permits nothing else.
+ *
+ * Server-to-server only - there is no browser path, by design.
+ */
+export class WhatsAppResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Send one template to one customer.
+     *
+     * Refusals arrive as a `ConnectError` whose `code` says what to tell the
+     * person who pressed Send - `template_not_approved`, `consent_required`,
+     * `opted_out`, `not_found`. None of them is a fault worth retrying.
+     *
+     * An `Idempotency-Key` is always sent, as on `otp.send`: a retried send
+     * without one is a second message on somebody's phone. Pass your own -
+     * derived from what is being sent, e.g. the quote number - to make a
+     * retry from a *later* request safe too.
+     */
+    send(input, options = {}) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/whatsapp/messages",
+            json: input,
+            headers: { "idempotency-key": options.idempotencyKey ?? crypto.randomUUID() },
+        });
+    }
+    /**
+     * Whether a template would send right now, and the values it needs.
+     *
+     * Ask before offering WhatsApp on a screen: Meta's approval takes minutes
+     * to days, and an approved template can be paused later. A `ConnectError`
+     * with `status: 404` means your application has no such template.
+     */
+    template(slug, options = {}) {
+        const language = options.language ? `?language=${encodeURIComponent(options.language)}` : "";
+        return request(this.transport, {
+            method: "GET",
+            path: `/whatsapp/templates/${encodeURIComponent(slug)}${language}`,
+        });
+    }
+}

package/dist/types/client/components/ask-ai-errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What Ask AI shows when something fails - a sentence for a person, never the
+ * error itself.
+ *
+ * The raw text is somebody else's diagnostic: `TypeError: Failed to fetch`
+ * from the browser, `Connect bridge returned 502` from the provider, a
+ * validation message naming a request field. None of it tells the person what
+ * happened or what to do, and the last one tells them something about the
+ * API they should not need to know. The real error is still on the console of
+ * whoever is debugging; this module decides only what is on screen.
+ */
+export declare const ASK_AI_GENERIC_FAILURE = "Something went wrong. Please try again.";
+export declare const TOOL_GENERIC_FAILURE = "That step couldn't be completed. Try again in a moment.";
+/**
+ * A failure Connect reported inside the stream, after it had opened.
+ *
+ * Kept apart from a transport failure because its text was written for the
+ * person by Connect's own stream error handler, so it may be shown as it is.
+ */
+export declare class AskAiStreamError extends Error {
+    readonly name = "AskAiStreamError";
+}
+export declare function describeAskAiFailure(cause: unknown): string;
+/**
+ * Whether trying the same question again could help.
+ *
+ * Off for the failures a retry cannot fix - signed out, no access, Ask AI
+ * switched off - so the panel does not offer a button that will fail the same
+ * way every time.
+ */
+export declare function isRetryableAskAiFailure(cause: unknown): boolean;
+/**
+ * The failure a tool's *result* reports, or `null` when it succeeded.
+ *
+ * An application's tool answers `{ isError: true, ... }` rather than throwing,
+ * which is MCP's distinction between "the tool refused" and "the call broke".
+ * Connect puts its own sentence in `error.message` when it could not reach
+ * the application at all; otherwise the application's first text block is its
+ * own refusal ("You don't have permission to ..."), written for its own user.
+ */
+export declare function toolFailureFromOutput(output: unknown): string | null;

package/dist/types/client/components/ask-ai-turns.d.ts

@@ -14,6 +14,11 @@ export type AskAiBlock = {
     id: string;
     name: string;
     input: unknown | null;
+    /**
+     * Set when the step failed - a sentence for the person, never the raw
+     * error. See `toolFailureFromOutput`.
+     */
+    failure?: string;
 };
 export interface AskAiTurn {
     id: string;

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

@@ -0,0 +1,62 @@
+/**
+ * The hand-off contract with Connect's portal - the pure half, so the rules
+ * can be tested without a browser. `openConnect` (on `useConnect()`) is the
+ * half that touches `window`.
+ *
+ * Every time this SDK sends somebody to Connect for a task - a plan, a
+ * payment method, their profile - it appends three params, and Connect's
+ * portal brings them back when the task is done:
+ *
+ * | Param | |
+ * |---|---|
+ * | `client_id` | Names this application. Connect only honours a `return_to` whose origin is registered for that client. |
+ * | `return_to` | The page they left. |
+ * | `mode` | `popup` - Connect closes its window when done and posts the outcome to this page first. `redirect` - Connect navigates back here with `?connect_result=`. |
+ */
+/** How this application sends people to Connect - see `ConnectProviderProps.handoff`. */
+export type ConnectHandoffMode = "popup" | "redirect";
+/**
+ * How a trip to Connect ended, as Connect reports it.
+ *
+ * Advisory. A payment confirmed by webhook can settle a moment after the
+ * window has closed, so `"completed"` means "they finished there", not "it is
+ * live" - re-read entitlements for that. The provider already does, for every
+ * hand-off.
+ */
+export type ConnectHandoffResult = "completed" | "cancelled" | "closed";
+/** `MessageEvent.data.type` of the message Connect posts before closing a popup. */
+export declare const CONNECT_HANDOFF_MESSAGE_TYPE = "connect:handoff";
+/** The query param Connect adds when it redirects back. */
+export declare const CONNECT_HANDOFF_RESULT_PARAM = "connect_result";
+export interface HandoffUrlOptions {
+    appUrl: string;
+    /** Empty when neither the provider nor the bridge knows it - the URL still works, Connect just cannot offer the way back. */
+    clientId: string;
+    mode: ConnectHandoffMode;
+    /** The page to come back to - `window.location.href` at the moment of the press. */
+    returnTo: string;
+}
+/**
+ * `target` - a path (`"/billing"`) or an absolute Connect URL (a readiness
+ * blocker's `resolveUrl`) - with the hand-off params set.
+ *
+ * Throws for a URL on any other origin: these params tell Connect where to
+ * send somebody back, and stamping them onto a third party's URL would hand
+ * that party the page this visitor was on.
+ */
+export declare function buildHandoffUrl(target: string, { appUrl, clientId, mode, returnTo }: HandoffUrlOptions): string;
+/**
+ * The result a `message` event carries, or `null` when it is not Connect's
+ * hand-off message. The origin check is the whole security story: any page
+ * can `postMessage` this window, and only Connect's verdict may trigger work.
+ */
+export declare function readHandoffMessage(event: Pick<MessageEvent, "origin" | "data">, appUrl: string): ConnectHandoffResult | null;
+/**
+ * The result a redirect-mode return carries in `href`, and `href` with it
+ * removed - so a reload does not report the same trip twice and the param
+ * does not end up in a link somebody shares.
+ */
+export declare function takeHandoffResult(href: string): {
+    result: ConnectHandoffResult;
+    cleaned: string;
+} | null;