@ultimat3/mail 1.0.0

package/src/driver.ts

@@ -0,0 +1,174 @@
+// Single responsibility: the transport seam. One `MailDriver` interface, the two local
+// implementations (memory + log), and a module-level ambient driver so `send()` never knows
+// which one is installed. The two production transports live in `driver-smtp.ts` and
+// `driver-resend.ts`; swapping one for the other is an `app.config.ts` line and zero template
+// changes.
+
+import { nanoid, logger as rootLogger } from '@ultimat3/core';
+import { driverUnavailable } from './errors';
+import { mailIdempotencyKey } from './idempotency';
+
+/** The rendered envelope. Everything a transport needs; nothing it does not. */
+export interface MailMessage {
+  readonly mailId: string;
+  readonly to: readonly string[];
+  readonly subject: string;
+  readonly html: string;
+  readonly text: string;
+  readonly locale: string;
+  readonly tz: string;
+  readonly replyTo?: string | undefined;
+  readonly cc?: readonly string[] | undefined;
+  readonly bcc?: readonly string[] | undefined;
+  readonly unsubscribeUrl?: string | undefined;
+  readonly idempotencyKey?: string | undefined;
+}
+
+export interface SendResult {
+  /** Provider message id, or a local id for the memory/log drivers. */
+  readonly id: string;
+  readonly driver: string;
+  readonly accepted: readonly string[];
+  /** True when the message was handed to the queue instead of a transport. */
+  readonly queued: boolean;
+  readonly idempotencyKey: string;
+}
+
+export interface MailDriver {
+  readonly name: string;
+  send(message: MailMessage): Promise<SendResult>;
+}
+
+/**
+ * RFC 8058 one-click unsubscribe. Gmail and Yahoo require it for bulk senders and
+ * reward it for transactional ones, so it is computed here rather than per driver.
+ */
+export function messageHeaders(message: MailMessage): Readonly<Record<string, string>> {
+  const headers: Record<string, string> = { 'Auto-Submitted': 'auto-generated' };
+  if (message.replyTo !== undefined) headers['Reply-To'] = message.replyTo;
+  if (message.unsubscribeUrl !== undefined) {
+    headers['List-Unsubscribe'] = `<${message.unsubscribeUrl}>`;
+    headers['List-Unsubscribe-Post'] = 'List-Unsubscribe=One-Click';
+  }
+  return headers;
+}
+
+/**
+ * Every address the envelope is delivered to. `Bcc` is one of them and never a header —
+ * an SMTP `RCPT TO` carries it, and putting it in the message would leak the blind list.
+ */
+export function envelopeRecipients(message: MailMessage): readonly string[] {
+  return [...message.to, ...(message.cc ?? []), ...(message.bcc ?? [])];
+}
+
+/** The shared `SendResult` shape, so a transport reports acceptance identically to every other. */
+export function resultFor(driver: string, message: MailMessage, id: string): SendResult {
+  return {
+    id,
+    driver,
+    accepted: envelopeRecipients(message),
+    queued: false,
+    // The content-derived key, not the provider's id: it is the same across every attempt of the
+    // same send, which is what a caller deduping its own retries needs it to be.
+    idempotencyKey: mailIdempotencyKey(message),
+  };
+}
+
+export interface SentMail {
+  readonly at: Date;
+  readonly message: MailMessage;
+  readonly result: SendResult;
+}
+
+/**
+ * Dev + test driver. Retains every message it accepts and exposes them, which is what the
+ * `/_x` mail panel reads to show the last mails rendered by the running app — a real inbox
+ * is not part of the local loop.
+ */
+export interface MemoryMailDriver extends MailDriver {
+  readonly name: 'memory';
+  readonly sent: readonly SentMail[];
+  /** Newest first, so the panel and assertions do not index backwards. */
+  outbox(): readonly SentMail[];
+  lastTo(address: string): SentMail | undefined;
+  clear(): void;
+}
+
+export function createMemoryDriver(): MemoryMailDriver {
+  const sent: SentMail[] = [];
+  return {
+    name: 'memory',
+    sent,
+    send(message: MailMessage): Promise<SendResult> {
+      const result = resultFor('memory', message, `mem_${nanoid(12)}`);
+      sent.push({ at: new Date(), message, result });
+      return Promise.resolve(result);
+    },
+    outbox: () => [...sent].reverse(),
+    lastTo: (address) => [...sent].reverse().find((entry) => entry.message.to.includes(address)),
+    clear: () => {
+      sent.length = 0;
+    },
+  };
+}
+
+/**
+ * Whether this driver caught the message instead of sending it. A host asks before reading
+ * `outbox()` — the `/_x` mail panel exists only when nothing was actually delivered, and a real
+ * transport has no record to show. Every member the interface promises is checked, not just the
+ * one a caller happens to reach first: the predicate hands back a `MemoryMailDriver`, so a
+ * look-alike that passed on `name` + `outbox()` alone would make `sent`, `lastTo()` and `clear()`
+ * a compile-time promise the object cannot keep.
+ */
+export function isMemoryDriver(driver: MailDriver): driver is MemoryMailDriver {
+  if (driver.name !== 'memory') return false;
+  const candidate = driver as MemoryMailDriver;
+  return (
+    Array.isArray(candidate.sent) &&
+    typeof candidate.outbox === 'function' &&
+    typeof candidate.lastTo === 'function' &&
+    typeof candidate.clear === 'function'
+  );
+}
+
+/**
+ * Structured log line per message through core's `logger` — the default for a worker that
+ * has no credentials yet. Bodies are never logged; a mail body is user data.
+ */
+export function createLogDriver(logger = rootLogger): MailDriver {
+  return {
+    name: 'log',
+    send(message: MailMessage): Promise<SendResult> {
+      const result = resultFor('log', message, `log_${nanoid(12)}`);
+      logger.info('mail.send', {
+        mailId: message.mailId,
+        to: message.to.length,
+        subject: message.subject,
+        locale: message.locale,
+        idempotencyKey: result.idempotencyKey,
+      });
+      return Promise.resolve(result);
+    },
+  };
+}
+
+let ambient: MailDriver | undefined;
+
+/** Set once at boot from `app.config.ts`. One driver per process, like the job driver. */
+export function setMailDriver(driver: MailDriver): void {
+  ambient = driver;
+}
+
+export function tryMailDriver(): MailDriver | undefined {
+  return ambient;
+}
+
+/** Throws `X_MAIL_DRIVER_UNAVAILABLE` rather than silently dropping mail on the floor. */
+export function mailDriver(): MailDriver {
+  if (ambient === undefined) throw driverUnavailable('setMailDriver() was never called');
+  return ambient;
+}
+
+export function resetMailDriver(): void {
+  ambient = undefined;
+}

