@cosmoops/connect-sdk 0.48.0 → 0.50.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/index.js

@@ -13,3 +13,8 @@ export { createState } from "./resources/identity.js";
  * obvious reason: the signing secret must never reach a browser bundle.
  */
 export { createConnectWebhookHandler, verifyConnectWebhook, } from "./webhooks.js";
+/**
+ * Receiving a Connect task - verify Google's OIDC token, then run. See
+ * `TasksResource` for the sending half.
+ */
+export { verifyConnectTask, createConnectTaskHandler, ConnectTaskVerificationError, } from "./tasks.js";

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/esm/server/resources/tasks.js

@@ -0,0 +1,22 @@
+import { request } from "../http.js";
+/**
+ * Background work, delivered back to your own endpoint by Google Cloud Tasks.
+ *
+ * Declare a queue in Console - its URL, its rate, its retries - then enqueue
+ * here. Cloud Tasks `POST`s `{ workspaceId, queue, payload }` to the queue's
+ * URL with a Google-signed OIDC token; verify it with `verifyConnectTask` (or
+ * let `createConnectTaskHandler` do it) before trusting a byte of the body.
+ *
+ * Deliveries are **at least once**. Make each step safe to run twice, and
+ * give each enqueue a `name` derived from the step so a retried enqueue is a
+ * `duplicate` rather than a second task.
+ */
+export class TasksResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    enqueue(input) {
+        return request(this.transport, { method: "POST", path: "/tasks", json: input });
+    }
+}

package/dist/esm/server/tasks.js

