@lunora/mail 0.0.0 → 1.0.0-alpha.2

package/dist/inbound/index.d.mts

@@ -0,0 +1,193 @@
+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";
+/** 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. */
+interface InboundAttachment {
+  /** Raw attachment content (base64 string or binary buffer, per `encoding`). */
+  content: ArrayBuffer | string | Uint8Array;
+  /** `Content-Disposition` (`"attachment"`/`"inline"`), or `null` when absent. */
+  disposition: "attachment" | "inline" | null;
+  /** How `content` is encoded, when the parser reported it. */
+  encoding?: "base64" | "utf8";
+  /** Filename, or `null` when the part declared none. */
+  filename: string | null;
+  /** Declared MIME type (e.g. `image/png`). */
+  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").
+*/
+interface InboundAuthentication {
+  /** DKIM verdict (`"pass"`/`"fail"`/…), or `null` when not reported. */
+  dkim: string | null;
+  /** DMARC verdict (`"pass"`/`"fail"`/…), or `null` when not reported. */
+  dmarc: string | null;
+  /** SPF verdict (`"pass"`/`"fail"`/…), or `null` when not reported. */
+  spf: 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`.
+  */
+  authentication: InboundAuthentication;
+  /** Sender mailbox (`from`), CR/LF-checked. Empty string when the message omitted it. SECURITY: spoofable — do not trust for authorization. */
+  from: string;
+  /** Flattened `key → value` of the parsed headers (lowercase keys), each value CR/LF-checked. */
+  headers: Record<string, string>;
+  /** HTML body, when present. */
+  html?: string;
+  /** `In-Reply-To` header (threading), CR/LF-checked. */
+  inReplyTo?: string;
+  /** `Message-ID` of this message, CR/LF-checked. */
+  messageId?: string;
+  /** `References` header (threading), CR/LF-checked. */
+  references?: string;
+  /** Subject line, CR/LF-checked. */
+  subject?: string;
+  /** Plain-text body, when present. */
+  text?: string;
+  /** Recipient mailboxes (`to`), each CR/LF-checked. */
+  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.
+*/
+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`.
+*/
+interface ForwardableEmailMessageLike {
+  /** Forward this message to a verified destination address. */
+  forward: (rcptTo: string, headers?: Headers) => Promise<unknown>;
+  /** Envelope `From`. */
+  readonly from: string;
+  /** Parsed top-level headers. */
+  readonly headers: Headers;
+  /** Stream of the raw RFC 822 message content. */
+  readonly raw: ReadableStream<Uint8Array>;
+  /** Reply to the sender with a new message. */
+  reply: (message: {
+    from: string;
+    raw: string;
+    to: string;
+  }) => Promise<unknown>;
+  /** Reject the message with a permanent SMTP error (Cloudflare bounces/retries). */
+  setReject: (reason: string) => void;
+  /** Envelope `To`. */
+  readonly to: string;
+}
+/** Context threaded to a `dispatch` callback alongside the parsed message. */
+interface InboundDispatchContext<TEnv = Record<string, unknown>> {
+  /** Cloudflare's `ExecutionContext`, forwarded verbatim from the `email()` entry. */
+  ctx: unknown;
+  /** Worker `env` (bindings, vars, secrets) projected as a plain record. */
+  env: TEnv;
+  /** The originating message, for `setReject`/`forward`/`reply`. */
+  message: ForwardableEmailMessageLike;
+}
+/** 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.
+*/
+type InboundVerify<TEnv = Record<string, unknown>> = (email: InboundEmail, context: InboundDispatchContext<TEnv>) => Promise<boolean | void> | boolean | 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`.
+  */
+  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.
+  */
+  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`).
+*/
+declare const createInboundEmailHandler: <TEnv = Record<string, unknown>>(options: InboundEmailHandlerOptions<TEnv>) => InboundEmailHandler<TEnv>;
+/** The `RpcEnvelope` shape the runtime's `/_lunora/rpc` path consumes. */
+interface RpcEnvelope {
+  args: unknown;
+  functionPath: string;
+  shardKey?: string;
+}
+/** 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.
+  */
+  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.
+  */
+  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.
+  */
+  resolveArgs?: (email: InboundEmail, context: InboundDispatchContext<TEnv>) => unknown;
+  /** The `SHARD` Durable Object namespace. */
+  shard: ShardNamespaceLike;
+  /** Shard the function runs on. Defaults to the runtime's default root shard. */
+  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.
+*/
+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 };