package/src/errors.d.ts

@@ -0,0 +1,23 @@
+import { UltimateError } from '@ultimat3/core';
+export declare const MAIL_ERROR_CODES: readonly ['X_MAIL_LOCALE_MISSING', 'X_MAIL_TEMPLATE_UNKNOWN', 'X_MAIL_DUPLICATE', 'X_MAIL_TEXT_MISSING', 'X_MAIL_DRIVER_UNAVAILABLE', 'X_NOT_IMPLEMENTED'];
+export type MailErrorCode = (typeof MAIL_ERROR_CODES)[number];
+export declare const MAIL_ERROR_TITLES: Readonly<Record<MailErrorCode, string>>;
+export interface MailErrorInit {
+    readonly code: MailErrorCode;
+    readonly cause: string;
+    readonly fix: string;
+    readonly meta?: Readonly<Record<string, unknown>> | undefined;
+}
+export declare class MailError extends UltimateError {
+    readonly name = "MailError";
+    constructor(init: MailErrorInit);
+}
+export declare const localeMissing: (mailId: string) => MailError;
+export declare const templateUnknown: (mailId: string, known: readonly string[]) => MailError;
+export declare const layoutUnknown: (mailId: string, layout: string, known: readonly string[]) => MailError;
+export declare const mailDuplicate: (mailId: string) => MailError;
+export declare const textMissing: (mailId: string) => MailError;
+export declare const driverUnavailable: (what: string) => MailError;
+/** The blessed shape for a transport that exists as an interface but has no wire yet. */
+export declare const transportNotImplemented: (driver: string, fix: string) => MailError;
+//# sourceMappingURL=errors.d.ts.map

