@bobfrankston/mailx-types 0.1.36 → 0.1.40

package/index.d.ts

@@ -10,6 +10,8 @@ export { expandRecipients, splitRecipients, isAddressToken, extractAddress, } fr
 export type { GroupMap, RecipientToken, ExpansionResult } from "./groups.js";
 export { REMINDER_STATE_FILE, normalizeReminderState, mergeReminderStates, reminderStatesEqual, } from "./reminder-state.js";
 export type { ReminderState } from "./reminder-state.js";
+export { extractInlineImages } from "./mime-inline-images.js";
+export type { InlineImagePart } from "./mime-inline-images.js";
 /** Supported authentication methods */
 export type AuthMethod = "password" | "oauth2";
 /** Mail account configuration */
@@ -361,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

@@ -17,6 +17,9 @@ export { expandRecipients, splitRecipients, isAddressToken, extractAddress, } fr
 // Reminder dismissed/snoozed cross-device state — one merge implementation
 // for the desktop service (mailx-settings) and Android/web (mailx-store-web).
 export { REMINDER_STATE_FILE, normalizeReminderState, mergeReminderStates, reminderStatesEqual, } from "./reminder-state.js";
+// Outgoing-mail inline images: data: URI → cid: extraction shared by both
+// MIME assemblers (desktop send + Android/web send).
+export { extractInlineImages } from "./mime-inline-images.js";
 // ── Message flag state ──
 //
 // External API surface for the IMAP system flags. The literal strings
@@ -103,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/mime-inline-images.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Inline-image extraction for outgoing mail.
+ *
+ * The compose editors embed pasted/inlined images as `data:` URIs — that's
+ * what renders inside a WebView editor with no server round-trip. But a
+ * `data:` URI inside the text/html MIME part is NOT interoperable mail:
+ * Outlook desktop (Word renderer) doesn't render data: images at all, and
+ * Gmail's web sanitizer strips them, so recipients on the two biggest
+ * platforms see broken/missing images while Thunderbird/Apple Mail users see
+ * the message fine. The interoperable form is RFC 2392 `cid:` references to
+ * base64 image parts inside a multipart/related wrapper — what every mail
+ * client has emitted since the 90s.
+ *
+ * This helper rewrites `<img src="data:...;base64,...">` to `cid:` refs and
+ * hands back the extracted parts; the platform send() paths (desktop
+ * mailx-service and Android/web web-service) wrap them into
+ * multipart/related. Shared here (mailx-types, zero deps) so both MIME
+ * assemblers can't drift apart.
+ *
+ * Non-base64 data: URIs (utf8 SVG etc.) are left in place — rare, small,
+ * and rewriting them would mean re-encoding; the size/interop problem this
+ * solves comes from pasted photos, which are always base64.
+ */
+export interface InlineImagePart {
+    /** Content-ID value WITHOUT angle brackets (use `<${contentId}>` in the header). */
+    contentId: string;
+    mime: string;
+    base64: string;
+}
+/** Pull base64 `data:` images out of the HTML, replacing each src with a
+ *  `cid:` reference. Identical data: URIs (the same image pasted twice)
+ *  collapse to one part. `idDomain` scopes the Content-IDs (RFC 2392 wants
+ *  msg-id-like uniqueness). */
+export declare function extractInlineImages(html: string, idDomain: string): {
+    html: string;
+    images: InlineImagePart[];
+};
+//# sourceMappingURL=mime-inline-images.d.ts.map

package/mime-inline-images.js

@@ -0,0 +1,45 @@
+/**
+ * Inline-image extraction for outgoing mail.
+ *
+ * The compose editors embed pasted/inlined images as `data:` URIs — that's
+ * what renders inside a WebView editor with no server round-trip. But a
+ * `data:` URI inside the text/html MIME part is NOT interoperable mail:
+ * Outlook desktop (Word renderer) doesn't render data: images at all, and
+ * Gmail's web sanitizer strips them, so recipients on the two biggest
+ * platforms see broken/missing images while Thunderbird/Apple Mail users see
+ * the message fine. The interoperable form is RFC 2392 `cid:` references to
+ * base64 image parts inside a multipart/related wrapper — what every mail
+ * client has emitted since the 90s.
+ *
+ * This helper rewrites `<img src="data:...;base64,...">` to `cid:` refs and
+ * hands back the extracted parts; the platform send() paths (desktop
+ * mailx-service and Android/web web-service) wrap them into
+ * multipart/related. Shared here (mailx-types, zero deps) so both MIME
+ * assemblers can't drift apart.
+ *
+ * Non-base64 data: URIs (utf8 SVG etc.) are left in place — rare, small,
+ * and rewriting them would mean re-encoding; the size/interop problem this
+ * solves comes from pasted photos, which are always base64.
+ */
+/** Pull base64 `data:` images out of the HTML, replacing each src with a
+ *  `cid:` reference. Identical data: URIs (the same image pasted twice)
+ *  collapse to one part. `idDomain` scopes the Content-IDs (RFC 2392 wants
+ *  msg-id-like uniqueness). */
+export function extractInlineImages(html, idDomain) {
+    const images = [];
+    const byDataUri = new Map(); // data-uri → contentId
+    const stamp = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+    const out = html.replace(/(<img\b[^>]*?\ssrc=)(["'])(data:(image\/[\w.+-]+);base64,([A-Za-z0-9+/=\s]+))\2/gi, (_m, prefix, quote, dataUri, mime, b64) => {
+        let cid = byDataUri.get(dataUri);
+        if (!cid) {
+            cid = `img${images.length + 1}.${stamp}@${idDomain}`;
+            byDataUri.set(dataUri, cid);
+            // Strip whitespace the editor may have wrapped into the URI;
+            // the send path re-wraps at 76 cols per RFC 2045.
+            images.push({ contentId: cid, mime, base64: b64.replace(/\s+/g, "") });
+        }
+        return `${prefix}${quote}cid:${cid}${quote}`;
+    });
+    return { html: out, images };
+}
+//# sourceMappingURL=mime-inline-images.js.map

package/package.json

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