@cosmoops/connect-sdk 0.42.0 → 0.44.0

package/CHANGELOG.md

@@ -3,8 +3,90 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.44.0
+
+### `ConnectCall.dialledAt`: was the person's phone rung?
+
+`unansweredReason: "cancelled"` covers two calls that need opposite handling:
+your user hanging up while the person's phone rang, and your user giving up
+before anybody was rung. The first left a missed call on the person's phone;
+the second never happened. Nothing on the call told them apart, so an app
+reading a call back after hang-up had to skip both and wait for the webhook.
+
+- **`dialledAt`** on `ConnectCall` (from `calls.get()` and `calls.list()`) is
+  when Connect asked the carrier to ring the person, on a `member` call. Set
+  means a cancelled call was a missed one - file it as missed, exactly as
+  `call.missed` would. `null` means nobody was rung - file nothing. Connect's
+  webhooks already follow the same rule.
+- It is on the record before any hang-up can be, so it never needs a retry.
+  `null` on agent calls and on member calls placed before this release.
+
+Nothing to wire if you file calls from `call.completed` / `call.missed` only.
+
+### `calls.list({ placedByApplication: true })`: the calls your UI placed
+
+A call placed with `<ConnectCallButton>` leaves from the workspace's own
+number, which is assigned to no application - so `calls.list()` never
+returned it, and an app whose webhook was delivered to another deployment had
+no way to find out the call happened. `placedByApplication: true` (with an
+optional `workspaceId`) lists exactly those calls, newest first: reconcile a
+call log from it.
+
+### Call recording, from inside your app
+
+`connect.calls.getCallSettings({ asUser })` and
+`connect.calls.setCallRecording({ recordingEnabled, asUser })` read and switch
+the workspace's call recording - the same switch as Connect's Calling screen.
+`canManage` is the member's own `channel:manage`; draw the switch disabled
+when it is false, because a save is refused `403`. The change applies to calls
+started afterwards and is audited against the member. Needs `calls:place`,
+which a key placing calls already holds.
+
+### The "Call ended" card shows the minutes left
+
+After a call, `<ConnectCallProvider>` re-reads the calling balance and the
+card now says how many minutes are left once that read lands, staying a few
+seconds longer to show it. Nothing to wire.
+
+## 0.43.0
+
+### Recorded calls: transcript, summary, intent and action items
+
+A workspace can now switch on **call recording** (Connect > Calling). Calls
+placed with `<ConnectCallButton>` are then recorded, the person called hears
+"This call may be recorded" as they answer, and a few minutes after the call
+Connect has transcribed it and read it.
+
+- **`call.analyzed`** - a new webhook event, sent after `call.completed` for a
+  recorded call. It carries `summary`, `intent` (a few words, e.g.
+  `"pricing enquiry"`), `sentiment`, `language`, `actionItems` (`title`,
+  `dueDate` as `YYYY-MM-DD` or `null`, and `owner`: `rep` or `customer`) and
+  `recordingFileId`. Subscribe to it on your webhook in Connect. Typed as
+  `CallAnalyzedEvent`.
+- **`calls.get(callId)`** returns the same reading as `call.analysis`, and
+  the transcript as the call's `turns` - your user as `agent`, the person
+  called as `user`. `analysis` is `null` for a call that was not recorded.
+- **The recording** is a Drive file: `connect.drive.getFileUrl(recordingFileId, { workspaceId })` with a
+  `drive:read` key plays it.
+
+Recording is the workspace's choice, off by default, and adds ₹0.30 + GST per
+minute to the call - nothing to wire on your side to offer it.
+
 ## 0.42.0
 
+### `connect.whatsapp` - your own approved templates, to a workspace's customers
+
+- **`whatsapp.send({ workspaceId, template, to, values, consent })`** sends one
+  of your application's Meta-approved templates - named by slug, resolved by
+  Connect as `app_<yourApplicationKey>_<slug>` - through Connect's WhatsApp
+  sender. Needs the `whatsapp:send` scope.
+- **`whatsapp.template(slug)`** answers `live` and the `variables` a send must
+  carry. Offer WhatsApp on a screen only when `live` is true.
+- `consent.collectedVia` records an opt-in your application collected, only
+  when Connect has none for the number. A number that opted out stays opted
+  out: the send fails with `opted_out`.
+
+
 ### Ask AI explains failures instead of printing them
 
 Nothing to wire - update and the panel behaves better on a bad day.

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