package/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoC,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEjF,eAAO,MAAM,gBAAgB,YAC3B,uBAAuB,EACvB,yBAAyB,EACzB,kBAAkB,EAClB,qBAAqB,EACrB,2BAA2B,EAC3B,mBAAmB,CACX,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAOrE,CAAC;AAQF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;CAC/D;AAED,qBAAa,SAAU,SAAQ,aAAa;IAC1C,SAAkB,IAAI,eAAe;IAErC,YAAY,IAAI,EAAE,aAAa,EAQ9B;CACF;AAED,eAAO,MAAM,aAAa,WAAY,MAAM,KAAG,SAM3C,CAAC;AAEL,eAAO,MAAM,eAAe,WAAY,MAAM,SAAS,SAAS,MAAM,EAAE,KAAG,SAMvE,CAAC;AAEL,eAAO,MAAM,aAAa,WAChB,MAAM,UACN,MAAM,SACP,SAAS,MAAM,EAAE,KACvB,SAMC,CAAC;AAEL,eAAO,MAAM,aAAa,WAAY,MAAM,KAAG,SAM3C,CAAC;AAEL,eAAO,MAAM,WAAW,WAAY,MAAM,KAAG,SAMzC,CAAC;AAEL,eAAO,MAAM,iBAAiB,SAAU,MAAM,KAAG,SAM7C,CAAC;AAEL,yFAAyF;AACzF,eAAO,MAAM,uBAAuB,WAAY,MAAM,OAAO,MAAM,KAAG,SAMlE,CAAC"}

package/src/errors.js

