@lunora/mail 1.0.0-alpha.12 → 1.0.0-alpha.120

package/dist/index.d.mts

@@ -1,20 +1,20 @@
-import { M as MailTransport, L as LunoraMailOptions, a as Mailer, b as MailboxSink, S as SendOptions } from "./packem_shared/capture-transport.d-ChnhdPO2.mjs";
-export { type C as CapturedMail, type Q as QueueLike, type c as SendPayload, d as createCaptureTransport } from "./packem_shared/capture-transport.d-ChnhdPO2.mjs";
-import { D as DurableObjectJurisdiction } from "./packem_shared/shard.d-CL2Lmliv.mjs";
+import { M as MailTransport, L as LunoraMailOptions, a as Mailer, Q as QueueLike, b as MailboxSink, S as SendOptions } from "./packem_shared/capture-transport.d-BD67fxbB.mjs";
+export { type C as CapturedMail, type c as SendPayload, d as createCaptureTransport } from "./packem_shared/capture-transport.d-BD67fxbB.mjs";
+import { D as DurableObjectJurisdiction } from "./packem_shared/shard.d-DVADjmEJ.mjs";
 import { ReactElement } from 'react';
 /**
-* Sends a raw RFC 822 message through a Worker's Email send binding. The Workers
-* runtime owns the binding, so the caller supplies this thin callback — keeping
-* `@lunora/mail` free of a `cloudflare:email` import and unit-testable. Wire it
-* in your project as:
-*
-* ```ts
-* send: async (from, to, raw) => {
-*     const { EmailMessage } = await import("cloudflare:email");
-*     await env.SEND_EMAIL.send(new EmailMessage(from, to, raw));
-* }
-* ```
-*/
+ * Sends a raw RFC 822 message through a Worker's Email send binding. The Workers
+ * runtime owns the binding, so the caller supplies this thin callback — keeping
+ * `@lunora/mail` free of a `cloudflare:email` import and unit-testable. Wire it
+ * in your project as:
+ *
+ * ```ts
+ * send: async (from, to, raw) => {
+ *     const { EmailMessage } = await import("cloudflare:email");
+ *     await env.SEND_EMAIL.send(new EmailMessage(from, to, raw));
+ * }
+ * ```
+ */
 type CloudflareSend = (from: string, to: string, raw: string) => Promise<void>;
 interface CloudflareTransportOptions {
   /** Default sender used when a `SendOptions.from` isn't supplied. */
@@ -23,75 +23,89 @@ interface CloudflareTransportOptions {
   send: CloudflareSend;
 }
 /**
-* Build the default Cloudflare Email Workers transport via `@visulima/email`.
-* Cloudflare's `send_email` binding is **single-recipient** and only delivers to
-* **verified Email Routing destination addresses**, and the underlying provider
-* rejects any `cc`/`bcc` or a non-single `to` outright. So this enforces a single
-* `to` recipient (throwing a clear error instead of silently dropping the rest)
-* and rejects `cc`/`bcc` rather than forwarding them into a generic "send failed".
-* Multi-recipient transactional mail must fan out one send per recipient at the
-* call site. In dev the capture transport intercepts before this runs, so the
-* verified-address constraint never bites the dev loop.
-*/
+ * Build the default Cloudflare Email Workers transport via `@visulima/email`.
+ * Cloudflare's `send_email` binding is **single-recipient** and only delivers to
+ * **verified Email Routing destination addresses**, and the underlying provider
+ * rejects any `cc`/`bcc` or a non-single `to` outright. So this enforces a single
+ * `to` recipient (throwing a clear error instead of silently dropping the rest)
+ * and rejects `cc`/`bcc` rather than forwarding them into a generic "send failed".
+ * Multi-recipient transactional mail must fan out one send per recipient at the
+ * call site. In dev the capture transport intercepts before this runs, so the
+ * verified-address constraint never bites the dev loop.
+ */
 declare const createCloudflareTransport: (options: CloudflareTransportOptions) => MailTransport;
 /**
-* Create a mailer bound to a transport.
-*
-* SECURITY — recipient policy and HTML content are the caller's responsibility.
-* The mailer fully blocks header/CRLF/comma injection in addresses
-* (`assertSafeAddresses` / `assertSafeHeaderValue`), but it does NOT decide WHO
-* you may send to or WHAT HTML you render.
-*
-* Open relay: derive `to`/`cc`/`bcc` from server-trusted state, never from raw
-* request input, and prefer a fixed/allowlisted `from` — sending to an arbitrary
-* user-supplied address turns your deployment into a spam relay.
-*
-* Template XSS / content injection: treat template HTML like any other HTML sink
-* — never interpolate untrusted data into raw markup (or a
-* `dangerouslySetInnerHTML`-style template) without escaping. The mailer sends
-* whatever HTML you hand it verbatim.
-*/
+ * Create a mailer bound to a transport.
+ *
+ * SECURITY — recipient policy and HTML content are the caller's responsibility.
+ * The mailer fully blocks header/CRLF/comma injection in addresses
+ * (`assertSafeAddresses` / `assertSafeHeaderValue`), but it does NOT decide WHO
+ * you may send to or WHAT HTML you render.
+ *
+ * Open relay: derive `to`/`cc`/`bcc` from server-trusted state, never from raw
+ * request input, and prefer a fixed/allowlisted `from` — sending to an arbitrary
+ * user-supplied address turns your deployment into a spam relay.
+ *
+ * Template XSS / content injection: treat template HTML like any other HTML sink
+ * — never interpolate untrusted data into raw markup (or a
+ * `dangerouslySetInnerHTML`-style template) without escaping. The mailer sends
+ * whatever HTML you hand it verbatim.
+ */
 declare const createMailer: (options: LunoraMailOptions) => Mailer;
 /** A Worker `env` projected as a plain record (vars, secrets, and bindings are `unknown`-valued). */
 type MailEnv = Record<string, unknown>;
 /** Options for {@link createMailerFromEnv}. */
 interface FromEnvOptions {
-  /** RFC 822 send callback bound to the Worker's `send_email` binding (Cloudflare default transport). */
+  /**
+   * RFC 822 send callback bound to the Worker's Cloudflare Email binding (the
+   * default transport). Honoured whenever it is passed, whatever the binding is
+   * named: passing it is the caller's choice of transport, so pass it only when
+   * the binding exists.
+   */
   cloudflareSend?: CloudflareSend;
   /**
-  * Pin the captured-mail inbox shard to a Cloudflare data-residency
-  * jurisdiction. Pass the same value as the worker's `jurisdiction` so the
-  * dev inbox co-resides with app data. Omit for the un-pinned global namespace.
-  */
+   * Pin the captured-mail inbox shard to a Cloudflare data-residency
+   * jurisdiction. Defaults to the jurisdiction the schema declares
+   * (`.jurisdiction("eu")`), so a generated app needs nothing here; set it only
+   * for a hand-written worker, to the same value as its `jurisdiction`. A value
+   * that contradicts the schema's throws.
+   */
   jurisdiction?: DurableObjectJurisdiction;
+  /** Cloudflare Queue binding backing `mailer.queue()`; without it `queue()` throws outside capture mode. */
+  queue?: QueueLike;
   /** Shard the captured-mail inbox lives on; override if your worker sets a custom `defaultShardKey`. */
   rootShard?: string;
 }
 /**
-* Whether outbound mail should be captured (into the studio inbox) rather than
-* delivered. Explicit `LUNORA_MAIL_CAPTURE` (`"1"`/`"true"` vs `"0"`/`"false"`)
-* always wins; unset, capture is on only in a development environment. It does
-* NOT fall back to "no SEND_EMAIL binding ⇒ capture" — a production deploy that
-* forgot the binding must fail loudly on send, not silently swallow mail.
-*/
+ * Whether outbound mail should be captured (into the studio inbox) rather than
+ * delivered. Explicit `LUNORA_MAIL_CAPTURE` (`"1"`/`"true"` vs `"0"`/`"false"`)
+ * always wins; unset, capture is on only when every set environment var (`CF_ENV`,
+ * `ENVIRONMENT`, `NODE_ENV`, `WORKER_ENV`) names a development one. It does
+ * NOT fall back to "no SEND_EMAIL binding ⇒ capture" — a production deploy that
+ * forgot the binding must fail loudly on send, not silently swallow mail.
+ */
 declare const shouldCaptureMail: (env: MailEnv) => boolean;
 /**
-* Build the {@link MailboxSink} that records a captured message into the studio's
-* root-shard inbox via the reserved `recordMail` admin RPC — the same
-* worker→root-shard path the runtime uses for auth events. Best-effort: without
-* the `SHARD` binding or `LUNORA_ADMIN_TOKEN` it returns a sentinel id so a send
-* never fails for lack of somewhere to record.
-*/
+ * Build the {@link MailboxSink} that records a captured message into the studio's
+ * root-shard inbox via the reserved `recordMail` admin RPC — the same
+ * worker→root-shard path the runtime uses for auth events. Best-effort: without
+ * the `SHARD` binding or `LUNORA_ADMIN_TOKEN` it returns a sentinel id so a send
+ * never fails for lack of somewhere to record — but it says so first (see below).
+ */
 declare const createCaptureSink: (env: MailEnv, rootShard?: string, jurisdiction?: DurableObjectJurisdiction) => MailboxSink;
 /**
-* Build a {@link Mailer} from a Worker `env`. In a dev environment every send is
-* captured into the studio's Mail inbox; otherwise it delivers via the supplied
-* `cloudflareSend` (the `SEND_EMAIL` binding) or, failing that, `RESEND_API_KEY`.
-* Throws when neither a capture context nor a real transport is available, so a
-* misconfigured production deploy fails loudly instead of silently dropping mail.
-*
-* `MAIL_FROM` is required (the default sender).
-*/
+ * Build a {@link Mailer} from a Worker `env`. In a dev environment every send is
+ * captured into the studio's Mail inbox; otherwise it delivers via the supplied
+ * `cloudflareSend` (when passed) or,
+ * failing that, `RESEND_API_KEY`. With no real transport `send()` rejects, so a
+ * misconfigured production deploy fails loudly instead of silently dropping mail
+ * — while `queue()` still works for a producer-only worker.
+ *
+ * A queue consumer should build its mailer here too: `consumeQueuedSend` goes
+ * through `send()`, so in dev queued mail is captured at consume time.
+ *
+ * `MAIL_FROM` is required (the default sender).
+ */
 declare const createMailerFromEnv: (env: MailEnv, options?: FromEnvOptions) => Mailer;
 /** Serializable representation of a `SendOptions` payload — drops the `react` field. */
 interface QueuedSend {
@@ -100,51 +114,84 @@ interface QueuedSend {
   from?: string;
   headers?: Record<string, string>;
   html?: string;
+  /**
+   * Stable dedup key, minted at enqueue time by `createMailer(...).queue()` — see
+   * `SendOptions.idempotencyKey`. Carried through untouched by `consumeQueuedSend`;
+   * a consumer wanting exactly-once delivery dedupes against its own store using it.
+   */
+  idempotencyKey?: string;
   replyTo?: string;
   subject: string;
   text?: string;
   to: string | string[];
 }
 /**
-* Narrow a `SendOptions` to its serializable `QueuedSend` shape by dropping the
-* non-cloneable `react` field. React elements are not structured-cloneable, so
-* the queue body must carry only the pre-rendered html/text and scalar fields.
-*/
+ * Narrow a `SendOptions` to its serializable `QueuedSend` shape by dropping the
+ * non-cloneable `react` field. React elements are not structured-cloneable, so
+ * the queue body must carry only the pre-rendered html/text and scalar fields.
+ */
 declare const toQueuedPayload: (options: SendOptions) => QueuedSend;
 /**
-* Helper used by Queue consumers: rehydrate a `QueuedSend` payload and forward
-* to a configured `Mailer.send()`. Use this inside your Worker's `queue()`
-* handler.
-*
-* ```ts
-* export default {
-*   queue: async (batch, env) => {
-*     const mailer = createMailer({ apiKey: env.RESEND_API_KEY, from: "..." });
-*     for (const message of batch.messages) {
-*       await consumeQueuedSend(mailer, message.body);
-*     }
-*   },
-* };
-* ```
-*/
+ * Helper used by Queue consumers: rehydrate a `QueuedSend` payload and forward
+ * to a configured `Mailer.send()`. Use this inside your Worker's `queue()`
+ * handler.
+ *
+ * DEDUPE IS THE CONSUMER'S JOB, and this helper does not do it. The payload's
+ * `idempotencyKey` was minted once at enqueue time so it survives redelivery, but
+ * nothing downstream reads it: no transport forwards it to the provider (Resend
+ * dedupes on an `Idempotency-Key` REQUEST header, which the provider client offers
+ * no hook for — its `headers` field becomes message headers in the body). A
+ * consumer that only acks is correct for the failure the ack covers and sends a
+ * duplicate for the one it does not: the provider accepted the message and the
+ * worker died before acking.
+ *
+ * The recipe below NARROWS that window; it does not close it, and nothing on
+ * this path can. The mark is written after the provider accepted the message, so
+ * a crash in between still redelivers and resends, and a KV read is eventually
+ * consistent — a redelivery seconds later can miss a mark that was written.
+ * Delivery is at-least-once end to end. An app that must not double-send needs a
+ * strongly-consistent mark taken BEFORE the send (a Durable Object or D1 row
+ * claimed by this key, released on failure), and even then the send-then-crash
+ * window is only ever traded for a send-that-may-not-have-happened one.
+ *
+ * ```ts
+ * export default {
+ *   queue: async (batch, env) => {
+ *     // createMailerFromEnv, so dev captures the message here instead of sending it.
+ *     const mailer = createMailerFromEnv(env);
+ *     for (const message of batch.messages) {
+ *       const { idempotencyKey } = message.body;
+ *       if (await env.SENT.get(idempotencyKey)) { message.ack(); continue; }
+ *       await consumeQueuedSend(mailer, message.body);
+ *       await env.SENT.put(idempotencyKey, "1", { expirationTtl: 86_400 });
+ *       message.ack();
+ *     }
+ *   },
+ * };
+ * ```
+ */
 declare const consumeQueuedSend: (mailer: Mailer, payload: unknown) => Promise<{
   id: string;
 }>;
 /**
-* Render a React element to an HTML/text pair suitable for inlining into a
-* provider payload. Wraps `@react-email/render` so we can swap to
-* `@visulima/email`'s react-email template engine without touching callers.
-*/
+ * Render a React element to an HTML/text pair suitable for inlining into a
+ * provider payload. Wraps `@react-email/render` so we can swap to
+ * `@visulima/email`'s react-email template engine without touching callers.
+ *
+ * The renderer is imported lazily so its top-level evaluation (prettier and
+ * html-to-text, in its workerd build) is deferred until the first React render
+ * instead of running on cold start. Bundlers may still include the code.
+ */
 declare const renderEmail: (element: ReactElement) => Promise<{
   html: string;
   text: string;
 }>;
 /**
-* Build a Resend-backed transport via `@visulima/email`. Wraps the provider's
-* `sendEmail()` into the minimal `{ send(payload) -> { id } }` shape the rest of
-* `@lunora/mail` consumes. Kept reachable as a named export so a project that
-* prefers Resend over the Cloudflare default can pass
-* `transport: createResendTransport(apiKey, from)` to `createMailer`.
-*/
+ * Build a Resend-backed transport via `@visulima/email`. Wraps the provider's
+ * `sendEmail()` into the minimal `{ send(payload) -> { id } }` shape the rest of
+ * `@lunora/mail` consumes. Kept reachable as a named export so a project that
+ * prefers Resend over the Cloudflare default can pass
+ * `transport: createResendTransport(apiKey, from)` to `createMailer`.
+ */
 declare const createResendTransport: (apiKey: string, defaultFrom: string) => MailTransport;
-export { type CloudflareSend, type CloudflareTransportOptions, type FromEnvOptions, type LunoraMailOptions, type MailEnv, type MailTransport, type MailboxSink, type Mailer, type QueuedSend, type SendOptions, consumeQueuedSend, createCaptureSink, createCloudflareTransport, createMailer, createMailerFromEnv, createResendTransport, renderEmail, shouldCaptureMail, toQueuedPayload };
+export { type CloudflareSend, type CloudflareTransportOptions, type FromEnvOptions, type LunoraMailOptions, type MailEnv, type MailTransport, type MailboxSink, type Mailer, type QueueLike, type QueuedSend, type SendOptions, consumeQueuedSend, createCaptureSink, createCloudflareTransport, createMailer, createMailerFromEnv, createResendTransport, renderEmail, shouldCaptureMail, toQueuedPayload };

package/dist/index.d.ts

@@ -1,20 +1,20 @@
-import { M as MailTransport, L as LunoraMailOptions, a as Mailer, b as MailboxSink, S as SendOptions } from "./packem_shared/capture-transport.d-ChnhdPO2.js";
-export { type C as CapturedMail, type Q as QueueLike, type c as SendPayload, d as createCaptureTransport } from "./packem_shared/capture-transport.d-ChnhdPO2.js";
-import { D as DurableObjectJurisdiction } from "./packem_shared/shard.d-CL2Lmliv.js";
+import { M as MailTransport, L as LunoraMailOptions, a as Mailer, Q as QueueLike, b as MailboxSink, S as SendOptions } from "./packem_shared/capture-transport.d-BD67fxbB.js";
+export { type C as CapturedMail, type c as SendPayload, d as createCaptureTransport } from "./packem_shared/capture-transport.d-BD67fxbB.js";
+import { D as DurableObjectJurisdiction } from "./packem_shared/shard.d-DVADjmEJ.js";
 import { ReactElement } from 'react';
 /**
-* Sends a raw RFC 822 message through a Worker's Email send binding. The Workers
-* runtime owns the binding, so the caller supplies this thin callback — keeping
-* `@lunora/mail` free of a `cloudflare:email` import and unit-testable. Wire it
-* in your project as:
-*
-* ```ts
-* send: async (from, to, raw) => {
-*     const { EmailMessage } = await import("cloudflare:email");
-*     await env.SEND_EMAIL.send(new EmailMessage(from, to, raw));
-* }
-* ```
-*/
+ * Sends a raw RFC 822 message through a Worker's Email send binding. The Workers
+ * runtime owns the binding, so the caller supplies this thin callback — keeping
+ * `@lunora/mail` free of a `cloudflare:email` import and unit-testable. Wire it
+ * in your project as:
+ *
+ * ```ts
+ * send: async (from, to, raw) => {
+ *     const { EmailMessage } = await import("cloudflare:email");
+ *     await env.SEND_EMAIL.send(new EmailMessage(from, to, raw));
+ * }
+ * ```
+ */
 type CloudflareSend = (from: string, to: string, raw: string) => Promise<void>;
 interface CloudflareTransportOptions {
   /** Default sender used when a `SendOptions.from` isn't supplied. */
@@ -23,75 +23,89 @@ interface CloudflareTransportOptions {
   send: CloudflareSend;
 }
 /**
-* Build the default Cloudflare Email Workers transport via `@visulima/email`.
-* Cloudflare's `send_email` binding is **single-recipient** and only delivers to
-* **verified Email Routing destination addresses**, and the underlying provider
-* rejects any `cc`/`bcc` or a non-single `to` outright. So this enforces a single
-* `to` recipient (throwing a clear error instead of silently dropping the rest)
-* and rejects `cc`/`bcc` rather than forwarding them into a generic "send failed".
-* Multi-recipient transactional mail must fan out one send per recipient at the
-* call site. In dev the capture transport intercepts before this runs, so the
-* verified-address constraint never bites the dev loop.
-*/
+ * Build the default Cloudflare Email Workers transport via `@visulima/email`.
+ * Cloudflare's `send_email` binding is **single-recipient** and only delivers to
+ * **verified Email Routing destination addresses**, and the underlying provider
+ * rejects any `cc`/`bcc` or a non-single `to` outright. So this enforces a single
+ * `to` recipient (throwing a clear error instead of silently dropping the rest)
+ * and rejects `cc`/`bcc` rather than forwarding them into a generic "send failed".
+ * Multi-recipient transactional mail must fan out one send per recipient at the
+ * call site. In dev the capture transport intercepts before this runs, so the
+ * verified-address constraint never bites the dev loop.
+ */
 declare const createCloudflareTransport: (options: CloudflareTransportOptions) => MailTransport;
 /**
-* Create a mailer bound to a transport.
-*
-* SECURITY — recipient policy and HTML content are the caller's responsibility.
-* The mailer fully blocks header/CRLF/comma injection in addresses
-* (`assertSafeAddresses` / `assertSafeHeaderValue`), but it does NOT decide WHO
-* you may send to or WHAT HTML you render.
-*
-* Open relay: derive `to`/`cc`/`bcc` from server-trusted state, never from raw
-* request input, and prefer a fixed/allowlisted `from` — sending to an arbitrary
-* user-supplied address turns your deployment into a spam relay.
-*
-* Template XSS / content injection: treat template HTML like any other HTML sink
-* — never interpolate untrusted data into raw markup (or a
-* `dangerouslySetInnerHTML`-style template) without escaping. The mailer sends
-* whatever HTML you hand it verbatim.
-*/
+ * Create a mailer bound to a transport.
+ *
+ * SECURITY — recipient policy and HTML content are the caller's responsibility.
+ * The mailer fully blocks header/CRLF/comma injection in addresses
+ * (`assertSafeAddresses` / `assertSafeHeaderValue`), but it does NOT decide WHO
+ * you may send to or WHAT HTML you render.
+ *
+ * Open relay: derive `to`/`cc`/`bcc` from server-trusted state, never from raw
+ * request input, and prefer a fixed/allowlisted `from` — sending to an arbitrary
+ * user-supplied address turns your deployment into a spam relay.
+ *
+ * Template XSS / content injection: treat template HTML like any other HTML sink
+ * — never interpolate untrusted data into raw markup (or a
+ * `dangerouslySetInnerHTML`-style template) without escaping. The mailer sends
+ * whatever HTML you hand it verbatim.
+ */
 declare const createMailer: (options: LunoraMailOptions) => Mailer;
 /** A Worker `env` projected as a plain record (vars, secrets, and bindings are `unknown`-valued). */
 type MailEnv = Record<string, unknown>;
 /** Options for {@link createMailerFromEnv}. */
 interface FromEnvOptions {
-  /** RFC 822 send callback bound to the Worker's `send_email` binding (Cloudflare default transport). */
+  /**
+   * RFC 822 send callback bound to the Worker's Cloudflare Email binding (the
+   * default transport). Honoured whenever it is passed, whatever the binding is
+   * named: passing it is the caller's choice of transport, so pass it only when
+   * the binding exists.
+   */
   cloudflareSend?: CloudflareSend;
   /**
-  * Pin the captured-mail inbox shard to a Cloudflare data-residency
-  * jurisdiction. Pass the same value as the worker's `jurisdiction` so the
-  * dev inbox co-resides with app data. Omit for the un-pinned global namespace.
-  */
+   * Pin the captured-mail inbox shard to a Cloudflare data-residency
+   * jurisdiction. Defaults to the jurisdiction the schema declares
+   * (`.jurisdiction("eu")`), so a generated app needs nothing here; set it only
+   * for a hand-written worker, to the same value as its `jurisdiction`. A value
+   * that contradicts the schema's throws.
+   */
   jurisdiction?: DurableObjectJurisdiction;
+  /** Cloudflare Queue binding backing `mailer.queue()`; without it `queue()` throws outside capture mode. */
+  queue?: QueueLike;
   /** Shard the captured-mail inbox lives on; override if your worker sets a custom `defaultShardKey`. */
   rootShard?: string;
 }
 /**
-* Whether outbound mail should be captured (into the studio inbox) rather than
-* delivered. Explicit `LUNORA_MAIL_CAPTURE` (`"1"`/`"true"` vs `"0"`/`"false"`)
-* always wins; unset, capture is on only in a development environment. It does
-* NOT fall back to "no SEND_EMAIL binding ⇒ capture" — a production deploy that
-* forgot the binding must fail loudly on send, not silently swallow mail.
-*/
+ * Whether outbound mail should be captured (into the studio inbox) rather than
+ * delivered. Explicit `LUNORA_MAIL_CAPTURE` (`"1"`/`"true"` vs `"0"`/`"false"`)
+ * always wins; unset, capture is on only when every set environment var (`CF_ENV`,
+ * `ENVIRONMENT`, `NODE_ENV`, `WORKER_ENV`) names a development one. It does
+ * NOT fall back to "no SEND_EMAIL binding ⇒ capture" — a production deploy that
+ * forgot the binding must fail loudly on send, not silently swallow mail.
+ */
 declare const shouldCaptureMail: (env: MailEnv) => boolean;
 /**
-* Build the {@link MailboxSink} that records a captured message into the studio's
-* root-shard inbox via the reserved `recordMail` admin RPC — the same
-* worker→root-shard path the runtime uses for auth events. Best-effort: without
-* the `SHARD` binding or `LUNORA_ADMIN_TOKEN` it returns a sentinel id so a send
-* never fails for lack of somewhere to record.
-*/
+ * Build the {@link MailboxSink} that records a captured message into the studio's
+ * root-shard inbox via the reserved `recordMail` admin RPC — the same
+ * worker→root-shard path the runtime uses for auth events. Best-effort: without
+ * the `SHARD` binding or `LUNORA_ADMIN_TOKEN` it returns a sentinel id so a send
+ * never fails for lack of somewhere to record — but it says so first (see below).
+ */
 declare const createCaptureSink: (env: MailEnv, rootShard?: string, jurisdiction?: DurableObjectJurisdiction) => MailboxSink;
 /**
-* Build a {@link Mailer} from a Worker `env`. In a dev environment every send is
-* captured into the studio's Mail inbox; otherwise it delivers via the supplied
-* `cloudflareSend` (the `SEND_EMAIL` binding) or, failing that, `RESEND_API_KEY`.
-* Throws when neither a capture context nor a real transport is available, so a
-* misconfigured production deploy fails loudly instead of silently dropping mail.
-*
-* `MAIL_FROM` is required (the default sender).
-*/
+ * Build a {@link Mailer} from a Worker `env`. In a dev environment every send is
+ * captured into the studio's Mail inbox; otherwise it delivers via the supplied
+ * `cloudflareSend` (when passed) or,
+ * failing that, `RESEND_API_KEY`. With no real transport `send()` rejects, so a
+ * misconfigured production deploy fails loudly instead of silently dropping mail
+ * — while `queue()` still works for a producer-only worker.
+ *
+ * A queue consumer should build its mailer here too: `consumeQueuedSend` goes
+ * through `send()`, so in dev queued mail is captured at consume time.
+ *
+ * `MAIL_FROM` is required (the default sender).
+ */
 declare const createMailerFromEnv: (env: MailEnv, options?: FromEnvOptions) => Mailer;
 /** Serializable representation of a `SendOptions` payload — drops the `react` field. */
 interface QueuedSend {
@@ -100,51 +114,84 @@ interface QueuedSend {
   from?: string;
   headers?: Record<string, string>;
   html?: string;
+  /**
+   * Stable dedup key, minted at enqueue time by `createMailer(...).queue()` — see
+   * `SendOptions.idempotencyKey`. Carried through untouched by `consumeQueuedSend`;
+   * a consumer wanting exactly-once delivery dedupes against its own store using it.
+   */
+  idempotencyKey?: string;
   replyTo?: string;
   subject: string;
   text?: string;
   to: string | string[];
 }
 /**
-* Narrow a `SendOptions` to its serializable `QueuedSend` shape by dropping the
-* non-cloneable `react` field. React elements are not structured-cloneable, so
-* the queue body must carry only the pre-rendered html/text and scalar fields.
-*/
+ * Narrow a `SendOptions` to its serializable `QueuedSend` shape by dropping the
+ * non-cloneable `react` field. React elements are not structured-cloneable, so
+ * the queue body must carry only the pre-rendered html/text and scalar fields.
+ */
 declare const toQueuedPayload: (options: SendOptions) => QueuedSend;
 /**
-* Helper used by Queue consumers: rehydrate a `QueuedSend` payload and forward
-* to a configured `Mailer.send()`. Use this inside your Worker's `queue()`
-* handler.
-*
-* ```ts
-* export default {
-*   queue: async (batch, env) => {
-*     const mailer = createMailer({ apiKey: env.RESEND_API_KEY, from: "..." });
-*     for (const message of batch.messages) {
-*       await consumeQueuedSend(mailer, message.body);
-*     }
-*   },
-* };
-* ```
-*/
+ * Helper used by Queue consumers: rehydrate a `QueuedSend` payload and forward
+ * to a configured `Mailer.send()`. Use this inside your Worker's `queue()`
+ * handler.
+ *
+ * DEDUPE IS THE CONSUMER'S JOB, and this helper does not do it. The payload's
+ * `idempotencyKey` was minted once at enqueue time so it survives redelivery, but
+ * nothing downstream reads it: no transport forwards it to the provider (Resend
+ * dedupes on an `Idempotency-Key` REQUEST header, which the provider client offers
+ * no hook for — its `headers` field becomes message headers in the body). A
+ * consumer that only acks is correct for the failure the ack covers and sends a
+ * duplicate for the one it does not: the provider accepted the message and the
+ * worker died before acking.
+ *
+ * The recipe below NARROWS that window; it does not close it, and nothing on
+ * this path can. The mark is written after the provider accepted the message, so
+ * a crash in between still redelivers and resends, and a KV read is eventually
+ * consistent — a redelivery seconds later can miss a mark that was written.
+ * Delivery is at-least-once end to end. An app that must not double-send needs a
+ * strongly-consistent mark taken BEFORE the send (a Durable Object or D1 row
+ * claimed by this key, released on failure), and even then the send-then-crash
+ * window is only ever traded for a send-that-may-not-have-happened one.
+ *
+ * ```ts
+ * export default {
+ *   queue: async (batch, env) => {
+ *     // createMailerFromEnv, so dev captures the message here instead of sending it.
+ *     const mailer = createMailerFromEnv(env);
+ *     for (const message of batch.messages) {
+ *       const { idempotencyKey } = message.body;
+ *       if (await env.SENT.get(idempotencyKey)) { message.ack(); continue; }
+ *       await consumeQueuedSend(mailer, message.body);
+ *       await env.SENT.put(idempotencyKey, "1", { expirationTtl: 86_400 });
+ *       message.ack();
+ *     }
+ *   },
+ * };
+ * ```
+ */
 declare const consumeQueuedSend: (mailer: Mailer, payload: unknown) => Promise<{
   id: string;
 }>;
 /**
-* Render a React element to an HTML/text pair suitable for inlining into a
-* provider payload. Wraps `@react-email/render` so we can swap to
-* `@visulima/email`'s react-email template engine without touching callers.
-*/
+ * Render a React element to an HTML/text pair suitable for inlining into a
+ * provider payload. Wraps `@react-email/render` so we can swap to
+ * `@visulima/email`'s react-email template engine without touching callers.
+ *
+ * The renderer is imported lazily so its top-level evaluation (prettier and
+ * html-to-text, in its workerd build) is deferred until the first React render
+ * instead of running on cold start. Bundlers may still include the code.
+ */
 declare const renderEmail: (element: ReactElement) => Promise<{
   html: string;
   text: string;
 }>;
 /**
-* Build a Resend-backed transport via `@visulima/email`. Wraps the provider's
-* `sendEmail()` into the minimal `{ send(payload) -> { id } }` shape the rest of
-* `@lunora/mail` consumes. Kept reachable as a named export so a project that
-* prefers Resend over the Cloudflare default can pass
-* `transport: createResendTransport(apiKey, from)` to `createMailer`.
-*/
+ * Build a Resend-backed transport via `@visulima/email`. Wraps the provider's
+ * `sendEmail()` into the minimal `{ send(payload) -> { id } }` shape the rest of
+ * `@lunora/mail` consumes. Kept reachable as a named export so a project that
+ * prefers Resend over the Cloudflare default can pass
+ * `transport: createResendTransport(apiKey, from)` to `createMailer`.
+ */
 declare const createResendTransport: (apiKey: string, defaultFrom: string) => MailTransport;
-export { type CloudflareSend, type CloudflareTransportOptions, type FromEnvOptions, type LunoraMailOptions, type MailEnv, type MailTransport, type MailboxSink, type Mailer, type QueuedSend, type SendOptions, consumeQueuedSend, createCaptureSink, createCloudflareTransport, createMailer, createMailerFromEnv, createResendTransport, renderEmail, shouldCaptureMail, toQueuedPayload };
+export { type CloudflareSend, type CloudflareTransportOptions, type FromEnvOptions, type LunoraMailOptions, type MailEnv, type MailTransport, type MailboxSink, type Mailer, type QueueLike, type QueuedSend, type SendOptions, consumeQueuedSend, createCaptureSink, createCloudflareTransport, createMailer, createMailerFromEnv, createResendTransport, renderEmail, shouldCaptureMail, toQueuedPayload };

package/dist/index.mjs

@@ -1,7 +1 @@
-export { createCaptureTransport } from './packem_shared/createCaptureTransport-Crz_8822.mjs';
-export { createCloudflareTransport } from './packem_shared/createCloudflareTransport-DXh1nUNi.mjs';
-export { default as createMailer } from './packem_shared/createMailer-B4Z_Cgiu.mjs';
-export { createCaptureSink, createMailerFromEnv, shouldCaptureMail } from './packem_shared/createCaptureSink-Di-5AJUs.mjs';
-export { consumeQueuedSend, toQueuedPayload } from './packem_shared/consumeQueuedSend-B9hTDOZ6.mjs';
-export { default as renderEmail } from './packem_shared/renderEmail-hyS1bpVP.mjs';
-export { default as createResendTransport } from './packem_shared/createResendTransport-CMQWjZoi.mjs';
+import{createCaptureTransport as a}from"./packem_shared/createCaptureTransport-DZhMUmaI.mjs";import{createCloudflareTransport as t}from"./packem_shared/createCloudflareTransport-bWoNSnK_.mjs";import{default as u}from"./packem_shared/createMailer-ImyDcZuj.mjs";import{createCaptureSink as f,createMailerFromEnv as l,shouldCaptureMail as m}from"./packem_shared/createCaptureSink-BIu-c0Kd.mjs";import{consumeQueuedSend as s,toQueuedPayload as c}from"./packem_shared/consumeQueuedSend-CRfALnCU.mjs";import{default as i}from"./packem_shared/renderEmail-CkxYrU2s.mjs";import{default as M}from"./packem_shared/createResendTransport-BMjRlHmy.mjs";export{s as consumeQueuedSend,f as createCaptureSink,a as createCaptureTransport,t as createCloudflareTransport,u as createMailer,l as createMailerFromEnv,M as createResendTransport,i as renderEmail,m as shouldCaptureMail,c as toQueuedPayload};

package/dist/packem_shared/address-oKy_d0aG.mjs

@@ -0,0 +1,3 @@
+import{LunoraError as t}from"@lunora/errors";const n=320,a=256,d=/^([^<]*)<([^>]*)>\s*$/,i=(r,s)=>{if(s.includes("\r")||s.includes(`
+`)||s.includes(","))throw new t("INTERNAL",`@lunora/mail: address ${r} must not contain CR, LF, or comma`)},u=(r,s)=>{if(s.includes("\r")||s.includes(`
+`))throw new t("INTERNAL",`@lunora/mail: ${r} must not contain CR or LF`)},m=(r,s)=>{if(r.length>a)throw new t("INTERNAL",`@lunora/mail: address name must be <= ${String(a)} characters`);if(s.length>n)throw new t("INTERNAL",`@lunora/mail: address email must be <= ${String(n)} characters`);return r&&i("name",r),i("email",s),r?{email:s,name:r}:{email:s}},l=r=>{const s=r.trim();if(s.length>n)throw new t("INTERNAL",`@lunora/mail: address email must be <= ${String(n)} characters`);return i("email",s),{email:s}},c=r=>{const s=d.exec(r),e=(s?.[2]??"").trim();return s&&e?m((s[1]??"").trim(),e):l(r)},o=r=>{if(r===void 0)return;const s=Array.isArray(r)?r:[r];if(s.length!==0)return s.map(e=>c(e))},f=r=>{if(o(r.to)===void 0)throw new t("INTERNAL","@lunora/mail: at least one recipient is required");o(r.cc),o(r.bcc),r.from!==void 0&&c(r.from),r.replyTo!==void 0&&c(r.replyTo)};export{u as a,c as b,f as c,o as t};

package/dist/packem_shared/authenticatesFrom-BOX-Paur.mjs

@@ -0,0 +1 @@
+import p from"postal-mime";import{a as c}from"./address-oKy_d0aG.mjs";const d=(s,e)=>{if(e!==void 0)return c(`inbound ${s}`,e),e},u=s=>s.address!==void 0&&s.address!==""?s.name?`${s.name} <${s.address}>`:s.address:s.group?s.group.map(e=>e.address??"").filter(e=>e!=="").join(", "):s.name??"",l=/"(?:[^"\\]|\\.)*(?:"|$)|\((?:[^()\\]|\\.)*(?:\)|$)/g,g=s=>s.replaceAll(l,e=>e.startsWith('"')?e.replaceAll(/[;=]/gu," "):" "),m=(s,e,r)=>{const i=g(s).matchAll(new RegExp(String.raw`(?:^|;)\s*${e}\s*(?:/\s*\d+\s*)?=\s*([a-z]+)([^;]*)`,"gi")),a=new RegExp(String.raw`\b${r.split(".").join(String.raw`\s*\.\s*`)}\s*=\s*"?([^\s;"]+)`,"i");return[...i].map(t=>{const n=a.exec(t[2]??"")?.[1];return{domain:n===void 0?null:n.slice(n.lastIndexOf("@")+1).toLowerCase(),result:(t[1]??"").toLowerCase()}})},v=s=>s===void 0||s===""?{dkim:[],dmarc:[],spf:[]}:{dkim:m(s,"dkim","header.d"),dmarc:m(s,"dmarc","header.from"),spf:m(s,"spf","smtp.mailfrom")},I=async s=>{const e=await p.parse(s),r={};for(const o of e.headers)c(`inbound header \`${o.key}\``,o.value),r[o.key]=o.value;const i=e.headers.find(o=>o.key==="authentication-results")?.value,a=(e.to??[]).map(o=>{const f=u(o);return c("inbound to",f),f}),t=e.from?u(e.from):"";return c("inbound from",t),{attachments:e.attachments.map(o=>({content:o.content,disposition:o.disposition,...o.encoding===void 0?{}:{encoding:o.encoding},filename:o.filename,mimeType:o.mimeType})),authentication:v(i),from:t,headers:r,...e.html===void 0?{}:{html:e.html},...d("inReplyTo",e.inReplyTo)===void 0?{}:{inReplyTo:e.inReplyTo},...d("messageId",e.messageId)===void 0?{}:{messageId:e.messageId},...d("references",e.references)===void 0?{}:{references:e.references},...d("subject",e.subject)===void 0?{}:{subject:e.subject},...e.text===void 0?{}:{text:e.text},to:a}},h=/<([^<>]*)>$/,x=s=>{const e=h.exec(s)?.[1]??s,r=e.indexOf("@");if(!(r===-1||r!==e.lastIndexOf("@")))return e.slice(r+1).trim().toLowerCase()},$=s=>{const e=x(s.from);if(e===void 0)return!1;const r=n=>n.some(o=>o.result==="pass"&&o.domain===e),{dkim:i,dmarc:a,spf:t}=s.authentication;return r(a)||r(t)||r(i)};export{$ as authenticatesFrom,I as parseInboundEmail};