@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):

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):

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