@bobfrankston/mailx-sync 0.1.3

package/README.md

@@ -0,0 +1,87 @@
+# @bobfrankston/mailx-sync
+
+Platform-agnostic mail provider implementations + sync orchestration interfaces. Single source of truth for protocol code consumed by both desktop (Node service) and Android (WebView).
+
+## Why this package exists
+
+Before this extraction, mailx maintained **parallel implementations** of the same Gmail provider in two places:
+
+- `mailx-imap/providers/gmail-api.ts` — used by the Node desktop service
+- `mailx-store-web/gmail-api-web.ts` — used by the Android WebView
+
+They drifted in practice. A 403-quota retry added to the desktop copy one day was missed in the web copy until users reported broken prefetch. Per `programming.md`'s **Economy of Mechanism** rule (the operational TS-spirit example), platform-forking the same protocol logic is a textbook violation: TypeScript's value is *one typed implementation imported everywhere it's needed*, not separate "Node" and "browser" copies of the same algorithm.
+
+## What's in here
+
+| Export | What it is |
+|---|---|
+| `MailProvider` (interface) | Protocol-agnostic provider contract — list folders, fetch messages, get UIDs, close. |
+| `ProviderFolder`, `ProviderMessage`, `FetchOptions` | Shared data shapes used at provider boundaries. |
+| `GmailApiProvider` | Gmail REST API. Bounded-concurrency batch fetch, 403-quota retry, exponential backoff. |
+| `ImapProvider` | Generic IMAP via `iflow-direct`'s `CompatImapClient`. Auto-reconnect on broken pipe. |
+| `OutlookApiProvider` | Microsoft Graph for Outlook.com / Office 365. Skeleton — needs Azure app reg for production. |
+| `SyncStorage`, `SyncBodyStore`, `SyncEventSink` (interfaces) | What sync orchestration needs from the host platform's database / file store / event bus. Used to keep `sync.ts` (planned) platform-free. |
+| `SyncFolder` | Storage-side folder shape. |
+
+## Platform requirements
+
+Pure TypeScript, no Node-specific imports. Runtime needs only:
+
+- `globalThis.fetch` — Node 18+ and all browsers/WebViews.
+- `atob`, `Uint8Array`, `TextDecoder` — universal.
+- A TCP byte-stream transport for `ImapProvider` (caller injects via `TransportFactory` — `NodeTcpTransport` on desktop, `BridgeTcpTransport` on Android).
+
+## How to instantiate
+
+**Desktop (Node service):**
+
+```ts
+import { GmailApiProvider, ImapProvider } from "@bobfrankston/mailx-sync";
+import { NodeTcpTransport } from "@bobfrankston/node-tcp-transport";
+
+const gmail = new GmailApiProvider(() => getGmailToken());
+
+const imap = new ImapProvider(
+    { server: "imap.example.com", port: 993, username: "u", password: "p" },
+    () => new NodeTcpTransport(),
+);
+```
+
+**Android (WebView Worker or main):**
+
+```ts
+import { GmailApiProvider, ImapProvider } from "@bobfrankston/mailx-sync";
+import { BridgeTcpTransport } from "@bobfrankston/tcp-transport";
+
+const gmail = new GmailApiProvider(() => getGmailToken());
+
+const imap = new ImapProvider(
+    { server: "imap.example.com", port: 993, username: "u", password: "p" },
+    () => new BridgeTcpTransport(),
+);
+```
+
+Identical API. The only platform-specific bit is the transport factory, which the package consumer injects.
+
+## Back-compat shims
+
+The earlier per-platform files now exist as thin re-exports so older import paths keep compiling:
+
+- `mailx-imap/providers/gmail-api.ts` re-exports `GmailApiProvider`.
+- `mailx-imap/providers/types.ts` re-exports the type interfaces.
+- `mailx-imap/providers/outlook-api.ts` re-exports `OutlookApiProvider`.
+- `mailx-store-web/gmail-api-web.ts` re-exports `GmailApiProvider as GmailApiWebProvider`.
+- `mailx-store-web/imap-web-provider.ts` re-exports `ImapProvider as ImapWebProvider`.
+- `mailx-store-web/provider-types.ts` re-exports the type interfaces.
+
+Don't extend these shims — extend `mailx-sync` itself.
+
+## Future work (in mailx's TODO.md)
+
+- Sync orchestration (`syncFolderViaApi`, `prefetchBodies`) extracted to `sync.ts` consuming the `SyncStorage`/`SyncBodyStore` interfaces. Eliminates the "android-bootstrap.ts has its own simpler syncFolder" duplication.
+- Storage adapters in mailx-store and mailx-store-web that satisfy `SyncStorage`.
+- Outbox claim logic shared (currently desktop-only).
+
+## License
+
+ISC

package/gmail.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Gmail API provider — replaces IMAP for Gmail accounts.
+ * Uses REST API for fast, reliable sync without connection limit issues.
+ *
+ * SOURCE OF TRUTH: this file is the single canonical Gmail provider for
+ * mailx. Both desktop (mailx-imap, Node) and Android (mailx-store-web,
+ * WebView) re-export from here. Earlier they had parallel copies that
+ * silently drifted (the 403-quota retry was added to desktop one day and
+ * missed in the web copy until a user reported broken prefetch).
+ *
+ * Platform requirements: globalThis.fetch (Node 18+ and all browsers/WebViews),
+ * atob, Uint8Array, TextDecoder. No Node-specific imports.
+ */
+import type { MailProvider, ProviderFolder, ProviderMessage, FetchOptions } from "./types.js";
+export declare class GmailApiProvider implements MailProvider {
+    private tokenProvider;
+    constructor(tokenProvider: () => Promise<string>);
+    private fetch;
+    listFolders(): Promise<ProviderFolder[]>;
+    /** List message IDs matching a query, handling pagination.
+     *  IMPORTANT: on any error we throw — do NOT return a partial list, because
+     *  callers use this for sync reconciliation and a short list would delete
+     *  real messages from the local DB. Returning [] silently caused the
+     *  "INBOX empty in mailx" bug when a rate-limit hit mid-pagination. */
+    private listMessageIds;
+    /** Batch-fetch message metadata or full content */
+    private batchFetch;
+    /** Parse a Gmail API message response into ProviderMessage */
+    private parseMessage;
+    fetchSince(folder: string, sinceUid: number, options?: FetchOptions): Promise<ProviderMessage[]>;
+    fetchByDate(folder: string, since: Date, before: Date, options?: FetchOptions, onChunk?: (msgs: ProviderMessage[]) => void): Promise<ProviderMessage[]>;
+    fetchByUids(folder: string, uids: number[], options?: FetchOptions): Promise<ProviderMessage[]>;
+    /** Bulk-fetch raw bodies for many UIDs in one "folder" (Gmail label).
+     *  Lists the label once, builds UID→ID map, then streams bodies through
+     *  `onBody` with bounded concurrency (lets Gmail's HTTP/2 stream multiplex;
+     *  `fetch()`'s built-in 429/5xx retry handles backoff automatically).
+     *
+     *  NOTE: Gmail's model is labels, not folders — a single message can be in
+     *  many labels. Treating each label as a folder causes duplicate fetches
+     *  across labels. Proper fix tracked as separate TODO ("Gmail label-native
+     *  model"). For now we mirror the IMAP folder grouping, accepting duplicate
+     *  fetches of multi-labeled messages. */
+    fetchBodiesBatch(folder: string, uids: number[], onBody: (uid: number, source: string) => void): Promise<void>;
+    fetchOne(folder: string, uid: number, options?: FetchOptions): Promise<ProviderMessage | null>;
+    getUids(folder: string): Promise<number[]>;
+    close(): Promise<void>;
+    /** Map folder path to Gmail label query term */
+    private folderToLabel;
+    /** Format date for Gmail query (YYYY/MM/DD) */
+    private formatDate;
+}
+//# sourceMappingURL=gmail.d.ts.map