@@ -0,0 +1,82 @@
+// Single responsibility: the mail package's stable error codes and their `fix:` lines.
+// Mail fails in production, not in tests — a wrong locale, an empty text part or an
+// unconfigured driver must name the exact call site edit that repairs it.
+import { hasErrorCode, registerErrorCodes, UltimateError } from '@ultimat3/core';
+export const MAIL_ERROR_CODES = [
+    'X_MAIL_LOCALE_MISSING',
+    'X_MAIL_TEMPLATE_UNKNOWN',
+    'X_MAIL_DUPLICATE',
+    'X_MAIL_TEXT_MISSING',
+    'X_MAIL_DRIVER_UNAVAILABLE',
+    'X_NOT_IMPLEMENTED',
+];
+export const MAIL_ERROR_TITLES = {
+    X_MAIL_LOCALE_MISSING: 'send() was called without a locale',
+    X_MAIL_TEMPLATE_UNKNOWN: 'no mail is registered under that id',
+    X_MAIL_DUPLICATE: 'two mails claim the same id',
+    X_MAIL_TEXT_MISSING: 'the rendered mail has no plain-text part',
+    X_MAIL_DRIVER_UNAVAILABLE: 'no mail driver is configured',
+    X_NOT_IMPLEMENTED: 'this driver has no transport yet',
+};
+// Titles must be registered for `format()` to render the contract's first line, but
+// `X_NOT_IMPLEMENTED` belongs to core — registering a code twice throws X_ERROR_CODE_DUPLICATE.
+for (const [code, title] of Object.entries(MAIL_ERROR_TITLES)) {
+    if (!hasErrorCode(code))
+        registerErrorCodes({ [code]: { title } });
+}
+export class MailError extends UltimateError {
+    name = 'MailError';
+    constructor(init) {
+        super({
+            code: init.code,
+            cause: init.cause,
+            fix: init.fix,
+            docs: `https://ultimate.dev/errors/${init.code}`,
+            meta: init.meta,
+        });
+    }
+}
+export const localeMissing = (mailId) => new MailError({
+    code: 'X_MAIL_LOCALE_MISSING',
+    cause: `send(${mailId}, data, options) got no locale — the recipient's language is unknown`,
+    fix: `pass it: send(${mailId}, data, { to, locale: ctx.locale })`,
+    meta: { mailId },
+});
+export const templateUnknown = (mailId, known) => new MailError({
+    code: 'X_MAIL_TEMPLATE_UNKNOWN',
+    cause: `no mail with id "${mailId}" is registered (have: ${known.join(', ') || 'none'})`,
+    fix: `x mail list --json   # then export defineMail({ id: '${mailId}', ... }) and import it`,
+    meta: { mailId, known },
+});
+export const layoutUnknown = (mailId, layout, known) => new MailError({
+    code: 'X_MAIL_TEMPLATE_UNKNOWN',
+    cause: `mail "${mailId}" wants layout "${layout}" (registered: ${known.join(', ')})`,
+    fix: `registerLayout('${layout}', myLayout) at boot, or set layout: 'base' on that mail`,
+    meta: { mailId, layout, known },
+});
+export const mailDuplicate = (mailId) => new MailError({
+    code: 'X_MAIL_DUPLICATE',
+    cause: `mail id "${mailId}" is already registered by another defineMail() call`,
+    fix: `x mail list --json   # then rename one of the two defineMail({ id }) declarations`,
+    meta: { mailId },
+});
+export const textMissing = (mailId) => new MailError({
+    code: 'X_MAIL_TEXT_MISSING',
+    cause: `mail "${mailId}" rendered an empty text part (HTML-only mail scores as spam)`,
+    fix: `add a text block to the "${mailId}" template: blocks.paragraph('mail.${mailId}.body')`,
+    meta: { mailId },
+});
+export const driverUnavailable = (what) => new MailError({
+    code: 'X_MAIL_DRIVER_UNAVAILABLE',
+    cause: `${what} — nothing can deliver the message`,
+    fix: 'setMailDriver(createMemoryDriver()) in dev, createSmtpDriver({ url: env.SMTP_URL }) live',
+    meta: { what },
+});
+/** The blessed shape for a transport that exists as an interface but has no wire yet. */
+export const transportNotImplemented = (driver, fix) => new MailError({
+    code: 'X_NOT_IMPLEMENTED',
+    cause: `the ${driver} mail driver has no transport in this build`,
+    fix,
+    meta: { driver },
+});
+//# sourceMappingURL=errors.js.map

package/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"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"}

package/src/errors.ts

