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

package/dist/server/emailBinding.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `gatewayEmailBinding(env)`: the Gateway's `email` capability as a
+ * `send_email` binding, for code written against `env.EMAIL.send(message)`.
+ *
+ * An app on Every App binds no `send_email` of its own: the Gateway sends
+ * with its sender, checks `from` against the installation's senders and
+ * keeps the mail budgets. Code that already calls `env.EMAIL.send()` gets
+ * this object in its place:
+ *
+ *   const EMAIL = gatewayEmailBinding(env, { for: request });
+ *   await EMAIL.send({ from, to, subject, text });
+ *
+ * Each `send()` is a `sendEmail()` (the manifest lists `capabilities: {
+ * email: { access: "write" } }`), so local development works the same way:
+ * checked and printed, or sent with the developer's own Email Sending
+ * account (EMAIL_REST_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, EMAIL_FROM).
+ */
+import { type SendEmailMessage } from "../internal/index.js";
+import type { GatewayCallFor } from "./attribution.js";
+export interface GatewayEmailBindingOptions {
+    /**
+     * Whom the mail is for: the inbound request, or `{ background: true,
+     * organizationId }` (sendEmail's `for`).
+     */
+    for?: GatewayCallFor;
+}
+/** `name <email>` or a bare address, as the binding takes them. */
+type BindingAddress = string | {
+    email: string;
+    name?: string;
+};
+type BindingRecipients = BindingAddress | BindingAddress[];
+/** The structured message `send_email`'s `send()` takes (`EmailMessageBuilder`). */
+export interface GatewayEmailBindingMessage {
+    from: BindingAddress;
+    to?: BindingRecipients;
+    cc?: BindingRecipients;
+    bcc?: BindingRecipients;
+    subject: string;
+    replyTo?: BindingAddress;
+    headers?: Record<string, string>;
+    text?: string;
+    html?: string;
+    attachments?: {
+        disposition?: "inline" | "attachment";
+        contentId?: string;
+        filename: string;
+        type: string;
+        content: string | ArrayBuffer | ArrayBufferView;
+    }[];
+}
+/**
+ * A `send_email` binding (`SendEmail`) over the Gateway: pass it where code
+ * takes `env.EMAIL`. `send()` takes the structured message (`from`, `to`,
+ * `cc`, `bcc`, `subject`, `text`, `html`, `replyTo`, `headers`,
+ * `attachments`) and resolves `{ messageId }`. A raw MIME `EmailMessage`
+ * (`new EmailMessage(from, to, raw)`) is refused with `GatewayRefusalError`
+ * `email_invalid_message`: the Gateway takes structured mail only.
+ *
+ * Errors are sendEmail()'s: `GatewayRefusalError` with the Gateway's code
+ * (`email_sender_not_allowed`, `email_budget_exhausted`,
+ * `integration_not_configured`, …) and `ConfigurationError` with neither a
+ * binding nor `everyapp dev`. Nothing is checked when the binding is made.
+ */
+export declare function gatewayEmailBinding(env: object, options?: GatewayEmailBindingOptions): SendEmail;
+/**
+ * The binding's message as sendEmail()'s: recipients as bare addresses,
+ * `from` and `replyTo` with their display names, attachments base64.
+ */
+export declare function toSendEmailMessage(message: unknown): SendEmailMessage;
+export {};
+//# sourceMappingURL=emailBinding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emailBinding.d.ts","sourceRoot":"","sources":["../../src/server/emailBinding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIvD,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;CACtB;AAED,mEAAmE;AACnE,KAAK,cAAc,GAAG,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAChE,KAAK,iBAAiB,GAAG,cAAc,GAAG,cAAc,EAAE,CAAC;AAE3D,oFAAoF;AACpF,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,cAAc,CAAC;IACrB,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB,GAAG,CAAC,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE;QACZ,WAAW,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAC;QACtC,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,eAAe,CAAC;KACjD,EAAE,CAAC;CACL;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,0BAA+B,GACvC,SAAS,CAcX;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CA6BrE"}

package/dist/server/emailBinding.js