package/dist/inbound/index.d.ts

@@ -0,0 +1,193 @@
+import { D as DurableObjectJurisdiction, S as ShardNamespaceLike } from "../packem_shared/shard.d-CL2Lmliv.js";
+export type { a as ShardStubLike } from "../packem_shared/shard.d-CL2Lmliv.js";
+/** 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. */
+interface InboundAttachment {
+  /** Raw attachment content (base64 string or binary buffer, per `encoding`). */
+  content: ArrayBuffer | string | Uint8Array;
+  /** `Content-Disposition` (`"attachment"`/`"inline"`), or `null` when absent. */
+  disposition: "attachment" | "inline" | null;
+  /** How `content` is encoded, when the parser reported it. */
+  encoding?: "base64" | "utf8";
+  /** Filename, or `null` when the part declared none. */
+  filename: string | null;
+  /** Declared MIME type (e.g. `image/png`). */
+  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").
+*/
+interface InboundAuthentication {
+  /** DKIM verdict (`"pass"`/`"fail"`/…), or `null` when not reported. */
+  dkim: string | null;
+  /** DMARC verdict (`"pass"`/`"fail"`/…), or `null` when not reported. */
+  dmarc: string | null;
+  /** SPF verdict (`"pass"`/`"fail"`/…), or `null` when not reported. */
+  spf: 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`.
+  */
+  authentication: InboundAuthentication;
+  /** Sender mailbox (`from`), CR/LF-checked. Empty string when the message omitted it. SECURITY: spoofable — do not trust for authorization. */
+  from: string;
+  /** Flattened `key → value` of the parsed headers (lowercase keys), each value CR/LF-checked. */
+  headers: Record<string, string>;
+  /** HTML body, when present. */
+  html?: string;
+  /** `In-Reply-To` header (threading), CR/LF-checked. */
+  inReplyTo?: string;
+  /** `Message-ID` of this message, CR/LF-checked. */
+  messageId?: string;
+  /** `References` header (threading), CR/LF-checked. */
+  references?: string;
+  /** Subject line, CR/LF-checked. */
+  subject?: string;
+  /** Plain-text body, when present. */
+  text?: string;
+  /** Recipient mailboxes (`to`), each CR/LF-checked. */
+  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.
+*/
+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`.
+*/
+interface ForwardableEmailMessageLike {
+  /** Forward this message to a verified destination address. */
+  forward: (rcptTo: string, headers?: Headers) => Promise<unknown>;
+  /** Envelope `From`. */
+  readonly from: string;
+  /** Parsed top-level headers. */
+  readonly headers: Headers;
+  /** Stream of the raw RFC 822 message content. */
+  readonly raw: ReadableStream<Uint8Array>;
+  /** Reply to the sender with a new message. */
+  reply: (message: {
+    from: string;
+    raw: string;
+    to: string;
+  }) => Promise<unknown>;
+  /** Reject the message with a permanent SMTP error (Cloudflare bounces/retries). */
+  setReject: (reason: string) => void;
+  /** Envelope `To`. */
+  readonly to: string;
+}
+/** Context threaded to a `dispatch` callback alongside the parsed message. */
+interface InboundDispatchContext<TEnv = Record<string, unknown>> {
+  /** Cloudflare's `ExecutionContext`, forwarded verbatim from the `email()` entry. */
+  ctx: unknown;
+  /** Worker `env` (bindings, vars, secrets) projected as a plain record. */
+  env: TEnv;
+  /** The originating message, for `setReject`/`forward`/`reply`. */
+  message: ForwardableEmailMessageLike;
+}
+/** 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.
+*/
+type InboundVerify<TEnv = Record<string, unknown>> = (email: InboundEmail, context: InboundDispatchContext<TEnv>) => Promise<boolean | void> | boolean | 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`.
+  */
+  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.
+  */
+  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`).
+*/
+declare const createInboundEmailHandler: <TEnv = Record<string, unknown>>(options: InboundEmailHandlerOptions<TEnv>) => InboundEmailHandler<TEnv>;
+/** The `RpcEnvelope` shape the runtime's `/_lunora/rpc` path consumes. */
+interface RpcEnvelope {
+  args: unknown;
+  functionPath: string;
+  shardKey?: string;
+}
+/** 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.
+  */
+  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.
+  */
+  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.
+  */
+  resolveArgs?: (email: InboundEmail, context: InboundDispatchContext<TEnv>) => unknown;
+  /** The `SHARD` Durable Object namespace. */
+  shard: ShardNamespaceLike;
+  /** Shard the function runs on. Defaults to the runtime's default root shard. */
+  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.
+*/
+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 };