@@ -0,0 +1,177 @@
+// Single responsibility: the mail package's stable error codes and their `fix:` lines.
+// Mail fails in production, not in tests — a wrong locale, an empty text part or an
+// unconfigured driver must name the exact call site edit that repairs it.
+
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+export const MAIL_ERROR_CODES = [
+  'X_MAIL_LOCALE_MISSING',
+  'X_MAIL_TEMPLATE_UNKNOWN',
+  'X_MAIL_DUPLICATE',
+  'X_MAIL_TEXT_MISSING',
+  'X_MAIL_DRIVER_UNAVAILABLE',
+  'X_MAIL_HEADER_INVALID',
+  'X_MAIL_SEND_FAILED',
+] as const;
+
+export type MailErrorCode = (typeof MAIL_ERROR_CODES)[number];
+
+export const MAIL_ERROR_TITLES: Readonly<Record<MailErrorCode, string>> = {
+  X_MAIL_LOCALE_MISSING: 'send() was called without a locale',
+  X_MAIL_TEMPLATE_UNKNOWN: 'no mail is registered under that id',
+  X_MAIL_DUPLICATE: 'two mails claim the same id',
+  X_MAIL_TEXT_MISSING: 'the rendered mail has no plain-text part',
+  X_MAIL_DRIVER_UNAVAILABLE: 'no mail driver is configured',
+  X_MAIL_HEADER_INVALID: 'a header value carries a line break',
+  X_MAIL_SEND_FAILED: 'the mail transport refused the message',
+};
+
+// Titles must be registered for `format()` to render the contract's first line. Every code above is
+// owned here and none is borrowed, so the call is unconditional: a second package claiming one has
+// to fail as X_ERROR_CODE_DUPLICATE, not quietly keep whichever title was registered first.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(MAIL_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+export interface MailErrorInit {
+  readonly code: MailErrorCode;
+  readonly cause: string;
+  readonly fix: string;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+}
+
+export class MailError extends UltimateError {
+  override readonly name = 'MailError';
+
+  constructor(init: MailErrorInit) {
+    super({
+      code: init.code,
+      cause: init.cause,
+      fix: init.fix,
+      docs: `https://ultimate.dev/errors/${init.code}`,
+      meta: init.meta,
+    });
+  }
+}
+
+export const localeMissing = (mailId: string): MailError =>
+  new MailError({
+    code: 'X_MAIL_LOCALE_MISSING',
+    cause: `send(${mailId}, data, options) got no locale — the recipient's language is unknown`,
+    fix: `pass it: send(${mailId}, data, { to, locale: ctx.locale })`,
+    meta: { mailId },
+  });
+
+export const templateUnknown = (mailId: string, known: readonly string[]): MailError =>
+  new MailError({
+    code: 'X_MAIL_TEMPLATE_UNKNOWN',
+    cause: `no mail with id "${mailId}" is registered (have: ${known.join(', ') || 'none'})`,
+    fix: `x mail list --json   # then export defineMail({ id: '${mailId}', ... }) and import it`,
+    meta: { mailId, known },
+  });
+
+export const layoutUnknown = (
+  mailId: string,
+  layout: string,
+  known: readonly string[],
+): MailError =>
+  new MailError({
+    code: 'X_MAIL_TEMPLATE_UNKNOWN',
+    cause: `mail "${mailId}" wants layout "${layout}" (registered: ${known.join(', ')})`,
+    fix: `registerLayout('${layout}', myLayout) at boot, or set layout: 'base' on that mail`,
+    meta: { mailId, layout, known },
+  });
+
+export const mailDuplicate = (mailId: string): MailError =>
+  new MailError({
+    code: 'X_MAIL_DUPLICATE',
+    cause: `mail id "${mailId}" is already registered by another defineMail() call`,
+    fix: `x mail list --json   # then rename one of the two defineMail({ id }) declarations`,
+    meta: { mailId },
+  });
+
+export const textMissing = (mailId: string): MailError =>
+  new MailError({
+    code: 'X_MAIL_TEXT_MISSING',
+    cause: `mail "${mailId}" rendered an empty text part (HTML-only mail scores as spam)`,
+    fix: `add a text block to the "${mailId}" template: blocks.paragraph('mail.${mailId}.body')`,
+    meta: { mailId },
+  });
+
+export const driverUnavailable = (what: string): MailError =>
+  new MailError({
+    code: 'X_MAIL_DRIVER_UNAVAILABLE',
+    cause: `${what} — nothing can deliver the message`,
+    fix: 'setMailDriver(createMemoryDriver()) in dev, createSmtpDriver({ url: env.SMTP_URL }) live',
+    meta: { what },
+  });
+
+/**
+ * A CR or LF inside a header value ends the header early and lets whatever follows become new
+ * headers — the recipient list, a forged `From`. Interpolated data reaches `Subject`, so this is
+ * refused rather than stripped: silently rewriting a subject is its own surprise.
+ */
+export const headerInvalid = (name: string, mailId: string): MailError =>
+  new MailError({
+    code: 'X_MAIL_HEADER_INVALID',
+    cause: `the "${name}" header of mail "${mailId}" contains a CR or LF, which would inject headers`,
+    fix:
+      `strip line breaks from the value before it reaches the header: ` +
+      `t('mail.${mailId}.subject', { ...data, x: String(x).replace(/[\\r\\n]+/g, ' ') })`,
+    meta: { header: name, mailId },
+  });
+
+/**
+ * Every step a send can die at. A closed union rather than a `string`: the stage is keyed on by
+ * the transports' `fix` tables and asserted on in tests, so a typo has to be a compile error
+ * instead of an unmapped fix line nobody notices until it reaches an operator.
+ */
+export type SendStage =
+  // The SMTP conversation, in the order it happens. `tls` is the implicit handshake `smtps://`
+  // opens with, before any SMTP byte; `starttls` is the in-band upgrade of a plaintext connection.
+  | 'connect'
+  | 'tls'
+  | 'greeting'
+  | 'ehlo'
+  | 'starttls'
+  | 'auth'
+  | 'from'
+  | 'recipient'
+  | 'data'
+  | 'quit'
+  // Reply framing, which can break at any of the steps above: bytes that never complete a reply.
+  | 'reply'
+  // The HTTPS transports: one request, so one stage.
+  | 'request';
+
+/**
+ * What a transport reports when the remote end did not take the message. `stage` names the
+ * exact step of the conversation, and `status` is the provider's own number — an SMTP reply
+ * code or an HTTP status — because "mail failed" without either is not a diagnosis.
+ */
+export interface SendFailure {
+  readonly driver: 'smtp' | 'resend';
+  readonly stage: SendStage;
+  readonly detail: string;
+  /** SMTP reply code (4xx/5xx) or HTTP status. Absent when the socket never answered. */
+  readonly status?: number | undefined;
+  /** True for a 4xx greylist/throttle: the job's next attempt can succeed unchanged. */
+  readonly retryable: boolean;
+  readonly fix: string;
+}
+
+export const sendFailed = (failure: SendFailure): MailError =>
+  new MailError({
+    code: 'X_MAIL_SEND_FAILED',
+    cause:
+      `${failure.driver} refused the message at ${failure.stage}` +
+      `${failure.status === undefined ? '' : ` (${failure.status})`}: ${failure.detail} — ` +
+      `${failure.retryable ? 'transient, the job will retry' : 'permanent, retrying cannot help'}`,
+    fix: failure.fix,
+    meta: {
+      driver: failure.driver,
+      stage: failure.stage,
+      retryable: failure.retryable,
+      ...(failure.status === undefined ? {} : { status: failure.status }),
+    },
+  });

