@every-app/sdk 0.3.0-rc.1 → 0.3.0-rc.11

package/dist/server/aiBinding.js

@@ -0,0 +1,294 @@
+/**
+ * `gatewayAiBinding(env)`: the Gateway's AI providers as a Workers AI
+ * binding, for code written against `env.AI.run(model, inputs, options)`.
+ *
+ * An app on Every App needs no `ai` binding of its own to call models: the
+ * Gateway holds the keys, counts the calls and keeps the app to `ai.models`.
+ * Code that already calls `env.AI.run()` (upstream code a port keeps, the
+ * Agents SDK, `workers-ai-provider`) gets this object in its place:
+ *
+ *   const AI = gatewayAiBinding(env, { for: request });
+ *   await AI.run("@cf/meta/llama-3.1-8b-instruct-fast", { messages });
+ *
+ * Each `run()` becomes an OpenAI-compatible call on the provider's route
+ * through the Gateway (`createGatewayFetch`): text generation (`messages`
+ * or `prompt`) on its chat completions route, text embeddings (`text`) on
+ * its embeddings route, answered in Workers AI's shapes (`{ response,
+ * tool_calls, usage }`, `{ shape, data }`, or a stream of `data:
+ * {"response": …}` events with `stream: true`). In local development
+ * without a Gateway, the developer's own key in `.dev.vars` is used, as
+ * `createGatewayFetch` does (WORKERS_AI_API_TOKEN and CLOUDFLARE_ACCOUNT_ID
+ * for Workers AI).
+ */
+import { AI_DEFAULT_MODEL, AI_DEFAULT_PROVIDER, AI_DEFAULT_ROUTES, ConfigurationError, devAiProvider, } from "../internal/index.js";
+import { BINDING_ORIGIN, createGatewayFetch } from "./gatewayFetch.js";
+import { GatewayRefusalError, gatewayRefusal } from "./refusal.js";
+/**
+ * A Workers AI binding (`Ai`) over the Gateway: pass it where code takes
+ * `env.AI`. `run()` covers text generation (messages or prompt; tools;
+ * `stream: true`; `returnRawResponse`, which returns the provider's
+ * OpenAI-shaped `Response`) and text embeddings; the binding's other
+ * methods (`gateway()`, `autorag()`, `models()`, `toMarkdown()`, …) and
+ * other tasks (images, audio, batches, websockets) throw
+ * `ConfigurationError`. `options.gateway` is ignored: the Gateway's
+ * operator decides whether calls go through Cloudflare AI Gateway
+ * (`everyapp ai gateway on`).
+ *
+ * Errors are thrown as a binding throws them: `GatewayRefusalError` when
+ * the Gateway refused (`ai_provider_not_configured`, `model_not_allowed`,
+ * …), `ConfigurationError` where createGatewayFetch throws one (no binding
+ * and no dev key), and an `Error` naming the status when the provider
+ * answered with an error. Nothing is checked when the binding is made, so
+ * making one per request costs nothing.
+ */
+export function gatewayAiBinding(env, options = {}) {
+    const provider = options.provider ?? "workers-ai";
+    async function run(model, inputs, runOptions = {}) {
+        if (runOptions.websocket) {
+            throw unsupported("run() with websocket: true");
+        }
+        if (!inputs || typeof inputs !== "object") {
+            throw unsupported("run() without an inputs object");
+        }
+        if (Array.isArray(inputs["requests"])) {
+            throw unsupported("run() with a batch of requests");
+        }
+        const embedding = !("messages" in inputs) && !("prompt" in inputs) && "text" in inputs;
+        if (!embedding && !("messages" in inputs) && !("prompt" in inputs)) {
+            throw unsupported("run() for anything but text generation (messages or prompt) and text embeddings (text)");
+        }
+        const url = `${BINDING_ORIGIN}/api/ai/${provider}${routeOf(provider, embedding ? "embeddings" : "chat")}`;
+        const sent = modelToSend(provider, model, options.models);
+        const body = embedding
+            ? { model: sent, input: inputs["text"] }
+            : chatBody(sent, inputs);
+        const gatewayFetch = createGatewayFetch({
+            env,
+            for: options.for,
+        });
+        const response = await gatewayFetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+            ...(runOptions.signal ? { signal: runOptions.signal } : {}),
+        });
+        if (runOptions.returnRawResponse)
+            return response;
+        await throwIfFailed(response, provider);
+        if (embedding)
+            return embeddingOutput(await response.json());
+        if (inputs["stream"] === true) {
+            if (!response.body)
+                return new ReadableStream();
+            return response.body.pipeThrough(toWorkersAiStream());
+        }
+        return textOutput(await response.json());
+    }
+    const notHere = (method) => () => {
+        throw unsupported(`env.AI.${method}()`);
+    };
+    const binding = {
+        aiGatewayLogId: null,
+        run,
+        gateway: notHere("gateway"),
+        autorag: notHere("autorag"),
+        aiSearch: notHere("aiSearch"),
+        websearch: notHere("websearch"),
+        models: notHere("models"),
+        toMarkdown: notHere("toMarkdown"),
+    };
+    // `Ai` is the app's own Workers types' class (it changes with each
+    // version); the object above is its working subset, the rest throwing.
+    return binding;
+}
+function unsupported(what) {
+    return new ConfigurationError(`${what} isn't available through the Every App gateway; call the provider's routes with createGatewayFetch() instead.`);
+}
+/** The provider's path for a chat or an embeddings call, under `/api/ai/<provider>`. */
+function routeOf(provider, kind) {
+    if (provider === AI_DEFAULT_PROVIDER)
+        return AI_DEFAULT_ROUTES[kind];
+    const spec = devAiProvider(provider);
+    if (!spec) {
+        throw new ConfigurationError(`gatewayAiBinding: ${JSON.stringify(provider)} is not an AI provider of the catalog.`);
+    }
+    const route = spec[kind];
+    if (!route) {
+        throw new ConfigurationError(`gatewayAiBinding: ${provider} has no OpenAI-compatible ${kind === "chat" ? "chat completions" : "embeddings"} route.`);
+    }
+    return route.path;
+}
+function modelToSend(provider, model, models) {
+    const mapped = models && Object.hasOwn(models, model) ? models[model] : null;
+    if (mapped)
+        return mapped;
+    if (provider === AI_DEFAULT_PROVIDER && model.startsWith("@cf/")) {
+        return AI_DEFAULT_MODEL;
+    }
+    return model;
+}
+/**
+ * Workers AI's text generation inputs as a chat completions body: `prompt`
+ * as one user message, legacy tools (`{ name, description, parameters }`)
+ * as OpenAI's, everything else (max_tokens, temperature, response_format,
+ * stream, …) as it is. Never adds `stream_options` (Workers AI refuses it
+ * on a call that doesn't stream).
+ */
+function chatBody(model, inputs) {
+    const { prompt, messages, tools, raw: _raw, lora: _lora, ...rest } = inputs;
+    const body = {
+        ...rest,
+        model,
+        messages: messages ??
+            (typeof prompt === "string" ? [{ role: "user", content: prompt }] : []),
+    };
+    if (Array.isArray(tools))
+        body["tools"] = tools.map(openAiTool);
+    return body;
+}
+function openAiTool(tool) {
+    if (!isRecord(tool) || "function" in tool)
+        return tool;
+    const { name, description, parameters } = tool;
+    return {
+        type: "function",
+        function: {
+            name,
+            ...(description === undefined ? {} : { description }),
+            ...(parameters === undefined ? {} : { parameters }),
+        },
+    };
+}
+async function throwIfFailed(response, provider) {
+    if (response.ok)
+        return;
+    const refusal = await gatewayRefusal(response.clone());
+    if (refusal)
+        throw new GatewayRefusalError(refusal);
+    const text = await response.text().catch(() => "");
+    throw new Error(`AI (${provider}) answered ${response.status}${text ? `: ${text.slice(0, 500)}` : ""}`);
+}
+/** A chat completion as Workers AI answers text generation. */
+function textOutput(body) {
+    const choice = firstChoice(body);
+    const message = isRecord(choice?.["message"]) ? choice["message"] : {};
+    const toolCalls = workersAiToolCalls(message["tool_calls"]);
+    const usage = isRecord(body) ? body["usage"] : undefined;
+    return {
+        // Workers AI may send an all-digit reply as a JSON number.
+        response: textOf(message["content"]),
+        ...(toolCalls ? { tool_calls: toolCalls } : {}),
+        ...(isRecord(usage) ? { usage } : {}),
+    };
+}
+/**
+ * OpenAI tool calls as both forms Workers AI answers with: the legacy
+ * `{ name, arguments }` (arguments parsed) and the OpenAI-shaped
+ * `{ id, type, function }`.
+ */
+function workersAiToolCalls(calls) {
+    if (!Array.isArray(calls) || calls.length === 0)
+        return undefined;
+    return calls.filter(isRecord).map((call) => {
+        const fn = isRecord(call["function"]) ? call["function"] : {};
+        const args = fn["arguments"];
+        return {
+            ...(call["id"] === undefined ? {} : { id: call["id"] }),
+            type: "function",
+            function: { name: fn["name"], arguments: args },
+            name: fn["name"],
+            arguments: typeof args === "string" ? parsedOr(args) : args,
+        };
+    });
+}
+/** Embeddings as Workers AI answers them: `{ shape: [rows, dimensions], data }`. */
+function embeddingOutput(body) {
+    const rows = isRecord(body) && Array.isArray(body["data"]) ? body["data"] : [];
+    const data = rows
+        .filter(isRecord)
+        .sort((a, b) => Number(a["index"] ?? 0) - Number(b["index"] ?? 0))
+        .map((row) => Array.isArray(row["embedding"]) ? row["embedding"] : []);
+    return { shape: [data.length, data[0]?.length ?? 0], data };
+}
+/**
+ * An OpenAI chat completions event stream as Workers AI streams text:
+ * one `data: {"response": "<token>"}` event per chunk with text (tool call
+ * deltas and usage alongside), then `data: [DONE]`.
+ */
+function toWorkersAiStream() {
+    const decoder = new TextDecoder();
+    const encoder = new TextEncoder();
+    let pending = "";
+    const convert = (line) => {
+        const match = /^data:[ ]?(.*?)\r?$/s.exec(line);
+        if (!match)
+            return "";
+        const data = match[1].trim();
+        if (data === "[DONE]")
+            return "data: [DONE]\n\n";
+        let chunk;
+        try {
+            chunk = JSON.parse(data);
+        }
+        catch {
+            return "";
+        }
+        const choice = firstChoice(chunk);
+        const delta = isRecord(choice?.["delta"]) ? choice["delta"] : {};
+        const usage = isRecord(chunk) ? chunk["usage"] : undefined;
+        const toolCalls = Array.isArray(delta["tool_calls"])
+            ? delta["tool_calls"]
+            : undefined;
+        const event = {
+            response: textOf(delta["content"]),
+            ...(toolCalls ? { tool_calls: toolCalls } : {}),
+            ...(isRecord(usage) ? { usage } : {}),
+        };
+        if (!event.response && !toolCalls && !isRecord(usage))
+            return "";
+        return `data: ${JSON.stringify(event)}\n\n`;
+    };
+    return new TransformStream({
+        transform(bytes, controller) {
+            pending += decoder.decode(bytes, { stream: true });
+            const end = pending.lastIndexOf("\n");
+            if (end === -1)
+                return;
+            const lines = pending.slice(0, end).split("\n");
+            pending = pending.slice(end + 1);
+            const out = lines.map(convert).join("");
+            if (out)
+                controller.enqueue(encoder.encode(out));
+        },
+        flush(controller) {
+            pending += decoder.decode();
+            const out = convert(pending);
+            if (out)
+                controller.enqueue(encoder.encode(out));
+        },
+    });
+}
+function firstChoice(body) {
+    if (!isRecord(body) || !Array.isArray(body["choices"]))
+        return undefined;
+    const choice = body["choices"][0];
+    return isRecord(choice) ? choice : undefined;
+}
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    if (typeof content === "number")
+        return String(content);
+    return "";
+}
+function parsedOr(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/server/attribution.d.ts

@@ -1,6 +1,8 @@
 /**
  * Whom a call through the gateway is for, which decides the organization
- * it counts against:
+ * it counts against. Left out, it comes from the request context: the
+ * request `everyApp()` is serving (its person, while the identity is good),
+ * or the organization `withOrganization()` named. Given explicitly:
  *
  *  - the inbound `Request`: its person, by the identity the gateway put on
  *    it (forwarded as is);
@@ -10,10 +12,19 @@
  *    checks is active and has a live member. An organization's own app may
  *    leave it out (the gateway knows its organization) and may only name
  *    its own.
+ *  - `{ background: true, organizationId, userId }`: a call to an OAuth
+ *    provider's API (`integrationFetch`) on the connection member `userId`
+ *    made in this app, at any time, even while serving another person's
+ *    request: the call carries that member (`x-everyapp-user`) and never
+ *    the identity of the person being served. Only an organization's own
+ *    app may name a member, and only one who may still open the app. No
+ *    identity for the member reaches the app. Other gateway calls ignore
+ *    `userId`.
  */
 export type GatewayCallFor = Request | {
     background: true;
     organizationId?: string;
+    userId?: string;
 };
 /**
  * A gateway call that doesn't say whom it is for where it must: from a
@@ -24,11 +35,13 @@ export declare class AttributionError extends Error {
     constructor(message: string);
 }
 /**
- * Check `target` before any call is made: a shared app's Worker must pass
- * the request or name the organization, and anything else passed must be
- * one of the two shapes.
+ * Whom the call is for, checked before any call is made: `target` as the
+ * app passed it, else the request context's answer
+ * ({@link attributionFromContext}; a `RequestContextError` outside every
+ * context). A shared app's Worker must end up with the request or an
+ * organization, and anything passed must be one of the two shapes.
  */
-export declare function checkAttribution(env: object, target: GatewayCallFor | undefined, what: string): void;
+export declare function attributionFor(env: object, target: GatewayCallFor | undefined, what: string): GatewayCallFor | undefined;
 /**
  * Put the call's attribution on its headers: the request's identity, or the
  * background work's organization, and never one the app set itself.

package/dist/server/attribution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../../src/server/attribution.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GACtB,OAAO,GACP;IAAE,UAAU,EAAE,IAAI,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,0BAA0B;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,GACX,IAAI,CAsBN;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,cAAc,GAAG,SAAS,GACjC,IAAI,CAUN;AASD,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAO1D"}
+{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../../src/server/attribution.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,cAAc,GACtB,OAAO,GACP;IAAE,UAAU,EAAE,IAAI,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,0BAA0B;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,GACX,cAAc,GAAG,SAAS,CAI5B;AAmCD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,cAAc,GAAG,SAAS,GACjC,IAAI,CAYN;AASD,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAO1D"}

package/dist/server/attribution.js

@@ -1,4 +1,5 @@
-import { IDENTITY_HEADER, ORG_HEADER, SHARED_ENV } from "../internal/index.js";
+import { IDENTITY_HEADER, ORG_HEADER, SHARED_ENV, USER_HEADER, } from "../internal/index.js";
+import { attributionFromContext } from "./context.js";
 /**
  * A gateway call that doesn't say whom it is for where it must: from a
  * shared app's Worker, with neither the request nor an organization.
@@ -11,15 +12,25 @@ export class AttributionError extends Error {
     }
 }
 /**
- * Check `target` before any call is made: a shared app's Worker must pass
- * the request or name the organization, and anything else passed must be
- * one of the two shapes.
+ * Whom the call is for, checked before any call is made: `target` as the
+ * app passed it, else the request context's answer
+ * ({@link attributionFromContext}; a `RequestContextError` outside every
+ * context). A shared app's Worker must end up with the request or an
+ * organization, and anything passed must be one of the two shapes.
  */
-export function checkAttribution(env, target, what) {
+export function attributionFor(env, target, what) {
+    const resolved = target === undefined ? attributionFromContext(what) : target;
+    checkAttribution(env, resolved, what);
+    return resolved;
+}
+function checkAttribution(env, target, what) {
     if (target !== undefined && !isRequest(target)) {
         if (target === null || typeof target !== "object" || !target.background) {
             throw new AttributionError(`${what}: \`for\` is the inbound Request or { background: true, organizationId }.`);
         }
+        if (target.userId !== undefined && !nonEmpty(target.userId)) {
+            throw new AttributionError(`${what}: { background: true, userId } needs a non-empty user id.`);
+        }
         if (target.organizationId !== undefined &&
             !nonEmpty(target.organizationId)) {
             throw new AttributionError(`${what}: { background: true, organizationId } needs a non-empty organization id.`);
@@ -38,6 +49,7 @@ export function checkAttribution(env, target, what) {
 export function applyAttribution(headers, target) {
     headers.delete(IDENTITY_HEADER);
     headers.delete(ORG_HEADER);
+    headers.delete(USER_HEADER);
     if (target === undefined)
         return;
     if (isRequest(target)) {
@@ -48,6 +60,8 @@ export function applyAttribution(headers, target) {
     }
     if (target.organizationId)
         headers.set(ORG_HEADER, target.organizationId);
+    if (target.userId)
+        headers.set(USER_HEADER, target.userId.trim());
 }
 function isSharedWorker(env) {
     const value = env[SHARED_ENV];

package/dist/server/connectUrl.d.ts

@@ -0,0 +1,16 @@
+export interface ConnectUrlOptions {
+    /** The Worker env: `GATEWAY_URL` and the app's id, which every deployed Worker and `everyapp dev` set. */
+    env: object;
+    /** The OAuth provider's id (`google-workspace`, `github`). */
+    provider: string;
+    /**
+     * Where to send the person afterwards: the app's own URL (absolute) or
+     * a path on the Gateway. Absent: Settings → Connected accounts.
+     */
+    returnTo?: string;
+}
+/** The path of the connect page for `provider` on the Gateway, without the app. */
+export declare function connectPath(provider: string): string;
+/** The absolute URL that connects the person to `provider` in this app. */
+export declare function connectUrl({ env, provider, returnTo, }: ConnectUrlOptions): string;
+//# sourceMappingURL=connectUrl.d.ts.map

package/dist/server/connectUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectUrl.d.ts","sourceRoot":"","sources":["../../src/server/connectUrl.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,iBAAiB;IAChC,0GAA0G;IAC1G,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,EACzB,GAAG,EACH,QAAQ,EACR,QAAQ,GACT,EAAE,iBAAiB,GAAG,MAAM,CAwB5B"}

package/dist/server/connectUrl.js

@@ -0,0 +1,40 @@
+/**
+ * Where an app sends a person to connect an OAuth provider the Gateway
+ * runs the flow for (docs/design/2026-11-oauth-simplify.md):
+ * `<gateway>/connect/<id>?app=<this app>&return=<back here>`. A
+ * connection belongs to one person and one app: the Gateway checks the
+ * session and that the person may open the app, asks the provider for
+ * exactly the scopes the app's `everyapp.config.ts` lists (plus the ones
+ * that name the account), finishes on its own callback and sends the
+ * browser back to `returnTo`, which must be a path on the Gateway or an
+ * https URL on one of its app hosts (in local dev also localhost).
+ */
+import { APP_ID_ENV, ConfigurationError } from "../internal/index.js";
+/** The path of the connect page for `provider` on the Gateway, without the app. */
+export function connectPath(provider) {
+    return `/connect/${encodeURIComponent(provider)}`;
+}
+/** The absolute URL that connects the person to `provider` in this app. */
+export function connectUrl({ env, provider, returnTo, }) {
+    const values = env;
+    const gateway = values["GATEWAY_URL"];
+    if (typeof gateway !== "string" || !gateway.trim()) {
+        throw new ConfigurationError("connectUrl() needs GATEWAY_URL in the Worker env: the deploy sets it, and everyapp dev sets it to the local gateway.");
+    }
+    let base;
+    try {
+        base = new URL(gateway.trim());
+    }
+    catch {
+        throw new ConfigurationError(`GATEWAY_URL isn't a URL: ${gateway}`);
+    }
+    const app = values[APP_ID_ENV];
+    if (typeof app !== "string" || !app.trim()) {
+        throw new ConfigurationError(`connectUrl() needs ${APP_ID_ENV} in the Worker env: a connection belongs to one app, and the deploy and everyapp dev set it.`);
+    }
+    const url = new URL(connectPath(provider), base.origin);
+    url.searchParams.set("app", app.trim());
+    if (returnTo)
+        url.searchParams.set("return", returnTo);
+    return url.toString();
+}

package/dist/server/context.d.ts

@@ -0,0 +1,68 @@
+import type { EveryAppUser } from "../internal/index.js";
+/** What `everyApp()` keeps while it serves one request. */
+export interface ServedRequest {
+    request: Request;
+    /** The verified user, or null on a public route. */
+    user: EveryAppUser | null;
+    /** When the forwarded identity expires (epoch ms); null without one. */
+    expiresAt: number | null;
+}
+/**
+ * A forwarded identity lives 120 seconds. One this close to its expiry could
+ * expire before the Gateway checks it (a 401 the call can't recover from),
+ * so work still running then goes on as the organization's background work.
+ */
+export declare const IDENTITY_EXPIRY_MARGIN_MS = 15000;
+/**
+ * Code `request_context_missing`: `currentUser()` or a Gateway call with
+ * no `for`, outside any request `everyApp()` serves and outside
+ * `withOrganization()`. Work no request started names its organization.
+ */
+export declare class RequestContextError extends Error {
+    readonly code = "request_context_missing";
+    constructor(message: string);
+}
+/**
+ * Code `attribution_organization_mismatch`: `withOrganization()` named
+ * another organization than the request being served belongs to.
+ */
+export declare class OrganizationMismatchError extends Error {
+    readonly code = "attribution_organization_mismatch";
+    constructor(message: string);
+}
+/** Serve `fn` for one request: `everyApp()` calls this; apps don't. */
+export declare function serveRequest<T>(served: ServedRequest, fn: () => T): T;
+/**
+ * Run `fn` as `organizationId`'s background work: every Gateway call made
+ * inside it (and in what it awaits or schedules) is that organization's,
+ * with no person behind it. For a Workflow step, a cron, a queue consumer or
+ * a Durable Object alarm, which no request started. An organization's own
+ * app names its own (`env.EVERY_APP_ORG_ID`); a shared app's Worker names
+ * the one the work is for. Inside a request another organization's person
+ * is driving, it throws {@link OrganizationMismatchError}; inside that
+ * organization's own request, the person stays attributed while their
+ * identity is good.
+ */
+export declare function withOrganization<T>(organizationId: string, fn: () => T): T;
+/**
+ * The verified user of the request being served: an `EveryAppUser`, or
+ * `null` on a public route and inside `withOrganization()`'s background
+ * work. Throws {@link RequestContextError} outside both: there is no one
+ * to be, and a handler that isn't under `everyApp()` is a bug.
+ */
+export declare function currentUser(): EveryAppUser | null;
+/**
+ * Whom a Gateway call made now is for, from the context:
+ *
+ *  - the request being served, while its identity is good;
+ *  - else that organization's background work (the identity is about to
+ *    expire, or `withOrganization()` named it);
+ *  - `undefined` on a public route of an organization's own app, which the
+ *    Gateway attributes to the app's organization; and
+ *  - a {@link RequestContextError} outside every context.
+ */
+export declare function attributionFromContext(what: string, now?: number): Request | {
+    background: true;
+    organizationId?: string;
+} | undefined;
+//# sourceMappingURL=context.d.ts.map

package/dist/server/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/server/context.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1B,wEAAwE;IACxE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAUD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,6BAA6B;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,uCAAuC;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAErE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAc1E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,YAAY,GAAG,IAAI,CAQjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,MAAmB,GACvB,OAAO,GAAG;IAAE,UAAU,EAAE,IAAI,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAoBrE"}

package/dist/server/context.js

@@ -0,0 +1,117 @@
+/**
+ * The request context: whom the app is serving, kept for the whole of a
+ * request's work (every `await`, `ctx.waitUntil()`, a streaming body) in an
+ * `AsyncLocalStorage`, which every Every App Worker has (`nodejs_compat`).
+ *
+ * `everyApp()` opens it around the handler and around each tool call, with
+ * the verified user and the request the Gateway forwarded. Deeper in the
+ * app, `currentUser()` reads the user without the request, and every call
+ * back to the Gateway (`integrationFetch`, `ai`, `sendEmail`, `emit`, ...)
+ * is attributed to that person without a `for`.
+ *
+ * Work no request started (a cron, a Workflow step, a queue consumer, a
+ * Durable Object alarm) has no context of its own: it runs under
+ * `withOrganization(organizationId, fn)`, which makes every Gateway call
+ * inside it that organization's background work. A Gateway call with
+ * neither is refused before it is made ({@link RequestContextError}): the
+ * SDK never acts as nobody.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const scopes = new AsyncLocalStorage();
+/**
+ * A forwarded identity lives 120 seconds. One this close to its expiry could
+ * expire before the Gateway checks it (a 401 the call can't recover from),
+ * so work still running then goes on as the organization's background work.
+ */
+export const IDENTITY_EXPIRY_MARGIN_MS = 15_000;
+/**
+ * Code `request_context_missing`: `currentUser()` or a Gateway call with
+ * no `for`, outside any request `everyApp()` serves and outside
+ * `withOrganization()`. Work no request started names its organization.
+ */
+export class RequestContextError extends Error {
+    code = "request_context_missing";
+    constructor(message) {
+        super(message);
+        this.name = "RequestContextError";
+    }
+}
+/**
+ * Code `attribution_organization_mismatch`: `withOrganization()` named
+ * another organization than the request being served belongs to.
+ */
+export class OrganizationMismatchError extends Error {
+    code = "attribution_organization_mismatch";
+    constructor(message) {
+        super(message);
+        this.name = "OrganizationMismatchError";
+    }
+}
+/** Serve `fn` for one request: `everyApp()` calls this; apps don't. */
+export function serveRequest(served, fn) {
+    return scopes.run({ served }, fn);
+}
+/**
+ * Run `fn` as `organizationId`'s background work: every Gateway call made
+ * inside it (and in what it awaits or schedules) is that organization's,
+ * with no person behind it. For a Workflow step, a cron, a queue consumer or
+ * a Durable Object alarm, which no request started. An organization's own
+ * app names its own (`env.EVERY_APP_ORG_ID`); a shared app's Worker names
+ * the one the work is for. Inside a request another organization's person
+ * is driving, it throws {@link OrganizationMismatchError}; inside that
+ * organization's own request, the person stays attributed while their
+ * identity is good.
+ */
+export function withOrganization(organizationId, fn) {
+    if (typeof organizationId !== "string" || organizationId.trim() === "") {
+        throw new TypeError("withOrganization(organizationId, fn) needs a non-empty organization id (an organization's own app passes env.EVERY_APP_ORG_ID).");
+    }
+    const parent = scopes.getStore();
+    const served = parent?.served;
+    if (served?.user && served.user.orgId !== organizationId) {
+        throw new OrganizationMismatchError(`withOrganization("${organizationId}") was called while serving a request of organization "${served.user.orgId}".`);
+    }
+    return scopes.run({ ...parent, organizationId }, fn);
+}
+/**
+ * The verified user of the request being served: an `EveryAppUser`, or
+ * `null` on a public route and inside `withOrganization()`'s background
+ * work. Throws {@link RequestContextError} outside both: there is no one
+ * to be, and a handler that isn't under `everyApp()` is a bug.
+ */
+export function currentUser() {
+    const scope = scopes.getStore();
+    if (!scope) {
+        throw new RequestContextError("currentUser() was called outside a request everyApp() serves and outside withOrganization(): there is no user here.");
+    }
+    return scope.served?.user ?? null;
+}
+/**
+ * Whom a Gateway call made now is for, from the context:
+ *
+ *  - the request being served, while its identity is good;
+ *  - else that organization's background work (the identity is about to
+ *    expire, or `withOrganization()` named it);
+ *  - `undefined` on a public route of an organization's own app, which the
+ *    Gateway attributes to the app's organization; and
+ *  - a {@link RequestContextError} outside every context.
+ */
+export function attributionFromContext(what, now = Date.now()) {
+    const scope = scopes.getStore();
+    if (!scope) {
+        throw new RequestContextError(`${what} was called with no \`for\`, outside a request everyApp() serves and outside withOrganization(): the call would be nobody's. Pass for: request, or run the work under withOrganization(organizationId, fn).`);
+    }
+    const served = scope.served;
+    if (served?.user) {
+        const fresh = served.expiresAt === null ||
+            now < served.expiresAt - IDENTITY_EXPIRY_MARGIN_MS;
+        // withOrganization() refused any other organization than the request's.
+        if (fresh)
+            return served.request;
+        return { background: true, organizationId: served.user.orgId };
+    }
+    if (scope.organizationId) {
+        return { background: true, organizationId: scope.organizationId };
+    }
+    return undefined;
+}