@@ -57,10 +57,15 @@ function useConnectCall() {
 }
 /** 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. */
+/** How long the "Call ended" card stays once it is showing the minutes left. */
 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;
+/**
+ * The longest the card waits for that re-read before going anyway - a read
+ * that failed must not leave a finished call on screen.
+ */
+const ENDED_CARD_MAX_MS = AVAILABILITY_SETTLE_MS + 6_000;
 function messageFromCause(cause) {
     if (typeof cause === "string" && cause.trim())
         return cause.trim();
@@ -86,6 +91,8 @@ function ConnectCallProvider({ children, onCallEnded, onError, className, }) {
     const targetRef = (0, react_1.useRef)(null);
     const callIdRef = (0, react_1.useRef)(null);
     const endedRef = (0, react_1.useRef)(false);
+    /** Set when a call ends; the next balance read is the one the card shows. */
+    const awaitingBalanceRef = (0, react_1.useRef)(false);
     const dismissTimer = (0, react_1.useRef)(null);
     // Read inside SDK event handlers wired once, so they always see the latest.
     const onCallEndedRef = (0, react_1.useRef)(onCallEnded);
@@ -118,15 +125,32 @@ function ConnectCallProvider({ children, onCallEnded, onError, className, }) {
             : current);
         if (dismissTimer.current)
             clearTimeout(dismissTimer.current);
-        dismissTimer.current = setTimeout(() => setCall(null), ENDED_CARD_MS);
+        dismissTimer.current = setTimeout(() => setCall(null), ENDED_CARD_MAX_MS);
         // The charge lands a moment after the line drops, so the minutes shown
-        // are re-read once it has had time to.
+        // are re-read once it has had time to - and the card waits for that read
+        // (see the effect below) rather than showing what was left before the call.
+        awaitingBalanceRef.current = true;
         setTimeout(() => refreshRef.current(), AVAILABILITY_SETTLE_MS);
         if (target) {
             target.onEnded?.({ callId });
             onCallEndedRef.current?.({ callId, phone: target.phone });
         }
     }, []);
