@cosmoops/connect-sdk 0.40.0 → 0.42.0

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.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.
@@ -69,10 +72,10 @@ Object.defineProperty(exports, "ConnectSignOutButton", { enumerable: true, get:
 // `ConnectUserMenu` was the only thing that could render it.
 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.
+// A link to *any* Connect portal page that offers a `"Back to <your app>"` way
+// 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; } });
@@ -271,6 +274,11 @@ var create_workspace_form_js_1 = require("./components/create-workspace-form.js"
 Object.defineProperty(exports, "ConnectCreateWorkspaceModal", { enumerable: true, get: function () { return create_workspace_form_js_1.ConnectCreateWorkspaceModal; } });
 var use_workspaces_js_1 = require("./use-workspaces.js");
 Object.defineProperty(exports, "useCreateWorkspace", { enumerable: true, get: function () { return use_workspaces_js_1.useCreateWorkspace; } });
+var call_button_js_1 = require("./components/call-button.js");
+Object.defineProperty(exports, "ConnectCallProvider", { enumerable: true, get: function () { return call_button_js_1.ConnectCallProvider; } });
+Object.defineProperty(exports, "ConnectCallButton", { enumerable: true, get: function () { return call_button_js_1.ConnectCallButton; } });
+Object.defineProperty(exports, "ConnectCallingStatus", { enumerable: true, get: function () { return call_button_js_1.ConnectCallingStatus; } });
+Object.defineProperty(exports, "useConnectCall", { enumerable: true, get: function () { return call_button_js_1.useConnectCall; } });
 var booking_calendar_js_1 = require("./components/booking-calendar.js");
 Object.defineProperty(exports, "ConnectBookingCalendar", { enumerable: true, get: function () { return booking_calendar_js_1.ConnectBookingCalendar; } });
 var booking_dialogs_js_1 = require("./components/booking-dialogs.js");

package/dist/cjs/client/portal-links.js

@@ -10,7 +10,7 @@ const provider_js_1 = require("./provider.js");
  * `connectPortalUrl(appUrl, clientId, "/calendar/settings")`, and so on.
  *
  * Connect answers any of these paths for a signed-in user on the bare URL -
- * these two params only add the "Back to <your app>" banner
+ * these two params only add the `"Back to <your app>"` banner
  * (`ApplicationReturnBar` on Connect's side). It validates `return_to`
  * against this `client_id`'s registered redirect origins and silently drops
  * the banner if they don't match, so a wrong or stale `appUrl`/`clientId`

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.40.0";
+exports.SDK_VERSION = "0.42.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);
@@ -1213,6 +1216,67 @@ function createConnectHandler(options) {
             const items = await client.sessions.list(await requireToken(request));
             return json({ items });
         },
+        /*
+         * Browser calling - `<ConnectCallButton>`. Three fixed writes and no read:
+         * how a call went is your *server's* question (`client.calls.get`), never
+         * the browser's, so a call log can't be written from what a page claims.
+         *
+         * The workspace and the member both come from the session, as everywhere
+         * here; the browser names only the number.
+         */
+        /*
+         * The one calling *read*, and it is about the member, not about a call:
+         * can they ring anybody from here. A refusal means they lack "Make calls"
+         * - which is an answer, not a failure, so it is returned as one and the
+         * button simply is not offered.
+         */
+        "GET /calls/availability": async (request) => {
+            await requireWorkspace(request);
+            const asUser = await requireToken(request);
+            try {
+                return json(await client.calls.getCallingAvailability({ asUser }));
+            }
+            catch (error) {
+                if (error instanceof errors_js_1.ConnectError && error.status === 403) {
+                    return json(NO_CALLING_PERMISSION);
+                }
+                throw error;
+            }
+        },
+        "POST /calls/browser-token": async (request) => {
+            await requireWorkspace(request);
+            const asUser = await requireToken(request);
+            return json(await client.calls.getBrowserCallingToken({ asUser }));
+        },
+        "POST /calls/start": async (request) => {
+            await requireWorkspace(request);
+            const asUser = await requireToken(request);
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.phone !== "string") {
+                throw new errors_js_1.ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "phone is required",
+                    endpoint: "/calls/start",
+                });
+            }
+            return json(await client.calls.startBrowserCall({ phone: body.phone, asUser }), 201);
+        },
+        "POST /calls/cancel": async (request) => {
+            await requireWorkspace(request);
+            const asUser = await requireToken(request);
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.callId !== "string") {
+                throw new errors_js_1.ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "callId is required",
+                    endpoint: "/calls/cancel",
+                });
+            }
+            await client.calls.cancelBrowserCall({ callId: body.callId, asUser });
+            return json({ cancelled: true });
+        },
         "POST /sessions/revoke": async (request) => {
             const body = (await request.json().catch(() => null));
             if (!body?.sessionId) {
@@ -1498,6 +1562,18 @@ function createConnectHandler(options) {
         }
     };
 }
+/** What a member without "Make calls" is told - see `GET /calls/availability`. */
+const NO_CALLING_PERMISSION = {
+    status: "no_permission",
+    number: null,
+    available: 0,
+    availableMinutes: 0,
+    ratePaisePerMinute: 0,
+    lowBalance: false,
+    canTopUp: false,
+    canManageNumber: false,
+    offer: null,
+};
 function json(body, status = 200) {
     return new Response(JSON.stringify(body), {
         status,

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CallsResource = void 0;
 const http_js_1 = require("../http.js");
+const acting_as_js_1 = require("./acting-as.js");
 /**
  * Every call that arrived on a channel assigned to your application.
  *
@@ -53,5 +54,62 @@ class CallsResource {
             path: `/calls/${encodeURIComponent(callId)}`,
         });
     }
+    /*
+     * Browser calling - what `<ConnectCallButton>` runs on, through your bridge.
+     *
+     * 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.
+     */
+    /**
+     * Whether the member can call, and if not why - what `<ConnectCallButton>`
+     * renders from. Throws `ConnectError` 403 for a member without "Make
+     * calls"; the bridge turns that into `status: "no_permission"`.
+     */
+    getCallingAvailability(input) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: "/calls/availability",
+            headers: (0, acting_as_js_1.actingAs)(input.asUser),
+        });
+    }
+    /** A carrier token the member's browser signs in to the phone network with. */
+    getBrowserCallingToken(input) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/calls/browser-token",
+            json: {},
+            headers: (0, acting_as_js_1.actingAs)(input.asUser),
+        });
+    }
+    /**
+     * Approves one call from the member to `phone` (E.164) and records it.
+     *
+     * Throws `ConnectError` with status `412` when the workspace has no active
+     * number, is not allowed to place calls, or the member is already on one -
+     * the message is written to be shown to them.
+     */
+    startBrowserCall(input) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/calls/start",
+            json: { phone: input.phone },
+            headers: (0, acting_as_js_1.actingAs)(input.asUser),
+        });
+    }
+    /**
+     * Closes a call the browser never managed to place - recorded as
+     * `unanswered`/`cancelled`. A no-op once the carrier has it.
+     */
+    async cancelBrowserCall(input) {
+        await (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/calls/cancel",
+            json: { callId: input.callId },
+            headers: (0, acting_as_js_1.actingAs)(input.asUser),
+        });
+    }
 }
 exports.CallsResource = CallsResource;

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;