@@ -0,0 +1,168 @@
+/**
+ * Receiving a task Connect enqueued: verify, then run.
+ *
+ * Cloud Tasks calls your queue's URL directly - not through Connect - with a
+ * bearer **OIDC token Google signs** for Connect's invoker service account.
+ * Three claims make a request a genuine delivery, and all three are needed:
+ *
+ * - the signature, against Google's published keys - or anyone can mint one;
+ * - `email`, the invoker account - or any Google-signed token for any
+ *   service account, including one an attacker owns, would pass;
+ * - `aud`, your own origin - or a token minted for somebody else's endpoint
+ *   could be replayed against yours.
+ *
+ * Checked with WebCrypto, so this needs no JWT library and runs on Node and
+ * on edge runtimes alike.
+ */
+const GOOGLE_CERTS_URL = "https://www.googleapis.com/oauth2/v3/certs";
+const GOOGLE_ISSUERS = new Set(["https://accounts.google.com", "accounts.google.com"]);
+/** Clock skew tolerated between Google and this server. */
+const SKEW_MS = 60_000;
+const DEFAULT_CERTS_TTL_MS = 60 * 60 * 1000;
+export class ConnectTaskVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConnectTaskVerificationError";
+    }
+}
+let certsCache = null;
+/** Test seam - drops the cached Google keys. */
+export function clearConnectTaskKeyCache() {
+    certsCache = null;
+}
+async function googleKeys(fetchImpl, now, force) {
+    if (!force && certsCache && certsCache.expiresAt > now)
+        return certsCache.keys;
+    const response = await fetchImpl(GOOGLE_CERTS_URL, { method: "GET" });
+    if (!response.ok)
+        throw new ConnectTaskVerificationError(`Could not fetch Google's signing keys (${response.status}).`);
+    const body = (await response.json());
+    const maxAge = /max-age=(\d+)/.exec(response.headers.get("cache-control") ?? "")?.[1];
+    certsCache = {
+        keys: body.keys ?? [],
+        expiresAt: now + (maxAge ? Number(maxAge) * 1000 : DEFAULT_CERTS_TTL_MS),
+    };
+    return certsCache.keys;
+}
+function base64UrlToBytes(segment) {
+    const base64 = segment.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(segment.length / 4) * 4, "=");
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+function decodeSegment(segment) {
+    try {
+        return JSON.parse(new TextDecoder().decode(base64UrlToBytes(segment)));
+    }
+    catch {
+        throw new ConnectTaskVerificationError("The token is not a JWT.");
+    }
+}
+/**
+ * Verify a delivery and return it, or throw `ConnectTaskVerificationError`.
+ *
+ * Reads the body, so call it once and use what it returns.
+ */
+export async function verifyConnectTask(request, options = {}) {
+    const invoker = options.invoker ?? process.env.CONNECT_TASK_INVOKER;
+    if (!invoker) {
+        throw new ConnectTaskVerificationError("No invoker configured - set CONNECT_TASK_INVOKER to the invoker service account the platform gave you.");
+    }
+    const audience = options.audience ?? process.env.CONNECT_TASK_AUDIENCE ?? new URL(request.url).origin;
+    const fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
+    const now = (options.now ?? Date.now)();
+    const header = request.headers.get("authorization") ?? "";
+    const token = /^Bearer\s+(.+)$/i.exec(header)?.[1];
+    if (!token)
+        throw new ConnectTaskVerificationError("No bearer token.");
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        throw new ConnectTaskVerificationError("The token is not a JWT.");
+    const [headerSegment, claimsSegment, signatureSegment] = parts;
+    const jwtHeader = decodeSegment(headerSegment);
+    if (jwtHeader.alg !== "RS256" || typeof jwtHeader.kid !== "string") {
+        throw new ConnectTaskVerificationError("Unexpected token algorithm.");
+    }
+    // An unknown `kid` is usually a rotation the cache has not seen - refetch once.
+    let jwk = (await googleKeys(fetchImpl, now, false)).find((key) => key.kid === jwtHeader.kid);
+    if (!jwk)
+        jwk = (await googleKeys(fetchImpl, now, true)).find((key) => key.kid === jwtHeader.kid);
+    if (!jwk)
+        throw new ConnectTaskVerificationError("The token was not signed by a current Google key.");
+    const key = await crypto.subtle.importKey("jwk", { kty: jwk.kty, n: jwk.n, e: jwk.e, alg: "RS256", ext: true }, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["verify"]);
+    const valid = await crypto.subtle.verify("RSASSA-PKCS1-v1_5", key, base64UrlToBytes(signatureSegment), new TextEncoder().encode(`${headerSegment}.${claimsSegment}`));
+    if (!valid)
+        throw new ConnectTaskVerificationError("The token's signature does not verify.");
+    const claims = decodeSegment(claimsSegment);
+    if (typeof claims.iss !== "string" || !GOOGLE_ISSUERS.has(claims.iss)) {
+        throw new ConnectTaskVerificationError("The token was not issued by Google.");
+    }
+    if (claims.aud !== audience)
+        throw new ConnectTaskVerificationError("The token was minted for another audience.");
+    if (claims.email !== invoker || claims.email_verified !== true) {
+        throw new ConnectTaskVerificationError("The token is not Connect's invoker.");
+    }
+    if (typeof claims.exp !== "number" || claims.exp * 1000 < now - SKEW_MS) {
+        throw new ConnectTaskVerificationError("The token has expired.");
+    }
+    if (typeof claims.iat === "number" && claims.iat * 1000 > now + SKEW_MS) {
+        throw new ConnectTaskVerificationError("The token is from the future.");
+    }
+    let body;
+    try {
+        body = (await request.json());
+    }
+    catch {
+        throw new ConnectTaskVerificationError("The delivery body is not JSON.");
+    }
+    if (typeof body.workspaceId !== "string" || typeof body.queue !== "string") {
+        throw new ConnectTaskVerificationError("The delivery body is not a Connect task.");
+    }
+    return {
+        workspaceId: body.workspaceId,
+        queue: body.queue,
+        payload: body.payload,
+        retryCount: Number(request.headers.get("x-cloudtasks-taskretrycount") ?? 0) || 0,
+        taskName: request.headers.get("x-cloudtasks-taskname"),
+    };
+}
+/**
+ * A ready-made `POST` route for a queue's URL:
+ *
+ * ```ts
+ * // app/api/tasks/campaign/route.ts
+ * export const POST = createConnectTaskHandler<{ campaignId: string }>({
+ *   handle: async ({ workspaceId, payload }) => runCampaignPage(workspaceId, payload.campaignId),
+ * });
+ * ```
+ *
+ * `401` for anything that does not verify, `500` when `handle` throws (or
+ * Google's keys cannot be fetched), `200` otherwise.
+ */
+export function createConnectTaskHandler(options) {
+    const { handle, ...verifyOptions } = options;
+    return async (request) => {
+        let delivery;
+        try {
+            delivery = await verifyConnectTask(request, verifyOptions);
+        }
+        catch (error) {
+            if (error instanceof ConnectTaskVerificationError) {
+                return Response.json({ error: error.message }, { status: 401 });
+            }
+            // Google's keys unreachable, say - not the sender's fault, so retryable.
+            console.error("[connect-task] could not verify a delivery:", error);
+            return Response.json({ error: "Could not verify the delivery." }, { status: 500 });
+        }
+        try {
+            await handle(delivery);
+        }
+        catch (error) {
+            console.error(`[connect-task] ${delivery.queue} failed (attempt ${delivery.retryCount + 1}):`, error);
+            return Response.json({ error: "Task failed - Cloud Tasks will retry it." }, { status: 500 });
+        }
+        return Response.json({ ok: true });
+    };
+}

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