+    /*
+     * The re-read after a call has landed: put what is left on the "Call ended"
+     * card, and give it its own few seconds from here, so the number is on
+     * screen long enough to read.
+     */
+    (0, react_1.useEffect)(() => {
+        if (!awaitingBalanceRef.current || !availability)
+            return;
+        awaitingBalanceRef.current = false;
+        const minutesLeft = availability.availableMinutes;
+        setCall((current) => (current?.phase === "ended" ? { ...current, minutesLeft } : current));
+        if (dismissTimer.current)
+            clearTimeout(dismissTimer.current);
+        dismissTimer.current = setTimeout(() => setCall(null), ENDED_CARD_MS);
+    }, [availability]);
     const wire = (0, react_1.useCallback)((client) => {
         const ringing = () => setCall((current) => (current ? { ...current, phase: "ringing" } : current));
         client.on("onCalling", ringing);
@@ -200,6 +224,7 @@ function ConnectCallProvider({ children, onCallEnded, onError, className, }) {
         if (dismissTimer.current)
             clearTimeout(dismissTimer.current);
         targetRef.current = target;
+        awaitingBalanceRef.current = false;
         callIdRef.current = null;
         placedRef.current = false;
         endedRef.current = false;
@@ -212,6 +237,7 @@ function ConnectCallProvider({ children, onCallEnded, onError, className, }) {
             endedAfterSeconds: null,
             muted: false,
             notice: null,
+            minutesLeft: null,
         });
         try {
             const client = await signIn();
@@ -383,7 +409,15 @@ function ConnectActiveCallBar({ call, onHangUp, onToggleMute, className, }) {
         : call.phase === "ended" && call.endedAfterSeconds !== null
             ? `Call ended · ${formatSeconds(call.endedAfterSeconds)}`
             : PHASE_LABEL[call.phase];
-    return ((0, jsx_runtime_1.jsx)("div", { role: "status", "aria-live": "polite", className: (0, cn_js_1.cn)("fixed inset-x-0 bottom-4 z-50 flex justify-center px-4", className), children: (0, jsx_runtime_1.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: [(0, jsx_runtime_1.jsx)("span", { className: "flex size-9 shrink-0 items-center justify-center rounded-full bg-accent-soft text-accent", children: (0, jsx_runtime_1.jsx)(lucide_react_1.PhoneOutgoing, { "aria-hidden": true, className: "size-4" }) }), (0, jsx_runtime_1.jsxs)("div", { className: "min-w-0 flex-1", children: [(0, jsx_runtime_1.jsx)("p", { className: "truncate text-sm font-medium", children: call.label }), (0, jsx_runtime_1.jsxs)("p", { className: "truncate text-xs text-muted tabular-nums", children: [status, call.notice ? ` · ${call.notice}` : call.label === call.number ? "" : ` · ${call.number}`] })] }), live && ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "secondary", "aria-label": call.muted ? "Unmute" : "Mute", isDisabled: call.phase !== "in-call", onPress: onToggleMute, children: call.muted ? (0, jsx_runtime_1.jsx)(lucide_react_1.MicOff, { className: "size-4" }) : (0, jsx_runtime_1.jsx)(lucide_react_1.Mic, { className: "size-4" }) }), (0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "danger", "aria-label": "Hang up", onPress: onHangUp, children: (0, jsx_runtime_1.jsx)(lucide_react_1.PhoneOff, { className: "size-4" }) })] }))] }) }));
+    const remaining = call.phase === "ended" ? minutesLeftLabel(call.minutesLeft) : null;
+    return ((0, jsx_runtime_1.jsx)("div", { role: "status", "aria-live": "polite", className: (0, cn_js_1.cn)("fixed inset-x-0 bottom-4 z-50 flex justify-center px-4", className), children: (0, jsx_runtime_1.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: [(0, jsx_runtime_1.jsx)("span", { className: "flex size-9 shrink-0 items-center justify-center rounded-full bg-accent-soft text-accent", children: (0, jsx_runtime_1.jsx)(lucide_react_1.PhoneOutgoing, { "aria-hidden": true, className: "size-4" }) }), (0, jsx_runtime_1.jsxs)("div", { className: "min-w-0 flex-1", children: [(0, jsx_runtime_1.jsx)("p", { className: "truncate text-sm font-medium", children: call.label }), (0, jsx_runtime_1.jsxs)("p", { className: "truncate text-xs text-muted tabular-nums", children: [status, call.notice ? ` · ${call.notice}` : call.label === call.number ? "" : ` · ${call.number}`] }), remaining && (0, jsx_runtime_1.jsx)("p", { className: "truncate text-xs text-muted tabular-nums", children: remaining })] }), live && ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "secondary", "aria-label": call.muted ? "Unmute" : "Mute", isDisabled: call.phase !== "in-call", onPress: onToggleMute, children: call.muted ? (0, jsx_runtime_1.jsx)(lucide_react_1.MicOff, { className: "size-4" }) : (0, jsx_runtime_1.jsx)(lucide_react_1.Mic, { className: "size-4" }) }), (0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "danger", "aria-label": "Hang up", onPress: onHangUp, children: (0, jsx_runtime_1.jsx)(lucide_react_1.PhoneOff, { className: "size-4" }) })] }))] }) }));
+}
+/** "42 min of calling left", once the post-call balance read has landed. */
+function minutesLeftLabel(minutes) {
+    if (minutes === null)
+        return null;
+    const whole = Math.max(0, Math.floor(minutes));
+    return whole === 0 ? "No calling minutes left" : `${whole} min of calling left`;
 }
 /** Seconds since `since`, ticking once a second. `0` while there is nothing to time. */
 function useElapsedSeconds(since) {

package/dist/cjs/server/client.js

@@ -183,4 +183,4 @@ class ConnectClient {
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.42.0";
+exports.SDK_VERSION = "0.44.0";

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

@@ -31,6 +31,8 @@ class CallsResource {
             path: "/calls",
             query: {
                 channelId: input.channelId,
+                placedByApplication: input.placedByApplication ? "true" : undefined,
+                workspaceId: input.workspaceId,
                 cursor: input.cursor,
                 limit: input.limit === undefined ? undefined : String(input.limit),
             },
@@ -60,8 +62,11 @@ class CallsResource {
      * All three need the `calls:place` scope **and** a signed-in member
      * (`asUser`), whose own "Make calls" permission Connect checks. None works
      * server-to-server: a call is placed by a person, from the workspace's own
-     * number, and is not recorded. Read how one went with `get(callId)`, which
-     * needs `calls:read` - a call your application placed is readable by it.
+     * number. It is recorded only when the workspace has switched recording on
+     * (the person called hears a notice); `call.analyzed` then follows with the
+     * summary, intent and action items. Read how one went with `get(callId)`,
+     * which needs `calls:read` - a call your application placed is readable by
+     * it, transcript included.
      */
     /**
      * Whether the member can call, and if not why - what `<ConnectCallButton>`
@@ -75,6 +80,30 @@ class CallsResource {
             headers: (0, acting_as_js_1.actingAs)(input.asUser),
         });
     }
+    /**
+     * Whether the workspace records its member calls, and whether this member
+     * may change that. The same switch as Connect's Calling screen.
+     */
+    getCallSettings(input) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: "/calls/settings",
+            headers: (0, acting_as_js_1.actingAs)(input.asUser),
+        });
+    }
+    /**
+     * Switches recording on or off for calls started from now. Throws
+     * `ConnectError` 403 when the member lacks `channel:manage`; the change is
+     * audited against them. Answers the settings as they now stand.
+     */
+    setCallRecording(input) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "PUT",
+            path: "/calls/settings",
+            json: { recordingEnabled: input.recordingEnabled },
+            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, {

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

@@ -17,10 +17,15 @@ export function useConnectCall() {
 }
 /** 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. */
+/** How long the "Call ended" card stays once it is showing the minutes left. */
 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;
+/**
+ * The longest the card waits for that re-read before going anyway - a read
+ * that failed must not leave a finished call on screen.
+ */
+const ENDED_CARD_MAX_MS = AVAILABILITY_SETTLE_MS + 6_000;
 function messageFromCause(cause) {
     if (typeof cause === "string" && cause.trim())
         return cause.trim();
@@ -46,6 +51,8 @@ export function ConnectCallProvider({ children, onCallEnded, onError, className,
     const targetRef = useRef(null);
     const callIdRef = useRef(null);
     const endedRef = useRef(false);
+    /** Set when a call ends; the next balance read is the one the card shows. */
+    const awaitingBalanceRef = useRef(false);
     const dismissTimer = useRef(null);
     // Read inside SDK event handlers wired once, so they always see the latest.
     const onCallEndedRef = useRef(onCallEnded);
@@ -78,15 +85,32 @@ export function ConnectCallProvider({ children, onCallEnded, onError, className,
             : current);
         if (dismissTimer.current)
             clearTimeout(dismissTimer.current);
-        dismissTimer.current = setTimeout(() => setCall(null), ENDED_CARD_MS);
+        dismissTimer.current = setTimeout(() => setCall(null), ENDED_CARD_MAX_MS);
         // The charge lands a moment after the line drops, so the minutes shown
-        // are re-read once it has had time to.
+        // are re-read once it has had time to - and the card waits for that read
+        // (see the effect below) rather than showing what was left before the call.
+        awaitingBalanceRef.current = true;
         setTimeout(() => refreshRef.current(), AVAILABILITY_SETTLE_MS);
         if (target) {
             target.onEnded?.({ callId });
             onCallEndedRef.current?.({ callId, phone: target.phone });
         }
     }, []);
+    /*
+     * The re-read after a call has landed: put what is left on the "Call ended"
+     * card, and give it its own few seconds from here, so the number is on
+     * screen long enough to read.
+     */
+    useEffect(() => {
+        if (!awaitingBalanceRef.current || !availability)
+            return;
+        awaitingBalanceRef.current = false;
+        const minutesLeft = availability.availableMinutes;
+        setCall((current) => (current?.phase === "ended" ? { ...current, minutesLeft } : current));
+        if (dismissTimer.current)
+            clearTimeout(dismissTimer.current);
+        dismissTimer.current = setTimeout(() => setCall(null), ENDED_CARD_MS);
+    }, [availability]);
     const wire = useCallback((client) => {
         const ringing = () => setCall((current) => (current ? { ...current, phase: "ringing" } : current));
         client.on("onCalling", ringing);
@@ -160,6 +184,7 @@ export function ConnectCallProvider({ children, onCallEnded, onError, className,
         if (dismissTimer.current)
             clearTimeout(dismissTimer.current);
         targetRef.current = target;
+        awaitingBalanceRef.current = false;
         callIdRef.current = null;
         placedRef.current = false;
         endedRef.current = false;
@@ -172,6 +197,7 @@ export function ConnectCallProvider({ children, onCallEnded, onError, className,
             endedAfterSeconds: null,
             muted: false,
             notice: null,
+            minutesLeft: null,
         });
         try {
             const client = await signIn();
@@ -343,7 +369,15 @@ export function ConnectActiveCallBar({ call, onHangUp, onToggleMute, className,
         : 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" }) })] }))] }) }));
+    const remaining = call.phase === "ended" ? minutesLeftLabel(call.minutesLeft) : null;
+    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}`] }), remaining && _jsx("p", { className: "truncate text-xs text-muted tabular-nums", children: remaining })] }), 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" }) })] }))] }) }));
+}
+/** "42 min of calling left", once the post-call balance read has landed. */
+function minutesLeftLabel(minutes) {
+    if (minutes === null)
+        return null;
+    const whole = Math.max(0, Math.floor(minutes));
+    return whole === 0 ? "No calling minutes left" : `${whole} min of calling left`;
 }
 /** Seconds since `since`, ticking once a second. `0` while there is nothing to time. */
 function useElapsedSeconds(since) {

package/dist/esm/server/client.js

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

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

@@ -28,6 +28,8 @@ export class CallsResource {
             path: "/calls",
             query: {
                 channelId: input.channelId,
+                placedByApplication: input.placedByApplication ? "true" : undefined,
+                workspaceId: input.workspaceId,
                 cursor: input.cursor,
                 limit: input.limit === undefined ? undefined : String(input.limit),
             },
@@ -57,8 +59,11 @@ export class CallsResource {
      * All three need the `calls:place` scope **and** a signed-in member
      * (`asUser`), whose own "Make calls" permission Connect checks. None works
      * server-to-server: a call is placed by a person, from the workspace's own
-     * number, and is not recorded. Read how one went with `get(callId)`, which
-     * needs `calls:read` - a call your application placed is readable by it.
+     * number. It is recorded only when the workspace has switched recording on
+     * (the person called hears a notice); `call.analyzed` then follows with the
+     * summary, intent and action items. Read how one went with `get(callId)`,
+     * which needs `calls:read` - a call your application placed is readable by
+     * it, transcript included.
      */
     /**
      * Whether the member can call, and if not why - what `<ConnectCallButton>`
@@ -72,6 +77,30 @@ export class CallsResource {
             headers: actingAs(input.asUser),
         });
     }
+    /**
+     * Whether the workspace records its member calls, and whether this member
+     * may change that. The same switch as Connect's Calling screen.
+     */
+    getCallSettings(input) {
+        return request(this.transport, {
+            method: "GET",
+            path: "/calls/settings",
+            headers: actingAs(input.asUser),
+        });
+    }
+    /**
+     * Switches recording on or off for calls started from now. Throws
+     * `ConnectError` 403 when the member lacks `channel:manage`; the change is
+     * audited against them. Answers the settings as they now stand.
+     */
+    setCallRecording(input) {
+        return request(this.transport, {
+            method: "PUT",
+            path: "/calls/settings",
+            json: { recordingEnabled: input.recordingEnabled },
+            headers: actingAs(input.asUser),
+        });
+    }
     /** A carrier token the member's browser signs in to the phone network with. */
     getBrowserCallingToken(input) {
         return request(this.transport, {

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

@@ -45,6 +45,12 @@ interface ActiveCall {
     endedAfterSeconds: number | null;
     muted: boolean;
     notice: string | null;
+    /**
+     * Calling minutes left once this call has been charged - filled on the
+     * "Call ended" card by the balance re-read that follows it, and `null`
+     * until that read lands, so the card never shows the pre-call figure.
+     */
+    minutesLeft: number | null;
 }
 /** The number to ring, and how to name the person on the in-call bar. */
 export interface ConnectCallTarget {

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

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

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

@@ -1,8 +1,17 @@
 import { type TransportOptions } from "../http.js";
-import type { BrowserCallingToken, CallingAvailability, CallDetail, CallsPage, StartedBrowserCall } from "../../types.js";
+import type { BrowserCallingToken, CallingAvailability, CallSettings, CallDetail, CallsPage, StartedBrowserCall } from "../../types.js";
 export interface ListCallsInput {
     /** Narrow to one channel. A channel belonging to another application simply matches nothing. */
     channelId?: string;
+    /**
+     * `true` for the member calls your UI placed (`<ConnectCallButton>`) instead
+     * of the calls on your channels. Those leave from the workspace's own
+     * number, so the default list never contains them - this is the list to
+     * reconcile a timeline from when a webhook went to another deployment.
+     */
+    placedByApplication?: boolean;
+    /** With `placedByApplication`, one workspace's calls. */
+    workspaceId?: string;
     /** From a previous page's `nextCursor`. */
     cursor?: string;
     /** 1-100, default 50. */
@@ -50,6 +59,22 @@ export declare class CallsResource {
     getCallingAvailability(input: {
         asUser: string;
     }): Promise<CallingAvailability>;
+    /**
+     * Whether the workspace records its member calls, and whether this member
+     * may change that. The same switch as Connect's Calling screen.
+     */
+    getCallSettings(input: {
+        asUser: string;
+    }): Promise<CallSettings>;
+    /**
+     * Switches recording on or off for calls started from now. Throws
+     * `ConnectError` 403 when the member lacks `channel:manage`; the change is
+     * audited against them. Answers the settings as they now stand.
+     */
+    setCallRecording(input: {
+        recordingEnabled: boolean;
+        asUser: string;
+    }): Promise<CallSettings>;
     /** A carrier token the member's browser signs in to the phone network with. */
     getBrowserCallingToken(input: {
         asUser: string;

package/dist/types/types.d.ts

@@ -1114,7 +1114,7 @@ export interface EmitEventsResponse {
  * `createConnectWebhookHandler` simply ignores anything you have not
  * registered a handler for.
  */
-export type ConnectWebhookEventType = "workspace.deletion_scheduled" | "workspace.deletion_cancelled" | "workspace.deleted" | "subscription.cancelled" | "call.completed" | "call.missed" | "booking.confirmed" | "booking.cancelled" | "booking.rescheduled" | "contact.created" | "contact.updated";
+export type ConnectWebhookEventType = "workspace.deletion_scheduled" | "workspace.deletion_cancelled" | "workspace.deleted" | "subscription.cancelled" | "call.completed" | "call.missed" | "call.analyzed" | "booking.confirmed" | "booking.cancelled" | "booking.rescheduled" | "contact.created" | "contact.updated";
 /** What becomes of one class of data when the workspace is purged. */
 export type ConnectDataDisposition = "erase" | "anonymize" | "retain";
 /** Who answers for your copy of the customer's data. See the deletion-policy guide. */
@@ -1321,6 +1321,48 @@ export interface CallMissedEvent {
     /** ISO-8601. */
     occurredAt: string;
 }
+/** How the person called came across, by the end of the call. */
+export type CallSentiment = "positive" | "neutral" | "negative";
+/**
+ * Something somebody committed to on a recorded call. `owner` is who said
+ * they would do it - `rep` for your user's side, `customer` for the person
+ * called. Both are worth a follow-up: one to do, one to chase.
+ */
+export interface CallActionItem {
+    title: string;
+    /** `YYYY-MM-DD` when a day was named or clearly implied, else `null`. */
+    dueDate: string | null;
+    owner: "rep" | "customer";
+}
+/**
+ * A recorded call, transcribed and read. Sent minutes after `call.completed`,
+ * and only for calls placed while the workspace records them - file the call
+ * on `call.completed` and enrich that row here. The transcript itself is the
+ * call's turns on `calls.get`.
+ */
+export interface CallAnalyzedEvent {
+    workspaceId: string;
+    callId: string;
+    channelId: string | null;
+    /** E.164 - the person called on an outbound call, the caller on an inbound one. */
+    contactPhone: string | null;
+    direction: ConnectCallDirection;
+    handler: CallHandler;
+    placedByUserId: string | null;
+    placedByName: string | null;
+    /** Two or three sentences, in English whatever language was spoken. */
+    summary: string | null;
+    /** Why they were on the call, in a few lowercase words - "pricing enquiry". */
+    intent: string | null;
+    sentiment: CallSentiment | null;
+    /** The main language spoken, BCP-47 - `hi-IN`, `en-IN`. */
+    language: string | null;
+    actionItems: CallActionItem[];
+    /** The audio in the workspace's Drive - read it with a `drive:read` key. */
+    recordingFileId: string | null;
+    /** ISO-8601 - when the call started. */
+    occurredAt: string;
+}
 /**
  * An appointment was booked and is holding its slot.
  *
@@ -1446,6 +1488,7 @@ export interface ConnectWebhookEventMap {
     "subscription.cancelled": SubscriptionCancelledEvent;
     "call.completed": CallCompletedEvent;
     "call.missed": CallMissedEvent;
+    "call.analyzed": CallAnalyzedEvent;
     "booking.confirmed": BookingConfirmedEvent;
     "booking.cancelled": BookingCancelledEvent;
     "booking.rescheduled": BookingRescheduledEvent;
@@ -2804,7 +2847,7 @@ 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. */
+    /** `member` for a call a person placed with `<ConnectCallButton>`. Such a call has no agent; it has a recording, a transcript and an `analysis` only when the workspace records calls. */
     handler: CallHandler;
     /** The member who placed a `member` call - their Connect user id. */
     placedByUserId: string | null;
@@ -2815,8 +2858,31 @@ export interface ConnectCall {
      * nobody answered.
      */
     talkSeconds: number | null;
+    /**
+     * When Connect asked the carrier to ring the person called, on a `member`
+     * call. Tells apart the two calls `unansweredReason: "cancelled"` covers:
+     * set when the member hung up while it rang (the person sees a missed call -
+     * Connect sends `call.missed`), `null` when they gave up before anyone was
+     * rung (no call happened, and no event is sent).
+     */
+    dialledAt: string | null;
     /** Why nobody answered - set only when `status` is `unanswered`. */
     unansweredReason: CallUnansweredReason | (string & {}) | null;
+    /**
+     * The reading of a recorded member call - summary, intent, action items.
+     * `null` for a call that was not recorded; `status: "pending"` while it is
+     * being read. The transcript is `CallDetail.turns`, the member as `agent`
+     * and the person called as `user`.
+     */
+    analysis: ConnectCallAnalysis | null;
+}
+export interface ConnectCallAnalysis {
+    status: "pending" | "done" | "failed";
+    summary: string | null;
+    intent: string | null;
+    sentiment: CallSentiment | null;
+    actionItems: CallActionItem[];
+    language: string | null;
 }
 /**
  * What the browser needs to place one approved call - see
@@ -2844,6 +2910,18 @@ export interface StartedBrowserCall {
  * - `available`.
  */
 export type CallingAvailabilityStatus = "available" | "no_permission" | "no_number" | "number_pending" | "no_balance";
+/**
+ * The workspace's calling settings, as the signed-in member sees them -
+ * `connect.calls.getCallSettings()`.
+ */
+export interface CallSettings {
+    /** Whether member calls are recorded, transcribed and read (`call.analyzed`). */
+    recordingEnabled: boolean;
+    /** Paise, pre-tax, recording adds to every billed minute - show it beside the switch. */
+    recordingRatePaisePerMinute: number;
+    /** Whether this member may change it - their `channel:manage`. Draw the switch disabled when not. */
+    canManage: boolean;
+}
 export interface CallingAvailability {
     status: CallingAvailabilityStatus;
     /** The workspace's business number, E.164, when it holds one. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.42.0",
+  "version": "0.44.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",