@bobfrankston/mailx-types 0.1.5 → 0.1.6

package/build-rules.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Generates contact-rules.ts from contact-rules.jsonc.
+ *
+ * The .jsonc is the source-of-truth (editable, comments, versioned in
+ * source). The .ts is what mailx-store and mailx-store-web import — Android
+ * has no `fs` to parse JSONC at runtime, and inlining the parsed object
+ * sidesteps that constraint cleanly.
+ *
+ * Run via `npm run build` (prebuild hook) or directly: `node build-rules.js`.
+ * Both .jsonc and generated .ts are checked in; the .ts is regenerated on
+ * every build so its mtime is deterministic relative to the .jsonc.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const __dirname = import.meta.dirname;
+const srcPath = path.join(__dirname, "contact-rules.jsonc");
+const outPath = path.join(__dirname, "contact-rules.ts");
+
+const raw = fs.readFileSync(srcPath, "utf-8");
+// Loose JSONC handler: strip // line comments and trailing commas. Avoids
+// pulling in jsonc-parser as a dep for what's effectively config.
+const stripped = raw
+    .replace(/^\s*\/\/.*$/gm, "")
+    .replace(/,(\s*[}\]])/g, "$1");
+const obj = JSON.parse(stripped);
+
+const banner = "// AUTO-GENERATED from contact-rules.jsonc — do not edit.\n" +
+               "// Edit the .jsonc and run `node build-rules.js` (or `npm run build`).\n\n";
+const ts = banner + `export const CONTACT_RULES = ${JSON.stringify(obj, null, 4)} as const;\n`;
+fs.writeFileSync(outPath, ts);
+console.log(`[mailx-types] regenerated ${path.basename(outPath)}`);

package/contact-rules.d.ts

@@ -0,0 +1,11 @@
+export declare const CONTACT_RULES: {
+    readonly rulesVersion: "v3-domain-oneoff";
+    readonly junk: {
+        readonly localExact: "^(no-?reply|do-?not-?reply|noreply|mailer-daemon|postmaster|abuse|automated|bounce(s|d)?|list-?(server|admin|owner|manager)?|notification|notifications?|admin@.*automated|root|daemon|nobody|undisclosed)$";
+        readonly localSuffix: "(-bounces|\\+bounces|-noreply|-no-reply|-notifications?|-mailer)$";
+        readonly localPrefix: "^(no-?reply|noreply|do-?not-?reply|donotreply|notifications?|alerts?|bounces?|mailer)[-_+]";
+        readonly localOneoff: "^[0-9a-f]{4}\\.[0-9a-f]{4}(\\.[0-9a-z]{6})?$";
+        readonly domain: "^(txt\\.voice\\.google\\.com|reply\\.facebook\\.com|reply\\.linkedin\\.com)$";
+    };
+};
+//# sourceMappingURL=contact-rules.d.ts.map

package/contact-rules.js

@@ -0,0 +1,13 @@
+// AUTO-GENERATED from contact-rules.jsonc — do not edit.
+// Edit the .jsonc and run `node build-rules.js` (or `npm run build`).
+export const CONTACT_RULES = {
+    "rulesVersion": "v3-domain-oneoff",
+    "junk": {
+        "localExact": "^(no-?reply|do-?not-?reply|noreply|mailer-daemon|postmaster|abuse|automated|bounce(s|d)?|list-?(server|admin|owner|manager)?|notification|notifications?|admin@.*automated|root|daemon|nobody|undisclosed)$",
+        "localSuffix": "(-bounces|\\+bounces|-noreply|-no-reply|-notifications?|-mailer)$",
+        "localPrefix": "^(no-?reply|noreply|do-?not-?reply|donotreply|notifications?|alerts?|bounces?|mailer)[-_+]",
+        "localOneoff": "^[0-9a-f]{4}\\.[0-9a-f]{4}(\\.[0-9a-z]{6})?$",
+        "domain": "^(txt\\.voice\\.google\\.com|reply\\.facebook\\.com|reply\\.linkedin\\.com)$"
+    }
+};
+//# sourceMappingURL=contact-rules.js.map

package/contact-rules.jsonc