@@ -237,3 +237,4 @@ export declare function requireConnectSession(request?: Request, options?: {
 export { createConnectHandler } from "../server/handler.js";
 export type { ConnectSessionStore } from "../server/handler.js";
 export { ConnectClient } from "../server/client.js";
+export { verifyConnectTask, createConnectTaskHandler, ConnectTaskVerificationError } from "../server/tasks.js";

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

@@ -23,6 +23,7 @@ import { SessionsResource } from "./resources/sessions.js";
 import { PlatformResource } from "./resources/platform.js";
 import { VisitorResource } from "./resources/visitor.js";
 import { PushResource } from "./resources/push.js";
+import { TasksResource } from "./resources/tasks.js";
 import { WhatsAppResource } from "./resources/whatsapp.js";
 export declare const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 export interface ConnectClientOptions {
@@ -125,6 +126,8 @@ export declare class ConnectClient {
      * preferences; you supply a title, a body and a URL. See `PushResource`.
      */
     readonly push: PushResource;
+    /** Background tasks on this application's declared Cloud Tasks queues - see `TasksResource`. */
+    readonly tasks: TasksResource;
     /** Your application's own approved WhatsApp templates, to a workspace's customers. */
     readonly whatsapp: WhatsAppResource;
     /**
@@ -141,4 +144,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.50.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/index.d.ts

@@ -25,6 +25,7 @@ export type { WorkspacesResource } from "./resources/workspaces.js";
 export type { OtpResource } from "./resources/otp.js";
 export type { LogsResource } from "./resources/logs.js";
 export type { AnalyticsResource } from "./resources/analytics.js";
+export type { TasksResource } from "./resources/tasks.js";
 export type { SessionsResource } from "./resources/sessions.js";
 export type { ExecuteIntegrationActionInput, InitiateIntegrationConnectionInput, IntegrationsResource, ProxyIntegrationRequestInput, } from "./resources/integrations.js";
 export type { PlatformResource } from "./resources/platform.js";
@@ -37,3 +38,9 @@ export type { CallsResource, ListCallsInput } from "./resources/calls.js";
  * obvious reason: the signing secret must never reach a browser bundle.
  */
 export { createConnectWebhookHandler, verifyConnectWebhook, type ConnectWebhookHandlers, type ConnectWebhookHandlerOptions, } from "./webhooks.js";
+/**
+ * Receiving a Connect task - verify Google's OIDC token, then run. See
+ * `TasksResource` for the sending half.
+ */
+export { verifyConnectTask, createConnectTaskHandler, ConnectTaskVerificationError, } from "./tasks.js";
+export type { VerifyConnectTaskOptions, ConnectTaskHandlerOptions } from "./tasks.js";

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/server/resources/tasks.d.ts

@@ -0,0 +1,19 @@
+import { type TransportOptions } from "../http.js";
+import type { EnqueueTaskInput, EnqueueTaskResponse } from "../../types.js";
+/**
+ * Background work, delivered back to your own endpoint by Google Cloud Tasks.
+ *
+ * Declare a queue in Console - its URL, its rate, its retries - then enqueue
+ * here. Cloud Tasks `POST`s `{ workspaceId, queue, payload }` to the queue's
+ * URL with a Google-signed OIDC token; verify it with `verifyConnectTask` (or
+ * let `createConnectTaskHandler` do it) before trusting a byte of the body.
+ *
+ * Deliveries are **at least once**. Make each step safe to run twice, and
+ * give each enqueue a `name` derived from the step so a retried enqueue is a
+ * `duplicate` rather than a second task.
+ */
+export declare class TasksResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    enqueue(input: EnqueueTaskInput): Promise<EnqueueTaskResponse>;
+}

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

@@ -0,0 +1,51 @@
+import type { FetchLike } from "./http.js";
+import type { ConnectTaskDelivery } from "../types.js";
+export declare class ConnectTaskVerificationError extends Error {
+    constructor(message: string);
+}
+export interface VerifyConnectTaskOptions {
+    /**
+     * The invoker service account's email - the one the platform gives you
+     * with your API key. Defaults to `CONNECT_TASK_INVOKER`.
+     */
+    invoker?: string;
+    /**
+     * Your own origin, which Connect sets as the token's audience. Defaults to
+     * `CONNECT_TASK_AUDIENCE`, then to the request URL's origin.
+     */
+    audience?: string;
+    /** Injectable for tests. Defaults to the global `fetch`. */
+    fetch?: FetchLike;
+    /** Injectable for tests. Milliseconds since the epoch. */
+    now?: () => number;
+}
+/** Test seam - drops the cached Google keys. */
+export declare function clearConnectTaskKeyCache(): void;
+/**
+ * Verify a delivery and return it, or throw `ConnectTaskVerificationError`.
+ *
+ * Reads the body, so call it once and use what it returns.
+ */
+export declare function verifyConnectTask<TPayload = unknown>(request: Request, options?: VerifyConnectTaskOptions): Promise<ConnectTaskDelivery<TPayload>>;
+export interface ConnectTaskHandlerOptions<TPayload> extends VerifyConnectTaskOptions {
+    /**
+     * Run one task. Return normally and Cloud Tasks counts it done; **throw**
+     * and it is retried with backoff, up to the queue's declared attempts. A
+     * failure no retry can fix (the record is gone) should return, not throw.
+     */
+    handle: (delivery: ConnectTaskDelivery<TPayload>) => Promise<void> | void;
+}
+/**
+ * A ready-made `POST` route for a queue's URL:
+ *
+ * ```ts
+ * // app/api/tasks/campaign/route.ts
+ * export const POST = createConnectTaskHandler<{ campaignId: string }>({
+ *   handle: async ({ workspaceId, payload }) => runCampaignPage(workspaceId, payload.campaignId),
+ * });
+ * ```
+ *
+ * `401` for anything that does not verify, `500` when `handle` throws (or
+ * Google's keys cannot be fetched), `200` otherwise.
+ */
+export declare function createConnectTaskHandler<TPayload = unknown>(options: ConnectTaskHandlerOptions<TPayload>): (request: Request) => Promise<Response>;