@bobfrankston/rmfmail 1.0.544 → 1.0.546

package/packages/mailx-service/local-store.js

@@ -0,0 +1,159 @@
+/**
+ * LocalStore — the formal API surface for UI-bound reads and writes.
+ *
+ * Contract: every method here is local-only. No IMAP, no Gmail API, no
+ * SMTP, no DNS, no Drive API. Methods complete in microseconds (DB reads)
+ * or whatever a single local file IO takes (body reads). They never await
+ * network calls.
+ *
+ * UI-side IPC dispatch lands here. The reconciler / sync queue is a
+ * separate concern — it owns network IO and signals completed work via
+ * events that the UI listens for. The two never call each other directly.
+ *
+ * This file is part of the local-first refactor (docs/local-first-plan.md).
+ * Step 1 of that plan: introduce the facade, prove it compiles, route
+ * one IPC method through it as proof-of-pattern. Subsequent steps migrate
+ * remaining call sites and remove the server-fetch path from the UI.
+ */
+import { simpleParser } from "mailparser";
+import { sanitizeHtml } from "@bobfrankston/mailx-types";
+import { sniffAndFixCharset } from "./charset.js";
+export class LocalStore {
+    db;
+    bodyStore;
+    constructor(db, bodyStore) {
+        this.db = db;
+        this.bodyStore = bodyStore;
+    }
+    // ── Account list (read-only here; mutations go through MailxService
+    //    until the cloud-write path is part of the queue too) ──
+    /** DB-shape account list (id/name/email/lastSync). The richer
+     *  AccountConfig (with imap/smtp/etc.) lives in accounts.jsonc and is
+     *  loaded by mailx-settings, not the DB — that path stays in
+     *  MailxService until step 3 of the local-first plan. */
+    getAccounts() {
+        return this.db.getAccounts();
+    }
+    // ── Folders ──
+    getFolders(accountId) {
+        return this.db.getFolders(accountId);
+    }
+    // ── Message envelopes ──
+    /** Single envelope by (account, uid, folder). Null when the row isn't
+     *  in the DB — caller decides whether to show "deleted" or queue a
+     *  server lookup via the reconciler. */
+    getMessageEnvelope(accountId, uid, folderId) {
+        const env = this.db.getMessageByUid(accountId, uid, folderId);
+        return env || null;
+    }
+    /** Paginated message list for a (account, folder, ...) query. */
+    getMessages(query) {
+        return this.db.getMessages(query);
+    }
+    /** All-Inboxes view: union of every account's INBOX, paginated. */
+    getUnifiedInbox(page = 1, pageSize = 50) {
+        return this.db.getUnifiedInbox(page, pageSize);
+    }
+    /** Local FTS5 search. Server-scope search is the reconciler's job. */
+    searchMessages(query, page = 1, pageSize = 50, accountId, folderId) {
+        return this.db.searchMessages(query, page, pageSize, accountId, folderId);
+    }
+    // ── Message body (read-from-disk only) ──
+    /** Read a fully-parsed message (envelope + body + attachments) entirely
+     *  from local state. Returns null when the envelope isn't known.
+     *  Returns `{ ...envelope, cached: false }` when the envelope is known
+     *  but the body file isn't on disk — UI shows a placeholder and the
+     *  reconciler queues the fetch.
+     *
+     *  `allowRemote=true` skips HTML sanitization. Used when the user has
+     *  explicitly allowed remote content for this sender / domain. */
+    async getMessage(accountId, uid, allowRemote, folderId) {
+        const envelope = this.db.getMessageByUid(accountId, uid, folderId);
+        if (!envelope)
+            return null;
+        // Resolve body path: prefer the row's own bodyPath, fall back to
+        // the historical lookup. Either may be empty (body never fetched).
+        let storedPath = envelope.bodyPath || "";
+        if (!storedPath)
+            storedPath = this.db.getMessageBodyPath(accountId, uid) || "";
+        const empty = {
+            ...envelope,
+            bodyHtml: "", bodyText: "",
+            hasRemoteContent: false, remoteAllowed: false,
+            attachments: [],
+            cached: false,
+            deliveredTo: "", returnPath: "", listUnsubscribe: "",
+        };
+        if (!storedPath)
+            return empty;
+        if (!await this.bodyStore.hasByPath(storedPath))
+            return empty;
+        let raw;
+        try {
+            raw = await this.bodyStore.readByPath(storedPath);
+        }
+        catch {
+            // File path is in DB but the file is missing — the prefetch
+            // dot is lying. Caller (UI) should mark the row as broken and
+            // the reconciler should re-fetch. Don't crash; return as if
+            // not cached.
+            return empty;
+        }
+        // Parse + sanitize. Same logic as today's MailxService.getMessage,
+        // but executed only when the body is local — never on a fresh
+        // server fetch.
+        const adjusted = sniffAndFixCharset(raw);
+        const parsed = await simpleParser(adjusted);
+        let bodyHtml = parsed.html || "";
+        const bodyText = parsed.text || "";
+        let hasRemoteContent = false;
+        let remoteAllowed = allowRemote;
+        const attachments = (parsed.attachments || []).map((a, i) => ({
+            id: i,
+            filename: a.filename || `attachment-${i}`,
+            mimeType: a.contentType || "application/octet-stream",
+            size: a.size || 0,
+            contentId: a.contentId || "",
+        }));
+        if (bodyHtml && !allowRemote) {
+            const result = sanitizeHtml(bodyHtml);
+            bodyHtml = result.html;
+            hasRemoteContent = result.hasRemoteContent;
+        }
+        // Header extraction — Delivered-To, Return-Path, List-Unsubscribe
+        // and friends. simpleParser exposes them via `headers`.
+        const hdr = (key) => {
+            const v = parsed.headers.get(key);
+            if (!v)
+                return "";
+            if (typeof v === "string")
+                return v;
+            return String(v?.value || "");
+        };
+        const deliveredTo = hdr("delivered-to");
+        const returnPath = hdr("return-path");
+        const listUnsubscribe = hdr("list-unsubscribe");
+        return {
+            ...envelope,
+            bodyHtml, bodyText,
+            hasRemoteContent, remoteAllowed,
+            attachments,
+            cached: true,
+            deliveredTo, returnPath, listUnsubscribe,
+        };
+    }
+    // ── Calendar / tasks / contacts (read paths) ──
+    getCalendarEvents(accountId, fromMs, toMs) {
+        return this.db.getCalendarEvents(accountId, fromMs, toMs);
+    }
+    getTasks(accountId, includeCompleted = false) {
+        return this.db.getTasks(accountId, includeCompleted);
+    }
+    searchContacts(query, limit = 10) {
+        return this.db.searchContacts(query, limit);
+    }
+    listContacts(query, page = 1, pageSize = 100) {
+        return this.db.listContacts(query, page, pageSize);
+    }
+}
+//# sourceMappingURL=local-store.js.map

