@cosmoops/connect-sdk 0.7.0 → 0.15.0

package/dist/esm/client/use-checkout.js

@@ -152,15 +152,19 @@ export function buildCancelUrl({ appUrl, subscriptionId }) {
  * The Connect URL that completes a subscribe or a plan change.
  *
  * Both land on a modal Connect renders over the relevant page (an intercepted
- * parallel route - `app/@modal/(.)applications/...` and
- * `app/@modal/(.)billing/...`), so the customer arrives already looking at the
- * confirmation for the plan they picked here, not at a catalogue they have to
- * find it in again.
+ * parallel route - `app/@modal/(.)apps/...` and `app/@modal/(.)billing/...`),
+ * so the customer arrives already looking at the confirmation for the plan
+ * they picked here, not at a catalogue they have to find it in again.
+ *
+ * The subscribe path is `/apps/...`, not `/applications/...`: the portal
+ * route customers see is `/apps`, and `/applications` is a Console-only
+ * prefix that has never served this page. Building the other one is what
+ * sent every first-time subscriber from a partner's pricing page to a 404.
  */
 export function buildCheckoutUrl({ appUrl, applicationId, planId, subscriptionId, coupon, }) {
     const path = subscriptionId
         ? `/billing/subscriptions/${encodeURIComponent(subscriptionId)}/change-plan/${encodeURIComponent(planId)}`
-        : `/applications/${encodeURIComponent(applicationId)}/subscribe/${encodeURIComponent(planId)}`;
+        : `/apps/${encodeURIComponent(applicationId)}/subscribe/${encodeURIComponent(planId)}`;
     const url = new URL(path, appUrl);
     if (coupon?.trim())
         url.searchParams.set("coupon", coupon.trim());

package/dist/esm/errors.js

@@ -55,7 +55,7 @@ export class ConnectError extends Error {
      * guessing keys. These two are the exception: reaching them required
      * presenting a key whose hash matched, so you already hold it, and what you
      * need to know is that no retry and no scope change will fix this - the key
-     * has to be reissued from the application's Integration tab.
+     * has to be reissued from the application's Connect client section.
      *
      * Worth alerting on. It is the one failure that will not resolve itself and
      * takes down every call your integration makes.

package/dist/esm/index.js

@@ -13,3 +13,4 @@
  */
 export { ConnectError, isConnectError } from "./errors.js";
 export { blockingBlockers, normalizePlanFeatures } from "./helpers.js";
+export { arrayRemove, arrayUnion, deleteField, documentExists, increment, serverTimestamp, storeIndexFor, storeIndexSignature, unchangedSince, } from "./store.js";

package/dist/esm/next/index.js

@@ -38,7 +38,7 @@ import { createConnectHandler } from "../server/handler.js";
  * | `CONNECT_SESSION_COOKIE` | no | session cookie name |
  *
  * Register `{your origin}/api/connect/callback` as a redirect URI in the
- * application's Integration tab. That is the only step this cannot do for you.
+ * application's Connect client section. That is the only step this cannot do for you.
  *
  * No `next.config.ts` changes needed either, including `transpilePackages`:
  * `dist/` is already ES2022 with `"use client"` hoisted to the top of every
@@ -287,7 +287,7 @@ export async function getConnectSession(request, options = {}) {
  * A thin wrapper, not a framework of its own - reach for `getConnectSession`
  * plus your own check when "not signed in" isn't "redirect to sign-in"
  * (an API route returning 401, say). Role and entitlement checks stay
- * outside this function on purpose: `session.applicationRole.granted` and
+ * outside this function on purpose: `session.permissions` and
  * `connect.entitlements.*` are one line each on top of the session this
  * already gives you, and where that line redirects (a plans page, a
  * "forbidden" screen) is a decision only your app can make - see

package/dist/esm/server/client.js

@@ -1,6 +1,9 @@
 import { AccessResource } from "./resources/access.js";
 import { AppsResource } from "./resources/apps.js";
 import { AiResource } from "./resources/ai.js";
+import { DataResource, storePassthrough } from "./resources/data.js";
+import { WorkspacesResource } from "./resources/workspaces.js";
+import { KvResource } from "./resources/kv.js";
 import { BillingResource } from "./resources/billing.js";
 import { DriveResource } from "./resources/drive.js";
 import { EntitlementsResource } from "./resources/entitlements.js";
@@ -10,6 +13,7 @@ import { LogsResource } from "./resources/logs.js";
 import { AnalyticsResource } from "./resources/analytics.js";
 import { OtpResource } from "./resources/otp.js";
 import { SessionsResource } from "./resources/sessions.js";
+import { PlatformResource } from "./resources/platform.js";
 export const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 const APPLICATION_API_PREFIX = "/api/v1/application";
 /**
@@ -74,6 +78,10 @@ export class ConnectClient {
     drive;
     /** RAG chat and structured extraction. */
     ai;
+    /** Your application's own document store - see `DataResource`. */
+    data;
+    /** Your application's key/value store - see `KvResource`. */
+    kv;
     /** WhatsApp/SMS phone verification. */
     otp;
     /** Feature events into the Console's audit log, filterable to your application. */
@@ -84,10 +92,20 @@ export class ConnectClient {
     sessions;
     /** Composio-hosted third-party connections (Google Calendar, Slack, ...) a workspace has connected. */
     integrations;
+    /** Which workspaces the signed-in user belongs to, switching between them, and the team - see `WorkspacesResource`. */
+    workspaces;
+    /** The platform's own legal identity and DPDP grievance channel - see `PlatformResource`. */
+    platform;
+    /**
+     * Relays one `/data/*` or `/kv/*` request verbatim - `createConnectHandler`'s
+     * store route and nothing else. See `storePassthrough`.
+     * @internal
+     */
+    storeRelay;
     constructor(options) {
         assertNotBrowser();
         if (!options.apiKey) {
-            throw new TypeError("ConnectClient requires `apiKey` - the plaintext shown once in the Integration tab.");
+            throw new TypeError("ConnectClient requires `apiKey` - the plaintext shown once in the Connect client section.");
         }
         const appBaseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
         const transport = {
@@ -107,12 +125,17 @@ export class ConnectClient {
         this.billing = new BillingResource(transport);
         this.drive = new DriveResource(transport);
         this.ai = new AiResource(transport);
+        this.data = new DataResource(transport);
+        this.kv = new KvResource(transport);
         this.otp = new OtpResource(transport);
         this.logs = new LogsResource(transport);
         this.analytics = new AnalyticsResource(transport);
         this.sessions = new SessionsResource(transport, options.clientId ?? null);
         this.integrations = new IntegrationsResource(transport);
+        this.workspaces = new WorkspacesResource(transport);
+        this.platform = new PlatformResource(transport);
+        this.storeRelay = (spec) => storePassthrough(transport, spec);
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.7.0";
+export const SDK_VERSION = "0.14.0";

package/dist/esm/server/handler.js

@@ -164,41 +164,253 @@ export function createConnectHandler(options) {
     async function whoami(request) {
         return client.identity.getUser(await requireToken(request));
     }
+    /**
+     * The caller's identity, plus the workspace every tenant-scoped route below
+     * needs - refusing the one session kind that has no workspace.
+     *
+     * A Connect **platform staff** session (`staff === true`) carries
+     * `workspaceId === null` by design: those accounts belong to no
+     * workspace, so entitlements, add-on balances, integrations, the AI context
+     * index and the data store have no tenant to read. Before this existed the
+     * type said `string` and the question never came up; now that it can, the
+     * only two answers are "refuse" and "let the request name a tenant" - and
+     * the second is precisely what this bridge exists to prevent.
+     *
+     * So: staff sign in, `/session` answers, and every workspace-scoped route
+     * refuses. An operator console reads `staff`/`role`/`permissions` and talks
+     * to your own backend for anything tenant-shaped.
+     */
+    async function requireWorkspace(request) {
+        const session = await whoami(request);
+        const workspaceId = session.user.workspaceId;
+        if (workspaceId === null) {
+            throw new ConnectError({
+                status: 403,
+                code: "no_workspace",
+                message: "This session has no workspace - platform staff sessions cannot read workspace data",
+                endpoint: new URL(request.url).pathname,
+            });
+        }
+        return { ...session, workspaceId };
+    }
+    /**
+     * The store paths a browser may reach through the bridge.
+     *
+     * Documents, 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.
+     * `storePassthrough` enforces the same set at the other end.
+     */
+    function isStoreRoute(route) {
+        return (route.startsWith("/data/") ||
+            route.startsWith("/kv/") ||
+            route.startsWith("/data-aggregate/") ||
+            route === "/data-commit");
+    }
+    /**
+     * Forwards one store call to Connect on behalf of the caller.
+     *
+     * Deliberately a thin relay of *path and body*, with the two things that
+     * decide access supplied here and never taken from the request: the session
+     * token, read from the partner's own session store, and the workspace, read
+     * from that session's identity. Connect re-derives both from the token
+     * anyway - this bridge is not trusted - but sending a client-supplied
+     * workspace even as an ignored field is the kind of thing that stops being
+     * ignored after a refactor.
+     *
+     * Paths are matched by prefix upstream and passed through unparsed; Connect
+     * validates every segment against the application's declared schema, so
+     * there is nothing useful for this layer to check and nothing it could check
+     * more strictly.
+     */
+    async function storeRoute(request) {
+        const token = await requireToken(request);
+        // Same refusal as every other tenant-scoped route - the store is a
+        // workspace's own data, and a staff session names no workspace. Note the
+        // token is still read first: this must fail as "no workspace", not as
+        // "no session".
+        const { workspaceId } = await requireWorkspace(request);
+        const url = new URL(request.url);
+        const route = (url.pathname.startsWith(basePath)
+            ? url.pathname.slice(basePath.length)
+            : url.pathname).replace(/\/+$/, "");
+        const query = new URLSearchParams(url.search);
+        query.set("workspaceId", workspaceId);
+        const body = request.method === "GET" || request.method === "DELETE"
+            ? undefined
+            : { ...(await request.json().catch(() => ({}))), workspaceId };
+        return client.storeRelay({
+            method: request.method,
+            path: `${route}?${query.toString()}`,
+            json: body,
+            headers: {
+                "x-connect-session-token": token,
+                // Forwarded because it is the one request header that changes what the
+                // write means, and dropping it would silently turn every merge into a
+                // replace.
+                ...(request.headers.get("x-store-write-mode")
+                    ? { "x-store-write-mode": request.headers.get("x-store-write-mode") }
+                    : {}),
+            },
+        });
+    }
     const routes = {
         "GET /session": async (request) => {
             const token = await session.read(request);
             // Signed out is a normal state for a page rendering a Login button, not
             // an error - `user: null` rather than a 401 the client must catch.
-            if (!token)
-                return json({ user: null, subscription: null, applicationRole: null });
+            // Signed out carries the same three access fields as a live session, so
+            // the client never has to tell "signed out" from "signed in with no
+            // role" by which keys happen to be present.
+            if (!token) {
+                return json({ user: null, subscription: null, role: null, permissions: [], staff: false });
+            }
             return json(await client.identity.getUser(token));
         },
         "GET /entitlements": async (request) => {
-            const { user } = await whoami(request);
+            const { workspaceId } = await requireWorkspace(request);
             const [readiness, subscription] = await Promise.all([
-                client.entitlements.getReadiness(user.workspaceId),
-                client.entitlements.getSubscription(user.workspaceId),
+                client.entitlements.getReadiness(workspaceId),
+                client.entitlements.getSubscription(workspaceId),
             ]);
             return json({ readiness, subscription });
         },
         "GET /plans": async () => json(await client.billing.listPlans()),
+        /**
+         * The platform's legal identity and grievance channel.
+         *
+         * The only route here that takes neither a session nor a workspace, and
+         * the only one where that is correct rather than a hole: the answer is a
+         * fact about the platform operator, identical for every caller, and
+         * already published on the public web. There is nothing to scope it to.
+         *
+         * Left unauthenticated on purpose. Requiring a session would mean a
+         * signed-out visitor reading your privacy page could not be shown the
+         * grievance officer to complain to - which is the one moment the notice
+         * most needs to be legible.
+         */
+        "GET /company-profile": async () => json({ companyProfile: await client.platform.getCompanyProfile() }),
         // Workspace comes from the caller's own session, same as every other
         // route here - a browser must not be able to ask what another workspace
         // has left.
         "GET /addons": async (request) => {
-            const { user } = await whoami(request);
-            return json(await client.billing.getAddonUsage(user.workspaceId));
+            const { workspaceId } = await requireWorkspace(request);
+            return json(await client.billing.getAddonUsage(workspaceId));
         },
         "GET /apps": async (request) => {
-            const { user } = await whoami(request);
-            return json({ apps: await client.apps.list(user.workspaceId) });
+            const { workspaceId } = await requireWorkspace(request);
+            return json({ apps: await client.apps.list(workspaceId) });
+        },
+        /**
+         * Ask AI. The one streaming route here, and the only one that does not
+         * answer JSON - it forwards Connect's server-sent event stream through
+         * untouched so `<ConnectAskAi>` can render tokens as they arrive.
+         *
+         * Same rule as every other route: the workspace comes from the caller's
+         * own session. It matters more here than anywhere else, because the
+         * answers are *retrieved from that workspace's Context Index* - a
+         * client-supplied `workspaceId` would be a read of another tenant's
+         * documents, laundered through a chat reply.
+         *
+         * Messages are forwarded as-is (part-based `UIMessage`s), and only their
+         * shape is checked: the conversation is the caller's own, and Connect
+         * validates it again on arrival.
+         */
+        "POST /ai/chat": async (request) => {
+            const { workspaceId } = await requireWorkspace(request);
+            const body = (await request.json().catch(() => null));
+            if (!Array.isArray(body?.messages)) {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "messages is required",
+                    endpoint: "POST /ai/chat",
+                });
+            }
+            const upstream = await client.ai.chat({
+                workspaceId: workspaceId,
+                messages: body.messages,
+                // Connect re-derives the workspace from this token, so the line above
+                // is belt to its braces - the browser cannot reach another tenant's
+                // Context Index even if this route were changed to trust the request.
+                asUser: await requireToken(request),
+            });
+            // `upstream.body` is piped, never buffered - awaiting it would collect
+            // the whole answer server-side and deliver it in one lump, which is the
+            // only thing streaming was for. The browser cancelling its read
+            // propagates down this pipe and stops generation upstream.
+            return new Response(upstream.body, {
+                status: upstream.status,
+                headers: {
+                    "content-type": upstream.headers.get("content-type") ?? "text/event-stream",
+                    "cache-control": "no-store",
+                    "x-content-type-options": "nosniff",
+                },
+            });
+        },
+        /**
+         * The store, forwarded.
+         *
+         * These are the only bridge routes with a *dynamic* path, and the only
+         * ones that forward a browser-supplied body to Connect. Both are safe for
+         * the same reason the rest of the bridge is: the caller's session token
+         * goes with the request as `asUser`, and Connect derives the user, their
+         * workspace and their permissions from it - so a browser cannot name
+         * another tenant, cannot claim a permission it does not hold, and cannot
+         * reach a collection this application never declared.
+         *
+         * `workspaceId` is still sent because the wire contract requires one, but
+         * Connect ignores it whenever a session token is present. It is filled
+         * from `whoami()` rather than the request either way, so this route never
+         * relays a client-supplied workspace even to be discarded.
+         */
+        "STORE": async (request) => storeRoute(request),
+        /**
+         * The workspace switcher's three reads, forwarded with the caller's own
+         * session token.
+         *
+         * `POST /workspaces/switch` is the only bridge route that *changes the
+         * caller's session*, so it writes the new token back through the same
+         * `session.write` the OAuth callback uses. Handing the raw token to the
+         * browser instead would put a credential in JavaScript's hands, which is
+         * exactly what this bridge exists to avoid - the browser gets the new
+         * workspace's name and a `Set-Cookie`, never the token itself.
+         *
+         * A partner with no `session.write` cannot re-persist a rotated token, so
+         * switching is simply absent for them rather than half-working - the same
+         * treatment `/signin` and `/callback` already get.
+         */
+        "GET /workspaces": async (request) => json({ workspaces: await client.workspaces.list({ asUser: await requireToken(request) }) }),
+        "GET /workspaces/members": async (request) => json({ members: await client.workspaces.members({ asUser: await requireToken(request) }) }),
+        "POST /workspaces/switch": async (request) => {
+            const token = await requireToken(request);
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.workspaceId !== "string") {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "workspaceId is required",
+                    endpoint: "POST /workspaces/switch",
+                });
+            }
+            const result = await client.workspaces.switch({ workspaceId: body.workspaceId }, { asUser: token });
+            // The response is built first so `session.write` has something to set
+            // cookies on, matching how `/callback` does it.
+            const response = json({
+                workspaceId: result.workspaceId,
+                workspaceName: result.workspaceName,
+                workspaceType: result.workspaceType,
+            });
+            await session.write?.(request, response, result.sessionToken);
+            return response;
         },
         "GET /integrations": async (request) => {
-            const { user } = await whoami(request);
-            return json({ toolkits: await client.integrations.list(user.workspaceId) });
+            const { workspaceId } = await requireWorkspace(request);
+            return json({ toolkits: await client.integrations.list(workspaceId) });
         },
         "POST /integrations/connect": async (request) => {
-            const { user } = await whoami(request);
+            const { workspaceId } = await requireWorkspace(request);
             const body = (await request.json().catch(() => null));
             if (!body?.toolkitSlug || !body?.returnUrl) {
                 throw new ConnectError({
@@ -208,10 +420,10 @@ export function createConnectHandler(options) {
                     endpoint: "POST /integrations/connect",
                 });
             }
-            return json(await client.integrations.initiateConnect(user.workspaceId, body.toolkitSlug, body.returnUrl));
+            return json(await client.integrations.initiateConnect(workspaceId, body.toolkitSlug, body.returnUrl));
         },
         "POST /integrations/disconnect": async (request) => {
-            const { user } = await whoami(request);
+            const { workspaceId } = await requireWorkspace(request);
             const body = (await request.json().catch(() => null));
             if (!body?.toolkitSlug) {
                 throw new ConnectError({
@@ -221,7 +433,7 @@ export function createConnectHandler(options) {
                     endpoint: "POST /integrations/disconnect",
                 });
             }
-            await client.integrations.disconnect(user.workspaceId, body.toolkitSlug);
+            await client.integrations.disconnect(workspaceId, body.toolkitSlug);
             return json({ ok: true });
         },
         // Account-wide, not scoped to this application - see `SessionsResource`'s
@@ -364,11 +576,20 @@ export function createConnectHandler(options) {
     if (!session.write) {
         delete routes["GET /signin"];
         delete routes["GET /callback"];
+        // A switch rotates the session token. Without somewhere to persist the new
+        // one, the old one would be revoked and the user silently signed out - so
+        // the route does not exist rather than working once and breaking.
+        delete routes["POST /workspaces/switch"];
     }
     return async function handle(request) {
         const path = new URL(request.url).pathname;
         const route = (path.startsWith(basePath) ? path.slice(basePath.length) : path).replace(/\/+$/, "") || "/";
-        const handler = routes[`${request.method} ${route}`];
+        const handler = routes[`${request.method} ${route}`] ??
+            // Store routes carry ids in the path, so they cannot be keyed by an
+            // exact string. Matched by prefix, and only this closed set - the bridge
+            // is deliberately not a generic proxy, and a broader fallback here is
+            // exactly how it would become one.
+            (isStoreRoute(route) ? routes.STORE : undefined);
         if (!handler) {
             return json({ error: { code: "not_found", message: `No Connect bridge route for ${route}` } }, 404);
         }

package/dist/esm/server/http.js

@@ -76,7 +76,8 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  * `ConnectError`.
  *
  * **On retries.** Only idempotent requests are retried without a caller
- * opt-in: every `GET`, plus any `POST` carrying an `Idempotency-Key` (the
+ * opt-in: every `GET`, `PUT` and `DELETE`, plus any `POST` carrying an
+ * `Idempotency-Key` (the
  * resources that mutate - `billing.consumeAddon`, `otp.send` - always set
  * one). A bare `POST` is attempted exactly once, because a 429 or a 504 says
  * nothing about whether the server already did the work.
@@ -114,7 +115,10 @@ export async function request(options, spec) {
         headers["content-type"] = "application/json";
         body = JSON.stringify(spec.json);
     }
-    const idempotent = spec.method === "GET" || headers["idempotency-key"] !== undefined;
+    // `PUT` and `DELETE` are idempotent by definition - replaying one lands the
+    // same end state - so they retry like `GET`. `POST` still needs an
+    // `Idempotency-Key` to earn it, because a replayed create is a second row.
+    const idempotent = spec.method !== "POST" || headers["idempotency-key"] !== undefined;
     const attempts = idempotent ? options.maxRetries + 1 : 1;
     let lastError;
     for (let attempt = 0; attempt < attempts; attempt++) {
@@ -124,33 +128,55 @@ export async function request(options, spec) {
             // request for minutes.
             await sleep(Math.min(lastError?.retryAfterMs ?? 250 * 2 ** (attempt - 1), 8_000));
         }
-        const timeout = AbortSignal.timeout(options.timeoutMs);
-        const signal = spec.signal ? AbortSignal.any([spec.signal, timeout]) : timeout;
-        let response;
+        // A cancellable timer rather than `AbortSignal.timeout`, because the
+        // timeout has to be *stopped* once this attempt is done reading - and a
+        // timeout signal cannot be cleared.
+        //
+        // That distinction is the whole point for a streaming endpoint. `fetch`
+        // resolves the moment the headers land, but its signal keeps governing
+        // the body: an `AbortSignal.timeout(20_000)` handed to `ai.chat` tears the
+        // SSE stream down mid-answer, twenty seconds in, on every conversation
+        // long enough to matter. Clearing the timer in `finally` bounds the
+        // request the same way it always did (a `raw` caller still gets its
+        // timeout on *reaching* Connect, and a JSON caller still gets it across
+        // the body read, which happens inside the `try`) while leaving a stream
+        // that has actually started to run as long as it needs. A caller that
+        // wants to bound the stream itself passes `spec.signal`.
+        const timeoutController = new AbortController();
+        const timer = setTimeout(() => timeoutController.abort(), options.timeoutMs);
+        const signal = spec.signal
+            ? AbortSignal.any([spec.signal, timeoutController.signal])
+            : timeoutController.signal;
         try {
-            response = await options.fetch(url.toString(), { method: spec.method, headers, body, signal });
+            let response;
+            try {
+                response = await options.fetch(url.toString(), { method: spec.method, headers, body, signal });
+            }
+            catch (cause) {
+                // A caller-supplied abort is a decision, not a fault - never retried.
+                if (spec.signal?.aborted)
+                    throw cause;
+                lastError = new ConnectError({
+                    status: 0,
+                    code: "network_error",
+                    message: `${endpoint} could not reach Connect`,
+                    endpoint,
+                    cause,
+                });
+                continue;
+            }
+            if (response.ok) {
+                if (spec.raw)
+                    return response;
+                return (await readBody(response));
+            }
+            lastError = toConnectError(response, await readBody(response), endpoint);
+            if (!RETRYABLE_STATUS.has(response.status))
+                throw lastError;
         }
-        catch (cause) {
-            // A caller-supplied abort is a decision, not a fault - never retried.
-            if (spec.signal?.aborted)
-                throw cause;
-            lastError = new ConnectError({
-                status: 0,
-                code: "network_error",
-                message: `${endpoint} could not reach Connect`,
-                endpoint,
-                cause,
-            });
-            continue;
+        finally {
+            clearTimeout(timer);
         }
-        if (response.ok) {
-            if (spec.raw)
-                return response;
-            return (await readBody(response));
-        }
-        lastError = toConnectError(response, await readBody(response), endpoint);
-        if (!RETRYABLE_STATUS.has(response.status))
-            throw lastError;
     }
     throw lastError;
 }

package/dist/esm/server/resources/acting-as.js

@@ -0,0 +1,13 @@
+/**
+ * The header that turns a server-to-server store call into one made *on behalf
+ * of* a signed-in user.
+ *
+ * Connect resolves the token to a user and a workspace itself and checks the
+ * collection's declared permission against that member's live roles - so a
+ * caller supplying this is asking for a *narrower* check than an application
+ * call, never a wider one. An unresolvable token is refused rather than
+ * quietly downgraded, precisely because the downgrade would be an escalation.
+ */
+export function actingAs(sessionToken) {
+    return sessionToken ? { "x-connect-session-token": sessionToken } : {};
+}

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

@@ -1,5 +1,13 @@
+import { actingAs } from "./acting-as.js";
 import { request } from "../http.js";
-/** RAG chat and structured extraction against a workspace's data. */
+/**
+ * RAG chat and structured extraction against a workspace's data.
+ *
+ * `asUser` on `chat` behaves as it does on the store resources: pass a
+ * signed-in user's `sessionToken` and Connect resolves the workspace from it,
+ * ignoring `workspaceId`. Without it you are the application, naming the
+ * workspace yourself.
+ */
 export class AiResource {
     transport;
     constructor(transport) {
@@ -15,7 +23,12 @@ export class AiResource {
         return request(this.transport, {
             method: "POST",
             path: "/ai/chat",
-            json: input,
+            // `asUser` never reaches the body - it is a credential, and Connect reads
+            // it from the header. Passing a signed-in user's session token makes
+            // Connect derive the workspace from *that* rather than from
+            // `workspaceId`, which is what the bridge relies on.
+            json: { workspaceId: input.workspaceId, messages: input.messages },
+            headers: actingAs(input.asUser),
             raw: true,
             signal: options.signal,
         });