@bobfrankston/mailx-types 0.1.38 → 0.1.40

package/index.d.ts

@@ -363,6 +363,46 @@ export declare function sanitizeHtml(html: string): {
     html: string;
     hasRemoteContent: boolean;
 };
+/**
+ * Encode a header VALUE as RFC 2047 encoded-words when it contains non-ASCII.
+ *
+ * Why this has to exist: a header carrying raw 8-bit UTF-8 makes the whole
+ * message an EAI message (RFC 6530), which can only be relayed over SMTPUTF8
+ * (RFC 6531). Plenty of receivers still don't advertise that extension, and a
+ * sending MTA that can't downgrade has no choice but to bounce. mailx built
+ * every outgoing header with bare interpolation — `Subject: ${msg.subject}` —
+ * so ONE curly apostrophe was enough to make a message undeliverable:
+ *
+ *   Subject: Re: … One of Canada’s Fastest Fiber Networks     (U+2019, raw UTF-8)
+ *   → <alland@soundbytesradio.com>: EAI message but server 17.57.152.5
+ *     does not support SMTPUTF8 … This is a permanent error
+ *
+ * (Bob 2026-08-08, qmail bounce from gal.iecc.com — iCloud, Zoho and
+ * land-com all refused it; herot.com, gmail and bob.ma took it, so it looked
+ * like a partial failure.) Reply subjects inherit whatever punctuation the
+ * original used, and Word/paste smart quotes do the rest, so this fires
+ * constantly and silently.
+ *
+ * Pure-ASCII values are returned untouched — encoding them would be legal but
+ * needlessly unreadable in every mail client's raw-source view.
+ *
+ * Base64 rather than Q-encoding: it is uniform (no per-character escaping
+ * rules that differ between phrase and unstructured context) and never
+ * produces a token needing further escaping. Chunks are split so each
+ * encoded-word stays inside RFC 2047's 75-character limit, split on CHARACTER
+ * boundaries so a multi-byte sequence is never cut in half.
+ */
+export declare function encodeHeaderWord(text: string): string;
+/**
+ * Encode an address header value (From/To/Cc/Bcc/Reply-To), encoding only the
+ * DISPLAY NAME of each address. The addr-spec must stay literal: encoding it
+ * would corrupt the address, and a non-ASCII addr-spec is genuinely EAI and
+ * cannot be represented any other way.
+ *
+ * Splits on commas outside angle brackets and quotes so a display name
+ * containing a comma ("Frankston, Bob" <x@y>) survives.
+ */
+export declare function encodeAddressHeader(value: string): string;
 /** Encode text as RFC 2045 quoted-printable. */
 export declare function encodeQuotedPrintable(text: string): string;
 /** Render an HTML document as a plain-text approximation suitable for the

package/index.js

@@ -106,6 +106,123 @@ export function sanitizeHtml(html) {
     clean = clean.replace(/<iframe\b[^>]*>[\s\S]*?<\/iframe>/gi, "");
     return { html: clean, hasRemoteContent };
 }
+/**
+ * Encode a header VALUE as RFC 2047 encoded-words when it contains non-ASCII.
+ *
+ * Why this has to exist: a header carrying raw 8-bit UTF-8 makes the whole
+ * message an EAI message (RFC 6530), which can only be relayed over SMTPUTF8
+ * (RFC 6531). Plenty of receivers still don't advertise that extension, and a
+ * sending MTA that can't downgrade has no choice but to bounce. mailx built
+ * every outgoing header with bare interpolation — `Subject: ${msg.subject}` —
+ * so ONE curly apostrophe was enough to make a message undeliverable:
+ *
+ *   Subject: Re: … One of Canada’s Fastest Fiber Networks     (U+2019, raw UTF-8)
+ *   → <alland@soundbytesradio.com>: EAI message but server 17.57.152.5
+ *     does not support SMTPUTF8 … This is a permanent error
+ *
+ * (Bob 2026-08-08, qmail bounce from gal.iecc.com — iCloud, Zoho and
+ * land-com all refused it; herot.com, gmail and bob.ma took it, so it looked
+ * like a partial failure.) Reply subjects inherit whatever punctuation the
+ * original used, and Word/paste smart quotes do the rest, so this fires
+ * constantly and silently.
+ *
+ * Pure-ASCII values are returned untouched — encoding them would be legal but
+ * needlessly unreadable in every mail client's raw-source view.
+ *
+ * Base64 rather than Q-encoding: it is uniform (no per-character escaping
+ * rules that differ between phrase and unstructured context) and never
+ * produces a token needing further escaping. Chunks are split so each
+ * encoded-word stays inside RFC 2047's 75-character limit, split on CHARACTER
+ * boundaries so a multi-byte sequence is never cut in half.
+ */
+export function encodeHeaderWord(text) {
+    if (!text)
+        return "";
+    // eslint-disable-next-line no-control-regex
+    if (!/[^\x00-\x7F]/.test(text))
+        return text;
+    const encoder = new TextEncoder();
+    // "=?UTF-8?B?" + payload + "?=" must be ≤ 75 chars, so the base64 payload
+    // gets 75 - 12 = 63 chars, and base64 only splits cleanly every 4 chars →
+    // 60 chars of payload = 45 bytes of input per encoded-word.
+    const MAX_BYTES_PER_WORD = 45;
+    const words = [];
+    let chunk = [];
+    for (const ch of text) { // iterate by code point
+        const bytes = Array.from(encoder.encode(ch));
+        if (chunk.length + bytes.length > MAX_BYTES_PER_WORD) {
+            words.push(chunk);
+            chunk = [];
+        }
+        chunk.push(...bytes);
+    }
+    if (chunk.length)
+        words.push(chunk);
+    // Continuation lines are joined with CRLF + space: consecutive
+    // encoded-words separated by folding whitespace are concatenated by the
+    // receiver with the whitespace REMOVED (RFC 2047 §6.2), which is what we
+    // want — the original text had no space there.
+    return words
+        .map(b => `=?UTF-8?B?${bytesToBase64(Uint8Array.from(b))}?=`)
+        .join("\r\n ");
+}
+/** Base64 without assuming Buffer (this package is browser-capable). */
+function bytesToBase64(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    // btoa exists in browsers and in Node ≥16.
+    return btoa(bin);
+}
+/**
+ * Encode an address header value (From/To/Cc/Bcc/Reply-To), encoding only the
+ * DISPLAY NAME of each address. The addr-spec must stay literal: encoding it
+ * would corrupt the address, and a non-ASCII addr-spec is genuinely EAI and
+ * cannot be represented any other way.
+ *
+ * Splits on commas outside angle brackets and quotes so a display name
+ * containing a comma ("Frankston, Bob" <x@y>) survives.
+ */
+export function encodeAddressHeader(value) {
+    if (!value)
+        return "";
+    // eslint-disable-next-line no-control-regex
+    if (!/[^\x00-\x7F]/.test(value))
+        return value;
+    const parts = [];
+    let cur = "";
+    let inAngle = false;
+    let inQuote = false;
+    for (const ch of value) {
+        if (ch === '"')
+            inQuote = !inQuote;
+        else if (ch === "<" && !inQuote)
+            inAngle = true;
+        else if (ch === ">" && !inQuote)
+            inAngle = false;
+        if (ch === "," && !inAngle && !inQuote) {
+            parts.push(cur);
+            cur = "";
+            continue;
+        }
+        cur += ch;
+    }
+    if (cur.trim())
+        parts.push(cur);
+    return parts.map(part => {
+        const p = part.trim();
+        const m = /^(.*?)\s*(<[^>]*>)\s*$/.exec(p);
+        if (!m)
+            return p; // bare addr-spec, nothing to encode
+        const display = m[1].replace(/^"(.*)"$/s, "$1");
+        if (!display)
+            return m[2];
+        // eslint-disable-next-line no-control-regex
+        if (!/[^\x00-\x7F]/.test(display))
+            return p; // ASCII name — leave the quoting alone
+        return `${encodeHeaderWord(display)} ${m[2]}`;
+    }).join(", ");
+}
 /** Encode text as RFC 2045 quoted-printable. */
 export function encodeQuotedPrintable(text) {
     const encoder = new TextEncoder();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-types",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",