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

package/dist/server/listMembers.d.ts

@@ -0,0 +1,32 @@
+import { type ListMembersResult } from "../internal/index.js";
+import { type GatewayCallFor } from "./attribution.js";
+export interface ListMembersOptions {
+    /** The Worker env: the EVERY_APP_GATEWAY binding when deployed; EVERYAPP_DEV in local dev. */
+    env: object;
+    /**
+     * Whom the list is for: the inbound request (its user), or
+     * `{ background: true, organizationId }` for work no person started (a
+     * cron sending reports). 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 organization's members who can open the app now, through the
+ * gateway's `members` capability: people deactivated, removed from the
+ * organization or (for an organization's own app) not granted the app are
+ * left out. Read it when acting for members who aren't in a request, such
+ * as choosing whom a scheduled report goes to, instead of a copy the app
+ * kept. The app lists `capabilities: { members: { access: "read" } }`.
+ *
+ * Throws {@link GatewayRefusalError} when the gateway won't list
+ * (`capability_not_requested`, `integration_agent_not_allowed` for an
+ * agent's tool call, ...).
+ *
+ * In local dev (`everyapp dev`, no binding) there is no directory: a call
+ * for a request answers its signed-in user alone, and background work
+ * answers no one.
+ */
+export declare function listMembers({ env, for: explicitTarget, }: ListMembersOptions): Promise<ListMembersResult>;
+//# sourceMappingURL=listMembers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"listMembers.d.ts","sourceRoot":"","sources":["../../src/server/listMembers.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAS1B,MAAM,WAAW,kBAAkB;IACjC,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;CACtB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAAC,EAChC,GAAG,EACH,GAAG,EAAE,cAAc,GACpB,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAkBjD"}

package/dist/server/listMembers.js

@@ -0,0 +1,71 @@
+import { ConfigurationError, serviceRoutePath, } from "../internal/index.js";
+import { applyAttribution, attributionFor, isRequest, } from "./attribution.js";
+import { getEveryAppUser } from "./everyApp.js";
+import { BINDING_ORIGIN, gatewayBinding, } from "./gatewayFetch.js";
+import { GatewayRefusalError, gatewayRefusal } from "./refusal.js";
+/**
+ * The organization's members who can open the app now, through the
+ * gateway's `members` capability: people deactivated, removed from the
+ * organization or (for an organization's own app) not granted the app are
+ * left out. Read it when acting for members who aren't in a request, such
+ * as choosing whom a scheduled report goes to, instead of a copy the app
+ * kept. The app lists `capabilities: { members: { access: "read" } }`.
+ *
+ * Throws {@link GatewayRefusalError} when the gateway won't list
+ * (`capability_not_requested`, `integration_agent_not_allowed` for an
+ * agent's tool call, ...).
+ *
+ * In local dev (`everyapp dev`, no binding) there is no directory: a call
+ * for a request answers its signed-in user alone, and background work
+ * answers no one.
+ */
+export async function listMembers({ env, for: explicitTarget, }) {
+    const target = attributionFor(env, explicitTarget, "listMembers");
+    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 listThroughGateway(binding, target);
+    }
+    if (!values["EVERYAPP_DEV"]) {
+        throw new ConfigurationError("Members are unavailable: deploy with the EVERY_APP_GATEWAY binding (everyapp deploy), or run under everyapp dev.");
+    }
+    return listInDev(env, target);
+}
+async function listThroughGateway(binding, target) {
+    const headers = new Headers();
+    applyAttribution(headers, target);
+    const response = await binding.fetch(new Request(`${BINDING_ORIGIN}${serviceRoutePath("members", "list")}`, {
+        method: "GET",
+        headers,
+    }));
+    const refusal = await gatewayRefusal(response);
+    if (refusal)
+        throw new GatewayRefusalError(refusal);
+    if (!response.ok) {
+        throw new GatewayRefusalError({
+            status: response.status,
+            code: "members_list_failed",
+            message: `The EveryApp gateway answered ${response.status} to the members list.`,
+        });
+    }
+    return (await response.json());
+}
+/** The dev gateway has one person: the request's, if the call is for one. */
+async function listInDev(env, target) {
+    const user = target && isRequest(target) ? await getEveryAppUser(target, env) : null;
+    if (!user)
+        return { members: [] };
+    return {
+        members: [
+            {
+                id: user.id,
+                email: user.email,
+                name: "",
+                role: user.orgRole,
+            },
+        ],
+    };
+}

