@bobfrankston/rmfmail 1.0.545 → 1.0.548

package/packages/mailx-service/index.ts

@@ -12,6 +12,10 @@ import { MailxDB } from "@bobfrankston/mailx-store";
 const __dirname = import.meta.dirname;
 import { ImapManager } from "@bobfrankston/mailx-imap";
 import * as gsync from "./google-sync.js";
+import { sniffAndFixCharset } from "./charset.js";
+import { LocalStore } from "./local-store.js";
+import { SyncQueue } from "./sync-queue.js";
+import { Reconciler } from "./reconciler.js";
 import { loadSettings, saveSettings, loadAccounts, loadAccountsAsync, saveAccounts, initCloudConfig, loadAllowlist, saveAllowlist, loadAutocomplete, saveAutocomplete, loadKeys, saveKeys, ensureKeysSectionExists, getStorePath, getStorageInfo, getConfigDir } from "@bobfrankston/mailx-settings";
 import type { AccountConfig, Folder, AutocompleteRequest, AutocompleteResponse, AutocompleteSettings, AiTransformRequest, AiTransformResponse, ExtractedEvent } from "@bobfrankston/mailx-types";
 import { sanitizeHtml, encodeQuotedPrintable, htmlToPlainText } from "@bobfrankston/mailx-types";
@@ -27,71 +31,11 @@ import { simpleParser } from "mailparser";
  *  Operates byte-wise so MIME boundaries / base64 / etc. are preserved.
  *  The `utf-8` validity test rejects 0xC0–0xC1 / 0xF5–0xFF and continuation
  *  bytes out of place, which would be common in genuine Latin-1 text. */
-function sniffAndFixCharset(raw: Buffer): Buffer {
-    const HEAD_LIMIT = 16384;
-    const head = raw.subarray(0, Math.min(HEAD_LIMIT, raw.length)).toString("latin1");
-    const re = /charset\s*=\s*"?(iso-8859-1|us-ascii|windows-1252|latin1)"?/gi;
-    if (!re.test(head)) return raw;
-    if (!isValidUtf8(raw)) return raw;
-    const fixed = head.replace(/charset\s*=\s*"?(iso-8859-1|us-ascii|windows-1252|latin1)"?/gi, "charset=utf-8");
-    return Buffer.concat([Buffer.from(fixed, "latin1"), raw.subarray(head.length)]);
-}
-
-/** Strict UTF-8 validity check: rejects overlong forms, invalid start
- *  bytes, and dangling continuations. Used to confirm the body is really
- *  UTF-8 before overriding a Latin-1 declaration. */
-function isValidUtf8(buf: Buffer): boolean {
-    let i = 0;
-    while (i < buf.length) {
-        const b = buf[i];
-        if (b < 0x80) { i++; continue; }
-        let need: number;
-        if ((b & 0xE0) === 0xC0) { if (b < 0xC2) return false; need = 1; }
-        else if ((b & 0xF0) === 0xE0) need = 2;
-        else if ((b & 0xF8) === 0xF0) { if (b > 0xF4) return false; need = 3; }
-        else return false;
-        if (i + need >= buf.length) return false;
-        for (let k = 1; k <= need; k++) {
-            if ((buf[i + k] & 0xC0) !== 0x80) return false;
-        }
-        i += need + 1;
-    }
-    return true;
-}
-
-/** 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;
+// sniffAndFixCharset moved to ./charset.ts so LocalStore can use it
+// without creating a circular dep with index.ts.
 
-    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 };
-}
+// parseListUnsubscribe moved to ./local-store.ts (only consumer is the
+// body-read path, which is now part of LocalStore).
 
 // ── Email provider detection (MX-based) ──
 
@@ -177,10 +121,28 @@ export class MailxService {
      *  showReminderPopup returns a "no host" reason. */
     setPopupFn(fn: PopupFn): void { this.popupFn = fn; }
 
