@pramen/server 0.0.11 → 0.0.12

package/dist/durable-object.js

@@ -17,6 +17,7 @@
 import { DurableObject } from "cloudflare:workers";
 import { migrate } from "./runtime/migrate";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
+import { createMail } from "./runtime/mail";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
 import { Db } from "./runtime/db";
 import { digest } from "./runtime/digest";
@@ -154,7 +155,15 @@ export class PramenDOBase extends DurableObject {
     taskCtx() {
         const identity = { roles: ["admin"] };
         const db = new Db(this.driver, { acl: this.acl, identity, system: true, schema: this.app.schema, partition: this.partition, suppressTriggers: true }, this.app.schema);
-        return { db, kv: this.kv, files: this.filesFor(this.tenant), env: this.envBag, identity, tasks: tasksFacade(this.driver) };
+        return {
+            db,
+            kv: this.kv,
+            files: this.filesFor(this.tenant),
+            env: this.envBag,
+            identity,
+            tasks: tasksFacade(this.driver),
+            mail: createMail(this.envBag, this.kv),
+        };
     }
     /** Restore (tenant, partition) on a cold wake (e.g. an alarm with no request) so the
      * task context is scoped correctly. No-op once loaded/persisted this instance. */

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, JsonValue, Pro
 export type { FileRef, Files, SignUploadOpts, SignDownloadOpts, HeadResult } from "./sdk/files";
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
+export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+export type { MailMessage, MailAddress, MailAdapter, SendEmailBinding } from "./runtime/mail";
 export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
 export { sqliteDialect, postgresDialect, DoSqliteDriver, D1Driver } from "./runtime/driver";
 export type { Driver, Dialect, Row } from "./runtime/driver";

package/dist/index.js

@@ -15,6 +15,8 @@ export { query, mutation } from "./sdk/handlers";
 // --- ACL ---
 export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
+// --- mail (ctx.mail) ---
+export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
 // --- errors ---
 export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
 // --- substrate seam (advanced: bring your own SQL backend) ---

package/dist/runtime/dispatch.js

@@ -11,6 +11,7 @@ import { Db } from "./db";
 import { warmup } from "./acl";
 import { BadRequest } from "./errors";
 import { enqueueTask } from "./outbox";
+import { createMail } from "./mail";
 /** The `ctx.tasks` facade over the outbox. `onEnqueue` lets the caller count enqueues
  * so it can wake the drainer. */
 export function tasksFacade(driver, onEnqueue) {
@@ -48,7 +49,15 @@ export async function dispatch(handlers, schema, driver, kv, files, env, acl, na
     const resolved = await warmup(acl.acl, acl.identity, systemDb);
     const db = new Db(driver, { acl: acl.acl, identity: acl.identity, input: parsed, resolved, schema, partition: acl.partition }, schema);
     let enqueued = 0;
-    const ctx = { db, kv, files, env, identity: acl.identity, tasks: tasksFacade(driver, () => enqueued++) };
+    const ctx = {
+        db,
+        kv,
+        files,
+        env,
+        identity: acl.identity,
+        tasks: tasksFacade(driver, () => enqueued++),
+        mail: createMail(env, kv),
+    };
     const result = handler.kind === "query"
         ? await handler.run(ctx, parsed)
         : await driver.transaction(async () => handler.run(ctx, parsed));

package/dist/runtime/mail.d.ts

@@ -0,0 +1,80 @@
+import type { Kv } from "./kv";
+export interface MailAddress {
+    email: string;
+    name?: string;
+}
+export interface MailMessage {
+    to: string | string[];
+    /** Sender. Optional — defaults to MAIL_FROM (a verified address). */
+    from?: MailAddress;
+    subject: string;
+    text?: string;
+    html?: string;
+    replyTo?: string | MailAddress;
+}
+/** The transport seam. One per backend (Cloudflare Email Sending, a dev stash, …). */
+export interface MailAdapter {
+    /** Deliver a fully-resolved message (`from` already filled by the facade). */
+    send(message: MailMessage & {
+        from: MailAddress;
+    }): Promise<void>;
+}
+/** The `ctx.mail` facade: resolves the sender, validates, and delegates to the adapter. */
+export declare class Mail {
+    private readonly adapter;
+    private readonly defaultFrom?;
+    constructor(adapter: MailAdapter, defaultFrom?: MailAddress | undefined);
+    send(message: MailMessage): Promise<void>;
+}
+/** The Cloudflare `send_email` binding shape (workers binding form: `from` uses `email`). */
+export interface SendEmailBinding {
+    send(message: {
+        to: string | string[];
+        from: MailAddress;
+        subject: string;
+        text?: string;
+        html?: string;
+        replyTo?: string | MailAddress;
+    }): Promise<void>;
+}
+/** Cloudflare Email Sending — sends via the `send_email` binding (no API keys). The
+ * `from` domain must be onboarded (`wrangler email sending enable yourdomain.com`). */
+export declare class CloudflareEmailAdapter implements MailAdapter {
+    private readonly binding;
+    constructor(binding: SendEmailBinding);
+    send(message: MailMessage & {
+        from: MailAddress;
+    }): Promise<void>;
+}
+/** Dev/test transport: stash the message in KV under `mail:<recipient>` so an e2e suite
+ * (or a dashboard) can read the "inbox" instead of really sending. */
+export declare class KvMailAdapter implements MailAdapter {
+    private readonly kv;
+    constructor(kv: Kv);
+    send(message: MailMessage & {
+        from: MailAddress;
+    }): Promise<void>;
+}
+/** In-memory transport: captures sent messages (pure; for unit tests). */
+export declare class MemoryMailAdapter implements MailAdapter {
+    readonly sent: Array<MailMessage & {
+        from: MailAddress;
+    }>;
+    send(message: MailMessage & {
+        from: MailAddress;
+    }): Promise<void>;
+}
+/** Fail-closed transport: no real sender and no explicit dev-capture opt-in, so a
+ * `send` THROWS rather than silently capturing. Prevents a misconfigured production
+ * (no MAIL_FROM) from writing security emails — magic-link tokens, resets — into KV
+ * instead of delivering them. Mirrors how files fail closed without FILES_SECRET. */
+export declare class UnconfiguredMailAdapter implements MailAdapter {
+    send(): Promise<void>;
+}
+/** Build `ctx.mail` from the environment:
+ *  - `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
+ *  - else `MAIL_CAPTURE=true` → capture (KV inbox if a Kv is given, else in-memory) with
+ *    a synthetic dev sender — an EXPLICIT dev opt-in, never the production default.
+ *  - else → fail closed: a `send` throws (so a missing-MAIL_FROM prod doesn't silently
+ *    stash security emails in KV). */
+export declare function createMail(env: Readonly<Record<string, unknown>>, kv?: Kv): Mail;

package/dist/runtime/mail.js

@@ -0,0 +1,102 @@
+// ctx.mail — transactional-ish email facade, the same shape as ctx.files: an adapter
+// seam (CloudflareEmailAdapter / KvMailAdapter / MemoryMailAdapter) behind a thin
+// `Mail` facade, chosen from the environment. Handlers send mail without touching the
+// `send_email` binding directly:
+//
+//   await ctx.mail.send({ to: "u@x.com", subject: "Welcome", text: "…" });
+//
+// On Cloudflare the transport is Cloudflare Email Sending (the `send_email`/`EMAIL`
+// binding, no API keys). With no verified sender configured (local/dev), mail is
+// captured instead of sent — to KV (so an e2e/dashboard can read the "inbox") or
+// in-memory — so handlers work unchanged off-platform.
+/** The `ctx.mail` facade: resolves the sender, validates, and delegates to the adapter. */
+export class Mail {
+    adapter;
+    defaultFrom;
+    constructor(adapter, defaultFrom) {
+        this.adapter = adapter;
+        this.defaultFrom = defaultFrom;
+    }
+    async send(message) {
+        const to = Array.isArray(message.to) ? message.to : [message.to];
+        if (to.length === 0 || to.some((a) => typeof a !== "string" || a.length === 0)) {
+            throw new Error("ctx.mail.send: `to` is required");
+        }
+        if (typeof message.subject !== "string" || message.subject.length === 0) {
+            throw new Error("ctx.mail.send: `subject` is required");
+        }
+        const from = message.from ?? this.defaultFrom;
+        if (!from)
+            throw new Error("ctx.mail.send: no sender — set the MAIL_FROM var or pass `from`");
+        await this.adapter.send({ ...message, from });
+    }
+}
+/** Cloudflare Email Sending — sends via the `send_email` binding (no API keys). The
+ * `from` domain must be onboarded (`wrangler email sending enable yourdomain.com`). */
+export class CloudflareEmailAdapter {
+    binding;
+    constructor(binding) {
+        this.binding = binding;
+    }
+    async send(message) {
+        await this.binding.send({
+            to: message.to,
+            from: message.from,
+            subject: message.subject,
+            text: message.text,
+            html: message.html,
+            replyTo: message.replyTo,
+        });
+    }
+}
+/** Dev/test transport: stash the message in KV under `mail:<recipient>` so an e2e suite
+ * (or a dashboard) can read the "inbox" instead of really sending. */
+export class KvMailAdapter {
+    kv;
+    constructor(kv) {
+        this.kv = kv;
+    }
+    async send(message) {
+        const to = Array.isArray(message.to) ? message.to : [message.to];
+        const value = JSON.stringify({ from: message.from, subject: message.subject, text: message.text, html: message.html });
+        for (const addr of to)
+            await this.kv.put(`mail:${addr}`, value, { expirationTtl: 900 });
+    }
+}
+/** In-memory transport: captures sent messages (pure; for unit tests). */
+export class MemoryMailAdapter {
+    sent = [];
+    async send(message) {
+        this.sent.push(message);
+    }
+}
+/** Fail-closed transport: no real sender and no explicit dev-capture opt-in, so a
+ * `send` THROWS rather than silently capturing. Prevents a misconfigured production
+ * (no MAIL_FROM) from writing security emails — magic-link tokens, resets — into KV
+ * instead of delivering them. Mirrors how files fail closed without FILES_SECRET. */
+export class UnconfiguredMailAdapter {
+    async send() {
+        throw new Error("ctx.mail: no transport configured — set MAIL_FROM (with the EMAIL binding) to send, " +
+            "or MAIL_CAPTURE=true to capture in dev.");
+    }
+}
+/** Build `ctx.mail` from the environment:
+ *  - `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
+ *  - else `MAIL_CAPTURE=true` → capture (KV inbox if a Kv is given, else in-memory) with
+ *    a synthetic dev sender — an EXPLICIT dev opt-in, never the production default.
+ *  - else → fail closed: a `send` throws (so a missing-MAIL_FROM prod doesn't silently
+ *    stash security emails in KV). */
+export function createMail(env, kv) {
+    const binding = env.EMAIL;
+    const fromAddr = typeof env.MAIL_FROM === "string" && env.MAIL_FROM ? env.MAIL_FROM : undefined;
+    if (binding && fromAddr) {
+        const name = typeof env.MAIL_FROM_NAME === "string" ? env.MAIL_FROM_NAME : undefined;
+        return new Mail(new CloudflareEmailAdapter(binding), { email: fromAddr, name });
+    }
+    if (env.MAIL_CAPTURE === "true") {
+        const devFrom = { email: "dev@pramen.local", name: "pramen (dev)" };
+        return new Mail(kv ? new KvMailAdapter(kv) : new MemoryMailAdapter(), devFrom);
+    }
+    // Sentinel `from` so the facade delegates to the adapter, which throws the clear error.
+    return new Mail(new UnconfiguredMailAdapter(), { email: "unconfigured@invalid" });
+}

package/dist/sdk/handlers.d.ts

@@ -1,5 +1,6 @@
 import type { Db } from "../runtime/db";
 import type { Kv } from "../runtime/kv";
+import type { Mail } from "../runtime/mail";
 import type { Identity } from "./acl";
 import type { Files } from "./files";
 import type { SchemaDef } from "./schema";
@@ -12,6 +13,11 @@ export interface HandlerContext<S extends SchemaDef = SchemaDef> {
     /** Per-tenant file storage: mint signed upload/download urls, head/delete blobs.
      * Bytes flow through the Worker /files/* route, never through the DO. */
     readonly files: Files;
+    /** Send email: `ctx.mail.send({ to, subject, text/html })`. On Cloudflare this is
+     * Cloudflare Email Sending (the `send_email` binding); off-platform / unconfigured it
+     * captures instead of sending. Prefer enqueuing the send as a task (see `ctx.tasks`)
+     * so it runs off the single-writer write path. */
+    readonly mail: Mail;
     /** The Worker/DO environment — bindings (KV, R2, DB, …) plus vars and secrets
      * (AUTH_SECRET, plus anything in wrangler.jsonc / .dev.vars / `wrangler secret`).
      * Use it to call external services from handlers — Cloudflare bindings (e.g. the

package/dist/worker.js

@@ -6,6 +6,7 @@
 import { authorizeTenant, HmacStrategy, isAdmin, JwksStrategy, resolveIdentity } from "./auth";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
+import { createMail } from "./runtime/mail";
 import { migrate } from "./runtime/migrate";
 import { compileAcl } from "./runtime/acl";
 import { Db } from "./runtime/db";
@@ -110,7 +111,8 @@ export function makeWorker(app) {
         const identity = { roles: ["admin"] };
         const files = createFiles({ tenant: "main", secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
         const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema, suppressTriggers: true }, app.schema);
-        return { db, kv: new Kv(env.KV), files, env: env, identity, tasks: tasksFacade(driver) };
+        const kv = new Kv(env.KV);
+        return { db, kv, files, env: env, identity, tasks: tasksFacade(driver), mail: createMail(env, kv) };
     };
     /** Drain the D1 outbox in the Worker (no DO/alarm on this path) — called by the
      * /admin/tasks/drain route with `x-pramen-store: d1`, and by `scheduled()` (Cron). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "pramen server runtime — schema, ACL, ORM, live queries, files, and the createPramen(app) factory for Cloudflare Workers + Durable Objects.",
   "license": "MIT",
   "repository": {

package/src/durable-object.ts

@@ -18,6 +18,7 @@
 import { DurableObject } from "cloudflare:workers";
 import { migrate } from "./runtime/migrate";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
+import { createMail } from "./runtime/mail";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
 import { Db } from "./runtime/db";
 import { digest } from "./runtime/digest";
@@ -205,7 +206,15 @@ export class PramenDOBase extends DurableObject<DoEnv> {
       { acl: this.acl, identity, system: true, schema: this.app.schema, partition: this.partition, suppressTriggers: true },
       this.app.schema,
     );
-    return { db, kv: this.kv, files: this.filesFor(this.tenant), env: this.envBag, identity, tasks: tasksFacade(this.driver) };
+    return {
+      db,
+      kv: this.kv,
+      files: this.filesFor(this.tenant),
+      env: this.envBag,
+      identity,
+      tasks: tasksFacade(this.driver),
+      mail: createMail(this.envBag, this.kv),
+    };
   }
 
   /** Restore (tenant, partition) on a cold wake (e.g. an alarm with no request) so the

package/src/index.ts

@@ -72,6 +72,10 @@ export type { FileRef, Files, SignUploadOpts, SignDownloadOpts, HeadResult } fro
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
 
+// --- mail (ctx.mail) ---
+export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+export type { MailMessage, MailAddress, MailAdapter, SendEmailBinding } from "./runtime/mail";
+
 // --- errors ---
 export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
 

package/src/runtime/dispatch.ts

@@ -12,6 +12,7 @@ import { Db } from "./db";
 import { warmup, type AclContext } from "./acl";
 import { BadRequest } from "./errors";
 import { enqueueTask, type TaskMap } from "./outbox";
+import { createMail } from "./mail";
 import type { Driver } from "./driver";
 import type { Kv } from "./kv";
 import type { Files } from "../sdk/files";
@@ -76,7 +77,15 @@ export async function dispatch(
 
   const db = new Db(driver, { acl: acl.acl, identity: acl.identity, input: parsed, resolved, schema, partition: acl.partition }, schema);
   let enqueued = 0;
-  const ctx: HandlerContext = { db, kv, files, env, identity: acl.identity, tasks: tasksFacade(driver, () => enqueued++) };
+  const ctx: HandlerContext = {
+    db,
+    kv,
+    files,
+    env,
+    identity: acl.identity,
+    tasks: tasksFacade(driver, () => enqueued++),
+    mail: createMail(env, kv),
+  };
 
   const result =
     handler.kind === "query"

package/src/runtime/mail.ts

@@ -0,0 +1,136 @@
+// ctx.mail — transactional-ish email facade, the same shape as ctx.files: an adapter
+// seam (CloudflareEmailAdapter / KvMailAdapter / MemoryMailAdapter) behind a thin
+// `Mail` facade, chosen from the environment. Handlers send mail without touching the
+// `send_email` binding directly:
+//
+//   await ctx.mail.send({ to: "u@x.com", subject: "Welcome", text: "…" });
+//
+// On Cloudflare the transport is Cloudflare Email Sending (the `send_email`/`EMAIL`
+// binding, no API keys). With no verified sender configured (local/dev), mail is
+// captured instead of sent — to KV (so an e2e/dashboard can read the "inbox") or
+// in-memory — so handlers work unchanged off-platform.
+
+import type { Kv } from "./kv";
+
+export interface MailAddress {
+  email: string;
+  name?: string;
+}
+
+export interface MailMessage {
+  to: string | string[];
+  /** Sender. Optional — defaults to MAIL_FROM (a verified address). */
+  from?: MailAddress;
+  subject: string;
+  text?: string;
+  html?: string;
+  replyTo?: string | MailAddress;
+}
+
+/** The transport seam. One per backend (Cloudflare Email Sending, a dev stash, …). */
+export interface MailAdapter {
+  /** Deliver a fully-resolved message (`from` already filled by the facade). */
+  send(message: MailMessage & { from: MailAddress }): Promise<void>;
+}
+
+/** The `ctx.mail` facade: resolves the sender, validates, and delegates to the adapter. */
+export class Mail {
+  constructor(
+    private readonly adapter: MailAdapter,
+    private readonly defaultFrom?: MailAddress,
+  ) {}
+
+  async send(message: MailMessage): Promise<void> {
+    const to = Array.isArray(message.to) ? message.to : [message.to];
+    if (to.length === 0 || to.some((a) => typeof a !== "string" || a.length === 0)) {
+      throw new Error("ctx.mail.send: `to` is required");
+    }
+    if (typeof message.subject !== "string" || message.subject.length === 0) {
+      throw new Error("ctx.mail.send: `subject` is required");
+    }
+    const from = message.from ?? this.defaultFrom;
+    if (!from) throw new Error("ctx.mail.send: no sender — set the MAIL_FROM var or pass `from`");
+    await this.adapter.send({ ...message, from });
+  }
+}
+
+/** The Cloudflare `send_email` binding shape (workers binding form: `from` uses `email`). */
+export interface SendEmailBinding {
+  send(message: {
+    to: string | string[];
+    from: MailAddress;
+    subject: string;
+    text?: string;
+    html?: string;
+    replyTo?: string | MailAddress;
+  }): Promise<void>;
+}
+
+/** Cloudflare Email Sending — sends via the `send_email` binding (no API keys). The
+ * `from` domain must be onboarded (`wrangler email sending enable yourdomain.com`). */
+export class CloudflareEmailAdapter implements MailAdapter {
+  constructor(private readonly binding: SendEmailBinding) {}
+  async send(message: MailMessage & { from: MailAddress }): Promise<void> {
+    await this.binding.send({
+      to: message.to,
+      from: message.from,
+      subject: message.subject,
+      text: message.text,
+      html: message.html,
+      replyTo: message.replyTo,
+    });
+  }
+}
+
+/** Dev/test transport: stash the message in KV under `mail:<recipient>` so an e2e suite
+ * (or a dashboard) can read the "inbox" instead of really sending. */
+export class KvMailAdapter implements MailAdapter {
+  constructor(private readonly kv: Kv) {}
+  async send(message: MailMessage & { from: MailAddress }): Promise<void> {
+    const to = Array.isArray(message.to) ? message.to : [message.to];
+    const value = JSON.stringify({ from: message.from, subject: message.subject, text: message.text, html: message.html });
+    for (const addr of to) await this.kv.put(`mail:${addr}`, value, { expirationTtl: 900 });
+  }
+}
+
+/** In-memory transport: captures sent messages (pure; for unit tests). */
+export class MemoryMailAdapter implements MailAdapter {
+  readonly sent: Array<MailMessage & { from: MailAddress }> = [];
+  async send(message: MailMessage & { from: MailAddress }): Promise<void> {
+    this.sent.push(message);
+  }
+}
+
+/** Fail-closed transport: no real sender and no explicit dev-capture opt-in, so a
+ * `send` THROWS rather than silently capturing. Prevents a misconfigured production
+ * (no MAIL_FROM) from writing security emails — magic-link tokens, resets — into KV
+ * instead of delivering them. Mirrors how files fail closed without FILES_SECRET. */
+export class UnconfiguredMailAdapter implements MailAdapter {
+  async send(): Promise<void> {
+    throw new Error(
+      "ctx.mail: no transport configured — set MAIL_FROM (with the EMAIL binding) to send, " +
+        "or MAIL_CAPTURE=true to capture in dev.",
+    );
+  }
+}
+
+/** Build `ctx.mail` from the environment:
+ *  - `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
+ *  - else `MAIL_CAPTURE=true` → capture (KV inbox if a Kv is given, else in-memory) with
+ *    a synthetic dev sender — an EXPLICIT dev opt-in, never the production default.
+ *  - else → fail closed: a `send` throws (so a missing-MAIL_FROM prod doesn't silently
+ *    stash security emails in KV). */
+export function createMail(env: Readonly<Record<string, unknown>>, kv?: Kv): Mail {
+  const binding = env.EMAIL as SendEmailBinding | undefined;
+  const fromAddr = typeof env.MAIL_FROM === "string" && env.MAIL_FROM ? env.MAIL_FROM : undefined;
+  if (binding && fromAddr) {
+    const name = typeof env.MAIL_FROM_NAME === "string" ? env.MAIL_FROM_NAME : undefined;
+    return new Mail(new CloudflareEmailAdapter(binding), { email: fromAddr, name });
+  }
+  if (env.MAIL_CAPTURE === "true") {
+    const devFrom: MailAddress = { email: "dev@pramen.local", name: "pramen (dev)" };
+    return new Mail(kv ? new KvMailAdapter(kv) : new MemoryMailAdapter(), devFrom);
+  }
+  // Sentinel `from` so the facade delegates to the adapter, which throws the clear error.
+  return new Mail(new UnconfiguredMailAdapter(), { email: "unconfigured@invalid" });
+}

package/src/sdk/handlers.ts

@@ -4,6 +4,7 @@
 
 import type { Db } from "../runtime/db";
 import type { Kv } from "../runtime/kv";
+import type { Mail } from "../runtime/mail";
 import type { Identity } from "./acl";
 import type { Files } from "./files";
 import type { SchemaDef } from "./schema";
@@ -17,6 +18,11 @@ export interface HandlerContext<S extends SchemaDef = SchemaDef> {
   /** Per-tenant file storage: mint signed upload/download urls, head/delete blobs.
    * Bytes flow through the Worker /files/* route, never through the DO. */
   readonly files: Files;
+  /** Send email: `ctx.mail.send({ to, subject, text/html })`. On Cloudflare this is
+   * Cloudflare Email Sending (the `send_email` binding); off-platform / unconfigured it
+   * captures instead of sending. Prefer enqueuing the send as a task (see `ctx.tasks`)
+   * so it runs off the single-writer write path. */
+  readonly mail: Mail;
   /** The Worker/DO environment — bindings (KV, R2, DB, …) plus vars and secrets
    * (AUTH_SECRET, plus anything in wrangler.jsonc / .dev.vars / `wrangler secret`).
    * Use it to call external services from handlers — Cloudflare bindings (e.g. the

package/src/worker.ts

@@ -7,6 +7,7 @@
 import { authorizeTenant, HmacStrategy, isAdmin, JwksStrategy, resolveIdentity, type VerifyStrategy } from "./auth";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
+import { createMail } from "./runtime/mail";
 import { migrate } from "./runtime/migrate";
 import { compileAcl } from "./runtime/acl";
 import { Db } from "./runtime/db";
@@ -149,7 +150,8 @@ export function makeWorker(app: PramenApp) {
     const identity: Identity = { roles: ["admin"] };
     const files = createFiles({ tenant: "main", secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
     const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema, suppressTriggers: true }, app.schema);
-    return { db, kv: new Kv(env.KV), files, env: env as unknown as Record<string, unknown>, identity, tasks: tasksFacade(driver) };
+    const kv = new Kv(env.KV);
+    return { db, kv, files, env: env as unknown as Record<string, unknown>, identity, tasks: tasksFacade(driver), mail: createMail(env as unknown as Record<string, unknown>, kv) };
   };
 
   /** Drain the D1 outbox in the Worker (no DO/alarm on this path) — called by the