zele 0.3.0 → 0.3.5

package/dist/gmail-client.js

@@ -1,16 +1,19 @@
 // Gmail API client for CLI/TUI use.
 // Wraps the @googleapis/gmail SDK with structured methods, object params, and inferred return types.
 // No abstract interfaces, no RPC layer — just a concrete class for Gmail.
-// Ported from Zero's GoogleMailManager (apps/server/src/lib/driver/google.ts) with CLI adaptations:
-//   - No HTML sanitization (CLI renders text)
-//   - No Effect library (simple retry loop)
-//   - Uses batchModify for label mutations (more efficient than per-thread modify)
-//   - Body decoding inline with Buffer (no base64-js dependency)
-//   - Concurrent hydration with configurable concurrency limit
+// Cache is built into the client for expensive read paths.
+// List/search entry-point calls always fetch fresh IDs and then reuse per-thread cache
+// to avoid repeated N+1 hydration calls.
+// Raw Google API responses are stored in the cache (gmail_v1.Schema$*) so the cache
+// is resilient to changes in our own parsed types. Parsing happens at read time.
+// When account is not provided (bootstrap/login flow), cache is skipped entirely.
 import { gmail as gmailApi } from '@googleapis/gmail';
 import { createMimeMessage } from 'mimetext';
 import { parseFrom, parseAddressList } from './email-utils.js';
-import { withRetry, mapConcurrent } from './api-utils.js';
+import * as errore from 'errore';
+import { withRetry, mapConcurrent, AuthError, isAuthLikeError, ApiError, NotFoundError, EmptyThreadError, MissingDataError } from './api-utils.js';
+import { renderEmailBody } from './output.js';
+import { getPrisma } from './db.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -37,6 +40,37 @@ function decodeBase64Url(encoded) {
     const base64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
     return Buffer.from(base64, 'base64').toString('utf-8');
 }