+    /** Local-first read/write facade. Every UI IPC handler that touches the
+     *  local DB or body store goes through this — no awaiting IMAP, no
+     *  awaiting Gmail API, no awaiting SMTP. See docs/local-first-plan.md. */
+    private localStore: LocalStore;
+
+    /** Persistent (and in-memory body-fetch) queue. UI handlers commit
+     *  locally, then enqueue a server-mirror task here. */
+    private syncQueue: SyncQueue;
+
+    /** Background loop: drains body-fetch tasks, retries failed message
+     *  actions, emits sync-state events for the status pill. */
+    private reconciler: Reconciler;
+
     constructor(
         private db: MailxDB,
         private imapManager: ImapManager,
     ) {
+        this.localStore = new LocalStore(db, imapManager.getBodyStore());
+        this.syncQueue = new SyncQueue(db, imapManager);
+        this.reconciler = new Reconciler(db, imapManager, this.syncQueue);
+        this.reconciler.start();
+
         // Invalidate account cache when accounts.jsonc changes on disk or GDrive.
         this.imapManager.on?.("configChanged", (filename: string) => {
             if (filename === "accounts.jsonc") this._accountsCache = null;
@@ -412,204 +374,54 @@ export class MailxService {
     // ── Messages ──
 
     getUnifiedInbox(page = 1, pageSize = 50): any {
-        return this.db.getUnifiedInbox(page, pageSize);
+        return this.localStore.getUnifiedInbox(page, pageSize);
     }
 
     getMessages(accountId: string, folderId: number, page = 1, pageSize = 50, sort = "date", sortDir = "desc", search?: string, flaggedOnly = false): any {
-        return this.db.getMessages({ accountId, folderId, page, pageSize, sort: sort as any, sortDir: sortDir as any, search, flaggedOnly });
+        return this.localStore.getMessages({ accountId, folderId, page, pageSize, sort: sort as any, sortDir: sortDir as any, search, flaggedOnly });
     }
 
+    /** UI body read — local-first. Returns immediately from the local cache:
+     *  `cached: true` with the full parsed body when on disk, or `cached: false`
+     *  with envelope-only when not. In the cache-miss case we kick off a
+     *  fire-and-forget IMAP fetch in the background and emit `bodyAvailable`
+     *  when the body lands; the UI listens for that event and re-requests.
+     *
+     *  No `await imap*` in the click → render path. The 60s body-fetch race
+     *  and structured `bodyError` shape that lived here previously are gone —
+     *  step 1 of the local-first refactor (docs/local-first-plan.md). */
     async getMessage(accountId: string, uid: number, allowRemote = false, folderId?: number): Promise<any> {
-        const envelope = this.db.getMessageByUid(accountId, uid, folderId);
-        if (!envelope) throw new Error("Message not found");
-
-        let bodyHtml = "";
-        let bodyText = "";
-        let hasRemoteContent = false;
-        let attachments: { id: number; filename: string; mimeType: string; size: number; contentId: string }[] = [];
-
-        // The per-account ops queue inside ImapManager has its own per-task
-        // timeout that destroys a wedged client and unblocks the queue. This
-        // outer race is a safety net only — the underlying timeout in
-        // withConnection should trigger first.
-        const BODY_FETCH_TIMEOUT_MS = 60_000;
-        let raw: Buffer | null = null;
-        try {
-            raw = await Promise.race([
-                this.imapManager.fetchMessageBody(accountId, envelope.folderId, envelope.uid),
-                new Promise<never>((_, reject) =>
-                    setTimeout(() => reject(new Error("body fetch timed out — try again")), BODY_FETCH_TIMEOUT_MS)
-                ),
-            ]);
-        } catch (fetchErr: any) {
-            // Message was deleted from the server (another device, expunge, etc.) —
-            // drop the stale local row so the UI removes it instead of showing a
-            // confusing error. Throwing a tagged error lets the client react.
-            if ((fetchErr as any)?.isNotFound) {
-                try {
-                    this.db.deleteMessage(accountId, envelope.uid);
-                    this.db.recalcFolderCounts(envelope.folderId);
-                } catch { /* ignore */ }
-                const err = new Error("Message was deleted from the server");
-                (err as any).isNotFound = true;
-                throw err;
-            }
-            // Don't stuff the error text into bodyText — it bleeds into the
-            // viewer's main content area. Surface as a structured error field
-            // so the UI can render a banner with retry UX above the (empty)
-            // body. The caller keeps the envelope so the header still shows.
-            const rawErr = fetchErr.message || "connection failed";
-            const isTransient = /connection|Too many|UNAVAILABLE|rate|429|5\d\d|timeout|ENOTFOUND|ECONNRESET|ETIMEDOUT/i.test(rawErr);
-            return {
-                ...envelope, bodyHtml: "", bodyText: "",
-                bodyError: rawErr,
-                bodyErrorTransient: isTransient,
-                hasRemoteContent: false, remoteAllowed: false, attachments: [], emlPath: "", deliveredTo: "", returnPath: "", listUnsubscribe: ""
-            };
-        }
-
-        if (!raw) {
-            // Same treatment as the thrown-error case: structured field, not body text.
-            return {
-                ...envelope, bodyHtml: "", bodyText: "",
-                bodyError: "Message body not cached locally and the server fetch returned nothing.",
-                bodyErrorTransient: true,
-                hasRemoteContent: false, remoteAllowed: false, attachments: [], emlPath: "", deliveredTo: "", returnPath: "", listUnsubscribe: ""
-            };
-        } else {
-            // Many senders (esp. PHPMailer-driven marketing) declare
-            // `charset=iso-8859-1` but emit UTF-8 bytes. simpleParser
-            // honors the declared charset and produces "â??" garbage for
-            // every non-ASCII codepoint (em-dash, smart quotes, …). If
-            // the raw body bytes are valid UTF-8, rewrite the charset
-            // header before parsing. We only override the obviously-
-            // wrong legacy declarations; explicit utf-8 / koi8 / etc.
-            // pass through.
-            const adjusted = sniffAndFixCharset(raw);
-            const parsed = await simpleParser(adjusted);
-            bodyHtml = parsed.html || "";
-            bodyText = parsed.text || "";
-            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 || ""
-            }));
-        }
-
-        // Sanitize HTML
-        if (bodyHtml && !allowRemote) {
-            const allowList = loadAllowlist();
-            const senderAddr = envelope.from?.address || "";
-            const senderDomain = senderAddr.split("@")[1] || "";
-            const toAddrs = (envelope.to || []).map((a: any) => a.address);
-            const isAllowed = allowList.senders.includes(senderAddr) ||
-                allowList.domains.includes(senderDomain) ||
-                toAddrs.some((a: string) => allowList.recipients?.includes(a));
-
-            if (isAllowed) {
-                allowRemote = true;
-            } else {
-                const result = sanitizeHtml(bodyHtml);
-                bodyHtml = result.html;
-                hasRemoteContent = result.hasRemoteContent;
-            }
-        }
-
-        // Extract headers
-        let deliveredTo = "";
-        let returnPath = "";
-        let listUnsubscribe = "";
-        let listUnsubscribeMail = "";
-        let listUnsubscribeHttp = "";
-        let listUnsubscribeOneClick = false;
-        if (raw) {
-            const parsed2 = await simpleParser(raw);
-            const hdr = (key: string): string => {
-                let v = parsed2.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 msgSettings = loadSettings();
-            const acctConfig = msgSettings.accounts.find((a: any) => a.id === accountId);
-            const relayDomains: string[] = acctConfig?.relayDomains || [];
-            const prefixes: string[] = acctConfig?.deliveredToPrefix || [];
-            const rawDelivered = parsed2.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;
-                        }
-                    }
-                }
-            }
-            returnPath = hdr("return-path").replace(/[<>]/g, "");
-            ({ listUnsubscribeMail, listUnsubscribeHttp, listUnsubscribeOneClick } =
-                parseListUnsubscribe(parsed2.headers));
-            listUnsubscribe = listUnsubscribeHttp || listUnsubscribeMail;
-        }
-
-        // EML path: re-read the row after the fetch — `fetchMessageBody`
-        // writes the body to disk and updates `body_path` on success, but the
-        // `envelope` snapshot above pre-dates that write, so trusting it
-        // hides the Source button on every just-opened message.
-        const refreshed: any = this.db.getMessageByUid(accountId, uid, folderId);
-        const emlPath = refreshed?.bodyPath || envelope.bodyPath || "";
-
-        // Flag check — surfaced in the remote-content banner as a red
-        // warning when the sender's address or domain is on the user's
-        // flagged list. Cheap lookup; loadAllowlist is already cached.
-        const allowList = loadAllowlist() as any;
-        const senderAddr = (envelope.from?.address || "").toLowerCase();
-        const senderDomain = senderAddr.split("@")[1] || "";
-        const isFlagged = !!(
-            (allowList.flaggedSenders || []).some((s: string) => (s || "").toLowerCase() === senderAddr) ||
-            (allowList.flaggedDomains || []).some((d: string) => (d || "").toLowerCase() === senderDomain)
-        );
-
-        // External reputation check — Spamhaus DBL + SURBL + URIBL in parallel.
-        // Off by default (privacy: the domain leaks to those DNSBLs and the
-        // user's local resolver). User opts in via Settings → "Check sender
-        // reputation". Each lookup is bounded at 500 ms; the whole check is
-        // bounded by the slowest, ~500 ms worst case.
+        const local = await this.localStore.getMessage(accountId, uid, allowRemote, folderId);
+        if (!local) throw new Error("Message not found");
+
+        if (!local.cached) {
+            // Body not on disk. Enqueue an interactive-lane fetch — the
+            // reconciler picks it up, emits `bodyAvailable` on success or
+            // `bodyFetchError` on failure. Return envelope-only; UI shows
+            // a placeholder and re-renders on the event.
+            this.syncQueue.enqueueBodyFetch(accountId, local.folderId as any, local.uid as any, "interactive");
+            this.reconciler.kick();
+            return local;
+        }
+
+        // Optional sender-reputation check. This is the one residual server
+        // touch in the read path (DNSBL lookup, ~500 ms). Opt-in via Settings;
+        // moves to the reconciler in step 4. See feedback_no_bandaids.md.
         let reputation: ReputationResult | null = null;
         const settings = (loadSettings() as any) || {};
