@lunora/mail 1.0.0-alpha.55 → 1.0.0-alpha.56

package/dist/inbound/index.d.mts

@@ -101,7 +101,14 @@ interface ForwardableEmailMessageLike {
     raw: string;
     to: string;
   }) => Promise<unknown>;
-  /** Reject the message with a permanent SMTP error (Cloudflare bounces/retries). */
+  /**
+   * Reject the message with a PERMANENT SMTP error — Cloudflare returns it to
+   * the connecting client with this reason, and it is never redelivered.
+   * Documented at https://developers.cloudflare.com/email-routing/email-workers/runtime-api/
+   * ("Reject this email message by returning a permanent SMTP error back to
+   * the connecting client, including the given reason") and mirrored in
+   * workerd's own `types/defines/email.d.ts`.
+   */
   setReject: (reason: string) => void;
   /** Envelope `To`. */
   readonly to: string;
@@ -125,21 +132,54 @@ type InboundDispatch<TEnv = Record<string, unknown>> = (email: InboundEmail, con
  * proceeds.
  */
 type InboundVerify<TEnv = Record<string, unknown>> = (email: InboundEmail, context: InboundDispatchContext<TEnv>) => Promise<boolean | void> | boolean | void;
+/**
+ * Opt-in durable sink for a failed `dispatch`. Hand the parsed message to
+ * something that owns the retry — a queue producer, a Durable Object, an alarm
+ * — and the handler ACCEPTS the SMTP session instead of bouncing, because the
+ * message is now owned rather than lost. Returning normally means "I have it";
+ * throwing means the hand-off itself failed and the message bounces with the
+ * generic reason (see {@link createInboundEmailHandler}).
+ *
+ * `error` is the dispatch failure, for classification/logging by the sink.
+ *
+ * NOTE: binary attachment `content` is an `ArrayBuffer`/`Uint8Array`, which
+ * survives structured clone (Cloudflare Queues, DO storage) but is corrupted by
+ * `JSON.stringify` — encode it yourself if the sink is JSON-bodied.
+ */
+type InboundRetain<TEnv = Record<string, unknown>> = (email: InboundEmail, context: InboundDispatchContext<TEnv>, error: unknown) => Promise<void> | void;
 /** Options for {@link createInboundEmailHandler}. */
 interface InboundEmailHandlerOptions<TEnv = Record<string, unknown>> {
   /** Routes the parsed message onward (e.g. {@link dispatchToLunoraFunction}). */
   dispatch: InboundDispatch<TEnv>;
   /**
-   * Called when `parse`/`verify`/`dispatch` throws. The default rejects the
-   * message via `message.setReject` so Cloudflare bounces/retries rather than
-   * silently dropping it. SECURITY: the reject reason is delivered to the
-   * (attacker-controlled) sender as a bounce, so the default reason is a fixed,
-   * generic string and the real error is logged server-side. Override to log,
-   * forward, or swallow — but never pass internal error text to `setReject`.
+   * Called when `parse`, `verify`, or `dispatch` fails — but with two DIFFERENT
+   * contracts, because only the first two decide the message's fate here:
+   *
+   * - `parse` / `verify` — this hook DECIDES the outcome. The default
+   * ({@link rejectOnError}) rejects via `message.setReject`; supplying your own
+   * replaces that, so the message is accepted unless you reject it yourself.
+   * - `dispatch` — this hook is OBSERVABILITY ONLY. It is called for the side
+   * effect (log, alert, forward) and the outcome is then decided by `retain`
+   * (accept) or a generic reject, regardless of what it does; the built-in
+   * default is deliberately NOT applied there. A `setReject` from inside it
+   * still takes effect, which would bounce a message `retain` went on to
+   * accept — almost certainly not what you want. A throw from the hook itself
+   * is logged and swallowed so it cannot mask the original dispatch error.
+   *
+   * SECURITY: a reject reason is delivered to the (attacker-controlled) sender
+   * as a bounce, so the default reason is a fixed, generic string and the real
+   * error is logged server-side. Never pass internal error text to `setReject`.
    */
   onError?: (error: unknown, context: InboundDispatchContext<TEnv>) => Promise<void> | void;
   /** Parses raw bytes into an {@link InboundEmail} (e.g. `parseInboundEmail`). */
   parse: (raw: RawInboundEmail) => Promise<InboundEmail>;
+  /**
+   * Opt-in: take durable ownership of a message whose `dispatch` failed, so a
+   * transient fault (a shard 502, a briefly-absent admin token) is retried
+   * instead of bounced. Omit it and a dispatch failure bounces, as it always
+   * has. See {@link InboundRetain}.
+   */
+  retain?: InboundRetain<TEnv>;
   /**
    * Opt-in sender-authentication gate run before `dispatch`. SECURITY: inbound
    * `from` is spoofable and dispatch is privileged — supply this (gating on
@@ -152,8 +192,54 @@ type InboundEmailHandler<TEnv = Record<string, unknown>> = (message: Forwardable
 /**
  * Build the `email(message, env, ctx)` handler. It (a) reads `message.raw`,
  * (b) parses it via `parse`, (c) runs the optional `verify` gate, then
- * (d) calls `dispatch(parsed, { message, env, ctx })`. Any throw (or a falsy
- * `verify`) routes through `onError` (default: a generic `message.setReject`).
+ * (d) calls `dispatch(parsed, { message, env, ctx })`.
+ *
+ * The two failure classes are routed differently:
+ *
+ * - `parse` / `verify` (including a falsy `verify`) → `onError` (default: a
+ * generic `message.setReject`). A malformed or unauthenticated message fails
+ * the same way on every redelivery, so bouncing it is the honest answer.
+ * - `dispatch` (or its transport) → a custom `onError` is called for
+ * observability, then the message is handed to `retain` if one is configured
+ * (SMTP ACCEPTs — the retry is now owned elsewhere) and otherwise bounced with
+ * the same generic reason. A `retain` that throws bounces too.
+ *
+ * WHY THE RETRY IS ABSORBED IN-WORKER RATHER THAN SIGNALLED OVER SMTP — there is
+ * no transient-reject API and no inbound redelivery to appeal to:
+ *
+ * - `setReject` is documented as a PERMANENT SMTP error
+ * (https://developers.cloudflare.com/email-routing/email-workers/runtime-api/),
+ * with no "try later" variant.
+ * - Cloudflare does not document what an uncaught throw from `email()` does. The
+ * full Email Routing and Email Service docs corpora
+ * (`developers.cloudflare.com/email-routing/llms-full.txt`,
+ * `.../email-service/llms-full.txt`) say nothing about an unhandled exception,
+ * and describe NO redelivery mechanism for inbound Email Workers at all. The
+ * documented lifecycle
+ * (https://developers.cloudflare.com/email-service/concepts/email-lifecycle/)
+ * lists exactly three worker outcomes — `forward()`, `reply()`, `setReject()` —
+ * with no branch for "the worker threw". (Its 4xx-retry prose is about OUTBOUND
+ * delivery to the destination MTA, not about invoking the worker.)
+ * - The behaviour reported in practice is a PERMANENT in-session rejection:
+ * `521 5.3.0 Upstream error`, i.e. the same permanence as `setReject` but with
+ * an opaque reason instead of ours. See
+ * https://community.cloudflare.com/t/is-it-possible-to-return-a-transient-failure-from-an-email-worker/599938
+ * ("If the email function raises an exception, a permanent failure is returned
+ * to the client after the DATA command") — a question Cloudflare never answered
+ * — and https://community.cloudflare.com/t/email-worker-upstream-error/457228.
+ * Email Routing also states it forwards upstream SMTP errors back to the sender
+ * in-session rather than generating a bounce later
+ * (https://developers.cloudflare.com/email-service/reference/postmaster/#smtp-errors).
+ *
+ * So every SMTP-visible outcome is permanent, and the only way not to lose a
+ * legitimate message to a two-second shard 502 is to accept it and take durable
+ * ownership: that is `retain`. It stays opt-in — with no `retain`, a dispatch
+ * failure bounces exactly as before.
+ *
+ * A dispatch that KNOWS one of its own failures is permanent should call
+ * `context.message.setReject(...)` and return normally rather than throw, so it
+ * bounces without being handed to `retain` (see `@lunora/agent`'s inbound
+ * handler for both cases).
  */
 declare const createInboundEmailHandler: <TEnv = Record<string, unknown>>(options: InboundEmailHandlerOptions<TEnv>) => InboundEmailHandler<TEnv>;
 /** The `RpcEnvelope` shape the runtime's `/_lunora/rpc` path consumes. */
@@ -192,8 +278,10 @@ interface DispatchToLunoraFunctionOptions<TEnv = Record<string, unknown>> {
  * Build a {@link InboundDispatch} that posts an {@link RpcEnvelope} to the root
  * shard stub — the same admin-RPC-over-shard path the dev capture sink uses
  * (`from-env.ts`) — routing the parsed message into a named Lunora
- * mutation/action. Throws on a non-2xx RPC or a missing admin token so the
- * handler's `onError` (default `setReject`) bounces the message.
+ * mutation/action. Throws on a non-2xx RPC or a missing admin token — both
+ * transient in principle, so the handler reports it through a custom `onError`
+ * and then hands the message to `retain` if one is configured, bouncing only
+ * when there is nowhere durable to put it (see {@link createInboundEmailHandler}).
  *
  * SECURITY: the RPC carries the admin bearer, so the target function runs with
  * RLS bypassed over fully attacker-controlled, spoofable input — see the module

package/dist/inbound/index.d.ts

@@ -101,7 +101,14 @@ interface ForwardableEmailMessageLike {
     raw: string;
     to: string;
   }) => Promise<unknown>;
-  /** Reject the message with a permanent SMTP error (Cloudflare bounces/retries). */
+  /**
+   * Reject the message with a PERMANENT SMTP error — Cloudflare returns it to
+   * the connecting client with this reason, and it is never redelivered.
+   * Documented at https://developers.cloudflare.com/email-routing/email-workers/runtime-api/
+   * ("Reject this email message by returning a permanent SMTP error back to
+   * the connecting client, including the given reason") and mirrored in
+   * workerd's own `types/defines/email.d.ts`.
+   */
   setReject: (reason: string) => void;
   /** Envelope `To`. */
   readonly to: string;
@@ -125,21 +132,54 @@ type InboundDispatch<TEnv = Record<string, unknown>> = (email: InboundEmail, con
  * proceeds.
  */
 type InboundVerify<TEnv = Record<string, unknown>> = (email: InboundEmail, context: InboundDispatchContext<TEnv>) => Promise<boolean | void> | boolean | void;
+/**
+ * Opt-in durable sink for a failed `dispatch`. Hand the parsed message to
+ * something that owns the retry — a queue producer, a Durable Object, an alarm
+ * — and the handler ACCEPTS the SMTP session instead of bouncing, because the
+ * message is now owned rather than lost. Returning normally means "I have it";
+ * throwing means the hand-off itself failed and the message bounces with the
+ * generic reason (see {@link createInboundEmailHandler}).
+ *
+ * `error` is the dispatch failure, for classification/logging by the sink.
+ *
+ * NOTE: binary attachment `content` is an `ArrayBuffer`/`Uint8Array`, which
+ * survives structured clone (Cloudflare Queues, DO storage) but is corrupted by
+ * `JSON.stringify` — encode it yourself if the sink is JSON-bodied.
+ */
+type InboundRetain<TEnv = Record<string, unknown>> = (email: InboundEmail, context: InboundDispatchContext<TEnv>, error: unknown) => Promise<void> | void;
 /** Options for {@link createInboundEmailHandler}. */
 interface InboundEmailHandlerOptions<TEnv = Record<string, unknown>> {
   /** Routes the parsed message onward (e.g. {@link dispatchToLunoraFunction}). */
   dispatch: InboundDispatch<TEnv>;
   /**
-   * Called when `parse`/`verify`/`dispatch` throws. The default rejects the
-   * message via `message.setReject` so Cloudflare bounces/retries rather than
-   * silently dropping it. SECURITY: the reject reason is delivered to the
-   * (attacker-controlled) sender as a bounce, so the default reason is a fixed,
-   * generic string and the real error is logged server-side. Override to log,
-   * forward, or swallow — but never pass internal error text to `setReject`.
+   * Called when `parse`, `verify`, or `dispatch` fails — but with two DIFFERENT
+   * contracts, because only the first two decide the message's fate here:
+   *
+   * - `parse` / `verify` — this hook DECIDES the outcome. The default
+   * ({@link rejectOnError}) rejects via `message.setReject`; supplying your own
+   * replaces that, so the message is accepted unless you reject it yourself.
+   * - `dispatch` — this hook is OBSERVABILITY ONLY. It is called for the side
+   * effect (log, alert, forward) and the outcome is then decided by `retain`
+   * (accept) or a generic reject, regardless of what it does; the built-in
+   * default is deliberately NOT applied there. A `setReject` from inside it
+   * still takes effect, which would bounce a message `retain` went on to
+   * accept — almost certainly not what you want. A throw from the hook itself
+   * is logged and swallowed so it cannot mask the original dispatch error.
+   *
+   * SECURITY: a reject reason is delivered to the (attacker-controlled) sender
+   * as a bounce, so the default reason is a fixed, generic string and the real
+   * error is logged server-side. Never pass internal error text to `setReject`.
    */
   onError?: (error: unknown, context: InboundDispatchContext<TEnv>) => Promise<void> | void;
   /** Parses raw bytes into an {@link InboundEmail} (e.g. `parseInboundEmail`). */
   parse: (raw: RawInboundEmail) => Promise<InboundEmail>;
+  /**
+   * Opt-in: take durable ownership of a message whose `dispatch` failed, so a
+   * transient fault (a shard 502, a briefly-absent admin token) is retried
+   * instead of bounced. Omit it and a dispatch failure bounces, as it always
+   * has. See {@link InboundRetain}.
+   */
+  retain?: InboundRetain<TEnv>;
   /**
    * Opt-in sender-authentication gate run before `dispatch`. SECURITY: inbound
    * `from` is spoofable and dispatch is privileged — supply this (gating on
@@ -152,8 +192,54 @@ type InboundEmailHandler<TEnv = Record<string, unknown>> = (message: Forwardable
 /**
  * Build the `email(message, env, ctx)` handler. It (a) reads `message.raw`,
  * (b) parses it via `parse`, (c) runs the optional `verify` gate, then
- * (d) calls `dispatch(parsed, { message, env, ctx })`. Any throw (or a falsy
- * `verify`) routes through `onError` (default: a generic `message.setReject`).
+ * (d) calls `dispatch(parsed, { message, env, ctx })`.
+ *
+ * The two failure classes are routed differently:
+ *
+ * - `parse` / `verify` (including a falsy `verify`) → `onError` (default: a
+ * generic `message.setReject`). A malformed or unauthenticated message fails
+ * the same way on every redelivery, so bouncing it is the honest answer.
+ * - `dispatch` (or its transport) → a custom `onError` is called for
+ * observability, then the message is handed to `retain` if one is configured
+ * (SMTP ACCEPTs — the retry is now owned elsewhere) and otherwise bounced with
+ * the same generic reason. A `retain` that throws bounces too.
+ *
+ * WHY THE RETRY IS ABSORBED IN-WORKER RATHER THAN SIGNALLED OVER SMTP — there is
+ * no transient-reject API and no inbound redelivery to appeal to:
+ *
+ * - `setReject` is documented as a PERMANENT SMTP error
+ * (https://developers.cloudflare.com/email-routing/email-workers/runtime-api/),
+ * with no "try later" variant.
+ * - Cloudflare does not document what an uncaught throw from `email()` does. The
+ * full Email Routing and Email Service docs corpora
+ * (`developers.cloudflare.com/email-routing/llms-full.txt`,
+ * `.../email-service/llms-full.txt`) say nothing about an unhandled exception,
+ * and describe NO redelivery mechanism for inbound Email Workers at all. The
+ * documented lifecycle
+ * (https://developers.cloudflare.com/email-service/concepts/email-lifecycle/)
+ * lists exactly three worker outcomes — `forward()`, `reply()`, `setReject()` —
+ * with no branch for "the worker threw". (Its 4xx-retry prose is about OUTBOUND
+ * delivery to the destination MTA, not about invoking the worker.)
+ * - The behaviour reported in practice is a PERMANENT in-session rejection:
+ * `521 5.3.0 Upstream error`, i.e. the same permanence as `setReject` but with
+ * an opaque reason instead of ours. See
+ * https://community.cloudflare.com/t/is-it-possible-to-return-a-transient-failure-from-an-email-worker/599938
+ * ("If the email function raises an exception, a permanent failure is returned
+ * to the client after the DATA command") — a question Cloudflare never answered
+ * — and https://community.cloudflare.com/t/email-worker-upstream-error/457228.
+ * Email Routing also states it forwards upstream SMTP errors back to the sender
+ * in-session rather than generating a bounce later
+ * (https://developers.cloudflare.com/email-service/reference/postmaster/#smtp-errors).
+ *
+ * So every SMTP-visible outcome is permanent, and the only way not to lose a
+ * legitimate message to a two-second shard 502 is to accept it and take durable
+ * ownership: that is `retain`. It stays opt-in — with no `retain`, a dispatch
+ * failure bounces exactly as before.
+ *
+ * A dispatch that KNOWS one of its own failures is permanent should call
+ * `context.message.setReject(...)` and return normally rather than throw, so it
+ * bounces without being handed to `retain` (see `@lunora/agent`'s inbound
+ * handler for both cases).
  */
 declare const createInboundEmailHandler: <TEnv = Record<string, unknown>>(options: InboundEmailHandlerOptions<TEnv>) => InboundEmailHandler<TEnv>;
 /** The `RpcEnvelope` shape the runtime's `/_lunora/rpc` path consumes. */
@@ -192,8 +278,10 @@ interface DispatchToLunoraFunctionOptions<TEnv = Record<string, unknown>> {
  * Build a {@link InboundDispatch} that posts an {@link RpcEnvelope} to the root
  * shard stub — the same admin-RPC-over-shard path the dev capture sink uses
  * (`from-env.ts`) — routing the parsed message into a named Lunora
- * mutation/action. Throws on a non-2xx RPC or a missing admin token so the
- * handler's `onError` (default `setReject`) bounces the message.
+ * mutation/action. Throws on a non-2xx RPC or a missing admin token — both
+ * transient in principle, so the handler reports it through a custom `onError`
+ * and then hands the message to `retain` if one is configured, bouncing only
+ * when there is nowhere durable to put it (see {@link createInboundEmailHandler}).
  *
  * SECURITY: the RPC carries the admin bearer, so the target function runs with
  * RLS bypassed over fully attacker-controlled, spoofable input — see the module

package/dist/inbound/index.mjs

@@ -1 +1 @@
-import{createInboundEmailHandler as r,dispatchToLunoraFunction as a}from"../packem_shared/createInboundEmailHandler-CTary3dz.mjs";import{parseInboundEmail as t}from"../packem_shared/parseInboundEmail-CqU52y3O.mjs";export{r as createInboundEmailHandler,a as dispatchToLunoraFunction,t as parseInboundEmail};
+import{createInboundEmailHandler as r,dispatchToLunoraFunction as a}from"../packem_shared/createInboundEmailHandler-C6V47mz5.mjs";import{parseInboundEmail as t}from"../packem_shared/parseInboundEmail-CqU52y3O.mjs";export{r as createInboundEmailHandler,a as dispatchToLunoraFunction,t as parseInboundEmail};

package/dist/packem_shared/createInboundEmailHandler-C6V47mz5.mjs

@@ -0,0 +1 @@
+import{LunoraError as d}from"@lunora/errors";import{D as h,p as l}from"./shard-C0aRRoVy.mjs";const f=r=>{let n="";for(let e=0;e<r.length;e+=32768)n+=String.fromCharCode(...r.subarray(e,e+32768));return btoa(n)},E="message could not be processed",u=(r,n)=>{console.error("@lunora/mail/inbound: dropping message —",r),n.message.setReject(E)},y=r=>{const n=r.onError??u;return async(t,e,c)=>{const a={ctx:c,env:e,message:t};let o;try{if(o=await r.parse(t.raw),r.verify&&await r.verify(o,a)===!1)throw new d("INTERNAL","@lunora/mail/inbound: sender verification rejected the message")}catch(i){await n(i,a);return}try{await r.dispatch(o,a)}catch(i){if(r.onError)try{await r.onError(i,a)}catch(s){console.error("@lunora/mail/inbound: onError threw while reporting a dispatch failure —",s)}if(r.retain)try{await r.retain(o,a,i);return}catch(s){console.error("@lunora/mail/inbound: retain failed to take ownership of the message —",s)}u(i,a)}}},m=r=>r.attachments.length===0?r:{...r,attachments:r.attachments.map(n=>{const{content:t}=n;if(typeof t=="string")return n;const e=t instanceof Uint8Array?t:new Uint8Array(t);return{...n,content:f(e),encoding:"base64"}})},A=r=>{const n=r.shardKey??h,t=r.resolveArgs??(e=>m(e));return async(e,c)=>{const a=r.adminToken??(typeof c.env.LUNORA_ADMIN_TOKEN=="string"?c.env.LUNORA_ADMIN_TOKEN:void 0);if(a===void 0||a==="")throw new d("INTERNAL","@lunora/mail/inbound: missing LUNORA_ADMIN_TOKEN — cannot authorize inbound dispatch to the shard RPC.");const o={args:t(e,c),functionPath:r.functionPath,shardKey:n};await l(r.shard,{adminToken:a,envelope:o,jurisdiction:r.jurisdiction,label:`@lunora/mail/inbound: dispatch to \`${r.functionPath}\``,shardKey:n})}};export{y as createInboundEmailHandler,A as dispatchToLunoraFunction};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/mail",
-  "version": "1.0.0-alpha.55",
+  "version": "1.0.0-alpha.56",
   "description": "Email for Lunora: Resend adapter, TSX templates, and queue-backed sends",
   "keywords": [
     "cloudflare",

package/dist/packem_shared/createInboundEmailHandler-CTary3dz.mjs

@@ -1 +0,0 @@
-import{LunoraError as i}from"@lunora/errors";import{D as c,p as d}from"./shard-C0aRRoVy.mjs";const u=n=>{let r="";for(let e=0;e<n.length;e+=32768)r+=String.fromCharCode(...n.subarray(e,e+32768));return btoa(r)},h="message could not be processed",f=(n,r)=>{console.error("@lunora/mail/inbound: dropping message —",n),r.message.setReject(h)},N=n=>{const r=n.onError??f;return async(t,e,s)=>{const a={ctx:s,env:e,message:t};try{const o=await n.parse(t.raw);if(n.verify&&await n.verify(o,a)===!1)throw new i("INTERNAL","@lunora/mail/inbound: sender verification rejected the message");await n.dispatch(o,a)}catch(o){await r(o,a)}}},l=n=>n.attachments.length===0?n:{...n,attachments:n.attachments.map(r=>{const{content:t}=r;if(typeof t=="string")return r;const e=t instanceof Uint8Array?t:new Uint8Array(t);return{...r,content:u(e),encoding:"base64"}})},g=n=>{const r=n.shardKey??c,t=n.resolveArgs??(e=>l(e));return async(e,s)=>{const a=n.adminToken??(typeof s.env.LUNORA_ADMIN_TOKEN=="string"?s.env.LUNORA_ADMIN_TOKEN:void 0);if(a===void 0||a==="")throw new i("INTERNAL","@lunora/mail/inbound: missing LUNORA_ADMIN_TOKEN — cannot authorize inbound dispatch to the shard RPC.");const o={args:t(e,s),functionPath:n.functionPath,shardKey:r};await d(n.shard,{adminToken:a,envelope:o,jurisdiction:n.jurisdiction,label:`@lunora/mail/inbound: dispatch to \`${n.functionPath}\``,shardKey:r})}};export{N as createInboundEmailHandler,g as dispatchToLunoraFunction};