@@ -0,0 +1,28 @@
+// mailx — global contact-filter rules (data, NOT user prefs).
+//
+// Edit the regex strings below; run `node build-rules.js` from this package
+// (or `npm run build`) to regenerate `contact-rules.ts`, which is what
+// mailx-store and mailx-store-web import. The .ts export is generated;
+// the .jsonc you're reading is the source of truth.
+//
+// rulesVersion: bump whenever the patterns tighten. The contacts table
+// runs a one-shot purge keyed off this string so historical rows under
+// older rules get cleaned up exactly once per device.
+//
+// Rule shape:
+//   localExact   — whole local-part match (e.g. "noreply", "mailer-daemon")
+//   localSuffix  — local-part ends with (e.g. "-bounces", "+bounces")
+//   localPrefix  — local-part starts with + separator (e.g. "noreply-<rand>")
+//   localOneoff  — full-shape match for per-message gateway addresses
+//                  (e.g. "16179691997.15082868100.nfblcbll1x")
+//   domain       — entire domain match (Google Voice SMS, reply.fb.com)
+{
+  "rulesVersion": "v3-domain-oneoff",
+  "junk": {
+    "localExact": "^(no-?reply|do-?not-?reply|noreply|mailer-daemon|postmaster|abuse|automated|bounce(s|d)?|list-?(server|admin|owner|manager)?|notification|notifications?|admin@.*automated|root|daemon|nobody|undisclosed)$",
+    "localSuffix": "(-bounces|\\+bounces|-noreply|-no-reply|-notifications?|-mailer)$",
+    "localPrefix": "^(no-?reply|noreply|do-?not-?reply|donotreply|notifications?|alerts?|bounces?|mailer)[-_+]",
+    "localOneoff": "^[0-9a-f]{4,}\\.[0-9a-f]{4,}(\\.[0-9a-z]{6,})?$",
+    "domain": "^(txt\\.voice\\.google\\.com|reply\\.facebook\\.com|reply\\.linkedin\\.com)$"
+  }
+}

package/groups.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Group expansion — turns a recipient string with group names into a flat
+ * deduplicated address list. Shared between desktop (mailx-service) and
+ * Android (mailx-store-web) so send paths produce the same result.
+ *
+ * Group source: contacts.jsonc → groups: Record<string, string[]>. Each
+ * value is an array of either email addresses ("a@b" or "Name <a@b>") or
+ * names of other groups (recursive aliasing). Cycles are detected; depth
+ * is capped at 10 nested levels.
+ */
+/** Raw recipient string from a To/Cc/Bcc field; may contain group names. */
+export type RecipientToken = string;
+/** Map of group name → member list (each entry: address or another group name). */
+export type GroupMap = Record<string, string[]>;
+/** Result of expanding a recipient string. */
+export interface ExpansionResult {
+    /** Flat unique address list (preserving order of first occurrence). */
+    addresses: string[];
+    /** Group names that couldn't be resolved (typo / cycle) — surface in UI. */
+    unresolved: string[];
+}
+/** Split a comma-or-semicolon recipient string into tokens. Respects
+ *  angle-bracket address blocks ("Name, Suffix <a@b>") so a comma inside
+ *  the display name doesn't split the entry. */
+export declare function splitRecipients(raw: string): RecipientToken[];
+/** Quick test: does the token look like an email address (with or without
+ *  a display name)? Anything containing "@" with non-whitespace on both
+ *  sides counts. */
+export declare function isAddressToken(token: string): boolean;
+/** Extract the bare email address from a token. Returns the original token
+ *  lowercased if it has no angle-bracket form. */
+export declare function extractAddress(token: string): string;
+/** Expand a recipient string by resolving group names against `groups`.
+ *  Group names take precedence: if a token matches a group name AND looks
+ *  like an address, it's treated as a group. (In practice no one names a
+ *  group "x@y.com", so this is rarely a real conflict.) */
+export declare function expandRecipients(raw: string, groups: GroupMap): ExpansionResult;
+//# sourceMappingURL=groups.d.ts.map

package/groups.js