package/dist/server/nodeServer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `nodeServerHandler()` — serve a Node HTTP framework (Express, NestJS, or
+ * anything on `node:http`) from an Every App Worker, through workerd's
+ * `cloudflare:node` bridge:
+ *
+ *   export default everyApp(
+ *     nodeServerHandler({
+ *       boot: async () => {
+ *         const app = await NestFactory.create(AppModule);
+ *         await app.listen(0);
+ *         return { port: app.getHttpServer().address().port };
+ *       },
+ *     }),
+ *   );
+ *
+ * `everyApp()` verifies the identity before the Node app sees the request,
+ * which still carries it as `x-everyapp-identity`. The bridge needs
+ * `nodejs_compat` and a compatibility date from 2025-09-01, which every
+ * `everyAppWorker()` has. See "Node frameworks" in the README for the rules
+ * such a Worker must follow (minify it, no work at module scope).
+ */
+import type { EveryAppHandler } from "./everyApp.js";
+/** A booted Node server: the port its `http.Server` listens on. */
+export interface NodeServer {
+    port: number;
+}
+export interface NodeServerHandlerOptions<TEnv> {
+    /**
+     * Start the server and return the port it listens on, e.g. `await
+     * app.listen(0)` and then `app.getHttpServer().address().port`. Port 0
+     * lets workerd pick one; a fixed port is still held by the server of the
+     * module graph a Vite reload replaced, in the same isolate. Runs once per
+     * isolate, on its first request rather than at module scope; requests
+     * that arrive meanwhile wait for it, and a failed boot is retried on the
+     * next request.
+     */
+    boot(env: TEnv): Promise<NodeServer>;
+}
+/**
+ * A handler for `everyApp()` that hands each request to the Node server
+ * `boot` started. On the way back it drops `Set-Cookie` (the gateway owns
+ * the session, and strips cookies from what reaches the app), and passes a
+ * body Node already encoded (`content-encoding`, e.g. from `compression()`)
+ * through as is: the bridge would let workerd encode it again, and clients
+ * would get unreadable bytes.
+ */
+export declare function nodeServerHandler<TEnv = Record<string, unknown>>(options: NodeServerHandlerOptions<TEnv>): EveryAppHandler<TEnv>;
+//# sourceMappingURL=nodeServer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nodeServer.d.ts","sourceRoot":"","sources":["../../src/server/nodeServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,wBAAwB,CAAC,IAAI;IAC5C;;;;;;;;OAQG;IACH,IAAI,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACtC;AAKD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,OAAO,EAAE,wBAAwB,CAAC,IAAI,CAAC,GACtC,eAAe,CAAC,IAAI,CAAC,CAiBvB"}

package/dist/server/nodeServer.js

@@ -0,0 +1,45 @@
+/** Statuses whose responses can't carry a body. */
+const NULL_BODY_STATUSES = new Set([101, 204, 205, 304]);
+/**
+ * A handler for `everyApp()` that hands each request to the Node server
+ * `boot` started. On the way back it drops `Set-Cookie` (the gateway owns
+ * the session, and strips cookies from what reaches the app), and passes a
+ * body Node already encoded (`content-encoding`, e.g. from `compression()`)
+ * through as is: the bridge would let workerd encode it again, and clients
+ * would get unreadable bytes.
+ */
+export function nodeServerHandler(options) {
+    let booting;
+    const server = (env) => {
+        if (!booting) {
+            const attempt = boot(options, env);
+            booting = attempt;
+            attempt.catch(() => {
+                if (booting === attempt)
+                    booting = undefined;
+            });
+        }
+        return booting;
+    };
+    return async (request, env) => {
+        const { port, handleAsNodeRequest } = await server(env);
+        return fromNode(await handleAsNodeRequest(port, request));
+    };
+}
+async function boot(options, env) {
+    // Imported here rather than at the top, so that loading the SDK needs no
+    // bridge (Node test runners, Workers on an older compatibility date).
+    const { handleAsNodeRequest } = await import("cloudflare:node");
+    const { port } = await options.boot(env);
+    return { port, handleAsNodeRequest };
+}
+function fromNode(response) {
+    const headers = new Headers(response.headers);
+    headers.delete("set-cookie");
+    return new Response(NULL_BODY_STATUSES.has(response.status) ? null : response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+        ...(headers.has("content-encoding") ? { encodeBody: "manual" } : {}),
+    });
+}

package/dist/server/refusal.d.ts

