@cosmoops/connect-sdk 0.48.0 → 0.49.0

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.49.0
+
+### Calling readiness
+
+`connect.calls.getCallingReadiness({ asUser })` answers whether the
+workspace may legally make each kind of call - `runs` covers service and
+sales (`promotional`) calls, dialled by a rep (`preview`) or by software
+(`automatic`), each with the first `reason` in the way - plus the steps left
+on Connect's calling compliance journey and a `setupUrl` to finish them.
+Member-only, on the `calls:place` scope. Read `runs` rather than deriving
+anything from `steps`: Connect evaluates them with the gates its dialer
+refuses on. Additive; nothing else changed.
+
 ## 0.48.0
 
 ### Calls declare a purpose

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.48.0";
+exports.SDK_VERSION = "0.49.0";

package/dist/cjs/server/handler.js

@@ -1,10 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_CACHE_TTL_MS = void 0;
 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"];
+/**
+ * The bridge's default session reuse window - the longest a revoked session,
+ * a removed member or a sign-out on another device keeps working through a
+ * warm instance. Seconds on purpose: this gates a person's access.
+ */
+exports.SESSION_CACHE_TTL_MS = 15_000;
+/** Sessions held per handler. Least recently used falls out first. */
+const SESSION_CACHE_MAX = 5_000;
 /**
  * A sentinel origin to resolve a candidate destination against. Never reached -
  * `.invalid` is reserved by RFC 2606 precisely so it cannot resolve.
@@ -310,9 +319,71 @@ function createConnectHandler(options) {
         }
         return token;
     }
+    /**
+     * Resolved sessions, per session token, for `SESSION_CACHE_TTL_MS`.
+     *
+     * Every tenant-scoped route starts by asking Connect who the caller is, and
+     * a page load fires several of them at once - so uncached, the bridge made
+     * one `/sso/user` round trip per browser request, and a partner's Connect
+     * traffic grew with their users times their routes. A resolved session is
+     * kept per token for a few seconds instead, the same trade
+     * `crmSession` makes in the reference CRM:
+     *
+     * - **Staleness is bounded and small.** A revoked session, a removed member
+     *   or a reduced role keeps working here for at most the TTL.
+     * - **Signing out is still immediate.** The cache is keyed by the token the
+     *   partner's session store hands back; `/logout` drops the entry, and once
+     *   the cookie is gone there is no token to look up.
+     * - **`GET /session` always reads through.** It is what the browser re-reads
+     *   after a hand-off (a plan bought in a popup, a profile edit), so it must
+     *   see the change at once; it refreshes the entry for everyone after it.
+     *
+     * The promise is cached rather than the value, so a burst of parallel
+     * requests on a cold token makes one round trip, and a failed lookup is
+     * dropped at once - a refusal is never remembered.
+     *
+     * Per handler and in process, timed on `performance.now()` (a monotonic
+     * clock cannot jump when the system clock is corrected).
+     */
+    const sessionCacheTtlMs = Math.max(0, options.sessionCacheTtlMs ?? exports.SESSION_CACHE_TTL_MS);
+    const sessionCache = new Map();
+    function rememberSession(token, session) {
+        if (sessionCacheTtlMs === 0)
+            return session;
+        sessionCache.delete(token);
+        while (sessionCache.size >= SESSION_CACHE_MAX) {
+            const oldest = sessionCache.keys().next();
+            if (oldest.done)
+                break;
+            sessionCache.delete(oldest.value);
+        }
+        const entry = { session, until: performance.now() + sessionCacheTtlMs };
+        sessionCache.set(token, entry);
+        session.catch(() => {
+            // Only the entry this lookup created - a newer one for the same token
+            // must survive an older lookup failing late.
+            if (sessionCache.get(token) === entry)
+                sessionCache.delete(token);
+        });
+        return session;
+    }
+    /** A fresh read from Connect, which then answers the cached routes too. */
+    function resolveSessionFresh(token) {
+        return rememberSession(token, client.identity.getUser(token));
+    }
+    function resolveSession(token) {
+        const hit = sessionCache.get(token);
+        if (hit && hit.until > performance.now()) {
+            // Re-inserted so the map's order tracks recency.
+            sessionCache.delete(token);
+            sessionCache.set(token, hit);
+            return hit.session;
+        }
+        return resolveSessionFresh(token);
+    }
     /** Signed-in identity plus the workspace it belongs to - the first read every other route needs. */
     async function whoami(request) {
-        return client.identity.getUser(await requireToken(request));
+        return resolveSession(await requireToken(request));
     }
     /**
      * The caller's identity, plus the workspace every tenant-scoped route below
@@ -346,7 +417,8 @@ function createConnectHandler(options) {
     /**
      * The store paths a browser may reach through the bridge.
      *
-     * Documents, the key/value store, aggregations and atomic commits.
+     * Documents (one at a time or a batch by id), the key/value store,
+     * aggregations and atomic commits.
      * **`/data-scan/` is deliberately absent**: a scan crosses every tenant, and
      * Connect refuses one made on behalf of a user - but a browser should not be
      * able to *ask*, so the refusal happens here rather than a round trip away.
@@ -356,7 +428,8 @@ function createConnectHandler(options) {
         return (route.startsWith("/data/") ||
             route.startsWith("/kv/") ||
             route.startsWith("/data-aggregate/") ||
-            route === "/data-commit");
+            route === "/data-commit" ||
+            route === "/data-get-many");
     }
     /**
      * Forwards one store call to Connect on behalf of the caller.
@@ -439,7 +512,7 @@ function createConnectHandler(options) {
                     clientId,
                 });
             }
-            return json({ ...(await client.identity.getUser(token)), oneTap: oneTapEndpoints, clientId });
+            return json({ ...(await resolveSessionFresh(token)), oneTap: oneTapEndpoints, clientId });
         },
         "GET /entitlements": async (request) => {
             const { workspaceId } = await requireWorkspace(request);
@@ -850,6 +923,9 @@ function createConnectHandler(options) {
                 });
             }
             const result = await client.workspaces.switch({ workspaceId: body.workspaceId }, { asUser: token });
+            // The old token is retired by the switch; its cached session names the
+            // workspace just left.
+            sessionCache.delete(token);
             // The response is built first so `session.write` has something to set
             // cookies on, matching how `/callback` does it.
             const response = json({
@@ -1502,6 +1578,8 @@ function createConnectHandler(options) {
         },
         "POST /logout": async (request) => {
             const token = await session.read(request);
+            if (token)
+                sessionCache.delete(token);
             const response = json({ ok: true });
             await session.clear?.(request, response);
             // Connect is told last, and a failure is swallowed: the user's own

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

@@ -104,6 +104,18 @@ class CallsResource {
             headers: (0, acting_as_js_1.actingAs)(input.asUser),
         });
     }
+    /**
+     * Whether the workspace may legally make each kind of call - service or
+     * sales, dialled by a rep or by software - and the steps left on Connect's
+     * calling compliance journey. Send the member to `setupUrl` to finish them.
+     */
+    getCallingReadiness(input) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: "/calling/readiness",
+            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/cjs/server/resources/data.js

