@pramen/server 0.0.58 → 0.0.59

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export { signToken, verifyToken, isUsableSecret, resolveSecret, MIN_TOKEN_SECRET
 export { HmacStrategy, JwksStrategy, type VerifyStrategy, type VerifyOptions } from "./auth";
 export type { ExpiringToken } from "./runtime/token";
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
-export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+export { Mail, CloudflareEmailAdapter, MailgunAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
 export type { MailMessage, MailAddress, MailAdapter, SendEmailBinding } from "./runtime/mail";
 export { Queue, CloudflareQueueAdapter, MemoryQueueAdapter, createQueue, discoverQueueBindings } from "./runtime/queue";
 export type { QueueAdapter, QueueProducerBinding, QueueSendOptions, QueueSendRequest, QueueBatchOptions, QueueContentType } from "./runtime/queue";

package/dist/index.js

@@ -26,7 +26,7 @@ export { signToken, verifyToken, isUsableSecret, resolveSecret, MIN_TOKEN_SECRET
 // token with the same JWKS cache (and its key-rotation handling) the Worker uses.
 export { HmacStrategy, JwksStrategy } from "./auth";
 // --- mail (ctx.mail) ---
-export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+export { Mail, CloudflareEmailAdapter, MailgunAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
 // --- queue (ctx.queue — Cloudflare Queues) ---
 export { Queue, CloudflareQueueAdapter, MemoryQueueAdapter, createQueue, discoverQueueBindings } from "./runtime/queue";
 export { routeQueue, dispatchQueueBatch } from "./runtime/queue-consumer";

package/dist/runtime/mail.d.ts

@@ -47,6 +47,33 @@ export declare class CloudflareEmailAdapter implements MailAdapter {
         from: MailAddress;
     }): Promise<void>;
 }
+/** Mailgun — an HTTP transport, for when Cloudflare Email Sending cannot be used.
+ *
+ * Worth the key for one reason: Cloudflare will only send from a domain that is a zone
+ * in the same account, and some accounts additionally refuse any recipient that is not a
+ * verified destination in Email Routing ("destination address is not a verified
+ * address"). That is workable for a handful of operators and hopeless for real users.
+ * Mailgun asks the domain be verified once, then delivers to anyone.
+ *
+ * A non-2xx THROWS, deliberately: `ctx.mail.send` is normally called from a task, and a
+ * throw is what makes the outbox retry and then dead-letter visibly. Swallowing the
+ * status would turn a bounced sign-in link into silence. The response body rides along
+ * in the message because Mailgun's 400s are specific and worth reading ("not a valid
+ * address", "domain not found"); the key never does. */
+export declare class MailgunAdapter implements MailAdapter {
+    private readonly apiKey;
+    private readonly domain;
+    /** `https://api.eu.mailgun.net` for an EU-region account; the two are separate
+     * deployments and a key from one 401s against the other. */
+    private readonly apiBase;
+    constructor(apiKey: string, domain: string, 
+    /** `https://api.eu.mailgun.net` for an EU-region account; the two are separate
+     * deployments and a key from one 401s against the other. */
+    apiBase?: string);
+    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 {
@@ -73,9 +100,14 @@ export declare class UnconfiguredMailAdapter implements MailAdapter {
     send(): Promise<void>;
 }
 /** Build `ctx.mail` from the environment:
- *  - `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
+ *  - `MAILGUN_API_KEY` + `MAILGUN_DOMAIN` + `MAIL_FROM` → Mailgun (real send).
+ *  - else `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). */
+ *    stash security emails in KV).
+ *
+ * Mailgun outranks the binding on purpose. The binding tends to be present because the
+ * infrastructure declares it, whereas an API key is only ever there because somebody put
+ * it there — so when both exist, the key is the newer decision. */
 export declare function createMail(env: EnvBag, kv?: Kv): Mail;

package/dist/runtime/mail.js

@@ -5,10 +5,15 @@
 //
 //   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.
+// Two real transports. Cloudflare Email Sending (the `send_email`/`EMAIL` binding) needs
+// no API keys, but it can only send FROM a domain that is a zone in the same account,
+// and on some accounts only TO addresses verified in Email Routing — which rules it out
+// whenever the recipients are ordinary people. Mailgun is the way out of both: an HTTP
+// API, any recipient, at the cost of a key. Configure it and it wins.
+//
+// With neither 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;
@@ -49,6 +54,60 @@ export class CloudflareEmailAdapter {
         });
     }
 }
