@cosmoops/connect-sdk 0.40.0 → 0.41.0

package/dist/types/client/components/call-button.d.ts

@@ -0,0 +1,132 @@
+import { type ReactNode } from "react";
+import type { CallingAvailability } from "../../types.js";
+/**
+ * Calling from the browser, through the workspace's own number.
+ *
+ * Three pieces: `<ConnectCallProvider>` once, high in your tree;
+ * `<ConnectCallButton phone="+91...">` wherever a person can be rung; and
+ * `useConnectCall()` if you want your own button.
+ *
+ * ## Why a provider, and why high up
+ *
+ * A call has to outlive the page it was started from - someone who rings a
+ * customer and then opens their invoices must not hang up on them by doing so.
+ * So the call lives in the provider, which also draws the in-call bar, and a
+ * button only asks it to start one. Mount it inside `<ConnectProvider>`,
+ * beside your app shell rather than inside a page.
+ *
+ * ## What happens when someone presses Call
+ *
+ * 1. The browser signs in to the phone network (`POST /calls/browser-token`
+ *    on your bridge), once per session - Plivo's SDK keeps its registration.
+ *    Plivo's SDK is loaded at this moment, not before, so a page that never
+ *    places a call never downloads it.
+ * 2. Connect approves the call (`POST /calls/start`): the workspace must hold
+ *    a number and the member must have "Make calls". What comes back lets this
+ *    browser place exactly this call and no other.
+ * 3. The browser places it. Connect dials the number from the workspace's own
+ *    number; nothing is recorded.
+ *
+ * ## Logging a call
+ *
+ * `onEnded` hands you the call id - deliberately not an outcome. A browser is
+ * not a witness your call log should trust, and the carrier's report reaches
+ * Connect a moment after the line drops anyway. Read the outcome on your
+ * **server** with `connect.calls.get(callId)` (`calls:read`): `status`,
+ * `talkSeconds`, `unansweredReason` and `placedByUserId` are what to log.
+ */
+type CallPhase = "connecting" | "ringing" | "in-call" | "ended";
+interface ActiveCall {
+    phase: CallPhase;
+    label: string;
+    number: string;
+    callId: string | null;
+    connectedAt: number | null;
+    endedAfterSeconds: number | null;
+    muted: boolean;
+    notice: string | null;
+}
+/** The number to ring, and how to name the person on the in-call bar. */
+export interface ConnectCallTarget {
+    /** E.164, e.g. `+919876543210`. */
+    phone: string;
+    /** Shown on the in-call bar. Defaults to the number. */
+    name?: string;
+    /**
+     * Called once the call is over, with Connect's id for it - or `null` when it
+     * never got as far as being approved. Read the outcome on your server with
+     * `connect.calls.get(callId)`; see the module comment for why not here.
+     */
+    onEnded?: (result: {
+        callId: string | null;
+    }) => void;
+}
+export interface ConnectCallContextValue {
+    /** A call is in progress - every Call button disables on it. */
+    isBusy: boolean;
+    startCall(target: ConnectCallTarget): Promise<void>;
+    /**
+     * Whether this member can call and, if not, why - `null` while it loads.
+     * Read once by the provider and shared, so every button and status panel
+     * agrees, and refreshed after each call so the minutes shown keep up.
+     */
+    availability: CallingAvailability | null;
+    /** Re-read `availability` - after a top-up in another tab, say. */
+    refreshAvailability(): void;
+}
+/** Start a call yourself. Must be inside `<ConnectCallProvider>`. */
+export declare function useConnectCall(): ConnectCallContextValue;
+export interface ConnectCallProviderProps {
+    children: ReactNode;
+    /**
+     * Called for every call that ends, whichever button started it - the place
+     * to wire "log this call" once for the whole app. A button's own `onEnded`
+     * runs as well.
+     */
+    onCallEnded?: (result: {
+        callId: string | null;
+        phone: string;
+    }) => void;
+    /** Called when a call could not be placed, with the reason to show. Defaults to the in-call bar saying so. */
+    onError?: (message: string) => void;
+    /** Extra classes for the in-call bar's outer element - merged with `cn`. */
+    className?: string;
+}
+/**
+ * Holds the call in progress and draws the in-call bar. See the module comment.
+ */
+export declare function ConnectCallProvider({ children, onCallEnded, onError, className, }: ConnectCallProviderProps): import("react").JSX.Element;
+export interface ConnectCallButtonProps extends ConnectCallTarget {
+    /** `compact` is an icon-only button for a row beside a number. */
+    variant?: "default" | "compact";
+    /** Button label. Defaults to "Call". */
+    children?: ReactNode;
+    isDisabled?: boolean;
+    /** Merged with `cn`, so an override replaces the default it conflicts with. */
+    className?: string;
+}
+/**
+ * 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 declare function ConnectCallButton({ phone, name, onEnded, variant, children, isDisabled, className, }: ConnectCallButtonProps): import("react").JSX.Element | null;
+export interface ConnectCallingStatusProps {
+    /** Merged with `cn`. */
+    className?: string;
+}
+/**
+ * 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 declare function ConnectCallingStatus({ className }: ConnectCallingStatusProps): import("react").JSX.Element;
+/** The floating in-call card. Exported for Storybook only - the provider draws it. */
+export declare function ConnectActiveCallBar({ call, onHangUp, onToggleMute, className, }: {
+    call: ActiveCall;
+    onHangUp: () => void;
+    onToggleMute: () => void;
+    className?: string;
+}): import("react").JSX.Element;
+export type { ActiveCall as ConnectActiveCall };

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