package/src/html.d.ts

@@ -0,0 +1,10 @@
+/** Escape text content AND attribute values — the same set covers both in mail. */
+export declare function escapeHtml(value: string): string;
+/**
+ * `javascript:` and `data:` hrefs are stripped rather than escaped: some clients still
+ * follow them, and a link the recipient cannot trust is worse than a dead one.
+ */
+export declare function safeUrl(value: string): string;
+/** `style="a:b;c:d"` from declarations, so no call site hand-builds a style attribute. */
+export declare function styleAttr(declarations: readonly string[]): string;
+//# sourceMappingURL=html.d.ts.map

package/src/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["html.ts"],"names":[],"mappings":"AAYA,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAID;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED,0FAA0F;AAC1F,wBAAgB,SAAS,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEjE"}

package/src/html.js

@@ -0,0 +1,34 @@
+// Single responsibility: turning untrusted values into inert HTML. Mail bodies interpolate
+// user-supplied names, org names and URLs; an unescaped one is a phishing vector that also
+// renders in the recipient's client forever, so escaping lives in exactly one place.
+const ESCAPES = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+/** Escape text content AND attribute values — the same set covers both in mail. */
+export function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => ESCAPES[char] ?? char);
+}
+const SAFE_PROTOCOLS = ['http:', 'https:', 'mailto:'];
+/**
+ * `javascript:` and `data:` hrefs are stripped rather than escaped: some clients still
+ * follow them, and a link the recipient cannot trust is worse than a dead one.
+ */
+export function safeUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return '#';
+    }
+    return SAFE_PROTOCOLS.includes(parsed.protocol) ? parsed.href : '#';
+}
+/** `style="a:b;c:d"` from declarations, so no call site hand-builds a style attribute. */
+export function styleAttr(declarations) {
+    return `style="${escapeHtml(declarations.join(';'))}"`;
+}
+//# sourceMappingURL=html.js.map