-        if (settings.checkDomainReputation && senderDomain && hasRemoteContent) {
+        const senderDomain = (local.from?.address || "").toLowerCase().split("@")[1] || "";
+        if (settings.checkDomainReputation && senderDomain && local.hasRemoteContent) {
             reputation = await this.checkDomainReputation(senderDomain);
         }
 
-        return {
-            ...envelope, bodyHtml, bodyText, hasRemoteContent, remoteAllowed: allowRemote,
-            attachments, emlPath, deliveredTo, returnPath,
-            listUnsubscribe, listUnsubscribeMail, listUnsubscribeHttp, listUnsubscribeOneClick,
-            isFlagged,
-            reputation,
-        };
+        return { ...local, reputation };
+    }
+
+    /** Diagnostic accessor — exposed for the sync-status pill / debug UI.
+     *  Returns the current queue counts so the UI can render
+     *  "Sync OK / Syncing N items" without polling per-account state. */
+    getSyncStatus(): { messageActions: number; bodyFetches: number } {
+        return this.syncQueue.pendingCount();
     }
 
     /** RFC 8058 one-click unsubscribe: POST `List-Unsubscribe=One-Click` to the
@@ -1085,9 +897,9 @@ export class MailxService {
             const sliced = items.slice((page - 1) * pageSize, page * pageSize);
             return { items: sliced, total, page, pageSize };
         } else if (scope === "current" && accountId && folderId) {
-            return this.db.searchMessages(q, page, pageSize, accountId, folderId);
+            return this.localStore.searchMessages(q, page, pageSize, accountId, folderId);
         } else {
-            return this.db.searchMessages(q, page, pageSize);
+            return this.localStore.searchMessages(q, page, pageSize);
         }
     }
 
@@ -1248,7 +1060,7 @@ export class MailxService {
                     .catch(e => this.handleGoogleRefreshError("calendar", e));
             }
         }
-        return this.db.getCalendarEvents(acctId, fromMs, toMs);
+        return this.localStore.getCalendarEvents(acctId, fromMs, toMs);
     }
 
     /** Returns true if the feature is currently in a quota-exceeded cooldown. */