@@ -60,6 +60,36 @@ class DataResource {
             headers: (0, acting_as_js_1.actingAs)(input.asUser),
         });
     }
+    /**
+     * Reads up to 200 documents of one collection by id, in **one request** -
+     * the batch form of `get`.
+     *
+     * Reach for it wherever you would loop over `get`: the contacts on a page of
+     * deals, the plans behind a list of subscriptions. It is gated exactly like
+     * `get` and spends one request of your rate limit however many ids it names.
+     *
+     * ```ts
+     * const { items } = await connect.data.getMany({
+     *   workspaceId,
+     *   collection: "contacts",
+     *   ids: deals.map((deal) => deal.data.contactId as string),
+     * });
+     * // items[i] belongs to ids[i]; null where that contact no longer exists.
+     * ```
+     *
+     * Answers positionally, `null` where a document does not exist - unlike
+     * `get`, a missing document does not throw.
+     */
+    getMany(input) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/data-get-many",
+            headers: (0, acting_as_js_1.actingAs)(input.asUser),
+            // A POST that writes nothing: two hundred ids do not fit in a URL.
+            idempotent: true,
+            json: { workspaceId: input.workspaceId, collection: input.collection, ids: input.ids },
+        });
+    }
     /**
      * Lists a collection, one page at a time.
      *
@@ -341,11 +371,12 @@ function isConflict(error) {
  * a round trip away.
  */
 /**
- * The store paths a browser may reach through the bridge: documents, the
- * key/value store, aggregations, and atomic commits. Anchored, so a path like
- * `/data-scan/tickets` cannot slip through on a prefix match.
+ * The store paths a browser may reach through the bridge: documents (singly or
+ * a batch by id), the key/value store, aggregations, and atomic commits.
+ * Anchored, so a path like `/data-scan/tickets` cannot slip through on a
+ * prefix match.
  */
