@every-app/sdk 0.3.0-rc.9 → 0.3.0

package/dist/server/ai.js

@@ -1,116 +1,22 @@
 /**
- * `ai()`: the Gateway's default chat model for an app that needs "a model"
- * rather than one provider (docs/design/2026-10-model-providers.md). The
- * manifest says `ai: { chat: true }` (or `{ chat: { why } }`); the Gateway's
- * operator decides which provider and model that is (`everyapp ai
- * default`, else OpenRouter → Workers AI → OpenAI → …, the first with its
- * key set), and the app never names either: it sends OpenAI-shaped chat
- * completions (and embeddings) to `/api/ai/default/v1/…` with `model:
- * "default"` or no model at all, and the Gateway fills the model in.
+ * Where an app's model calls go behind the Gateway, for an OpenAI client's
+ * `baseURL` or a plain `fetch`, both sent with `createGatewayFetch()`:
+ * `aiBaseUrl("openai")` (a provider's OpenAI-compatible base), `aiBaseUrl()`
+ * (the Gateway's default model, `ai: { chat: true }`: send `model:
+ * "default"` or none and the Gateway fills in the workspace's model), and
+ * `providerBaseUrl("openai")` (a provider's root, for its own paths).
  *
- * An OpenAI client takes `baseURL` and `fetch` as they are:
- *
- *   const { baseURL, fetch, model } = ai({ env, for: request });
- *   const client = new OpenAI({ baseURL, fetch, apiKey: "gateway-managed" });
- *   await client.chat.completions.create({ model, messages });
- *
- * In local development with no Gateway, the developer's own key in
- * `.dev.vars` decides the provider by the same order (createGatewayFetch's
- * fallback). An app that needs one provider in particular keeps listing it
- * under `providers` and calling `/api/ai/<provider>/…`.
+ *   const client = new OpenAI({
+ *     baseURL: aiBaseUrl(),
+ *     fetch: createGatewayFetch({ env }),
+ *     apiKey: "gateway-managed",
+ *   });
+ *   await client.chat.completions.create({ model: "default", messages });
  */
