@cosmoops/connect-sdk 0.49.0 → 0.50.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 `@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

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.49.0";
+exports.SDK_VERSION = "0.50.0";

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/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.49.0";
+export const SDK_VERSION = "0.50.0";

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/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.49.0";
+export declare const SDK_VERSION = "0.50.0";

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/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>;

package/dist/types/types.d.ts

@@ -267,9 +267,16 @@ export interface PlanAddonConsumable {
 export interface PlanAddon {
     id: string;
     name: string;
-    /** GST-exclusive, in paise. */
+    /** GST-exclusive, in paise. Per plan cycle, or per year when `billingCadence` is `"annual"`. */
     price: number;
     consumable?: PlanAddonConsumable | null;
+    /**
+     * When the add-on is billed. `"annual"` = once on the first cycle that holds
+     * it, then on each anniversary - on a monthly plan too - so render its price
+     * as "/year". `"plan"` (or absent, from a Connect that predates the field) =
+     * every plan cycle, as before.
+     */
+    billingCadence?: "plan" | "annual" | null;
 }
 /**
  * A plan feature with its label, as the **catalogue** read reports it.
@@ -3237,3 +3244,43 @@ export interface RegisterPushDeviceResponse {
     /** Hand this to `revokeDevice` to turn the same browser off again. */
     id: string;
 }
+/**
+ * One task, onto one of this application's declared task queues, for one
+ * workspace it serves. Hand-written like every wire type here;
+ * `conformance.test.ts` holds it to `EnqueueApplicationTaskInputSchema`.
+ */
+export interface EnqueueTaskInput {
+    workspaceId: string;
+    /** A queue declared for this application in Console. */
+    queue: string;
+    /** Any JSON. Delivered back as `payload`. Keep it to ids - 100 KB at most. */
+    payload?: unknown;
+    /**
+     * A dedup key. A second enqueue with the same name for the same workspace
+     * answers `duplicate` and queues nothing - name a self-chaining step after
+     * the step (`campaign-42-page-3`) so two runners cannot both queue it.
+     */
+    name?: string;
+    /** ISO-8601, at most 30 days ahead. Omit to run as soon as the queue's rate allows. */
+    scheduleAt?: string;
+}
+export interface EnqueueTaskResponse {
+    /**
+     * `unavailable` means this Connect deployment has no task queue (local
+     * development). Nothing was queued; fall back to whatever you would do
+     * without one.
+     */
+    status: "queued" | "duplicate" | "unavailable";
+    scheduleAt: string | null;
+}
+/** What Cloud Tasks POSTs to a queue's URL - and what `verifyConnectTask` returns. */
+export interface ConnectTaskDelivery<TPayload = unknown> {
+    /** The workspace the enqueue was gated on - trust this, not anything in `payload`. */
+    workspaceId: string;
+    queue: string;
+    payload: TPayload;
+    /** From Cloud Tasks' own headers: 0 on the first attempt. */
+    retryCount: number;
+    /** Cloud Tasks' task id, stable across retries. */
+    taskName: string | null;
+}

package/package.json

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