@cosmoops/connect-sdk 0.41.0 → 0.43.0

package/dist/cjs/client/components/subscription.js

@@ -80,13 +80,13 @@ function ConnectNoSubscriptionCard({ plansHref = DEFAULT_PLANS_HREF, title = "Yo
  * impure and re-renders wrong.
  */
 function ConnectSubscriptionCard({ plansHref, className }) {
-    const { appUrl } = (0, provider_js_1.useConnect)();
+    const { openConnect } = (0, provider_js_1.useConnect)();
     const { isLoading, detail, plan, state } = useSubscriptionState();
     if (isLoading)
         return (0, jsx_runtime_1.jsx)(react_1.Skeleton, { className: (0, cn_js_1.cn)("h-48 rounded-xl", className) });
     if (!detail || !plan)
         return (0, jsx_runtime_1.jsx)(ConnectNoSubscriptionCard, { plansHref: plansHref, className: className });
-    return ((0, jsx_runtime_1.jsx)(motion_js_1.MotionProvider, { children: (0, jsx_runtime_1.jsx)(motion_js_1.m.div, { initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { duration: 0.2 }, children: (0, jsx_runtime_1.jsxs)(react_1.Card, { className: className, children: [(0, jsx_runtime_1.jsxs)(react_1.Card.Header, { children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex items-start justify-between gap-2", children: [(0, jsx_runtime_1.jsx)(react_1.Card.Title, { children: plan.name }), (0, jsx_runtime_1.jsx)(SubscriptionChip, { state: state })] }), (0, jsx_runtime_1.jsxs)(react_1.Card.Description, { children: [(0, plan_pricing_js_1.formatPrice)(plan.price), " + ", plan.gstRate, "% GST per", " ", (0, plan_pricing_js_1.intervalLabel)(plan.billingInterval).per] })] }), (0, jsx_runtime_1.jsxs)(react_1.Card.Content, { className: "flex flex-col gap-2 text-sm", children: [(0, jsx_runtime_1.jsx)(NextEvent, { detail: detail, state: state }), (0, jsx_runtime_1.jsx)(ConnectSeatUsage, { plan: plan, detail: detail })] }), (0, jsx_runtime_1.jsxs)(react_1.Card.Footer, { className: "flex flex-wrap gap-2", children: [(0, jsx_runtime_1.jsxs)(react_1.Button, { variant: "secondary", onPress: () => window.open(`${appUrl}/billing/subscriptions/${detail.id}`, "_blank", "noopener,noreferrer"), children: ["Manage on Connect", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5" })] }), (0, jsx_runtime_1.jsx)(link_button_js_1.ConnectLinkButton, { href: plansHref ?? DEFAULT_PLANS_HREF, variant: "tertiary", children: "Change plan" })] })] }) }) }));
+    return ((0, jsx_runtime_1.jsx)(motion_js_1.MotionProvider, { children: (0, jsx_runtime_1.jsx)(motion_js_1.m.div, { initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { duration: 0.2 }, children: (0, jsx_runtime_1.jsxs)(react_1.Card, { className: className, children: [(0, jsx_runtime_1.jsxs)(react_1.Card.Header, { children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex items-start justify-between gap-2", children: [(0, jsx_runtime_1.jsx)(react_1.Card.Title, { children: plan.name }), (0, jsx_runtime_1.jsx)(SubscriptionChip, { state: state })] }), (0, jsx_runtime_1.jsxs)(react_1.Card.Description, { children: [(0, plan_pricing_js_1.formatPrice)(plan.price), " + ", plan.gstRate, "% GST per", " ", (0, plan_pricing_js_1.intervalLabel)(plan.billingInterval).per] })] }), (0, jsx_runtime_1.jsxs)(react_1.Card.Content, { className: "flex flex-col gap-2 text-sm", children: [(0, jsx_runtime_1.jsx)(NextEvent, { detail: detail, state: state }), (0, jsx_runtime_1.jsx)(ConnectSeatUsage, { plan: plan, detail: detail })] }), (0, jsx_runtime_1.jsxs)(react_1.Card.Footer, { className: "flex flex-wrap gap-2", children: [(0, jsx_runtime_1.jsxs)(react_1.Button, { variant: "secondary", onPress: () => openConnect(`/billing/subscriptions/${encodeURIComponent(detail.id)}`), children: ["Manage on Connect", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5" })] }), (0, jsx_runtime_1.jsx)(link_button_js_1.ConnectLinkButton, { href: plansHref ?? DEFAULT_PLANS_HREF, variant: "tertiary", children: "Change plan" })] })] }) }) }));
 }
 function SubscriptionChip({ state }) {
     switch (state) {
@@ -157,11 +157,11 @@ function ConnectSeatUsage({ plan, detail, className, }) {
  * actually cares about anyway.
  */
 function ConnectTrialBanner({ plansHref, className }) {
-    const { appUrl } = (0, provider_js_1.useConnect)();
+    const { openConnect } = (0, provider_js_1.useConnect)();
     const { detail, state } = useSubscriptionState();
     if (state !== "trialing" || !detail)
         return null;
-    return ((0, jsx_runtime_1.jsxs)("div", { className: (0, cn_js_1.cn)("flex flex-wrap items-center justify-between gap-3 rounded-lg bg-accent-soft px-3 py-2 text-sm text-accent", className), children: [(0, jsx_runtime_1.jsxs)("span", { className: "flex items-center gap-2", children: [(0, jsx_runtime_1.jsx)(lucide_react_1.Clock, { className: "size-4 shrink-0", "aria-hidden": "true" }), "You're on a free trial", detail.nextBillingDate ? `. Your first charge is on ${formatDate(detail.nextBillingDate)}.` : "."] }), (0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2", children: [(0, jsx_runtime_1.jsx)(link_button_js_1.ConnectLinkButton, { href: plansHref ?? DEFAULT_PLANS_HREF, variant: "tertiary", children: "Compare plans" }), (0, jsx_runtime_1.jsxs)(react_1.Button, { variant: "secondary", onPress: () => window.open(`${appUrl}/billing/subscriptions/${detail.id}`, "_blank", "noopener,noreferrer"), children: ["Manage", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5" })] })] })] }));
+    return ((0, jsx_runtime_1.jsxs)("div", { className: (0, cn_js_1.cn)("flex flex-wrap items-center justify-between gap-3 rounded-lg bg-accent-soft px-3 py-2 text-sm text-accent", className), children: [(0, jsx_runtime_1.jsxs)("span", { className: "flex items-center gap-2", children: [(0, jsx_runtime_1.jsx)(lucide_react_1.Clock, { className: "size-4 shrink-0", "aria-hidden": "true" }), "You're on a free trial", detail.nextBillingDate ? `. Your first charge is on ${formatDate(detail.nextBillingDate)}.` : "."] }), (0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2", children: [(0, jsx_runtime_1.jsx)(link_button_js_1.ConnectLinkButton, { href: plansHref ?? DEFAULT_PLANS_HREF, variant: "tertiary", children: "Compare plans" }), (0, jsx_runtime_1.jsxs)(react_1.Button, { variant: "secondary", onPress: () => openConnect(`/billing/subscriptions/${encodeURIComponent(detail.id)}`), children: ["Manage", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5" })] })] })] }));
 }
 /**
  * Renders `children` for a subscribed workspace, and the "pick a plan" card for

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

@@ -13,7 +13,6 @@ const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("@heroui/react");
 const lucide_react_1 = require("lucide-react");
 const provider_js_1 = require("../provider.js");
-const portal_links_js_1 = require("../portal-links.js");
 const mark_js_1 = require("../mark.js");
 const identity_js_1 = require("./identity.js");
 const account_sessions_js_1 = require("./account-sessions.js");
@@ -26,6 +25,12 @@ const THEME_OPTIONS = [
     { value: "dark", label: "Dark", icon: lucide_react_1.Moon },
     { value: "system", label: "System", icon: lucide_react_1.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");
 }
@@ -100,8 +105,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 ((0, jsx_runtime_1.jsxs)(react_1.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 ${surfaces_js_1.PANEL_FILL} p-3 hover:border-accent hover:bg-surface-secondary`, onPress: () => openExternal(url), children: [(0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "absolute end-2 top-2 size-3.5 text-muted", "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)("span", { className: `flex ${surfaces_js_1.MEDALLION} items-center justify-center rounded-xl bg-surface text-muted`, children: icon }), (0, jsx_runtime_1.jsx)("span", { className: "text-xs font-medium text-foreground", children: label })] }));
+function DestinationTile({ icon, label, onPress, newTab, }) {
+    return ((0, jsx_runtime_1.jsxs)(react_1.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 ${surfaces_js_1.PANEL_FILL} p-3 hover:border-accent hover:bg-surface-secondary`, onPress: onPress, children: [newTab && (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "absolute end-2 top-2 size-3.5 text-muted", "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)("span", { className: `flex ${surfaces_js_1.MEDALLION} items-center justify-center rounded-xl bg-surface text-muted`, children: icon }), (0, jsx_runtime_1.jsx)("span", { className: "text-xs font-medium text-foreground", children: label })] }));
 }
 /**
  * The account modal's contents - identity card, the three Connect
@@ -122,14 +127,14 @@ function DestinationTile({ icon, label, url, }) {
  * three navigations.
  */
 function ProfileSurface({ onSignOut, theme, onThemeChange, }) {
-    const { session, signOut, appUrl, clientId } = (0, provider_js_1.useConnect)();
+    const { session, signOut, appUrl, openConnect, handoffMode } = (0, provider_js_1.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 ((0, jsx_runtime_1.jsx)(react_1.Modal.Backdrop, { children: (0, jsx_runtime_1.jsx)(react_1.Modal.Container, { size: "md", scroll: "inside", children: (0, jsx_runtime_1.jsxs)(react_1.Modal.Dialog, { children: [(0, jsx_runtime_1.jsx)(react_1.Modal.CloseTrigger, {}), (0, jsx_runtime_1.jsx)(react_1.Modal.Header, { children: (0, jsx_runtime_1.jsx)(react_1.Modal.Heading, { children: "Account" }) }), (0, jsx_runtime_1.jsxs)(react_1.Modal.Body, { className: "flex flex-col gap-5", children: [(0, jsx_runtime_1.jsxs)("div", { className: `flex items-start gap-3 rounded-xl border border-border ${surfaces_js_1.PANEL_FILL} p-4`, children: [(0, jsx_runtime_1.jsx)(UserAvatar, { user: user, size: "lg" }), (0, jsx_runtime_1.jsxs)("div", { className: "flex min-w-0 flex-1 flex-col gap-0.5", children: [(0, jsx_runtime_1.jsx)("p", { className: "truncate text-sm font-semibold text-foreground", children: label }), user.email && (0, jsx_runtime_1.jsx)("p", { className: "truncate text-xs text-muted", children: user.email }), (0, jsx_runtime_1.jsx)("p", { className: "truncate text-xs text-muted", children: user.workspaceName }), (role || planChip || !user.emailVerified) && ((0, jsx_runtime_1.jsxs)("div", { className: "mt-1.5 flex flex-wrap items-center gap-1.5", children: [role && ((0, jsx_runtime_1.jsx)(react_1.Chip, { size: "sm", variant: "soft", color: "accent", children: humanizeRole(role) })), planChip, !user.emailVerified && ((0, jsx_runtime_1.jsx)(react_1.Chip, { size: "sm", variant: "soft", color: "warning", children: "Email unverified" }))] }))] })] }), (0, jsx_runtime_1.jsxs)("div", { className: "grid grid-cols-3 gap-2", children: [(0, jsx_runtime_1.jsx)(DestinationTile, { icon: (0, jsx_runtime_1.jsx)(lucide_react_1.UserRound, { className: surfaces_js_1.ICON, "aria-hidden": "true" }), label: "Profile", url: (0, portal_links_js_1.connectPortalUrl)(appUrl, clientId, "/profile") }), (0, jsx_runtime_1.jsx)(DestinationTile, { icon: (0, jsx_runtime_1.jsx)(lucide_react_1.CreditCard, { className: surfaces_js_1.ICON, "aria-hidden": "true" }), label: "Billing", url: `${appUrl}/billing` }), (0, jsx_runtime_1.jsx)(DestinationTile, { icon: (0, jsx_runtime_1.jsx)(mark_js_1.ConnectMark, { className: surfaces_js_1.ICON }), label: "Connect", url: appUrl })] }), theme && onThemeChange && ((0, jsx_runtime_1.jsxs)("div", { className: "flex flex-col gap-2", children: [(0, jsx_runtime_1.jsx)("p", { className: "text-sm font-medium text-foreground", children: "Appearance" }), (0, jsx_runtime_1.jsx)(react_1.ToggleButtonGroup, { fullWidth: true, "aria-label": "Theme", selectionMode: "single", disallowEmptySelection: true, selectedKeys: [theme], onSelectionChange: (keys) => {
+    return ((0, jsx_runtime_1.jsx)(react_1.Modal.Backdrop, { children: (0, jsx_runtime_1.jsx)(react_1.Modal.Container, { size: "md", scroll: "inside", children: (0, jsx_runtime_1.jsxs)(react_1.Modal.Dialog, { children: [(0, jsx_runtime_1.jsx)(react_1.Modal.CloseTrigger, {}), (0, jsx_runtime_1.jsx)(react_1.Modal.Header, { children: (0, jsx_runtime_1.jsx)(react_1.Modal.Heading, { children: "Account" }) }), (0, jsx_runtime_1.jsxs)(react_1.Modal.Body, { className: "flex flex-col gap-5", children: [(0, jsx_runtime_1.jsxs)("div", { className: `flex items-start gap-3 rounded-xl border border-border ${surfaces_js_1.PANEL_FILL} p-4`, children: [(0, jsx_runtime_1.jsx)(UserAvatar, { user: user, size: "lg" }), (0, jsx_runtime_1.jsxs)("div", { className: "flex min-w-0 flex-1 flex-col gap-0.5", children: [(0, jsx_runtime_1.jsx)("p", { className: "truncate text-sm font-semibold text-foreground", children: label }), user.email && (0, jsx_runtime_1.jsx)("p", { className: "truncate text-xs text-muted", children: user.email }), (0, jsx_runtime_1.jsx)("p", { className: "truncate text-xs text-muted", children: user.workspaceName }), (role || planChip || !user.emailVerified) && ((0, jsx_runtime_1.jsxs)("div", { className: "mt-1.5 flex flex-wrap items-center gap-1.5", children: [role && ((0, jsx_runtime_1.jsx)(react_1.Chip, { size: "sm", variant: "soft", color: "accent", children: humanizeRole(role) })), planChip, !user.emailVerified && ((0, jsx_runtime_1.jsx)(react_1.Chip, { size: "sm", variant: "soft", color: "warning", children: "Email unverified" }))] }))] })] }), (0, jsx_runtime_1.jsxs)("div", { className: "grid grid-cols-3 gap-2", children: [(0, jsx_runtime_1.jsx)(DestinationTile, { icon: (0, jsx_runtime_1.jsx)(lucide_react_1.UserRound, { className: surfaces_js_1.ICON, "aria-hidden": "true" }), label: "Profile", onPress: () => openConnect("/profile"), newTab: handoffMode === "popup" }), (0, jsx_runtime_1.jsx)(DestinationTile, { icon: (0, jsx_runtime_1.jsx)(lucide_react_1.CreditCard, { className: surfaces_js_1.ICON, "aria-hidden": "true" }), label: "Billing", onPress: () => openConnect("/billing"), newTab: handoffMode === "popup" }), (0, jsx_runtime_1.jsx)(DestinationTile, { icon: (0, jsx_runtime_1.jsx)(mark_js_1.ConnectMark, { className: surfaces_js_1.ICON }), label: "Connect", onPress: () => openExternal(appUrl), newTab: true })] }), theme && onThemeChange && ((0, jsx_runtime_1.jsxs)("div", { className: "flex flex-col gap-2", children: [(0, jsx_runtime_1.jsx)("p", { className: "text-sm font-medium text-foreground", children: "Appearance" }), (0, jsx_runtime_1.jsx)(react_1.ToggleButtonGroup, { fullWidth: true, "aria-label": "Theme", selectionMode: "single", disallowEmptySelection: true, selectedKeys: [theme], onSelectionChange: (keys) => {
                                             const [next] = [...keys];
                                             if (typeof next === "string")
                                                 onThemeChange(next);
@@ -207,8 +212,8 @@ function ConnectUserMenu({ compact = false, ...rest }) {
  * state, a settings page.
  */
 function ConnectManageSubscriptionButton({ className }) {
-    const { appUrl } = (0, provider_js_1.useConnect)();
-    return ((0, jsx_runtime_1.jsxs)(react_1.Button, { variant: "secondary", className: className, onPress: () => openExternal(`${appUrl}/billing`), children: [(0, jsx_runtime_1.jsx)(lucide_react_1.CreditCard, { className: "size-4 shrink-0" }), "Manage subscription", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
+    const { openConnect } = (0, provider_js_1.useConnect)();
+    return ((0, jsx_runtime_1.jsxs)(react_1.Button, { variant: "secondary", className: className, onPress: () => openConnect("/billing"), children: [(0, jsx_runtime_1.jsx)(lucide_react_1.CreditCard, { className: "size-4 shrink-0" }), "Manage subscription", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
 }
 /**
  * Invoices and payment history, on Connect.
@@ -221,10 +226,10 @@ function ConnectManageSubscriptionButton({ className }) {
  * version of a record that must have exactly one.
  */
 function ConnectInvoicesButton({ className }) {
-    const { session, appUrl } = (0, provider_js_1.useConnect)();
+    const { session, openConnect } = (0, provider_js_1.useConnect)();
     if (!session?.user)
         return null;
-    return ((0, jsx_runtime_1.jsxs)(react_1.Button, { variant: "tertiary", className: className, onPress: () => openExternal(`${appUrl}/billing/invoices`), children: [(0, jsx_runtime_1.jsx)(lucide_react_1.ReceiptText, { className: "size-4 shrink-0" }), "Invoices", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
+    return ((0, jsx_runtime_1.jsxs)(react_1.Button, { variant: "tertiary", className: className, onPress: () => openConnect("/billing/invoices"), children: [(0, jsx_runtime_1.jsx)(lucide_react_1.ReceiptText, { className: "size-4 shrink-0" }), "Invoices", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
 }
 /**
  * The "Profile" action on its own - the third of the three Connect
@@ -236,10 +241,10 @@ function ConnectInvoicesButton({ className }) {
  * and got no `return_to`, so the user had no way back.
  */
 function ConnectProfileButton({ className }) {
-    const { session, appUrl, clientId } = (0, provider_js_1.useConnect)();
+    const { session, openConnect } = (0, provider_js_1.useConnect)();
     if (!session?.user)
         return null;
-    return ((0, jsx_runtime_1.jsxs)(react_1.Button, { variant: "tertiary", className: className, onPress: () => openExternal((0, portal_links_js_1.connectPortalUrl)(appUrl, clientId, "/profile")), children: [(0, jsx_runtime_1.jsx)(lucide_react_1.UserRound, { className: "size-4 shrink-0" }), "Profile", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
+    return ((0, jsx_runtime_1.jsxs)(react_1.Button, { variant: "tertiary", className: className, onPress: () => openConnect("/profile"), children: [(0, jsx_runtime_1.jsx)(lucide_react_1.UserRound, { className: "size-4 shrink-0" }), "Profile", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5 shrink-0 text-muted" })] }));
 }
 /** A plain "Open Connect" button, for a footer or a help menu. */
 function ConnectHomeButton({ className }) {

package/dist/cjs/client/handoff.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * 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=`. |
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONNECT_HANDOFF_RESULT_PARAM = exports.CONNECT_HANDOFF_MESSAGE_TYPE = void 0;
+exports.buildHandoffUrl = buildHandoffUrl;
+exports.readHandoffMessage = readHandoffMessage;
+exports.takeHandoffResult = takeHandoffResult;
+/** `MessageEvent.data.type` of the message Connect posts before closing a popup. */
+exports.CONNECT_HANDOFF_MESSAGE_TYPE = "connect:handoff";
+/** The query param Connect adds when it redirects back. */
+exports.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.
+ */
+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.
+ */
+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 === exports.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.
+ */
+function takeHandoffResult(href) {
+    const url = new URL(href);
+    const result = url.searchParams.get(exports.CONNECT_HANDOFF_RESULT_PARAM);
+    if (!isResult(result))
+        return null;
+    url.searchParams.delete(exports.CONNECT_HANDOFF_RESULT_PARAM);
+    return { result, cleaned: url.toString() };
+}

package/dist/cjs/client/index.js

@@ -1,9 +1,9 @@
 "use client";
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConnectSideNav = exports.ConnectSidebarNav = exports.RAIL_EXPANDED = exports.RAIL_COLLAPSED = exports.sidebarRowClass = exports.useConnectShell = exports.ConnectShellProvider = exports.ConnectSidebarRow = exports.ConnectSidebarFooter = exports.ConnectSidebarBody = exports.ConnectSidebarHeader = exports.ConnectSidebar = exports.AppShell = exports.useConnectPortalUrl = exports.connectPortalUrl = exports.ConnectAccountSessions = exports.ConnectSignOutButton = exports.ConnectHomeButton = exports.ConnectProfileButton = exports.ConnectInvoicesButton = exports.ConnectManageSubscriptionButton = exports.ConnectUserMenu = exports.ConnectProfileModal = exports.ConnectUserButton = exports.ConnectOneTap = exports.ConnectRegisterButton = exports.ConnectLoginButton = exports.ConnectLogo = exports.ConnectMark = exports.ConnectGrievanceNotice = exports.isConnectError = exports.ConnectError = exports.normalizePlanFeatures = exports.blockingBlockers = exports.CONNECT_APP_URL = exports.useConnectResource = exports.useConnectIntegrations = exports.useConnectSessions = exports.useConnectAddonUsage = exports.useConnectCompanyProfile = exports.useConnectApps = exports.useConnectPlans = exports.useConnectEntitlements = exports.useConnectPlatformAccess = exports.useConnectAudience = exports.useConnectWorkspaceType = exports.useConnectUser = exports.useConnectOptional = exports.useConnect = exports.ConnectProvider = void 0;
-exports.ConnectConfirmDialog = exports.ConnectLinkButton = exports.ConnectPlansPage = exports.ConnectUsageMeter = exports.ConnectPlatformGate = exports.ConnectWorkspaceTypeGate = exports.useConnectFeature = exports.ConnectFeatureGate = exports.useConnectAccessGate = exports.ConnectAccessGate = exports.ConnectReadinessGate = exports.ConnectReadinessBanner = exports.resolveSubscriptionState = exports.ConnectSeatUsage = exports.ConnectTrialBanner = exports.ConnectSubscriptionCard = exports.ConnectNoSubscriptionCard = exports.ConnectSubscriptionGate = exports.ConnectSubscribeDialog = exports.ConnectPlans = exports.ConnectIntegrationsModal = exports.AI_TONE_DOT = exports.AI_TONE_CHIP = exports.AI_EMPTY_VALUE = exports.aiStatusTone = exports.isNumericAiFormat = exports.formatAiValue = exports.AiSources = exports.AiSteps = exports.AiDetails = exports.AiTimeline = exports.AiMetrics = exports.AiChart = exports.AiTable = exports.ConnectAskAi = exports.ConnectAppsGrid = exports.visitorSlotOfferFrom = exports.readVisitorStream = exports.ConnectVisitorChat = exports.isLinkableConnectScreen = exports.matchConnectScreen = exports.filterNavForAudience = exports.gateExemptPaths = exports.isNavItemActive = exports.resolveActivePath = exports.normalizePath = exports.flattenNav = exports.normalizeNav = exports.useConnectPush = exports.useActivePath = void 0;
-exports.zonedInstant = exports.dayColumns = exports.layoutBookings = exports.useBookingActions = exports.useBookings = exports.useAvailableSlots = exports.useUpdateEventType = exports.useCreateEventType = exports.useManageableEventTypes = exports.useUpdateAvailabilitySchedule = exports.useCreateAvailabilitySchedule = exports.useAvailabilitySchedules = exports.useBookableEventTypes = exports.ConnectEventTypeFormModal = exports.ConnectAvailabilityFormModal = exports.ConnectBookingDetail = exports.ConnectBookingDialog = exports.ConnectBookingCalendar = exports.useConnectCall = exports.ConnectCallingStatus = exports.ConnectCallButton = exports.ConnectCallProvider = exports.useCreateWorkspace = exports.ConnectCreateWorkspaceModal = exports.useConnectWorkspaceMembers = exports.useConnectWorkspaces = exports.ConnectWorkspaceSwitcher = exports.resolvePlanGroup = exports.groupPlansByTier = exports.isFreePlan = exports.ACTION_LABEL = exports.discountLabel = exports.annualSaving = exports.checkoutSubscriptionId = exports.resolveAction = exports.monthlyOf = exports.formatPrice = exports.buildCheckoutUrl = exports.useConnectCheckout = exports.ConnectFilterTabs = exports.ConnectCursorPagination = void 0;
+exports.RAIL_EXPANDED = exports.RAIL_COLLAPSED = exports.sidebarRowClass = exports.useConnectShell = exports.ConnectShellProvider = exports.ConnectSidebarRow = exports.ConnectSidebarFooter = exports.ConnectSidebarBody = exports.ConnectSidebarHeader = exports.ConnectSidebar = exports.AppShell = exports.useConnectPortalUrl = exports.connectPortalUrl = exports.ConnectAccountSessions = exports.ConnectSignOutButton = exports.ConnectHomeButton = exports.ConnectProfileButton = exports.ConnectInvoicesButton = exports.ConnectManageSubscriptionButton = exports.ConnectUserMenu = exports.ConnectProfileModal = exports.ConnectUserButton = exports.ConnectOneTap = exports.ConnectRegisterButton = exports.ConnectLoginButton = exports.ConnectLogo = exports.ConnectMark = exports.ConnectGrievanceNotice = exports.isConnectError = exports.ConnectError = exports.normalizePlanFeatures = exports.blockingBlockers = exports.CONNECT_HANDOFF_RESULT_PARAM = exports.CONNECT_HANDOFF_MESSAGE_TYPE = exports.CONNECT_APP_URL = exports.useConnectResource = exports.useConnectIntegrations = exports.useConnectSessions = exports.useConnectAddonUsage = exports.useConnectCompanyProfile = exports.useConnectApps = exports.useConnectPlans = exports.useConnectEntitlements = exports.useConnectPlatformAccess = exports.useConnectAudience = exports.useConnectWorkspaceType = exports.useConnectUser = exports.useConnectOptional = exports.useConnect = exports.ConnectProvider = void 0;
+exports.ConnectPlansPage = exports.ConnectUsageMeter = exports.ConnectPlatformGate = exports.ConnectWorkspaceTypeGate = exports.useConnectFeature = exports.ConnectFeatureGate = exports.useConnectAccessGate = exports.ConnectAccessGate = exports.ConnectReadinessGate = exports.ConnectReadinessBanner = exports.resolveSubscriptionState = exports.ConnectSeatUsage = exports.ConnectTrialBanner = exports.ConnectSubscriptionCard = exports.ConnectNoSubscriptionCard = exports.ConnectSubscriptionGate = exports.ConnectSubscribeDialog = exports.ConnectPlans = exports.ConnectIntegrationsModal = exports.AI_TONE_DOT = exports.AI_TONE_CHIP = exports.AI_EMPTY_VALUE = exports.aiStatusTone = exports.isNumericAiFormat = exports.formatAiValue = exports.AiSources = exports.AiSteps = exports.AiDetails = exports.AiTimeline = exports.AiMetrics = exports.AiChart = exports.AiTable = exports.ConnectAskAi = exports.ConnectAppsGrid = exports.visitorSlotOfferFrom = exports.readVisitorStream = exports.ConnectVisitorChat = exports.isLinkableConnectScreen = exports.matchConnectScreen = exports.filterNavForAudience = exports.gateExemptPaths = exports.isNavItemActive = exports.resolveActivePath = exports.normalizePath = exports.flattenNav = exports.normalizeNav = exports.useConnectPush = exports.useActivePath = exports.ConnectSideNav = exports.ConnectSidebarNav = void 0;
+exports.zonedInstant = exports.dayColumns = exports.layoutBookings = exports.useBookingActions = exports.useBookings = exports.useAvailableSlots = exports.useUpdateEventType = exports.useCreateEventType = exports.useManageableEventTypes = exports.useUpdateAvailabilitySchedule = exports.useCreateAvailabilitySchedule = exports.useAvailabilitySchedules = exports.useBookableEventTypes = exports.ConnectEventTypeFormModal = exports.ConnectAvailabilityFormModal = exports.ConnectBookingDetail = exports.ConnectBookingDialog = exports.ConnectBookingCalendar = exports.useConnectCall = exports.ConnectCallingStatus = exports.ConnectCallButton = exports.ConnectCallProvider = exports.useCreateWorkspace = exports.ConnectCreateWorkspaceModal = exports.useConnectWorkspaceMembers = exports.useConnectWorkspaces = exports.ConnectWorkspaceSwitcher = exports.resolvePlanGroup = exports.groupPlansByTier = exports.isFreePlan = exports.ACTION_LABEL = exports.discountLabel = exports.annualSaving = exports.checkoutSubscriptionId = exports.resolveAction = exports.monthlyOf = exports.formatPrice = exports.buildCheckoutUrl = exports.useConnectCheckout = exports.ConnectFilterTabs = exports.ConnectCursorPagination = exports.ConnectConfirmDialog = exports.ConnectLinkButton = void 0;
 /**
  * Browser half of `@cosmoops/connect-sdk` - React components and hooks.
  *
@@ -35,6 +35,9 @@ Object.defineProperty(exports, "useConnectSessions", { enumerable: true, get: fu
 Object.defineProperty(exports, "useConnectIntegrations", { enumerable: true, get: function () { return provider_js_1.useConnectIntegrations; } });
 Object.defineProperty(exports, "useConnectResource", { enumerable: true, get: function () { return provider_js_1.useConnectResource; } });
 Object.defineProperty(exports, "CONNECT_APP_URL", { enumerable: true, get: function () { return provider_js_1.CONNECT_APP_URL; } });
+var handoff_js_1 = require("./handoff.js");
+Object.defineProperty(exports, "CONNECT_HANDOFF_MESSAGE_TYPE", { enumerable: true, get: function () { return handoff_js_1.CONNECT_HANDOFF_MESSAGE_TYPE; } });
+Object.defineProperty(exports, "CONNECT_HANDOFF_RESULT_PARAM", { enumerable: true, get: function () { return handoff_js_1.CONNECT_HANDOFF_RESULT_PARAM; } });
 // 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.
@@ -70,9 +73,9 @@ Object.defineProperty(exports, "ConnectSignOutButton", { enumerable: true, get:
 var account_sessions_js_1 = require("./components/account-sessions.js");
 Object.defineProperty(exports, "ConnectAccountSessions", { enumerable: true, get: function () { return account_sessions_js_1.ConnectAccountSessions; } });
 // 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.
 var portal_links_js_1 = require("./portal-links.js");
 Object.defineProperty(exports, "connectPortalUrl", { enumerable: true, get: function () { return portal_links_js_1.connectPortalUrl; } });
 Object.defineProperty(exports, "useConnectPortalUrl", { enumerable: true, get: function () { return portal_links_js_1.useConnectPortalUrl; } });

package/dist/cjs/client/provider.js

@@ -22,6 +22,8 @@ exports.useConnectResource = useConnectResource;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 const one_tap_state_js_1 = require("./components/one-tap-state.js");
+const errors_js_1 = require("../errors.js");
+const handoff_js_1 = require("./handoff.js");
 exports.CONNECT_APP_URL = "https://connect.cosmoops.com";
 const ConnectContext = (0, react_1.createContext)(null);
 /** Marks that this tab has already spent its one silent attempt - see `ConnectProviderProps.silentSignIn`. */
@@ -40,7 +42,7 @@ const SILENT_ATTEMPT_KEY = "connect_silent_attempted";
  * </ConnectProvider>
  * ```
  */
-function ConnectProvider({ clientId = "", basePath = "/api/connect", redirectUri, appUrl = exports.CONNECT_APP_URL, fetch: fetchImpl, silentSignIn = false, children, }) {
+function ConnectProvider({ clientId = "", basePath = "/api/connect", redirectUri, appUrl = exports.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
@@ -142,7 +144,17 @@ function ConnectProvider({ clientId = "", basePath = "/api/connect", redirectUri
         });
         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 errors_js_1.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]);
@@ -192,6 +204,61 @@ function ConnectProvider({ clientId = "", basePath = "/api/connect", redirectUri
         // 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 = (0, react_1.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((0, handoff_js_1.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((0, handoff_js_1.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 = (0, react_1.useRef)(onHandoffResult);
+    (0, react_1.useEffect)(() => {
+        onHandoffResultRef.current = onHandoffResult;
+    });
+    (0, react_1.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 = (0, handoff_js_1.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 = (0, handoff_js_1.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]);
     (0, react_1.useEffect)(() => {
         // `silentPending` already encodes settled-and-signed-out, no prior
         // attempt, and no bridge error - a failed bridge read says nothing about
@@ -313,8 +380,10 @@ function ConnectProvider({ clientId = "", basePath = "/api/connect", redirectUri
         }
     }, [fetchImpl, mutateResource, oneTapEndpoints, refresh]);
     const value = (0, react_1.useMemo)(() => ({
-        clientId,
+        clientId: handoffClientId,
         appUrl,
+        handoffMode: handoff,
+        openConnect,
         session,
         isLoading,
         error,
@@ -328,8 +397,10 @@ function ConnectProvider({ clientId = "", basePath = "/api/connect", redirectUri
         readOneTapHint,
         oneTapSignIn,
     }), [
-        clientId,
+        handoffClientId,
         appUrl,
+        handoff,
+        openConnect,
         session,
         isLoading,
         error,

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

@@ -5,6 +5,7 @@ exports.useConnectCheckout = useConnectCheckout;
 exports.buildCancelUrl = buildCancelUrl;
 exports.buildCheckoutUrl = buildCheckoutUrl;
 const react_1 = require("react");
+const handoff_js_1 = require("./handoff.js");
 const provider_js_1 = require("./provider.js");
 /** How often `/entitlements` is re-read while a checkout is open. */
 const POLL_INTERVAL_MS = 3_000;
@@ -35,7 +36,7 @@ const CLOSE_GRACE_MS = 12_000;
  * period rather than ending the run.
  */
 function useConnectCheckout() {
-    const { fetchResource, invalidateResource, refresh } = (0, provider_js_1.useConnect)();
+    const { appUrl, fetchResource, invalidateResource, refresh, openConnect } = (0, provider_js_1.useConnect)();
     const [state, setState] = (0, react_1.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
@@ -56,20 +57,18 @@ 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,
@@ -79,7 +78,7 @@ function useConnectCheckout() {
             generation: generation.current,
         };
         setState({ status: "waiting", url });
-    }, [stop]);
+    }, [openConnect, stop]);
     (0, react_1.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
@@ -135,11 +134,19 @@ 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 ((0, handoff_js_1.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/cjs/server/client.js

@@ -25,6 +25,7 @@ const sessions_js_1 = require("./resources/sessions.js");
 const platform_js_1 = require("./resources/platform.js");
 const visitor_js_1 = require("./resources/visitor.js");
 const push_js_1 = require("./resources/push.js");
+const whatsapp_js_1 = require("./resources/whatsapp.js");
 exports.DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 const APPLICATION_API_PREFIX = "/api/v1/application";
 /**
@@ -128,6 +129,8 @@ 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`.
@@ -174,9 +177,10 @@ class ConnectClient {
         this.visitor = new visitor_js_1.VisitorResource(transport);
         this.platform = new platform_js_1.PlatformResource(transport);
         this.push = new push_js_1.PushResource(transport);
+        this.whatsapp = new whatsapp_js_1.WhatsAppResource(transport);
         this.storeRelay = (spec) => (0, data_js_1.storePassthrough)(transport, spec);
     }
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.41.0";
+exports.SDK_VERSION = "0.43.0";

package/dist/cjs/server/handler.js

@@ -411,6 +411,8 @@ 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);
@@ -432,9 +434,10 @@ 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/cjs/server/resources/calls.js

@@ -60,8 +60,11 @@ class CallsResource {
      * All three need the `calls:place` scope **and** a signed-in member
      * (`asUser`), whose own "Make calls" permission Connect checks. None works
      * server-to-server: a call is placed by a person, from the workspace's own
-     * number, and is not recorded. Read how one went with `get(callId)`, which
-     * needs `calls:read` - a call your application placed is readable by it.
+     * number. It is recorded only when the workspace has switched recording on
+     * (the person called hears a notice); `call.analyzed` then follows with the
+     * summary, intent and action items. Read how one went with `get(callId)`,
+     * which needs `calls:read` - a call your application placed is readable by
+     * it, transcript included.
      */
     /**
      * Whether the member can call, and if not why - what `<ConnectCallButton>`

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

@@ -94,6 +94,18 @@ 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/cjs/server/resources/whatsapp.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WhatsAppResource = void 0;
+const http_js_1 = require("../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.
+ */
+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 (0, http_js_1.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 (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: `/whatsapp/templates/${encodeURIComponent(slug)}${language}`,
+        });
+    }
+}
+exports.WhatsAppResource = WhatsAppResource;