@bobfrankston/mailx-types 0.1.49 → 0.1.53

package/index.d.ts

@@ -439,4 +439,55 @@ export declare function parseSearchQuery(query: string): {
     conditions: string[];
     params: (string | number)[];
 };
+/**
+ * Is this text a JS "missing value" that leaked into a message body?
+ *
+ * Marketing mail whose `text/plain` alternative is generated in JavaScript
+ * sometimes stringifies an absent value straight into the part, so the entire
+ * plain-text body is the word `undefined`. Adobe Firefly / Creative Cloud and
+ * Xfinity do this — 40 messages in Bob's bobma store on 2026-08-19, every one
+ * with a perfectly good HTML part sitting next to the junk text part.
+ *
+ * Used in two places that must agree:
+ *   - `extractPreview` (mailx-imap) — skip the text part and summarize the
+ *     HTML instead, so newly-synced mail never indexes the junk.
+ *   - the message-list row renderer — suppress the snippet for rows that were
+ *     already indexed with it, so old rows heal without a re-sync.
+ *
+ * Deliberately narrow: only values that mean "a value was missing". `false`,
+ * `0` and `no` are excluded — those are things a human might actually write.
+ */
+export declare function isJunkPreviewText(s: string | null | undefined): boolean;
+/**
+ * Does a display name assert an email address other than the real one?
+ *
+ * Display-name spoofing is the cheapest phish there is: put
+ * `security@paypal.com` in the From *name* and point the real address at
+ * anywhere. The message list shows only the display name, so nothing on
+ * screen contradicts the claim.
+ *
+ * Returns the claimed address when the name contains an email-like token that
+ * differs from `address`, otherwise null. A name that merely repeats the real
+ * address is not spoofing — see formatSender, which collapses that case.
+ */
+export declare function displayNameClaimsOtherAddress(name: string, address: string): string | null;
+/**
+ * How a sender should read in the UI.
+ *
+ * `text` is what to show. `claimed` is set when the display name asserts a
+ * different address than the envelope's — callers must make the real address
+ * visible in that case rather than trusting `text` alone.
+ *
+ * Collapses the redundant `"x@y.com" <x@y.com>` form that Microsoft 365
+ * quarantine notices and plenty of bulk senders emit — showing the same
+ * address twice reads as if two different parties were involved
+ * (Bob 2026-08-19).
+ */
+export declare function formatSender(addr: {
+    name?: string;
+    address: string;
+} | null | undefined): {
+    text: string;
+    claimed: string | null;
+};
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -434,4 +434,76 @@ export function parseSearchQuery(query) {
     }
     return { conditions, params };
 }
+/**
+ * Is this text a JS "missing value" that leaked into a message body?
+ *
+ * Marketing mail whose `text/plain` alternative is generated in JavaScript
+ * sometimes stringifies an absent value straight into the part, so the entire
+ * plain-text body is the word `undefined`. Adobe Firefly / Creative Cloud and
+ * Xfinity do this — 40 messages in Bob's bobma store on 2026-08-19, every one
+ * with a perfectly good HTML part sitting next to the junk text part.
+ *
+ * Used in two places that must agree:
+ *   - `extractPreview` (mailx-imap) — skip the text part and summarize the
+ *     HTML instead, so newly-synced mail never indexes the junk.
+ *   - the message-list row renderer — suppress the snippet for rows that were
+ *     already indexed with it, so old rows heal without a re-sync.
+ *
+ * Deliberately narrow: only values that mean "a value was missing". `false`,
+ * `0` and `no` are excluded — those are things a human might actually write.
+ */
+export function isJunkPreviewText(s) {
+    const t = (s || "").replace(/\s+/g, " ").trim().toLowerCase();
+    if (!t)
+        return true;
+    return t === "undefined" || t === "null" || t === "nan" || t === "[object object]";
+}
+/**
+ * Does a display name assert an email address other than the real one?
+ *
+ * Display-name spoofing is the cheapest phish there is: put
+ * `security@paypal.com` in the From *name* and point the real address at
+ * anywhere. The message list shows only the display name, so nothing on
+ * screen contradicts the claim.
+ *
+ * Returns the claimed address when the name contains an email-like token that
+ * differs from `address`, otherwise null. A name that merely repeats the real
+ * address is not spoofing — see formatSender, which collapses that case.
+ */
+export function displayNameClaimsOtherAddress(name, address) {
+    const n = (name || "").trim();
+    if (!n)
+        return null;
+    const real = (address || "").trim().toLowerCase();
+    // Deliberately loose: anything shaped like local@domain.tld inside the name.
+    const m = n.match(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g);
+    if (!m)
+        return null;
+    for (const claimed of m) {
+        if (claimed.toLowerCase() !== real)
+            return claimed;
+    }
+    return null;
+}
+/**
+ * How a sender should read in the UI.
+ *
+ * `text` is what to show. `claimed` is set when the display name asserts a
+ * different address than the envelope's — callers must make the real address
+ * visible in that case rather than trusting `text` alone.
+ *
+ * Collapses the redundant `"x@y.com" <x@y.com>` form that Microsoft 365
+ * quarantine notices and plenty of bulk senders emit — showing the same
+ * address twice reads as if two different parties were involved
+ * (Bob 2026-08-19).
+ */
+export function formatSender(addr) {
+    const address = (addr?.address || "").trim();
+    const name = (addr?.name || "").trim();
+    if (!name)
+        return { text: address, claimed: null };
+    if (name.toLowerCase() === address.toLowerCase())
+        return { text: address, claimed: null };
+    return { text: `${name} <${address}>`, claimed: displayNameClaimsOtherAddress(name, address) };
+}
 //# sourceMappingURL=index.js.map

package/package.json

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