@sandsoftwaresolutions/mail-kit 0.1.0 → 0.1.1

package/README.md

@@ -40,7 +40,7 @@ Node 20 or newer. Works with `import` and `require()`, with TypeScript types for
 
 ## 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)`. Everything is escaped; unsafe links and invalid colors are refused, not passed through.
+**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.**
 

package/dist/index.cjs

@@ -3,7 +3,7 @@ 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 } = require("./template.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");
@@ -25,6 +25,7 @@ exports.htmlToText = htmlToText;
 exports.wrapText = wrapText;
 exports.block = block;
 exports.email = email;
+exports.escapeMarkup = escapeMarkup;
 exports.smtpTransport = smtpTransport;
 exports.failoverTransport = failoverTransport;
 exports.memoryTransport = memoryTransport;

package/dist/index.d.cts

@@ -119,6 +119,8 @@ export interface EmailOptions {
 }
 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 }[];
 

package/dist/template.cjs

@@ -15,7 +15,11 @@ const color = (value, fallback, name) => {
 };
 
 // Inline markup used in every text block: **bold**, `code`, [label](https://url). Everything else is plain text.
-const INLINE = /\[([^\]\n]+)\]\(([^)\s]+)\)|\*\*([^*\n]+)\*\*|`([^`\n]+)`/g;
+// 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 = "";
@@ -23,16 +27,18 @@ function inlineHtml(text, theme) {
   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 += LINKABLE.test(m[2]) ? `<a href="${escapeHtml(m[2])}" style="color:${theme.accent};text-decoration:underline;">${escapeHtml(m[1])}</a>` : escapeHtml(m[1]);
-    } else if (m[3] !== undefined) out += `<strong>${escapeHtml(m[3])}</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[4])}</code>`;
+    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, (_, label, url, bold, code) => {
+  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;
   });
@@ -195,5 +201,6 @@ ${footerLines.length ? `<tr><td class="ss-pad" style="padding:0 36px 28px;border
   return { subject: subject.trim(), html, text: parts.join("\n\n") + "\n" };
 }
 
+exports.escapeMarkup = escapeMarkup;
 exports.block = block;
 exports.email = email;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandsoftwaresolutions/mail-kit",
-  "version": "0.1.0",
+  "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",

package/src/index.d.ts

@@ -119,6 +119,8 @@ export interface EmailOptions {
 }
 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 }[];
 

package/src/index.js

@@ -2,7 +2,7 @@ import { MailError } from "./errors.js";
 import { encodeWords, formatAddress, isEmail, normalizeAddress, parseAddress, parseAddressList } from "./address.js";
 import { prepareMessage, quotedPrintable } from "./message.js";
 import { escapeHtml, extractLinks, htmlToText, wrapText } from "./text.js";
-import { block, email } from "./template.js";
+import { block, email, escapeMarkup } from "./template.js";
 import { smtpTransport } from "./smtp.js";
 import { failoverTransport, memoryTransport, resendTransport } from "./transports.js";
 import { createMailer } from "./mailer.js";
@@ -11,4 +11,4 @@ import { preview } from "./preview.js";
 
 export { MailError, encodeWords, formatAddress, isEmail, normalizeAddress, parseAddress, parseAddressList };
 export { prepareMessage, quotedPrintable, escapeHtml, extractLinks, htmlToText, wrapText };
-export { block, email, smtpTransport, failoverTransport, memoryTransport, resendTransport, createMailer, lintEmail, preview };
+export { block, email, escapeMarkup, smtpTransport, failoverTransport, memoryTransport, resendTransport, createMailer, lintEmail, preview };

package/src/template.js

@@ -14,7 +14,11 @@ const color = (value, fallback, name) => {
 };
 
 // Inline markup used in every text block: **bold**, `code`, [label](https://url). Everything else is plain text.
-const INLINE = /\[([^\]\n]+)\]\(([^)\s]+)\)|\*\*([^*\n]+)\*\*|`([^`\n]+)`/g;
+// 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 = "";
@@ -22,16 +26,18 @@ function inlineHtml(text, theme) {
   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 += LINKABLE.test(m[2]) ? `<a href="${escapeHtml(m[2])}" style="color:${theme.accent};text-decoration:underline;">${escapeHtml(m[1])}</a>` : escapeHtml(m[1]);
-    } else if (m[3] !== undefined) out += `<strong>${escapeHtml(m[3])}</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[4])}</code>`;
+    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, (_, label, url, bold, code) => {
+  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;
   });