@lunora/mail 0.0.0 → 1.0.0-alpha.1

package/dist/inbound/index.d.mts

@@ -0,0 +1,207 @@
+/** 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 projections of the `SHARD` Durable Object namespace + one shard
+* stub, shared by the inbound dispatcher. Mirrors the shapes the outbound dev
+* capture sink uses (`packages/mail/src/from-env.ts`) so inbound dispatch routes
+* a parsed message into a Lunora function over the exact same admin-RPC-over-shard
+* path — without importing any Cloudflare types into `@lunora/mail`.
+*/
+/** Structural projection of one shard stub — only `fetch` returning something with `.json()`. */
+interface ShardStubLike {
+  fetch: (input: string, init?: {
+    body?: string;
+    headers?: Record<string, string>;
+    method?: string;
+  }) => Promise<{
+    json: () => Promise<unknown>;
+  }>;
+}
+/** Structural projection of the `SHARD` Durable Object namespace. */
+interface ShardNamespaceLike {
+  get: (id: unknown) => ShardStubLike;
+  idFromName: (name: string) => unknown;
+}
+/**
+* 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;
+  /**
+  * 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, type ShardStubLike, createInboundEmailHandler, dispatchToLunoraFunction, parseInboundEmail };

package/dist/inbound/index.d.ts

@@ -0,0 +1,207 @@
+/** 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 projections of the `SHARD` Durable Object namespace + one shard
+* stub, shared by the inbound dispatcher. Mirrors the shapes the outbound dev
+* capture sink uses (`packages/mail/src/from-env.ts`) so inbound dispatch routes
+* a parsed message into a Lunora function over the exact same admin-RPC-over-shard
+* path — without importing any Cloudflare types into `@lunora/mail`.
+*/
+/** Structural projection of one shard stub — only `fetch` returning something with `.json()`. */
+interface ShardStubLike {
+  fetch: (input: string, init?: {
+    body?: string;
+    headers?: Record<string, string>;
+    method?: string;
+  }) => Promise<{
+    json: () => Promise<unknown>;
+  }>;
+}
+/** Structural projection of the `SHARD` Durable Object namespace. */
+interface ShardNamespaceLike {
+  get: (id: unknown) => ShardStubLike;
+  idFromName: (name: string) => unknown;
+}
+/**
+* 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;
+  /**
+  * 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, type ShardStubLike, createInboundEmailHandler, dispatchToLunoraFunction, parseInboundEmail };

package/dist/inbound/index.mjs

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

package/dist/index.d.mts

@@ -0,0 +1,126 @@
+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 { 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;
+  /** 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) => 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,126 @@
+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 { 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;
+  /** 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) => 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 };