@@ -0,0 +1,124 @@
+/**
+ * `gatewayEmailBinding(env)`: the Gateway's `email` capability as a
+ * `send_email` binding, for code written against `env.EMAIL.send(message)`.
+ *
+ * An app on Every App binds no `send_email` of its own: the Gateway sends
+ * with its sender, checks `from` against the installation's senders and
+ * keeps the mail budgets. Code that already calls `env.EMAIL.send()` gets
+ * this object in its place:
+ *
+ *   const EMAIL = gatewayEmailBinding(env, { for: request });
+ *   await EMAIL.send({ from, to, subject, text });
+ *
+ * Each `send()` is a `sendEmail()` (the manifest lists `capabilities: {
+ * email: { access: "write" } }`), so local development works the same way:
+ * checked and printed, or sent with the developer's own Email Sending
+ * account (EMAIL_REST_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, EMAIL_FROM).
+ */
+import { ConfigurationError, } from "../internal/index.js";
+import { GatewayRefusalError } from "./refusal.js";
+import { sendEmail } from "./sendEmail.js";
+/**
+ * A `send_email` binding (`SendEmail`) over the Gateway: pass it where code
+ * takes `env.EMAIL`. `send()` takes the structured message (`from`, `to`,
+ * `cc`, `bcc`, `subject`, `text`, `html`, `replyTo`, `headers`,
+ * `attachments`) and resolves `{ messageId }`. A raw MIME `EmailMessage`
+ * (`new EmailMessage(from, to, raw)`) is refused with `GatewayRefusalError`
+ * `email_invalid_message`: the Gateway takes structured mail only.
+ *
+ * Errors are sendEmail()'s: `GatewayRefusalError` with the Gateway's code
+ * (`email_sender_not_allowed`, `email_budget_exhausted`,
+ * `integration_not_configured`, …) and `ConfigurationError` with neither a
+ * binding nor `everyapp dev`. Nothing is checked when the binding is made.
+ */
+export function gatewayEmailBinding(env, options = {}) {
+    const binding = {
+        async send(message) {
+            const result = await sendEmail({
+                env,
+                ...(options.for === undefined ? {} : { for: options.for }),
+                message: toSendEmailMessage(message),
+            });
+            return { messageId: result.messageId ?? "" };
+        },
+    };
+    // `SendEmail` is the app's own Workers types' interface, whose `send()`
+    // overloads change with the version; this `send()` takes both forms.
+    return binding;
+}
+/**
+ * The binding's message as sendEmail()'s: recipients as bare addresses,
+ * `from` and `replyTo` with their display names, attachments base64.
+ */
+export function toSendEmailMessage(message) {
+    if (!message || typeof message !== "object") {
+        throw new ConfigurationError("EMAIL.send() takes a message object.");
+    }
+    if (!("subject" in message)) {
+        throw new GatewayRefusalError({
+            status: 400,
+            code: "email_invalid_message",
+            message: "Raw MIME messages can't be sent through the Every App gateway; send a structured message ({ from, to, subject, text or html }).",
+        });
+    }
+    const m = message;
+    return {
+        to: addresses(m.to) ?? [],
+        ...(m.cc === undefined ? {} : { cc: addresses(m.cc) }),
+        ...(m.bcc === undefined ? {} : { bcc: addresses(m.bcc) }),
+        subject: m.subject,
+        ...(m.text ? { text: m.text } : {}),
+        ...(m.html ? { html: m.html } : {}),
+        from: named(m.from),
+        ...(m.replyTo ? { replyTo: named(m.replyTo) } : {}),
+        ...(m.headers && Object.keys(m.headers).length > 0
+            ? { headers: m.headers }
+            : {}),
+        ...(m.attachments?.length
+            ? { attachments: m.attachments.map(attachment) }
+            : {}),
+    };
+}
+/**
+ * One attachment in the Gateway's shape. An inline part without a content
+ * id can't be referenced (and the Gateway refuses it), so it goes as an
+ * ordinary attachment.
+ */
+function attachment(a) {
+    const contentId = a.contentId?.trim();
+    return {
+        filename: a.filename,
+        contentType: a.type,
+        content: base64(a.content),
+        ...(a.disposition === "inline" && contentId
+            ? { disposition: "inline", contentId }
+            : {}),
+    };
+}
+function named(address) {
+    if (typeof address === "string")
+        return { address };
+    return {
+        address: address.email,
+        ...(address.name?.trim() ? { name: address.name } : {}),
+    };
+}
+function addresses(recipients) {
+    if (recipients === undefined)
+        return undefined;
+    const of = (a) => (typeof a === "string" ? a : a.email);
+    return Array.isArray(recipients) ? recipients.map(of) : of(recipients);
+}
+/** Strings are taken as base64 already, as the binding takes them; bytes are encoded. */
+function base64(content) {
+    if (typeof content === "string")
+        return content;
+    const bytes = content instanceof ArrayBuffer
+        ? new Uint8Array(content)
+        : new Uint8Array(content.buffer, content.byteOffset, content.byteLength);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(binary);
+}

package/dist/server/emit.d.ts

