@sandsoftwaresolutions/mail-kit 0.0.0-stage → 0.1.1

package/dist/template.cjs

@@ -0,0 +1,206 @@
+"use strict";
+const { MailError } = require("./errors.cjs");
+const { escapeHtml, wrapText } = require("./text.cjs");
+
+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. */
+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)`. */
+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.
+ */
+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" };
+}
+
+exports.escapeMarkup = escapeMarkup;
+exports.block = block;
+exports.email = email;

package/dist/text.cjs

@@ -0,0 +1,80 @@
+"use strict";
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ", ndash: "–", mdash: "—", hellip: "…", euro: "€", copy: "©", laquo: "«", raquo: "»" };
+
+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. */
+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. */
+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. */
+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;
+}
+
+exports.escapeHtml = escapeHtml;
+exports.htmlToText = htmlToText;
+exports.wrapText = wrapText;
+exports.extractLinks = extractLinks;

package/dist/transports.cjs

@@ -0,0 +1,118 @@
+"use strict";
+const { formatAddress } = require("./address.cjs");
+const { MailError } = require("./errors.cjs");
+const { prepareMessage } = require("./message.cjs");
+const { extractLinks } = require("./text.cjs");
+
+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.
+ */
+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. */
+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.
+ */
+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;
+    },
+  };
+}
+
+exports.resendTransport = resendTransport;
+exports.memoryTransport = memoryTransport;
+exports.failoverTransport = failoverTransport;

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@sandsoftwaresolutions/mail-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Send good-looking email from Node with no dependencies: SMTP (Zoho, Gmail, ...) and Resend, templates that work in Outlook and dark mode, automatic text version, safe by default, retries without double-sending.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./src/index.d.ts",
+        "default": "./src/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test && node scripts/build-cjs.mjs --check",
+    "pack:check": "npm pack --dry-run",
+    "build": "node scripts/build-cjs.mjs",
+    "prepack": "node scripts/build-cjs.mjs"
+  },
+  "keywords": [
+    "email",
+    "mail",
+    "smtp",
+    "resend",
+    "template",
+    "transactional",
+    "mime",
+    "zoho"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SandSoftwareSolutions/ss-mail-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SandSoftwareSolutions/ss-mail-kit/issues"
+  },
+  "homepage": "https://github.com/SandSoftwareSolutions/ss-mail-kit#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/address.js

@@ -0,0 +1,123 @@
+import { domainToASCII } from "node:url";
+
+import { MailError } from "./errors.js";
+
+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. */
+export 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}`;
+}
+
+export 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 }`. */
+export 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. */
+export 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. */
+export 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 ");
+}
+
+export function formatAddress({ name, address }) {
+  if (!name) return address;
+  if (PRINTABLE_ASCII.test(name)) return `"${name.replace(/(["\\])/g, "\\$1")}" <${address}>`;
+  return `${encodeWords(name)} <${address}>`;
+}
+
+export function formatAddressList(list) {
+  return list.map(formatAddress).join(",\r\n ");
+}

package/src/errors.js

@@ -0,0 +1,10 @@
+/** Every failure of this package is a MailError, so callers can branch on `code` and `retryable`. */
+export 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);
+  }
+}