@lunora/mail 1.0.0-alpha.6 → 1.0.0-alpha.60

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/dist/inbound/index.d.mts

@@ -1,5 +1,5 @@
-import { D as DurableObjectJurisdiction, S as ShardNamespaceLike } from "../packem_shared/shard.d-CL2Lmliv.mjs";
-export type { a as ShardStubLike } from "../packem_shared/shard.d-CL2Lmliv.mjs";
+import { D as DurableObjectJurisdiction, S as ShardNamespaceLike } from "../packem_shared/shard.d-DVADjmEJ.mjs";
+export type { a as ShardStubLike } from "../packem_shared/shard.d-DVADjmEJ.mjs";
 /** A raw RFC 822 message as accepted by the parser. */
 type RawInboundEmail = ArrayBuffer | ReadableStream<Uint8Array> | string | Uint8Array;
 /** One parsed attachment. `content` is preserved as the parser decoded it. */
@@ -16,33 +16,62 @@ interface InboundAttachment {
   mimeType: string;
 }
 /**
-* Sender-authentication verdicts pulled from the `Authentication-Results` header
-* the receiving MX (e.g. Cloudflare Email Routing) stamped on the message.
-*
-* SECURITY: Cloudflare Email Routing authenticates only the *recipient* domain,
-* **not** the sender. The envelope `from` and message content are trivially
-* spoofable, so a downstream handler MUST NOT make trust/authorization decisions
-* on `email.from` alone — gate on these verdicts (or your own policy) instead.
-* Verdicts are best-effort: when the receiving MX did not stamp an
-* `Authentication-Results` header, every field is `null` ("unknown").
-*/
+ * Sender-authentication verdicts pulled from the `Authentication-Results` header
+ * the receiving MX (e.g. Cloudflare Email Routing) stamped on the message.
+ *
+ * SECURITY: Cloudflare Email Routing authenticates only the *recipient* domain,
+ * **not** the sender. The envelope `from` and message content are trivially
+ * spoofable, so a downstream handler MUST NOT make trust/authorization decisions
+ * on `email.from` alone — gate on these verdicts (or your own policy) instead.
+ * Verdicts are best-effort: when the receiving MX did not stamp an
+ * `Authentication-Results` header, every field is `null` ("unknown").
+ *
+ * SECURITY: a bare `"pass"` is NOT proof the `From` header is genuine. SPF
+ * authenticates the envelope `MAIL FROM` domain and DKIM the signing domain
+ * (`d=`), and an attacker controls both — `spf=pass smtp.mailfrom=evil.example;
+ * dkim=pass header.d=evil.example` is routine for a message whose `From` says
+ * `ceo@victim.example`. Each verdict therefore carries the identifier it is
+ * about (`*Domain`): an SPF or DKIM pass only vouches for `from` when that
+ * domain equals the `From` address's domain (RFC 7489 strict alignment). Only a
+ * DMARC pass already checked alignment for you. A pass with no identifier
+ * reported cannot be aligned and must be treated as unauthenticated.
+ *
+ * SECURITY: verdicts are read from the **first/topmost** `Authentication-Results`
+ * header in document order. The receiving MX prepends its own genuine header per
+ * RFC 8601, so the topmost occurrence is the trustworthy one; any lower
+ * occurrences (which an untrusted sender can inject into the raw message) are
+ * ignored. As defense-in-depth a consumer may additionally verify the topmost
+ * header's `authserv-id` matches its receiving MX (e.g. Cloudflare) — that needs
+ * config this runtime-agnostic parser does not carry, so it is left to the host.
+ */
 interface InboundAuthentication {
   /** DKIM verdict (`"pass"`/`"fail"`/…), or `null` when not reported. */
   dkim: string | null;
+  /** Signing domain the DKIM verdict is about (`header.d=`, lowercased), or `null` when not reported. */
+  dkimDomain: string | null;
   /** DMARC verdict (`"pass"`/`"fail"`/…), or `null` when not reported. */
   dmarc: string | null;
+  /** `From` domain the DMARC verdict evaluated (`header.from=`, lowercased), or `null` when not reported. */
+  dmarcDomain: string | null;
   /** SPF verdict (`"pass"`/`"fail"`/…), or `null` when not reported. */
   spf: string | null;
+  /** Envelope `MAIL FROM` domain the SPF verdict is about (`smtp.mailfrom=`, local part dropped, lowercased), or `null` when not reported. */
+  spfDomain: string | null;
 }
 /** Normalised, transport-agnostic view of a received message. */
 interface InboundEmail {
   /** Decoded attachments (empty array when none). */
   attachments: InboundAttachment[];
   /**
-  * Sender-authentication verdicts (DKIM/SPF/DMARC) parsed from the receiving
-  * MX's `Authentication-Results` header. SECURITY: see {@link InboundAuthentication}
-  * — `from` is spoofable; gate trust on these verdicts, not on `from`.
-  */
+   * Sender-authentication verdicts (DKIM/SPF/DMARC) and the domain each is
+   * about, parsed from the receiving MX's **first/topmost**
+   * `Authentication-Results` header. SECURITY: see
+   * {@link InboundAuthentication} — `from` is spoofable, and an SPF/DKIM pass
+   * vouches for it only when its `*Domain` equals the `From` domain (a DMARC
+   * pass checked that already). Reading the raw `headers["authentication-results"]`
+   * map instead exposes last-wins (a lower, potentially attacker-injected)
+   * value — trust `authentication`, not the raw map.
+   */
   authentication: InboundAuthentication;
   /** Sender mailbox (`from`), CR/LF-checked. Empty string when the message omitted it. SECURITY: spoofable — do not trust for authorization. */
   from: string;
@@ -64,17 +93,17 @@ interface InboundEmail {
   to: string[];
 }
 /**
-* Parse a raw RFC 822 message into a normalised {@link InboundEmail}. Accepts the
-* shapes a Cloudflare Email Worker can hand off — `ReadableStream`, `ArrayBuffer`,
-* `Uint8Array`, or a decoded string.
-*/
+ * Parse a raw RFC 822 message into a normalised {@link InboundEmail}. Accepts the
+ * shapes a Cloudflare Email Worker can hand off — `ReadableStream`, `ArrayBuffer`,
+ * `Uint8Array`, or a decoded string.
+ */
 declare const parseInboundEmail: (raw: RawInboundEmail) => Promise<InboundEmail>;
 /**
-* Structural projection of Cloudflare's `ForwardableEmailMessage` (verified
-* against `@cloudflare/workers-types`' `ForwardableEmailMessage`). Only the
-* members the handler touches are modelled, so the host can pass the real
-* runtime object without `@lunora/mail` importing `cloudflare:email`.
-*/
+ * Structural projection of Cloudflare's `ForwardableEmailMessage` (verified
+ * against `@cloudflare/workers-types`' `ForwardableEmailMessage`). Only the
+ * members the handler touches are modelled, so the host can pass the real
+ * runtime object without `@lunora/mail` importing `cloudflare:email`.
+ */
 interface ForwardableEmailMessageLike {
   /** Forward this message to a verified destination address. */
   forward: (rcptTo: string, headers?: Headers) => Promise<unknown>;
@@ -90,7 +119,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;
@@ -107,43 +143,122 @@ interface InboundDispatchContext<TEnv = Record<string, unknown>> {
 /** Routes a parsed message into a Lunora function (or anywhere). */
 type InboundDispatch<TEnv = Record<string, unknown>> = (email: InboundEmail, context: InboundDispatchContext<TEnv>) => Promise<void>;
 /**
-* Opt-in sender-verification gate. Runs after `parse` and before `dispatch` with
-* the parsed message. Return `false` (or throw) to reject the message before it
-* reaches the privileged dispatch — use it to enforce DKIM/SPF/DMARC via
-* `email.authentication`, an allow-list, etc. Returning `true`/`undefined`
-* proceeds.
-*/
+ * Opt-in sender-verification gate. Runs after `parse` and before `dispatch` with
+ * the parsed message. Return `false` (or throw) to reject the message before it
+ * reaches the privileged dispatch — use it to enforce DKIM/SPF/DMARC via
+ * `email.authentication`, an allow-list, etc. Returning `true`/`undefined`
+ * 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 sender-authentication gate run before `dispatch`. SECURITY: inbound
-  * `from` is spoofable and dispatch is privileged — supply this (gating on
-  * `email.authentication`) when an inbound function makes any trust decision.
-  */
+   * 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
+   * `email.authentication`) when an inbound function makes any trust decision.
+   */
   verify?: InboundVerify<TEnv>;
 }
 /** The `email(message, env, ctx)` callback the factory returns. */
 type InboundEmailHandler<TEnv = Record<string, unknown>> = (message: ForwardableEmailMessageLike, env: TEnv, context: unknown) => Promise<void>;
 /**
-* 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`).
-*/
+ * 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 })`.
+ *
+ * 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. */
 interface RpcEnvelope {
@@ -154,23 +269,23 @@ interface RpcEnvelope {
 /** Options for {@link dispatchToLunoraFunction}. */
 interface DispatchToLunoraFunctionOptions<TEnv = Record<string, unknown>> {
   /**
-  * Admin bearer authorizing the shard RPC. Defaults to reading
-  * `env.LUNORA_ADMIN_TOKEN` at dispatch time.
-  */
+   * Admin bearer authorizing the shard RPC. Defaults to reading
+   * `env.LUNORA_ADMIN_TOKEN` at dispatch time.
+   */
   adminToken?: string;
   /** `functionPath` of the target mutation/action (e.g. `"inbound:onEmail"`). */
   functionPath: string;
   /**
-  * Pin inbound dispatch to a Cloudflare data-residency jurisdiction. Pass the
-  * same value as the worker's `jurisdiction` so inbound mail routes to the
-  * jurisdiction-pinned shard. Omit for the un-pinned global namespace.
-  */
+   * Pin inbound dispatch to a Cloudflare data-residency jurisdiction. Pass the
+   * same value as the worker's `jurisdiction` so inbound mail routes to the
+   * jurisdiction-pinned shard. Omit for the un-pinned global namespace.
+   */
   jurisdiction?: DurableObjectJurisdiction;
   /**
-  * Map the parsed message into the function's args. Defaults to passing the
-  * whole {@link InboundEmail} with binary attachment `content` base64-encoded
-  * (see {@link toJsonSafeEmail}) so it survives the JSON-serialised RPC body.
-  */
+   * Map the parsed message into the function's args. Defaults to passing the
+   * whole {@link InboundEmail} with binary attachment `content` base64-encoded
+   * (see {@link toJsonSafeEmail}) so it survives the JSON-serialised RPC body.
+   */
   resolveArgs?: (email: InboundEmail, context: InboundDispatchContext<TEnv>) => unknown;
   /** The `SHARD` Durable Object namespace. */
   shard: ShardNamespaceLike;
@@ -178,16 +293,146 @@ interface DispatchToLunoraFunctionOptions<TEnv = Record<string, unknown>> {
   shardKey?: string;
 }
 /**
-* 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.
-*
-* SECURITY: the RPC carries the admin bearer, so the target function runs with
-* RLS bypassed over fully attacker-controlled, spoofable input — see the module
-* docstring. Verify the sender (`verify` hook / `email.authentication`) before
-* making any trust decision in the target function.
-*/
+ * 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 — 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
+ * docstring. Verify the sender (`verify` hook / `email.authentication`) before
+ * making any trust decision in the target function.
+ */
 declare const dispatchToLunoraFunction: <TEnv extends Record<string, unknown> = Record<string, unknown>>(options: DispatchToLunoraFunctionOptions<TEnv>) => InboundDispatch<TEnv>;
-export { type DispatchToLunoraFunctionOptions, type ForwardableEmailMessageLike, type InboundAttachment, type InboundAuthentication, type InboundDispatch, type InboundDispatchContext, type InboundEmail, type InboundEmailHandler, type InboundEmailHandlerOptions, type InboundVerify, type RawInboundEmail, type RpcEnvelope, type ShardNamespaceLike, createInboundEmailHandler, dispatchToLunoraFunction, parseInboundEmail };
+export {
+/**
+ * `@lunora/mail/inbound` — inbound Email Routing support.
+ *
+ * Wire a Cloudflare Email Worker entry to route received mail into a Lunora
+ * mutation/action:
+ *
+ * ```ts
+ * import { createInboundEmailHandler, parseInboundEmail, dispatchToLunoraFunction } from "@lunora/mail/inbound";
+ *
+ * export const email = createInboundEmailHandler({
+ *     parse: parseInboundEmail,
+ *     dispatch: dispatchToLunoraFunction({ shard: env.SHARD, functionPath: "inbound:onEmail" }),
+ * });
+ * ```
+ */
+type DispatchToLunoraFunctionOptions,
+/**
+ * `@lunora/mail/inbound` — inbound Email Routing support.
+ *
+ * Wire a Cloudflare Email Worker entry to route received mail into a Lunora
+ * mutation/action:
+ *
+ * ```ts
+ * import { createInboundEmailHandler, parseInboundEmail, dispatchToLunoraFunction } from "@lunora/mail/inbound";
+ *
+ * export const email = createInboundEmailHandler({
+ *     parse: parseInboundEmail,
+ *     dispatch: dispatchToLunoraFunction({ shard: env.SHARD, functionPath: "inbound:onEmail" }),
+ * });
+ * ```
+ */
+type ForwardableEmailMessageLike, type InboundAttachment, type InboundAuthentication,
+/**
+ * `@lunora/mail/inbound` — inbound Email Routing support.
+ *
+ * Wire a Cloudflare Email Worker entry to route received mail into a Lunora
+ * mutation/action:
+ *
+ * ```ts
+ * import { createInboundEmailHandler, parseInboundEmail, dispatchToLunoraFunction } from "@lunora/mail/inbound";
+ *
+ * export const email = createInboundEmailHandler({
+ *     parse: parseInboundEmail,
+ *     dispatch: dispatchToLunoraFunction({ shard: env.SHARD, functionPath: "inbound:onEmail" }),
+ * });
+ * ```
+ */
+type InboundDispatch,
+/**
+ * `@lunora/mail/inbound` — inbound Email Routing support.
+ *
+ * Wire a Cloudflare Email Worker entry to route received mail into a Lunora
+ * mutation/action:
+ *
+ * ```ts
+ * import { createInboundEmailHandler, parseInboundEmail, dispatchToLunoraFunction } from "@lunora/mail/inbound";
+ *
+ * export const email = createInboundEmailHandler({
+ *     parse: parseInboundEmail,
+ *     dispatch: dispatchToLunoraFunction({ shard: env.SHARD, functionPath: "inbound:onEmail" }),
+ * });
+ * ```
+ */
+type InboundDispatchContext, type InboundEmail,
+/**
+ * `@lunora/mail/inbound` — inbound Email Routing support.
+ *
+ * Wire a Cloudflare Email Worker entry to route received mail into a Lunora
+ * mutation/action:
+ *
+ * ```ts
+ * import { createInboundEmailHandler, parseInboundEmail, dispatchToLunoraFunction } from "@lunora/mail/inbound";
+ *
+ * export const email = createInboundEmailHandler({
+ *     parse: parseInboundEmail,
+ *     dispatch: dispatchToLunoraFunction({ shard: env.SHARD, functionPath: "inbound:onEmail" }),
+ * });
+ * ```
+ */
+type InboundEmailHandler,
+/**
+ * `@lunora/mail/inbound` — inbound Email Routing support.
+ *
+ * Wire a Cloudflare Email Worker entry to route received mail into a Lunora
+ * mutation/action:
+ *
+ * ```ts
+ * import { createInboundEmailHandler, parseInboundEmail, dispatchToLunoraFunction } from "@lunora/mail/inbound";
+ *
+ * export const email = createInboundEmailHandler({
+ *     parse: parseInboundEmail,
+ *     dispatch: dispatchToLunoraFunction({ shard: env.SHARD, functionPath: "inbound:onEmail" }),
+ * });
+ * ```
+ */
+type InboundEmailHandlerOptions,
+/**
+ * `@lunora/mail/inbound` — inbound Email Routing support.
+ *
+ * Wire a Cloudflare Email Worker entry to route received mail into a Lunora
+ * mutation/action:
+ *
+ * ```ts
+ * import { createInboundEmailHandler, parseInboundEmail, dispatchToLunoraFunction } from "@lunora/mail/inbound";
+ *
+ * export const email = createInboundEmailHandler({
+ *     parse: parseInboundEmail,
+ *     dispatch: dispatchToLunoraFunction({ shard: env.SHARD, functionPath: "inbound:onEmail" }),
+ * });
+ * ```
+ */
+type InboundVerify, type RawInboundEmail,
+/**
+ * `@lunora/mail/inbound` — inbound Email Routing support.
+ *
+ * Wire a Cloudflare Email Worker entry to route received mail into a Lunora
+ * mutation/action:
+ *
+ * ```ts
+ * import { createInboundEmailHandler, parseInboundEmail, dispatchToLunoraFunction } from "@lunora/mail/inbound";
+ *
+ * export const email = createInboundEmailHandler({
+ *     parse: parseInboundEmail,
+ *     dispatch: dispatchToLunoraFunction({ shard: env.SHARD, functionPath: "inbound:onEmail" }),
+ * });
+ * ```
+ */
+type RpcEnvelope, type ShardNamespaceLike, createInboundEmailHandler, dispatchToLunoraFunction, parseInboundEmail };