@@ -0,0 +1,55 @@
+/** What would make it work, as the Gateway words it. */
+export interface SetupInfo {
+    /** The Gateway settings it needs (`["DATAFORSEO_API_KEY"]`); `[]` when ready or not a setting. */
+    settings: readonly string[];
+    /** One sentence for a person, naming what to set and how; null when ready. */
+    setup: string | null;
+    /** The command an admin runs (`pnpm everyapp configure crm`), or null. */
+    command: string | null;
+}
+/** A refusal the AppGateway binding made itself, not the provider. */
+export interface GatewayRefusal extends SetupInfo {
+    status: number;
+    /** e.g. `capability_not_requested`, `integration_not_configured`. */
+    code: string;
+    message: string;
+}
+/** The refusal codes that mean no model is set up for the call. */
+export declare const AI_NOT_CONFIGURED_CODES: readonly string[];
+/**
+ * A refusal the AppGateway binding made, thrown: what `sendEmail()` throws
+ * when the gateway won't send (`email_sender_not_allowed`,
+ * `email_budget_exhausted`, ...). The thrown twin of {@link gatewayRefusal}.
+ */
+export declare class GatewayRefusalError extends Error implements GatewayRefusal {
+    readonly status: number;
+    readonly code: string;
+    readonly settings: readonly string[];
+    readonly setup: string | null;
+    readonly command: string | null;
+    constructor({ status, code, message, settings, setup, command, }: Pick<GatewayRefusal, "status" | "code" | "message"> & Partial<SetupInfo>);
+}
+/**
+ * The gateway's own refusal in `response`, or null when the response is the
+ * provider's answer (which may be an error of its own). Reads the body only
+ * for a refusal, so call it before reading the body yourself.
+ */
+export declare function gatewayRefusal(response: Response): Promise<GatewayRefusal | null>;
+/**
+ * The Gateway's refusal behind a thrown error, or null when it isn't one:
+ * a {@link GatewayRefusalError} (`sendEmail()`, `listMembers()`, `emit()`),
+ * an OpenAI SDK `APIError` or an ai-sdk `APICallError` for a call the
+ * Gateway refused (also inside ai-sdk's `RetryError` or an error's
+ * `cause`), or the SDK's local-development `ConfigurationError` for a
+ * missing key, which answers as the deployed refusal would
+ * (`ai_provider_not_configured`, status 503, the `.dev.vars` names).
+ */
+export declare function refusalFromError(error: unknown): GatewayRefusal | null;
+/**
+ * Whether `error` (or a refusal already read) means no model is set up:
+ * `ai_provider_not_configured` or `ai_default_not_configured`, from the
+ * Gateway or, in local development, from the SDK with no key in
+ * `.dev.vars`. Show `refusalFromError(error).setup` to the person.
+ */
+export declare function isAiNotConfigured(error: unknown): boolean;
+//# sourceMappingURL=refusal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.d.ts","sourceRoot":"","sources":["../../src/server/refusal.ts"],"names":[],"mappings":"AAgBA,wDAAwD;AACxD,MAAM,WAAW,SAAS;IACxB,kGAAkG;IAClG,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,8EAA8E;IAC9E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,sEAAsE;AACtE,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mEAAmE;AACnE,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAGpD,CAAC;AAEF;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAM,YAAW,cAAc;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEpB,EACV,MAAM,EACN,IAAI,EACJ,OAAO,EACP,QAAa,EACb,KAAY,EACZ,OAAc,GACf,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC;CAS5E;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAKhC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAWtE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGzD"}

package/dist/server/refusal.js

