@cosmoops/connect-sdk 0.48.0 → 0.50.0

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.50.0
+
+### Background tasks
+
+`connect.tasks.enqueue({ workspaceId, queue, payload, name?, scheduleAt? })`
+puts a task on one of your application's Cloud Tasks queues, declared in
+Console (scope `tasks:write`). Cloud Tasks delivers `{ workspaceId, queue,
+payload }` to the queue's URL with a Google-signed OIDC token;
+`createConnectTaskHandler({ handle })` - or `verifyConnectTask(request)` -
+from `./server` or `./next` verifies it. Set `CONNECT_TASK_INVOKER` to the
+invoker account the platform gives you. `name` dedups per workspace;
+`status: "unavailable"` means the Connect deployment has no queue, so keep a
+fallback. Additive; nothing else changed.
+
+## 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/client/components/plans.js

@@ -140,7 +140,7 @@ function ConnectPlans({ planIds, hideCoupon = false, className }) {
                                                 // card used to do. The description rides along as a
                                                 // title so a feature that needs explaining can have one
                                                 // without a second line in every card.
-                                                (0, jsx_runtime_1.jsxs)("li", { className: "flex items-start gap-2 text-sm text-foreground", title: feature.description || undefined, children: [(0, jsx_runtime_1.jsx)(lucide_react_1.Check, { className: "mt-0.5 size-4 shrink-0 text-accent", "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)("span", { children: feature.name })] }, feature.key))) })), plan.addons.length > 0 && ((0, jsx_runtime_1.jsxs)("div", { className: "flex flex-col gap-1.5 border-t border-separator pt-3", children: [(0, jsx_runtime_1.jsx)("p", { className: "text-xs font-medium uppercase tracking-wide text-muted", children: "Add-ons" }), plan.addons.map((addon) => ((0, jsx_runtime_1.jsxs)("div", { className: "flex items-baseline justify-between gap-2 text-sm", children: [(0, jsx_runtime_1.jsxs)("span", { className: "text-foreground", children: [addon.name, addon.consumable && ((0, jsx_runtime_1.jsxs)("span", { className: "text-muted", children: [" ", "- ", addon.consumable.includedPerCycle.toLocaleString("en-IN"), " ", addon.consumable.unit, "/cycle"] }))] }), (0, jsx_runtime_1.jsx)("span", { className: "shrink-0 text-muted", children: (0, plan_pricing_js_1.formatPrice)(addon.price) })] }, addon.id)))] })), (0, jsx_runtime_1.jsxs)("p", { className: "text-xs text-muted", children: [plan.seats.model === "unlimited" && "Unlimited seats", plan.seats.model === "fixed" && `${plan.seats.included} seats included`, plan.seats.model === "per-seat" &&
+                                                (0, jsx_runtime_1.jsxs)("li", { className: "flex items-start gap-2 text-sm text-foreground", title: feature.description || undefined, children: [(0, jsx_runtime_1.jsx)(lucide_react_1.Check, { className: "mt-0.5 size-4 shrink-0 text-accent", "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)("span", { children: feature.name })] }, feature.key))) })), plan.addons.length > 0 && ((0, jsx_runtime_1.jsxs)("div", { className: "flex flex-col gap-1.5 border-t border-separator pt-3", children: [(0, jsx_runtime_1.jsx)("p", { className: "text-xs font-medium uppercase tracking-wide text-muted", children: "Add-ons" }), plan.addons.map((addon) => ((0, jsx_runtime_1.jsxs)("div", { className: "flex items-baseline justify-between gap-2 text-sm", children: [(0, jsx_runtime_1.jsxs)("span", { className: "text-foreground", children: [addon.name, addon.consumable && ((0, jsx_runtime_1.jsxs)("span", { className: "text-muted", children: [" ", "- ", addon.consumable.includedPerCycle.toLocaleString("en-IN"), " ", addon.consumable.unit, "/cycle"] }))] }), (0, jsx_runtime_1.jsxs)("span", { className: "shrink-0 text-muted", children: [(0, plan_pricing_js_1.formatPrice)(addon.price), addon.billingCadence === "annual" && "/year"] })] }, addon.id)))] })), (0, jsx_runtime_1.jsxs)("p", { className: "text-xs text-muted", children: [plan.seats.model === "unlimited" && "Unlimited seats", plan.seats.model === "fixed" && `${plan.seats.included} seats included`, plan.seats.model === "per-seat" &&
                                                         `${plan.seats.included ?? 0} seats included, then ${(0, plan_pricing_js_1.formatPrice)(plan.seats.pricePerExtraSeat ?? 0)} each`] })] }), (0, jsx_runtime_1.jsx)(react_1.Card.Footer, { children: (0, jsx_runtime_1.jsxs)(react_1.Button, { className: "w-full", variant: action === "upgrade" || action === "subscribe" || action === "switch-to-annual"
                                                 ? "primary"
                                                 : "secondary", 

package/dist/cjs/next/index.js

@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConnectClient = exports.createConnectHandler = void 0;
+exports.ConnectTaskVerificationError = exports.createConnectTaskHandler = exports.verifyConnectTask = exports.ConnectClient = exports.createConnectHandler = void 0;
 exports.connectClient = connectClient;
 exports.connectProviderProps = connectProviderProps;
 exports.cookieSessionStore = cookieSessionStore;
@@ -486,3 +486,7 @@ var handler_js_2 = require("../server/handler.js");
 Object.defineProperty(exports, "createConnectHandler", { enumerable: true, get: function () { return handler_js_2.createConnectHandler; } });
 var client_js_2 = require("../server/client.js");
 Object.defineProperty(exports, "ConnectClient", { enumerable: true, get: function () { return client_js_2.ConnectClient; } });
+var tasks_js_1 = require("../server/tasks.js");
+Object.defineProperty(exports, "verifyConnectTask", { enumerable: true, get: function () { return tasks_js_1.verifyConnectTask; } });
+Object.defineProperty(exports, "createConnectTaskHandler", { enumerable: true, get: function () { return tasks_js_1.createConnectTaskHandler; } });
+Object.defineProperty(exports, "ConnectTaskVerificationError", { enumerable: true, get: function () { return tasks_js_1.ConnectTaskVerificationError; } });

package/dist/cjs/server/client.js

@@ -25,6 +25,7 @@ const sessions_js_1 = require("./resources/sessions.js");
 const platform_js_1 = require("./resources/platform.js");
 const visitor_js_1 = require("./resources/visitor.js");
 const push_js_1 = require("./resources/push.js");
+const tasks_js_1 = require("./resources/tasks.js");
 const whatsapp_js_1 = require("./resources/whatsapp.js");
 exports.DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 const APPLICATION_API_PREFIX = "/api/v1/application";
@@ -129,6 +130,8 @@ class ConnectClient {
      * preferences; you supply a title, a body and a URL. See `PushResource`.
      */
     push;
+    /** Background tasks on this application's declared Cloud Tasks queues - see `TasksResource`. */
+    tasks;
     /** Your application's own approved WhatsApp templates, to a workspace's customers. */
     whatsapp;
     /**
@@ -177,10 +180,11 @@ class ConnectClient {
         this.visitor = new visitor_js_1.VisitorResource(transport);
         this.platform = new platform_js_1.PlatformResource(transport);
         this.push = new push_js_1.PushResource(transport);
+        this.tasks = new tasks_js_1.TasksResource(transport);
         this.whatsapp = new whatsapp_js_1.WhatsAppResource(transport);
         this.storeRelay = (spec) => (0, data_js_1.storePassthrough)(transport, spec);
     }
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.48.0";
+exports.SDK_VERSION = "0.50.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/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifyConnectWebhook = exports.createConnectWebhookHandler = exports.createState = exports.createConnectHandler = exports.SDK_VERSION = exports.DEFAULT_BASE_URL = exports.ConnectClient = void 0;
+exports.ConnectTaskVerificationError = exports.createConnectTaskHandler = exports.verifyConnectTask = exports.verifyConnectWebhook = exports.createConnectWebhookHandler = exports.createState = exports.createConnectHandler = exports.SDK_VERSION = exports.DEFAULT_BASE_URL = exports.ConnectClient = void 0;
 /**
  * Server-only half of `@cosmoops/connect-sdk`.
  *
@@ -23,3 +23,11 @@ Object.defineProperty(exports, "createState", { enumerable: true, get: function
 var webhooks_js_1 = require("./webhooks.js");
 Object.defineProperty(exports, "createConnectWebhookHandler", { enumerable: true, get: function () { return webhooks_js_1.createConnectWebhookHandler; } });
 Object.defineProperty(exports, "verifyConnectWebhook", { enumerable: true, get: function () { return webhooks_js_1.verifyConnectWebhook; } });
+/**
+ * Receiving a Connect task - verify Google's OIDC token, then run. See
+ * `TasksResource` for the sending half.
+ */
+var tasks_js_1 = require("./tasks.js");
+Object.defineProperty(exports, "verifyConnectTask", { enumerable: true, get: function () { return tasks_js_1.verifyConnectTask; } });
+Object.defineProperty(exports, "createConnectTaskHandler", { enumerable: true, get: function () { return tasks_js_1.createConnectTaskHandler; } });
+Object.defineProperty(exports, "ConnectTaskVerificationError", { enumerable: true, get: function () { return tasks_js_1.ConnectTaskVerificationError; } });

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

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TasksResource = void 0;
+const http_js_1 = require("../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.
+ */
+class TasksResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    enqueue(input) {
+        return (0, http_js_1.request)(this.transport, { method: "POST", path: "/tasks", json: input });
+    }
+}
+exports.TasksResource = TasksResource;

package/dist/cjs/server/tasks.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectTaskVerificationError = void 0;
+exports.clearConnectTaskKeyCache = clearConnectTaskKeyCache;
+exports.verifyConnectTask = verifyConnectTask;
+exports.createConnectTaskHandler = createConnectTaskHandler;
+/**
+ * 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;
+class ConnectTaskVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConnectTaskVerificationError";
+    }
+}
+exports.ConnectTaskVerificationError = ConnectTaskVerificationError;
+let certsCache = null;
+/** Test seam - drops the cached Google keys. */
+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.
+ */
+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.
+ */
+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/esm/client/components/plans.js

@@ -137,7 +137,7 @@ export function ConnectPlans({ planIds, hideCoupon = false, className }) {
                                                 // card used to do. The description rides along as a
                                                 // title so a feature that needs explaining can have one
                                                 // without a second line in every card.
-                                                _jsxs("li", { className: "flex items-start gap-2 text-sm text-foreground", title: feature.description || undefined, children: [_jsx(Check, { className: "mt-0.5 size-4 shrink-0 text-accent", "aria-hidden": "true" }), _jsx("span", { children: feature.name })] }, feature.key))) })), plan.addons.length > 0 && (_jsxs("div", { className: "flex flex-col gap-1.5 border-t border-separator pt-3", children: [_jsx("p", { className: "text-xs font-medium uppercase tracking-wide text-muted", children: "Add-ons" }), plan.addons.map((addon) => (_jsxs("div", { className: "flex items-baseline justify-between gap-2 text-sm", children: [_jsxs("span", { className: "text-foreground", children: [addon.name, addon.consumable && (_jsxs("span", { className: "text-muted", children: [" ", "- ", addon.consumable.includedPerCycle.toLocaleString("en-IN"), " ", addon.consumable.unit, "/cycle"] }))] }), _jsx("span", { className: "shrink-0 text-muted", children: formatPrice(addon.price) })] }, addon.id)))] })), _jsxs("p", { className: "text-xs text-muted", children: [plan.seats.model === "unlimited" && "Unlimited seats", plan.seats.model === "fixed" && `${plan.seats.included} seats included`, plan.seats.model === "per-seat" &&
+                                                _jsxs("li", { className: "flex items-start gap-2 text-sm text-foreground", title: feature.description || undefined, children: [_jsx(Check, { className: "mt-0.5 size-4 shrink-0 text-accent", "aria-hidden": "true" }), _jsx("span", { children: feature.name })] }, feature.key))) })), plan.addons.length > 0 && (_jsxs("div", { className: "flex flex-col gap-1.5 border-t border-separator pt-3", children: [_jsx("p", { className: "text-xs font-medium uppercase tracking-wide text-muted", children: "Add-ons" }), plan.addons.map((addon) => (_jsxs("div", { className: "flex items-baseline justify-between gap-2 text-sm", children: [_jsxs("span", { className: "text-foreground", children: [addon.name, addon.consumable && (_jsxs("span", { className: "text-muted", children: [" ", "- ", addon.consumable.includedPerCycle.toLocaleString("en-IN"), " ", addon.consumable.unit, "/cycle"] }))] }), _jsxs("span", { className: "shrink-0 text-muted", children: [formatPrice(addon.price), addon.billingCadence === "annual" && "/year"] })] }, addon.id)))] })), _jsxs("p", { className: "text-xs text-muted", children: [plan.seats.model === "unlimited" && "Unlimited seats", plan.seats.model === "fixed" && `${plan.seats.included} seats included`, plan.seats.model === "per-seat" &&
                                                         `${plan.seats.included ?? 0} seats included, then ${formatPrice(plan.seats.pricePerExtraSeat ?? 0)} each`] })] }), _jsx(Card.Footer, { children: _jsxs(Button, { className: "w-full", variant: action === "upgrade" || action === "subscribe" || action === "switch-to-annual"
                                                 ? "primary"
                                                 : "secondary", 

package/dist/esm/next/index.js

@@ -452,3 +452,4 @@ async function redirectTo(url) {
 }
 export { createConnectHandler } from "../server/handler.js";
 export { ConnectClient } from "../server/client.js";
+export { verifyConnectTask, createConnectTaskHandler, ConnectTaskVerificationError } from "../server/tasks.js";

package/dist/esm/server/client.js

@@ -22,6 +22,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 const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 const APPLICATION_API_PREFIX = "/api/v1/application";
@@ -126,6 +127,8 @@ export class ConnectClient {
      * preferences; you supply a title, a body and a URL. See `PushResource`.
      */
     push;
+    /** Background tasks on this application's declared Cloud Tasks queues - see `TasksResource`. */
+    tasks;
     /** Your application's own approved WhatsApp templates, to a workspace's customers. */
     whatsapp;
     /**
@@ -174,9 +177,10 @@ export class ConnectClient {
         this.visitor = new VisitorResource(transport);
         this.platform = new PlatformResource(transport);
         this.push = new PushResource(transport);
+        this.tasks = new TasksResource(transport);
         this.whatsapp = new WhatsAppResource(transport);
         this.storeRelay = (spec) => storePassthrough(transport, spec);
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.48.0";
+export const SDK_VERSION = "0.50.0";