@cosmoops/connect-sdk 0.47.0 → 0.48.0

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.48.0
+
+### Calls declare a purpose
+
+`<ConnectCallButton purpose="promotional">`, `startCall({ phone, purpose })`
+and `connect.calls.startBrowserCall({ phone, asUser, purpose })` take an
+optional `ConnectCallPurpose` - `"service"`, `"transactional"` or
+`"promotional"`. Connect records it on the call and places the call from a
+workspace number allowed to carry it: in India a regular number carries
+service and transactional calls only, and promotional calls need a 140-series
+number with an approved DLT header. Omit it and the call is placed as before.
+
+While the workspace's Connect deployment runs `CALL_PURPOSE_ENFORCEMENT=shadow`
+(the default), a call no number may carry is still placed and only logged;
+under `enforce` it is refused with a `412` whose message names the number
+series needed. The bridge drops a purpose that is not one of the three
+rather than forwarding it to be refused.
+
 ## 0.47.0
 
 ### `connect.integrations.request()` reaches the endpoints a toolkit has no action for

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

@@ -243,6 +243,7 @@ function ConnectCallProvider({ children, onCallEnded, onError, className, }) {
             const client = await signIn();
             const started = await mutateResource("/calls/start", {
                 phone: target.phone,
+                ...(target.purpose ? { purpose: target.purpose } : {}),
             });
             callIdRef.current = started.callId;
             setCall((current) => current ? { ...current, callId: started.callId, number: started.toNumber } : current);
@@ -308,9 +309,9 @@ function ConnectCallProvider({ children, onCallEnded, onError, className, }) {
  * above it, and a member with "Make calls" - render it only for them, since a
  * button the server refuses for everyone else helps nobody.
  */
-function ConnectCallButton({ phone, name, onEnded, variant = "default", children, isDisabled, className, }) {
+function ConnectCallButton({ phone, name, purpose, onEnded, variant = "default", children, isDisabled, className, }) {
     const { isBusy, startCall, availability } = useConnectCall();
-    const press = () => void startCall({ phone, name, onEnded });
+    const press = () => void startCall({ phone, name, purpose, onEnded });
     // Not offered at all to someone who may not call - a button that always
     // refuses helps nobody.
     if (availability?.status === "no_permission")

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.47.0";
+exports.SDK_VERSION = "0.48.0";

package/dist/cjs/server/handler.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createConnectHandler = createConnectHandler;
 const errors_js_1 = require("../errors.js");
 const identity_js_1 = require("./resources/identity.js");
+/** The purposes `/calls/start` accepts - see `ConnectCallPurpose`. */
+const CALL_PURPOSES = ["service", "transactional", "promotional"];
 /**
  * A sentinel origin to resolve a candidate destination against. Never reached -
  * `.invalid` is reserved by RFC 2606 precisely so it cannot resolve.
@@ -1260,7 +1262,10 @@ function createConnectHandler(options) {
                     endpoint: "/calls/start",
                 });
             }
-            return json(await client.calls.startBrowserCall({ phone: body.phone, asUser }), 201);
+            // Passed on only when it is one of the three - Connect validates it
+            // again, and an unknown value is dropped rather than sent to be refused.
+            const purpose = CALL_PURPOSES.find((value) => value === body.purpose);
+            return json(await client.calls.startBrowserCall({ phone: body.phone, asUser, purpose }), 201);
         },
         "POST /calls/cancel": async (request) => {
             await requireWorkspace(request);

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

@@ -118,13 +118,14 @@ class CallsResource {
      *
      * 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.
+     * the message is written to be shown to them. With a `purpose`, also when
+     * no number may carry it and the workspace enforces purposes.
      */
     startBrowserCall(input) {
         return (0, http_js_1.request)(this.transport, {
             method: "POST",
             path: "/calls/start",
-            json: { phone: input.phone },
+            json: input.purpose ? { phone: input.phone, purpose: input.purpose } : { phone: input.phone },
             headers: (0, acting_as_js_1.actingAs)(input.asUser),
         });
     }

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

@@ -203,6 +203,7 @@ export function ConnectCallProvider({ children, onCallEnded, onError, className,
             const client = await signIn();
             const started = await mutateResource("/calls/start", {
                 phone: target.phone,
+                ...(target.purpose ? { purpose: target.purpose } : {}),
             });
             callIdRef.current = started.callId;
             setCall((current) => current ? { ...current, callId: started.callId, number: started.toNumber } : current);
@@ -268,9 +269,9 @@ export function ConnectCallProvider({ children, onCallEnded, onError, className,
  * 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, }) {
+export function ConnectCallButton({ phone, name, purpose, onEnded, variant = "default", children, isDisabled, className, }) {
     const { isBusy, startCall, availability } = useConnectCall();
-    const press = () => void startCall({ phone, name, onEnded });
+    const press = () => void startCall({ phone, name, purpose, onEnded });
     // Not offered at all to someone who may not call - a button that always
     // refuses helps nobody.
     if (availability?.status === "no_permission")

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.47.0";
+export const SDK_VERSION = "0.48.0";

package/dist/esm/server/handler.js

@@ -1,5 +1,7 @@
 import { ConnectError } from "../errors.js";
 import { createPkcePair, createState } from "./resources/identity.js";
+/** The purposes `/calls/start` accepts - see `ConnectCallPurpose`. */
+const CALL_PURPOSES = ["service", "transactional", "promotional"];
 /**
  * A sentinel origin to resolve a candidate destination against. Never reached -
  * `.invalid` is reserved by RFC 2606 precisely so it cannot resolve.
@@ -1257,7 +1259,10 @@ export function createConnectHandler(options) {
                     endpoint: "/calls/start",
                 });
             }
-            return json(await client.calls.startBrowserCall({ phone: body.phone, asUser }), 201);
+            // Passed on only when it is one of the three - Connect validates it
+            // again, and an unknown value is dropped rather than sent to be refused.
+            const purpose = CALL_PURPOSES.find((value) => value === body.purpose);
+            return json(await client.calls.startBrowserCall({ phone: body.phone, asUser, purpose }), 201);
         },
         "POST /calls/cancel": async (request) => {
             await requireWorkspace(request);

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

@@ -115,13 +115,14 @@ export class CallsResource {
      *
      * 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.
+     * the message is written to be shown to them. With a `purpose`, also when
+     * no number may carry it and the workspace enforces purposes.
      */
     startBrowserCall(input) {
         return request(this.transport, {
             method: "POST",
             path: "/calls/start",
-            json: { phone: input.phone },
+            json: input.purpose ? { phone: input.phone, purpose: input.purpose } : { phone: input.phone },
             headers: actingAs(input.asUser),
         });
     }

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

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import type { CallingAvailability } from "../../types.js";
+import type { CallingAvailability, ConnectCallPurpose } from "../../types.js";
 /**
  * Calling from the browser, through the workspace's own number.
  *
@@ -60,6 +60,11 @@ export interface ConnectCallTarget {
     phone: string;
     /** Shown on the in-call bar. Defaults to the number. */
     name?: string;
+    /**
+     * What the call is for - Connect places it from a number allowed to carry
+     * it. See `ConnectCallPurpose`; omit it to place the call as before.
+     */
+    purpose?: ConnectCallPurpose;
     /**
      * 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
@@ -118,7 +123,7 @@ export interface ConnectCallButtonProps extends ConnectCallTarget {
  * 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 declare function ConnectCallButton({ phone, name, purpose, onEnded, variant, children, isDisabled, className, }: ConnectCallButtonProps): import("react").JSX.Element | null;
 export interface ConnectCallingStatusProps {
     /** Merged with `cn`. */
     className?: string;

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.47.0";
+export declare const SDK_VERSION = "0.48.0";

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

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { BrowserCallingToken, CallingAvailability, CallSettings, CallDetail, CallsPage, StartedBrowserCall } from "../../types.js";
+import type { BrowserCallingToken, CallingAvailability, CallSettings, CallDetail, CallsPage, ConnectCallPurpose, StartedBrowserCall } from "../../types.js";
 export interface ListCallsInput {
     /** Narrow to one channel. A channel belonging to another application simply matches nothing. */
     channelId?: string;
@@ -84,11 +84,13 @@ export declare class CallsResource {
      *
      * 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.
+     * the message is written to be shown to them. With a `purpose`, also when
+     * no number may carry it and the workspace enforces purposes.
      */
     startBrowserCall(input: {
         phone: string;
         asUser: string;
+        purpose?: ConnectCallPurpose;
     }): Promise<StartedBrowserCall>;
     /**
      * Closes a call the browser never managed to place - recorded as

package/dist/types/types.d.ts

@@ -2911,6 +2911,14 @@ export interface ConnectCallAnalysis {
  * carry a one-time key, valid for two minutes, that lets the call be placed
  * once and by nobody else.
  */
+/**
+ * What a call is for, declared by the caller - Connect places it from a
+ * workspace number allowed to carry it. In India the series decides: regular
+ * numbers carry `service` and `transactional`, 140-series numbers carry
+ * `promotional` only. Omit it and the call is placed as before and recorded
+ * as undeclared.
+ */
+export type ConnectCallPurpose = "service" | "transactional" | "promotional";
 export interface StartedBrowserCall {
     callId: string;
     /** The number being rung, E.164. */

package/package.json

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