@cosmoops/connect-sdk 0.47.0 → 0.49.0

package/CHANGELOG.md

@@ -3,6 +3,37 @@
 `@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
+
+`<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.49.0";

package/dist/cjs/server/handler.js

@@ -1,8 +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.
@@ -308,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
@@ -344,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.
@@ -354,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.
@@ -437,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);
@@ -848,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({
@@ -1260,7 +1338,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);
@@ -1497,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, {
@@ -118,13 +130,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/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/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.49.0";

package/dist/esm/server/handler.js

@@ -1,5 +1,15 @@
 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.
@@ -305,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
@@ -341,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.
@@ -351,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.
@@ -434,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);
@@ -845,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({
@@ -1257,7 +1334,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);
@@ -1494,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, {
@@ -115,13 +127,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/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/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.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, 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;
@@ -84,11 +92,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/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;
@@ -2911,6 +2919,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. */
@@ -2943,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.47.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",