@cosmoops/connect-sdk 0.40.0 → 0.42.0

package/dist/esm/client/components/call-button.js

@@ -0,0 +1,358 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { Button } from "@heroui/react";
+import { Mic, MicOff, Phone, PhoneOff, PhoneOutgoing } from "lucide-react";
+import { cn } from "../../cn.js";
+import { useConnect, useConnectResource } from "../provider.js";
+import { useConnectPortalUrl } from "../portal-links.js";
+const ConnectCallContext = createContext(null);
+/** Start a call yourself. Must be inside `<ConnectCallProvider>`. */
+export function useConnectCall() {
+    const value = useContext(ConnectCallContext);
+    if (!value) {
+        throw new Error("useConnectCall() needs a <ConnectCallProvider> above it.");
+    }
+    return value;
+}
+/** How long the SDK may take to sign in before the attempt is abandoned. */
+const LOGIN_TIMEOUT_MS = 15_000;
+/** How long the "Call ended" card stays before the bar goes away. */
+const ENDED_CARD_MS = 4_000;
+/** How long after a call to re-read the balance - the carrier's report settles it. */
+const AVAILABILITY_SETTLE_MS = 3_000;
+function messageFromCause(cause) {
+    if (typeof cause === "string" && cause.trim())
+        return cause.trim();
+    return "The call couldn't be connected.";
+}
+function errorMessage(cause) {
+    return cause instanceof Error && cause.message ? cause.message : "Something went wrong.";
+}
+/**
+ * Holds the call in progress and draws the in-call bar. See the module comment.
+ */
+export function ConnectCallProvider({ children, onCallEnded, onError, className, }) {
+    const { mutateResource } = useConnect();
+    const [call, setCall] = useState(null);
+    const { data: availability, refetch: refreshAvailability } = useConnectResource("/calls/availability");
+    // Read inside `finish`, which is wired to SDK events once.
+    const refreshRef = useRef(refreshAvailability);
+    useEffect(() => {
+        refreshRef.current = refreshAvailability;
+    }, [refreshAvailability]);
+    const clientRef = useRef(null);
+    const placedRef = useRef(false);
+    const targetRef = useRef(null);
+    const callIdRef = useRef(null);
+    const endedRef = useRef(false);
+    const dismissTimer = useRef(null);
+    // Read inside SDK event handlers wired once, so they always see the latest.
+    const onCallEndedRef = useRef(onCallEnded);
+    useEffect(() => {
+        onCallEndedRef.current = onCallEnded;
+    }, [onCallEnded]);
+    const cancelOnServer = useCallback(() => {
+        const callId = callIdRef.current;
+        if (!callId)
+            return;
+        // Best effort: Connect closes an unclaimed call on its own within minutes.
+        void mutateResource("/calls/cancel", { callId }).catch(() => undefined);
+    }, [mutateResource]);
+    const finish = useCallback((notice) => {
+        if (endedRef.current)
+            return;
+        endedRef.current = true;
+        const callId = callIdRef.current;
+        const target = targetRef.current;
+        placedRef.current = false;
+        setCall((current) => current
+            ? {
+                ...current,
+                phase: "ended",
+                notice,
+                endedAfterSeconds: current.connectedAt
+                    ? Math.round((Date.now() - current.connectedAt) / 1000)
+                    : null,
+            }
+            : current);
+        if (dismissTimer.current)
+            clearTimeout(dismissTimer.current);
+        dismissTimer.current = setTimeout(() => setCall(null), ENDED_CARD_MS);
+        // The charge lands a moment after the line drops, so the minutes shown
+        // are re-read once it has had time to.
+        setTimeout(() => refreshRef.current(), AVAILABILITY_SETTLE_MS);
+        if (target) {
+            target.onEnded?.({ callId });
+            onCallEndedRef.current?.({ callId, phone: target.phone });
+        }
+    }, []);
+    const wire = useCallback((client) => {
+        const ringing = () => setCall((current) => (current ? { ...current, phase: "ringing" } : current));
+        client.on("onCalling", ringing);
+        client.on("onCallRemoteRinging", ringing);
+        client.on("onCallAnswered", () => setCall((current) => current ? { ...current, phase: "in-call", connectedAt: Date.now() } : current));
+        client.on("onCallTerminated", () => finish(null));
+        client.on("onCallFailed", (cause) => {
+            if (!placedRef.current)
+                cancelOnServer();
+            finish(messageFromCause(cause));
+        });
+        client.on("onMediaPermission", (event) => {
+            if (event?.status === "failure") {
+                cancelOnServer();
+                finish("Allow microphone access in your browser to make calls.");
+            }
+        });
+    }, [cancelOnServer, finish]);
+    const signIn = useCallback(async () => {
+        let client = clientRef.current;
+        if (!client) {
+            const { default: Plivo } = await import("plivo-browser-sdk");
+            client = new Plivo({
+                debug: "ERROR",
+                // Ask for the microphone when a call starts, not on page load.
+                permOnClick: true,
+                // Warn before a tab mid-call is closed.
+                closeProtection: true,
+                enableTracking: false,
+            }).client;
+            clientRef.current = client;
+            wire(client);
+        }
+        if (client.isLoggedIn)
+            return client;
+        const { token } = await mutateResource("/calls/browser-token", {});
+        const signedIn = client;
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new Error("Signing in to the phone service timed out."));
+            }, LOGIN_TIMEOUT_MS);
+            const onLogin = () => {
+                cleanup();
+                resolve();
+            };
+            const onLoginFailed = (cause) => {
+                cleanup();
+                reject(new Error(`Couldn't sign in to the phone service: ${messageFromCause(cause)}`));
+            };
+            function cleanup() {
+                clearTimeout(timer);
+                signedIn.off("onLogin", onLogin);
+                signedIn.off("onLoginFailed", onLoginFailed);
+            }
+            signedIn.on("onLogin", onLogin);
+            signedIn.on("onLoginFailed", onLoginFailed);
+            if (!signedIn.loginWithAccessToken(token)) {
+                cleanup();
+                reject(new Error("Couldn't sign in to the phone service."));
+            }
+        });
+        return signedIn;
+    }, [mutateResource, wire]);
+    const isBusy = call !== null && call.phase !== "ended";
+    const startCall = useCallback(async (target) => {
+        if (isBusy) {
+            onError?.("You're already on a call.");
+            return;
+        }
+        if (dismissTimer.current)
+            clearTimeout(dismissTimer.current);
+        targetRef.current = target;
+        callIdRef.current = null;
+        placedRef.current = false;
+        endedRef.current = false;
+        setCall({
+            phase: "connecting",
+            label: target.name?.trim() || target.phone,
+            number: target.phone,
+            callId: null,
+            connectedAt: null,
+            endedAfterSeconds: null,
+            muted: false,
+            notice: null,
+        });
+        try {
+            const client = await signIn();
+            const started = await mutateResource("/calls/start", {
+                phone: target.phone,
+            });
+            callIdRef.current = started.callId;
+            setCall((current) => current ? { ...current, callId: started.callId, number: started.toNumber } : current);
+            // Connect dials the number on the record, not this one - it is passed
+            // because the SDK requires a destination.
+            if (!client.call(started.toNumber.replace(/^\+/, ""), started.headers)) {
+                throw new Error("The phone service didn't accept the call.");
+            }
+            placedRef.current = true;
+        }
+        catch (cause) {
+            cancelOnServer();
+            // A refusal is usually news about the workspace - an empty balance, a
+            // number that has gone - so the buttons should learn it too.
+            refreshRef.current();
+            const message = errorMessage(cause);
+            if (onError) {
+                onError(message);
+                endedRef.current = true;
+                setCall(null);
+                target.onEnded?.({ callId: callIdRef.current });
+                onCallEndedRef.current?.({ callId: callIdRef.current, phone: target.phone });
+            }
+            else {
+                finish(message);
+            }
+        }
+    }, [cancelOnServer, finish, isBusy, mutateResource, onError, signIn]);
+    const hangUp = useCallback(() => {
+        const client = clientRef.current;
+        if (placedRef.current && client) {
+            client.hangup();
+            return; // `onCallTerminated` takes it from here.
+        }
+        cancelOnServer();
+        finish(null);
+    }, [cancelOnServer, finish]);
+    const toggleMute = useCallback(() => {
+        const client = clientRef.current;
+        if (!client)
+            return;
+        setCall((current) => {
+            if (!current)
+                return current;
+            if (current.muted)
+                client.unmute();
+            else
+                client.mute();
+            return { ...current, muted: !current.muted };
+        });
+    }, []);
+    // Sign out of the carrier when the provider unmounts.
+    useEffect(() => () => {
+        clientRef.current?.logout();
+        if (dismissTimer.current)
+            clearTimeout(dismissTimer.current);
+    }, []);
+    const value = useMemo(() => ({ isBusy, startCall, availability, refreshAvailability }), [isBusy, startCall, availability, refreshAvailability]);
+    return (_jsxs(ConnectCallContext.Provider, { value: value, children: [children, call && (_jsx(ConnectActiveCallBar, { call: call, onHangUp: hangUp, onToggleMute: toggleMute, className: className }))] }));
+}
+/**
+ * Rings `phone` from the workspace's number. Needs `<ConnectCallProvider>`
+ * above it, and a member with "Make calls" - render it only for them, since a
+ * button the server refuses for everyone else helps nobody.
+ */
+export function ConnectCallButton({ phone, name, onEnded, variant = "default", children, isDisabled, className, }) {
+    const { isBusy, startCall, availability } = useConnectCall();
+    const press = () => void startCall({ phone, name, onEnded });
+    // Not offered at all to someone who may not call - a button that always
+    // refuses helps nobody.
+    if (availability?.status === "no_permission")
+        return null;
+    // Anything else short of `available` says why, where the button would be,
+    // with the next step for whoever can take it.
+    if (availability && availability.status !== "available") {
+        return variant === "compact" ? (_jsx(Button, { isIconOnly: true, size: "sm", variant: "ghost", "aria-label": unavailableReason(availability).text, isDisabled: true, className: className, children: _jsx(Phone, { className: "size-3.5" }) })) : (_jsx(ConnectCallUnavailable, { availability: availability, className: className }));
+    }
+    if (variant === "compact") {
+        return (_jsx(Button, { isIconOnly: true, size: "sm", variant: "ghost", "aria-label": `Call ${name?.trim() || phone}`, isDisabled: isBusy || isDisabled, onPress: press, className: className, children: _jsx(Phone, { className: "size-3.5" }) }));
+    }
+    return (_jsxs(Button, { size: "sm", variant: "primary", isDisabled: isBusy || isDisabled || availability === null, onPress: press, className: cn("shrink-0", className), children: [_jsx(Phone, { className: "size-4" }), children ?? "Call"] }));
+}
+/**
+ * What to say when a member cannot call, and the one link that fixes it -
+ * offered only to someone with the permission to follow it.
+ */
+function unavailableReason(availability) {
+    switch (availability.status) {
+        case "no_number":
+            return availability.canManageNumber && availability.offer
+                ? {
+                    text: "Calling needs a business number.",
+                    action: {
+                        label: `Add ${availability.offer.addonName}`,
+                        path: `/billing/subscriptions/${availability.offer.subscriptionId}`,
+                    },
+                }
+                : { text: "Calling needs a business number - ask a workspace admin.", action: null };
+        case "number_pending":
+            return availability.canManageNumber
+                ? {
+                    text: "Your business number is still being set up.",
+                    action: { label: "Check calling", path: "/calling" },
+                }
+                : { text: "Your business number is still being set up.", action: null };
+        case "no_balance":
+            return availability.canTopUp
+                ? { text: "Out of calling minutes.", action: { label: "Top up", path: "/calling" } }
+                : { text: "Out of calling minutes - ask a workspace admin to top up.", action: null };
+        default:
+            return { text: "Calling isn't available.", action: null };
+    }
+}
+/** The inline "why not" a Call button becomes when the member cannot call. */
+function ConnectCallUnavailable({ availability, className, }) {
+    const { text, action } = unavailableReason(availability);
+    const href = useConnectPortalUrl(action?.path ?? "/calling");
+    return (_jsxs("p", { className: cn("text-xs text-muted", className), children: [text, " ", action && (_jsx("a", { href: href, className: "font-medium text-accent hover:underline", children: action.label }))] }));
+}
+function formatRupees(paise) {
+    return `₹${(paise / 100).toLocaleString("en-IN", {
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+    })}`;
+}
+/**
+ * The workspace's calling at a glance - its business number, the minutes
+ * left, and the next step - for a settings page. Reads the same availability
+ * the Call buttons do, so the two never disagree. Buying minutes and adding a
+ * number happen in Connect, and come back here when done.
+ */
+export function ConnectCallingStatus({ className }) {
+    const { availability } = useConnectCall();
+    const callingHref = useConnectPortalUrl("/calling");
+    const offerHref = useConnectPortalUrl(availability?.offer ? `/billing/subscriptions/${availability.offer.subscriptionId}` : "/calling");
+    if (!availability) {
+        return _jsx("div", { className: cn("h-24 animate-pulse rounded-lg bg-surface-secondary", className) });
+    }
+    const rate = formatRupees(availability.ratePaisePerMinute);
+    return (_jsxs("div", { className: cn("space-y-3 rounded-lg border border-separator bg-surface p-4", className), children: [_jsxs("div", { className: "flex flex-wrap items-start justify-between gap-3", children: [_jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "text-xs text-muted", children: "Business number" }), _jsx("p", { className: "text-sm font-medium tabular-nums", children: availability.number ?? (availability.status === "number_pending" ? "Being set up…" : "None") })] }), availability.number && (_jsxs("div", { className: "text-right", children: [_jsx("p", { className: "text-xs text-muted", children: "Calling minutes" }), _jsxs("p", { className: cn("text-sm font-medium tabular-nums", availability.lowBalance && "text-danger"), children: [formatRupees(availability.available), " \u00B7 about ", availability.availableMinutes, " min"] })] }))] }), availability.status === "no_permission" ? (_jsx("p", { className: "text-xs text-muted", children: "You don't have permission to make calls here." })) : !availability.number ? (_jsxs("p", { className: "text-xs text-muted", children: ["Call customers from their record, from your own business number. Calls are not recorded, and minutes are prepaid at ", rate, " + GST a minute.", " ", availability.status === "number_pending"
+                        ? availability.canManageNumber && (_jsx("a", { href: callingHref, className: "font-medium text-accent hover:underline", children: "Check on your number" }))
+                        : availability.canManageNumber && availability.offer
+                            ? (_jsxs("a", { href: offerHref, className: "font-medium text-accent hover:underline", children: ["Add ", availability.offer.addonName, " (", formatRupees(availability.offer.price), " + GST)"] }))
+                            : "Ask a workspace admin to add a business number."] })) : (_jsxs("p", { className: "text-xs text-muted", children: [availability.lowBalance
+                        ? "Calling minutes are running low. "
+                        : `Calls cost ${rate} + GST a minute, from prepaid minutes. `, availability.canTopUp ? (_jsx("a", { href: callingHref, className: "font-medium text-accent hover:underline", children: "Top up minutes" })) : ("A workspace admin can top up.")] }))] }));
+}
+const PHASE_LABEL = {
+    connecting: "Connecting…",
+    ringing: "Calling…",
+    ended: "Call ended",
+};
+function formatSeconds(seconds) {
+    const whole = Math.max(0, Math.round(seconds));
+    const minutes = Math.floor(whole / 60);
+    return `${minutes}:${String(whole % 60).padStart(2, "0")}`;
+}
+/** The floating in-call card. Exported for Storybook only - the provider draws it. */
+export function ConnectActiveCallBar({ call, onHangUp, onToggleMute, className, }) {
+    const elapsed = useElapsedSeconds(call.phase === "in-call" ? call.connectedAt : null);
+    const live = call.phase !== "ended";
+    const status = call.phase === "in-call"
+        ? formatSeconds(elapsed)
+        : call.phase === "ended" && call.endedAfterSeconds !== null
+            ? `Call ended · ${formatSeconds(call.endedAfterSeconds)}`
+            : PHASE_LABEL[call.phase];
+    return (_jsx("div", { role: "status", "aria-live": "polite", className: cn("fixed inset-x-0 bottom-4 z-50 flex justify-center px-4", className), children: _jsxs("div", { className: "flex w-full max-w-sm items-center gap-3 rounded-2xl border border-separator bg-surface p-3 shadow-lg", children: [_jsx("span", { className: "flex size-9 shrink-0 items-center justify-center rounded-full bg-accent-soft text-accent", children: _jsx(PhoneOutgoing, { "aria-hidden": true, className: "size-4" }) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("p", { className: "truncate text-sm font-medium", children: call.label }), _jsxs("p", { className: "truncate text-xs text-muted tabular-nums", children: [status, call.notice ? ` · ${call.notice}` : call.label === call.number ? "" : ` · ${call.number}`] })] }), live && (_jsxs(_Fragment, { children: [_jsx(Button, { isIconOnly: true, size: "sm", variant: "secondary", "aria-label": call.muted ? "Unmute" : "Mute", isDisabled: call.phase !== "in-call", onPress: onToggleMute, children: call.muted ? _jsx(MicOff, { className: "size-4" }) : _jsx(Mic, { className: "size-4" }) }), _jsx(Button, { isIconOnly: true, size: "sm", variant: "danger", "aria-label": "Hang up", onPress: onHangUp, children: _jsx(PhoneOff, { className: "size-4" }) })] }))] }) }));
+}
+/** Seconds since `since`, ticking once a second. `0` while there is nothing to time. */
+function useElapsedSeconds(since) {
+    const [now, setNow] = useState(() => Date.now());
+    useEffect(() => {
+        if (since === null)
+            return;
+        const timer = setInterval(() => setNow(Date.now()), 1_000);
+        return () => clearInterval(timer);
+    }, [since]);
+    return since === null ? 0 : Math.max(0, Math.round((now - since) / 1000));
+}

