@sandsoftwaresolutions/mail-kit 0.0.0-stage → 0.1.1

package/src/smtp.js

@@ -0,0 +1,275 @@
+import { hostname } from "node:os";
+import { connect as netConnect } from "node:net";
+import { connect as tlsConnect } from "node:tls";
+
+import { MailError } from "./errors.js";
+import { prepareMessage } from "./message.js";
+
+const LOOPBACK = /^(localhost|127\.\d+\.\d+\.\d+|::1)$/;
+
+const networkError = (error, stage) => {
+  const code = error?.code;
+  if (code === "ERR_TLS_CERT_ALTNAME_INVALID" || /certificate|self.signed|unable to verify/i.test(error?.message ?? "")) {
+    return new MailError(`The mail server's certificate was refused: ${error.message}`, { code: "tls_failed", cause: error });
+  }
+  if (stage === "sent") {
+    return new MailError("The connection broke after the message was sent; it may or may not have been delivered", { code: "delivery_unknown", cause: error });
+  }
+  return new MailError(`Could not talk to the mail server (${code ?? error?.message ?? "error"})`, { code: "connection_failed", retryable: true, cause: error });
+};
+
+class Connection {
+  constructor(socket, timeoutMs) {
+    this.timeoutMs = timeoutMs;
+    this.stage = "connect";
+    this.bind(socket);
+  }
+
+  bind(socket) {
+    this.socket = socket;
+    this.buffer = "";
+    this.lines = [];
+    this.queue = [];
+    this.waiter = null;
+    this.failure = null;
+    socket.setTimeout(this.timeoutMs);
+    socket.on("data", (chunk) => this.onData(chunk));
+    socket.on("error", (error) => this.fail(networkError(error, this.stage)));
+    socket.on("close", () => this.fail(networkError(Object.assign(new Error("connection closed"), { code: "ECONNRESET" }), this.stage)));
+    socket.on("timeout", () => this.fail(this.stage === "sent"
+      ? new MailError("The mail server did not answer after the message was sent; it may or may not have been delivered", { code: "delivery_unknown" })
+      : new MailError("The mail server did not answer in time", { code: "timeout", retryable: true })));
+  }
+
+  onData(chunk) {
+    this.buffer += chunk.toString("latin1");
+    let index;
+    while ((index = this.buffer.indexOf("\n")) >= 0) {
+      const line = this.buffer.slice(0, index).replace(/\r$/, "");
+      this.buffer = this.buffer.slice(index + 1);
+      this.lines.push(line);
+      const match = /^(\d{3})([ -]?)/.exec(line);
+      if (!match) continue;
+      if (match[2] !== "-") {
+        this.queue.push({ code: Number(match[1]), lines: this.lines.map((l) => l.slice(4)), text: this.lines.map((l) => l.slice(4)).join("\n") });
+        this.lines = [];
+        this.flush();
+      }
+    }
+  }
+
+  flush() {
+    if (this.waiter && this.queue.length) {
+      const { resolve } = this.waiter;
+      this.waiter = null;
+      resolve(this.queue.shift());
+    }
+  }
+
+  fail(error) {
+    if (this.failure) return;
+    this.failure = error;
+    if (this.waiter) {
+      const { reject } = this.waiter;
+      this.waiter = null;
+      reject(error);
+    }
+  }
+
+  reply() {
+    if (this.queue.length) return Promise.resolve(this.queue.shift());
+    if (this.failure) return Promise.reject(this.failure);
+    return new Promise((resolve, reject) => (this.waiter = { resolve, reject }));
+  }
+
+  write(data) {
+    if (this.failure) return;
+    this.socket.write(data, "latin1");
+  }
+
+  async command(line, expect) {
+    this.write(`${line}\r\n`);
+    const reply = await this.reply();
+    if (expect && !expect.includes(reply.code)) throw replyError(reply, line.split(" ")[0]);
+    return reply;
+  }
+
+  destroy() {
+    this.socket.destroy();
+  }
+}
+
+function replyError(reply, command) {
+  const transient = reply.code >= 400 && reply.code < 500;
+  const auth = reply.code === 535 || reply.code === 534 || reply.code === 530 || reply.code === 454 || command === "AUTH";
+  const code = auth ? "auth_failed" : command === "RCPT" ? "recipient_rejected" : command === "MAIL" ? "sender_rejected" : transient ? "temporary_failure" : "rejected";
+  return new MailError(`Mail server answered ${reply.code} to ${command}: ${reply.text.slice(0, 200)}`, {
+    code,
+    retryable: transient && !auth,
+    responseCode: reply.code,
+    response: reply.text.slice(0, 500),
+  });
+}
+
+function parseCapabilities(reply) {
+  const caps = new Map();
+  for (const line of reply.lines.slice(1)) {
+    const [name, ...rest] = line.trim().split(/\s+/);
+    caps.set(name.toUpperCase(), rest.join(" "));
+  }
+  return caps;
+}
+
+function openSocket(o) {
+  return new Promise((resolve, reject) => {
+    const socket =
+      o.security === "tls"
+        ? tlsConnect({ host: o.host, port: o.port, servername: o.tls.servername ?? (LOOPBACK.test(o.host) ? undefined : o.host), ...o.tls })
+        : netConnect({ host: o.host, port: o.port });
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(new MailError(`Could not connect to ${o.host}:${o.port} in time`, { code: "timeout", retryable: true }));
+    }, o.timeoutMs);
+    socket.once(o.security === "tls" ? "secureConnect" : "connect", () => {
+      clearTimeout(timer);
+      socket.removeListener("error", onError);
+      resolve(socket);
+    });
+    const onError = (error) => {
+      clearTimeout(timer);
+      reject(networkError(error, "connect"));
+    };
+    socket.once("error", onError);
+  });
+}
+
+function upgrade(connection, o) {
+  return new Promise((resolve, reject) => {
+    const plain = connection.socket;
+    plain.removeAllListeners();
+    plain.setTimeout(0);
+    plain.on("error", () => {});
+    const secure = tlsConnect({ socket: plain, servername: o.tls.servername ?? (LOOPBACK.test(o.host) ? undefined : o.host), ...o.tls });
+    secure.once("secureConnect", () => resolve(secure));
+    secure.once("error", (error) => reject(networkError(error, "connect")));
+  });
+}
+
+async function openSession(o) {
+  const socket = await openSocket(o);
+  const c = new Connection(socket, o.timeoutMs);
+  try {
+    const hello = await c.reply();
+    if (hello.code !== 220) throw replyError(hello, "CONNECT");
+    let ehlo = await c.command(`EHLO ${o.clientName}`);
+    if (ehlo.code >= 500) ehlo = await c.command(`HELO ${o.clientName}`, [250]);
+    let caps = parseCapabilities(ehlo);
+    let secureNow = o.security === "tls";
+    if (o.security === "starttls") {
+      if (!caps.has("STARTTLS")) throw new MailError("The mail server does not offer STARTTLS, so the connection would not be encrypted. Use security: \"none\" only if you really want that.", { code: "tls_unavailable" });
+      await c.command("STARTTLS", [220]);
+      c.bind(await upgrade(c, o));
+      secureNow = true;
+      ehlo = await c.command(`EHLO ${o.clientName}`, [250]);
+      caps = parseCapabilities(ehlo);
+    }
+    if (o.user !== undefined) {
+      if (!secureNow && !o.allowInsecureAuth) throw new MailError("Refusing to send the password over an unencrypted connection", { code: "tls_unavailable" });
+      await authenticate(c, caps, o);
+    }
+    return { c, caps };
+  } catch (error) {
+    c.destroy();
+    throw error;
+  }
+}
+
+async function authenticate(c, caps, o) {
+  const offered = (caps.get("AUTH") ?? "").toUpperCase().split(/\s+/);
+  const b64 = (s) => Buffer.from(s, "utf8").toString("base64");
+  if (offered.includes("PLAIN")) {
+    await c.command(`AUTH PLAIN ${b64(`\0${o.user}\0${o.pass}`)}`, [235]);
+  } else if (offered.includes("LOGIN")) {
+    await c.command("AUTH LOGIN", [334]);
+    await c.command(b64(o.user), [334]);
+    await c.command(b64(o.pass), [235]);
+  } else {
+    throw new MailError(`The mail server offers no login method this package supports (it offers: ${offered.join(" ") || "none"})`, { code: "auth_failed" });
+  }
+}
+
+const dotStuff = (raw) => {
+  const text = raw.toString("latin1").replace(/(^|\r\n)\./g, "$1..");
+  return text.endsWith("\r\n") ? text : `${text}\r\n`;
+};
+
+/**
+ * Sends through any SMTP server (Zoho, Gmail, your own). Encrypted by default: port 465 uses TLS right away,
+ * other ports must offer STARTTLS or the send is refused. No dependencies.
+ */
+export function smtpTransport(options = {}) {
+  const port = options.port ?? (options.security === "tls" ? 465 : 587);
+  const security = options.security ?? (port === 465 ? "tls" : "starttls");
+  if (!options.host || typeof options.host !== "string") throw new MailError("smtpTransport needs a host", { code: "invalid_config" });
+  if (!["tls", "starttls", "none"].includes(security)) throw new MailError('security must be "tls", "starttls" or "none"', { code: "invalid_config" });
+  if ((options.user === undefined) !== (options.pass === undefined)) throw new MailError("Give both user and pass, or neither", { code: "invalid_config" });
+  if (security === "none" && options.user !== undefined && !options.allowInsecureAuth) {
+    throw new MailError('A login over security: "none" would send the password unencrypted; set allowInsecureAuth: true to allow it', { code: "invalid_config" });
+  }
+  const o = {
+    host: options.host,
+    port,
+    security,
+    user: options.user,
+    pass: options.pass,
+    allowInsecureAuth: options.allowInsecureAuth === true,
+    timeoutMs: options.timeoutMs ?? 20_000,
+    clientName: String(options.clientName ?? (hostname().replace(/[^A-Za-z0-9.-]/g, "") || "localhost")),
+    tls: { ...options.tls },
+  };
+
+  const withSession = async (work) => {
+    const session = await openSession(o);
+    try {
+      return await work(session);
+    } finally {
+      session.c.write("QUIT\r\n");
+      setTimeout(() => session.c.destroy(), 200).unref();
+    }
+  };
+
+  return {
+    name: "smtp",
+    /** Opens a connection, encrypts it and logs in, then closes. Use it at startup to catch wrong settings early. */
+    verify: () => withSession(async () => true),
+    async send(input) {
+      const message = input.raw ? input : prepareMessage(input);
+      const raw = message.raw;
+      return withSession(async ({ c, caps }) => {
+        const limit = Number(caps.get("SIZE"));
+        if (limit > 0 && raw.length > limit) throw new MailError(`The message is ${raw.length} bytes; the server accepts at most ${limit}`, { code: "too_large" });
+        await c.command(`MAIL FROM:<${message.envelope.from}>`, [250]);
+        const accepted = [];
+        const rejected = [];
+        let lastError;
+        for (const to of message.envelope.to) {
+          const reply = await c.command(`RCPT TO:<${to}>`);
+          if (reply.code === 250 || reply.code === 251) accepted.push(to);
+          else {
+            rejected.push(to);
+            lastError = replyError(reply, "RCPT");
+          }
+        }
+        if (!accepted.length) throw lastError;
+        await c.command("DATA", [354]);
+        c.stage = "sent";
+        c.write(`${dotStuff(raw)}.\r\n`);
+        const done = await c.reply();
+        c.stage = "done";
+        if (done.code !== 250) throw replyError(done, "DATA");
+        const queued = /queued as ([\w.@-]+)|\bid[ =:]+([\w.@-]+)/i.exec(done.text);
+        return { id: queued?.[1] ?? queued?.[2] ?? message.messageId, messageId: message.messageId, accepted, rejected, response: done.text.slice(0, 500) };
+      });
+    },
+  };
+}