-const STORE_PATHS = /^\/(?:data|kv|data-aggregate)\/|^\/data-commit$/;
+const STORE_PATHS = /^\/(?:data|kv|data-aggregate)\/|^\/data-commit$|^\/data-get-many$/;
 // `async` so the refusal below arrives as a rejected promise rather than a
 // synchronous throw. A function typed `Promise<Response>` that sometimes
 // throws before returning one is the kind of thing a caller's `.catch()`

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

package/dist/esm/server/handler.js

@@ -2,6 +2,14 @@ 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"];
+/**
+ * The bridge's default session reuse window - the longest a revoked session,
+ * a removed member or a sign-out on another device keeps working through a
+ * warm instance. Seconds on purpose: this gates a person's access.
+ */
+export const SESSION_CACHE_TTL_MS = 15_000;
+/** Sessions held per handler. Least recently used falls out first. */
+const SESSION_CACHE_MAX = 5_000;
 /**
  * A sentinel origin to resolve a candidate destination against. Never reached -
  * `.invalid` is reserved by RFC 2606 precisely so it cannot resolve.
@@ -307,9 +315,71 @@ export function createConnectHandler(options) {
         }
         return token;
     }
+    /**
+     * Resolved sessions, per session token, for `SESSION_CACHE_TTL_MS`.
+     *
+     * Every tenant-scoped route starts by asking Connect who the caller is, and
+     * a page load fires several of them at once - so uncached, the bridge made
+     * one `/sso/user` round trip per browser request, and a partner's Connect
+     * traffic grew with their users times their routes. A resolved session is
+     * kept per token for a few seconds instead, the same trade
+     * `crmSession` makes in the reference CRM:
+     *
+     * - **Staleness is bounded and small.** A revoked session, a removed member
+     *   or a reduced role keeps working here for at most the TTL.
+     * - **Signing out is still immediate.** The cache is keyed by the token the
+     *   partner's session store hands back; `/logout` drops the entry, and once
+     *   the cookie is gone there is no token to look up.
+     * - **`GET /session` always reads through.** It is what the browser re-reads
+     *   after a hand-off (a plan bought in a popup, a profile edit), so it must
+     *   see the change at once; it refreshes the entry for everyone after it.
+     *
+     * The promise is cached rather than the value, so a burst of parallel
+     * requests on a cold token makes one round trip, and a failed lookup is
+     * dropped at once - a refusal is never remembered.
+     *
+     * Per handler and in process, timed on `performance.now()` (a monotonic
+     * clock cannot jump when the system clock is corrected).
+     */
+    const sessionCacheTtlMs = Math.max(0, options.sessionCacheTtlMs ?? SESSION_CACHE_TTL_MS);
+    const sessionCache = new Map();
+    function rememberSession(token, session) {
+        if (sessionCacheTtlMs === 0)
+            return session;
+        sessionCache.delete(token);
+        while (sessionCache.size >= SESSION_CACHE_MAX) {
+            const oldest = sessionCache.keys().next();
+            if (oldest.done)
+                break;
+            sessionCache.delete(oldest.value);
+        }
+        const entry = { session, until: performance.now() + sessionCacheTtlMs };
+        sessionCache.set(token, entry);
+        session.catch(() => {
+            // Only the entry this lookup created - a newer one for the same token
+            // must survive an older lookup failing late.
+            if (sessionCache.get(token) === entry)
+                sessionCache.delete(token);
+        });
+        return session;
+    }
+    /** A fresh read from Connect, which then answers the cached routes too. */
+    function resolveSessionFresh(token) {
+        return rememberSession(token, client.identity.getUser(token));
+    }
+    function resolveSession(token) {
+        const hit = sessionCache.get(token);
+        if (hit && hit.until > performance.now()) {
+            // Re-inserted so the map's order tracks recency.
+            sessionCache.delete(token);
+            sessionCache.set(token, hit);
+            return hit.session;
+        }
+        return resolveSessionFresh(token);
+    }
     /** Signed-in identity plus the workspace it belongs to - the first read every other route needs. */
     async function whoami(request) {
-        return client.identity.getUser(await requireToken(request));
+        return resolveSession(await requireToken(request));
     }
     /**
      * The caller's identity, plus the workspace every tenant-scoped route below
@@ -343,7 +413,8 @@ export function createConnectHandler(options) {
     /**
      * The store paths a browser may reach through the bridge.
      *
-     * Documents, the key/value store, aggregations and atomic commits.
+     * Documents (one at a time or a batch by id), the key/value store,
+     * aggregations and atomic commits.
      * **`/data-scan/` is deliberately absent**: a scan crosses every tenant, and
      * Connect refuses one made on behalf of a user - but a browser should not be
      * able to *ask*, so the refusal happens here rather than a round trip away.
@@ -353,7 +424,8 @@ export function createConnectHandler(options) {
         return (route.startsWith("/data/") ||
             route.startsWith("/kv/") ||
             route.startsWith("/data-aggregate/") ||
-            route === "/data-commit");
+            route === "/data-commit" ||
+            route === "/data-get-many");
     }
     /**
      * Forwards one store call to Connect on behalf of the caller.
@@ -436,7 +508,7 @@ export function createConnectHandler(options) {
                     clientId,
                 });
             }
-            return json({ ...(await client.identity.getUser(token)), oneTap: oneTapEndpoints, clientId });
+            return json({ ...(await resolveSessionFresh(token)), oneTap: oneTapEndpoints, clientId });
         },
         "GET /entitlements": async (request) => {
             const { workspaceId } = await requireWorkspace(request);
@@ -847,6 +919,9 @@ export function createConnectHandler(options) {
                 });
             }
             const result = await client.workspaces.switch({ workspaceId: body.workspaceId }, { asUser: token });
+            // The old token is retired by the switch; its cached session names the
+            // workspace just left.
+            sessionCache.delete(token);
             // The response is built first so `session.write` has something to set
             // cookies on, matching how `/callback` does it.
             const response = json({
@@ -1499,6 +1574,8 @@ export function createConnectHandler(options) {
         },
         "POST /logout": async (request) => {
             const token = await session.read(request);
+            if (token)
+                sessionCache.delete(token);
             const response = json({ ok: true });
             await session.clear?.(request, response);
             // Connect is told last, and a failure is swallowed: the user's own

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

@@ -101,6 +101,18 @@ export class CallsResource {
             headers: actingAs(input.asUser),
         });
     }
+    /**
+     * Whether the workspace may legally make each kind of call - service or
+     * sales, dialled by a rep or by software - and the steps left on Connect's
+     * calling compliance journey. Send the member to `setupUrl` to finish them.
+     */
+    getCallingReadiness(input) {
+        return request(this.transport, {
+            method: "GET",
+            path: "/calling/readiness",
+            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/esm/server/resources/data.js

@@ -56,6 +56,36 @@ export class DataResource {
             headers: actingAs(input.asUser),
         });
     }
+    /**
+     * Reads up to 200 documents of one collection by id, in **one request** -
+     * the batch form of `get`.
+     *
+     * Reach for it wherever you would loop over `get`: the contacts on a page of
+     * deals, the plans behind a list of subscriptions. It is gated exactly like
+     * `get` and spends one request of your rate limit however many ids it names.
+     *
+     * ```ts
+     * const { items } = await connect.data.getMany({
+     *   workspaceId,
+     *   collection: "contacts",
+     *   ids: deals.map((deal) => deal.data.contactId as string),
+     * });
+     * // items[i] belongs to ids[i]; null where that contact no longer exists.
+     * ```
+     *
+     * Answers positionally, `null` where a document does not exist - unlike
+     * `get`, a missing document does not throw.
+     */
+    getMany(input) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/data-get-many",
+            headers: actingAs(input.asUser),
+            // A POST that writes nothing: two hundred ids do not fit in a URL.
+            idempotent: true,
+            json: { workspaceId: input.workspaceId, collection: input.collection, ids: input.ids },
+        });
+    }
     /**
      * Lists a collection, one page at a time.
      *
@@ -336,11 +366,12 @@ function isConflict(error) {
  * a round trip away.
  */
 /**
- * The store paths a browser may reach through the bridge: documents, the
- * key/value store, aggregations, and atomic commits. Anchored, so a path like
- * `/data-scan/tickets` cannot slip through on a prefix match.
+ * The store paths a browser may reach through the bridge: documents (singly or
+ * a batch by id), the key/value store, aggregations, and atomic commits.
+ * Anchored, so a path like `/data-scan/tickets` cannot slip through on a
+ * prefix match.
  */