-import { AI_DEFAULT_MODEL, AI_DEFAULT_PROVIDER, CATALOG, ConfigurationError, aiProviderSettings, devAiProvider, resolveAiDefault, } from "../internal/index.js";
-import { applyAttribution, attributionFor, } from "./attribution.js";
-import { BINDING_ORIGIN, createGatewayFetch, gatewayBinding, } from "./gatewayFetch.js";
-/** The base URL of the default route, as the SDK and the docs name it. */
-export const AI_DEFAULT_BASE_URL = `${BINDING_ORIGIN}/api/ai/${AI_DEFAULT_PROVIDER}/v1`;
-export function ai(options) {
-    const fetch = createGatewayFetch(options);
-    if (!fetch)
-        return null;
-    return {
-        baseURL: AI_DEFAULT_BASE_URL,
-        fetch,
-        model: AI_DEFAULT_MODEL,
-        chatCompletionsUrl: `${AI_DEFAULT_BASE_URL}/chat/completions`,
-        embeddingsUrl: `${AI_DEFAULT_BASE_URL}/embeddings`,
-    };
-}
-/**
- * Whether the app can use a model right now, without calling one: gate
- * an AI feature and show `setup` ("A chat model isn't set up on this
- * Gateway: it needs OPENROUTER_API_KEY. An admin runs: pnpm everyapp
- * configure inbox") up front instead of failing mid-task. `provider`
- * defaults to `default`, the Gateway's default model (`ai: { chat: true }`);
- * name one the manifest lists under `providers` to ask about it instead.
- * The Gateway owns the wording: show `setup` and `command` as they are.
- *
- * Over the binding it sends `GET /api/ai/<provider>`; in local dev it
- * answers from `.dev.vars` by the same rule `createGatewayFetch()` uses.
- */
-export async function aiStatus({ env, provider = AI_DEFAULT_PROVIDER, for: explicitTarget, }) {
-    const target = attributionFor(env, explicitTarget, "aiStatus");
-    const values = env;
-    const binding = gatewayBinding(env);
-    const unavailable = {
-        provider,
-        requested: false,
-        configured: false,
-        ready: false,
-        resolved: null,
-        settings: [],
-        setup: null,
-        command: null,
-    };
-    if (binding && typeof binding.fetch === "function") {
-        const headers = new Headers();
-        if (target !== undefined)
-            applyAttribution(headers, target);
-        const response = await binding.fetch(`${BINDING_ORIGIN}/api/ai/${encodeURIComponent(provider)}`, { headers });
-        if (!response.ok)
-            return unavailable;
-        const body = (await response.json());
-        return {
-            ...unavailable,
-            ...body,
-            provider,
-            settings: Array.isArray(body.settings) ? body.settings : [],
-            setup: typeof body.setup === "string" ? body.setup : null,
-            command: typeof body.command === "string" ? body.command : null,
-            resolved: body.resolved ?? null,
-        };
-    }
-    if (!values["EVERYAPP_DEV"])
-        return unavailable;
-    const isSet = (name) => typeof values[name] === "string" && values[name].trim() !== "";
-    const dev = (label, settings, configured, resolved, also = "") => ({
-        provider,
-        requested: true,
-        configured,
-        ready: configured,
-        resolved,
-        settings: configured ? [] : [...settings],
-        setup: configured
-            ? null
-            : `${label} isn't set up for local development: set ${settings.join(" and ")}${also} in .dev.vars.`,
-        command: null,
-    });
-    if (provider === AI_DEFAULT_PROVIDER) {
-        const resolution = resolveAiDefault({ provider: null, isSet });
-        return dev("A chat model", resolution.settings, resolution.configured, resolution.configured
-            ? {
-                provider: resolution.provider,
-                label: resolution.label,
-                model: resolution.model,
-            }
-            : null, " (or another model provider's key)");
-    }
-    const spec = devAiProvider(provider);
-    if (!spec)
-        return unavailable;
-    const settings = aiProviderSettings(spec);
-    return dev(CATALOG.get(provider)?.label ?? provider, settings, settings.every(isSet), null);
-}
+import { AI_DEFAULT_PROVIDER, CATALOG, ConfigurationError, } from "../internal/index.js";
+import { BINDING_ORIGIN } from "./gatewayFetch.js";
+/** The base URL of the default route, `…/api/ai/default/v1`. */
+const AI_DEFAULT_BASE_URL = `${BINDING_ORIGIN}/api/ai/${AI_DEFAULT_PROVIDER}/v1`;
 const CHAT_COMPLETIONS = "/chat/completions";
 /**
  * A provider's root behind the Gateway, `http://every-app-gateway.internal/api/ai/<provider>`:
@@ -124,7 +30,7 @@ export function providerBaseUrl(provider) {
 /**
  * The OpenAI-compatible base URL of `provider` behind the Gateway, for an
  * OpenAI client's `baseURL` (with `fetch: createGatewayFetch(...)`):
- * `default` (the default) is {@link AI_DEFAULT_BASE_URL},
+ * `default` (the default, and what it is when left out) is
  * `…/api/ai/default/v1`; a catalog provider's is its root and the prefix
  * of its chat route (`…/api/ai/openrouter/api/v1`, `…/api/ai/workers-ai/v1`,
  * `…/api/ai/openai/v1`). Throws `ConfigurationError` for a provider with

package/dist/server/attribution.d.ts

@@ -2,7 +2,7 @@
  * Whom a call through the gateway is for, which decides the organization
  * 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:
+ * or the organization the SDK's event delivery runs under. Given explicitly:
  *
  *  - the inbound `Request`: its person, by the identity the gateway put on
  *    it (forwarded as is);
@@ -12,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

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

@@ -1 +1 @@
-{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../../src/server/attribution.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;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;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,GACX,cAAc,GAAG,SAAS,CAI5B;AA8BD;;;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,4 @@
-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
@@ -28,6 +28,9 @@ function checkAttribution(env, target, what) {
         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.`);
@@ -46,6 +49,7 @@ 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)) {
@@ -56,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

@@ -1,6 +1,5 @@
-import type { ConnectionAccount } from "../internal/index.js";
 export interface ConnectUrlOptions {
-    /** The Worker env: `GATEWAY_URL`, which every deployed Worker and `everyapp dev` set. */
+    /** 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;
@@ -9,13 +8,9 @@ export interface ConnectUrlOptions {
      * a path on the Gateway. Absent: Settings → Connected accounts.
      */
     returnTo?: string;