@@ -106,6 +106,8 @@ export { ConnectCreateWorkspaceModal } from "./components/create-workspace-form.
 export type { ConnectCreateWorkspaceModalProps } from "./components/create-workspace-form.js";
 export { useCreateWorkspace } from "./use-workspaces.js";
 export type { WorkspaceActionsState } from "./use-workspaces.js";
+export { ConnectCallProvider, ConnectCallButton, ConnectCallingStatus, useConnectCall, } from "./components/call-button.js";
+export type { ConnectCallProviderProps, ConnectCallButtonProps, ConnectCallTarget, ConnectCallContextValue, ConnectCallingStatusProps, } from "./components/call-button.js";
 export { ConnectBookingCalendar } from "./components/booking-calendar.js";
 export type { ConnectBookingCalendarProps } from "./components/booking-calendar.js";
 export { ConnectBookingDialog, ConnectBookingDetail } from "./components/booking-dialogs.js";

package/dist/types/client/portal-links.d.ts

@@ -4,7 +4,7 @@
  * `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/types/server/client.d.ts

@@ -138,4 +138,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.40.0";
+export declare const SDK_VERSION = "0.41.0";

package/dist/types/server/resources/calls.d.ts

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { CallDetail, CallsPage } from "../../types.js";
+import type { BrowserCallingToken, CallingAvailability, CallDetail, CallsPage, StartedBrowserCall } from "../../types.js";
 export interface ListCallsInput {
     /** Narrow to one channel. A channel belonging to another application simply matches nothing. */
     channelId?: string;
@@ -42,4 +42,35 @@ export declare class CallsResource {
      * exist *or* belongs to another application.
      */
     get(callId: string): Promise<CallDetail>;
+    /**
+     * 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: {
+        asUser: string;
+    }): Promise<CallingAvailability>;
+    /** A carrier token the member's browser signs in to the phone network with. */
+    getBrowserCallingToken(input: {
+        asUser: string;
+    }): Promise<BrowserCallingToken>;
+    /**
+     * 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: {
+        phone: string;
+        asUser: string;
+    }): Promise<StartedBrowserCall>;
+    /**
+     * Closes a call the browser never managed to place - recorded as
+     * `unanswered`/`cancelled`. A no-op once the carrier has it.
+     */
+    cancelBrowserCall(input: {
+        callId: string;
+        asUser: string;
+    }): Promise<void>;
 }

package/dist/types/types.d.ts

@@ -1269,12 +1269,29 @@ export interface CallCompletedEvent {
      * for presence.
      */
     extraction: Record<string, unknown>;
+    /**
+     * `member` when a person placed this call from a browser - `<ConnectCallButton>`
+     * or Connect's own portal - rather than an agent handling it. Absent on
+     * events sent before member calling existed; treat absent as `agent`.
+     */
+    handler?: CallHandler;
+    /**
+     * The member who placed a `member` call - their Connect user id, the same id
+     * a workspace roster carries. The one to attribute the call to. `null` on an
+     * agent's call.
+     */
+    placedByUserId?: string | null;
+    /** That member's display name, else their email - so the call can be attributed without a roster read. */
+    placedByName?: string | null;
     /** ISO-8601. */
     occurredAt: string;
 }
 /**
  * A call reached a channel and nothing answered it.
  *
+ * Also raised for a call a member placed that the person rang did not pick
+ * up (`handler: "member"`, `direction: "outbound"`) - somebody to try again.
+ *
  * Its own event rather than an `outcome` on the one above, because the action
  * differs in kind: a completed call is something to file, a missed one is
  * somebody to ring back. Treating this as a lead is the right thing to do
@@ -1287,6 +1304,20 @@ export interface CallMissedEvent {
     /** E.164, and the only identity this carries - see `CallCompletedEvent.contactPhone`. */
     contactPhone: string | null;
     direction: ConnectCallDirection;
+    /**
+     * `member` when a person placed this call from a browser - `<ConnectCallButton>`
+     * or Connect's own portal - rather than an agent handling it. Absent on
+     * events sent before member calling existed; treat absent as `agent`.
+     */
+    handler?: CallHandler;
+    /**
+     * The member who placed a `member` call - their Connect user id, the same id
+     * a workspace roster carries. The one to attribute the call to. `null` on an
+     * agent's call.
+     */
+    placedByUserId?: string | null;
+    /** That member's display name, else their email - so the call can be attributed without a roster read. */
+    placedByName?: string | null;
     /** ISO-8601. */
     occurredAt: string;
 }
@@ -2696,8 +2727,16 @@ export type CallDirection = "inbound" | "outbound";
  * `rejected` means Connect never connected it - see `rejectReason`.
  * `answered` is a call still in progress; `completed` is one that ran and
  * ended.
+ *
+ * `dialing` and `unanswered` are an outbound call's: ringing, and nobody
+ * picked up - see `unansweredReason`. A call your `<ConnectCallButton>`
+ * placed passes through `dialing` on its way to one of the other two.
  */
-export type CallStatus = "answered" | "rejected" | "completed";
+export type CallStatus = "dialing" | "answered" | "rejected" | "unanswered" | "completed";
+/** Who was on Connect's end of a call: one of the workspace's agents, or a member calling from a browser. */
+export type CallHandler = "agent" | "member";
+/** Why an outbound call reached nobody. Widened at its use site like `CallRejectReason`. */
+export type CallUnansweredReason = "no_answer" | "busy" | "failed" | "cancelled";
 /**
  * Why a call was refused. Widened at the point of use with `(string & {})`,
  * the same way `ReadinessBlocker.code` is: Connect adds reasons as it learns
@@ -2765,6 +2804,76 @@ export interface ConnectCall {
     extraction: Record<string, unknown> | null;
     agentId: string | null;
     agentVersion: number | null;
+    /** `member` for a call a person placed with `<ConnectCallButton>`; such a call has no agent, transcript or recording. */
+    handler: CallHandler;
+    /** The member who placed a `member` call - their Connect user id. */
+    placedByUserId: string | null;
+    /**
+     * How long the person called was on the line, for a `member` call. Read this
+     * rather than `durationSeconds`, which there measures the member's own leg,
+     * ringing included. `null` until the carrier reports it, and for a call
+     * nobody answered.
+     */
+    talkSeconds: number | null;
+    /** Why nobody answered - set only when `status` is `unanswered`. */
+    unansweredReason: CallUnansweredReason | (string & {}) | null;
+}
+/**
+ * What the browser needs to place one approved call - see
+ * `calls.startBrowserCall`. `headers` are SIP headers to send with it; they
+ * carry a one-time key, valid for two minutes, that lets the call be placed
+ * once and by nobody else.
+ */
+export interface StartedBrowserCall {
+    callId: string;
+    /** The number being rung, E.164. */
+    toNumber: string;
+    /** The workspace's own number, which the person called will see. */
+    fromNumber: string;
+    headers: Record<string, string>;
+}
+/**
+ * Why a member can or cannot call - see `calls.getCallingAvailability`.
+ *
+ * - `no_permission` - they lack "Make calls". Don't offer calling.
+ * - `no_number` - the workspace has no business number. `offer` says where to
+ *   buy one (a "Business number" add-on on one of its subscriptions).
+ * - `number_pending` - one was bought but Connect's pool was empty; an admin
+ *   can retry from Connect's Calling page.
+ * - `no_balance` - a number, but not a minute's worth of prepaid minutes.
+ * - `available`.
+ */
+export type CallingAvailabilityStatus = "available" | "no_permission" | "no_number" | "number_pending" | "no_balance";
+export interface CallingAvailability {
+    status: CallingAvailabilityStatus;
+    /** The workspace's business number, E.164, when it holds one. */
+    number: string | null;
+    /** Prepaid balance a new call may spend, in paise, pre-tax. */
+    available: number;
+    /** About how many minutes that buys. */
+    availableMinutes: number;
+    ratePaisePerMinute: number;
+    /** Under about 55 minutes - worth a warning. */
+    lowBalance: boolean;
+    /** Whether this member may buy minutes. */
+    canTopUp: boolean;
+    /** Whether this member may add the number add-on or retry a pending number. */
+    canManageNumber: boolean;
+    /** Where a business number can be bought, when the workspace has none. */
+    offer: {
+        subscriptionId: string;
+        applicationId: string;
+        addonId: string;
+        addonName: string;
+        /** Pre-tax, paise, per billing cycle. */
+        price: number;
+    } | null;
+}
+/** A carrier access token a member's browser signs in to the phone network with. Valid for an hour. */
+export interface BrowserCallingToken {
+    token: string;
+    /** ISO-8601. */
+    expiresAt: string;
 }
 /** Who spoke. */
 export type CallTurnRole = "user" | "agent";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Official server-side SDK for the CosmoOps Connect platform API - Login with Connect, entitlements, billing and metering.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -136,5 +136,8 @@
     "streamdown": {
       "optional": true
     }
+  },
+  "dependencies": {
+    "plivo-browser-sdk": "2.2.21"
   }
 }