-const STORE_PATHS = /^\/(?:data|kv|data-aggregate)\/|^\/data-commit$/;
+const STORE_PATHS = /^\/(?:data|kv|data-aggregate)\/|^\/data-commit$|^\/data-get-many$/;
 // `async` so the refusal below arrives as a rejected promise rather than a
 // synchronous throw. A function typed `Promise<Response>` that sometimes
 // throws before returning one is the kind of thing a caller's `.catch()`

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

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

@@ -39,5 +39,18 @@ export interface ConnectHandlerOptions {
      * if it collides with something you already set.
      */
     stateCookieName?: string;
+    /**
+     * How long, in milliseconds, this handler reuses a resolved session for the
+     * routes that only need to know *whose* request it is. Defaults to
+     * `SESSION_CACHE_TTL_MS` (15 seconds); `0` turns the cache off. See
+     * `createConnectHandler` for exactly what it trades.
+     */
+    sessionCacheTtlMs?: number;
 }
+/**
+ * The bridge's default session reuse window - the longest a revoked session,
+ * a removed member or a sign-out on another device keeps working through a
+ * warm instance. Seconds on purpose: this gates a person's access.
+ */
+export declare const SESSION_CACHE_TTL_MS = 15000;
 export declare function createConnectHandler(options: ConnectHandlerOptions): (request: Request) => Promise<Response>;

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, ConnectCallPurpose, StartedBrowserCall } from "../../types.js";
+import type { BrowserCallingToken, CallingAvailability, CallSettings, CallingReadiness, 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;
@@ -75,6 +75,14 @@ export declare class CallsResource {
         recordingEnabled: boolean;
         asUser: string;
     }): Promise<CallSettings>;