@@ -0,0 +1,99 @@
+/**
+ * Group expansion — turns a recipient string with group names into a flat
+ * deduplicated address list. Shared between desktop (mailx-service) and
+ * Android (mailx-store-web) so send paths produce the same result.
+ *
+ * Group source: contacts.jsonc → groups: Record<string, string[]>. Each
+ * value is an array of either email addresses ("a@b" or "Name <a@b>") or
+ * names of other groups (recursive aliasing). Cycles are detected; depth
+ * is capped at 10 nested levels.
+ */
+/** Split a comma-or-semicolon recipient string into tokens. Respects
+ *  angle-bracket address blocks ("Name, Suffix <a@b>") so a comma inside
+ *  the display name doesn't split the entry. */
+export function splitRecipients(raw) {
+    const out = [];
+    let buf = "";
+    let depth = 0;
+    for (let i = 0; i < raw.length; i++) {
+        const c = raw[i];
+        if (c === "<")
+            depth++;
+        else if (c === ">")
+            depth = Math.max(0, depth - 1);
+        if ((c === "," || c === ";") && depth === 0) {
+            const t = buf.trim();
+            if (t)
+                out.push(t);
+            buf = "";
+        }
+        else {
+            buf += c;
+        }
+    }
+    const t = buf.trim();
+    if (t)
+        out.push(t);
+    return out;
+}
+/** Quick test: does the token look like an email address (with or without
+ *  a display name)? Anything containing "@" with non-whitespace on both
+ *  sides counts. */
+export function isAddressToken(token) {
+    return /^[^@\s][^@]*@[^@\s]+(\s|$)|<[^>]+@[^>]+>/.test(token) || /^[^\s<>@]+@[^\s<>@]+$/.test(token);
+}
+/** Extract the bare email address from a token. Returns the original token
+ *  lowercased if it has no angle-bracket form. */
+export function extractAddress(token) {
+    const m = token.match(/<([^>]+)>/);
+    if (m)
+        return m[1].trim().toLowerCase();
+    return token.trim().toLowerCase();
+}
+/** Expand a recipient string by resolving group names against `groups`.
+ *  Group names take precedence: if a token matches a group name AND looks
+ *  like an address, it's treated as a group. (In practice no one names a
+ *  group "x@y.com", so this is rarely a real conflict.) */
+export function expandRecipients(raw, groups) {
+    const tokens = splitRecipients(raw);
+    const seen = new Set();
+    const addresses = [];
+    const unresolved = [];
+    const visit = (token, depth, visited) => {
+        if (depth > 10) {
+            unresolved.push(`${token} (depth limit)`);
+            return;
+        }
+        // Group name match — case-insensitive
+        const groupKey = Object.keys(groups).find(k => k.toLowerCase() === token.trim().toLowerCase());
+        if (groupKey) {
+            if (visited.has(groupKey.toLowerCase())) {
+                unresolved.push(`${groupKey} (cycle)`);
+                return;
+            }
+            const next = new Set(visited);
+            next.add(groupKey.toLowerCase());
+            for (const member of groups[groupKey] || []) {
+                visit(member, depth + 1, next);
+            }
+            return;
+        }
+        // Address — keep the original (with display name if present), but
+        // dedupe by lowercased bare address.
+        if (isAddressToken(token)) {
+            const key = extractAddress(token);
+            if (!seen.has(key)) {
+                seen.add(key);
+                addresses.push(token.trim());
+            }
+            return;
+        }
+        // Neither group nor address — flag.
+        unresolved.push(token);
+    };
+    for (const t of tokens) {
+        visit(t, 0, new Set());
+    }
+    return { addresses, unresolved };
+}
+//# sourceMappingURL=groups.js.map

package/index.d.ts

@@ -3,6 +3,9 @@
  * Shared type definitions for the mailx email client.
  * This is the contract between client and server.
  */
+export { CONTACT_RULES } from "./contact-rules.js";
+export { expandRecipients, splitRecipients, isAddressToken, extractAddress, } from "./groups.js";
+export type { GroupMap, RecipientToken, ExpansionResult } from "./groups.js";
 /** Supported authentication methods */
 export type AuthMethod = "password" | "oauth2";
 /** Mail account configuration */

package/index.js

@@ -3,6 +3,15 @@
  * Shared type definitions for the mailx email client.
  * This is the contract between client and server.
  */
+// Generated rule data — both desktop store and Android store import via
+// this barrel so a single source-of-truth (contact-rules.jsonc) drives
+// junk-contact filtering on every platform.
+export { CONTACT_RULES } from "./contact-rules.js";
+// Group-name expansion for recipient fields. Lets users type a group name
+// (e.g. "family") in To/Cc/Bcc and have it expand to the address list at
+// send time. Both desktop and Android send paths consume this expander
+// against contacts.jsonc → groups.
+export { expandRecipients, splitRecipients, isAddressToken, extractAddress, } from "./groups.js";
 // ── Shared Utilities ──
 // Pure functions used by both desktop (mailx-service) and Android (web-service).
 // Kept here to avoid duplication — both platforms import from mailx-types.

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@bobfrankston/mailx-types",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
   "scripts": {
+    "prebuild": "node build-rules.js",
     "build": "tsc",
     "release": "npmglobalize"
   },
@@ -12,5 +13,8 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/BobFrankston/mailx-types.git"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }