@lunora/mail 1.0.0-alpha.7 → 1.0.0-alpha.71

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, b as MailboxSink, S as SendOptions } from "./packem_shared/capture-transport.d-BD67fxbB.mjs";
+export { type C as CapturedMail, type Q as QueueLike, 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,34 +23,34 @@ 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>;
@@ -59,39 +59,39 @@ interface FromEnvOptions {
   /** RFC 822 send callback bound to the Worker's `send_email` binding (Cloudflare default transport). */
   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. 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.
+   */
   jurisdiction?: DurableObjectJurisdiction;
   /** 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 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.
+ */
 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` (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).
+ */
 declare const createMailerFromEnv: (env: MailEnv, options?: FromEnvOptions) => Mailer;
 /** Serializable representation of a `SendOptions` payload — drops the `react` field. */
 interface QueuedSend {
@@ -100,51 +100,79 @@ 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) => {
+ *     const mailer = createMailer({ apiKey: env.RESEND_API_KEY, from: "..." });
+ *     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.
+ */
 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 };

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, b as MailboxSink, S as SendOptions } from "./packem_shared/capture-transport.d-BD67fxbB.js";
+export { type C as CapturedMail, type Q as QueueLike, 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,34 +23,34 @@ 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>;
@@ -59,39 +59,39 @@ interface FromEnvOptions {
   /** RFC 822 send callback bound to the Worker's `send_email` binding (Cloudflare default transport). */
   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. 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.
+   */
   jurisdiction?: DurableObjectJurisdiction;
   /** 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 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.
+ */
 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` (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).
+ */
 declare const createMailerFromEnv: (env: MailEnv, options?: FromEnvOptions) => Mailer;
 /** Serializable representation of a `SendOptions` payload — drops the `react` field. */
 interface QueuedSend {
@@ -100,51 +100,79 @@ 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) => {
+ *     const mailer = createMailer({ apiKey: env.RESEND_API_KEY, from: "..." });
+ *     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.
+ */
 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 };

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-CKc6NpZR.mjs";import{createCloudflareTransport as t}from"./packem_shared/createCloudflareTransport-DpfCxn16.mjs";import{default as u}from"./packem_shared/createMailer-CjQmT7Ln.mjs";import{createCaptureSink as f,createMailerFromEnv as l,shouldCaptureMail as m}from"./packem_shared/createCaptureSink-CeV0DSsT.mjs";import{consumeQueuedSend as s,toQueuedPayload as c}from"./packem_shared/consumeQueuedSend-CRfALnCU.mjs";import{default as i}from"./packem_shared/renderEmail-BOUnr6i3.mjs";import{default as M}from"./packem_shared/createResendTransport-DDkOitck.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-soPj2Z0j.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`)},f=(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}},A=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):A(r)},o=r=>r===void 0?void 0:(Array.isArray(r)?r:[r]).map(e=>c(e)),u=r=>{o(r.to),o(r.cc),o(r.bcc),r.from!==void 0&&c(r.from),r.replyTo!==void 0&&c(r.replyTo)};export{f as a,c as b,u as c,o as t};

package/dist/packem_shared/authenticatesFrom-xpKAFMRN.mjs

@@ -0,0 +1 @@
+import p from"postal-mime";import{a as c}from"./address-soPj2Z0j.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};