@diskd-ai/email-client-mcp 0.1.0

package/dist/server.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * email-client-mcp stdio entry. Composition root.
+ *
+ * Responsibilities:
+ *  1. Parse CLI args (default subcommand: stdio).
+ *  2. Load + validate the TOML config.
+ *  3. Build @diskd/sdk client and Drive store.
+ *  4. Build IMAP pool + sync deps.
+ *  5. Register MCP tools, attach stdio transport.
+ *  6. Start the watcher AFTER the MCP `initialized` notification so we
+ *     do not race with the client handshake -- per the email-mcp pattern.
+ *  7. Graceful shutdown on SIGINT/SIGTERM.
+ *
+ * Logs go to stderr only (stdout is reserved for MCP JSON-RPC).
+ */
+export {};

package/dist/server.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * email-client-mcp stdio entry. Composition root.
+ *
+ * Responsibilities:
+ *  1. Parse CLI args (default subcommand: stdio).
+ *  2. Load + validate the TOML config.
+ *  3. Build @diskd/sdk client and Drive store.
+ *  4. Build IMAP pool + sync deps.
+ *  5. Register MCP tools, attach stdio transport.
+ *  6. Start the watcher AFTER the MCP `initialized` notification so we
+ *     do not race with the client handshake -- per the email-mcp pattern.
+ *  7. Graceful shutdown on SIGINT/SIGTERM.
+ *
+ * Logs go to stderr only (stdout is reserved for MCP JSON-RPC).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config/loader.js";
+import { errorMessage } from "./domain/errors.js";
+import { Err, Ok } from "./domain/result.js";
+import { fetchEnvelopesUidRange, fetchUidRange, folderStatus, withMailboxLock, } from "./imap/fetch.js";
+import { buildImapPool } from "./imap/pool.js";
+import { buildDiskd } from "./sdk/diskdClient.js";
+import { buildDriveStore } from "./store/driveStore.js";
+import { buildWatcher } from "./sync/watcher.js";
+import { registerTools } from "./tools/registry.js";
+const log = (msg, extra) => {
+    const payload = extra === undefined ? msg : `${msg} ${JSON.stringify(extra)}`;
+    process.stderr.write(`[email-client-mcp] ${payload}\n`);
+};
+const parseSubcommand = (argv) => {
+    // npx will pass the bin name as argv[1]; the user-supplied subcommand
+    // is at argv[2] (or absent).
+    const sub = argv[2];
+    if (sub === undefined || sub === "stdio")
+        return "stdio";
+    return "unknown";
+};
+const main = async () => {
+    const sub = parseSubcommand(process.argv);
+    if (sub === "unknown") {
+        log("usage: email-client-mcp [stdio]");
+        process.exit(2);
+    }
+    const configPath = process.env.EMAIL_CLIENT_MCP_CONFIG;
+    const cfg = await loadConfig(configPath);
+    if (cfg.tag === "Err") {
+        log("config error", { error: errorMessage(cfg.error) });
+        process.exit(1);
+    }
+    const diskd = buildDiskd(cfg.value.sdk, process.env.MCP_HUB_WORKSPACE_ID);
+    if (diskd.tag === "Err") {
+        log("sdk init failed", { error: errorMessage(diskd.error) });
+        process.exit(1);
+    }
+    log("sdk ready", { workspaceId: diskd.value.workspaceId });
+    const driveStore = buildDriveStore(diskd.value.messagesStore);
+    const pool = buildImapPool(cfg.value.accounts);
+    const syncDeps = {
+        drive: driveStore,
+        imap: {
+            listFolders: async (accountId) => {
+                const c = await pool.forAccount(accountId);
+                if (c.tag === "Err")
+                    return c;
+                try {
+                    const list = await c.value.list();
+                    return Ok(list.map((f) => ({
+                        path: f.path,
+                        specialUse: (f.specialUse ?? null),
+                    })));
+                }
+                catch (cause) {
+                    return Err({
+                        kind: "ImapError",
+                        accountId,
+                        message: `list failed: ${cause?.message ?? String(cause)}`,
+                    });
+                }
+            },
+            folderStatus: async (accountId, path) => {
+                const c = await pool.forAccount(accountId);
+                if (c.tag === "Err")
+                    return c;
+                try {
+                    const s = await folderStatus(c.value, path);
+                    return Ok(s);
+                }
+                catch (cause) {
+                    return Err({
+                        kind: "ImapError",
+                        accountId,
+                        message: `status ${path}: ${cause?.message ?? String(cause)}`,
+                    });
+                }
+            },
+            fetchRange: async function* (accountId, path, fromUid, toUid) {
+                const c = await pool.forAccount(accountId);
+                if (c.tag === "Err")
+                    throw new Error(errorMessage(c.error));
+                // Buffer under-lock, yield after release. Batch sizes are
+                // bounded (sync uses 50) so the cost is acceptable.
+                const buf = await withMailboxLock(c.value, path, async () => {
+                    const out = [];
+                    for await (const m of fetchUidRange(c.value, fromUid, toUid))
+                        out.push(m);
+                    return out;
+                });
+                for (const m of buf)
+                    yield m;
+            },
+            fetchEnvelopesRange: async function* (accountId, path, fromUid, toUid) {
+                const c = await pool.forAccount(accountId);
+                if (c.tag === "Err")
+                    throw new Error(errorMessage(c.error));
+                const buf = await withMailboxLock(c.value, path, async () => {
+                    const out = [];
+                    for await (const m of fetchEnvelopesUidRange(c.value, fromUid, toUid))
+                        out.push(m);
+                    return out;
+                });
+                for (const m of buf)
+                    yield m;
+            },
+        },
+        now: () => new Date(),
+    };
+    const watcher = buildWatcher(syncDeps, cfg.value.accounts, cfg.value.watcher, log);
+    const server = new McpServer({
+        name: "email-client-mcp",
+        version: "0.1.0",
+    });
+    registerTools(server, {
+        accounts: cfg.value.accounts,
+        imapPool: pool,
+        watcher,
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log("mcp ready", { accounts: cfg.value.accounts.length });
+    // Start watcher after MCP transport is ready. The interval fires
+    // immediately on the first tick (see watcher.start), then on every
+    // clamped interval thereafter.
+    if (cfg.value.watcher.enabled) {
+        watcher.start();
+    }
+    else {
+        log("watcher.disabled-by-config");
+    }
+    const shutdown = async (signal) => {
+        log("shutdown", { signal });
+        try {
+            await watcher.stop();
+        }
+        catch (e) {
+            log("watcher stop error", { error: String(e) });
+        }
+        try {
+            await pool.closeAll();
+        }
+        catch (e) {
+            log("pool close error", { error: String(e) });
+        }
+        try {
+            await server.close();
+        }
+        catch (e) {
+            log("server close error", { error: String(e) });
+        }
+        process.exit(0);
+    };
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+};
+main().catch((err) => {
+    log("fatal", { error: err?.message ?? String(err) });
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/store/conventions.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure helpers that map account/folder/UID identity onto the
+ * messagesStore namespace. Concentrating these so a future change
+ * (e.g. a different mailbox-id scheme) only edits one file.
+ */
+/**
+ * Sanitize an account id for use as a Drive mailbox id (slug subset
+ * `[a-z0-9-]{1,64}`). Lowercase, replace anything else with `-`, collapse
+ * runs, trim leading/trailing dashes, truncate. Empty input -> 'mailbox'.
+ */
+export declare const sanitizeMailboxId: (raw: string) => string;
+/**
+ * Caller-supplied folderId for a given IMAP mailbox path. We keep the
+ * IMAP path verbatim so `find_mailbox_folder` can round-trip it.
+ */
+export declare const folderIdFromImapPath: (imapPath: string) => string;
+/**
+ * Build the messagesStore externalId for a message. `${uidValidity}:${uid}`
+ * makes the id stable across sync runs and disjoint across UIDVALIDITY
+ * generations.
+ */
+export declare const externalIdFor: (uidValidity: number, uid: number) => string;
+/**
+ * Parse an externalId back into its components. Returns null on a
+ * malformed input -- callers should treat that as "not produced by us".
+ */
+export declare const parseExternalId: (externalId: string) => {
+    uidValidity: number;
+    uid: number;
+} | null;
+export declare const isValidMailboxId: (id: string) => boolean;

package/dist/store/conventions.js

@@ -0,0 +1,53 @@
+/**
+ * Pure helpers that map account/folder/UID identity onto the
+ * messagesStore namespace. Concentrating these so a future change
+ * (e.g. a different mailbox-id scheme) only edits one file.
+ */
+const MAILBOX_ID_RE = /^[a-z0-9-]{1,64}$/;
+/**
+ * Sanitize an account id for use as a Drive mailbox id (slug subset
+ * `[a-z0-9-]{1,64}`). Lowercase, replace anything else with `-`, collapse
+ * runs, trim leading/trailing dashes, truncate. Empty input -> 'mailbox'.
+ */
+export const sanitizeMailboxId = (raw) => {
+    const lowered = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    const truncated = lowered.slice(0, 64);
+    return truncated.length === 0 ? "mailbox" : truncated;
+};
+/**
+ * Caller-supplied folderId for a given IMAP mailbox path. We keep the
+ * IMAP path verbatim so `find_mailbox_folder` can round-trip it.
+ */
+export const folderIdFromImapPath = (imapPath) => imapPath;
+/**
+ * Build the messagesStore externalId for a message. `${uidValidity}:${uid}`
+ * makes the id stable across sync runs and disjoint across UIDVALIDITY
+ * generations.
+ */
+export const externalIdFor = (uidValidity, uid) => `${uidValidity}:${uid}`;
+/**
+ * Parse an externalId back into its components. Returns null on a
+ * malformed input -- callers should treat that as "not produced by us".
+ */
+export const parseExternalId = (externalId) => {
+    const parts = externalId.split(":");
+    if (parts.length !== 2)
+        return null;
+    const uvRaw = parts[0];
+    const uidRaw = parts[1];
+    if (uvRaw === undefined || uidRaw === undefined)
+        return null;
+    const uv = Number.parseInt(uvRaw, 10);
+    const uid = Number.parseInt(uidRaw, 10);
+    if (!Number.isFinite(uv) || !Number.isFinite(uid))
+        return null;
+    if (uv < 0 || uid < 0)
+        return null;
+    return { uidValidity: uv, uid };
+};
+export const isValidMailboxId = (id) => MAILBOX_ID_RE.test(id);
+//# sourceMappingURL=conventions.js.map

package/dist/store/conventions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../src/store/conventions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAW,EAAU,EAAE;IACvD,MAAM,OAAO,GAAG,GAAG;SAChB,WAAW,EAAE;SACb,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC;SAC5B,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACzB,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACvC,OAAO,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;AACxD,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,QAAgB,EAAU,EAAE,CAAC,QAAQ,CAAC;AAE3E;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,WAAmB,EAAE,GAAW,EAAU,EAAE,CAAC,GAAG,WAAW,IAAI,GAAG,EAAE,CAAC;AAEnG;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,UAAkB,EAC2B,EAAE;IAC/C,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/D,IAAI,EAAE,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC;AAClC,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,EAAU,EAAW,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC"}

package/dist/store/driveStore.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Adapter over `diskd.os.messagesStore`. Wraps each call in
+ * try/catch -> typed `DriveError` so the sync core stays pure-ish
+ * (Result-returning) and we can compose retries with backoff.
+ *
+ * One mailbox per account: ensureMailbox is idempotent; the underlying
+ * `createMailbox` errors (e.g. ALREADY_EXISTS) are absorbed -- callers
+ * do not need to track creation state.
+ */
+import type { diskd as DiskdNs } from "@diskd/sdk";
+import { type DriveError } from "../domain/errors.js";
+import { type Result } from "../domain/result.js";
+import type { StoredEmailPayload, SyncState } from "./payloadTypes.js";
+type MessagesStore = ReturnType<typeof DiskdNs.os.messagesStore>;
+export type DriveStore = {
+    /** Ensure mailbox exists and SQLite schema is bootstrapped. */
+    readonly ensureMailbox: (mailboxId: string, displayName: string) => Promise<Result<DriveError, void>>;
+    readonly listMailboxes: () => Promise<Result<DriveError, readonly string[]>>;
+    readonly upsertFolder: (mailboxId: string, folderId: string, displayName: string, metadata: SyncState) => Promise<Result<DriveError, void>>;
+    readonly getFolder: (mailboxId: string, folderId: string) => Promise<Result<DriveError, {
+        metadata: Readonly<Record<string, unknown>>;
+    } | null>>;
+    readonly listFolders: (mailboxId: string) => Promise<Result<DriveError, readonly {
+        folderId: string;
+        messageCount: number;
+    }[]>>;
+    readonly deleteFolder: (mailboxId: string, folderId: string) => Promise<Result<DriveError, {
+        deletedMessageCount: number;
+    }>>;
+    readonly upsertMessages: (mailboxId: string, folderId: string, payloads: readonly StoredEmailPayload[], externalIds: readonly string[]) => Promise<Result<DriveError, {
+        inserted: number;
+        updated: number;
+    }>>;
+};
+export declare const buildDriveStore: (store: MessagesStore) => DriveStore;
+export {};

package/dist/store/driveStore.js

@@ -0,0 +1,95 @@
+/**
+ * Adapter over `diskd.os.messagesStore`. Wraps each call in
+ * try/catch -> typed `DriveError` so the sync core stays pure-ish
+ * (Result-returning) and we can compose retries with backoff.
+ *
+ * One mailbox per account: ensureMailbox is idempotent; the underlying
+ * `createMailbox` errors (e.g. ALREADY_EXISTS) are absorbed -- callers
+ * do not need to track creation state.
+ */
+import { driveError } from "../domain/errors.js";
+import { Err, Ok } from "../domain/result.js";
+import { isValidMailboxId } from "./conventions.js";
+const wrap = async (what, fn) => {
+    try {
+        return Ok(await fn());
+    }
+    catch (cause) {
+        return Err(driveError(`${what} failed: ${cause?.message ?? String(cause)}`, cause));
+    }
+};
+const folderScoped = (store, mailboxId, folderId) => store.mailbox({ mailboxId }).folder({ folderId });
+export const buildDriveStore = (store) => ({
+    async ensureMailbox(mailboxId, displayName) {
+        if (!isValidMailboxId(mailboxId)) {
+            return Err(driveError(`mailboxId '${mailboxId}' is not a valid slug`));
+        }
+        const list = await wrap("listMailboxes", () => store.listMailboxes());
+        if (list.tag === "Err")
+            return list;
+        const exists = list.value.some((m) => m.mailboxId === mailboxId);
+        if (!exists) {
+            const create = await wrap("createMailbox", () => store.createMailbox({ mailboxId, displayName }));
+            if (create.tag === "Err")
+                return create;
+        }
+        const init = await wrap("mailbox.init", () => store.mailbox({ mailboxId }).init());
+        if (init.tag === "Err")
+            return init;
+        return Ok(undefined);
+    },
+    async listMailboxes() {
+        const r = await wrap("listMailboxes", () => store.listMailboxes());
+        if (r.tag === "Err")
+            return r;
+        return Ok(r.value.map((m) => m.mailboxId));
+    },
+    async upsertFolder(mailboxId, folderId, displayName, metadata) {
+        const r = await wrap("upsertFolder", () => store.mailbox({ mailboxId }).upsertFolder({
+            folderId,
+            displayName,
+            metadata: metadata,
+        }));
+        if (r.tag === "Err")
+            return r;
+        return Ok(undefined);
+    },
+    async getFolder(mailboxId, folderId) {
+        try {
+            const summary = await folderScoped(store, mailboxId, folderId).get();
+            return Ok({ metadata: summary.metadata });
+        }
+        catch (cause) {
+            const msg = cause?.message ?? String(cause);
+            if (/not found|FOLDER_NOT_FOUND|404/i.test(msg)) {
+                return Ok(null);
+            }
+            return Err(driveError(`folder.get failed: ${msg}`, cause));
+        }
+    },
+    async listFolders(mailboxId) {
+        const r = await wrap("listFolders", () => store.mailbox({ mailboxId }).listFolders());
+        if (r.tag === "Err")
+            return r;
+        return Ok(r.value.map((f) => ({ folderId: f.folderId, messageCount: f.messageCount })));
+    },
+    async deleteFolder(mailboxId, folderId) {
+        const r = await wrap("folder.delete", () => folderScoped(store, mailboxId, folderId).delete());
+        if (r.tag === "Err")
+            return r;
+        return Ok({ deletedMessageCount: r.value.deletedMessageCount });
+    },
+    async upsertMessages(mailboxId, folderId, payloads, externalIds) {
+        if (payloads.length === 0)
+            return Ok({ inserted: 0, updated: 0 });
+        const items = payloads.map((p, i) => ({
+            externalId: externalIds[i],
+            payload: p,
+        }));
+        const r = await wrap("folder.upsertBatch", () => folderScoped(store, mailboxId, folderId).upsertBatch({ items, autoCommit: false }));
+        if (r.tag === "Err")
+            return r;
+        return Ok({ inserted: r.value.inserted, updated: r.value.updated });
+    },
+});
+//# sourceMappingURL=driveStore.js.map

package/dist/store/driveStore.js.map

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

package/dist/store/payloadTypes.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Drive `messagesStore` payload shape -- opaque JSON to Drive but owned
+ * by this server. Keep stable: external consumers (search, agents)
+ * can rely on these fields landing in the store mirror.
+ *
+ * `externalId` (the messagesStore primary key for a message) is built
+ * from `${uidValidity}:${uid}` so a UIDVALIDITY rollover never
+ * collides with the previous generation.
+ */
+export type EmailAddress = {
+    readonly name: string | null;
+    readonly address: string;
+};
+export type StoredAttachment = {
+    readonly filename: string;
+    readonly contentType: string;
+    readonly sizeBytes: number;
+    readonly partId: string;
+};
+export type StoredEmailPayload = {
+    readonly accountId: string;
+    readonly mailbox: string;
+    readonly uid: number;
+    readonly uidValidity: number;
+    readonly messageId: string | null;
+    readonly inReplyTo: string | null;
+    readonly references: readonly string[];
+    readonly from: EmailAddress | null;
+    readonly to: readonly EmailAddress[];
+    readonly cc: readonly EmailAddress[];
+    readonly subject: string;
+    readonly date: string;
+    readonly flags: readonly string[];
+    readonly labels: readonly string[];
+    readonly hasAttachments: boolean;
+    readonly attachments: readonly StoredAttachment[];
+    readonly snippet: string;
+    readonly bodyText: string | null;
+    readonly bodyHtml: string | null;
+    readonly truncated: boolean;
+    readonly fetchedAt: string;
+};
+/**
+ * Folder metadata used by the watcher to drive idempotent, restart-safe
+ * sync. Stored as opaque JSON via `mailbox.folder(...).upsert({metadata})`.
+ *
+ *  - `uidValidity`: snapshot of last seen UIDVALIDITY; mismatch triggers
+ *    a full folder drop+resync.
+ *  - `uidNext`: snapshot of last seen UIDNEXT; the head of the sync window.
+ *  - `lastSyncedUid`: highest UID confirmed written via successful upsert.
+ *    `runSyncOnce` advances this only after a batch upsert returns Ok.
+ *  - `lastSyncStartedAt` / `lastSyncFinishedAt` / `lastSyncError`:
+ *    diagnostic snapshot exposed via `get_watcher_status`.
+ */
+export type SyncState = {
+    readonly uidValidity: number;
+    readonly uidNext: number;
+    readonly lastSyncedUid: number;
+    readonly lastSyncStartedAt: string | null;
+    readonly lastSyncFinishedAt: string | null;
+    readonly lastSyncError: string | null;
+};

package/dist/store/payloadTypes.js

@@ -0,0 +1,11 @@
+/**
+ * Drive `messagesStore` payload shape -- opaque JSON to Drive but owned
+ * by this server. Keep stable: external consumers (search, agents)
+ * can rely on these fields landing in the store mirror.
+ *
+ * `externalId` (the messagesStore primary key for a message) is built
+ * from `${uidValidity}:${uid}` so a UIDVALIDITY rollover never
+ * collides with the previous generation.
+ */
+export {};
+//# sourceMappingURL=payloadTypes.js.map

package/dist/store/payloadTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payloadTypes.js","sourceRoot":"","sources":["../../src/store/payloadTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/sync/backoff.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Pure exponential-backoff helper. `nextDelay(prev)` returns the next
+ * delay in ms, capped at MAX_BACKOFF_MS. The watcher uses this when an
+ * IMAP or Drive operation fails inside a tick, so each retry waits a
+ * little longer up to the cap.
+ *
+ * Pure; no setTimeout. Callers compose the delay with their own timers.
+ */
+export declare const INITIAL_BACKOFF_MS = 1000;
+export declare const MAX_BACKOFF_MS = 60000;
+export declare const BACKOFF_FACTOR = 2;
+export declare const nextBackoff: (prevMs: number | null) => number;
+/**
+ * Clamp a configured tick interval to the spec floor of 60s. Used by
+ * the watcher; not the backoff helper itself.
+ */
+export declare const MIN_TICK_INTERVAL_MS = 60000;
+export declare const clampTickInterval: (ms: number) => number;

package/dist/sync/backoff.js

@@ -0,0 +1,24 @@
+/**
+ * Pure exponential-backoff helper. `nextDelay(prev)` returns the next
+ * delay in ms, capped at MAX_BACKOFF_MS. The watcher uses this when an
+ * IMAP or Drive operation fails inside a tick, so each retry waits a
+ * little longer up to the cap.
+ *
+ * Pure; no setTimeout. Callers compose the delay with their own timers.
+ */
+export const INITIAL_BACKOFF_MS = 1_000;
+export const MAX_BACKOFF_MS = 60_000;
+export const BACKOFF_FACTOR = 2;
+export const nextBackoff = (prevMs) => {
+    if (prevMs === null)
+        return INITIAL_BACKOFF_MS;
+    const next = prevMs * BACKOFF_FACTOR;
+    return next > MAX_BACKOFF_MS ? MAX_BACKOFF_MS : next;
+};
+/**
+ * Clamp a configured tick interval to the spec floor of 60s. Used by
+ * the watcher; not the backoff helper itself.
+ */
+export const MIN_TICK_INTERVAL_MS = 60_000;
+export const clampTickInterval = (ms) => ms < MIN_TICK_INTERVAL_MS ? MIN_TICK_INTERVAL_MS : ms;
+//# sourceMappingURL=backoff.js.map

package/dist/sync/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../src/sync/backoff.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC;AACxC,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AACrC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAqB,EAAU,EAAE;IAC3D,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,kBAAkB,CAAC;IAC/C,MAAM,IAAI,GAAG,MAAM,GAAG,cAAc,CAAC;IACrC,OAAO,IAAI,GAAG,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC;AACvD,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAC3C,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,EAAU,EAAU,EAAE,CACtD,EAAE,GAAG,oBAAoB,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC"}

package/dist/sync/sync.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The reliability core. `runSyncOnce(account)` performs one watcher
+ * pass for one account.
+ *
+ * Invariants enforced here:
+ *  1. `lastSyncedUid` is advanced ONLY after a successful upsertBatch.
+ *     A crash mid-tick or a Drive 5xx leaves the checkpoint untouched,
+ *     so the next tick re-fetches the unprocessed UIDs (idempotent
+ *     because externalId is `${UIDVALIDITY}:${UID}`).
+ *  2. UIDVALIDITY mismatch -> drop+recreate folder, resync from UID 1.
+ *  3. Folder metadata is the source of truth across restarts. The
+ *     watcher never relies on in-memory state to resume.
+ *  4. Folders deleted in IMAP are pruned from Drive at the end of a tick.
+ *  5. A bounded sliding-window flag reconciliation catches drift on
+ *     already-synced UIDs without re-downloading bodies.
+ *
+ * The function takes injected dependencies (drive store, IMAP client
+ * factory, mapper) so unit tests can drive it without real I/O.
+ */
+import { type Account, type WatcherSettings } from "../config/schema.js";
+import { type AppError, type ImapError } from "../domain/errors.js";
+import { type Result } from "../domain/result.js";
+import { type FetchedMessageLike } from "../imap/mapper.js";
+import type { StoredEmailPayload, SyncState } from "../store/payloadTypes.js";
+export type SyncDeps = {
+    readonly drive: {
+        readonly ensureMailbox: (mailboxId: string, displayName: string) => Promise<Result<AppError, void>>;
+        readonly upsertFolder: (mailboxId: string, folderId: string, displayName: string, metadata: SyncState) => Promise<Result<AppError, void>>;
+        readonly getFolder: (mailboxId: string, folderId: string) => Promise<Result<AppError, {
+            metadata: Readonly<Record<string, unknown>>;
+        } | null>>;
+        readonly listFolders: (mailboxId: string) => Promise<Result<AppError, readonly {
+            folderId: string;
+            messageCount: number;
+        }[]>>;
+        readonly deleteFolder: (mailboxId: string, folderId: string) => Promise<Result<AppError, {
+            deletedMessageCount: number;
+        }>>;
+        readonly upsertMessages: (mailboxId: string, folderId: string, payloads: readonly StoredEmailPayload[], externalIds: readonly string[]) => Promise<Result<AppError, {
+            inserted: number;
+            updated: number;
+        }>>;
+    };
+    readonly imap: {
+        readonly listFolders: (accountId: string) => Promise<Result<ImapError, readonly {
+            path: string;
+            specialUse: string | null;
+        }[]>>;
+        readonly folderStatus: (accountId: string, path: string) => Promise<Result<ImapError, {
+            uidValidity: number;
+            uidNext: number;
+            messages: number;
+        }>>;
+        readonly fetchRange: (accountId: string, path: string, fromUid: number, toUid: number) => AsyncIterable<{
+            readonly imapMessage: FetchedMessageLike;
+            readonly bodyText: string | null;
+            readonly bodyHtml: string | null;
+        }>;
+        readonly fetchEnvelopesRange: (accountId: string, path: string, fromUid: number, toUid: number) => AsyncIterable<FetchedMessageLike>;
+    };
+    readonly now: () => Date;
+};
+export type SyncFolderReport = {
+    readonly folderId: string;
+    readonly newMessages: number;
+    readonly reconciledFlags: number;
+    readonly uidValidityRolled: boolean;
+    readonly error: string | null;
+};
+export type SyncReport = {
+    readonly accountId: string;
+    readonly folders: readonly SyncFolderReport[];
+    readonly prunedFolders: number;
+    readonly startedAt: string;
+    readonly finishedAt: string;
+    readonly error: string | null;
+};
+/**
+ * Run one sync tick for one account. Sequentially walks all folders,
+ * then prunes Drive folders that no longer exist in IMAP.
+ */
+export declare const runSyncOnce: (deps: SyncDeps, account: Account, watcher: WatcherSettings) => Promise<SyncReport>;
+export declare const __test__: {
+    Err: <E>(error: E) => Result<E, never>;
+};