package/src/html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.js","sourceRoot":"","sources":["html.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,2FAA2F;AAC3F,qFAAqF;AAErF,MAAM,OAAO,GAAqC;IAChD,GAAG,EAAE,OAAO;IACZ,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,QAAQ;IACb,GAAG,EAAE,OAAO;CACb,CAAC;AAEF,mFAAmF;AACnF,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,cAAc,GAAsB,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;AAEzE;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;AACtE,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,SAAS,CAAC,YAA+B;IACvD,OAAO,UAAU,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;AACzD,CAAC"}

package/src/html.ts

@@ -0,0 +1,37 @@
+// Single responsibility: turning untrusted values into inert HTML. Mail bodies interpolate
+// user-supplied names, org names and URLs; an unescaped one is a phishing vector that also
+// renders in the recipient's client forever, so escaping lives in exactly one place.
+
+const ESCAPES: Readonly<Record<string, string>> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+};
+
+/** Escape text content AND attribute values — the same set covers both in mail. */
+export function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (char) => ESCAPES[char] ?? char);
+}
+
+const SAFE_PROTOCOLS: readonly string[] = ['http:', 'https:', 'mailto:'];
+
+/**
+ * `javascript:` and `data:` hrefs are stripped rather than escaped: some clients still
+ * follow them, and a link the recipient cannot trust is worse than a dead one.
+ */
+export function safeUrl(value: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return '#';
+  }
+  return SAFE_PROTOCOLS.includes(parsed.protocol) ? parsed.href : '#';
+}
+
+/** `style="a:b;c:d"` from declarations, so no call site hand-builds a style attribute. */
+export function styleAttr(declarations: readonly string[]): string {
+  return `style="${escapeHtml(declarations.join(';'))}"`;
+}

package/src/idempotency.ts