package/gmail.js

@@ -0,0 +1,367 @@
+/**
+ * Gmail API provider — replaces IMAP for Gmail accounts.
+ * Uses REST API for fast, reliable sync without connection limit issues.
+ *
+ * SOURCE OF TRUTH: this file is the single canonical Gmail provider for
+ * mailx. Both desktop (mailx-imap, Node) and Android (mailx-store-web,
+ * WebView) re-export from here. Earlier they had parallel copies that
+ * silently drifted (the 403-quota retry was added to desktop one day and
+ * missed in the web copy until a user reported broken prefetch).
+ *
+ * Platform requirements: globalThis.fetch (Node 18+ and all browsers/WebViews),
+ * atob, Uint8Array, TextDecoder. No Node-specific imports.
+ */
+const API = "https://gmail.googleapis.com/gmail/v1/users/me";
+/** Convert Gmail hex ID to integer UID (lower 48 bits — deterministic, stable) */
+function idToUid(id) {
+    const hex = id.length > 12 ? id.slice(-12) : id;
+    return parseInt(hex, 16);
+}
+/** Map Gmail label to IMAP-style specialUse */
+function labelSpecialUse(label) {
+    switch (label.id) {
+        case "INBOX": return "inbox";
+        case "SENT": return "sent";
+        case "DRAFT": return "drafts";
+        case "TRASH": return "trash";
+        case "SPAM": return "junk";
+        case "STARRED": return "";
+        case "IMPORTANT": return "";
+        default: return "";
+    }
+}
+/** Parse RFC 2822 headers from Gmail metadata payload */
+function getHeader(headers, name) {
+    return headers.find(h => h.name.toLowerCase() === name.toLowerCase())?.value || "";
+}
+/** Parse "Name <addr>" or "addr" into { name, address } */
+function parseAddress(raw) {
+    const match = raw.match(/^"?([^"<]*?)"?\s*<([^>]+)>/);
+    if (match)
+        return { name: match[1].trim(), address: match[2].trim() };
+    return { address: raw.trim() };
+}
+function parseAddressList(raw) {
+    if (!raw)
+        return [];
+    // Split on commas that aren't inside quotes
+    return raw.split(/,(?=(?:[^"]*"[^"]*")*[^"]*$)/).map(s => parseAddress(s.trim())).filter(a => a.address);
+}
+export class GmailApiProvider {
+    tokenProvider;
+    constructor(tokenProvider) {
+        this.tokenProvider = tokenProvider;
+    }
+    async fetch(path, options = {}) {
+        const token = await this.tokenProvider();
+        const maxAttempts = 6;
+        const baseDelayMs = 1000;
+        const maxDelayMs = 60_000;
+        let lastStatus = 0;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const res = await globalThis.fetch(`${API}${path}`, {
+                ...options,
+                headers: {
+                    "Authorization": `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                    ...options.headers,
+                },
+            });
+            // 403 with "Quota exceeded" body is Google's per-minute quota limit.
+            // Not 429. Retry like a rate-limit, don't throw as a permanent failure.
+            let isQuota403 = false;
+            if (res.status === 403) {
+                try {
+                    const cloned = res.clone();
+                    const body = await cloned.text();
+                    if (/quota exceeded|rate ?limit|user[-_ ]rate/i.test(body))
+                        isQuota403 = true;
+                }
+                catch { /* ignore */ }
+            }
+            if (res.status === 429 || res.status >= 500 || isQuota403) {
+                lastStatus = res.status;
+                // Honor Retry-After if present (seconds or HTTP-date)
+                const retryAfter = res.headers.get("Retry-After");
+                let delay = baseDelayMs * Math.pow(2, attempt);
+                if (retryAfter) {
+                    const asInt = parseInt(retryAfter, 10);
+                    if (!isNaN(asInt))
+                        delay = asInt * 1000;
+                    else {
+                        const when = Date.parse(retryAfter);
+                        if (!isNaN(when))
+                            delay = Math.max(0, when - Date.now());
+                    }
+                }
+                // Per-minute-quota 403 deserves a minimum 60s wait — the quota
+                // resets per minute, so shorter backoff just re-triggers.
+                if (isQuota403)
+                    delay = Math.max(delay, 60_000);
+                // Full jitter to avoid synchronized retries
+                delay = Math.min(maxDelayMs, delay);
+                delay = Math.floor(delay * (0.5 + Math.random() * 0.5));
+                console.log(`  [gmail] ${res.status}${isQuota403 ? " (per-minute quota)" : ""} (attempt ${attempt + 1}/${maxAttempts}), waiting ${(delay / 1000).toFixed(1)}s${retryAfter ? ` (Retry-After: ${retryAfter})` : ""}...`);
+                await new Promise(r => setTimeout(r, delay));
+                continue;
+            }
+            if (!res.ok) {
+                const err = await res.text().catch(() => "");
+                throw new Error(`Gmail API ${res.status}: ${err.substring(0, 200)}`);
+            }
+            return res.json();
+        }
+        throw new Error(`Gmail API: failed after ${maxAttempts} retries (last status ${lastStatus})`);
+    }
+    async listFolders() {
+        const data = await this.fetch("/labels");
+        const labels = data.labels || [];
+        const folders = [];
+        for (const label of labels) {
+            // Skip system labels that aren't useful as folders
+            if (["UNREAD", "STARRED", "IMPORTANT", "CATEGORY_PERSONAL",
+                "CATEGORY_SOCIAL", "CATEGORY_PROMOTIONS", "CATEGORY_UPDATES",
+                "CATEGORY_FORUMS", "CHAT"].includes(label.id))
+                continue;
+            const specialUse = labelSpecialUse(label);
+            // Map Gmail path separators (/) to IMAP-style
+            const path = label.name || label.id;
+            const name = path.includes("/") ? path.split("/").pop() : path;
+            folders.push({
+                path,
+                name,
+                delimiter: "/",
+                specialUse,
+                flags: label.type === "system" ? ["\\Noselect"] : [],
+            });
+        }
+        return folders;
+    }
+    /** List message IDs matching a query, handling pagination.
+     *  IMPORTANT: on any error we throw — do NOT return a partial list, because
+     *  callers use this for sync reconciliation and a short list would delete
+     *  real messages from the local DB. Returning [] silently caused the
+     *  "INBOX empty in mailx" bug when a rate-limit hit mid-pagination. */
+    async listMessageIds(query, maxResults = 500) {
+        const ids = [];
+        let pageToken = "";
+        let truncated = false;
+        while (true) {
+            const params = new URLSearchParams({ q: query, maxResults: String(Math.min(maxResults - ids.length, 500)) });
+            if (pageToken)
+                params.set("pageToken", pageToken);
+            const data = await this.fetch(`/messages?${params}`);
+            for (const msg of data.messages || []) {
+                ids.push(msg.id);
+            }
+            if (!data.nextPageToken)
+                break;
+            if (ids.length >= maxResults) {
+                // Hit the caller's cap but the server has more. Flag it so
+                // reconcile-style callers can refuse to treat this as complete.
+                truncated = true;
+                break;
+            }
+            pageToken = data.nextPageToken;
+        }
+        ids._truncated = truncated;
+        return ids;
+    }
+    /** Batch-fetch message metadata or full content */
+    async batchFetch(ids, options = {}, onChunk) {
+        const all = [];
+        const chunkSize = options.source ? 10 : 50; // Smaller chunks for full bodies
+        const format = options.source ? "raw" : "metadata";
+        for (let i = 0; i < ids.length; i += chunkSize) {
+            const chunk = ids.slice(i, i + chunkSize);
+            // Sequential fetches to avoid Gmail 429 rate limits
+            const messages = [];
+            for (const id of chunk) {
+                const params = new URLSearchParams({ format });
+                if (format === "metadata") {
+                    for (const h of ["From", "To", "Cc", "Subject", "Message-ID", "Date", "In-Reply-To", "References"]) {
+                        params.append("metadataHeaders", h);
+                    }
+                }
+                messages.push(await this.fetch(`/messages/${id}?${params}`));
+            }
+            const parsed = messages.map(msg => this.parseMessage(msg, options));
+            all.push(...parsed);
+            if (onChunk)
+                onChunk(parsed);
+        }
+        return all;
+    }
+    /** Parse a Gmail API message response into ProviderMessage */
+    parseMessage(msg, options = {}) {
+        const labels = msg.labelIds || [];
+        const headers = msg.payload?.headers || [];
+        let source = "";
+        if (options.source && msg.raw) {
+            // Gmail returns URL-safe base64 — convert to standard base64 then decode
+            const base64 = msg.raw.replace(/-/g, "+").replace(/_/g, "/");
+            source = new TextDecoder().decode(Uint8Array.from(atob(base64), c => c.charCodeAt(0)));
+        }
+        const fromRaw = getHeader(headers, "From");
+        const toRaw = getHeader(headers, "To");
+        const ccRaw = getHeader(headers, "Cc");
+        const dateRaw = getHeader(headers, "Date") || "";
+        const subject = getHeader(headers, "Subject") || msg.snippet || "";
+        const messageId = getHeader(headers, "Message-ID") || "";
+        const inReplyTo = getHeader(headers, "In-Reply-To") || "";
+        const referencesRaw = getHeader(headers, "References") || "";
+        const references = referencesRaw.trim()
+            ? referencesRaw.split(/\s+/).filter(r => r.startsWith("<") && r.endsWith(">"))
+            : [];
+        return {
+            uid: idToUid(msg.id),
+            messageId,
+            providerId: msg.id,
+            date: dateRaw ? new Date(dateRaw) : (msg.internalDate ? new Date(Number(msg.internalDate)) : null),
+            subject,
+            from: parseAddressList(fromRaw),
+            to: parseAddressList(toRaw),
+            cc: parseAddressList(ccRaw),
+            inReplyTo,
+            references,
+            seen: !labels.includes("UNREAD"),
+            flagged: labels.includes("STARRED"),
+            answered: false, // Gmail API doesn't expose this directly
+            draft: labels.includes("DRAFT"),
+            size: msg.sizeEstimate || 0,
+            source,
+        };
+    }
+    async fetchSince(folder, sinceUid, options = {}) {
+        // Gmail message IDs are hash-derived, NOT monotonic — filtering by
+        // `uid > sinceUid` silently drops new messages whose hash happens to
+        // fall below the high-water mark. Fetch the most recent page and let
+        // upsertMessage dedupe by (account, folder, uid). The sinceUid arg is
+        // kept for interface compatibility but no longer used for filtering.
+        void sinceUid;
+        const query = `in:${this.folderToLabel(folder)}`;
+        const ids = await this.listMessageIds(query, 200);
+        return this.batchFetch(ids, options);
+    }
+    async fetchByDate(folder, since, before, options = {}, onChunk) {
+        const afterDate = this.formatDate(since);
+        const beforeDate = this.formatDate(before);
+        const query = `in:${this.folderToLabel(folder)} after:${afterDate} before:${beforeDate}`;
+        const ids = await this.listMessageIds(query);
+        return this.batchFetch(ids, options, onChunk);
+    }
+    async fetchByUids(folder, uids, options = {}) {
+        // UIDs are derived from Gmail IDs — we'd need a reverse lookup
+        // For now, fetch all messages in folder and filter
+        const query = `in:${this.folderToLabel(folder)}`;
+        const ids = await this.listMessageIds(query);
+        const uidSet = new Set(uids);
+        const matchingIds = ids.filter(id => uidSet.has(idToUid(id)));
+        return this.batchFetch(matchingIds, options);
+    }
+    /** Bulk-fetch raw bodies for many UIDs in one "folder" (Gmail label).
+     *  Lists the label once, builds UID→ID map, then streams bodies through
+     *  `onBody` with bounded concurrency (lets Gmail's HTTP/2 stream multiplex;
+     *  `fetch()`'s built-in 429/5xx retry handles backoff automatically).
+     *
+     *  NOTE: Gmail's model is labels, not folders — a single message can be in
+     *  many labels. Treating each label as a folder causes duplicate fetches
+     *  across labels. Proper fix tracked as separate TODO ("Gmail label-native
+     *  model"). For now we mirror the IMAP folder grouping, accepting duplicate
+     *  fetches of multi-labeled messages. */
+    async fetchBodiesBatch(folder, uids, onBody) {
+        if (uids.length === 0)
+            return;
+        const query = `in:${this.folderToLabel(folder)}`;
+        const ids = await this.listMessageIds(query, 10000);
+        const uidToId = new Map();
+        for (const id of ids)
+            uidToId.set(idToUid(id), id);
+        const wanted = [];
+        for (const uid of uids) {
+            const id = uidToId.get(uid);
+            if (id)
+                wanted.push({ uid, id });
+        }
+        if (wanted.length === 0)
+            return;
+        // Bounded concurrency — 5 in-flight respects Gmail's PER-MINUTE quota
+        // (~15k queries/user/min shared across a project; with 10 concurrent we
+        // hit 403 "Quota exceeded for Queries per minute" on active accounts).
+        // The fetch() helper now retries 403-quota like 429, but staying under
+        // the threshold avoids the backoff pause in the first place.
+        const CONCURRENCY = 5;
+        let cursor = 0;
+        const worker = async () => {
+            while (cursor < wanted.length) {
+                const idx = cursor++;
+                const { uid, id } = wanted[idx];
+                try {
+                    const msg = await this.fetch(`/messages/${id}?format=raw`);
+                    if (!msg?.raw)
+                        continue;
+                    const base64 = msg.raw.replace(/-/g, "+").replace(/_/g, "/");
+                    const source = new TextDecoder().decode(Uint8Array.from(atob(base64), c => c.charCodeAt(0)));
+                    onBody(uid, source);
+                }
+                catch (e) {
+                    // Per-message failure is non-fatal; keep worker alive for the rest.
+                    console.error(`  [gmail batch] UID ${uid}: ${e.message}`);
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(CONCURRENCY, wanted.length) }, () => worker()));
+    }
+    async fetchOne(folder, uid, options = {}) {
+        // Need to find the Gmail ID from the UID — search all messages in folder
+        const query = `in:${this.folderToLabel(folder)}`;
+        const ids = await this.listMessageIds(query, 1000);
+        const id = ids.find(id => idToUid(id) === uid);
+        if (!id)
+            return null;
+        const format = options.source ? "raw" : "metadata";
+        const params = new URLSearchParams({ format });
+        if (format === "metadata") {
+            for (const h of ["From", "To", "Cc", "Subject", "Message-ID", "Date", "In-Reply-To", "References"]) {
+                params.append("metadataHeaders", h);
+            }
+        }
+        const msg = await this.fetch(`/messages/${id}?${params}`);
+        return this.parseMessage(msg, options);
+    }
+    async getUids(folder) {
+        const query = `in:${this.folderToLabel(folder)}`;
+        const ids = await this.listMessageIds(query, 10000);
+        const result = ids.map(idToUid);
+        // Propagate the truncation flag so reconcile can refuse to delete.
+        if (ids._truncated)
+            result._truncated = true;
+        return result;
+    }
+    async close() {
+        // No persistent connection to close
+    }
+    /** Map folder path to Gmail label query term */
+    folderToLabel(path) {
+        const lower = path.toLowerCase();
+        if (lower === "inbox")
+            return "inbox";
+        if (lower === "sent" || lower === "[gmail]/sent mail")
+            return "sent";
+        if (lower === "drafts" || lower === "[gmail]/drafts")
+            return "drafts";
+        if (lower === "trash" || lower === "[gmail]/trash")
+            return "trash";
+        if (lower === "spam" || lower === "[gmail]/spam" || lower === "junk email")
+            return "spam";
+        if (lower === "archive" || lower === "[gmail]/all mail")
+            return "all";
+        // Custom label — use exact name
+        return `"${path}"`;
+    }
+    /** Format date for Gmail query (YYYY/MM/DD) */
+    formatDate(d) {
+        return `${d.getFullYear()}/${String(d.getMonth() + 1).padStart(2, "0")}/${String(d.getDate()).padStart(2, "0")}`;
+    }
+}
+//# sourceMappingURL=gmail.js.map

package/imap.d.ts

@@ -0,0 +1,39 @@
+/**
+ * IMAP provider — implements MailProvider using CompatImapClient + a caller-
+ * supplied TransportFactory. Single source of truth for IMAP-protocol-side
+ * code shared by desktop (Node) and Android (WebView).
+ *
+ * SOURCE OF TRUTH: this file is the single canonical IMAP provider for mailx.
+ * Was previously `mailx-store-web/imap-web-provider.ts` (Android-only, with a
+ * BridgeTransport default). Moved here without the platform-specific default
+ * — callers inject the right transport at construction:
+ *   - Desktop:  () => new NodeTcpTransport()    (from @bobfrankston/node-tcp-transport)
+ *   - Android:  () => new BridgeTcpTransport()  (from @bobfrankston/tcp-transport)
+ *
+ * Includes automatic retry on broken pipe / connection errors: if an operation
+ * fails with a connection-related error, we discard the client and retry once
+ * with a fresh connection.
+ */
+import { type ImapClientConfig } from "@bobfrankston/iflow-direct";
+import type { TransportFactory } from "@bobfrankston/tcp-transport";
+import type { MailProvider, ProviderFolder, ProviderMessage, FetchOptions } from "./types.js";
+export declare class ImapProvider implements MailProvider {
+    private client;
+    private config;
+    private transportFactory;
+    private specialFolders;
+    private folderListCache;
+    constructor(config: ImapClientConfig, transportFactory: TransportFactory);
+    /** Discard the current client + recreate. Called after a broken-pipe error. */
+    private reconnect;
+    /** Run an operation, retrying once on connection error with a fresh client. */
+    private withRetry;
+    listFolders(): Promise<ProviderFolder[]>;
+    fetchSince(folder: string, sinceUid: number, options?: FetchOptions): Promise<ProviderMessage[]>;
+    fetchByDate(folder: string, since: Date, before: Date, options?: FetchOptions, onChunk?: (msgs: ProviderMessage[]) => void): Promise<ProviderMessage[]>;
+    fetchByUids(folder: string, uids: number[], options?: FetchOptions): Promise<ProviderMessage[]>;
+    fetchOne(folder: string, uid: number, options?: FetchOptions): Promise<ProviderMessage | null>;
+    getUids(folder: string): Promise<number[]>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=imap.d.ts.map

package/imap.js

@@ -0,0 +1,144 @@
+/**
+ * IMAP provider — implements MailProvider using CompatImapClient + a caller-
+ * supplied TransportFactory. Single source of truth for IMAP-protocol-side
+ * code shared by desktop (Node) and Android (WebView).
+ *
+ * SOURCE OF TRUTH: this file is the single canonical IMAP provider for mailx.
+ * Was previously `mailx-store-web/imap-web-provider.ts` (Android-only, with a
+ * BridgeTransport default). Moved here without the platform-specific default
+ * — callers inject the right transport at construction:
+ *   - Desktop:  () => new NodeTcpTransport()    (from @bobfrankston/node-tcp-transport)
+ *   - Android:  () => new BridgeTcpTransport()  (from @bobfrankston/tcp-transport)
+ *
+ * Includes automatic retry on broken pipe / connection errors: if an operation
+ * fails with a connection-related error, we discard the client and retry once
+ * with a fresh connection.
+ */
+import { CompatImapClient } from "@bobfrankston/iflow-direct";
+/** Convert iflow-direct's NativeFolder into the protocol-agnostic ProviderFolder
+ *  shape, detecting special-use from IMAP flags + special-folder hints. */
+function toProviderFolder(f, special) {
+    const flagsLower = (f.flags || []).map(x => x.toLowerCase());
+    let specialUse = "";
+    if (f.path === special.inbox || flagsLower.includes("\\inbox") || f.path.toUpperCase() === "INBOX")
+        specialUse = "inbox";
+    else if (f.path === special.sent || flagsLower.includes("\\sent"))
+        specialUse = "sent";
+    else if (f.path === special.trash || flagsLower.includes("\\trash"))
+        specialUse = "trash";
+    else if (f.path === special.drafts || flagsLower.includes("\\drafts"))
+        specialUse = "drafts";
+    else if (f.path === special.spam || f.path === special.junk || flagsLower.includes("\\junk"))
+        specialUse = "junk";
+    else if (f.path === special.archive || flagsLower.includes("\\archive"))
+        specialUse = "archive";
+    // Leaf name = last path segment after delimiter
+    const leaf = f.delimiter ? f.path.split(f.delimiter).pop() || f.path : f.path;
+    return {
+        path: f.path,
+        name: leaf,
+        delimiter: f.delimiter || "/",
+        specialUse,
+        flags: f.flags || [],
+    };
+}
+function toProviderMessage(m) {
+    return {
+        uid: m.uid,
+        messageId: m.messageId || "",
+        providerId: "",
+        date: m.date || null,
+        subject: m.subject || "",
+        from: m.from || [],
+        to: m.to || [],
+        cc: m.cc || [],
+        seen: !!m.seen,
+        flagged: !!m.flagged,
+        answered: !!m.answered,
+        draft: !!m.draft,
+        size: m.size || 0,
+        source: m.source || "",
+    };
+}
+/** Heuristic for "should we reconnect and try again?" — captures broken-pipe,
+ *  socket-closed, EPIPE, ECONNRESET, etc. */
+function isConnectionError(e) {
+    const msg = (e?.message || "").toLowerCase();
+    return msg.includes("broken pipe") || msg.includes("not connected") ||
+        msg.includes("connection") || msg.includes("socket") ||
+        msg.includes("timeout") || msg.includes("econnreset") ||
+        msg.includes("epipe") || msg.includes("closed");
+}
+export class ImapProvider {
+    client;
+    config;
+    transportFactory;
+    specialFolders = {};
+    folderListCache = null;
+    constructor(config, transportFactory) {
+        this.config = config;
+        this.transportFactory = transportFactory;
+        this.client = new CompatImapClient(config, this.transportFactory);
+    }
+    /** Discard the current client + recreate. Called after a broken-pipe error. */
+    reconnect() {
+        console.log("[imap] reconnecting after connection error");
+        try {
+            this.client.logout();
+        }
+        catch { /* ignore */ }
+        this.client = new CompatImapClient(this.config, this.transportFactory);
+    }
+    /** Run an operation, retrying once on connection error with a fresh client. */
+    async withRetry(op, label) {
+        try {
+            return await op();
+        }
+        catch (e) {
+            if (isConnectionError(e)) {
+                console.warn(`[imap] ${label}: ${e.message} — reconnecting and retrying`);
+                this.reconnect();
+                return await op();
+            }
+            throw e;
+        }
+    }
+    async listFolders() {
+        const native = await this.withRetry(() => this.client.getFolderList(), "listFolders");
+        const special = this.client.getSpecialFolders(native);
+        this.specialFolders = special;
+        const result = native.map(f => toProviderFolder(f, this.specialFolders));
+        this.folderListCache = result;
+        return result;
+    }
+    async fetchSince(folder, sinceUid, options) {
+        const msgs = await this.withRetry(() => this.client.fetchMessagesSinceUid(folder, sinceUid, { source: !!options?.source }), `fetchSince(${folder})`);
+        return msgs.map(toProviderMessage);
+    }
+    async fetchByDate(folder, since, before, options, onChunk) {
+        const wrappedChunk = onChunk ? (raw) => onChunk(raw.map(toProviderMessage)) : undefined;
+        const msgs = await this.withRetry(() => this.client.fetchMessageByDate(folder, since, before, { source: !!options?.source }, wrappedChunk), `fetchByDate(${folder})`);
+        return msgs.map(toProviderMessage);
+    }
+    async fetchByUids(folder, uids, options) {
+        if (!uids.length)
+            return [];
+        const range = uids.join(",");
+        const msgs = await this.withRetry(() => this.client.fetchMessages(folder, range, { source: !!options?.source }), `fetchByUids(${folder})`);
+        return msgs.map(toProviderMessage);
+    }
+    async fetchOne(folder, uid, options) {
+        const msg = await this.withRetry(() => this.client.fetchMessageByUid(folder, uid, { source: !!options?.source }), `fetchOne(${folder}/${uid})`);
+        return msg ? toProviderMessage(msg) : null;
+    }
+    async getUids(folder) {
+        return this.withRetry(() => this.client.getUids(folder), `getUids(${folder})`);
+    }
+    async close() {
+        try {
+            await this.client.logout();
+        }
+        catch { /* ignore */ }
+    }
+}
+//# sourceMappingURL=imap.js.map

package/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @bobfrankston/mailx-sync — platform-agnostic mail provider implementations
+ * + sync orchestration. Single source of truth for protocol code, consumed
+ * by both desktop service (Node) and Android (WebView).
+ *
+ * Why this exists: prior to this package, mailx-imap (Node) and
+ * mailx-store-web (browser) maintained parallel copies of the same Gmail
+ * provider. They drifted in practice — bug fixes in one half got lost in the
+ * other. See programming.md "Economy of Mechanism" rule and the operational
+ * TS example added 2026-04-14.
+ *
+ * Initial scope (this version): canonical types + Gmail provider. Future
+ * additions: IMAP provider, sync orchestration, batch/prefetch logic.
+ */
+export type { MailProvider, ProviderFolder, ProviderMessage, FetchOptions } from "./types.js";
+export type { SyncFolder, SyncStorage, SyncBodyStore, SyncEventSink } from "./storage.js";
+export { GmailApiProvider } from "./gmail.js";
+export { ImapProvider } from "./imap.js";
+export { OutlookApiProvider } from "./outlook.js";
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,18 @@
+/**
+ * @bobfrankston/mailx-sync — platform-agnostic mail provider implementations
+ * + sync orchestration. Single source of truth for protocol code, consumed
+ * by both desktop service (Node) and Android (WebView).
+ *
+ * Why this exists: prior to this package, mailx-imap (Node) and
+ * mailx-store-web (browser) maintained parallel copies of the same Gmail
+ * provider. They drifted in practice — bug fixes in one half got lost in the
+ * other. See programming.md "Economy of Mechanism" rule and the operational
+ * TS example added 2026-04-14.
+ *
+ * Initial scope (this version): canonical types + Gmail provider. Future
+ * additions: IMAP provider, sync orchestration, batch/prefetch logic.
+ */
+export { GmailApiProvider } from "./gmail.js";
+export { ImapProvider } from "./imap.js";
+export { OutlookApiProvider } from "./outlook.js";
+//# sourceMappingURL=index.js.map

package/outlook.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Microsoft Graph API provider — replaces IMAP for Outlook.com/Office 365 accounts.
+ * Uses Graph API for reliable, fast mail sync.
+ *
+ * SOURCE OF TRUTH: this file is the canonical Outlook provider for mailx.
+ * Same Provider abstraction as Gmail and IMAP, lives alongside them so future
+ * Android Outlook support uses the same code with no re-implementation.
+ * Currently only desktop instantiates it.
+ *
+ * Platform requirements: globalThis.fetch (Node 18+ and all browsers/WebViews).
+ * No Node-specific imports.
+ */
+import type { MailProvider, ProviderFolder, ProviderMessage, FetchOptions } from "./types.js";
+export declare class OutlookApiProvider implements MailProvider {
+    private tokenProvider;
+    constructor(tokenProvider: () => Promise<string>);
+    private fetch;
+    /** Fetch raw bytes (for RFC 2822 $value endpoint) */
+    private fetchRaw;
+    listFolders(): Promise<ProviderFolder[]>;
+    private fetchChildFolders;
+    /** Convert Graph message to ProviderMessage */
+    private parseMessage;
+    /** Stable integer UID from Graph string ID */
+    private idToUid;
+    /** List messages in a folder with optional date filter */
+    private listMessages;
+    fetchSince(folder: string, sinceUid: number, options?: FetchOptions): Promise<ProviderMessage[]>;
+    fetchByDate(folder: string, since: Date, before: Date, options?: FetchOptions, onChunk?: (msgs: ProviderMessage[]) => void): Promise<ProviderMessage[]>;
+    fetchByUids(folder: string, uids: number[], options?: FetchOptions): Promise<ProviderMessage[]>;
+    fetchOne(folder: string, uid: number, options?: FetchOptions): Promise<ProviderMessage | null>;
+    getUids(folder: string): Promise<number[]>;
+    close(): Promise<void>;
+    /** Add RFC 2822 source to messages (batch) */
+    private addSources;
+}
+//# sourceMappingURL=outlook.d.ts.map

package/outlook.js

@@ -0,0 +1,212 @@
+/**
+ * Microsoft Graph API provider — replaces IMAP for Outlook.com/Office 365 accounts.
+ * Uses Graph API for reliable, fast mail sync.
+ *
+ * SOURCE OF TRUTH: this file is the canonical Outlook provider for mailx.
+ * Same Provider abstraction as Gmail and IMAP, lives alongside them so future
+ * Android Outlook support uses the same code with no re-implementation.
+ * Currently only desktop instantiates it.
+ *
+ * Platform requirements: globalThis.fetch (Node 18+ and all browsers/WebViews).
+ * No Node-specific imports.
+ */
+const GRAPH = "https://graph.microsoft.com/v1.0/me";
+/** Map Graph well-known folder names to specialUse */
+const WELL_KNOWN = {
+    inbox: "inbox",
+    sentitems: "sent",
+    drafts: "drafts",
+    deleteditems: "trash",
+    junkemail: "junk",
+    archive: "archive",
+};
+export class OutlookApiProvider {
+    tokenProvider;
+    constructor(tokenProvider) {
+        this.tokenProvider = tokenProvider;
+    }
+    async fetch(path, options = {}) {
+        const token = await this.tokenProvider();
+        const res = await globalThis.fetch(`${GRAPH}${path}`, {
+            ...options,
+            headers: {
+                "Authorization": `Bearer ${token}`,
+                "Content-Type": "application/json",
+                ...options.headers,
+            },
+        });
+        if (!res.ok) {
+            const err = await res.text().catch(() => "");
+            throw new Error(`Graph API ${res.status}: ${err.substring(0, 200)}`);
+        }
+        return res.json();
+    }
+    /** Fetch raw bytes (for RFC 2822 $value endpoint) */
+    async fetchRaw(path) {
+        const token = await this.tokenProvider();
+        const res = await globalThis.fetch(`${GRAPH}${path}`, {
+            headers: { "Authorization": `Bearer ${token}` },
+        });
+        if (!res.ok) {
+            throw new Error(`Graph API ${res.status} on raw fetch`);
+        }
+        return res.text();
+    }
+    async listFolders() {
+        const folders = [];
+        let url = "/mailFolders?$top=100";
+        while (url) {
+            const data = await this.fetch(url);
+            for (const f of data.value || []) {
+                const specialUse = WELL_KNOWN[f.displayName?.toLowerCase()] || "";
+                folders.push({
+                    path: f.id,
+                    name: f.displayName || f.id,
+                    delimiter: "/",
+                    specialUse,
+                    flags: [],
+                });
+                // Fetch child folders
+                if (f.childFolderCount > 0) {
+                    const children = await this.fetchChildFolders(f.id, f.displayName);
+                    folders.push(...children);
+                }
+            }
+            url = data["@odata.nextLink"]?.replace(`${GRAPH}`, "") || "";
+        }
+        return folders;
+    }
+    async fetchChildFolders(parentId, parentName) {
+        const folders = [];
+        const data = await this.fetch(`/mailFolders/${parentId}/childFolders?$top=100`);
+        for (const f of data.value || []) {
+            const path = `${parentName}/${f.displayName}`;
+            folders.push({
+                path: f.id,
+                name: f.displayName,
+                delimiter: "/",
+                specialUse: "",
+                flags: [],
+            });
+            if (f.childFolderCount > 0) {
+                const children = await this.fetchChildFolders(f.id, path);
+                folders.push(...children);
+            }
+        }
+        return folders;
+    }
+    /** Convert Graph message to ProviderMessage */
+    parseMessage(msg, source = "") {
+        const from = msg.from?.emailAddress
+            ? [{ name: msg.from.emailAddress.name, address: msg.from.emailAddress.address }]
+            : [];
+        const to = (msg.toRecipients || []).map((r) => ({
+            name: r.emailAddress?.name, address: r.emailAddress?.address
+        }));
+        const cc = (msg.ccRecipients || []).map((r) => ({
+            name: r.emailAddress?.name, address: r.emailAddress?.address
+        }));
+        // Graph uses string IDs — hash to integer UID
+        const uid = this.idToUid(msg.id);
+        return {
+            uid,
+            messageId: msg.internetMessageId || "",
+            providerId: msg.id,
+            date: msg.receivedDateTime ? new Date(msg.receivedDateTime) : null,
+            subject: msg.subject || "",
+            from, to, cc,
+            seen: msg.isRead === true,
+            flagged: msg.flag?.flagStatus === "flagged",
+            answered: false,
+            draft: msg.isDraft === true,
+            size: 0, // Graph doesn't return size in list
+            source,
+        };
+    }
+    /** Stable integer UID from Graph string ID */
+    idToUid(id) {
+        // Graph IDs are long base64 strings — hash to 48-bit int
+        let hash = 0;
+        for (let i = 0; i < id.length; i++) {
+            hash = ((hash << 5) - hash + id.charCodeAt(i)) | 0;
+        }
+        return Math.abs(hash);
+    }
+    /** List messages in a folder with optional date filter */
+    async listMessages(folderId, filter = "", top = 500) {
+        const messages = [];
+        const select = "id,subject,from,toRecipients,ccRecipients,receivedDateTime,isRead,isDraft,flag,internetMessageId,hasAttachments";
+        let url = `/mailFolders/${folderId}/messages?$select=${select}&$top=${Math.min(top, 100)}&$orderby=receivedDateTime desc`;
+        if (filter)
+            url += `&$filter=${filter}`;
+        while (url && messages.length < top) {
+            const data = await this.fetch(url);
+            messages.push(...(data.value || []));
+            url = data["@odata.nextLink"]?.replace(`${GRAPH}`, "") || "";
+        }
+        return messages;
+    }
+    async fetchSince(folder, sinceUid, options = {}) {
+        // Fetch recent messages — caller filters by UID
+        const msgs = await this.listMessages(folder, "", 200);
+        let results = msgs.map(m => this.parseMessage(m));
+        results = results.filter(m => m.uid > sinceUid);
+        if (options.source) {
+            results = await this.addSources(results);
+        }
+        return results;
+    }
+    async fetchByDate(folder, since, before, options = {}, onChunk) {
+        const filter = `receivedDateTime ge ${since.toISOString()} and receivedDateTime lt ${before.toISOString()}`;
+        const msgs = await this.listMessages(folder, filter);
+        const all = [];
+        const chunkSize = 25;
+        for (let i = 0; i < msgs.length; i += chunkSize) {
+            const chunk = msgs.slice(i, i + chunkSize);
+            let parsed = chunk.map(m => this.parseMessage(m));
+            if (options.source) {
+                parsed = await this.addSources(parsed);
+            }
+            all.push(...parsed);
+            if (onChunk)
+                onChunk(parsed);
+        }
+        return all;
+    }
+    async fetchByUids(folder, uids, options = {}) {
+        const uidSet = new Set(uids);
+        const msgs = await this.listMessages(folder, "", 1000);
+        let results = msgs.map(m => this.parseMessage(m)).filter(m => uidSet.has(m.uid));
+        if (options.source) {
+            results = await this.addSources(results);
+        }
+        return results;
+    }
+    async fetchOne(folder, uid, options = {}) {
+        const msgs = await this.listMessages(folder, "", 500);
+        const msg = msgs.find(m => this.idToUid(m.id) === uid);
+        if (!msg)
+            return null;
+        let source = "";
+        if (options.source) {
+            source = await this.fetchRaw(`/messages/${msg.id}/$value`);
+        }
+        return this.parseMessage(msg, source);
+    }
+    async getUids(folder) {
+        const msgs = await this.listMessages(folder, "", 10000);
+        return msgs.map(m => this.idToUid(m.id));
+    }
+    async close() { }
+    /** Add RFC 2822 source to messages (batch) */
+    async addSources(messages) {
+        for (const msg of messages) {
+            try {
+                msg.source = await this.fetchRaw(`/messages/${msg.providerId}/$value`);
+            }
+            catch { /* source unavailable — leave empty */ }
+        }
+        return messages;
+    }
+}
+//# sourceMappingURL=outlook.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@bobfrankston/mailx-sync",
+  "version": "0.1.3",
+  "description": "Platform-agnostic mail provider implementations + sync orchestration. Single source of truth for Gmail/IMAP/Outlook protocol code, consumed by both desktop (Node) and Android (WebView) — eliminates the parallel mailx-imap/mailx-store-web Gmail providers that drifted in practice.",
+  "main": "index.js",
+  "types": "index.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -watch",
+    "check": "tsc --noEmit"
+  },
+  "keywords": [
+    "mail",
+    "gmail",
+    "imap",
+    "platform-agnostic"
+  ],
+  "author": "Bob Frankston",
+  "license": "ISC",
+  "dependencies": {
+    "@bobfrankston/tcp-transport": "^0.1.3",
+    "@bobfrankston/iflow-direct": "^0.1.20"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "default": "./index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BobFrankston/mailx-sync.git"
+  },
+  ".dependencies": {
+    "@bobfrankston/tcp-transport": "file:../tcp-transport",
+    "@bobfrankston/iflow-direct": "file:../iflow-direct"
+  },
+  ".transformedSnapshot": {
+    "dependencies": {
+      "@bobfrankston/tcp-transport": "^0.1.3",
+      "@bobfrankston/iflow-direct": "^0.1.20"
+    }
+  }
+}

package/storage.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Storage interface — what the shared sync code needs from a database.
+ *
+ * Two implementations satisfy this interface:
+ *   - Desktop:  `@bobfrankston/mailx-store` (node:sqlite-backed `MailxDB`)
+ *   - Android:  `@bobfrankston/mailx-store-web` (sql.js-backed `WebMailxDB`)
+ *
+ * Each adapts its own DB to this interface so the shared sync orchestration
+ * (in `./sync.ts`) doesn't care which platform it's running on. Methods kept
+ * deliberately small — only what sync orchestration actually needs.
+ */
+import type { ProviderMessage } from "./types.js";
+export interface SyncFolder {
+    id: number;
+    accountId: string;
+    path: string;
+    name: string;
+    specialUse: string;
+    delimiter: string;
+}
+export interface SyncStorage {
+    /** All folders for an account. Used to look up folder by id during sync. */
+    getFolders(accountId: string): SyncFolder[];
+    /** Highest UID currently cached for a folder. 0 means never synced. */
+    getHighestUid(accountId: string, folderId: number): number;
+    /** All UIDs currently in the DB for a folder. Used by the reconcile path
+     *  to detect server-side deletions. */
+    getUidsForFolder(accountId: string, folderId: number): number[];
+    /** Insert-or-update a single message envelope. Returns true if a new row
+     *  was inserted, false if it was an update of an existing row. */
+    upsertProviderMessage(accountId: string, folderId: number, msg: ProviderMessage): boolean;
+    /** Remove a message row + cascade folder counts. */
+    deleteMessage(accountId: string, uid: number): void;
+    /** Recompute total/unread for a folder (called after batch insert/delete). */
+    recalcFolderCounts(folderId: number): void;
+    /** Update the on-disk path where the body bytes are stored. Called after
+     *  a successful body fetch. */
+    updateBodyPath(accountId: string, uid: number, bodyPath: string): void;
+    /** Find messages whose body hasn't been cached yet. Used by prefetch.
+     *  Returns up to `limit` rows ordered most-recent-first. */
+    getMessagesWithoutBody(accountId: string, limit: number): {
+        uid: number;
+        folderId: number;
+    }[];
+}
+/** Where message bodies (raw RFC 2822 .eml files or equivalent blobs) live.
+ *  Desktop: filesystem under ~/.mailx/mailxstore/.
+ *  Android: IndexedDB or local-storage equivalent. */
+export interface SyncBodyStore {
+    /** Write body bytes for a message. Returns an opaque path/id that
+     *  `updateBodyPath` will store in the DB. */
+    putMessage(accountId: string, folderId: number, uid: number, raw: Uint8Array): Promise<string>;
+    /** Delete a body — best-effort, may resolve even if missing. */
+    deleteMessage(accountId: string, folderId: number, uid: number): Promise<void>;
+}
+/** Optional event sink so shared sync can emit progress. Both platforms have
+ *  some kind of event system; this is a thin shim. Callers can no-op. */
+export interface SyncEventSink {
+    folderCountsChanged(accountId: string): void;
+    syncProgress?(accountId: string, phase: string, progress: number): void;
+}
+//# sourceMappingURL=storage.d.ts.map

package/storage.js

@@ -0,0 +1,13 @@
+/**
+ * Storage interface — what the shared sync code needs from a database.
+ *
+ * Two implementations satisfy this interface:
+ *   - Desktop:  `@bobfrankston/mailx-store` (node:sqlite-backed `MailxDB`)
+ *   - Android:  `@bobfrankston/mailx-store-web` (sql.js-backed `WebMailxDB`)
+ *
+ * Each adapts its own DB to this interface so the shared sync orchestration
+ * (in `./sync.ts`) doesn't care which platform it's running on. Methods kept
+ * deliberately small — only what sync orchestration actually needs.
+ */
+export {};
+//# sourceMappingURL=storage.js.map

package/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Mail provider interface — abstraction over IMAP, Gmail API, and Microsoft Graph.
+ * Sync code uses this interface; never calls IMAP/REST directly.
+ *
+ * SOURCE OF TRUTH: this file is the single canonical definition. The earlier
+ * mailx-imap/providers/types.ts and mailx-store-web/provider-types.ts have
+ * been collapsed into this; both packages now re-export from here.
+ */
+export interface ProviderFolder {
+    path: string;
+    name: string;
+    delimiter: string;
+    specialUse: string;
+    flags: string[];
+}
+export interface ProviderMessage {
+    uid: number;
+    messageId: string;
+    providerId: string;
+    date: Date | null;
+    subject: string;
+    from: {
+        name?: string;
+        address?: string;
+    }[];
+    to: {
+        name?: string;
+        address?: string;
+    }[];
+    cc: {
+        name?: string;
+        address?: string;
+    }[];
+    inReplyTo?: string;
+    references?: string[];
+    seen: boolean;
+    flagged: boolean;
+    answered: boolean;
+    draft: boolean;
+    size: number;
+    source: string;
+}
+export interface FetchOptions {
+    source?: boolean;
+}
+/**
+ * A mail provider that can list folders, fetch messages, and perform actions.
+ * Implementations: ImapProvider (existing iflow), GmailApiProvider, GraphApiProvider.
+ */
+export interface MailProvider {
+    /** List all folders/labels */
+    listFolders(): Promise<ProviderFolder[]>;
+    /** Fetch messages newer than sinceUid (incremental sync) */
+    fetchSince(folder: string, sinceUid: number, options?: FetchOptions): Promise<ProviderMessage[]>;
+    /** Fetch messages by date range (first sync) */
+    fetchByDate(folder: string, since: Date, before: Date, options?: FetchOptions, onChunk?: (msgs: ProviderMessage[]) => void): Promise<ProviderMessage[]>;
+    /** Fetch specific messages by UID */
+    fetchByUids(folder: string, uids: number[], options?: FetchOptions): Promise<ProviderMessage[]>;
+    /** Fetch a single message by UID */
+    fetchOne(folder: string, uid: number, options?: FetchOptions): Promise<ProviderMessage | null>;
+    /** Get all UIDs in a folder (for reconciliation) */
+    getUids(folder: string): Promise<number[]>;
+    /** Close/cleanup */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/types.js

@@ -0,0 +1,10 @@
+/**
+ * Mail provider interface — abstraction over IMAP, Gmail API, and Microsoft Graph.
+ * Sync code uses this interface; never calls IMAP/REST directly.
+ *
+ * SOURCE OF TRUTH: this file is the single canonical definition. The earlier
+ * mailx-imap/providers/types.ts and mailx-store-web/provider-types.ts have
+ * been collapsed into this; both packages now re-export from here.
+ */
+export {};
+//# sourceMappingURL=types.js.map