@sandsoftwaresolutions/mail-kit 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SandSoftwareSolutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# @sandsoftwaresolutions/mail-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/SandSoftwareSolutions/ss-mail-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/SandSoftwareSolutions/ss-mail-kit/actions/workflows/ci.yml)
+
+Send good-looking email from Node without learning email. One small API for the whole job: build the mail, send it over **SMTP** (Zoho, Gmail, your own server) or **Resend**, retry temporary failures without ever sending twice, and test it without sending anything. No dependencies.
+
+```js
+import { createMailer, smtpTransport, email, block } from "@sandsoftwaresolutions/mail-kit";
+
+const mailer = createMailer({
+  from: "Prijzenwacht <noreply@prijzenwacht.sandsoftwaresolutions.com>",
+  transport: smtpTransport({ host: "smtp.zoho.eu", user: "noreply@…", pass: process.env.SMTP_PASS }),
+});
+
+await mailer.send({
+  to: "klant@example.nl",
+  ...email({
+    subject: "Bevestig je e-mailadres",
+    preheader: "Nog één stap",
+    lang: "nl",
+    brand: { name: "Prijzenwacht", url: "https://prijzenwacht.sandsoftwaresolutions.com", color: "#0f766e" },
+    blocks: [
+      block.heading("Welkom!"),
+      "Bevestig je e-mailadres om te beginnen. [Hulp nodig?](https://example.nl/hulp)",
+      block.button("Bevestig mijn e-mailadres", verifyUrl),
+      block.note("Heb jij dit niet aangevraagd? Dan kun je deze mail negeren."),
+    ],
+    footer: ["Prijzenwacht · KvK 12345678"],
+  }),
+});
+```
+
+## Install
+
+```bash
+npm install @sandsoftwaresolutions/mail-kit
+```
+
+Node 20 or newer. Works with `import` and `require()`, with TypeScript types for both.
+
+## What you get
+
+**Templates that work.** `email()` makes table-based HTML with inline styles (Outlook, Gmail and Apple Mail), a phone layout, a dark-mode variant, a hidden preheader, and a **hand-written plain-text version from the same blocks** (not stripped HTML). Blocks: `heading`, paragraph (a plain string), `button`, `code` (verification codes), `list`, `table` (invoice rows), `note`, `divider`, `image`. Text blocks understand `**bold**`, `` `code` `` and `[label](https://url)`. **Text you did not write yourself** (a customer's name) goes through `escapeMarkup(name)` first, otherwise a name like `[click](https://evil)` would become a real link in your mail. Everything is HTML-escaped either way; unsafe links and invalid colors are refused, not passed through.
+
+**Transports.**
+
+| | |
+|---|---|
+| `smtpTransport({ host, port, user, pass })` | Own SMTP client. Port 465 = TLS from the start; other ports **must** upgrade with STARTTLS or the send is refused (no silent downgrade). Certificates are checked. Refuses to send a password unencrypted. PLAIN and LOGIN. |
+| `resendTransport({ apiKey })` | Resend HTTP API. The message id is the idempotency key, so a retry can never deliver twice. |
+| `memoryTransport()` | Keeps mails in memory for tests. `transport.to("a@b.nl").links[0]` is the verification link. |
+| `failoverTransport([a, b])` | Tries the next one only when the first never accepted the mail. |
+
+**The mailer.** `createMailer({ transport, from })` then `mailer.send({ to, subject, html })`:
+
+- Retries temporary failures (`retries: 2`, exponential backoff). Permanent rejections are not retried. If the connection breaks *after* the message was sent, the error is `delivery_unknown` and it is **not** retried, so nobody gets two mails.
+- `redirectAllTo: "dev@…"` for staging: every mail goes there, with the real recipients (masked) in the subject.
+- `allowDomains: ["sand.nl"]` blocks any other recipient before anything is sent.
+- `onSent` / `onError` hooks get masked addresses; a hook that throws cannot break sending.
+- `await mailer.verify()` at startup connects and logs in (SMTP) so wrong settings show up at boot.
+
+**Safe by default.** Header injection (a line break in a subject, name or address) is refused. Addresses are validated (internationalized domains become punycode). `Bcc` never appears in headers. At most 50 recipients unless you raise it. Attachment names cannot contain path parts. Errors never contain your password or API key.
+
+**Smaller things.** `unsubscribe: { url }` adds the one-click `List-Unsubscribe` headers. Attachments and inline images (`cid:`). `Auto-Submitted: auto-generated` on by default so out-of-office replies stay away. `lintEmail(mail)` warns about ALL CAPS subjects, mails over Gmail's 102 KB cut-off, `http://` links, images without alt text. `preview(mail)` returns one HTML page (wide, phone width and text) to open in a browser.
+
+## Zoho
+
+```js
+smtpTransport({ host: "smtp.zoho.eu", port: 465, user: "noreply@yourdomain", pass: "<app password>" })
+```
+
+Use `smtp.zoho.com` for accounts in the US data centre. Create an app-specific password in the Zoho account settings. The `from` address must be the account's address or an alias of it. Zoho signs your mail (DKIM) once the domain's SPF and DKIM records are set; this package does not sign.
+
+## Testing your own app
+
+```js
+const transport = memoryTransport();
+const mailer = createMailer({ transport, from: "app@example.nl" });
+await signUp("klant@example.nl");                       // your code, which calls mailer.send(...)
+const link = transport.to("klant@example.nl").links[0]; // follow it in your test
+```
+
+## Errors
+
+Everything thrown is a `MailError` with `code` and `retryable`. Examples: `invalid_address`, `auth_failed`, `recipient_rejected`, `temporary_failure`, `rate_limited`, `timeout`, `tls_failed`, `tls_unavailable`, `too_large`, `delivery_unknown`, `recipient_not_allowed`.
+
+## Not included
+
+No DKIM signing (your mail provider does it), no connection pool (one connection per mail; fine for transactional volumes), no bounce handling, no marketing-list management, no OAuth2 for SMTP, no `.mjml`. For mass mailing use a dedicated service.
+
+MIT

package/dist/address.cjs

@@ -0,0 +1,132 @@
+"use strict";
+const { domainToASCII } = require("node:url");
+
+const { MailError } = require("./errors.cjs");
+
+const LOCAL = /^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*$/;
+const LABEL = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/;
+const CONTROL = /[\u0000-\u001f\u007f]/;
+const PRINTABLE_ASCII = /^[\x20-\x7e]*$/;
+
+const bad = (message, value) => new MailError(message, { code: "invalid_address", value: typeof value === "string" ? value.slice(0, 200) : value });
+
+/** Checks one bare address and returns it with a lowercased, ASCII (punycode) domain. Throws MailError. */
+function normalizeAddress(address) {
+  if (typeof address !== "string") throw bad("Email address must be a string", address);
+  const value = address.trim();
+  const at = value.lastIndexOf("@");
+  if (at < 1 || value.length > 254) throw bad(`Not a valid email address: ${value.slice(0, 80)}`, value);
+  const local = value.slice(0, at);
+  const domain = domainToASCII(value.slice(at + 1)).toLowerCase();
+  const labels = domain.split(".");
+  if (local.length > 64 || !LOCAL.test(local)) throw bad(`Not a valid email address: ${value.slice(0, 80)}`, value);
+  if (labels.length < 2 || domain.length > 253 || !labels.every((l) => LABEL.test(l)) || /^\d+$/.test(labels[labels.length - 1])) {
+    throw bad(`Not a valid email address: ${value.slice(0, 80)}`, value);
+  }
+  return `${local}@${domain}`;
+}
+
+function isEmail(value) {
+  try {
+    normalizeAddress(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Accepts `"a@b.nl"`, `"Name <a@b.nl>"` or `{ name, address }` and returns `{ name, address }`. */
+function parseAddress(input) {
+  let name = "";
+  let address;
+  if (input && typeof input === "object") {
+    name = input.name ?? "";
+    address = input.address;
+  } else if (typeof input === "string") {
+    const angle = /^([\s\S]*?)<([^<>]*)>\s*$/.exec(input.trim());
+    if (angle) {
+      name = angle[1].trim().replace(/^"([\s\S]*)"$/, (_, inner) => inner.replace(/\\(.)/g, "$1"));
+      address = angle[2];
+    } else address = input;
+  } else throw bad("Email address must be a string or { name, address }", input);
+  if (typeof name !== "string" || CONTROL.test(name)) throw bad("Display name may not contain control characters or line breaks", name);
+  return { name: name.trim(), address: normalizeAddress(address) };
+}
+
+/** Splits `"A <a@x.nl>, b@y.nl"` on commas outside quotes and angle brackets. */
+function splitList(text) {
+  const parts = [];
+  let current = "";
+  let quoted = false;
+  let angle = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "\\" && quoted) {
+      current += ch + (text[++i] ?? "");
+      continue;
+    }
+    if (ch === '"') quoted = !quoted;
+    else if (!quoted && ch === "<") angle = true;
+    else if (!quoted && ch === ">") angle = false;
+    if (ch === "," && !quoted && !angle) {
+      parts.push(current);
+      current = "";
+    } else current += ch;
+  }
+  parts.push(current);
+  return parts.map((p) => p.trim()).filter(Boolean);
+}
+
+/** A string, an object, or an array of those; always returns an array of `{ name, address }` without duplicates. */
+function parseAddressList(input) {
+  if (input === undefined || input === null || input === "") return [];
+  const items = Array.isArray(input) ? input.flatMap((i) => (typeof i === "string" ? splitList(i) : [i])) : typeof input === "string" ? splitList(input) : [input];
+  const seen = new Set();
+  const out = [];
+  for (const item of items) {
+    const parsed = parseAddress(item);
+    const key = parsed.address.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(parsed);
+  }
+  return out;
+}
+
+/** Encodes non-ASCII text for a header (RFC 2047), in pieces that stay under 75 characters. ASCII is returned as is. */
+function encodeWords(text) {
+  if (PRINTABLE_ASCII.test(text)) return text;
+  const words = [];
+  let current = "";
+  let bytes = 0;
+  for (const ch of text) {
+    const size = Buffer.byteLength(ch);
+    if (bytes + size > 45) {
+      words.push(current);
+      current = "";
+      bytes = 0;
+    }
+    current += ch;
+    bytes += size;
+  }
+  if (current) words.push(current);
+  return words.map((w) => `=?UTF-8?B?${Buffer.from(w, "utf8").toString("base64")}?=`).join("\r\n ");
+}
+
+function formatAddress({ name, address }) {
+  if (!name) return address;
+  if (PRINTABLE_ASCII.test(name)) return `"${name.replace(/(["\\])/g, "\\$1")}" <${address}>`;
+  return `${encodeWords(name)} <${address}>`;
+}
+
+function formatAddressList(list) {
+  return list.map(formatAddress).join(",\r\n ");
+}
+
+exports.normalizeAddress = normalizeAddress;
+exports.isEmail = isEmail;
+exports.parseAddress = parseAddress;
+exports.parseAddressList = parseAddressList;
+exports.encodeWords = encodeWords;
+exports.formatAddress = formatAddress;
+exports.formatAddressList = formatAddressList;

package/dist/errors.cjs

@@ -0,0 +1,13 @@
+"use strict";
+/** Every failure of this package is a MailError, so callers can branch on `code` and `retryable`. */
+class MailError extends Error {
+  constructor(message, { code = "mail_error", retryable = false, cause, ...extra } = {}) {
+    super(message, cause ? { cause } : undefined);
+    this.name = "MailError";
+    this.code = code;
+    this.retryable = retryable;
+    Object.assign(this, extra);
+  }
+}
+
+exports.MailError = MailError;

package/dist/index.cjs

@@ -0,0 +1,35 @@
+"use strict";
+const { MailError } = require("./errors.cjs");
+const { encodeWords, formatAddress, isEmail, normalizeAddress, parseAddress, parseAddressList } = require("./address.cjs");
+const { prepareMessage, quotedPrintable } = require("./message.cjs");
+const { escapeHtml, extractLinks, htmlToText, wrapText } = require("./text.cjs");
+const { block, email, escapeMarkup } = require("./template.cjs");
+const { smtpTransport } = require("./smtp.cjs");
+const { failoverTransport, memoryTransport, resendTransport } = require("./transports.cjs");
+const { createMailer } = require("./mailer.cjs");
+const { lintEmail } = require("./lint.cjs");
+const { preview } = require("./preview.cjs");
+
+exports.MailError = MailError;
+exports.encodeWords = encodeWords;
+exports.formatAddress = formatAddress;
+exports.isEmail = isEmail;
+exports.normalizeAddress = normalizeAddress;
+exports.parseAddress = parseAddress;
+exports.parseAddressList = parseAddressList;
+exports.prepareMessage = prepareMessage;
+exports.quotedPrintable = quotedPrintable;
+exports.escapeHtml = escapeHtml;
+exports.extractLinks = extractLinks;
+exports.htmlToText = htmlToText;
+exports.wrapText = wrapText;
+exports.block = block;
+exports.email = email;
+exports.escapeMarkup = escapeMarkup;
+exports.smtpTransport = smtpTransport;
+exports.failoverTransport = failoverTransport;
+exports.memoryTransport = memoryTransport;
+exports.resendTransport = resendTransport;
+exports.createMailer = createMailer;
+exports.lintEmail = lintEmail;
+exports.preview = preview;

package/dist/index.d.cts

@@ -0,0 +1,166 @@
+export interface Address { name: string; address: string }
+export type AddressInput = string | { name?: string; address: string };
+export type AddressesInput = AddressInput | AddressInput[];
+
+export class MailError extends Error {
+  /** invalid_address, invalid_header, invalid_message, invalid_template, invalid_config, no_recipients, auth_failed,
+   *  recipient_rejected, rejected, temporary_failure, rate_limited, timeout, connection_failed, tls_failed,
+   *  tls_unavailable, too_large, delivery_unknown, recipient_not_allowed, send_failed, ... */
+  code: string;
+  /** True when sending the same message again is safe and may work. */
+  retryable: boolean;
+  /** Set by the mailer: how many tries were made. */
+  attempts?: number;
+  responseCode?: number;
+  response?: string;
+}
+
+export interface Attachment {
+  filename: string;
+  content: Buffer | Uint8Array | string;
+  /** "base64" when `content` is a base64 string. */
+  encoding?: "base64" | "utf8";
+  contentType?: string;
+  /** Makes it an inline image: use `<img src="cid:logo">` with `cid: "logo"`. */
+  cid?: string;
+}
+
+export interface MessageInput {
+  from?: AddressInput;
+  to?: AddressesInput;
+  cc?: AddressesInput;
+  bcc?: AddressesInput;
+  replyTo?: AddressesInput;
+  subject: string;
+  html?: string;
+  /** Made from the html when left out. */
+  text?: string;
+  headers?: Record<string, string>;
+  attachments?: Attachment[];
+  /** Adds List-Unsubscribe and the one-click header. */
+  unsubscribe?: { url?: string; mailto?: string };
+  /** Default true: adds `Auto-Submitted: auto-generated`, which stops out-of-office replies. */
+  autoSubmitted?: boolean;
+  messageId?: string;
+  date?: Date;
+  /** Bounce address, if different from `from`. */
+  envelopeFrom?: string;
+  /** Default 50. */
+  maxRecipients?: number;
+}
+
+export interface PreparedMessage {
+  from: Address; to: Address[]; cc: Address[]; bcc: Address[]; replyTo: Address[];
+  subject: string; html?: string; text: string;
+  headers: Record<string, string>;
+  attachments: { filename: string; content: Buffer; contentType: string; cid?: string }[];
+  messageId: string; date: Date;
+  envelope: { from: string; to: string[] };
+  /** The complete RFC 5322 message, all CRLF, 7-bit. */
+  readonly raw: Buffer;
+}
+
+export interface SendResult {
+  id: string; messageId: string; accepted: string[]; rejected: string[]; response?: string;
+  attempts?: number; transport?: string;
+}
+
+export interface Transport {
+  name: string;
+  send(message: PreparedMessage | MessageInput): Promise<SendResult>;
+  verify?(): Promise<unknown>;
+}
+
+export function isEmail(value: unknown): boolean;
+export function normalizeAddress(address: string): string;
+export function parseAddress(input: AddressInput): Address;
+export function parseAddressList(input?: AddressesInput): Address[];
+export function encodeWords(text: string): string;
+export function formatAddress(address: Address): string;
+export function prepareMessage(input: MessageInput, defaults?: Partial<MessageInput>): PreparedMessage;
+export function quotedPrintable(text: string): string;
+
+export function escapeHtml(value: unknown): string;
+export function htmlToText(html: string): string;
+export function wrapText(text: string, width?: number): string;
+export function extractLinks(content: string): string[];
+
+export type Block =
+  | { type: "heading"; text: string; level: 1 | 2 }
+  | { type: "paragraph" | "note"; text: string }
+  | { type: "button"; label: string; url: string }
+  | { type: "code"; value: string; caption?: string }
+  | { type: "list"; items: string[]; ordered: boolean }
+  | { type: "table"; rows: [string, string][]; total: boolean }
+  | { type: "divider" }
+  | { type: "image"; src: string; alt: string; width?: number };
+
+export const block: {
+  heading(text: string, level?: 1 | 2): Block;
+  paragraph(text: string): Block;
+  button(label: string, url: string): Block;
+  code(value: string, caption?: string): Block;
+  list(items: string[], options?: { ordered?: boolean }): Block;
+  table(rows: [string, string][], options?: { total?: boolean }): Block;
+  note(text: string): Block;
+  divider(): Block;
+  image(src: string, alt: string, options?: { width?: number }): Block;
+};
+
+export interface EmailOptions {
+  subject: string;
+  /** Preview text shown next to the subject in the inbox. */
+  preheader?: string;
+  /** Strings are paragraphs. Text blocks understand **bold**, `code` and [label](https://url). */
+  blocks: (Block | string)[];
+  footer?: string | string[];
+  lang?: string;
+  brand?: { name?: string; url?: string; logoUrl?: string; color?: string; buttonTextColor?: string; textColor?: string; background?: string; font?: string };
+}
+export interface Mail { subject: string; html: string; text: string }
+export function email(options: EmailOptions): Mail;
+/** Escape a name or any outside text before putting it in a block, so it cannot turn into a link, bold text or code. */
+export function escapeMarkup(value: unknown): string;
+export function preview(mail: Mail): string;
+export function lintEmail(mail: MessageInput | PreparedMessage): { level: "warning" | "info"; message: string }[];
+
+export interface SmtpOptions {
+  host: string;
+  /** Default 587 (465 when security is "tls"). */
+  port?: number;
+  /** "tls" = encrypted from the start (port 465), "starttls" = must upgrade or fail (default), "none" = no encryption. */
+  security?: "tls" | "starttls" | "none";
+  user?: string;
+  pass?: string;
+  allowInsecureAuth?: boolean;
+  timeoutMs?: number;
+  clientName?: string;
+  tls?: { rejectUnauthorized?: boolean; ca?: string | Buffer | (string | Buffer)[]; servername?: string; minVersion?: string };
+}
+export function smtpTransport(options: SmtpOptions): Transport & { verify(): Promise<true> };
+export function resendTransport(options: { apiKey: string; apiUrl?: string; fetch?: typeof fetch; timeoutMs?: number }): Transport;
+export function memoryTransport(): Transport & {
+  sent: (PreparedMessage & { links: string[] })[];
+  last(): (PreparedMessage & { links: string[] }) | undefined;
+  to(address: string): (PreparedMessage & { links: string[] }) | undefined;
+  clear(): void;
+};
+export function failoverTransport(transports: Transport[]): Transport & { verify(): Promise<boolean> };
+
+export interface MailerOptions extends Partial<MessageInput> {
+  transport: Transport;
+  /** Extra tries for temporary failures. Default 2. */
+  retries?: number;
+  retryDelayMs?: number;
+  /** Every mail goes here instead (staging); the real recipients are noted in the subject. */
+  redirectAllTo?: AddressesInput;
+  /** Only these recipient domains may get mail. */
+  allowDomains?: string[];
+  onSent?: (info: SendResult & { to: string[]; subject: string }) => void;
+  onError?: (error: MailError, info: { to: string[]; subject: string }) => void;
+}
+export function createMailer(options: MailerOptions): {
+  send(message: MessageInput): Promise<SendResult>;
+  verify(): Promise<unknown>;
+  transport: Transport;
+};

package/dist/lint.cjs

@@ -0,0 +1,34 @@
+"use strict";
+const { prepareMessage } = require("./message.cjs");
+const { extractLinks } = require("./text.cjs");
+
+/**
+ * Looks at a mail the way a spam filter and an inbox would, and returns a list of `{ level, message }` hints.
+ * It is advice, not a guarantee of delivery.
+ */
+function lintEmail(input) {
+  const m = input.raw ? input : prepareMessage({ from: "lint@example.com", to: "lint@example.com", ...input });
+  const out = [];
+  const warn = (message) => out.push({ level: "warning", message });
+  const info = (message) => out.push({ level: "info", message });
+  if (m.subject.length > 78) warn(`Subject is ${m.subject.length} characters; inboxes cut it off around 60-78.`);
+  if (m.subject.length > 3 && m.subject === m.subject.toUpperCase() && /[A-Z]/.test(m.subject)) warn("Subject is ALL CAPS, which spam filters dislike.");
+  if (/!{2,}/.test(m.subject)) warn("Subject has repeated exclamation marks.");
+  if (m.html !== undefined) {
+    const size = Buffer.byteLength(m.html);
+    if (size > 100_000) warn(`HTML is ${Math.round(size / 1000)} KB; Gmail cuts messages off at about 102 KB.`);
+    if (/<img\b/i.test(m.html) && !/<img\b[^>]*\balt=/i.test(m.html)) warn("An image has no alt text.");
+    if (/<script\b|\son\w+\s*=|javascript:/i.test(m.html)) warn("HTML contains script or event handlers; mail clients strip them.");
+    if (/<link\b[^>]*stylesheet|@import/i.test(m.html)) warn("External stylesheets are ignored by most mail clients; use inline styles.");
+    const textLength = m.text.replace(/\s+/g, "").length;
+    if (textLength < 40 && /<img\b/i.test(m.html)) warn("Almost only images; add real text, it helps delivery and accessibility.");
+  }
+  const links = [...new Set([...extractLinks(m.html ?? ""), ...extractLinks(m.text)])];
+  if (links.some((l) => l.startsWith("http://"))) warn("Contains an http:// link; use https://.");
+  if (links.length > 10) info(`Contains ${links.length} links; fewer is safer for delivery.`);
+  const hasUnsub = Object.keys(m.headers).some((h) => h.toLowerCase() === "list-unsubscribe");
+  if (!hasUnsub && !/^auto-generated$/i.test(m.headers["Auto-Submitted"] ?? "")) info("No List-Unsubscribe header; add one if this is not a transactional mail.");
+  return out;
+}
+
+exports.lintEmail = lintEmail;

package/dist/mailer.cjs

@@ -0,0 +1,69 @@
+"use strict";
+const { setTimeout: sleep } = require("node:timers/promises");
+
+const { parseAddress, parseAddressList } = require("./address.cjs");
+const { MailError } = require("./errors.cjs");
+const { prepareMessage } = require("./message.cjs");
+
+const mask = (address) => address.replace(/^(.).*(@.*)$/, "$1***$2");
+
+/**
+ * The one object an app uses: `mailer.send({ to, subject, html })` checks the message, sends it, retries
+ * temporary failures with a pause, and can keep staging or test systems from mailing real people.
+ *
+ * @param {object} options
+ * @param {{ send(message): Promise<object> }} options.transport  smtpTransport, resendTransport, memoryTransport, failoverTransport
+ * @param {string|{name,address}} options.from  default sender
+ * @param {string|string[]} [options.redirectAllTo]  every mail goes to these addresses instead (staging); the real recipients are put in the subject
+ * @param {string[]} [options.allowDomains]  only these recipient domains may receive mail; others fail before sending
+ */
+function createMailer(options = {}) {
+  const { transport, retries = 2, retryDelayMs = 500, onSent, onError, redirectAllTo, allowDomains, ...defaults } = options;
+  if (!transport || typeof transport.send !== "function") throw new MailError("createMailer needs a transport", { code: "invalid_config" });
+  const redirect = redirectAllTo ? parseAddressList(redirectAllTo) : null;
+  const allowed = allowDomains ? new Set(allowDomains.map((d) => String(d).toLowerCase())) : null;
+  if (defaults.from !== undefined) parseAddress(defaults.from);
+
+  const guard = (message) => {
+    if (!allowed) return;
+    const blocked = message.envelope.to.filter((a) => !allowed.has(a.split("@")[1]));
+    if (blocked.length) throw new MailError(`Recipient domain not allowed: ${blocked.map(mask).join(", ")}`, { code: "recipient_not_allowed" });
+  };
+
+  async function send(input) {
+    let message = prepareMessage(input, defaults);
+    guard(message);
+    if (redirect) {
+      const original = message.envelope.to.map(mask).join(", ");
+      message = prepareMessage({ ...input, to: redirect, cc: undefined, bcc: undefined, subject: `[to: ${original}] ${message.subject}` }, defaults);
+    }
+    let attempt = 0;
+    for (;;) {
+      attempt++;
+      try {
+        const result = await transport.send(message);
+        const done = { ...result, attempts: attempt, transport: result.transport ?? transport.name };
+        try { onSent?.({ ...done, to: message.envelope.to.map(mask), subject: message.subject }); } catch { /* a logging hook must not break sending */ }
+        return done;
+      } catch (error) {
+        const wrapped = error instanceof MailError ? error : new MailError(`Sending failed: ${error?.message ?? error}`, { code: "send_failed", cause: error });
+        if (wrapped.retryable && attempt <= retries) {
+          await sleep(Math.round(retryDelayMs * 2 ** (attempt - 1) * (0.75 + Math.random() * 0.5)));
+          continue;
+        }
+        wrapped.attempts = attempt;
+        try { onError?.(wrapped, { to: message.envelope.to.map(mask), subject: message.subject }); } catch { /* same */ }
+        throw wrapped;
+      }
+    }
+  }
+
+  return {
+    send,
+    /** Checks the transport settings (connects and logs in for SMTP). Call it once at startup. */
+    verify: async () => (typeof transport.verify === "function" ? transport.verify() : true),
+    transport,
+  };
+}
+
+exports.createMailer = createMailer;