+function decodeHtmlEntities(value) {
+    const namedEntities = {
+        amp: '&',
+        lt: '<',
+        gt: '>',
+        quot: '"',
+        apos: "'",
+        nbsp: ' ',
+    };
+    return value.replace(/&(#x[0-9a-fA-F]+|#\d+|[a-zA-Z]+);/g, (match, entity) => {
+        if (entity.startsWith('#x') || entity.startsWith('#X')) {
+            const codePoint = Number.parseInt(entity.slice(2), 16);
+            if (!Number.isFinite(codePoint))
+                return match;
+            return String.fromCodePoint(codePoint);
+        }
+        if (entity.startsWith('#')) {
+            const codePoint = Number.parseInt(entity.slice(1), 10);
+            if (!Number.isFinite(codePoint))
+                return match;
+            return String.fromCodePoint(codePoint);
+        }
+        return namedEntities[entity.toLowerCase()] ?? match;
+    });
+}
+function sanitizeSnippet(snippet) {
+    return decodeHtmlEntities(snippet)
+        .replace(/[\u00A0\u00AD\u034F\u061C\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
 function encodeBase64Url(data) {
     const buf = typeof data === 'string' ? Buffer.from(data) : data;
     return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
@@ -44,90 +78,211 @@ function encodeBase64Url(data) {
 // ---------------------------------------------------------------------------
 // GmailClient
 // ---------------------------------------------------------------------------
+// TTL constants in milliseconds
+const TTL = {
+    THREAD: 30 * 60 * 1000, // 30 minutes
+    LABELS: 30 * 60 * 1000, // 30 minutes
+    PROFILE: 24 * 60 * 60 * 1000, // 24 hours
+};
+function isExpired(createdAt, ttlMs) {
+    return createdAt.getTime() + ttlMs < Date.now();
+}
+/** Boundary helper: wrap a googleapis SDK call, converting auth-like errors to AuthError values.
+ *  Non-auth errors are wrapped in ApiError so they remain error values (no throwing).
+ *  Original error is preserved as `cause` for debugging. */
+function gmailBoundary(email, fn) {
+    return errore.tryAsync({
+        try: fn,
+        catch: (err) => isAuthLikeError(err)
+            ? new AuthError({ email, reason: String(err) })
+            : new ApiError({ reason: String(err), cause: err }),
+    });
+}
 export class GmailClient {
     gmail;
     labelIdCache = {};
-    constructor({ auth }) {
+    account;
+    constructor({ auth, account }) {
         this.gmail = gmailApi({ version: 'v1', auth });
+        this.account = account ?? null;
+    }
+    // =========================================================================
+    // Cache helpers (private) — skip all cache ops when account is null
+    // =========================================================================
+    get cacheEnabled() {
+        return this.account !== null;
+    }
+    async getCachedThread(threadId) {
+        if (!this.cacheEnabled)
+            return undefined;
+        const prisma = await getPrisma();
+        const row = await prisma.thread.findUnique({
+            where: { email_appId_threadId: { email: this.account.email, appId: this.account.appId, threadId } },
+        });
+        if (!row || isExpired(row.createdAt, row.ttlMs))
+            return undefined;
+        return JSON.parse(row.rawData);
+    }
+    async cacheThreadData(threadId, raw, parsed) {
+        if (!this.cacheEnabled)
+            return;
+        const prisma = await getPrisma();
+        await prisma.thread.upsert({
+            where: { email_appId_threadId: { email: this.account.email, appId: this.account.appId, threadId } },
+            create: {
+                email: this.account.email, appId: this.account.appId, threadId,
+                subject: parsed.subject, snippet: parsed.snippet,
+                fromEmail: parsed.from.email, fromName: parsed.from.name ?? '',
+                date: parsed.date, labelIds: parsed.labelIds.join(','),
+                hasUnread: parsed.hasUnread, msgCount: parsed.messageCount,
+                historyId: parsed.historyId,
+                rawData: JSON.stringify(raw), ttlMs: TTL.THREAD, createdAt: new Date(),
+            },
+            update: {
+                subject: parsed.subject, snippet: parsed.snippet,
+                fromEmail: parsed.from.email, fromName: parsed.from.name ?? '',
+                date: parsed.date, labelIds: parsed.labelIds.join(','),
+                hasUnread: parsed.hasUnread, msgCount: parsed.messageCount,
+                historyId: parsed.historyId,
+                rawData: JSON.stringify(raw), ttlMs: TTL.THREAD, createdAt: new Date(),
+            },
+        });
+    }
+    async invalidateThreads(threadIds) {
+        if (!this.cacheEnabled)
+            return;
+        const prisma = await getPrisma();
+        await prisma.thread.deleteMany({ where: { email: this.account.email, appId: this.account.appId, threadId: { in: threadIds } } });
+    }
+    async invalidateThread(threadId) {
+        if (!this.cacheEnabled)
+            return;
+        const prisma = await getPrisma();
+        await prisma.thread.deleteMany({ where: { email: this.account.email, appId: this.account.appId, threadId } });
+    }
+    async getCachedLabels() {
+        if (!this.cacheEnabled)
+            return undefined;
+        const prisma = await getPrisma();
+        const row = await prisma.label.findUnique({ where: { email_appId: { email: this.account.email, appId: this.account.appId } } });
+        if (!row || isExpired(row.createdAt, row.ttlMs))
+            return undefined;
+        return JSON.parse(row.rawData);
+    }
+    async cacheLabelsData(raw) {
+        if (!this.cacheEnabled)
+            return;
+        const prisma = await getPrisma();
+        await prisma.label.upsert({
+            where: { email_appId: { email: this.account.email, appId: this.account.appId } },
+            create: { email: this.account.email, appId: this.account.appId, rawData: JSON.stringify(raw), ttlMs: TTL.LABELS, createdAt: new Date() },
+            update: { rawData: JSON.stringify(raw), ttlMs: TTL.LABELS, createdAt: new Date() },
+        });
+    }
+    async invalidateLabels() {
+        if (!this.cacheEnabled)
+            return;
+        const prisma = await getPrisma();
+        await prisma.label.deleteMany({ where: { email: this.account.email, appId: this.account.appId } });
+    }
+    async getCachedProfile() {
+        if (!this.cacheEnabled)
+            return undefined;
+        const prisma = await getPrisma();
+        const row = await prisma.profile.findUnique({ where: { email_appId: { email: this.account.email, appId: this.account.appId } } });
+        if (!row || isExpired(row.createdAt, row.ttlMs))
+            return undefined;
+        return { emailAddress: row.emailAddress, messagesTotal: row.messagesTotal, threadsTotal: row.threadsTotal, historyId: row.historyId };
+    }
+    async cacheProfileData(profile) {
+        if (!this.cacheEnabled)
+            return;
+        const prisma = await getPrisma();
+        await prisma.profile.upsert({
+            where: { email_appId: { email: this.account.email, appId: this.account.appId } },
+            create: { email: this.account.email, appId: this.account.appId, ...profile, ttlMs: TTL.PROFILE, createdAt: new Date() },
+            update: { ...profile, ttlMs: TTL.PROFILE, createdAt: new Date() },
+        });
     }
     // =========================================================================
     // Thread operations
     // =========================================================================
     async listThreads({ query, folder, maxResults = 25, labelIds, pageToken, } = {}) {
         const { q, resolvedLabelIds } = this.buildSearchParams(folder, query, labelIds);
-        const res = await withRetry(() => this.gmail.users.threads.list({
+        const res = await gmailBoundary(this.account?.email ?? 'unknown', () => withRetry(() => this.gmail.users.threads.list({
             userId: 'me',
             q: q || undefined,
             labelIds: resolvedLabelIds.length > 0 ? resolvedLabelIds : undefined,
             maxResults,
             pageToken: pageToken || undefined,
-        }));
+        })));
+        if (res instanceof Error)
+            return res;
         const rawThreads = res.data.threads ?? [];
-        // Hydrate with metadata
-        const threads = await mapConcurrent(rawThreads, async (t) => {
+        // Hydrate with metadata — collect both raw and parsed
+        const hydrated = await mapConcurrent(rawThreads, async (t) => {
             if (!t.id)
                 return null;
-            try {
-                const detail = await withRetry(() => this.gmail.users.threads.get({
-                    userId: 'me',
-                    id: t.id,
-                    format: 'metadata',
-                    metadataHeaders: ['Subject', 'From', 'Date', 'To'],
-                }));
-                return this.parseThreadListItem(t.id, detail.data);
+            const cached = await this.getCachedThread(t.id);
+            if (cached && (!t.historyId || !cached.historyId || t.historyId === cached.historyId)) {
+                return {
+                    parsed: GmailClient.parseRawThreadListItem(cached),
+                    raw: cached,
+                };
             }
-            catch {
+            // Boundary: threads.get — auth errors abort via mapConcurrent, others skip.
+            const detail = await gmailBoundary(this.account?.email ?? 'unknown', () => withRetry(() => this.gmail.users.threads.get({
+                userId: 'me',
+                id: t.id,
+                format: 'full',
+            })));
+            if (detail instanceof AuthError)
+                return detail;
+            if (detail instanceof Error)
                 return null;
-            }
+            const parsed = GmailClient.parseRawThread(detail.data);
+            await this.cacheThreadData(t.id, detail.data, parsed);
+            return {
+                parsed: GmailClient.parseRawThreadListItem(detail.data),
+                raw: detail.data,
+            };
         });
-        return {
-            threads: threads.filter((t) => t !== null),
+        if (hydrated instanceof Error)
+            return hydrated;
+        const valid = hydrated.filter((t) => t !== null);
+        const result = {
+            threads: valid.map((t) => t.parsed),
+            rawThreads: valid.map((t) => t.raw),
             nextPageToken: res.data.nextPageToken ?? null,
             resultSizeEstimate: res.data.resultSizeEstimate ?? 0,
         };
+        return result;
     }
     async getThread({ threadId }) {
+        // Check cache
+        const cached = await this.getCachedThread(threadId);
+        if (cached) {
+            return { parsed: GmailClient.parseRawThread(cached), raw: cached };
+        }
         const res = await withRetry(() => this.gmail.users.threads.get({
             userId: 'me',
             id: threadId,
             format: 'full',
         }));
-        if (!res.data.messages || res.data.messages.length === 0) {
-            return {
-                id: threadId,
-                historyId: res.data.historyId ?? null,
-                messages: [],
-                subject: '',
-                snippet: '',
-                from: { email: '' },
-                date: '',
-                labelIds: [],
-                hasUnread: false,
-                messageCount: 0,
-            };
-        }
-        const messages = res.data.messages.map((m) => this.parseMessage(m));
-        const latest = messages.findLast((m) => !m.isDraft) ?? messages[messages.length - 1];
-        const allLabels = [...new Set(messages.flatMap((m) => m.labelIds))];
-        return {
-            id: threadId,
-            historyId: res.data.historyId ?? null,
-            messages,
-            subject: latest.subject,
-            snippet: latest.snippet,
-            from: latest.from,
-            date: latest.date,
-            labelIds: allLabels,
-            hasUnread: messages.some((m) => m.unread),
-            messageCount: messages.filter((m) => !m.isDraft).length,
-        };
+        const parsed = GmailClient.parseRawThread(res.data);
+        const result = { parsed, raw: res.data };
+        // Write cache
+        await this.cacheThreadData(threadId, res.data, parsed);
+        return result;
     }
     async getMessage({ messageId, format = 'full', }) {
-        const res = await withRetry(() => this.gmail.users.messages.get({
+        const res = await gmailBoundary(this.account?.email ?? 'unknown', () => withRetry(() => this.gmail.users.messages.get({
             userId: 'me',
             id: messageId,
             format,
-        }));
+        })));
+        if (res instanceof Error)
+            return res;
         if (format === 'raw') {
             return {
                 id: messageId,
@@ -137,13 +292,15 @@ export class GmailClient {
         return this.parseMessage(res.data);
     }
     async getRawMessage({ messageId }) {
-        const res = await withRetry(() => this.gmail.users.messages.get({
+        const res = await gmailBoundary(this.account?.email ?? 'unknown', () => withRetry(() => this.gmail.users.messages.get({
             userId: 'me',
             id: messageId,
             format: 'raw',
-        }));
+        })));
+        if (res instanceof Error)
+            return res;
         if (!res.data.raw)
-            throw new Error('No raw email data found');
+            return new MissingDataError({ what: 'raw email data', resource: `message ${messageId}` });
         return decodeBase64Url(res.data.raw);
     }
     // =========================================================================
@@ -171,6 +328,86 @@ export class GmailClient {
         return res.data;
     }
     // =========================================================================
+    // Reply / Forward (high-level composition)
+    // =========================================================================
+    /**
+     * Reply to a thread. Handles reply-to resolution, reply-all CC computation,
+     * References/In-Reply-To headers, and subject prefixing.
+     */
+    async replyToThread({ threadId, body, replyAll = false, cc, fromEmail, }) {
+        const { parsed: thread } = await this.getThread({ threadId });
+        if (thread.messages.length === 0) {
+            return new EmptyThreadError({ threadId });
+        }
+        const lastMsg = thread.messages[thread.messages.length - 1];
+        const replyTo = lastMsg.replyTo ?? lastMsg.from.email;
+        const to = [{ email: replyTo }];
+        let resolvedCc;
+        if (replyAll) {
+            const profile = await this.getProfile();
+            if (profile instanceof Error)
+                return profile;
+            const myEmail = profile.emailAddress.toLowerCase();
+            const allRecipients = [
+                ...lastMsg.to.map((r) => r.email),
+                ...(lastMsg.cc?.map((r) => r.email) ?? []),
+            ]
+                .filter((e) => e.toLowerCase() !== myEmail)
+                .filter((e) => e.toLowerCase() !== replyTo.toLowerCase());
+            if (allRecipients.length > 0) {
+                resolvedCc = allRecipients.map((e) => ({ email: e }));
+            }
+        }
+        if (cc) {
+            resolvedCc = [...(resolvedCc ?? []), ...cc];
+        }
+        const refs = [lastMsg.references, lastMsg.messageId].filter(Boolean).join(' ');
+        const result = await this.sendMessage({
+            to,
+            subject: lastMsg.subject.startsWith('Re:') ? lastMsg.subject : `Re: ${lastMsg.subject}`,
+            body,
+            cc: resolvedCc,
+            threadId,
+            inReplyTo: lastMsg.messageId,
+            references: refs || undefined,
+            fromEmail,
+        });
+        await this.invalidateThread(threadId);
+        return result;
+    }
+    /**
+     * Forward a thread. Fetches the last message, renders its body,
+     * builds the "Forwarded message" block, and sends.
+     */
+    async forwardThread({ threadId, to, body, fromEmail, }) {
+        const { parsed: thread } = await this.getThread({ threadId });
+        if (thread.messages.length === 0) {
+            return new EmptyThreadError({ threadId });
+        }
+        const lastMsg = thread.messages[thread.messages.length - 1];
+        const renderedBody = renderEmailBody(lastMsg.body, lastMsg.mimeType);
+        const fromStr = lastMsg.from.name && lastMsg.from.name !== lastMsg.from.email
+            ? `${lastMsg.from.name} <${lastMsg.from.email}>`
+            : lastMsg.from.email;
+        const fullBody = [
+            body ?? '',
+            '',
+            '---------- Forwarded message ----------',
+            `From: ${fromStr}`,
+            `Date: ${lastMsg.date}`,
+            `Subject: ${lastMsg.subject}`,
+            `To: ${lastMsg.to.map((t) => t.email).join(', ')}`,
+            '',
+            renderedBody,
+        ].join('\n');
+        return this.sendMessage({
+            to,
+            subject: `Fwd: ${lastMsg.subject}`,
+            body: fullBody,
+            fromEmail,
+        });
+    }
+    // =========================================================================
     // Draft operations
     // =========================================================================
     async createDraft({ to, subject, body, cc, bcc, threadId, fromEmail, attachments, }) {
@@ -183,25 +420,16 @@ export class GmailClient {
         }));
         return res.data;
     }
-    async updateDraft({ draftId, to, subject, body, cc, bcc, threadId, fromEmail, attachments, }) {
-        const raw = this.buildMimeMessage({ to, subject, body, cc, bcc, attachments, fromEmail });
-        const res = await withRetry(() => this.gmail.users.drafts.update({
-            userId: 'me',
-            id: draftId,
-            requestBody: {
-                message: { raw, threadId },
-            },
-        }));
-        return res.data;
-    }
     async getDraft({ draftId }) {
-        const res = await withRetry(() => this.gmail.users.drafts.get({
+        const res = await gmailBoundary(this.account?.email ?? 'unknown', () => withRetry(() => this.gmail.users.drafts.get({
             userId: 'me',
             id: draftId,
             format: 'full',
-        }));
+        })));
+        if (res instanceof Error)
+            return res;
         if (!res.data || !res.data.message)
-            throw new Error('Draft not found');
+            return new NotFoundError({ resource: `draft ${draftId}` });
         const message = this.parseMessage(res.data.message);
         const headers = res.data.message.payload?.headers ?? [];
         return {
@@ -213,37 +441,41 @@ export class GmailClient {
         };
     }
     async listDrafts({ query, maxResults = 20, pageToken, } = {}) {
-        const res = await withRetry(() => this.gmail.users.drafts.list({
+        const res = await gmailBoundary(this.account?.email ?? 'unknown', () => withRetry(() => this.gmail.users.drafts.list({
             userId: 'me',
             q: query || undefined,
             maxResults,
             pageToken: pageToken || undefined,
-        }));
+        })));
+        if (res instanceof Error)
+            return res;
         const drafts = await mapConcurrent(res.data.drafts ?? [], async (draft) => {
             if (!draft.id)
                 return null;
-            try {
-                const detail = await withRetry(() => this.gmail.users.drafts.get({
-                    userId: 'me',
-                    id: draft.id,
-                    format: 'metadata',
-                }));
-                if (!detail.data.message)
-                    return null;
-                const headers = detail.data.message.payload?.headers ?? [];
-                return {
-                    id: draft.id,
-                    threadId: detail.data.message.threadId ?? null,
-                    subject: this.getHeader(headers, 'subject') ?? '(no subject)',
-                    to: this.getHeaderValues(headers, 'to'),
-                    date: this.getHeader(headers, 'date') ?? '',
-                    snippet: detail.data.message.snippet ?? '',
-                };
-            }
-            catch {
+            // Boundary: drafts.get — auth errors abort via mapConcurrent, others skip.
+            const detail = await gmailBoundary(this.account?.email ?? 'unknown', () => withRetry(() => this.gmail.users.drafts.get({
+                userId: 'me',
+                id: draft.id,
+                format: 'metadata',
+            })));
+            if (detail instanceof AuthError)
+                return detail;
+            if (detail instanceof Error)
                 return null;
-            }
+            if (!detail.data.message)
+                return null;
+            const headers = detail.data.message.payload?.headers ?? [];
+            return {
+                id: draft.id,
+                threadId: detail.data.message.threadId ?? null,
+                subject: this.getHeader(headers, 'subject') ?? '(no subject)',
+                to: this.getHeaderValues(headers, 'to'),
+                date: this.getHeader(headers, 'date') ?? '',
+                snippet: detail.data.message.snippet ?? '',
+            };
         });
+        if (drafts instanceof Error)
+            return drafts;
         return {
             drafts: drafts.filter((d) => d !== null),
             nextPageToken: res.data.nextPageToken ?? null,
@@ -267,63 +499,88 @@ export class GmailClient {
     // =========================================================================
     async markAsRead({ threadIds }) {
         const messageIds = await this.getMessageIdsForThreads(threadIds, (labelIds) => labelIds.includes('UNREAD'));
+        if (messageIds instanceof Error)
+            return messageIds;
         if (messageIds.length === 0)
             return;
         await this.batchModifyMessages(messageIds, { removeLabelIds: ['UNREAD'] });
+        await this.invalidateAfterThreadMutation(threadIds);
     }
     async markAsUnread({ threadIds }) {
         const messageIds = await this.getMessageIdsForThreads(threadIds, (labelIds) => !labelIds.includes('UNREAD'));
+        if (messageIds instanceof Error)
+            return messageIds;
         if (messageIds.length === 0)
             return;
         await this.batchModifyMessages(messageIds, { addLabelIds: ['UNREAD'] });
+        await this.invalidateAfterThreadMutation(threadIds);
     }
     async star({ threadIds }) {
         const messageIds = await this.getMessageIdsForThreads(threadIds);
+        if (messageIds instanceof Error)
+            return messageIds;
         if (messageIds.length === 0)
             return;
         await this.batchModifyMessages(messageIds, { addLabelIds: ['STARRED'] });
+        await this.invalidateAfterThreadMutation(threadIds);
     }
     async unstar({ threadIds }) {
         const messageIds = await this.getMessageIdsForThreads(threadIds, (labelIds) => labelIds.includes('STARRED'));
+        if (messageIds instanceof Error)
+            return messageIds;
         if (messageIds.length === 0)
             return;
         await this.batchModifyMessages(messageIds, { removeLabelIds: ['STARRED'] });
+        await this.invalidateAfterThreadMutation(threadIds);
     }
     async modifyLabels({ threadIds, addLabelIds = [], removeLabelIds = [], }) {
         // Resolve add labels (auto-create if missing), but only look up remove labels (never create)
         const resolvedAdd = await Promise.all(addLabelIds.map((l) => this.resolveLabelId(l)));
-        const resolvedRemove = (await Promise.all(removeLabelIds.map((l) => this.lookupLabelId(l)))).filter((id) => id !== null);
+        const addErr = resolvedAdd.find((r) => r instanceof Error);
+        if (addErr)
+            return addErr;
+        const resolvedRemoveRaw = await Promise.all(removeLabelIds.map((l) => this.lookupLabelId(l)));
+        const removeErr = resolvedRemoveRaw.find((r) => r instanceof Error);
+        if (removeErr)
+            return removeErr;
+        const resolvedRemove = resolvedRemoveRaw.filter((id) => typeof id === 'string');
         const messageIds = await this.getMessageIdsForThreads(threadIds);
+        if (messageIds instanceof Error)
+            return messageIds;
         if (messageIds.length === 0)
             return;
         await this.batchModifyMessages(messageIds, {
-            addLabelIds: resolvedAdd,
+            addLabelIds: resolvedAdd.filter((r) => typeof r === 'string'),
             removeLabelIds: resolvedRemove,
         });
+        await this.invalidateAfterThreadMutation(threadIds);
     }
     async trash({ threadId }) {
         await withRetry(() => this.gmail.users.threads.trash({
             userId: 'me',
             id: threadId,
         }));
+        await this.invalidateAfterThreadMutation([threadId]);
     }
     async untrash({ threadId }) {
         await withRetry(() => this.gmail.users.threads.untrash({
             userId: 'me',
             id: threadId,
         }));
+        await this.invalidateAfterThreadMutation([threadId]);
     }
     async archive({ threadIds }) {
         const messageIds = await this.getMessageIdsForThreads(threadIds);
+        if (messageIds instanceof Error)
+            return messageIds;
         if (messageIds.length === 0)
             return;
         await this.batchModifyMessages(messageIds, { removeLabelIds: ['INBOX'] });
+        await this.invalidateAfterThreadMutation(threadIds);
     }
-    async deleteMessage({ messageId }) {
-        await withRetry(() => this.gmail.users.messages.delete({
-            userId: 'me',
-            id: messageId,
-        }));
+    /** Invalidate thread cache after a thread mutation. */
+    async invalidateAfterThreadMutation(threadIds) {
+        await this.invalidateThreads(threadIds);
     }
     /** Moves all spam threads to trash. Does not permanently delete. */
     async trashAllSpam() {
@@ -335,10 +592,14 @@ export class GmailClient {
                 maxResults: 100,
                 pageToken,
             });
+            if (res instanceof Error)
+                return res;
             if (res.threads.length === 0)
                 break;
             const threadIds = res.threads.map((t) => t.id);
             const messageIds = await this.getMessageIdsForThreads(threadIds);
+            if (messageIds instanceof Error)
+                return messageIds;
             await this.batchModifyMessages(messageIds, {
                 addLabelIds: ['TRASH'],
                 removeLabelIds: ['SPAM', 'INBOX'],
@@ -354,20 +615,18 @@ export class GmailClient {
     // Labels CRUD
     // =========================================================================
     async listLabels() {
-        const res = await withRetry(() => this.gmail.users.labels.list({ userId: 'me' }));
-        return (res.data.labels?.map((label) => ({
-            id: label.id ?? '',
-            name: label.name ?? '',
-            type: (label.type ?? 'user'),
-            messageListVisibility: label.messageListVisibility ?? null,
-            labelListVisibility: label.labelListVisibility ?? null,
-            color: label.color
-                ? {
-                    backgroundColor: label.color.backgroundColor ?? '',
-                    textColor: label.color.textColor ?? '',
-                }
-                : null,
-        })) ?? []);
+        // Check cache
+        const cached = await this.getCachedLabels();
+        if (cached) {
+            return { parsed: GmailClient.parseRawLabels(cached), raw: cached };
+        }
+        const res = await gmailBoundary(this.account?.email ?? 'unknown', () => withRetry(() => this.gmail.users.labels.list({ userId: 'me' })));
+        if (res instanceof Error)
+            return res;
+        const rawLabels = res.data.labels ?? [];
+        // Write cache
+        await this.cacheLabelsData(rawLabels);
+        return { parsed: GmailClient.parseRawLabels(rawLabels), raw: rawLabels };
     }
     async getLabel({ labelId }) {
         const res = await withRetry(() => this.gmail.users.labels.get({
@@ -400,72 +659,71 @@ export class GmailClient {
                 color,
             },
         }));
+        await this.invalidateLabels();
         return {
             id: res.data.id ?? '',
             name: res.data.name ?? name,
         };
     }
-    async updateLabel({ labelId, name, color, }) {
-        await withRetry(() => this.gmail.users.labels.update({
-            userId: 'me',
-            id: labelId,
-            requestBody: {
-                name,
-                color,
-            },
-        }));
-        // Invalidate label ID cache since name may have changed
-        this.labelIdCache = {};
-    }
     async deleteLabel({ labelId }) {
         await withRetry(() => this.gmail.users.labels.delete({
             userId: 'me',
             id: labelId,
         }));
-        // Invalidate label ID cache
         this.labelIdCache = {};
+        await this.invalidateLabels();
     }
     // =========================================================================
     // Label counts (unread counts per folder/label)
     // =========================================================================
     async getLabelCounts() {
-        // Fetch label counts and archive count concurrently
-        const [labels, archiveRes] = await Promise.all([
-            this.listLabels(),
-            withRetry(() => this.gmail.users.threads.list({
-                userId: 'me',
-                q: 'in:archive',
-                maxResults: 1,
-            })).catch(() => null),
-        ]);
-        const counts = await mapConcurrent(labels, async (label) => {
+        // Always fresh: label counts are user-facing live data.
+        // Archive count is best-effort — auth errors propagate, others yield null.
+        const archiveRes = await gmailBoundary(this.account?.email ?? 'unknown', () => withRetry(() => this.gmail.users.threads.list({
+            userId: 'me',
+            q: 'in:archive',
+            maxResults: 1,
+        })));
+        if (archiveRes instanceof AuthError)
+            return archiveRes;
+        // archiveRes may be ApiError (non-auth failure) — archive count unavailable
+        const labelsResult = await this.listLabels();
+        if (labelsResult instanceof Error)
+            return labelsResult;
+        // Fetch detailed counts for each label — collect both raw and parsed
+        const rawDetails = [];
+        const counts = await mapConcurrent(labelsResult.parsed, async (label) => {
             if (!label.id)
                 return null;
-            try {
-                const detail = await withRetry(() => this.gmail.users.labels.get({
-                    userId: 'me',
-                    id: label.id,
-                }));
-                const labelName = (detail.data.name ?? detail.data.id ?? '').toLowerCase();
-                const isTotalLabel = labelName === 'draft' || labelName === 'sent';
-                return {
-                    label: labelName === 'draft' ? 'drafts' : labelName,
-                    count: Number(isTotalLabel ? detail.data.threadsTotal : detail.data.threadsUnread) || 0,
-                };
-            }
-            catch {
+            // Boundary: labels.get — auth errors abort via mapConcurrent, others skip.
+            const detail = await gmailBoundary(this.account?.email ?? 'unknown', () => withRetry(() => this.gmail.users.labels.get({
+                userId: 'me',
+                id: label.id,
+            })));
+            if (detail instanceof AuthError)
+                return detail;
+            if (detail instanceof Error)
                 return null;
-            }
+            rawDetails.push(detail.data);
+            const labelName = (detail.data.name ?? detail.data.id ?? '').toLowerCase();
+            const isTotalLabel = labelName === 'draft' || labelName === 'sent';
+            return {
+                label: labelName === 'draft' ? 'drafts' : labelName,
+                count: Number(isTotalLabel ? detail.data.threadsTotal : detail.data.threadsUnread) || 0,
+            };
         });
+        if (counts instanceof Error)
+            return counts;
         const result = counts.filter((c) => c !== null);
         // Add archive count (same as Zero's count() method)
-        if (archiveRes) {
+        if (!(archiveRes instanceof Error)) {
             result.push({
                 label: 'archive',
                 count: Number(archiveRes.data.resultSizeEstimate ?? 0),
             });
         }
-        return result;
+        const archiveEstimate = !(archiveRes instanceof Error) ? Number(archiveRes.data.resultSizeEstimate ?? 0) : null;
+        return { parsed: result, raw: rawDetails, archiveEstimate };
     }
     // =========================================================================
     // Attachments
@@ -480,229 +738,202 @@ export class GmailClient {
         // Convert base64url to standard base64
         return data.replace(/-/g, '+').replace(/_/g, '/');
     }
-    async getMessageAttachments({ messageId }) {
-        const res = await withRetry(() => this.gmail.users.messages.get({
-            userId: 'me',
-            id: messageId,
-        }));
-        const parts = res.data.payload?.parts;
-        if (!parts)
-            return [];
-        const attachmentParts = this.findAttachmentParts(parts);
-        const attachments = await mapConcurrent(attachmentParts, async (part) => {
-            const attId = part.body?.attachmentId;
-            if (!attId)
-                return null;
-            try {
-                const data = await this.getAttachment({ messageId, attachmentId: attId });
-                return {
-                    filename: part.filename ?? '',
-                    mimeType: part.mimeType ?? '',
-                    size: Number(part.body?.size ?? 0),
-                    attachmentId: attId,
-                    data,
-                };
-            }
-            catch {
-                return null;
-            }
-        });
-        return attachments.filter((a) => a !== null);
-    }
     // =========================================================================
     // Account / profile
     // =========================================================================
     async getProfile() {
-        const res = await withRetry(() => this.gmail.users.getProfile({ userId: 'me' }));
-        return {
+        // Check cache
+        const cached = await this.getCachedProfile();
+        if (cached)
+            return cached;
+        const res = await gmailBoundary(this.account?.email ?? 'unknown', () => withRetry(() => this.gmail.users.getProfile({ userId: 'me' })));
+        if (res instanceof Error)
+            return res;
+        const profile = {
             emailAddress: res.data.emailAddress ?? '',
             messagesTotal: res.data.messagesTotal ?? 0,
             threadsTotal: res.data.threadsTotal ?? 0,
             historyId: res.data.historyId ?? '',
         };
-    }
-    async getEmailAliases() {
-        const profile = await this.getProfile();
-        const primaryEmail = profile.emailAddress;
-        const aliases = [
-            { email: primaryEmail, primary: true },
-        ];
-        try {
-            const settings = await withRetry(() => this.gmail.users.settings.sendAs.list({ userId: 'me' }));
-            for (const alias of settings.data.sendAs ?? []) {
-                if (alias.isPrimary && alias.sendAsEmail === primaryEmail)
-                    continue;
-                aliases.push({
-                    email: alias.sendAsEmail ?? '',
-                    name: alias.displayName ?? undefined,
-                    primary: alias.isPrimary ?? false,
-                });
-            }
-        }
-        catch {
-            // sendAs.list may fail if the user doesn't have permission
-        }
-        return aliases;
+        // Write cache
+        await this.cacheProfileData(profile);
+        return profile;
     }
     // =========================================================================
-    // History / sync
+    // Static: parse raw Google API responses (used by cache readers)
     // =========================================================================
-    async listHistory({ startHistoryId, labelId, historyTypes, }) {
-        const allHistory = [];
-        let pageToken;
-        let latestHistoryId = startHistoryId;
-        while (true) {
-            const res = await withRetry(() => this.gmail.users.history.list({
-                userId: 'me',
-                startHistoryId,
-                labelId,
-                historyTypes,
-                pageToken,
-            }));
-            if (res.data.history) {
-                allHistory.push(...res.data.history);
-            }
-            latestHistoryId = res.data.historyId ?? latestHistoryId;
-            pageToken = res.data.nextPageToken ?? undefined;
-            if (!pageToken)
-                break;
+    /** Parse a raw gmail_v1.Schema$Thread (format: full) into ThreadData. */
+    static parseRawThread(raw) {
+        const messages = (raw.messages ?? []).map((m) => GmailClient.parseRawMessage(m));
+        if (messages.length === 0) {
+            return {
+                id: raw.id ?? '',
+                historyId: raw.historyId ?? null,
+                messages: [],
+                subject: '',
+                snippet: '',
+                from: { email: '' },
+                date: '',
+                labelIds: [],
+                hasUnread: false,
+                messageCount: 0,
+            };
         }
+        const latest = messages.findLast((m) => !m.isDraft) ?? messages[messages.length - 1];
+        const allLabels = [...new Set(messages.flatMap((m) => m.labelIds))];
         return {
-            history: allHistory,
-            historyId: latestHistoryId,
-        };
-    }
-    // NOTE: This method wraps Gmail's push notification API (users.watch),
-    // which requires a Google Cloud Pub/Sub topic. Since zele uses borrowed
-    // OAuth credentials (Thunderbird's client ID), we cannot create Pub/Sub
-    // resources on their GCP project. Users would need their own GCP project,
-    // which defeats the zero-config design. The CLI uses History API polling
-    // instead (see src/commands/watch.ts). This method is kept for potential
-    // future use if users bring their own GCP credentials.
-    async watch({ topicName, labelIds = ['INBOX'], }) {
-        const res = await withRetry(() => this.gmail.users.watch({
-            userId: 'me',
-            requestBody: {
-                topicName,
-                labelIds,
-            },
-        }));
-        return {
-            historyId: res.data.historyId ?? '',
-            expiration: res.data.expiration ?? '',
+            id: raw.id ?? '',
+            historyId: raw.historyId ?? null,
+            messages,
+            subject: latest.subject,
+            snippet: latest.snippet,
+            from: latest.from,
+            date: latest.date,
+            labelIds: allLabels,
+            hasUnread: messages.some((m) => m.unread),
+            messageCount: messages.filter((m) => !m.isDraft).length,
         };
     }
-    async stopWatch() {
-        await withRetry(() => this.gmail.users.stop({ userId: 'me' }));
-    }
-    // =========================================================================
-    // Private: message parsing
-    // =========================================================================
-    parseMessage(message) {
+    /** Parse a raw gmail_v1.Schema$Message into ParsedMessage. */
+    static parseRawMessage(message) {
         const headers = message.payload?.headers ?? [];
         const labelIds = message.labelIds ?? [];
-        const fromHeader = this.getHeader(headers, 'from') ?? '';
-        const toHeader = this.getHeader(headers, 'to') ?? '';
-        const ccHeaders = this.getHeaderAll(headers, 'cc');
-        const { body, mimeType } = this.extractBody(message.payload ?? {});
+        const getHeader = (name) => headers.find((h) => h.name?.toLowerCase() === name.toLowerCase())?.value ?? null;
+        const fromHeader = getHeader('from') ?? '';
+        const toHeader = getHeader('to') ?? '';
+        const ccHeaders = headers
+            .filter((h) => h.name?.toLowerCase() === 'cc')
+            .map((h) => h.value ?? '')
+            .filter((v) => v.length > 0);
+        const { body, mimeType, textBody } = GmailClient.extractBodyStatic(message.payload ?? {});
         return {
             id: message.id ?? '',
             threadId: message.threadId ?? '',
-            subject: (this.getHeader(headers, 'subject') ?? '(no subject)').replace(/"/g, '').trim(),
-            snippet: message.snippet ?? '',
+            subject: (getHeader('subject') ?? '(no subject)').replace(/"/g, '').trim(),
+            snippet: sanitizeSnippet(message.snippet ?? ''),
             from: parseFrom(fromHeader),
             to: toHeader ? parseAddressList(toHeader) : [],
             cc: ccHeaders.length > 0
                 ? ccHeaders.filter((h) => h.trim().length > 0).flatMap((h) => parseAddressList(h))
                 : null,
             bcc: [],
-            replyTo: this.getHeader(headers, 'reply-to') ?? undefined,
-            date: this.getHeader(headers, 'date') ?? '',
+            replyTo: getHeader('reply-to') ?? undefined,
+            date: getHeader('date') ?? '',
             labelIds,
             unread: labelIds.includes('UNREAD'),
             starred: labelIds.includes('STARRED'),
             isDraft: labelIds.includes('DRAFT'),
-            messageId: this.getHeader(headers, 'message-id') ?? '',
-            inReplyTo: this.getHeader(headers, 'in-reply-to') ?? undefined,
-            references: this.getHeader(headers, 'references') ?? undefined,
-            listUnsubscribe: this.getHeader(headers, 'list-unsubscribe') ?? undefined,
+            messageId: getHeader('message-id') ?? '',
+            inReplyTo: getHeader('in-reply-to') ?? undefined,
+            references: getHeader('references') ?? undefined,
+            listUnsubscribe: getHeader('list-unsubscribe') ?? undefined,
             body,
             mimeType,
-            attachments: this.extractAttachmentMeta(message.payload?.parts ?? []),
+            textBody,
+            attachments: GmailClient.extractAttachmentMetaStatic(message.payload?.parts ?? []),
         };
     }
-    parseThreadListItem(threadId, thread) {
-        const messages = thread.messages ?? [];
-        // Use the last non-draft message, or the last message
+    /** Parse raw gmail_v1.Schema$Thread (format: metadata) into ThreadListItem. */
+    static parseRawThreadListItem(raw) {
+        const messages = raw.messages ?? [];
         const latest = messages.findLast((m) => !m.labelIds?.includes('DRAFT')) ?? messages[messages.length - 1];
         const headers = latest?.payload?.headers ?? [];
         const allLabels = [...new Set(messages.flatMap((m) => m.labelIds ?? []))];
+        const getHeader = (name) => headers.find((h) => h.name?.toLowerCase() === name.toLowerCase())?.value ?? null;
         return {
-            id: threadId,
-            historyId: thread.historyId ?? null,
-            snippet: latest?.snippet ?? '',
-            subject: (this.getHeader(headers, 'subject') ?? '(no subject)').replace(/"/g, '').trim(),
-            from: parseFrom(this.getHeader(headers, 'from') ?? ''),
-            date: this.getHeader(headers, 'date') ?? '',
+            id: raw.id ?? '',
+            historyId: raw.historyId ?? null,
+            snippet: sanitizeSnippet(latest?.snippet ?? ''),
+            subject: (getHeader('subject') ?? '(no subject)').replace(/"/g, '').trim(),
+            from: parseFrom(getHeader('from') ?? ''),
+            date: getHeader('date') ?? '',
             labelIds: allLabels,
             unread: allLabels.includes('UNREAD'),
             messageCount: messages.filter((m) => !m.labelIds?.includes('DRAFT')).length,
         };
     }
+    /** Parse raw gmail_v1.Schema$Label[] from labels.list into our label objects. */
+    static parseRawLabels(rawLabels) {
+        return rawLabels.map((label) => ({
+            id: label.id ?? '',
+            name: label.name ?? '',
+            type: (label.type ?? 'user'),
+            messageListVisibility: label.messageListVisibility ?? null,
+            labelListVisibility: label.labelListVisibility ?? null,
+            color: label.color
+                ? {
+                    backgroundColor: label.color.backgroundColor ?? '',
+                    textColor: label.color.textColor ?? '',
+                }
+                : null,
+        }));
+    }
+    /** Parse raw gmail_v1.Schema$Label[] (with counts) into label count objects. */
+    static parseRawLabelCounts(rawLabels, archiveEstimate) {
+        const result = rawLabels
+            .map((detail) => {
+            const labelName = (detail.name ?? detail.id ?? '').toLowerCase();
+            const isTotalLabel = labelName === 'draft' || labelName === 'sent';
+            return {
+                label: labelName === 'draft' ? 'drafts' : labelName,
+                count: Number(isTotalLabel ? detail.threadsTotal : detail.threadsUnread) || 0,
+            };
+        });
+        if (archiveEstimate !== null) {
+            result.push({ label: 'archive', count: archiveEstimate });
+        }
+        return result;
+    }
     // =========================================================================
-    // Private: body extraction
+    // Private static: body/attachment extraction (for static parse methods)
     // =========================================================================
-    extractBody(payload) {
-        // Direct body on payload
+    static extractBodyStatic(payload) {
         if (payload.body?.data) {
+            const mime = payload.mimeType ?? 'text/plain';
             return {
                 body: decodeBase64Url(payload.body.data),
-                mimeType: payload.mimeType ?? 'text/plain',
+                mimeType: mime,
+                textBody: mime === 'text/plain' ? decodeBase64Url(payload.body.data) : null,
             };
         }
         if (!payload.parts) {
-            return { body: '', mimeType: 'text/plain' };
+            return { body: '', mimeType: 'text/plain', textBody: null };
         }
-        // Prefer text/html, fallback to text/plain
-        const htmlBody = this.findBodyPart(payload.parts, 'text/html');
-        if (htmlBody) {
-            return { body: decodeBase64Url(htmlBody), mimeType: 'text/html' };
+        const htmlData = GmailClient.findBodyPartStatic(payload.parts, 'text/html');
+        const textData = GmailClient.findBodyPartStatic(payload.parts, 'text/plain');
+        const textBody = textData ? decodeBase64Url(textData) : null;
+        if (htmlData) {
+            return { body: decodeBase64Url(htmlData), mimeType: 'text/html', textBody };
         }
-        const textBody = this.findBodyPart(payload.parts, 'text/plain');
-        if (textBody) {
-            return { body: decodeBase64Url(textBody), mimeType: 'text/plain' };
+        if (textData) {
+            return { body: textBody, mimeType: 'text/plain', textBody };
         }
-        // Nested multipart (e.g. multipart/alternative inside multipart/mixed)
         for (const part of payload.parts) {
             if (part.parts) {
-                const nested = this.extractBody(part);
+                const nested = GmailClient.extractBodyStatic(part);
                 if (nested.body)
                     return nested;
             }
         }
-        return { body: '', mimeType: 'text/plain' };
+        return { body: '', mimeType: 'text/plain', textBody: null };
     }
-    findBodyPart(parts, mimeType) {
+    static findBodyPartStatic(parts, mimeType) {
         for (const part of parts) {
             if (part.mimeType === mimeType && part.body?.data) {
                 return part.body.data;
             }
             if (part.parts) {
-                const found = this.findBodyPart(part.parts, mimeType);
+                const found = GmailClient.findBodyPartStatic(part.parts, mimeType);
                 if (found)
                     return found;
             }
         }
         return null;
     }
-    // =========================================================================
-    // Private: attachment handling
-    // =========================================================================
-    extractAttachmentMeta(parts) {
+    static extractAttachmentMetaStatic(parts) {
         const results = [];
         for (const part of parts) {
             if (part.filename && part.filename.length > 0 && part.body?.attachmentId) {
-                // Skip inline images (content-disposition: inline with content-id)
                 const disposition = part.headers?.find((h) => h.name?.toLowerCase() === 'content-disposition')?.value ?? '';
                 const hasContentId = part.headers?.some((h) => h.name?.toLowerCase() === 'content-id');
                 const isInline = disposition.toLowerCase().includes('inline');
@@ -715,30 +946,182 @@ export class GmailClient {
                     });
                 }
             }
-            // Recurse into nested parts
             if (part.parts) {
-                results.push(...this.extractAttachmentMeta(part.parts));
+                results.push(...GmailClient.extractAttachmentMetaStatic(part.parts));
             }
         }
         return results;
     }
-    findAttachmentParts(parts) {
-        const results = [];
-        for (const part of parts) {
-            if (part.filename && part.filename.length > 0 && part.body?.attachmentId) {
-                // Filter out inline CID images (same logic as Zero's findAttachments)
-                const disposition = part.headers?.find((h) => h.name?.toLowerCase() === 'content-disposition')?.value ?? '';
-                const isInline = disposition.toLowerCase().includes('inline');
-                const hasContentId = part.headers?.some((h) => h.name?.toLowerCase() === 'content-id');
-                if (!isInline || !hasContentId) {
-                    results.push(part);
-                }
+    async getEmailAliases() {
+        const profile = await this.getProfile();
+        if (profile instanceof Error)
+            return profile;
+        const primaryEmail = profile.emailAddress;
+        const aliases = [
+            { email: primaryEmail, primary: true },
+        ];
+        // Boundary: sendAs.list — auth errors propagate; permission-denied is expected
+        // (some accounts lack Gmail settings access) and yields primary email only.
+        const settings = await gmailBoundary(this.account?.email ?? 'unknown', () => withRetry(() => this.gmail.users.settings.sendAs.list({ userId: 'me' })));
+        if (settings instanceof AuthError)
+            return settings;
+        if (settings instanceof Error)
+            return aliases; // permission denied — return primary only
+        for (const alias of settings.data.sendAs ?? []) {
+            if (alias.isPrimary && alias.sendAsEmail === primaryEmail)
+                continue;
+            aliases.push({
+                email: alias.sendAsEmail ?? '',
+                name: alias.displayName ?? undefined,
+                primary: alias.isPrimary ?? false,
+            });
+        }
+        return aliases;
+    }
+    // =========================================================================
+    // History / sync
+    // =========================================================================
+    async listHistory({ startHistoryId, labelId, historyTypes, }) {
+        const allHistory = [];
+        let pageToken;
+        let latestHistoryId = startHistoryId;
+        while (true) {
+            const res = await gmailBoundary(this.account?.email ?? 'unknown', () => withRetry(() => this.gmail.users.history.list({
+                userId: 'me',
+                startHistoryId,
+                labelId,
+                historyTypes,
+                pageToken,
+            })));
+            if (res instanceof Error)
+                return res;
+            if (res.data.history) {
+                allHistory.push(...res.data.history);
             }
-            if (part.parts) {
-                results.push(...this.findAttachmentParts(part.parts));
+            latestHistoryId = res.data.historyId ?? latestHistoryId;
+            pageToken = res.data.nextPageToken ?? undefined;
+            if (!pageToken)
+                break;
+        }
+        return {
+            history: allHistory,
+            historyId: latestHistoryId,
+        };
+    }
+    // =========================================================================
+    // Watch: async generator for inbox polling via History API
+    // =========================================================================
+    /**
+     * Poll for new messages using the Gmail History API.
+     * Yields WatchEvent objects as new messages arrive.
+     * Handles history seeding, expiry re-seeding, and client-side query filtering.
+     * Persists historyId in the DB so it survives across CLI invocations.
+     */
+    async *watchInbox({ folder = 'inbox', intervalMs = 15_000, query, once = false, } = {}) {
+        if (!this.account)
+            throw new MissingDataError({ what: 'authenticated account', resource: 'watchInbox' });
+        const filterLabelId = WATCH_FOLDER_LABELS[folder];
+        if (!filterLabelId) {
+            throw new NotFoundError({ resource: `watch folder "${folder}". Supported: ${Object.keys(WATCH_FOLDER_LABELS).join(', ')}` });
+        }
+        // Seed historyId — guaranteed non-undefined after this block
+        let historyId = await getLastHistoryId(this.account) ?? '';
+        if (!historyId) {
+            const profile = await this.getProfile();
+            if (profile instanceof Error)
+                throw profile;
+            historyId = profile.historyId;
+            await setLastHistoryId(this.account, historyId);
+        }
+        while (true) {
+            // listHistory returns errors as values — check and handle history expiry.
+            const historyResult = await this.listHistory({
+                startHistoryId: historyId,
+                labelId: filterLabelId,
+                historyTypes: ['messageAdded'],
+            });
+            if (historyResult instanceof Error) {
+                if (!isHistoryExpired(historyResult))
+                    throw historyResult;
+                // historyId expired — Google only keeps ~7 days. Re-seed.
+                const profile = await this.getProfile();
+                if (profile instanceof Error)
+                    throw profile;
+                historyId = profile.historyId;
+                await setLastHistoryId(this.account, historyId);
+                // Retry once after reseed
+                const retryResult = await this.listHistory({ startHistoryId: historyId, labelId: filterLabelId, historyTypes: ['messageAdded'] });
+                if (retryResult instanceof Error)
+                    throw retryResult;
+                yield* this.pollOnceFromHistory(retryResult, historyId, query, (newId) => { historyId = newId; });
+            }
+            else {
+                yield* this.pollOnceFromHistory(historyResult, historyId, query, (newId) => { historyId = newId; });
             }
+            if (once)
+                return;
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+    }
+    /** Single poll tick from pre-fetched history — yields WatchEvents for new messages. */
+    async *pollOnceFromHistory(historyData, prevHistoryId, query, updateHistoryId) {
+        const { history, historyId: newHistoryId } = historyData;
+        if (newHistoryId !== prevHistoryId) {
+            updateHistoryId(newHistoryId);
+            await setLastHistoryId(this.account, newHistoryId);
+        }
+        if (history.length === 0)
+            return;
+        // Collect unique message IDs from messageAdded events
+        const seenIds = new Set();
+        const messageIds = [];
+        for (const entry of history) {
+            for (const added of entry.messagesAdded ?? []) {
+                const id = added.message?.id;
+                if (id && !seenIds.has(id)) {
+                    seenIds.add(id);
+                    messageIds.push(id);
+                }
+            }
+        }
+        if (messageIds.length === 0)
+            return;
+        // Hydrate messages with metadata (bounded concurrency).
+        // getMessage returns errors as values — auth errors abort via mapConcurrent,
+        // 404s (message deleted between history and hydration) are skipped.
+        const hydrated = await mapConcurrent(messageIds, async (msgId) => {
+            const msg = await this.getMessage({ messageId: msgId, format: 'metadata' });
+            if (msg instanceof AuthError)
+                return msg; // abort batch
+            if (msg instanceof Error)
+                return null; // skip this message
+            if ('raw' in msg)
+                return null;
+            if (query && !matchesQuery(msg, query))
+                return null;
+            return msg;
+        });
+        if (hydrated instanceof Error)
+            throw hydrated; // propagate to generator consumer
+        for (const msg of hydrated) {
+            if (!msg)
+                continue;
+            yield {
+                account: this.account,
+                type: 'new_message',
+                message: msg,
+                threadId: msg.threadId,
+            };
         }
-        return results;
+    }
+    // =========================================================================
+    // Private: message parsing (delegates to static methods)
+    // =========================================================================
+    parseMessage(message) {
+        return GmailClient.parseRawMessage(message);
+    }
+    parseThreadListItem(threadId, thread) {
+        return GmailClient.parseRawThreadListItem({ ...thread, id: threadId });
     }
     // =========================================================================
     // Private: MIME message construction
@@ -799,7 +1182,10 @@ export class GmailClient {
             return labelNameOrId;
         if (this.labelIdCache[labelNameOrId])
             return this.labelIdCache[labelNameOrId];
-        const labels = await this.listLabels();
+        const labelsResult = await this.listLabels();
+        if (labelsResult instanceof Error)
+            return labelsResult;
+        const { parsed: labels } = labelsResult;
         const match = labels.find((l) => l.name.toLowerCase() === labelNameOrId.toLowerCase());
         if (match) {
             this.labelIdCache[labelNameOrId] = match.id;
@@ -813,7 +1199,10 @@ export class GmailClient {
             return labelNameOrId;
         if (this.labelIdCache[labelNameOrId])
             return this.labelIdCache[labelNameOrId];
-        const labels = await this.listLabels();
+        const labelsResult = await this.listLabels();
+        if (labelsResult instanceof Error)
+            return labelsResult;
+        const { parsed: labels } = labelsResult;
         const match = labels.find((l) => l.name.toLowerCase() === labelNameOrId.toLowerCase());
         if (match) {
             this.labelIdCache[labelNameOrId] = match.id;
@@ -879,12 +1268,14 @@ export class GmailClient {
     // =========================================================================
     async getMessageIdsForThreads(threadIds, filter) {
         const allIds = [];
-        await mapConcurrent(threadIds, async (threadId) => {
-            const res = await withRetry(() => this.gmail.users.threads.get({
+        const result = await mapConcurrent(threadIds, async (threadId) => {
+            const res = await gmailBoundary(this.account?.email ?? 'unknown', () => withRetry(() => this.gmail.users.threads.get({
                 userId: 'me',
                 id: threadId,
                 format: 'metadata',
-            }));
+            })));
+            if (res instanceof Error)
+                return res;
             for (const msg of res.data.messages ?? []) {
                 if (!msg.id)
                     continue;
@@ -893,6 +1284,8 @@ export class GmailClient {
                 allIds.push(msg.id);
             }
         });
+        if (result instanceof Error)
+            return result;
         return [...new Set(allIds)];
     }
     async batchModifyMessages(messageIds, body) {
@@ -931,4 +1324,151 @@ export class GmailClient {
             .filter(Boolean));
     }
 }
+// ---------------------------------------------------------------------------
+// Watch: folder label mapping
+// ---------------------------------------------------------------------------
+const WATCH_FOLDER_LABELS = {
+    inbox: 'INBOX',
+    sent: 'SENT',
+    trash: 'TRASH',
+    spam: 'SPAM',
+    starred: 'STARRED',
+    drafts: 'DRAFT',
+};
+// ---------------------------------------------------------------------------
+// Watch: sync state persistence (historyId in DB)
+// ---------------------------------------------------------------------------
+async function getLastHistoryId(account) {
+    const prisma = await getPrisma();
+    const row = await prisma.syncState.findUnique({
+        where: { email_appId_key: { email: account.email, appId: account.appId, key: 'history_id' } },
+    });
+    return row?.value;
+}
+async function setLastHistoryId(account, historyId) {
+    const prisma = await getPrisma();
+    await prisma.syncState.upsert({
+        where: { email_appId_key: { email: account.email, appId: account.appId, key: 'history_id' } },
+        create: { email: account.email, appId: account.appId, key: 'history_id', value: historyId },
+        update: { value: historyId },
+    });
+}
+// ---------------------------------------------------------------------------
+// Watch: history expiry detection
+// ---------------------------------------------------------------------------
+function isHistoryExpired(err) {
+    const status = err?.code ?? err?.status ?? err?.response?.status;
+    if (status === 404)
+        return true;
+    if (status === 400) {
+        const message = err?.message ?? err?.response?.data?.error?.message ?? '';
+        if (message.includes('historyId'))
+            return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Watch: client-side Gmail query matching
+// ---------------------------------------------------------------------------
+// The History API doesn't support server-side query filtering, so we parse
+// common Gmail search operators and match against message metadata.
+//
+// Supported operators: from:, to:, cc:, subject:, is:unread/read/starred,
+// has:attachment, and plain text (matches subject + from).
+// Multiple terms are AND-ed together. Quoted phrases and negation supported.
+//
+// Limitations vs full Gmail search:
+// - label: not supported (labelIds are API IDs like Label_123, not names)
+// - has:attachment uses Content-Type heuristic (metadata format lacks parts)
+// - OR, {}, newer_than:, older_than:, etc. are server-only — warned & skipped
+//
+// See https://support.google.com/mail/answer/7190 for the full Gmail spec.
+// ---------------------------------------------------------------------------
+const SERVER_ONLY_OPERATORS = new Set([
+    'in', 'label', 'after', 'before', 'newer_than', 'older_than',
+    'filename', 'size', 'larger', 'smaller', 'deliveredto', 'rfc822msgid',
+    'list', 'category',
+]);
+const SUPPORTED_OPERATORS = new Set([
+    'from', 'to', 'cc', 'subject', 'is', 'has',
+]);
+const warnedOperators = new Set();
+function matchesQuery(msg, query) {
+    const terms = parseQueryTerms(query);
+    return terms.every((term) => matchesTerm(msg, term));
+}
+function parseQueryTerms(query) {
+    const terms = [];
+    const regex = /(-?)(?:(\w+):)?(?:"([^"]*)"|([\S]+))/gi;
+    let match;
+    while ((match = regex.exec(query)) !== null) {
+        const negated = match[1] === '-';
+        const rawOperator = match[2]?.toLowerCase() ?? null;
+        const value = (match[3] ?? match[4] ?? '').toLowerCase();
+        if (!value)
+            continue;
+        if (!rawOperator && value === 'or')
+            continue;
+        if (rawOperator && SERVER_ONLY_OPERATORS.has(rawOperator)) {
+            if (!warnedOperators.has(rawOperator)) {
+                warnedOperators.add(rawOperator);
+                console.error(`# --query: "${rawOperator}:" is a server-only operator (use "mail search" instead), skipping`);
+            }
+            continue;
+        }
+        if (rawOperator && !SUPPORTED_OPERATORS.has(rawOperator)) {
+            if (!warnedOperators.has(rawOperator)) {
+                warnedOperators.add(rawOperator);
+                console.error(`# --query: unknown operator "${rawOperator}:", skipping`);
+            }
+            continue;
+        }
+        terms.push({ operator: rawOperator, value, negated });
+    }
+    return terms;
+}
+function senderMatches(sender, value) {
+    const full = `${sender.name ?? ''} ${sender.email}`.toLowerCase();
+    return full.includes(value);
+}
+function matchesTerm(msg, term) {
+    let result;
+    switch (term.operator) {
+        case 'from':
+            result = senderMatches(msg.from, term.value);
+            break;
+        case 'to':
+            result = msg.to.some((r) => senderMatches(r, term.value));
+            break;
+        case 'cc':
+            result = (msg.cc ?? []).some((r) => senderMatches(r, term.value));
+            break;
+        case 'subject':
+            result = msg.subject.toLowerCase().includes(term.value);
+            break;
+        case 'is':
+            if (term.value === 'unread')
+                result = msg.unread;
+            else if (term.value === 'read')
+                result = !msg.unread;
+            else if (term.value === 'starred')
+                result = msg.starred;
+            else
+                result = false;
+            break;
+        case 'has':
+            if (term.value === 'attachment')
+                result = msg.mimeType.includes('multipart/mixed');
+            else
+                result = false;
+            break;
+        default: {
+            const subject = msg.subject.toLowerCase();
+            const from = `${msg.from.name ?? ''} ${msg.from.email}`.toLowerCase();
+            result = subject.includes(term.value) || from.includes(term.value);
+            break;
+        }
+    }
+    return term.negated ? !result : result;
+}
 //# sourceMappingURL=gmail-client.js.map