package/src/template.js

@@ -0,0 +1,201 @@
+import { MailError } from "./errors.js";
+import { escapeHtml, wrapText } from "./text.js";
+
+const COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+const FONT = /^[\w\s,'"-]{1,200}$/;
+const HTTPS_OR_HTTP = /^https?:\/\/[^\s<>"']+$/i;
+const LINKABLE = /^(?:https?:\/\/|mailto:|tel:)[^\s<>"']+$/i;
+
+const fail = (message) => new MailError(message, { code: "invalid_template" });
+const color = (value, fallback, name) => {
+  if (value === undefined) return fallback;
+  if (!COLOR.test(value)) throw fail(`${name} must be a hex color like #2563eb`);
+  return value;
+};
+
+// Inline markup used in every text block: **bold**, `code`, [label](https://url). Everything else is plain text.
+// A backslash makes the next markup character literal; escapeMarkup() does that for text you did not write yourself.
+const INLINE = /\\([\\*`[\]()])|\[([^\]\n]+)\]\(([^)\s]+)\)|\*\*([^*\n]+)\*\*|`([^`\n]+)`/g;
+
+/** Makes a name, address or any other outside text safe to put inside a block: it can no longer become a link or bold text. */
+export const escapeMarkup = (value) => String(value).replace(/([\\*`[\]()])/g, "\\$1");
+
+function inlineHtml(text, theme) {
+  let out = "";
+  let last = 0;
+  for (const m of String(text).matchAll(INLINE)) {
+    out += escapeHtml(text.slice(last, m.index));
+    last = m.index + m[0].length;
+    if (m[1] !== undefined) out += escapeHtml(m[1]);
+    else if (m[2] !== undefined) {
+      out += LINKABLE.test(m[3]) ? `<a href="${escapeHtml(m[3])}" style="color:${theme.accent};text-decoration:underline;">${escapeHtml(m[2])}</a>` : escapeHtml(m[2]);
+    } else if (m[4] !== undefined) out += `<strong>${escapeHtml(m[4])}</strong>`;
+    else out += `<code class="ss-soft" style="font-family:Menlo,Consolas,monospace;font-size:0.95em;background:${theme.soft};padding:1px 5px;border-radius:4px;">${escapeHtml(m[5])}</code>`;
+  }
+  return (out + escapeHtml(text.slice(last))).replace(/\n/g, "<br>");
+}
+
+function inlineText(text) {
+  return String(text).replace(INLINE, (_, escaped, label, url, bold, code) => {
+    if (escaped !== undefined) return escaped;
+    if (label !== undefined) return LINKABLE.test(url) && label !== url ? `${label} (${url})` : label;
+    return bold ?? code;
+  });
+}
+
+/** Building blocks for `email({ blocks })`. A plain string in the list means `paragraph(string)`. */
+export const block = {
+  heading: (text, level = 1) => ({ type: "heading", text: String(text), level: level === 2 ? 2 : 1 }),
+  paragraph: (text) => ({ type: "paragraph", text: String(text) }),
+  /** A call-to-action button. The text version prints the label and the full URL on separate lines. */
+  button: (label, url) => {
+    if (!HTTPS_OR_HTTP.test(url ?? "")) throw fail(`Button URL must be an http(s) URL: ${String(url).slice(0, 80)}`);
+    return { type: "button", label: String(label), url };
+  },
+  /** A big monospaced value, like a verification code. */
+  code: (value, caption) => ({ type: "code", value: String(value), caption }),
+  list: (items, { ordered = false } = {}) => ({ type: "list", items: items.map(String), ordered }),
+  /** Label/value rows, for an invoice or an order summary: `table([["Plan", "Klein"], ["Total", "€ 9,00"]])`. */
+  table: (rows, { total = false } = {}) => ({ type: "table", rows: rows.map(([a, b]) => [String(a), String(b)]), total }),
+  /** A highlighted note (warnings, "you did not request this"). */
+  note: (text) => ({ type: "note", text: String(text) }),
+  divider: () => ({ type: "divider" }),
+  /** An image. Use `cid:name` as src for an inline attachment. Alt text is required. */
+  image: (src, alt, { width } = {}) => {
+    if (!/^(https:\/\/[^\s<>"']+|cid:[\w.@+-]+)$/.test(src ?? "")) throw fail("Image src must be an https URL or cid:name");
+    if (!alt) throw fail("Images need alt text, many mail clients block images");
+    return { type: "image", src, alt: String(alt), width };
+  },
+};
+
+function renderBlockHtml(b, theme) {
+  const text = `color:${theme.text};font-family:${theme.font};`;
+  switch (b.type) {
+    case "heading":
+      return `<h${b.level} style="margin:0 0 16px;${text}font-size:${b.level === 1 ? 24 : 18}px;line-height:1.3;font-weight:700;">${inlineHtml(b.text, theme)}</h${b.level}>`;
+    case "paragraph":
+      return `<p style="margin:0 0 16px;${text}font-size:16px;line-height:1.55;">${inlineHtml(b.text, theme)}</p>`;
+    case "button":
+      return `<table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin:8px 0 24px;"><tr><td align="center" bgcolor="${theme.accent}" style="border-radius:8px;"><a class="ss-btn" href="${escapeHtml(b.url)}" style="display:inline-block;padding:13px 26px;font-family:${theme.font};font-size:16px;font-weight:700;line-height:1.2;color:${theme.accentText};text-decoration:none;border-radius:8px;">${escapeHtml(b.label)}</a></td></tr></table>`;
+    case "code":
+      return `<table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin:8px 0 24px;"><tr><td class="ss-soft" style="background:${theme.soft};border-radius:8px;padding:14px 22px;font-family:Menlo,Consolas,monospace;font-size:28px;letter-spacing:6px;font-weight:700;color:${theme.text};">${escapeHtml(b.value)}</td></tr></table>${b.caption ? `<p style="margin:-12px 0 16px;${text}font-size:14px;color:${theme.muted};">${inlineHtml(b.caption, theme)}</p>` : ""}`;
+    case "list": {
+      const tag = b.ordered ? "ol" : "ul";
+      return `<${tag} style="margin:0 0 16px;padding-left:22px;${text}font-size:16px;line-height:1.55;">${b.items.map((i) => `<li style="margin:0 0 6px;">${inlineHtml(i, theme)}</li>`).join("")}</${tag}>`;
+    }
+    case "table":
+      return `<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="margin:0 0 20px;border-collapse:collapse;">${b.rows
+        .map(([k, v], i) => {
+          const last = b.total && i === b.rows.length - 1;
+          const cell = `padding:9px 0;border-bottom:1px solid ${theme.line};${text}font-size:15px;${last ? "font-weight:700;" : ""}`;
+          return `<tr><td style="${cell}">${inlineHtml(k, theme)}</td><td align="right" style="${cell}">${inlineHtml(v, theme)}</td></tr>`;
+        })
+        .join("")}</table>`;
+    case "note":
+      return `<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="margin:0 0 20px;"><tr><td class="ss-soft" style="background:${theme.soft};border-left:4px solid ${theme.accent};border-radius:4px;padding:12px 16px;${text}font-size:14px;line-height:1.5;">${inlineHtml(b.text, theme)}</td></tr></table>`;
+    case "divider":
+      return `<hr style="border:0;border-top:1px solid ${theme.line};margin:24px 0;">`;
+    case "image":
+      return `<img src="${escapeHtml(b.src)}" alt="${escapeHtml(b.alt)}"${b.width ? ` width="${Number(b.width) | 0}"` : ""} style="display:block;max-width:100%;height:auto;border:0;margin:0 0 16px;">`;
+    default:
+      throw fail(`Unknown block type: ${b.type}`);
+  }
+}
+
+function renderBlockText(b) {
+  switch (b.type) {
+    case "heading":
+      return b.level === 1 ? `${inlineText(b.text).toUpperCase()}` : inlineText(b.text);
+    case "paragraph":
+    case "note":
+      return wrapText(inlineText(b.text));
+    case "button":
+      return `${b.label}:\n${b.url}`;
+    case "code":
+      return `${b.value}${b.caption ? `\n${inlineText(b.caption)}` : ""}`;
+    case "list":
+      return b.items.map((i, n) => wrapText(`${b.ordered ? `${n + 1}.` : "-"} ${inlineText(i)}`)).join("\n");
+    case "table": {
+      const width = Math.max(...b.rows.map(([k]) => inlineText(k).length));
+      return b.rows.map(([k, v]) => `${inlineText(k).padEnd(width)}  ${inlineText(v)}`).join("\n");
+    }
+    case "divider":
+      return "----";
+    case "image":
+      return `[${b.alt}]`;
+    default:
+      throw fail(`Unknown block type: ${b.type}`);
+  }
+}
+
+/**
+ * Makes a finished mail: `{ subject, html, text }`. The HTML is table-based with inline styles (works in Outlook, Gmail
+ * and Apple Mail, with a dark-mode variant), the text version is written from the same blocks, and all text is escaped.
+ */
+export function email(options = {}) {
+  const { subject, preheader = "", blocks = [], footer = [], lang = "en", brand = {} } = options;
+  if (typeof subject !== "string" || !subject.trim()) throw fail("email needs a subject");
+  if (!Array.isArray(blocks) || !blocks.length) throw fail("email needs at least one block");
+  if (!/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(lang)) throw fail("lang must be a language tag like nl or en-GB");
+  const font = brand.font ?? "-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif";
+  if (!FONT.test(font)) throw fail("brand.font may only contain letters, digits, spaces, commas, quotes and dashes");
+  const accent = color(brand.color, "#2563eb", "brand.color");
+  const theme = {
+    font,
+    accent,
+    accentText: color(brand.buttonTextColor, "#ffffff", "brand.buttonTextColor"),
+    text: color(brand.textColor, "#1f2933", "brand.textColor"),
+    muted: "#6b7785",
+    soft: "#f1f4f8",
+    line: "#e1e6ec",
+    page: color(brand.background, "#f4f6f9", "brand.background"),
+    card: "#ffffff",
+  };
+  if (brand.logoUrl !== undefined && !/^https:\/\/[^\s<>"']+$/.test(brand.logoUrl) && !/^cid:[\w.@+-]+$/.test(brand.logoUrl)) throw fail("brand.logoUrl must be an https URL or cid:name");
+  const items = blocks.map((b) => (typeof b === "string" ? block.paragraph(b) : b));
+  const footerLines = (Array.isArray(footer) ? footer : [footer]).map(String);
+
+  const header = brand.logoUrl
+    ? `<img src="${escapeHtml(brand.logoUrl)}" alt="${escapeHtml(brand.name ?? "")}" height="32" style="display:block;border:0;height:32px;width:auto;">`
+    : brand.name
+      ? `<span style="font-family:${font};font-size:20px;font-weight:700;color:${theme.text};">${escapeHtml(brand.name)}</span>`
+      : "";
+  const headerHtml = header && brand.url && HTTPS_OR_HTTP.test(brand.url) ? `<a href="${escapeHtml(brand.url)}" style="text-decoration:none;">${header}</a>` : header;
+
+  const hiddenPreheader = preheader
+    ? `<div style="display:none;font-size:1px;line-height:1px;max-height:0;max-width:0;opacity:0;overflow:hidden;mso-hide:all;">${escapeHtml(preheader)}${"&#847;&zwnj;&nbsp;".repeat(40)}</div>`
+    : "";
+
+  const html = `<!doctype html>
+<html lang="${lang}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="color-scheme" content="light dark">
+<meta name="supported-color-schemes" content="light dark">
+<meta name="x-apple-disable-message-reformatting">
+<title>${escapeHtml(subject)}</title>
+<style>
+@media (max-width:620px){.ss-card{width:100%!important;border-radius:0!important}.ss-pad{padding:24px 20px!important}}
+@media (prefers-color-scheme:dark){.ss-page{background:#12161b!important}.ss-card{background:#1b2128!important}.ss-card h1,.ss-card h2,.ss-card p,.ss-card li,.ss-card td,.ss-card span{color:#e8edf2!important}.ss-card a:not(.ss-btn){color:#8db4ff!important}.ss-card .ss-soft{background:#2a333d!important}}
+</style>
+</head>
+<body class="ss-page" style="margin:0;padding:0;background:${theme.page};">
+${hiddenPreheader}
+<table role="presentation" class="ss-page" width="100%" cellpadding="0" cellspacing="0" border="0" style="background:${theme.page};"><tr><td align="center" style="padding:24px 12px;">
+<table role="presentation" class="ss-card" width="600" cellpadding="0" cellspacing="0" border="0" style="width:600px;max-width:100%;background:${theme.card};border-radius:12px;">
+<tr><td class="ss-pad" style="padding:32px 36px 8px;">${headerHtml}</td></tr>
+<tr><td class="ss-pad" style="padding:16px 36px 28px;">
+${items.map((b) => renderBlockHtml(b, theme)).join("\n")}
+</td></tr>
+${footerLines.length ? `<tr><td class="ss-pad" style="padding:0 36px 28px;border-top:1px solid ${theme.line};"><p style="margin:18px 0 0;font-family:${font};font-size:12px;line-height:1.6;color:${theme.muted};">${footerLines.map((l) => inlineHtml(l, theme)).join("<br>")}</p></td></tr>` : ""}
+</table>
+</td></tr></table>
+</body>
+</html>`;
+
+  const parts = items.map(renderBlockText);
+  if (brand.name) parts.unshift(brand.name);
+  if (footerLines.length) parts.push(`--\n${footerLines.map(inlineText).join("\n")}`);
+  return { subject: subject.trim(), html, text: parts.join("\n\n") + "\n" };
+}

package/src/text.js

@@ -0,0 +1,74 @@
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ", ndash: "–", mdash: "—", hellip: "…", euro: "€", copy: "©", laquo: "«", raquo: "»" };
+
+export const escapeHtml = (value) =>
+  String(value).replace(/[&<>"']/g, (ch) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[ch]);
+
+const decodeEntities = (text) =>
+  text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (whole, name) => {
+    if (name[0] === "#") {
+      const code = name[1].toLowerCase() === "x" ? parseInt(name.slice(2), 16) : parseInt(name.slice(1), 10);
+      return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : whole;
+    }
+    return ENTITIES[name.toLowerCase()] ?? whole;
+  });
+
+/** Plain-text version of an HTML mail: links become `label (url)`, lists get dashes, blocks get blank lines. */
+export function htmlToText(html) {
+  let text = String(html)
+    .replace(/<(head|style|script|title)[\s\S]*?<\/\1>/gi, "")
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .replace(/<a\s[^>]*?href\s*=\s*(?:"([^"]*)"|'([^']*)')[^>]*>([\s\S]*?)<\/a>/gi, (_, a, b, label) => {
+      const url = decodeEntities(a ?? b ?? "");
+      const inner = label.replace(/<[^>]*>/g, "").trim();
+      if (!inner || inner === url || /^(mailto|tel):/i.test(url) && decodeEntities(inner) === url.replace(/^\w+:/, "")) return inner || url;
+      return /^(https?|mailto|tel):/i.test(url) ? `${inner} (${url})` : inner;
+    })
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<hr\s*\/?>/gi, "\n----\n")
+    .replace(/<li[^>]*>/gi, "\n- ")
+    .replace(/<\/(p|div|tr|h[1-6]|ul|ol|table|blockquote)>/gi, "\n\n")
+    .replace(/<\/t[dh]>/gi, " ")
+    .replace(/<[^>]*>/g, "");
+  text = decodeEntities(text)
+    .replace(/[ \t\f\v]+/g, " ")
+    .replace(/ *\n */g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+  return text;
+}
+
+/** Wraps text at `width` characters on spaces. Words longer than the width (like URLs) stay whole. */
+export function wrapText(text, width = 76) {
+  return text
+    .split("\n")
+    .map((line) => {
+      if (line.length <= width) return line;
+      const indent = /^(\s*(?:- )?)/.exec(line)[1];
+      const hang = " ".repeat(indent.length);
+      const out = [];
+      let current = "";
+      for (const word of line.slice(indent.length).split(" ")) {
+        const candidate = current ? `${current} ${word}` : word;
+        if (current && (out.length ? hang : indent).length + candidate.length > width) {
+          out.push((out.length ? hang : indent) + current);
+          current = word;
+        } else current = candidate;
+      }
+      out.push((out.length ? hang : indent) + current);
+      return out.join("\n");
+    })
+    .join("\n");
+}
+
+/** Every http(s) link in an HTML string (from href attributes) or in a plain text, in order, without duplicates. */
+export function extractLinks(content) {
+  const found = [];
+  const add = (url) => {
+    const clean = decodeEntities(url).replace(/[).,;:!?]+$/, "");
+    if (/^https?:\/\//i.test(clean) && !found.includes(clean)) found.push(clean);
+  };
+  const source = String(content);
+  if (/<[a-z!][^>]*>/i.test(source)) for (const m of source.matchAll(/href\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)) add(m[1] ?? m[2]);
+  else for (const m of source.matchAll(/https?:\/\/[^\s<>"')]+/gi)) add(m[0]);
+  return found;
+}

package/src/transports.js

@@ -0,0 +1,113 @@
+import { formatAddress } from "./address.js";
+import { MailError } from "./errors.js";
+import { prepareMessage } from "./message.js";
+import { extractLinks } from "./text.js";
+
+const asMessage = (input) => (input && typeof input.raw !== "undefined" && input.envelope ? input : prepareMessage(input));
+
+/**
+ * Sends through the Resend HTTP API. The message id is sent as the idempotency key, so a retry after a timeout
+ * can never deliver the same mail twice.
+ */
+export function resendTransport(options = {}) {
+  const apiKey = options.apiKey;
+  if (typeof apiKey !== "string" || !/^re_\S+$/.test(apiKey)) throw new MailError("resendTransport needs an apiKey that starts with re_", { code: "invalid_config" });
+  const apiUrl = String(options.apiUrl ?? "https://api.resend.com").replace(/\/+$/, "");
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? 15_000;
+  return {
+    name: "resend",
+    async send(input) {
+      const m = asMessage(input);
+      const body = {
+        from: formatAddress(m.from),
+        to: m.to.map(formatAddress),
+        subject: m.subject,
+        text: m.text,
+        headers: m.headers,
+      };
+      if (m.cc.length) body.cc = m.cc.map(formatAddress);
+      if (m.bcc.length) body.bcc = m.bcc.map(formatAddress);
+      if (m.replyTo.length) body.reply_to = m.replyTo.map(formatAddress);
+      if (m.html !== undefined) body.html = m.html;
+      if (m.attachments.length) {
+        body.attachments = m.attachments.map((a) => ({ filename: a.filename, content: a.content.toString("base64"), content_type: a.contentType, ...(a.cid ? { content_id: a.cid } : {}) }));
+      }
+      let response;
+      try {
+        response = await doFetch(`${apiUrl}/emails`, {
+          method: "POST",
+          headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json", "idempotency-key": m.messageId.replace(/[<>]/g, "") },
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+      } catch (error) {
+        const timedOut = error?.name === "TimeoutError" || error?.name === "AbortError";
+        throw new MailError(timedOut ? "Resend did not answer in time" : `Could not reach Resend (${error?.cause?.code ?? error?.message ?? "error"})`, { code: timedOut ? "timeout" : "connection_failed", retryable: true, cause: error });
+      }
+      const payload = await response.json().catch(() => ({}));
+      if (!response.ok) {
+        const detail = String(payload?.message ?? payload?.error ?? response.statusText ?? "").slice(0, 300);
+        const retryable = response.status === 429 || response.status >= 500;
+        const code = response.status === 401 || response.status === 403 ? "auth_failed" : response.status === 429 ? "rate_limited" : retryable ? "temporary_failure" : "rejected";
+        throw new MailError(`Resend answered ${response.status}${detail ? `: ${detail}` : ""}`, { code, retryable, responseCode: response.status, response: detail });
+      }
+      return { id: payload?.id ?? m.messageId, messageId: m.messageId, accepted: m.envelope.to, rejected: [], response: "ok" };
+    },
+  };
+}
+
+/** Keeps every mail in memory instead of sending it. For tests and local development. */
+export function memoryTransport() {
+  const sent = [];
+  return {
+    name: "memory",
+    sent,
+    async send(input) {
+      const m = asMessage(input);
+      const record = {
+        ...m,
+        raw: m.raw,
+        /** Every http(s) link in the mail (html first, then text), e.g. the verification link. */
+        links: [...new Set([...extractLinks(m.html ?? ""), ...extractLinks(m.text)])],
+      };
+      sent.push(record);
+      return { id: `memory-${sent.length}`, messageId: m.messageId, accepted: m.envelope.to, rejected: [], response: "stored" };
+    },
+    last: () => sent[sent.length - 1],
+    clear: () => (sent.length = 0),
+    /** Newest mail sent to this address, or undefined. */
+    to: (address) => [...sent].reverse().find((m) => m.envelope.to.some((a) => a.toLowerCase() === address.toLowerCase())),
+  };
+}
+
+/**
+ * Tries the first transport and falls back to the next only when the first never got to accept the mail
+ * (could not connect, timed out before sending, server said "try later"). Never after a permanent rejection,
+ * and never when delivery is unknown, so no mail goes out twice.
+ */
+export function failoverTransport(transports) {
+  if (!Array.isArray(transports) || transports.length < 2) throw new MailError("failoverTransport needs at least two transports", { code: "invalid_config" });
+  return {
+    name: `failover(${transports.map((t) => t.name).join(",")})`,
+    async send(input) {
+      const m = asMessage(input);
+      let last;
+      for (const transport of transports) {
+        try {
+          const result = await transport.send(m);
+          return { ...result, transport: transport.name };
+        } catch (error) {
+          last = error;
+          if (!(error instanceof MailError) || !(error.retryable || error.code === "auth_failed" || error.code === "tls_failed" || error.code === "tls_unavailable")) throw error;
+        }
+      }
+      throw last;
+    },
+    async verify() {
+      const results = await Promise.allSettled(transports.map((t) => t.verify?.()));
+      if (results.every((r) => r.status === "rejected")) throw results[0].reason;
+      return true;
+    },
+  };
+}