+    /**
+     * Whether the workspace may legally make each kind of call - service or
+     * sales, dialled by a rep or by software - and the steps left on Connect's
+     * calling compliance journey. Send the member to `setupUrl` to finish them.
+     */
+    getCallingReadiness(input: {
+        asUser: string;
+    }): Promise<CallingReadiness>;
     /** A carrier token the member's browser signs in to the phone network with. */
     getBrowserCallingToken(input: {
         asUser: string;

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

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { StoreAggregatePage, StoreAggregation, StoreCommitOperation, StoreCommitResult, StoreDocument, StoreQueryFilter, StoreQueryPage, StoreOrderBy, StoreScanPage } from "../../types.js";
+import type { StoreAggregatePage, StoreAggregation, StoreCommitOperation, StoreCommitResult, StoreDocument, StoreGetManyResult, StoreQueryFilter, StoreQueryPage, StoreOrderBy, StoreScanPage } from "../../types.js";
 /**
  * Your application's own document store - a dedicated Firestore database that
  * only Connect can reach.
@@ -51,6 +51,32 @@ export declare class DataResource {
         id: string;
         asUser?: string;
     }): Promise<StoreDocument>;
+    /**
+     * Reads up to 200 documents of one collection by id, in **one request** -
+     * the batch form of `get`.
+     *
+     * Reach for it wherever you would loop over `get`: the contacts on a page of
+     * deals, the plans behind a list of subscriptions. It is gated exactly like
+     * `get` and spends one request of your rate limit however many ids it names.
+     *
+     * ```ts
+     * const { items } = await connect.data.getMany({
+     *   workspaceId,
+     *   collection: "contacts",
+     *   ids: deals.map((deal) => deal.data.contactId as string),
+     * });
+     * // items[i] belongs to ids[i]; null where that contact no longer exists.
+     * ```
+     *
+     * Answers positionally, `null` where a document does not exist - unlike
+     * `get`, a missing document does not throw.
+     */
+    getMany(input: {
+        workspaceId?: string;
+        collection: string;
+        ids: string[];
+        asUser?: string;
+    }): Promise<StoreGetManyResult>;
     /**
      * Lists a collection, one page at a time.
      *

package/dist/types/types.d.ts

@@ -1786,6 +1786,14 @@ export interface StoreCommitResult {
     /** The document id each operation wrote, positionally aligned with the operations sent. */
     ids: string[];
 }
+/** What `data.getMany` answers - see `POST /data-get-many`. */
+export interface StoreGetManyResult {
+    /**
+     * Positionally aligned with the ids asked for, `null` where a document does
+     * not exist. A missing document is an ordinary answer here, not a 404.
+     */
+    items: Array<StoreDocument | null>;
+}
 /** One entry from the `kv` store. */
 export interface KvEntry {
     key: string;
@@ -2951,6 +2959,45 @@ export interface CallSettings {
     /** Whether this member may change it - their `channel:manage`. Draw the switch disabled when not. */
     canManage: boolean;
 }
+/** A step of Connect's calling compliance journey - `connect.calls.getCallingReadiness()`. */
+export interface CallingReadinessStep {
+    key: "intent" | "business" | "number" | "header" | "autodialer" | "consent" | "rules";
+    label: string;
+    status: "not_started" | "submitted" | "returned" | "done";
+    /** Whether the business needs it for the calls it said it makes. */
+    required: boolean;
+    /** A returned step's reason, or what the numbers say. */
+    note: string | null;
+}
+/** One kind of calling, and whether the workspace may run it today. */
+export interface CallingReadinessRun {
+    /** `service` covers existing customers; `promotional` is any sales call. */
+    purpose: "service" | "promotional";
+    /** `preview`: a rep presses dial. `automatic`: software paces the dialing. */
+    mode: "preview" | "automatic";
+    allowed: boolean;
+    /** The first thing in the way, worded for the member. `null` when allowed. */
+    reason: string | null;
+}
+/**
+ * Where the workspace stands on the steps Indian telecom rules ask of a
+ * business before it calls - `connect.calls.getCallingReadiness()`. Read
+ * `runs`, not `steps`, to decide what to offer: Connect evaluates them with
+ * the gates the dialer refuses on.
+ */
+export interface CallingReadiness {
+    intent: "service_only" | "service_and_sales" | null;
+    progress: {
+        done: number;
+        required: number;
+    };
+    steps: CallingReadinessStep[];
+    runs: CallingReadinessRun[];
+    /** Connect's journey screen, carrying your `client_id` when SSO is on. */
+    setupUrl: string;
+    /** Whether this member may take the steps - their `channel:manage`. */
+    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.48.0",
+  "version": "0.49.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",