package/packages/mailx-service/local-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-store.js","sourceRoot":"","sources":["local-store.ts"],"names":[],"mappings":"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"}

package/packages/mailx-service/local-store.ts

@@ -0,0 +1,307 @@
+/**
+ * LocalStore — the formal API surface for UI-bound reads and writes.
+ *
+ * Contract: every method here is local-only. No IMAP, no Gmail API, no
+ * SMTP, no DNS, no Drive API. Methods complete in microseconds (DB reads)
+ * or whatever a single local file IO takes (body reads). They never await
+ * network calls.
+ *
+ * UI-side IPC dispatch lands here. The reconciler / sync queue is a
+ * separate concern — it owns network IO and signals completed work via
+ * events that the UI listens for. The two never call each other directly.
+ *
+ * This file is part of the local-first refactor (docs/local-first-plan.md).
+ * Step 1 of that plan: introduce the facade, prove it compiles, route
+ * one IPC method through it as proof-of-pattern. Subsequent steps migrate
+ * remaining call sites and remove the server-fetch path from the UI.
+ */
+
+import * as fs from "node:fs";
+import { simpleParser } from "mailparser";
+import type { MailxDB, FileMessageStore } from "@bobfrankston/mailx-store";
+import type {
+    MessageEnvelope, Message, MessageQuery, PagedResult,
+} from "@bobfrankston/mailx-types";
+import { sanitizeHtml } from "@bobfrankston/mailx-types";
+import { loadSettings, loadAllowlist } from "@bobfrankston/mailx-settings";
+import { sniffAndFixCharset } from "./charset.js";
+
+/** Parse `List-Unsubscribe` (RFC 2369) and `List-Unsubscribe-Post` (RFC 8058).
+ *  mailparser only exposes ONE of mail/url even when both are present, so we
+ *  also scan the raw header text for the full set of angle-bracketed URIs. */
+function parseListUnsubscribe(headers: any): { listUnsubscribeMail: string; listUnsubscribeHttp: string; listUnsubscribeOneClick: boolean } {
+    let mail = "";
+    let http = "";
+    let oneClick = false;
+
+    const raw = headers.get("list-unsubscribe");
+    const rawStr = typeof raw === "string" ? raw : (raw && typeof (raw as any).text === "string" ? (raw as any).text : "");
+    if (rawStr) {
+        const matches = rawStr.match(/<([^>]+)>/g) || [];
+        for (const m of matches) {
+            const url = m.slice(1, -1).trim();
+            if (!mail && /^mailto:/i.test(url)) mail = url;
+            else if (!http && /^https?:/i.test(url)) http = url;
+        }
+    }
+    if (!mail && !http) {
+        const listHeaders = headers.get("list");
+        if (listHeaders?.unsubscribe) {
+            const unsub = listHeaders.unsubscribe;
+            if (unsub.url) http = Array.isArray(unsub.url) ? unsub.url[0] : unsub.url;
+            if (unsub.mail) mail = `mailto:${Array.isArray(unsub.mail) ? unsub.mail[0] : unsub.mail}`;
+        }
+    }
+
+    const post = headers.get("list-unsubscribe-post");
+    const postStr = typeof post === "string" ? post : (post && typeof (post as any).text === "string" ? (post as any).text : "");
+    if (postStr && /one-?click/i.test(postStr)) oneClick = true;
+
+    return { listUnsubscribeMail: mail, listUnsubscribeHttp: http, listUnsubscribeOneClick: oneClick };
+}
+
+/** What the UI gets back from a body read. Mirrors the historical
+ *  `getMessage` shape so call-site migration is mechanical. `cached: false`
+ *  means the body isn't on disk yet — the UI shows a "downloading…"
+ *  placeholder and listens for `bodyAvailable` to re-render. The reconciler
+ *  is responsible for actually fetching and emitting the event. */
+export interface LocalMessage extends MessageEnvelope {
+    bodyHtml: string;
+    bodyText: string;
+    hasRemoteContent: boolean;
+    remoteAllowed: boolean;
+    attachments: Array<{ id: number; filename: string; mimeType: string; size: number; contentId: string }>;
+    cached: boolean;          // false = body not on disk; UI shows downloading
+    deliveredTo: string;
+    returnPath: string;
+    listUnsubscribe: string;
+    listUnsubscribeMail: string;
+    listUnsubscribeHttp: string;
+    listUnsubscribeOneClick: boolean;
+    emlPath: string;
+    isFlagged: boolean;
+}
+
+export class LocalStore {
+    constructor(
+        private db: MailxDB,
+        private bodyStore: FileMessageStore,
+    ) {}
+
+    // ── Account list (read-only here; mutations go through MailxService
+    //    until the cloud-write path is part of the queue too) ──
+
+    /** DB-shape account list (id/name/email/lastSync). The richer
+     *  AccountConfig (with imap/smtp/etc.) lives in accounts.jsonc and is
+     *  loaded by mailx-settings, not the DB — that path stays in
+     *  MailxService until step 3 of the local-first plan. */
+    getAccounts(): { id: string; name: string; email: string; lastSync: number }[] {
+        return this.db.getAccounts();
+    }
+
+    // ── Folders ──
+
+    getFolders(accountId: string): any[] {
+        return this.db.getFolders(accountId);
+    }
+
+    // ── Message envelopes ──
+
+    /** Single envelope by (account, uid, folder). Null when the row isn't
+     *  in the DB — caller decides whether to show "deleted" or queue a
+     *  server lookup via the reconciler. */
+    getMessageEnvelope(accountId: string, uid: number, folderId?: number): MessageEnvelope | null {
+        const env = this.db.getMessageByUid(accountId, uid, folderId);
+        return env || null;
+    }
+
+    /** Paginated message list for a (account, folder, ...) query. */
+    getMessages(query: MessageQuery): PagedResult<MessageEnvelope> {
+        return this.db.getMessages(query);
+    }
+
+    /** All-Inboxes view: union of every account's INBOX, paginated. */
+    getUnifiedInbox(page = 1, pageSize = 50): PagedResult<MessageEnvelope> {
+        return this.db.getUnifiedInbox(page, pageSize);
+    }
+
+    /** Local FTS5 search. Server-scope search is the reconciler's job. */
+    searchMessages(query: string, page = 1, pageSize = 50, accountId?: string, folderId?: number): PagedResult<MessageEnvelope> {
+        return this.db.searchMessages(query, page, pageSize, accountId, folderId);
+    }
+
+    // ── Message body (read-from-disk only) ──
+
+    /** Read a fully-parsed message (envelope + body + attachments) entirely
+     *  from local state. Returns null when the envelope isn't known.
+     *  Returns `{ ...envelope, cached: false }` when the envelope is known
+     *  but the body file isn't on disk — UI shows a placeholder and the
+     *  reconciler queues the fetch.
+     *
+     *  `allowRemote=true` skips HTML sanitization. Used when the user has
+     *  explicitly allowed remote content for this sender / domain. */
+    async getMessage(accountId: string, uid: number, allowRemote: boolean, folderId?: number): Promise<LocalMessage | null> {
+        const envelope: any = this.db.getMessageByUid(accountId, uid, folderId);
+        if (!envelope) return null;
+
+        const allowList = loadAllowlist() as any;
+        const senderAddr = (envelope.from?.address || "").toLowerCase();
+        const senderDomain = senderAddr.split("@")[1] || "";
+        const toAddrs = (envelope.to || []).map((a: any) => (a.address || "").toLowerCase());
+
+        // Allowlist auto-allow: trusted sender / domain / recipient skips
+        // sanitization. Same rule as the legacy service implementation.
+        if (!allowRemote) {
+            const senders = (allowList.senders || []).map((s: string) => (s || "").toLowerCase());
+            const domains = (allowList.domains || []).map((d: string) => (d || "").toLowerCase());
+            const recipients = (allowList.recipients || []).map((r: string) => (r || "").toLowerCase());
+            if (senders.includes(senderAddr) ||
+                domains.includes(senderDomain) ||
+                toAddrs.some((a: string) => recipients.includes(a))) {
+                allowRemote = true;
+            }
+        }
+
+        const isFlagged = !!(
+            (allowList.flaggedSenders || []).some((s: string) => (s || "").toLowerCase() === senderAddr) ||
+            (allowList.flaggedDomains || []).some((d: string) => (d || "").toLowerCase() === senderDomain)
+        );
+
+        // Resolve body path: prefer the row's own bodyPath, fall back to
+        // the historical lookup. Either may be empty (body never fetched).
+        let storedPath = envelope.bodyPath || "";
+        if (!storedPath) storedPath = this.db.getMessageBodyPath(accountId, uid) || "";
+
+        const empty: LocalMessage = {
+            ...envelope,
+            bodyHtml: "", bodyText: "",
+            hasRemoteContent: false, remoteAllowed: allowRemote,
+            attachments: [],
+            cached: false,
+            deliveredTo: "", returnPath: "",
+            listUnsubscribe: "", listUnsubscribeMail: "", listUnsubscribeHttp: "", listUnsubscribeOneClick: false,
+            emlPath: "",
+            isFlagged,
+        };
+
+        if (!storedPath) return empty;
+        if (!await this.bodyStore.hasByPath(storedPath)) return empty;
+
+        let raw: Buffer;
+        try {
+            raw = await this.bodyStore.readByPath(storedPath);
+        } catch {
+            // File path is in DB but the file is missing — the prefetch
+            // dot is lying. Caller (UI) should mark the row as broken and
+            // the reconciler should re-fetch. Don't crash; return as if
+            // not cached.
+            return empty;
+        }
+
+        // Parse + sanitize. Same logic as today's MailxService.getMessage,
+        // but executed only when the body is local — never on a fresh
+        // server fetch.
+        const adjusted = sniffAndFixCharset(raw);
+        const parsed = await simpleParser(adjusted);
+        let bodyHtml = parsed.html || "";
+        const bodyText = parsed.text || "";
+        let hasRemoteContent = false;
+        const attachments = (parsed.attachments || []).map((a, i) => ({
+            id: i,
+            filename: a.filename || `attachment-${i}`,
+            mimeType: a.contentType || "application/octet-stream",
+            size: a.size || 0,
+            contentId: a.contentId || "",
+        }));
+
+        if (bodyHtml && !allowRemote) {
+            const result = sanitizeHtml(bodyHtml);
+            bodyHtml = result.html;
+            hasRemoteContent = result.hasRemoteContent;
+        }
+
+        // Header extraction — Delivered-To with relay-domain unwrapping,
+        // Return-Path, List-Unsubscribe variants. The relay/prefix rules
+        // come from accounts.jsonc settings; cheap local read.
+        const settings = (loadSettings() as any) || {};
+        const acctConfig = (settings.accounts || []).find((a: any) => a.id === accountId) || {};
+        const relayDomains: string[] = acctConfig.relayDomains || [];
+        const prefixes: string[] = acctConfig.deliveredToPrefix || [];
+
+        let deliveredTo = "";
+        const rawDelivered = parsed.headers.get("delivered-to");
+        if (rawDelivered) {
+            const deliveredList = Array.isArray(rawDelivered) ? rawDelivered : [rawDelivered];
+            for (let i = deliveredList.length - 1; i >= 0; i--) {
+                const d = deliveredList[i];
+                const addr = typeof d === "string" ? d : (d as any)?.text || (d as any)?.address || String(d);
+                if (!relayDomains.some(rd => addr.includes(`@${rd}`))) {
+                    deliveredTo = addr;
+                    break;
+                }
+            }
+            if (!deliveredTo && deliveredList.length > 0) {
+                const d = deliveredList[deliveredList.length - 1];
+                deliveredTo = typeof d === "string" ? d : (d as any)?.text || (d as any)?.address || String(d);
+            }
+            if (deliveredTo && prefixes.length > 0) {
+                const [local, domain] = deliveredTo.split("@");
+                for (const prefix of prefixes) {
+                    if (local.startsWith(prefix)) {
+                        deliveredTo = `${local.slice(prefix.length)}@${domain}`;
+                        break;
+                    }
+                }
+            }
+        }
+
+        const hdr = (key: string): string => {
+            let v = parsed.headers.get(key);
+            if (!v) return "";
+            if (Array.isArray(v)) v = v[0];
+            if (typeof v === "string") return v;
+            if (typeof v === "object" && v !== null) {
+                if ("text" in v) return (v as any).text || "";
+                if ("value" in v) return String((v as any).value);
+                if ("address" in v) return (v as any).address || "";
+            }
+            return String(v);
+        };
+        const returnPath = hdr("return-path").replace(/[<>]/g, "");
+        const { listUnsubscribeMail, listUnsubscribeHttp, listUnsubscribeOneClick } =
+            parseListUnsubscribe(parsed.headers);
+        const listUnsubscribe = listUnsubscribeHttp || listUnsubscribeMail;
+
+        return {
+            ...envelope,
+            bodyHtml, bodyText,
+            hasRemoteContent, remoteAllowed: allowRemote,
+            attachments,
+            cached: true,
+            deliveredTo, returnPath,
+            listUnsubscribe, listUnsubscribeMail, listUnsubscribeHttp, listUnsubscribeOneClick,
+            emlPath: storedPath,
+            isFlagged,
+        };
+    }
+
+    // ── Calendar / tasks / contacts (read paths) ──
+
+    getCalendarEvents(accountId: string, fromMs: number, toMs: number): any[] {
+        return this.db.getCalendarEvents(accountId, fromMs, toMs);
+    }
+
+    getTasks(accountId: string, includeCompleted = false): any[] {
+        return this.db.getTasks(accountId, includeCompleted);
+    }
+
+    searchContacts(query: string, limit = 10): any[] {
+        return this.db.searchContacts(query, limit);
+    }
+
+    listContacts(query: string, page = 1, pageSize = 100): any {
+        return this.db.listContacts(query, page, pageSize);
+    }
+
+    // Write paths and sync-queue enqueue methods come in step 3.
+}