package/dist/esm/client/components/plans.js

@@ -162,6 +162,7 @@ function ConnectCheckoutStatusRow({ checkout, }) {
     return (_jsx(AnimatePresence, { mode: "wait", initial: false, children: checkout.status !== "idle" && (_jsx(m.div, { initial: { opacity: 0, y: 4 }, animate: { opacity: 1, y: 0 }, exit: { opacity: 0, y: -4 }, transition: { duration: 0.18 }, children: _jsx(CheckoutStatusRowContent, { checkout: checkout }) }, checkout.status)) }));
 }
 function CheckoutStatusRowContent({ checkout, }) {
+    const { openConnect } = useConnect();
     if (checkout.status === "waiting") {
         return (_jsxs("div", { className: "flex items-center gap-2 rounded-lg border border-separator px-3 py-2 text-sm text-muted", children: [_jsx(Loader2, { className: "size-4 shrink-0 animate-spin", "aria-hidden": "true" }), _jsx("span", { children: "Finish up in the Connect window. This page updates on its own." })] }));
     }
@@ -172,7 +173,11 @@ function CheckoutStatusRowContent({ checkout, }) {
     // are fixed by going to the same URL - so offer it rather than explaining.
     return (_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3 rounded-lg border border-separator px-3 py-2 text-sm text-muted", children: [_jsx("span", { children: checkout.status === "blocked"
                     ? "Your browser blocked the Connect window."
-                    : "Nothing changed - the Connect window closed before it was finished." }), _jsxs("div", { className: "flex items-center gap-2", children: [checkout.url && (_jsxs(Button, { variant: "secondary", onPress: () => window.open(checkout.url, "_blank", "noopener,noreferrer"), children: ["Open Connect", _jsx(ExternalLink, { className: "size-3.5" })] })), _jsx(Button, { variant: "tertiary", onPress: checkout.reset, children: "Dismiss" })] })] }));
+                    : "Nothing changed - the Connect window closed before it was finished." }), _jsxs("div", { className: "flex items-center gap-2", children: [checkout.url && (_jsxs(Button, { variant: "secondary", 
+                        // Not watched by the checkout poll - that run has ended - but a
+                        // hand-off all the same: Connect reports back when it is done, and
+                        // the provider re-reads every resource on this page.
+                        onPress: () => openConnect(checkout.url), children: ["Open Connect", _jsx(ExternalLink, { className: "size-3.5" })] })), _jsx(Button, { variant: "tertiary", onPress: checkout.reset, children: "Dismiss" })] })] }));
 }
 /**
  * Cancellation, kept out of the plan grid and stated plainly.
@@ -192,9 +197,10 @@ function CheckoutStatusRowContent({ checkout, }) {
  * version.
  */
 function ConnectUnsubscribeRow({ subscription, appUrl, checkout, }) {
+    const { openConnect } = useConnect();
     const endsOn = subscription.currentBillingCycle?.endDate;
     if (subscription.cancelAtPeriodEnd) {
-        return (_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3 border-t border-separator pt-4", children: [_jsxs("p", { className: "text-sm text-muted", children: ["Cancels", endsOn ? ` on ${new Date(endsOn).toLocaleDateString()}` : " at the end of this cycle", ". You keep access until then."] }), _jsxs(Button, { variant: "tertiary", onPress: () => window.open(`${appUrl}/billing/subscriptions/${subscription.id}`, "_blank", "noopener,noreferrer"), children: ["View on Connect", _jsx(ExternalLink, { className: "size-3.5" })] })] }));
+        return (_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3 border-t border-separator pt-4", children: [_jsxs("p", { className: "text-sm text-muted", children: ["Cancels", endsOn ? ` on ${new Date(endsOn).toLocaleDateString()}` : " at the end of this cycle", ". You keep access until then."] }), _jsxs(Button, { variant: "tertiary", onPress: () => openConnect(`/billing/subscriptions/${encodeURIComponent(subscription.id)}`), children: ["View on Connect", _jsx(ExternalLink, { className: "size-3.5" })] })] }));
     }
     return (_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-3 border-t border-separator pt-4", children: [_jsx("p", { className: "text-sm text-muted", children: "Cancel any time. Access continues to the end of the paid cycle." }), _jsxs(Button, { variant: "tertiary", className: "text-danger", isDisabled: checkout.status === "waiting", onPress: () => checkout.start({
                     url: buildCancelUrl({ appUrl, subscriptionId: subscription.id }),

package/dist/esm/client/components/readiness.js

@@ -68,9 +68,10 @@ export function ConnectReadinessBanner({ includeAdvisory = false, hideWhenReady
     return (_jsx(MotionProvider, { children: _jsx(m.div, { className: cn("flex flex-col gap-2", className), role: "status", initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, transition: ENTER, children: blockers.map((blocker) => (_jsx(BlockerRow, { blocker: blocker }, `${blocker.code}-${blocker.message}`))) }) }));
 }
 function BlockerRow({ blocker }) {
+    const { openConnect } = useConnect();
     const inProgress = IN_PROGRESS_CODES.has(blocker.code);
     const isBlocking = blocker.severity === "blocking";
-    return (_jsxs("div", { className: `flex flex-wrap items-center justify-between gap-3 rounded-lg px-3 py-2 text-sm ${inProgress || !isBlocking ? "bg-surface text-muted" : "bg-danger-soft text-danger"}`, children: [_jsxs("span", { className: "flex items-center gap-2", children: [inProgress || !isBlocking ? (_jsx(Info, { className: "size-4 shrink-0", "aria-hidden": "true" })) : (_jsx(AlertTriangle, { className: "size-4 shrink-0", "aria-hidden": "true" })), blocker.message] }), blocker.resolveUrl && !inProgress && (_jsxs(Button, { variant: "secondary", onPress: () => window.open(blocker.resolveUrl, "_blank", "noopener,noreferrer"), children: [actionLabel(blocker), _jsx(ExternalLink, { className: "size-3.5" })] }))] }));
+    return (_jsxs("div", { className: `flex flex-wrap items-center justify-between gap-3 rounded-lg px-3 py-2 text-sm ${inProgress || !isBlocking ? "bg-surface text-muted" : "bg-danger-soft text-danger"}`, children: [_jsxs("span", { className: "flex items-center gap-2", children: [inProgress || !isBlocking ? (_jsx(Info, { className: "size-4 shrink-0", "aria-hidden": "true" })) : (_jsx(AlertTriangle, { className: "size-4 shrink-0", "aria-hidden": "true" })), blocker.message] }), blocker.resolveUrl && !inProgress && (_jsxs(Button, { variant: "secondary", onPress: () => openConnect(blocker.resolveUrl), children: [actionLabel(blocker), _jsx(ExternalLink, { className: "size-3.5" })] }))] }));
 }
 function ReadyRow({ className }) {
     return (_jsx("p", { className: cn("text-sm text-muted", className), children: "This workspace is cleared to use every part of the application." }));

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

@@ -72,13 +72,13 @@ export function ConnectNoSubscriptionCard({ plansHref = DEFAULT_PLANS_HREF, titl
  * impure and re-renders wrong.
  */
 export function ConnectSubscriptionCard({ plansHref, className }) {
-    const { appUrl } = useConnect();
+    const { openConnect } = useConnect();
     const { isLoading, detail, plan, state } = useSubscriptionState();
     if (isLoading)
         return _jsx(Skeleton, { className: cn("h-48 rounded-xl", className) });
     if (!detail || !plan)
         return _jsx(ConnectNoSubscriptionCard, { plansHref: plansHref, className: className });
-    return (_jsx(MotionProvider, { children: _jsx(m.div, { initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { duration: 0.2 }, children: _jsxs(Card, { className: className, children: [_jsxs(Card.Header, { children: [_jsxs("div", { className: "flex items-start justify-between gap-2", children: [_jsx(Card.Title, { children: plan.name }), _jsx(SubscriptionChip, { state: state })] }), _jsxs(Card.Description, { children: [formatPrice(plan.price), " + ", plan.gstRate, "% GST per", " ", intervalLabel(plan.billingInterval).per] })] }), _jsxs(Card.Content, { className: "flex flex-col gap-2 text-sm", children: [_jsx(NextEvent, { detail: detail, state: state }), _jsx(ConnectSeatUsage, { plan: plan, detail: detail })] }), _jsxs(Card.Footer, { className: "flex flex-wrap gap-2", children: [_jsxs(Button, { variant: "secondary", onPress: () => window.open(`${appUrl}/billing/subscriptions/${detail.id}`, "_blank", "noopener,noreferrer"), children: ["Manage on Connect", _jsx(ExternalLink, { className: "size-3.5" })] }), _jsx(ConnectLinkButton, { href: plansHref ?? DEFAULT_PLANS_HREF, variant: "tertiary", children: "Change plan" })] })] }) }) }));
+    return (_jsx(MotionProvider, { children: _jsx(m.div, { initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { duration: 0.2 }, children: _jsxs(Card, { className: className, children: [_jsxs(Card.Header, { children: [_jsxs("div", { className: "flex items-start justify-between gap-2", children: [_jsx(Card.Title, { children: plan.name }), _jsx(SubscriptionChip, { state: state })] }), _jsxs(Card.Description, { children: [formatPrice(plan.price), " + ", plan.gstRate, "% GST per", " ", intervalLabel(plan.billingInterval).per] })] }), _jsxs(Card.Content, { className: "flex flex-col gap-2 text-sm", children: [_jsx(NextEvent, { detail: detail, state: state }), _jsx(ConnectSeatUsage, { plan: plan, detail: detail })] }), _jsxs(Card.Footer, { className: "flex flex-wrap gap-2", children: [_jsxs(Button, { variant: "secondary", onPress: () => openConnect(`/billing/subscriptions/${encodeURIComponent(detail.id)}`), children: ["Manage on Connect", _jsx(ExternalLink, { className: "size-3.5" })] }), _jsx(ConnectLinkButton, { href: plansHref ?? DEFAULT_PLANS_HREF, variant: "tertiary", children: "Change plan" })] })] }) }) }));
 }
 function SubscriptionChip({ state }) {
     switch (state) {
@@ -149,11 +149,11 @@ export function ConnectSeatUsage({ plan, detail, className, }) {
  * actually cares about anyway.
  */
 export function ConnectTrialBanner({ plansHref, className }) {
-    const { appUrl } = useConnect();
+    const { openConnect } = useConnect();
     const { detail, state } = useSubscriptionState();
     if (state !== "trialing" || !detail)
         return null;
-    return (_jsxs("div", { className: 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: [_jsxs("span", { className: "flex items-center gap-2", children: [_jsx(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)}.` : "."] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(ConnectLinkButton, { href: plansHref ?? DEFAULT_PLANS_HREF, variant: "tertiary", children: "Compare plans" }), _jsxs(Button, { variant: "secondary", onPress: () => window.open(`${appUrl}/billing/subscriptions/${detail.id}`, "_blank", "noopener,noreferrer"), children: ["Manage", _jsx(ExternalLink, { className: "size-3.5" })] })] })] }));
+    return (_jsxs("div", { className: 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: [_jsxs("span", { className: "flex items-center gap-2", children: [_jsx(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)}.` : "."] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(ConnectLinkButton, { href: plansHref ?? DEFAULT_PLANS_HREF, variant: "tertiary", children: "Compare plans" }), _jsxs(Button, { variant: "secondary", onPress: () => openConnect(`/billing/subscriptions/${encodeURIComponent(detail.id)}`), children: ["Manage", _jsx(ExternalLink, { className: "size-3.5" })] })] })] }));
 }
 /**
  * Renders `children` for a subscribed workspace, and the "pick a plan" card for

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() };
+}