@every-app/sdk 0.2.0 → 0.3.0-rc.10

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

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

@@ -0,0 +1,63 @@
+/**
+ * `emit()`: an app's own event onto the gateway's event bus
+ * (docs/design/2026-10-events-out.md, section 7). It is shaped like
+ * `sendEmail()` on purpose: the same `{ env, for }` attribution, the same
+ * route over the EVERY_APP_GATEWAY binding, the same refusals thrown as
+ * `GatewayRefusalError`, and the same local-dev twin that checks what the
+ * gateway would check and prints instead of sending. The name and data
+ * rules live in `internal/events.ts`, which the gateway reads too, so the
+ * two can't drift.
+ */
+import { type EmitEventResult } from "../internal/index.js";
+import { type GatewayCallFor } from "./attribution.js";
+export interface EmitOptions {
+    /** The Worker env: the EVERY_APP_GATEWAY binding when deployed; EVERYAPP_DEV in local dev. */
+    env: object;
+    /**
+     * Whom the event is about: the inbound request (its user becomes the
+     * event's actor), or `{ background: true, organizationId }` for work no
+     * person started (a cron, a queue, a provider's webhook). An
+     * organization's own app may omit it for background work; a shared app's
+     * Worker must pass one or the other ({@link AttributionError}).
+     */
+    for?: GatewayCallFor;
+    /**
+     * The app's own name for what happened: lowercase letters, digits and
+     * underscores in dotted segments (`invoice.paid`, `todo.completed`), at
+     * most 64 characters. The gateway delivers it as `app.<app id>.<event>`.
+     */
+    event: string;
+    /**
+     * What a subscriber needs to act on it: a JSON object, at most 8 KiB
+     * serialized, nested at most 8 levels. Ids, names, amounts and states;
+     * never a credential. A key named like one at any depth (`token`,
+     * `secret`, `password`, `apiKey`, `session`, `cookie`, ...) is refused.
+     */
+    data: Record<string, unknown>;
+}
+/**
+ * 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
+ * app can never emit one of the gateway's own types (`member.joined`);
+ * owners and admins choose `app.<app id>.*` (or one name) in Manage
+ * workspace, Events, or with `everyapp events add`. Nothing is declared in
+ * the manifest. Delivery happens after the call returns: a subscriber that
+ * is down doesn't slow or fail the app.
+ *
+ * `data` goes, as written, to every URL a subscriber chose (Slack, Zapier,
+ * an agent): put in it what a person or a workflow reads, never a
+ * credential, a session or a person's private content they didn't expect
+ * to leave the app. The gateway refuses a key named like a credential.
+ *
+ * Throws {@link GatewayRefusalError} when the gateway won't take it
+ * (`event_name_invalid`, `event_data_invalid`, `event_data_refused`,
+ * `event_data_too_large`, `event_rate_limited` past 600 an hour, ...), with
+ * the code and a message to show. An emit that must never fail the work
+ * around it goes under `ctx.waitUntil()` or a `.catch()`.
+ *
+ * In local dev (`everyapp dev`, no binding) the event is checked the way
+ * the gateway checks it, printed, and answered `{ id: "dev-…", type }`;
+ * nothing is delivered.
+ */
+export declare function emit({ env, for: explicitTarget, event, data, }: EmitOptions): Promise<EmitEventResult>;
+//# sourceMappingURL=emit.d.ts.map

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

@@ -0,0 +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;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

@@ -0,0 +1,101 @@
+/**
+ * `emit()`: an app's own event onto the gateway's event bus
+ * (docs/design/2026-10-events-out.md, section 7). It is shaped like
+ * `sendEmail()` on purpose: the same `{ env, for }` attribution, the same
+ * route over the EVERY_APP_GATEWAY binding, the same refusals thrown as
+ * `GatewayRefusalError`, and the same local-dev twin that checks what the
+ * gateway would check and prints instead of sending. The name and data
+ * rules live in `internal/events.ts`, which the gateway reads too, so the
+ * 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, 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
+ * app can never emit one of the gateway's own types (`member.joined`);
+ * owners and admins choose `app.<app id>.*` (or one name) in Manage
+ * workspace, Events, or with `everyapp events add`. Nothing is declared in
+ * the manifest. Delivery happens after the call returns: a subscriber that
+ * is down doesn't slow or fail the app.
+ *
+ * `data` goes, as written, to every URL a subscriber chose (Slack, Zapier,
+ * an agent): put in it what a person or a workflow reads, never a
+ * credential, a session or a person's private content they didn't expect
+ * to leave the app. The gateway refuses a key named like a credential.
+ *
+ * Throws {@link GatewayRefusalError} when the gateway won't take it
+ * (`event_name_invalid`, `event_data_invalid`, `event_data_refused`,
+ * `event_data_too_large`, `event_rate_limited` past 600 an hour, ...), with
+ * the code and a message to show. An emit that must never fail the work
+ * around it goes under `ctx.waitUntil()` or a `.catch()`.
+ *
+ * In local dev (`everyapp dev`, no binding) the event is checked the way
+ * the gateway checks it, printed, and answered `{ id: "dev-…", type }`;
+ * nothing is delivered.
+ */
+export async function emit({ env, for: explicitTarget, event, data, }) {
+    const target = attributionFor(env, explicitTarget, "emit");
+    const values = env;
+    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.");
+        }
+        return emitThroughGateway(binding, target, { event, data });
+    }
+    if (!values["EVERYAPP_DEV"]) {
+        throw new ConfigurationError("Events are unavailable: deploy with the EVERY_APP_GATEWAY binding (everyapp deploy), or run under everyapp dev.");
+    }
+    return emitInDev(values, { event, data });
+}
+async function emitThroughGateway(binding, target, body) {
+    const headers = new Headers({ "content-type": "application/json" });
+    applyAttribution(headers, target);
+    const response = await binding.fetch(new Request(`${BINDING_ORIGIN}${EVENTS_EMIT_PATH}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    }));
+    const refusal = await gatewayRefusal(response);
+    if (refusal)
+        throw new GatewayRefusalError(refusal);
+    if (!response.ok) {
+        throw new GatewayRefusalError({
+            status: response.status,
+            code: "event_emit_failed",
+            message: `The EveryApp gateway answered ${response.status} to the event.`,
+        });
+    }
+    return (await response.json());
+}
+/**
+ * What the gateway would do, with no gateway: the same name and data
+ * rules, then one line on the console. The data isn't printed: it may hold
+ * a person's content, and the line is for "it fired", not for its payload.
+ */
+function emitInDev(values, { event, data }) {
+    const nameProblem = appEventNameProblem(event);
+    if (nameProblem) {
+        throw new GatewayRefusalError({
+            status: 400,
+            code: "event_name_invalid",
+            message: nameProblem,
+        });
+    }
+    const checked = checkEventData(data, APP_EVENT_DATA_MAX_BYTES);
+    if (!checked.ok) {
+        throw new GatewayRefusalError({
+            status: checked.code === "event_data_too_large" ? 413 : 400,
+            code: checked.code,
+            message: checked.message,
+        });
+    }
+    const appId = values[APP_ID_ENV];
+    // The gateway prefixes the manifest id; a dev env without it still shows the shape.
+    const type = appEventType(typeof appId === "string" && appId.trim() ? appId.trim() : "app", event);
+    console.info(`[everyapp dev] event ${type} (not delivered: no Gateway)`);
+    return { id: `dev-${crypto.randomUUID()}`, type };
+}

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 {};