@mandujs/core 0.53.3 → 0.54.0

package/src/email/index.ts

@@ -1,282 +1,282 @@
-/**
- * @mandujs/core/email
- *
- * Minimal transactional-email primitive: an `EmailSender` interface and two
- * concrete adapters (`memory`, `resend`). Authentication flows (Phase 5.3 —
- * email verification, password reset) consume this interface; they do not
- * care which provider is wired up.
- *
- * Design constraints:
- *   - **No external deps.** The resend adapter speaks HTTP via `fetch`.
- *   - **Send-only.** No MIME parsing inbound, no attachments (deferred to v2),
- *     no templating — callers build their own HTML.
- *   - **No queue / retry.** The caller (or a job runner) owns retries. This
- *     module is a transport primitive, not a mail pipeline.
- *   - **SMTP is stubbed.** See {@link ./smtp.ts} for the planned design.
- *
- * @example
- * ```ts
- * import { createResendSender } from "@mandujs/core/email";
- *
- * const mail = createResendSender({ apiKey: process.env.RESEND_API_KEY! });
- * await mail.send({
- *   from: "Mandu <no-reply@mandu.dev>",
- *   to: "user@example.com",
- *   subject: "Verify your email",
- *   html: "<p>Click <a href=\"...\">here</a> to verify.</p>",
- * });
- * ```
- *
- * @example Tests — swap in the memory adapter:
- * ```ts
- * import { createMemoryEmailSender } from "@mandujs/core/email";
- *
- * const mail = createMemoryEmailSender();
- * await handler({ mail });            // your code under test
- * await mail.waitFor(1);              // race-free assertion
- * expect(mail.sent[0].subject).toBe("Verify your email");
- * ```
- *
- * @module email
- */
-
-import { newId } from "../id/index.js";
-
-// ─── Public types ───────────────────────────────────────────────────────────
-
-/** A single outbound message. At least one of `html` / `text` is required. */
-export interface EmailMessage {
-  /**
-   * Sender address. Accepted forms:
-   *   - `"sender@domain.com"`
-   *   - `"Display Name <sender@domain.com>"`
-   */
-  from: string;
-  /** Single address or an array of addresses (≥ 1). */
-  to: string | string[];
-  /** Non-empty subject line. */
-  subject: string;
-  /** HTML body. Required if `text` is absent. */
-  html?: string;
-  /** Plain-text body. Required if `html` is absent. */
-  text?: string;
-  /** CC recipients (optional). */
-  cc?: string | string[];
-  /** BCC recipients (optional). */
-  bcc?: string | string[];
-  /** Reply-To address (optional). Mapped to `reply_to` on provider payloads. */
-  replyTo?: string;
-  /**
-   * Arbitrary provider-specific headers. Keys are lowercased before being
-   * forwarded to the provider. Non-ASCII values may be rejected by the
-   * provider — we do not validate here.
-   */
-  headers?: Record<string, string>;
-}
-
-/** Result of a successful send. */
-export interface EmailSendResult {
-  /** Provider's message id. For the memory adapter, a synthetic UUIDv7. */
-  id: string;
-  /** Unix ms when the send call settled. */
-  sentAt: number;
-}
-
-/** Abstract transport. */
-export interface EmailSender {
-  /**
-   * Sends a single message. Throws:
-   *   - `TypeError` on validation failure (malformed message shape).
-   *   - `Error` with status/context on transport failure (non-2xx, network).
-   */
-  send(message: EmailMessage): Promise<EmailSendResult>;
-}
-
-/** In-process adapter for tests + dev. Single-process only — NOT distributed. */
-export interface MemoryEmailSender extends EmailSender {
-  /** All messages sent since construction. Read-only, order preserved. */
-  readonly sent: ReadonlyArray<EmailMessage & { id: string; sentAt: number }>;
-  /** Empty the spool. Useful between test cases. */
-  clear(): void;
-  /**
-   * Resolves once `sent.length >= n`. Rejects after `timeoutMs`. Useful for
-   * tests that race with a request handler.
-   *
-   * @param n Target count. Default 1.
-   * @param timeoutMs Abort threshold in ms. Default 1000.
-   */
-  waitFor(n?: number, timeoutMs?: number): Promise<void>;
-}
-
-// ─── Validation ─────────────────────────────────────────────────────────────
-
-/**
- * Accepts either a bare address (`"a@b.com"`) or display-name form
- * (`"Name <a@b.com>"`). We deliberately do NOT implement RFC 5322 — that
- * regex is famously 6kB and still imperfect. The provider will reject
- * addresses it doesn't like.
- */
-const BARE_EMAIL_RE = /^[^\s@]+@[^\s@]+$/;
-const DISPLAY_NAME_RE = /^.+\s<[^\s@]+@[^\s@]+>$/;
-
-function isValidFrom(from: string): boolean {
-  if (typeof from !== "string" || from.length === 0) return false;
-  return BARE_EMAIL_RE.test(from) || DISPLAY_NAME_RE.test(from);
-}
-
-function normalizeRecipients(
-  value: string | string[] | undefined,
-): string[] | undefined {
-  if (value === undefined) return undefined;
-  if (typeof value === "string") return value.length > 0 ? [value] : [];
-  return value;
-}
-
-/**
- * Validates `message` shape. Throws `TypeError` on the first problem found.
- *
- * Exported for tests and for callers who want to pre-check a message before
- * enqueueing it.
- *
- * @internal
- */
-export function _validateMessage(message: EmailMessage): void {
-  if (!message || typeof message !== "object") {
-    throw new TypeError("[@mandujs/core/email] send: message must be an object.");
-  }
-
-  if (!isValidFrom(message.from)) {
-    throw new TypeError(
-      `[@mandujs/core/email] send: 'from' must be an email address or "Name <addr>" form (got ${JSON.stringify(
-        message.from,
-      )}).`,
-    );
-  }
-
-  const to = normalizeRecipients(message.to);
-  if (!to || to.length === 0) {
-    throw new TypeError(
-      "[@mandujs/core/email] send: 'to' must be a non-empty string or non-empty array.",
-    );
-  }
-  for (const addr of to) {
-    if (typeof addr !== "string" || addr.length === 0) {
-      throw new TypeError(
-        "[@mandujs/core/email] send: 'to' entries must be non-empty strings.",
-      );
-    }
-  }
-
-  if (typeof message.subject !== "string" || message.subject.length === 0) {
-    throw new TypeError(
-      "[@mandujs/core/email] send: 'subject' must be a non-empty string.",
-    );
-  }
-
-  const hasHtml = typeof message.html === "string" && message.html.length > 0;
-  const hasText = typeof message.text === "string" && message.text.length > 0;
-  if (!hasHtml && !hasText) {
-    throw new TypeError(
-      "[@mandujs/core/email] send: message must include at least one of 'html' or 'text'.",
-    );
-  }
-}
-
-/**
- * Shared coercion used by provider adapters: turn a `EmailMessage` into a
- * `{ to, cc, bcc }` bundle of string arrays for the provider payload. Omits
- * undefined-valued fields entirely so the provider doesn't see `null`s.
- *
- * @internal
- */
-export function _coerceRecipients(message: EmailMessage): {
-  to: string[];
-  cc?: string[];
-  bcc?: string[];
-} {
-  const out: { to: string[]; cc?: string[]; bcc?: string[] } = {
-    to: normalizeRecipients(message.to) ?? [],
-  };
-  const cc = normalizeRecipients(message.cc);
-  if (cc && cc.length > 0) out.cc = cc;
-  const bcc = normalizeRecipients(message.bcc);
-  if (bcc && bcc.length > 0) out.bcc = bcc;
-  return out;
-}
-
-/**
- * Lowercases the keys of a headers map. Keeps duplicate-key semantics to
- * whichever one the caller supplied last — same as the JS object itself.
- *
- * @internal
- */
-export function _lowercaseHeaders(
-  headers: Record<string, string> | undefined,
-): Record<string, string> | undefined {
-  if (!headers) return undefined;
-  const out: Record<string, string> = {};
-  for (const [k, v] of Object.entries(headers)) {
-    out[k.toLowerCase()] = v;
-  }
-  return out;
-}
-
-// ─── Memory adapter ─────────────────────────────────────────────────────────
-
-/**
- * Creates an in-process email sender. Messages never leave the current
- * process — perfect for unit tests and dev environments.
- */
-export function createMemoryEmailSender(): MemoryEmailSender {
-  const spool: Array<EmailMessage & { id: string; sentAt: number }> = [];
-
-  async function send(message: EmailMessage): Promise<EmailSendResult> {
-    _validateMessage(message);
-    const id = newId();
-    const sentAt = Date.now();
-    // Freeze a shallow snapshot so the spool entry doesn't mutate if the
-    // caller reuses the `message` object.
-    spool.push({
-      ...message,
-      id,
-      sentAt,
-    });
-    return { id, sentAt };
-  }
-
-  function clear(): void {
-    spool.length = 0;
-  }
-
-  async function waitFor(n: number = 1, timeoutMs: number = 1000): Promise<void> {
-    if (n <= 0 || spool.length >= n) return;
-    const deadline = Date.now() + timeoutMs;
-    // Poll on a 10ms cadence — simpler than wiring a notifier and plenty
-    // responsive for test assertions.
-    while (spool.length < n) {
-      if (Date.now() >= deadline) {
-        throw new Error(
-          `[@mandujs/core/email] waitFor timed out after ${timeoutMs}ms (got ${spool.length}/${n} messages).`,
-        );
-      }
-      await new Promise<void>((resolve) => setTimeout(resolve, 10));
-    }
-  }
-
-  return {
-    send,
-    clear,
-    waitFor,
-    // Expose the array itself as a readonly view. `ReadonlyArray` is purely
-    // a TS-level guarantee; consumers that mutate via `as unknown as` are
-    // reaching past the type system and get what they deserve.
-    get sent() {
-      return spool as ReadonlyArray<EmailMessage & { id: string; sentAt: number }>;
-    },
-  };
-}
-
-// ─── Re-exports ─────────────────────────────────────────────────────────────
-
-export { createResendSender, type ResendOptions } from "./resend.js";
-export { createSmtpSender, type SmtpOptions } from "./smtp.js";
+/**
+ * @mandujs/core/email
+ *
+ * Minimal transactional-email primitive: an `EmailSender` interface and two
+ * concrete adapters (`memory`, `resend`). Authentication flows (Phase 5.3 —
+ * email verification, password reset) consume this interface; they do not
+ * care which provider is wired up.
+ *
+ * Design constraints:
+ *   - **No external deps.** The resend adapter speaks HTTP via `fetch`.
+ *   - **Send-only.** No MIME parsing inbound, no attachments (deferred to v2),
+ *     no templating — callers build their own HTML.
+ *   - **No queue / retry.** The caller (or a job runner) owns retries. This
+ *     module is a transport primitive, not a mail pipeline.
+ *   - **SMTP is stubbed.** See {@link ./smtp.ts} for the planned design.
+ *
+ * @example
+ * ```ts
+ * import { createResendSender } from "@mandujs/core/email";
+ *
+ * const mail = createResendSender({ apiKey: process.env.RESEND_API_KEY! });
+ * await mail.send({
+ *   from: "Mandu <no-reply@mandu.dev>",
+ *   to: "user@example.com",
+ *   subject: "Verify your email",
+ *   html: "<p>Click <a href=\"...\">here</a> to verify.</p>",
+ * });
+ * ```
+ *
+ * @example Tests — swap in the memory adapter:
+ * ```ts
+ * import { createMemoryEmailSender } from "@mandujs/core/email";
+ *
+ * const mail = createMemoryEmailSender();
+ * await handler({ mail });            // your code under test
+ * await mail.waitFor(1);              // race-free assertion
+ * expect(mail.sent[0].subject).toBe("Verify your email");
+ * ```
+ *
+ * @module email
+ */
+
+import { newId } from "../id/index.js";
+
+// ─── Public types ───────────────────────────────────────────────────────────
+
+/** A single outbound message. At least one of `html` / `text` is required. */
+export interface EmailMessage {
+  /**
+   * Sender address. Accepted forms:
+   *   - `"sender@domain.com"`
+   *   - `"Display Name <sender@domain.com>"`
+   */
+  from: string;
+  /** Single address or an array of addresses (≥ 1). */
+  to: string | string[];
+  /** Non-empty subject line. */
+  subject: string;
+  /** HTML body. Required if `text` is absent. */
+  html?: string;
+  /** Plain-text body. Required if `html` is absent. */
+  text?: string;
+  /** CC recipients (optional). */
+  cc?: string | string[];
+  /** BCC recipients (optional). */
+  bcc?: string | string[];
+  /** Reply-To address (optional). Mapped to `reply_to` on provider payloads. */
+  replyTo?: string;
+  /**
+   * Arbitrary provider-specific headers. Keys are lowercased before being
+   * forwarded to the provider. Non-ASCII values may be rejected by the
+   * provider — we do not validate here.
+   */
+  headers?: Record<string, string>;
+}
+
+/** Result of a successful send. */
+export interface EmailSendResult {
+  /** Provider's message id. For the memory adapter, a synthetic UUIDv7. */
+  id: string;
+  /** Unix ms when the send call settled. */
+  sentAt: number;
+}
+
+/** Abstract transport. */
+export interface EmailSender {
+  /**
+   * Sends a single message. Throws:
+   *   - `TypeError` on validation failure (malformed message shape).
+   *   - `Error` with status/context on transport failure (non-2xx, network).
+   */
+  send(message: EmailMessage): Promise<EmailSendResult>;
+}
+
+/** In-process adapter for tests + dev. Single-process only — NOT distributed. */
+export interface MemoryEmailSender extends EmailSender {
+  /** All messages sent since construction. Read-only, order preserved. */
+  readonly sent: ReadonlyArray<EmailMessage & { id: string; sentAt: number }>;
+  /** Empty the spool. Useful between test cases. */
+  clear(): void;
+  /**
+   * Resolves once `sent.length >= n`. Rejects after `timeoutMs`. Useful for
+   * tests that race with a request handler.
+   *
+   * @param n Target count. Default 1.
+   * @param timeoutMs Abort threshold in ms. Default 1000.
+   */
+  waitFor(n?: number, timeoutMs?: number): Promise<void>;
+}
+
+// ─── Validation ─────────────────────────────────────────────────────────────
+
+/**
+ * Accepts either a bare address (`"a@b.com"`) or display-name form
+ * (`"Name <a@b.com>"`). We deliberately do NOT implement RFC 5322 — that
+ * regex is famously 6kB and still imperfect. The provider will reject
+ * addresses it doesn't like.
+ */
+const BARE_EMAIL_RE = /^[^\s@]+@[^\s@]+$/;
+const DISPLAY_NAME_RE = /^.+\s<[^\s@]+@[^\s@]+>$/;
+
+function isValidFrom(from: string): boolean {
+  if (typeof from !== "string" || from.length === 0) return false;
+  return BARE_EMAIL_RE.test(from) || DISPLAY_NAME_RE.test(from);
+}
+
+function normalizeRecipients(
+  value: string | string[] | undefined,
+): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === "string") return value.length > 0 ? [value] : [];
+  return value;
+}
+
+/**
+ * Validates `message` shape. Throws `TypeError` on the first problem found.
+ *
+ * Exported for tests and for callers who want to pre-check a message before
+ * enqueueing it.
+ *
+ * @internal
+ */
+export function _validateMessage(message: EmailMessage): void {
+  if (!message || typeof message !== "object") {
+    throw new TypeError("[@mandujs/core/email] send: message must be an object.");
+  }
+
+  if (!isValidFrom(message.from)) {
+    throw new TypeError(
+      `[@mandujs/core/email] send: 'from' must be an email address or "Name <addr>" form (got ${JSON.stringify(
+        message.from,
+      )}).`,
+    );
+  }
+
+  const to = normalizeRecipients(message.to);
+  if (!to || to.length === 0) {
+    throw new TypeError(
+      "[@mandujs/core/email] send: 'to' must be a non-empty string or non-empty array.",
+    );
+  }
+  for (const addr of to) {
+    if (typeof addr !== "string" || addr.length === 0) {
+      throw new TypeError(
+        "[@mandujs/core/email] send: 'to' entries must be non-empty strings.",
+      );
+    }
+  }
+
+  if (typeof message.subject !== "string" || message.subject.length === 0) {
+    throw new TypeError(
+      "[@mandujs/core/email] send: 'subject' must be a non-empty string.",
+    );
+  }
+
+  const hasHtml = typeof message.html === "string" && message.html.length > 0;
+  const hasText = typeof message.text === "string" && message.text.length > 0;
+  if (!hasHtml && !hasText) {
+    throw new TypeError(
+      "[@mandujs/core/email] send: message must include at least one of 'html' or 'text'.",
+    );
+  }
+}
+
+/**
+ * Shared coercion used by provider adapters: turn a `EmailMessage` into a
+ * `{ to, cc, bcc }` bundle of string arrays for the provider payload. Omits
+ * undefined-valued fields entirely so the provider doesn't see `null`s.
+ *
+ * @internal
+ */
+export function _coerceRecipients(message: EmailMessage): {
+  to: string[];
+  cc?: string[];
+  bcc?: string[];
+} {
+  const out: { to: string[]; cc?: string[]; bcc?: string[] } = {
+    to: normalizeRecipients(message.to) ?? [],
+  };
+  const cc = normalizeRecipients(message.cc);
+  if (cc && cc.length > 0) out.cc = cc;
+  const bcc = normalizeRecipients(message.bcc);
+  if (bcc && bcc.length > 0) out.bcc = bcc;
+  return out;
+}
+
+/**
+ * Lowercases the keys of a headers map. Keeps duplicate-key semantics to
+ * whichever one the caller supplied last — same as the JS object itself.
+ *
+ * @internal
+ */
+export function _lowercaseHeaders(
+  headers: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  if (!headers) return undefined;
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) {
+    out[k.toLowerCase()] = v;
+  }
+  return out;
+}
+
+// ─── Memory adapter ─────────────────────────────────────────────────────────
+
+/**
+ * Creates an in-process email sender. Messages never leave the current
+ * process — perfect for unit tests and dev environments.
+ */
+export function createMemoryEmailSender(): MemoryEmailSender {
+  const spool: Array<EmailMessage & { id: string; sentAt: number }> = [];
+
+  async function send(message: EmailMessage): Promise<EmailSendResult> {
+    _validateMessage(message);
+    const id = newId();
+    const sentAt = Date.now();
+    // Freeze a shallow snapshot so the spool entry doesn't mutate if the
+    // caller reuses the `message` object.
+    spool.push({
+      ...message,
+      id,
+      sentAt,
+    });
+    return { id, sentAt };
+  }
+
+  function clear(): void {
+    spool.length = 0;
+  }
+
+  async function waitFor(n: number = 1, timeoutMs: number = 1000): Promise<void> {
+    if (n <= 0 || spool.length >= n) return;
+    const deadline = Date.now() + timeoutMs;
+    // Poll on a 10ms cadence — simpler than wiring a notifier and plenty
+    // responsive for test assertions.
+    while (spool.length < n) {
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `[@mandujs/core/email] waitFor timed out after ${timeoutMs}ms (got ${spool.length}/${n} messages).`,
+        );
+      }
+      await new Promise<void>((resolve) => setTimeout(resolve, 10));
+    }
+  }
+
+  return {
+    send,
+    clear,
+    waitFor,
+    // Expose the array itself as a readonly view. `ReadonlyArray` is purely
+    // a TS-level guarantee; consumers that mutate via `as unknown as` are
+    // reaching past the type system and get what they deserve.
+    get sent() {
+      return spool as ReadonlyArray<EmailMessage & { id: string; sentAt: number }>;
+    },
+  };
+}
+
+// ─── Re-exports ─────────────────────────────────────────────────────────────
+
+export { createResendSender, type ResendOptions } from "./resend.js";
+export { createSmtpSender, type SmtpOptions } from "./smtp.js";