+/** Mailgun — an HTTP transport, for when Cloudflare Email Sending cannot be used.
+ *
+ * Worth the key for one reason: Cloudflare will only send from a domain that is a zone
+ * in the same account, and some accounts additionally refuse any recipient that is not a
+ * verified destination in Email Routing ("destination address is not a verified
+ * address"). That is workable for a handful of operators and hopeless for real users.
+ * Mailgun asks the domain be verified once, then delivers to anyone.
+ *
+ * A non-2xx THROWS, deliberately: `ctx.mail.send` is normally called from a task, and a
+ * throw is what makes the outbox retry and then dead-letter visibly. Swallowing the
+ * status would turn a bounced sign-in link into silence. The response body rides along
+ * in the message because Mailgun's 400s are specific and worth reading ("not a valid
+ * address", "domain not found"); the key never does. */
+export class MailgunAdapter {
+    apiKey;
+    domain;
+    apiBase;
+    constructor(apiKey, domain, 
+    /** `https://api.eu.mailgun.net` for an EU-region account; the two are separate
+     * deployments and a key from one 401s against the other. */
+    apiBase = "https://api.mailgun.net") {
+        this.apiKey = apiKey;
+        this.domain = domain;
+        this.apiBase = apiBase;
+    }
+    async send(message) {
+        const body = new URLSearchParams();
+        body.set("from", message.from.name ? `${message.from.name} <${message.from.email}>` : message.from.email);
+        for (const to of Array.isArray(message.to) ? message.to : [message.to])
+            body.append("to", to);
+        body.set("subject", message.subject);
+        if (message.text)
+            body.set("text", message.text);
+        if (message.html)
+            body.set("html", message.html);
+        if (message.replyTo) {
+            const r = message.replyTo;
+            body.set("h:Reply-To", typeof r === "string" ? r : r.name ? `${r.name} <${r.email}>` : r.email);
+        }
+        const res = await fetch(`${this.apiBase.replace(/\/+$/, "")}/v3/${encodeURIComponent(this.domain)}/messages`, {
+            method: "POST",
+            headers: {
+                // `api` is the literal username Mailgun expects; the key is the password.
+                authorization: `Basic ${btoa(`api:${this.apiKey}`)}`,
+                "content-type": "application/x-www-form-urlencoded",
+            },
+            body,
+        });
+        if (!res.ok) {
+            const detail = await res.text().catch(() => "");
+            throw new Error(`mailgun: send failed (${res.status})${detail ? ` — ${detail.slice(0, 300)}` : ""}`);
+        }
+    }
+}
 /** 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 {
@@ -76,21 +135,35 @@ export class MemoryMailAdapter {
  * 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.");
+        throw new Error("ctx.mail: no transport configured — set MAIL_FROM with either the EMAIL binding " +
+            "or MAILGUN_API_KEY + MAILGUN_DOMAIN 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).
+ *  - `MAILGUN_API_KEY` + `MAILGUN_DOMAIN` + `MAIL_FROM` → Mailgun (real send).
+ *  - else `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). */
+ *    stash security emails in KV).
+ *
+ * Mailgun outranks the binding on purpose. The binding tends to be present because the
+ * infrastructure declares it, whereas an API key is only ever there because somebody put
+ * it there — so when both exist, the key is the newer decision. */
 export function createMail(env, kv) {
     const binding = env.EMAIL;
     const fromAddr = typeof env.MAIL_FROM === "string" && env.MAIL_FROM ? env.MAIL_FROM : undefined;
+    const str = (k) => typeof env[k] === "string" && env[k] ? env[k] : undefined;
+    const name = typeof env.MAIL_FROM_NAME === "string" ? env.MAIL_FROM_NAME : undefined;
+    const mailgunKey = str("MAILGUN_API_KEY");
+    const mailgunDomain = str("MAILGUN_DOMAIN");
+    if (mailgunKey && mailgunDomain && fromAddr) {
+        return new Mail(new MailgunAdapter(mailgunKey, mailgunDomain, str("MAILGUN_API_BASE")), {
+            email: fromAddr,
+            name,
+        });
+    }
     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") {

package/package.json

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

package/src/index.ts

@@ -95,7 +95,7 @@ export type { ExpiringToken } from "./runtime/token";
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
 
 // --- mail (ctx.mail) ---
-export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+export { Mail, CloudflareEmailAdapter, MailgunAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
 export type { MailMessage, MailAddress, MailAdapter, SendEmailBinding } from "./runtime/mail";
 
 // --- queue (ctx.queue — Cloudflare Queues) ---

package/src/runtime/mail.ts

@@ -5,10 +5,15 @@
 //
 //   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.
+// Two real transports. Cloudflare Email Sending (the `send_email`/`EMAIL` binding) needs
+// no API keys, but it can only send FROM a domain that is a zone in the same account,
+// and on some accounts only TO addresses verified in Email Routing — which rules it out
+// whenever the recipients are ordinary people. Mailgun is the way out of both: an HTTP
+// API, any recipient, at the cost of a key. Configure it and it wins.
+//
+// With neither 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";
 import type { EnvBag } from "../sdk/handlers";
@@ -83,6 +88,56 @@ export class CloudflareEmailAdapter implements MailAdapter {
   }
 }
 
+/** Mailgun — an HTTP transport, for when Cloudflare Email Sending cannot be used.
+ *
+ * Worth the key for one reason: Cloudflare will only send from a domain that is a zone
+ * in the same account, and some accounts additionally refuse any recipient that is not a
+ * verified destination in Email Routing ("destination address is not a verified
+ * address"). That is workable for a handful of operators and hopeless for real users.
+ * Mailgun asks the domain be verified once, then delivers to anyone.
+ *
+ * A non-2xx THROWS, deliberately: `ctx.mail.send` is normally called from a task, and a
+ * throw is what makes the outbox retry and then dead-letter visibly. Swallowing the
+ * status would turn a bounced sign-in link into silence. The response body rides along
+ * in the message because Mailgun's 400s are specific and worth reading ("not a valid
+ * address", "domain not found"); the key never does. */
+export class MailgunAdapter implements MailAdapter {
+  constructor(
+    private readonly apiKey: string,
+    private readonly domain: string,
+    /** `https://api.eu.mailgun.net` for an EU-region account; the two are separate
+     * deployments and a key from one 401s against the other. */
+    private readonly apiBase: string = "https://api.mailgun.net",
+  ) {}
+
+  async send(message: MailMessage & { from: MailAddress }): Promise<void> {
+    const body = new URLSearchParams();
+    body.set("from", message.from.name ? `${message.from.name} <${message.from.email}>` : message.from.email);
+    for (const to of Array.isArray(message.to) ? message.to : [message.to]) body.append("to", to);
+    body.set("subject", message.subject);
+    if (message.text) body.set("text", message.text);
+    if (message.html) body.set("html", message.html);
+    if (message.replyTo) {
+      const r = message.replyTo;
+      body.set("h:Reply-To", typeof r === "string" ? r : r.name ? `${r.name} <${r.email}>` : r.email);
+    }
+
+    const res = await fetch(`${this.apiBase.replace(/\/+$/, "")}/v3/${encodeURIComponent(this.domain)}/messages`, {
+      method: "POST",
+      headers: {
+        // `api` is the literal username Mailgun expects; the key is the password.
+        authorization: `Basic ${btoa(`api:${this.apiKey}`)}`,
+        "content-type": "application/x-www-form-urlencoded",
+      },
+      body,
+    });
+    if (!res.ok) {
+      const detail = await res.text().catch(() => "");
+      throw new Error(`mailgun: send failed (${res.status})${detail ? ` — ${detail.slice(0, 300)}` : ""}`);
+    }
+  }
+}
+
 /** 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 {
@@ -109,23 +164,39 @@ export class MemoryMailAdapter implements MailAdapter {
 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.",
+      "ctx.mail: no transport configured — set MAIL_FROM with either the EMAIL binding " +
+        "or MAILGUN_API_KEY + MAILGUN_DOMAIN 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).
+ *  - `MAILGUN_API_KEY` + `MAILGUN_DOMAIN` + `MAIL_FROM` → Mailgun (real send).
+ *  - else `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). */
+ *    stash security emails in KV).
+ *
+ * Mailgun outranks the binding on purpose. The binding tends to be present because the
+ * infrastructure declares it, whereas an API key is only ever there because somebody put
+ * it there — so when both exist, the key is the newer decision. */
 export function createMail(env: EnvBag, kv?: Kv): Mail {
   const binding = env.EMAIL as SendEmailBinding | undefined;
   const fromAddr = typeof env.MAIL_FROM === "string" && env.MAIL_FROM ? env.MAIL_FROM : undefined;
+  const str = (k: string): string | undefined =>
+    typeof env[k] === "string" && (env[k] as string) ? (env[k] as string) : undefined;
+  const name = typeof env.MAIL_FROM_NAME === "string" ? env.MAIL_FROM_NAME : undefined;
+
+  const mailgunKey = str("MAILGUN_API_KEY");
+  const mailgunDomain = str("MAILGUN_DOMAIN");
+  if (mailgunKey && mailgunDomain && fromAddr) {
+    return new Mail(new MailgunAdapter(mailgunKey, mailgunDomain, str("MAILGUN_API_BASE")), {
+      email: fromAddr,
+      name,
+    });
+  }
   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") {