@@ -59,5 +59,5 @@ export interface EmitOptions {
  * the gateway checks it, printed, and answered `{ id: "dev-…", type }`;
  * nothing is delivered.
  */
-export declare function emit({ env, for: target, event, data, }: EmitOptions): Promise<EmitEventResult>;
+export declare function emit({ env, for: explicitTarget, event, data, }: EmitOptions): Promise<EmitEventResult>;
 //# sourceMappingURL=emit.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/server/emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EASL,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAI1B,MAAM,WAAW,WAAW;IAC1B,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,IAAI,CAAC,EACzB,GAAG,EACH,GAAG,EAAE,MAAM,EACX,KAAK,EACL,IAAI,GACL,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAoBxC"}
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/server/emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EASL,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAQ1B,MAAM,WAAW,WAAW;IAC1B,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,IAAI,CAAC,EACzB,GAAG,EACH,GAAG,EAAE,cAAc,EACnB,KAAK,EACL,IAAI,GACL,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAkBxC"}

package/dist/server/emit.js

@@ -9,9 +9,9 @@
  * two can't drift.
  */
 import { APP_EVENT_DATA_MAX_BYTES, APP_ID_ENV, ConfigurationError, EVENTS_EMIT_PATH, appEventNameProblem, appEventType, checkEventData, } from "../internal/index.js";
-import { applyAttribution, checkAttribution, } from "./attribution.js";
-import { BINDING_ORIGIN } from "./gatewayFetch.js";
-import { GatewayRefusalError, gatewayRefusal } from "./integrationFetch.js";
+import { applyAttribution, attributionFor, } from "./attribution.js";
+import { BINDING_ORIGIN, gatewayBinding, } from "./gatewayFetch.js";
+import { GatewayRefusalError, gatewayRefusal } from "./refusal.js";
 /**
  * Put an event on the gateway's event bus, for the organization's webhook
  * and email subscribers. The gateway names it `app.<app id>.<event>`, so an
@@ -36,10 +36,10 @@ import { GatewayRefusalError, gatewayRefusal } from "./integrationFetch.js";
  * the gateway checks it, printed, and answered `{ id: "dev-…", type }`;
  * nothing is delivered.
  */
-export async function emit({ env, for: target, event, data, }) {
-    checkAttribution(env, target, "emit");
+export async function emit({ env, for: explicitTarget, event, data, }) {
+    const target = attributionFor(env, explicitTarget, "emit");
     const values = env;
-    const binding = values["EVERY_APP_GATEWAY"];
+    const binding = gatewayBinding(env);
     if (binding) {
         if (typeof binding.fetch !== "function") {
             throw new ConfigurationError("EVERY_APP_GATEWAY is configured but is not a valid service binding.");
@@ -66,7 +66,7 @@ async function emitThroughGateway(binding, target, body) {
         throw new GatewayRefusalError({
             status: response.status,
             code: "event_emit_failed",
-            message: `The Every App gateway answered ${response.status} to the event.`,
+            message: `The EveryApp gateway answered ${response.status} to the event.`,
         });
     }
     return (await response.json());

package/dist/server/env.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `EveryAppEnv`: what Every App puts in an app Worker's `env`, for an app
+ * that types its env by hand. An app built with `everyAppWorker()` needs
+ * none of it: `cf workers types` writes the same names into `Env` from the
+ * Worker's definition.
+ */
+import type { EveryAppManifest } from "../manifest.js";
+/** The `env` keys Every App sets on an app's Worker, deployed and under `everyapp dev`. */
+export interface EveryAppEnv<M extends EveryAppManifest = EveryAppManifest> {
+    /** The manifest's `id`. */
+    EVERYAPP_APP_ID: string;
+    /**
+     * The manifest (`everyapp.config.ts`) as JSON: what the app asked for,
+     * for a page that shows it. `EveryAppEnv<typeof manifest>` types it as
+     * the app's own.
+     */
+    EVERYAPP_MANIFEST: M;
+    /** The Gateway's URL; links back to it go through `gatewayUrl(env)`. */
+    GATEWAY_URL: string;
+    /** The identity tokens' issuer: the Gateway's URL, or the dev issuer. */
+    EVERYAPP_IDENTITY_ISSUER: string;
+    /** The public keys (JSON array of PEMs) `everyApp()` verifies identities with. */
+    EVERYAPP_IDENTITY_PUBLIC_KEYS: string;
+    /** Deployed: the Worker's name, the identity tokens' audience. */
+    EVERYAPP_AUDIENCE?: string;
+    /** Deployed: the organization the app is installed for. */
+    EVERY_APP_ORG_ID?: string;
+    /** Deployed, on an app installed for every organization: `"1"`. */
+    EVERYAPP_SHARED?: string;
+    /** Deployed: the service binding to the Gateway, which capabilities, AI and email go through. */
+    EVERY_APP_GATEWAY?: Fetcher;
+    /** `"1"` under `everyapp dev`, absent when deployed. */
+    EVERYAPP_DEV?: string;
+    /** Under `everyapp dev`: the manifest's `capabilities`, as JSON, for the SDK's dev fallbacks. */
+    EVERYAPP_DEV_CAPABILITIES?: string;
+    /** Under `everyapp dev`: the app's `.everyapp/providers/*.json`, as JSON. */
+    EVERYAPP_DEV_PROVIDERS?: string;
+    /** Under `everyapp dev`, from `.dev.vars`: the senders standing in for `everyapp email set --sender`. */
+    EVERYAPP_EMAIL_SENDERS?: string;
+    /** Under `everyapp dev --gateway` (linked dev): the gateway-lite's forwarder, which the SDK's services call the real Gateway through, and the run's nonce. */
+    EVERYAPP_LINKED_DEV_URL?: string;
+    EVERYAPP_LINKED_DEV_NONCE?: string;
+}
+//# sourceMappingURL=env.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/server/env.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,2FAA2F;AAC3F,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,gBAAgB,GAAG,gBAAgB;IACxE,2BAA2B;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,iBAAiB,EAAE,CAAC,CAAC;IACrB,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,wBAAwB,EAAE,MAAM,CAAC;IACjC,kFAAkF;IAClF,6BAA6B,EAAE,MAAM,CAAC;IACtC,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iGAAiG;IACjG,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iGAAiG;IACjG,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,6EAA6E;IAC7E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,yGAAyG;IACzG,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,8JAA8J;IAC9J,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC"}

package/dist/server/env.js

@@ -0,0 +1 @@
+export {};

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 });
+}

package/dist/server/everyApp.d.ts

@@ -13,12 +13,24 @@
  * `everyapp.config.ts` (the Cloudflare Vite plugin hides every file
  * `cloudflare.config.ts` imports from the Worker in dev).
  * It also answers the gateway's internal tools contract
- * (`/__everyapp/tools/*`) for the app's `defineTools()` catalog.
+ * (`/__everyapp/tools/*`) for the app's `defineTools()` catalog, and the
+ * event sink's deliveries (`/__everyapp/events`) for `events: { on }`.
+ *
+ * Around the handler and around each tool call it opens the request
+ * context (context.ts): `currentUser()` reads the user anywhere below, and
+ * every call back to the Gateway is attributed to the request without a
+ * `for`. A deployed Worker is pinned to its organization
+ * (`EVERY_APP_ORG_ID`), and an identity for any other is refused on both
+ * paths. The response leaves without `Set-Cookie`: the perimeter strips
+ * every `Cookie` before a request reaches the app, so a cookie the app's
+ * framework sets could never come back, and one named like the Gateway's
+ * session cookie would lock the person out of the app host.
  */
-import { ConfigurationError, IdentityError, type EveryAppUser, type IdentityResult } from "../internal/index.js";
+import { ConfigurationError, IdentityError, isAdmin, isAgentCall, type EveryAppUser, type IdentityResult, type OrgRole } from "../internal/index.js";
 import type { ToolSet } from "./tools.js";
-export { ConfigurationError, IdentityError };
-export type { EveryAppUser, IdentityResult };
+import { type AppEventsOptions } from "./eventsEndpoint.js";
+export { ConfigurationError, IdentityError, isAdmin, isAgentCall };
+export type { EveryAppUser, IdentityResult, OrgRole };
 /**
  * The runtime's `ExecutionContext`, which `everyApp()` passes to the handler
  * as the Worker received it, so it goes on to Hono's `app.fetch(request,
@@ -30,7 +42,7 @@ export interface EveryAppManifestLike {
     id: string;
     [key: string]: unknown;
 }
-export interface EveryAppOptions {
+export interface EveryAppOptions<TEnv = Record<string, unknown>> {
     /** Optional expected issuer (gateway URL). Defaults to env.EVERYAPP_IDENTITY_ISSUER when set. */
     issuer?: string;
     /** Env var holding the public key set. Defaults to EVERYAPP_IDENTITY_PUBLIC_KEYS. */
@@ -47,6 +59,13 @@ export interface EveryAppOptions {
      * and serves them to MCP clients; see `defineTools`.
      */
     tools?: ToolSet;
+    /**
+     * The Gateway's events this app subscribes to (`events.subscribe` in its
+     * manifest), delivered to `on` over the service binding: one function, or
+     * one per type. The SDK verifies the Gateway's `events.deliver` token
+     * before `on` runs.
+     */
+    events?: AppEventsOptions<TEnv>;
     /** Override for tests. */
     now?: number;
 }
@@ -60,22 +79,32 @@ interface EveryAppExport<TEnv, TCtx extends ExecutionContextLike> {
 }
 /**
  * Return the verified Every App user for this request, or null for a declared
- * public request. Uses the request cache first, then verifies the identity
- * headers from the app id and public keys configured in env.
+ * public request. `request` is the inbound `Request` or just its `Headers`
+ * (a framework that hands out headers alone needs no made-up Request).
+ * Answers from the request context or the per-request cache first, then
+ * verifies the identity headers from the audience and public keys in env.
+ * Inside a handler `everyApp()` serves, `currentUser()` is the shorter way.
  */
-export declare function getEveryAppUser(request: Request, env: object): Promise<EveryAppUser | null>;
+export declare function getEveryAppUser(request: Request | Headers, env: object): Promise<EveryAppUser | null>;
 /**
  * Return the verified user, or throw the same 401 JSON Response shape as
  * everyApp() when the request is public or unauthenticated.
  */
-export declare function requireEveryAppUser(request: Request, env: object): Promise<EveryAppUser>;
+export declare function requireEveryAppUser(request: Request | Headers, env: object): Promise<EveryAppUser>;
+/**
+ * The user of the request being served (`currentUser()`), or throw the
+ * same 401 JSON Response as `requireEveryAppUser()` on a public route.
+ * Outside a request (`withOrganization()` work, a handler not under
+ * `everyApp()`) it throws `RequestContextError`, as `currentUser()` does.
+ */
+export declare function requireCurrentUser(): EveryAppUser;
 export declare function hasScope(user: EveryAppUser, scope: string): boolean;
 /** Wrap a Worker fetch handler with Every App identity verification. */
-export declare function everyApp<TEnv = Record<string, unknown>, TCtx extends ExecutionContextLike = ExecutionContext>(handler: EveryAppHandler<TEnv, TCtx>, options?: EveryAppOptions): EveryAppExport<TEnv, TCtx>;
+export declare function everyApp<TEnv = Record<string, unknown>, TCtx extends ExecutionContextLike = ExecutionContext>(handler: EveryAppHandler<TEnv, TCtx>, options?: EveryAppOptions<TEnv>): EveryAppExport<TEnv, TCtx>;
 /**
  * @deprecated Drop the manifest: the app id now comes from
  *   `env.EVERYAPP_APP_ID` and the audience from `env.EVERYAPP_AUDIENCE`.
  *   When passed, it must match the app id.
  */
-export declare function everyApp<TEnv = Record<string, unknown>, TCtx extends ExecutionContextLike = ExecutionContext>(handler: EveryAppHandler<TEnv, TCtx>, manifest: EveryAppManifestLike | undefined, options?: EveryAppOptions): EveryAppExport<TEnv, TCtx>;
+export declare function everyApp<TEnv = Record<string, unknown>, TCtx extends ExecutionContextLike = ExecutionContext>(handler: EveryAppHandler<TEnv, TCtx>, manifest: EveryAppManifestLike | undefined, options?: EveryAppOptions<TEnv>): EveryAppExport<TEnv, TCtx>;
 //# sourceMappingURL=everyApp.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"everyApp.d.ts","sourceRoot":"","sources":["../../src/server/everyApp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAGL,kBAAkB,EAElB,aAAa,EAIb,KAAK,YAAY,EACjB,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0BAA0B;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,CACzB,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,SAAS,oBAAoB,GAAG,gBAAgB,IAClD,CACF,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,IAAI,EACT,IAAI,EAAE,YAAY,GAAG,IAAI,KACtB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC,UAAU,cAAc,CAAC,IAAI,EAAE,IAAI,SAAS,oBAAoB;IAC9D,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAClE;AAoHD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAS9B;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,YAAY,CAAC,CAevB;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnE;AAUD,wEAAwE;AACxE,wBAAgB,QAAQ,CACtB,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,SAAS,oBAAoB,GAAG,gBAAgB,EAEpD,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,EACpC,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC9B;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,SAAS,oBAAoB,GAAG,gBAAgB,EAEpD,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,EACpC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC"}
+{"version":3,"file":"everyApp.d.ts","sourceRoot":"","sources":["../../src/server/everyApp.ts"],"names":[],"mappings":"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"}