-    /** Whose connection to make: the person's (default) or the organization's (owner or admin). */
-    account?: ConnectionAccount;
-    /** Scope sets to ask for; absent: the union every active app that lists the provider declares. */
-    sets?: readonly string[];
 }
-/** The path of the connect page for `provider` on the Gateway. */
+/** 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 starts the Gateway-owned flow for `provider`. */
-export declare function connectUrl({ env, provider, returnTo, account, sets, }: ConnectUrlOptions): 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

@@ -1 +1 @@
-{"version":3,"file":"connectUrl.d.ts","sourceRoot":"","sources":["../../src/server/connectUrl.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,kGAAkG;IAClG,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,EACzB,GAAG,EACH,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,IAAI,GACL,EAAE,iBAAiB,GAAG,MAAM,CAmB5B"}
+{"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

@@ -1,19 +1,21 @@
 /**
  * Where an app sends a person to connect an OAuth provider the Gateway
- * runs the flow for (docs/design/2026-10-oauth-providers.md section 5):
- * `<gateway>/connect/<id>?return=<back here>&account=<user|organization>`.
- * The Gateway checks the session, asks the provider for the union of the
- * sets every active app declares, 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).
+ * 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 { ConfigurationError } from "../internal/index.js";
-/** The path of the connect page for `provider` on the Gateway. */
+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 starts the Gateway-owned flow for `provider`. */
-export function connectUrl({ env, provider, returnTo, account, sets, }) {
+/** 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()) {
@@ -26,12 +28,13 @@ export function connectUrl({ env, provider, returnTo, account, sets, }) {
     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);
-    if (account)
-        url.searchParams.set("account", account);
-    if (sets && sets.length > 0)
-        url.searchParams.set("sets", sets.join(","));
     return url.toString();
 }

package/dist/server/context.d.ts

@@ -14,9 +14,9 @@ export interface ServedRequest {
  */
 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.
+ * Code `request_context_missing`: a Gateway call with no `for`, outside
+ * any request `everyApp()` serves. Work no request started passes
+ * `for: { background: true }`.
  */
 export declare class RequestContextError extends Error {
     readonly code = "request_context_missing";
@@ -35,20 +35,18 @@ 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.
+ * with no person behind it. The SDK's event delivery (eventsEndpoint.ts)
+ * runs the app's `events.on` under it; apps pass `for` instead. 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.
+ * The verified user of the request being served (`everyApp()` reads it to
+ * reuse one verification): an `EveryAppUser`, or `null` on a public route
+ * and inside `withOrganization()`'s background work. Throws
+ * {@link RequestContextError} outside both.
  */
 export declare function currentUser(): EveryAppUser | null;
 /**

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

@@ -1 +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"}
+{"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;;;;;;;;GAQG;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

@@ -4,17 +4,17 @@
  * `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`.
+ * the verified user and the request the Gateway forwarded. Every call back
+ * to the Gateway made inside it (`integrationFetch`, `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.
+ * Durable Object alarm) has no context of its own: it says whom each call
+ * is for, `for: { background: true }` (a shared app's Worker adds the
+ * `organizationId`). The SDK's own event delivery runs its handler under
+ * `withOrganization()`, which does the same for every call inside it. 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();
@@ -25,9 +25,9 @@ const scopes = new AsyncLocalStorage();
  */
 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.
+ * Code `request_context_missing`: a Gateway call with no `for`, outside
+ * any request `everyApp()` serves. Work no request started passes
+ * `for: { background: true }`.
  */
 export class RequestContextError extends Error {
     code = "request_context_missing";
@@ -54,13 +54,11 @@ export function serveRequest(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.
+ * with no person behind it. The SDK's event delivery (eventsEndpoint.ts)
+ * runs the app's `events.on` under it; apps pass `for` instead. 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() === "") {
@@ -74,15 +72,15 @@ export function withOrganization(organizationId, fn) {
     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.
+ * The verified user of the request being served (`everyApp()` reads it to
+ * reuse one verification): an `EveryAppUser`, or `null` on a public route
+ * and inside `withOrganization()`'s background work. Throws
+ * {@link RequestContextError} outside both.
  */
 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.");
+        throw new RequestContextError("currentUser() was called outside a request everyApp() serves: there is no user here.");
     }
     return scope.served?.user ?? null;
 }
@@ -99,7 +97,7 @@ export function currentUser() {
 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).`);
+        throw new RequestContextError(`${what} was called with no \`for\`, outside a request everyApp() serves: the call would be nobody's. Pass for: request, or for: { background: true } for work no request started (a cron, a Workflow step, a queue consumer).`);
     }
     const served = scope.served;
     if (served?.user) {

package/dist/server/eventsEndpoint.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The app side of the `app` event sink (docs/design/2026-11-birds-decisions/app-event-sink.md).
+ *
+ * `everyApp()` answers the reserved `POST /__everyapp/events` here, before
+ * any app code runs and whether or not the app passed `events`:
+ *
+ *  - the request needs the Gateway's system token for this app (purpose
+ *    `events.deliver`), whose `bh` claim is the SHA-256 of this exact body,
+ *    so a token opens one delivery and nothing else;
+ *  - the envelope must name the organization this Worker serves
+ *    (`EVERY_APP_ORG_ID`), when it is pinned;
+ *  - only then is `events.on` called, under `withOrganization()`, so every
+ *    Gateway call it makes is that organization's background work.
+ *
+ * The perimeter refuses the path from outside and strips inbound
+ * `x-everyapp-*` headers, so only the Gateway's event bus reaches it, over
+ * the service binding.
+ */
+import { type AppEventEnvelope, type RequestIdentityOptions } from "../internal/index.js";
+import type { ExecutionContextLike } from "./everyApp.js";
+/** One event the Gateway delivered: the webhook envelope, plus the delivery's id and attempt. */
+export interface AppEvent extends AppEventEnvelope {
+    delivery: {
+        id: string;
+        attempt: number;
+    };
+}
+export type AppEventHandler<TEnv = unknown> = (event: AppEvent, env: TEnv, ctx: ExecutionContextLike) => unknown | Promise<unknown>;
+/**
+ * `everyApp(handler, { events: { on } })`. `on` is one function for every
+ * event, or one per exact type (`"member.removed"`). An event with no
+ * handler is acknowledged and dropped. A handler that throws answers 500,
+ * and the Gateway retries the delivery with its usual backoff.
+ */
+export interface AppEventsOptions<TEnv = unknown> {
+    on: AppEventHandler<TEnv> | Partial<Record<string, AppEventHandler<TEnv>>>;
+}
+export interface EventsEndpointOptions {
+    events?: AppEventsOptions<never>;
+    /** How to verify the Gateway's token (keys, issuer, audience, dev opt-in). */
+    identity: RequestIdentityOptions;
+}
+/**
+ * Answer a request to the reserved events path, or return null for any
+ * other path so the app's own handler runs.
+ */
+export declare function handleEventsRequest(request: Request, env: unknown, ctx: ExecutionContextLike, options: EventsEndpointOptions): Promise<Response | null>;
+//# sourceMappingURL=eventsEndpoint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"eventsEndpoint.d.ts","sourceRoot":"","sources":["../../src/server/eventsEndpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EASL,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC5B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D,iGAAiG;AACjG,MAAM,WAAW,QAAS,SAAQ,gBAAgB;IAChD,QAAQ,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,MAAM,MAAM,eAAe,CAAC,IAAI,GAAG,OAAO,IAAI,CAC5C,KAAK,EAAE,QAAQ,EACf,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,oBAAoB,KACtB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAAC,IAAI,GAAG,OAAO;IAC9C,EAAE,EAAE,eAAe,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;CAC5E;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACjC,8EAA8E;IAC9E,QAAQ,EAAE,sBAAsB,CAAC;CAClC;AAwCD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,oBAAoB,EACzB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA4F1B"}

package/dist/server/eventsEndpoint.js

@@ -0,0 +1,145 @@
+/**
+ * The app side of the `app` event sink (docs/design/2026-11-birds-decisions/app-event-sink.md).
+ *
+ * `everyApp()` answers the reserved `POST /__everyapp/events` here, before
+ * any app code runs and whether or not the app passed `events`:
+ *
+ *  - the request needs the Gateway's system token for this app (purpose
+ *    `events.deliver`), whose `bh` claim is the SHA-256 of this exact body,
+ *    so a token opens one delivery and nothing else;
+ *  - the envelope must name the organization this Worker serves
+ *    (`EVERY_APP_ORG_ID`), when it is pinned;
+ *  - only then is `events.on` called, under `withOrganization()`, so every
+ *    Gateway call it makes is that organization's background work.
+ *
+ * The perimeter refuses the path from outside and strips inbound
+ * `x-everyapp-*` headers, so only the Gateway's event bus reaches it, over
+ * the service binding.
+ */
+import { APP_EVENTS_PATH, ConfigurationError, EVENT_HEADERS, IdentityError, SYSTEM_HEADER, bodyHash, resolveVerifyOptions, verifySystemJwt, } from "../internal/index.js";
+import { withOrganization } from "./context.js";
+/** The most body the endpoint reads: an envelope's data is at most 16 KiB. */
+const MAX_BODY_BYTES = 64 * 1024;
+function answer(status, body) {
+    return Response.json(body, {
+        status,
+        headers: { "cache-control": "no-store" },
+    });
+}
+function isEnvelope(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const v = value;
+    const org = v.organization;
+    return (typeof v.id === "string" &&
+        typeof v.type === "string" &&
+        typeof v.version === "number" &&
+        typeof v.time === "string" &&
+        !!org &&
+        typeof org === "object" &&
+        typeof org.id === "string" &&
+        !!v.data &&
+        typeof v.data === "object" &&
+        !Array.isArray(v.data));
+}
+function handlerFor(on, type) {
+    if (typeof on === "function")
+        return on;
+    return Object.prototype.hasOwnProperty.call(on, type) ? on[type] : undefined;
+}
+/**
+ * Answer a request to the reserved events path, or return null for any
+ * other path so the app's own handler runs.
+ */
+export async function handleEventsRequest(request, env, ctx, options) {
+    const { pathname } = new URL(request.url);
+    if (pathname !== APP_EVENTS_PATH)
+        return null;
+    if (request.method !== "POST") {
+        return answer(405, { error: "method_not_allowed" });
+    }
+    let verify;
+    try {
+        verify = resolveVerifyOptions(options.identity);
+    }
+    catch (error) {
+        if (error instanceof ConfigurationError) {
+            console.error(error);
+            return answer(500, { error: "misconfigured", message: error.message });
+        }
+        throw error;
+    }
+    let claims;
+    try {
+        claims = await verifySystemJwt(request.headers.get(SYSTEM_HEADER) ?? "", {
+            ...verify,
+            purpose: "events.deliver",
+        });
+    }
+    catch (error) {
+        if (error instanceof IdentityError) {
+            return answer(401, { error: "unauthenticated", message: error.message });
+        }
+        throw error;
+    }
+    const declared = Number(request.headers.get("content-length") ?? "0");
+    if (declared > MAX_BODY_BYTES) {
+        return answer(413, { error: "too_large" });
+    }
+    const body = await request.text();
+    if (body.length > MAX_BODY_BYTES) {
+        return answer(413, { error: "too_large" });
+    }
+    // The token was minted for this exact body: another body, even one the
+    // Gateway sent, is refused.
+    if (claims.bh !== (await bodyHash(body))) {
+        return answer(401, {
+            error: "unauthenticated",
+            message: "the token was minted for another delivery",
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (!isEnvelope(parsed)) {
+        return answer(400, { error: "invalid_request" });
+    }
+    const pinned = options.identity.organizationId;
+    if (pinned && parsed.organization.id !== pinned) {
+        return answer(403, {
+            error: "forbidden",
+            message: `the event is for organization "${parsed.organization.id}", and this Worker serves "${pinned}"`,
+        });
+    }
+    if (!options.events) {
+        // The manifest subscribes, but the Worker passes no `events` to
+        // everyApp(): say so, and let the Gateway retry once it does.
+        return answer(404, {
+            error: "no_handler",
+            message: "everyApp() was given no events: { on }",
+        });
+    }
+    const handler = handlerFor(options.events.on, parsed.type);
+    if (!handler)
+        return answer(200, { ok: true, handled: false });
+    const event = {
+        ...parsed,
+        delivery: {
+            id: request.headers.get(EVENT_HEADERS.delivery) ?? "",
+            attempt: Number(request.headers.get(EVENT_HEADERS.attempt) ?? "0") || 0,
+        },
+    };
+    try {
+        await withOrganization(parsed.organization.id, () => handler(event, env, ctx));
+    }
+    catch (error) {
+        console.error(error);
+        return answer(500, { error: "handler_failed" });
+    }
+    return answer(200, { ok: true, handled: true });
+}