@cosmoops/connect-sdk 0.40.0 → 0.41.0

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/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/index.js

@@ -31,7 +31,7 @@ ConnectUserMenu, ConnectManageSubscriptionButton, ConnectInvoicesButton, Connect
 // Built, compiled into `dist/`, and reachable from no entry point until now -
 // `ConnectUserMenu` was the only thing that could render it.
 export { ConnectAccountSessions } from "./components/account-sessions.js";
-// A link to *any* Connect portal page that offers a "Back to <your app>" way
+// 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.
@@ -152,6 +152,7 @@ export { useConnectWorkspaces, useConnectWorkspaceMembers } from "./provider.js"
 // than a link-out to Connect's own "Create workspace" button.
 export { ConnectCreateWorkspaceModal } from "./components/create-workspace-form.js";
 export { useCreateWorkspace } from "./use-workspaces.js";
+export { ConnectCallProvider, ConnectCallButton, ConnectCallingStatus, useConnectCall, } from "./components/call-button.js";
 export { ConnectBookingCalendar } from "./components/booking-calendar.js";
 export { ConnectBookingDialog, ConnectBookingDetail } from "./components/booking-dialogs.js";
 // The write half of scheduling - a workspace's own first-time setup, not a

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

@@ -6,7 +6,7 @@ import { useConnect } from "./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/esm/server/client.js

@@ -175,4 +175,4 @@ export class ConnectClient {
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.40.0";
+export const SDK_VERSION = "0.41.0";

package/dist/esm/server/handler.js

@@ -1210,6 +1210,67 @@ export 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 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 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 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) {
@@ -1495,6 +1556,18 @@ export 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/esm/server/resources/calls.js

@@ -1,4 +1,5 @@
 import { request } from "../http.js";
+import { actingAs } from "./acting-as.js";
 /**
  * Every call that arrived on a channel assigned to your application.
  *
@@ -50,4 +51,61 @@ export 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 request(this.transport, {
+            method: "GET",
+            path: "/calls/availability",
+            headers: actingAs(input.asUser),
+        });
+    }
+    /** A carrier token the member's browser signs in to the phone network with. */
+    getBrowserCallingToken(input) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/calls/browser-token",
+            json: {},
+            headers: 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 request(this.transport, {
+            method: "POST",
+            path: "/calls/start",
+            json: { phone: input.phone },
+            headers: 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 request(this.transport, {
+            method: "POST",
+            path: "/calls/cancel",
+            json: { callId: input.callId },
+            headers: actingAs(input.asUser),
+        });
+    }
 }