package/dist/inbound/index.mjs

@@ -0,0 +1,2 @@
+export { createInboundEmailHandler, dispatchToLunoraFunction } from '../packem_shared/createInboundEmailHandler-D0uCOrU-.mjs';
+export { parseInboundEmail } from '../packem_shared/parseInboundEmail-Bw9u_1oc.mjs';

package/dist/index.d.mts

@@ -0,0 +1,133 @@
+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 { 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));
+* }
+* ```
+*/
+type CloudflareSend = (from: string, to: string, raw: string) => Promise<void>;
+interface CloudflareTransportOptions {
+  /** Default sender used when a `SendOptions.from` isn't supplied. */
+  from: string;
+  /** RFC 822 send callback bound to the Worker's `send_email` binding. */
+  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.
+*/
+declare const createCloudflareTransport: (options: CloudflareTransportOptions) => MailTransport;
+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). */
+  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.
+  */
+  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.
+*/
+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.
+*/
+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).
+*/
+declare const createMailerFromEnv: (env: MailEnv, options?: FromEnvOptions) => Mailer;
+/** Serializable representation of a `SendOptions` payload — drops the `react` field. */
+interface QueuedSend {
+  bcc?: string[];
+  cc?: string[];
+  from?: string;
+  headers?: Record<string, string>;
+  html?: 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.
+*/
+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);
+*     }
+*   },
+* };
+* ```
+*/
+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.
+*/
+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`.
+*/
+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

@@ -0,0 +1,133 @@
+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 { 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));
+* }
+* ```
+*/
+type CloudflareSend = (from: string, to: string, raw: string) => Promise<void>;
+interface CloudflareTransportOptions {
+  /** Default sender used when a `SendOptions.from` isn't supplied. */
+  from: string;
+  /** RFC 822 send callback bound to the Worker's `send_email` binding. */
+  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.
+*/
+declare const createCloudflareTransport: (options: CloudflareTransportOptions) => MailTransport;
+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). */
+  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.
+  */
+  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.
+*/
+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.
+*/
+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).
+*/
+declare const createMailerFromEnv: (env: MailEnv, options?: FromEnvOptions) => Mailer;
+/** Serializable representation of a `SendOptions` payload — drops the `react` field. */
+interface QueuedSend {
+  bcc?: string[];
+  cc?: string[];
+  from?: string;
+  headers?: Record<string, string>;
+  html?: 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.
+*/
+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);
+*     }
+*   },
+* };
+* ```
+*/
+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.
+*/
+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`.
+*/
+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

@@ -0,0 +1,7 @@
+export { createCaptureTransport } from './packem_shared/createCaptureTransport-Crz_8822.mjs';
+export { createCloudflareTransport } from './packem_shared/createCloudflareTransport-yHOVEsZv.mjs';
+export { default as createMailer } from './packem_shared/createMailer-oEKPAd4J.mjs';
+export { createCaptureSink, createMailerFromEnv, shouldCaptureMail } from './packem_shared/createCaptureSink-DeihS4LH.mjs';
+export { consumeQueuedSend, toQueuedPayload } from './packem_shared/consumeQueuedSend-BEKOdaxU.mjs';
+export { default as renderEmail } from './packem_shared/renderEmail-hyS1bpVP.mjs';
+export { default as createResendTransport } from './packem_shared/createResendTransport-oNIorpzv.mjs';