@@ -0,0 +1,61 @@
+// Single responsibility: the content-derived key that makes at-least-once delivery safe. It lives
+// apart from `job.ts` because the transports need it too: a job retry after a timeout hands the
+// same envelope to the provider again, and without this key on the wire that is a second email.
+
+import type { MailMessage } from './driver';
+
+/**
+ * `(mailId, recipients, hash(rendered payload))`, or the caller's key when supplied.
+ * Content-derived on purpose: a retry of the same request produces the same key, while an
+ * intentional resend with different content produces a different one.
+ */
+export function mailIdempotencyKey(message: MailMessage): string {
+  const explicit = message.idempotencyKey;
+  if (explicit !== undefined && explicit !== '') return `mail:${explicit}`;
+  const recipients = [...message.to].map((address) => address.toLowerCase()).sort();
+  // Every field that reaches the wire is hashed, `replyTo` included: it travels as `Reply-To` and
+  // as Resend's `reply_to`, so two mails that differ only there are two mails, and a shared key
+  // would have the provider drop the second one as a duplicate.
+  const digest = contentDigest(
+    stableStringify({
+      subject: message.subject,
+      html: message.html,
+      text: message.text,
+      cc: message.cc ?? [],
+      bcc: message.bcc ?? [],
+      locale: message.locale,
+      tz: message.tz,
+      replyTo: message.replyTo ?? '',
+      unsubscribeUrl: message.unsubscribeUrl ?? '',
+    }),
+  );
+  return `mail:${message.mailId}:${recipients.join(',')}:${digest}`;
+}
+
+/** Key order is normalised so two structurally equal payloads hash identically. */
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`);
+    return `{${entries.join(',')}}`;
+  }
+  if (value === undefined) return 'null';
+  return JSON.stringify(value);
+}
+
+/** 128 bits of hex: no collision at any volume a mailer reaches, and short enough for a header. */
+const DIGEST_HEX_CHARS = 32;
+
+/**
+ * SHA-256, truncated. Two properties matter and only a specified algorithm has both. Width: a
+ * 32-bit digest reaches a 1% chance of collision at ~9,300 payloads for one mailId and recipient
+ * set, and a collision here is an email the provider dedupes away — 128 bits does not get there.
+ * Stability: SHA-256's output is fixed by its specification, so a key minted by one Bun version
+ * still matches the one minted by the next — `Bun.hash`'s families promise no such thing.
+ */
+function contentDigest(input: string): string {
+  return new Bun.CryptoHasher('sha256').update(input).digest('hex').slice(0, DIGEST_HEX_CHARS);
+}

package/src/index.d.ts

@@ -0,0 +1,17 @@
+export type { CalloutTone, MailBlock, MailTemplate, TemplateArgs } from './blocks';
+export { blocks } from './blocks';
+export { MAIL_CATALOG, MAIL_CATALOG_SOURCE, registerMailCatalog } from './catalog';
+export type { MailDriver, MailMessage, MemoryMailDriver, ResendDriverOptions, SendResult, SentMail, SmtpDriverOptions, } from './driver';
+export { createLogDriver, createMemoryDriver, createResendDriver, createSmtpDriver, mailDriver, messageHeaders, resetMailDriver, setMailDriver, tryMailDriver, } from './driver';
+export type { MailErrorCode, MailErrorInit } from './errors';
+export { driverUnavailable, layoutUnknown, localeMissing, MAIL_ERROR_CODES, MAIL_ERROR_TITLES, MailError, mailDuplicate, templateUnknown, textMissing, transportNotImplemented, } from './errors';
+export { escapeHtml, safeUrl } from './html';
+export { mailIdempotencyKey, mailMessageSchema, sendMailJob } from './job';
+export type { ColorScheme, DarkRule, LayoutInput, MailLayout, MailToken, UnsubscribeSlot, } from './layout';
+export { BASE_LAYOUT, baseLayout, DARK_RULES, darkModeCss, layoutFor, MAIL_FONT_STACK, MAIL_TOKENS, MAIL_WIDTH_PX, registeredLayouts, registerLayout, token, } from './layout';
+export type { AnyMailDefinition, MailDefinition, MailInit, SendOptions } from './mail';
+export { defineMail, mailFor, registeredMailIds, registeredMails, renderMessage, resetMails, send, sendById, } from './mail';
+export type { RenderableMail, RenderedMail, RenderOptions } from './render';
+export { FOOTER_KEYS, renderMail, textOf, UNSUBSCRIBE_KEY } from './render';
+export { FRAMEWORK_MAILS, type InviteInput, inviteInput, inviteMail, MFA_METHODS, type MfaEnrolledInput, mfaEnrolledInput, mfaEnrolledMail, type ResetPasswordInput, resetPasswordInput, resetPasswordMail, type SecurityAlertInput, securityAlertInput, securityAlertMail, type VerifyEmailInput, verifyEmailInput, verifyEmailMail, type WelcomeInput, welcomeInput, welcomeMail, } from './templates';
+//# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACnF,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACnF,YAAY,EACV,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,mBAAmB,EACnB,UAAU,EACV,QAAQ,EACR,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,aAAa,GACd,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,aAAa,EACb,eAAe,EACf,WAAW,EACX,uBAAuB,GACxB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAE7C,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAC3E,YAAY,EACV,WAAW,EACX,QAAQ,EACR,WAAW,EACX,UAAU,EACV,SAAS,EACT,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,WAAW,EACX,UAAU,EACV,UAAU,EACV,WAAW,EACX,SAAS,EACT,eAAe,EACf,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,KAAK,GACN,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACvF,OAAO,EACL,UAAU,EACV,OAAO,EACP,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,UAAU,EACV,IAAI,EACJ,QAAQ,GACT,MAAM,QAAQ,CAAC;AAChB,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE5E,OAAO,EACL,eAAe,EACf,KAAK,WAAW,EAChB,WAAW,EACX,UAAU,EACV,WAAW,EACX,KAAK,gBAAgB,EACrB,gBAAgB,EAChB,eAAe,EACf,KAAK,kBAAkB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,gBAAgB,EAChB,eAAe,EACf,KAAK,YAAY,EACjB,YAAY,EACZ,WAAW,GACZ,MAAM,aAAa,CAAC"}