@@ -0,0 +1,193 @@
+/**
+ * The Gateway's own refusals, read the same way wherever they surface: a
+ * `Response` from a gateway fetch ({@link gatewayRefusal}), the error an
+ * SDK helper throws ({@link GatewayRefusalError}), or the error an AI
+ * client throws for a refused call (an OpenAI SDK's `APIError`, ai-sdk's
+ * `APICallError`) ({@link refusalFromError}).
+ *
+ * A refusal that means "not set up" (`integration_not_configured`,
+ * `ai_provider_not_configured`, `ai_default_not_configured`) carries what
+ * to do in the Gateway's words: `settings` (the setting names it needs),
+ * `setup` (one sentence for a person) and `command` (what an admin runs,
+ * `pnpm everyapp configure <app>`, or null). Show them as they are; never
+ * match the message text or hardcode a setting name or a command.
+ */
+import { ConfigurationError, GATEWAY_ERROR_HEADER } from "../internal/index.js";
+/** The refusal codes that mean no model is set up for the call. */
+export const AI_NOT_CONFIGURED_CODES = [
+    "ai_provider_not_configured",
+    "ai_default_not_configured",
+];
+/**
+ * A refusal the AppGateway binding made, thrown: what `sendEmail()` throws
+ * when the gateway won't send (`email_sender_not_allowed`,
+ * `email_budget_exhausted`, ...). The thrown twin of {@link gatewayRefusal}.
+ */
+export class GatewayRefusalError extends Error {
+    status;
+    code;
+    settings;
+    setup;
+    command;
+    constructor({ status, code, message, settings = [], setup = null, command = null, }) {
+        super(message);
+        this.name = "GatewayRefusalError";
+        this.status = status;
+        this.code = code;
+        this.settings = settings;
+        this.setup = setup;
+        this.command = command;
+    }
+}
+/**
+ * The gateway's own refusal in `response`, or null when the response is the
+ * provider's answer (which may be an error of its own). Reads the body only
+ * for a refusal, so call it before reading the body yourself.
+ */
+export async function gatewayRefusal(response) {
+    const code = response.headers.get(GATEWAY_ERROR_HEADER);
+    if (!code)
+        return null;
+    const body = await response.json().catch(() => null);
+    return refusalOf(response.status, code, body);
+}
+/**
+ * The Gateway's refusal behind a thrown error, or null when it isn't one:
+ * a {@link GatewayRefusalError} (`sendEmail()`, `listMembers()`, `emit()`),
+ * an OpenAI SDK `APIError` or an ai-sdk `APICallError` for a call the
+ * Gateway refused (also inside ai-sdk's `RetryError` or an error's
+ * `cause`), or the SDK's local-development `ConfigurationError` for a
+ * missing key, which answers as the deployed refusal would
+ * (`ai_provider_not_configured`, status 503, the `.dev.vars` names).
+ */
+export function refusalFromError(error) {
+    const seen = new Set();
+    let current = error;
+    while (current && typeof current === "object" && !seen.has(current)) {
+        seen.add(current);
+        const found = refusalHere(current);
+        if (found)
+            return found;
+        const record = current;
+        current = record["lastError"] ?? record["cause"];
+    }
+    return null;
+}
+/**
+ * Whether `error` (or a refusal already read) means no model is set up:
+ * `ai_provider_not_configured` or `ai_default_not_configured`, from the
+ * Gateway or, in local development, from the SDK with no key in
+ * `.dev.vars`. Show `refusalFromError(error).setup` to the person.
+ */
+export function isAiNotConfigured(error) {
+    const refusal = isRefusal(error) ? error : refusalFromError(error);
+    return refusal !== null && AI_NOT_CONFIGURED_CODES.includes(refusal.code);
+}
+function isRefusal(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        !(value instanceof Error) &&
+        typeof value.code === "string" &&
+        typeof value.status === "number");
+}
+function refusalHere(error) {
+    // A Response is read with gatewayRefusal(), which can read its body.
+    if (error instanceof Response)
+        return null;
+    if (error instanceof GatewayRefusalError) {
+        return {
+            status: error.status,
+            code: error.code,
+            message: error.message,
+            settings: error.settings,
+            setup: error.setup,
+            command: error.command,
+        };
+    }
+    if (error instanceof ConfigurationError) {
+        if (!error.code)
+            return null;
+        return {
+            status: 503,
+            code: error.code,
+            message: error.message,
+            settings: error.settings,
+            setup: error.message,
+            command: null,
+        };
+    }
+    const record = error;
+    // ai-sdk's APICallError: lowercase header names, the body as text.
+    const responseHeaders = record["responseHeaders"];
+    if (responseHeaders && typeof responseHeaders === "object") {
+        const code = headerOf(responseHeaders, GATEWAY_ERROR_HEADER);
+        if (!code)
+            return null;
+        return refusalOf(numberOf(record["statusCode"]), code, parseJson(record["responseBody"]), messageOf(error));
+    }
+    // An OpenAI SDK APIError: `headers` (Headers or a record), `status`,
+    // and `error`, the body's `error` object (which carries the same fields).
+    const headers = record["headers"];
+    if (headers && typeof headers === "object" && "status" in record) {
+        const code = headerOf(headers, GATEWAY_ERROR_HEADER);
+        if (!code)
+            return null;
+        return refusalOf(numberOf(record["status"]), code, record["error"], messageOf(error));
+    }
+    return null;
+}
+/** A refusal from its status, code and body (the Gateway's `{ code, message, … }`, or OpenAI's `{ error: {…} }`). */
+function refusalOf(status, code, body, fallback) {
+    const top = recordOf(body);
+    const inner = recordOf(top?.["error"]);
+    const field = (name) => top?.[name] ?? inner?.[name];
+    const message = stringOf(top?.["message"]) ??
+        stringOf(inner?.["message"]) ??
+        fallback ??
+        `The EveryApp gateway refused the call (${code}).`;
+    const settings = field("settings");
+    return {
+        status,
+        code,
+        message,
+        settings: Array.isArray(settings)
+            ? settings.filter((name) => typeof name === "string")
+            : [],
+        setup: stringOf(field("setup")) ?? null,
+        command: stringOf(field("command")) ?? null,
+    };
+}
+function headerOf(headers, name) {
+    if (typeof headers.get === "function") {
+        return headers.get(name);
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === name && typeof value === "string")
+            return value;
+    }
+    return null;
+}
+function recordOf(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringOf(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
+function numberOf(value) {
+    return typeof value === "number" ? value : 0;
+}
+function parseJson(value) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+function messageOf(error) {
+    return error instanceof Error && error.message ? error.message : undefined;
+}

package/dist/server/sendEmail.d.ts

@@ -0,0 +1,39 @@
+import { type SendEmailMessage, type SendEmailResult } from "../internal/index.js";
+import { type GatewayCallFor } from "./attribution.js";
+export interface SendEmailOptions {
+    /**
+     * The Worker env: the EVERY_APP_GATEWAY binding when deployed; in local
+     * dev EVERYAPP_DEV, EVERYAPP_EMAIL_SENDERS in `.dev.vars` for the senders
+     * a `from` may name, and optionally EMAIL_REST_API_TOKEN,
+     * CLOUDFLARE_ACCOUNT_ID and EMAIL_FROM there to really send.
+     */
+    env: object;
+    /**
+     * Whom the mail is for: the inbound request (its user), or
+     * `{ background: true, organizationId }` for work no person started (an
+     * `email()` handler, a cron, a Workflow). 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;
+    message: SendEmailMessage;
+}
+/**
+ * Send an email through the gateway's `email` capability: its sender
+ * (EMAIL_FROM) unless `message.from` names an address the installation's
+ * senders allow (`everyapp email set --sender`; in dev, `.dev.vars`'
+ * EVERYAPP_EMAIL_SENDERS), within the gateway's daily budgets. The app
+ * lists `capabilities: { email: { access: "write" } }`.
+ *
+ * Throws {@link GatewayRefusalError} when the gateway won't send
+ * (`email_sender_not_allowed`, `email_budget_exhausted`,
+ * `integration_not_configured`, ...), with the code and a message to show.
+ *
+ * In local dev (`everyapp dev`, no binding) the message is checked the way
+ * the gateway checks it, then printed and answered `{ status: "logged" }`;
+ * with EMAIL_REST_API_TOKEN, CLOUDFLARE_ACCOUNT_ID and EMAIL_FROM in
+ * `.dev.vars` it goes out for real through Email Sending's REST API, from
+ * the developer's own account.
+ */
+export declare function sendEmail({ env, for: explicitTarget, message, }: SendEmailOptions): Promise<SendEmailResult>;
+//# sourceMappingURL=sendEmail.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sendEmail.d.ts","sourceRoot":"","sources":["../../src/server/sendEmail.ts"],"names":[],"mappings":"AAAA,OAAO,EAeL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAQ1B,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,SAAS,CAAC,EAC9B,GAAG,EACH,GAAG,EAAE,cAAc,EACnB,OAAO,GACR,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkB7C"}

package/dist/server/sendEmail.js

@@ -0,0 +1,114 @@
+import { ConfigurationError, EMAIL_SENDERS_ENV, emailDomain, emailProviderRefusal, emailRestBody, emailRestUrl, emailSenderRefusal, parseEmailList, parseEmailSender, parseSendEmailMessage, readEmailRestResponse, senderAllowed, serviceRoutePath, } from "../internal/index.js";
+import { applyAttribution, attributionFor, } from "./attribution.js";
+import { BINDING_ORIGIN, gatewayBinding, } from "./gatewayFetch.js";
+import { GatewayRefusalError, gatewayRefusal } from "./refusal.js";
+/**
+ * Send an email through the gateway's `email` capability: its sender
+ * (EMAIL_FROM) unless `message.from` names an address the installation's
+ * senders allow (`everyapp email set --sender`; in dev, `.dev.vars`'
+ * EVERYAPP_EMAIL_SENDERS), within the gateway's daily budgets. The app
+ * lists `capabilities: { email: { access: "write" } }`.
+ *
+ * Throws {@link GatewayRefusalError} when the gateway won't send
+ * (`email_sender_not_allowed`, `email_budget_exhausted`,
+ * `integration_not_configured`, ...), with the code and a message to show.
+ *
+ * In local dev (`everyapp dev`, no binding) the message is checked the way
+ * the gateway checks it, then printed and answered `{ status: "logged" }`;
+ * with EMAIL_REST_API_TOKEN, CLOUDFLARE_ACCOUNT_ID and EMAIL_FROM in
+ * `.dev.vars` it goes out for real through Email Sending's REST API, from
+ * the developer's own account.
+ */
+export async function sendEmail({ env, for: explicitTarget, message, }) {
+    const target = attributionFor(env, explicitTarget, "sendEmail");
+    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 sendThroughGateway(binding, target, message);
+    }
+    if (!values["EVERYAPP_DEV"]) {
+        throw new ConfigurationError("Email is unavailable: deploy with the EVERY_APP_GATEWAY binding (everyapp deploy), or run under everyapp dev.");
+    }
+    return sendInDev(values, message);
+}
+async function sendThroughGateway(binding, target, message) {
+    const headers = new Headers({ "content-type": "application/json" });
+    applyAttribution(headers, target);
+    const response = await binding.fetch(new Request(`${BINDING_ORIGIN}${serviceRoutePath("email", "send")}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(message),
+    }));
+    const refusal = await gatewayRefusal(response);
+    if (refusal)
+        throw new GatewayRefusalError(refusal);
+    if (!response.ok) {
+        throw new GatewayRefusalError({
+            status: response.status,
+            code: "email_send_failed",
+            message: `The EveryApp gateway answered ${response.status} to the send.`,
+        });
+    }
+    return (await response.json());
+}
+/**
+ * What the gateway would do, with no gateway: the same checks and sender
+ * rule, then the developer's own Email Sending account or the console.
+ */
+async function sendInDev(values, input) {
+    const parsed = parseSendEmailMessage(input);
+    if (!parsed.ok) {
+        throw new GatewayRefusalError({
+            status: 400,
+            code: "email_invalid_message",
+            message: parsed.problem,
+        });
+    }
+    const message = parsed.message;
+    if (message.from &&
+        !senderAllowed(message.from.address, parseEmailList(values[EMAIL_SENDERS_ENV]))) {
+        throw new GatewayRefusalError({
+            status: 403,
+            code: "email_sender_not_allowed",
+            message: emailSenderRefusal(message.from.address, "dev"),
+        });
+    }
+    const token = stringValue(values["EMAIL_REST_API_TOKEN"]);
+    const accountId = stringValue(values["CLOUDFLARE_ACCOUNT_ID"]);
+    const configuredFrom = stringValue(values["EMAIL_FROM"]);
+    // The gateway needs a name for its sender; a developer's address alone will do.
+    const sender = configuredFrom
+        ? (parseEmailSender(configuredFrom, stringValue(values["EMAIL_FROM_NAME"])) ?? { address: configuredFrom })
+        : null;
+    if (token && accountId && sender) {
+        return sendWithRest(message, message.from ?? sender, token, accountId);
+    }
+    const recipients = message.to.length + message.cc.length + message.bcc.length;
+    console.info(`[everyapp dev] email to ${recipients} recipient${recipients === 1 ? "" : "s"} subject ${JSON.stringify(message.subject)} (not sent: set EMAIL_REST_API_TOKEN, CLOUDFLARE_ACCOUNT_ID and EMAIL_FROM in .dev.vars to send)`);
+    return { status: "logged", messageId: `dev-${crypto.randomUUID()}` };
+}
+async function sendWithRest(message, from, token, accountId) {
+    const response = await fetch(emailRestUrl(accountId), {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${token}`,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(emailRestBody({ ...message, from })),
+    });
+    const body = await response.json().catch(() => null);
+    const result = readEmailRestResponse(response.status, body);
+    if (!result.ok) {
+        throw new GatewayRefusalError(emailProviderRefusal(result.providerCode, emailDomain(from.address)));
+    }
+    return {
+        status: result.status,
+        ...(result.messageId ? { messageId: result.messageId } : {}),
+    };
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}