@@ -1405,7 +1217,7 @@ export class MailxService {
                     .catch(e => this.handleGoogleRefreshError("tasks", e));
             }
         }
-        return this.db.getTasks(acctId, includeCompleted);
+        return this.localStore.getTasks(acctId, includeCompleted);
     }
 
     private async refreshTasks(accountId: string, includeCompleted: boolean): Promise<boolean> {
@@ -2056,8 +1868,22 @@ export class MailxService {
     async getAttachment(accountId: string, uid: number, attachmentId: number, folderId?: number): Promise<{ content: Buffer; contentType: string; filename: string }> {
         const envelope = this.db.getMessageByUid(accountId, uid, folderId);
         if (!envelope) throw new Error("Message not found");
-        const raw = await this.imapManager.fetchMessageBody(accountId, envelope.folderId, envelope.uid);
+
+        // Prefer the on-disk body — when the user just opened the message,
+        // LocalStore.getMessage either returned cached:true (body already on
+        // disk) or kicked a background fetch that wrote it. Either way a
+        // re-fetch here would be wasted IMAP work and risks racing.
+        const bodyStore = this.imapManager.getBodyStore();
+        let raw: Buffer | null = null;
+        const storedPath = envelope.bodyPath || this.db.getMessageBodyPath(accountId, uid) || "";
+        if (storedPath && await bodyStore.hasByPath(storedPath)) {
+            try { raw = await bodyStore.readByPath(storedPath); } catch { raw = null; }
+        }
+        if (!raw) {
+            raw = await this.imapManager.fetchMessageBody(accountId, envelope.folderId, envelope.uid);
+        }
         if (!raw) throw new Error("Message body not available");
+
         const parsed = await simpleParser(raw);
         const att = parsed.attachments?.[attachmentId];
         if (!att) throw new Error("Attachment not found");
@@ -2123,14 +1949,10 @@ export class MailxService {
             }
         } catch { /* non-fatal — draft stays in memory at least */ }
 
-        // Background reconcile to server Drafts folder. Fire-and-forget —
-        // the ACK to the client is already on its way.
-        this.imapManager.saveDraft(accountId, raw, previousDraftUid, id).catch((e: any) => {
-            console.error(`  [draft] background IMAP save failed for ${id}: ${e?.message || e}`);
-            // Surface as an event so the UI can show a status-bar hint without
-            // blocking the caller. Draft is preserved on disk regardless.
-            (this as any).emit?.("draftSaveDeferred", { accountId, draftId: id, error: String(e?.message || e) });
-        });
+        // Background reconcile to server Drafts folder via the SyncQueue
+        // seam. Fire-and-forget; deferred failures surface as a `draftSaveDeferred`
+        // event the UI can render in the status bar.
+        this.syncQueue.enqueueDraftPush(accountId, raw, previousDraftUid, id);
 
         return { draftUid: null, draftId: id };
     }
@@ -2144,7 +1966,7 @@ export class MailxService {
     searchContacts(query: string): any[] {
         query = (query || "").trim();
         if (query.length < 1) return [];
-        return this.db.searchContacts(query);
+        return this.localStore.searchContacts(query);
     }
 
     /** Q49: boolean hint for compose to auto-expand Cc when replying to this
@@ -2181,7 +2003,7 @@ export class MailxService {
 
     /** Address-book listing — paginated, filterable. */
     listContacts(query: string, page = 1, pageSize = 100): any {
-        return this.db.listContacts(query || "", page, pageSize);
+        return this.localStore.listContacts(query || "", page, pageSize);
     }
 
     /** Upsert a contact from the address book UI (edit name). Two-way cache:

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

@@ -0,0 +1,86 @@
+/**
+ * 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 type { MailxDB, FileMessageStore } from "@bobfrankston/mailx-store";
+import type { MessageEnvelope, MessageQuery, PagedResult } from "@bobfrankston/mailx-types";
+/** 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;
+    deliveredTo: string;
+    returnPath: string;
+    listUnsubscribe: string;
+    listUnsubscribeMail: string;
+    listUnsubscribeHttp: string;
+    listUnsubscribeOneClick: boolean;
+    emlPath: string;
+    isFlagged: boolean;
+}
+export declare class LocalStore {
+    private db;
+    private bodyStore;
+    constructor(db: MailxDB, bodyStore: FileMessageStore);
+    /** 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;
+    }[];
+    getFolders(accountId: string): any[];
+    /** 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;
+    /** Paginated message list for a (account, folder, ...) query. */
+    getMessages(query: MessageQuery): PagedResult<MessageEnvelope>;
+    /** All-Inboxes view: union of every account's INBOX, paginated. */
+    getUnifiedInbox(page?: number, pageSize?: number): PagedResult<MessageEnvelope>;
+    /** Local FTS5 search. Server-scope search is the reconciler's job. */
+    searchMessages(query: string, page?: number, pageSize?: number, accountId?: string, folderId?: number): PagedResult<MessageEnvelope>;
+    /** 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. */
+    getMessage(accountId: string, uid: number, allowRemote: boolean, folderId?: number): Promise<LocalMessage | null>;
+    getCalendarEvents(accountId: string, fromMs: number, toMs: number): any[];
+    getTasks(accountId: string, includeCompleted?: boolean): any[];
+    searchContacts(query: string, limit?: number): any[];
+    listContacts(query: string, page?: number, pageSize?: number): any;
+}
+//# sourceMappingURL=local-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"local-store.d.ts","sourceRoot":"","sources":["local-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,KAAK,EACR,eAAe,EAAW,YAAY,EAAE,WAAW,EACtD,MAAM,2BAA2B,CAAC;AAuCnC;;;;mEAImE;AACnE,MAAM,WAAW,YAAa,SAAQ,eAAe;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,WAAW,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxG,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,uBAAuB,EAAE,OAAO,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACtB;AAED,qBAAa,UAAU;IAEf,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,SAAS;gBADT,EAAE,EAAE,OAAO,EACX,SAAS,EAAE,gBAAgB;IAMvC;;;6DAGyD;IACzD,WAAW,IAAI;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE;IAM9E,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,EAAE;IAMpC;;4CAEwC;IACxC,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAK7F,iEAAiE;IACjE,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,CAAC,eAAe,CAAC;IAI9D,mEAAmE;IACnE,eAAe,CAAC,IAAI,SAAI,EAAE,QAAQ,SAAK,GAAG,WAAW,CAAC,eAAe,CAAC;IAItE,sEAAsE;IACtE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,SAAI,EAAE,QAAQ,SAAK,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,eAAe,CAAC;IAM3H;;;;;;;sEAOkE;IAC5D,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAmJvH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,EAAE;IAIzE,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,gBAAgB,UAAQ,GAAG,GAAG,EAAE;IAI5D,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,GAAG,EAAE;IAIhD,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,SAAI,EAAE,QAAQ,SAAM,GAAG,GAAG;CAK7D"}