@bobfrankston/iflow 1.0.2 → 1.0.4

package/iflow.code-workspace

@@ -0,0 +1,42 @@
+{
+	"folders": [
+		{
+			"path": "."
+		},
+		{
+			"path": "../imail"
+		},
+		{
+			"path": "../uinfo"
+		},
+		{
+			"path": "../mlconfig"
+		},
+		{
+			"path": "../config"
+		}
+	],
+	"settings": {
+		"workbench.colorCustomizations": {
+			"activityBar.activeBackground": "#ebe835",
+			"activityBar.background": "#ebe835",
+			"activityBar.foreground": "#15202b",
+			"activityBar.inactiveForeground": "#15202b99",
+			"activityBarBadge.background": "#11aeab",
+			"activityBarBadge.foreground": "#e7e7e7",
+			"commandCenter.border": "#15202b99",
+			"sash.hoverBorder": "#ebe835",
+			"statusBar.background": "#d9d515",
+			"statusBar.foreground": "#15202b",
+			"statusBarItem.hoverBackground": "#aaa710",
+			"statusBarItem.remoteBackground": "#d9d515",
+			"statusBarItem.remoteForeground": "#15202b",
+			"titleBar.activeBackground": "#d9d515",
+			"titleBar.activeForeground": "#15202b",
+			"titleBar.inactiveBackground": "#d9d51599",
+			"titleBar.inactiveForeground": "#15202b99"
+		},
+		"peacock.color": "#d9d515",
+		"workbench.colorTheme": "Visual Studio 2019 Dark"
+	}
+}

package/imaplib/ImapClient.d.ts

@@ -1,4 +1,4 @@
-import imapflow from 'imapflow';
+import imapflow, { SearchObject } from 'imapflow';
 import { ImapClientConfig, FetchedMessage } from './types.js';
 export interface iFetchOptions {
     source: boolean;
@@ -8,15 +8,68 @@ export declare class ImapClient {
     private config;
     private isDestroying;
     private connectionPromise;
+    private initialized;
+    private reconnectAttempts;
     constructor(cfg: ImapClientConfig);
     private init;
+    private getAuth;
     private handleReconnection;
     private cleanup;
     private withConnection;
     getMessagesCount(mailbox: string): Promise<number>;
+    /** Get all UIDs in a mailbox (lightweight — no message data fetched) */
+    getUids(mailbox: string): Promise<number[]>;
+    /**
+     * Search messages in a mailbox using IMAP SEARCH criteria.
+     * Returns UIDs of matching messages. Use fetchMessageByUid to get full content.
+     *
+     * @param mailbox Mailbox path (e.g., "INBOX")
+     * @param criteria imapflow SearchObject — supports from, to, subject, body,
+     *   before/since dates, flags, size, header, boolean (or/not), and Gmail raw search (gmraw).
+     *   See: https://imapflow.com/module-imapflow-ImapFlow.html#search
+     * @returns Array of matching UIDs
+     *
+     * @example
+     *   // Text search in body
+     *   await client.searchMessages("INBOX", { body: "meeting" });
+     *   // From + date range
+     *   await client.searchMessages("INBOX", { from: "bob", since: new Date("2026-01-01") });
+     *   // Gmail native search
+     *   await client.searchMessages("INBOX", { gmraw: "has:attachment from:alice" });
+     */
+    searchMessages(mailbox: string, criteria: SearchObject): Promise<number[]>;
     fetchMessageByDate(mailbox: string, start: Date | number, endingx?: Date | number, options?: iFetchOptions): Promise<FetchedMessage[]>;
     fetchMessages(mailbox: string, end: number, count: number, options?: iFetchOptions): Promise<FetchedMessage[]>;
+    /** Fetch messages with UID greater than sinceUid */
+    fetchMessagesSinceUid(mailbox: string, sinceUid: number, options?: iFetchOptions): Promise<FetchedMessage[]>;
+    /** Fetch a single message by UID, returning source by default */
+    fetchMessageByUid(mailbox: string, uid: number, options?: iFetchOptions): Promise<FetchedMessage | null>;
     moveMessage(msg: FetchedMessage, sourceMailbox: string, targetMailbox: string): Promise<void>;
+    /**
+     * Append a raw message to a mailbox
+     * @param mailbox Target mailbox path
+     * @param rawMessage Raw RFC822 message content
+     * @param flags Optional message flags (e.g., ['\\Seen', '\\Flagged'])
+     * @param internalDate Optional internal date for the message
+     */
+    appendMessage(mailbox: string, rawMessage: string | Buffer, flags?: string[], internalDate?: Date): Promise<false | imapflow.AppendResponseObject>;
+    /**
+     * Copy a message to another IMAP server/account
+     * @param msg Message to copy
+     * @param targetClient Target ImapClient (different server/account)
+     * @param targetMailbox Target mailbox on the destination server
+     * @param preserveFlags Whether to copy message flags (default: true)
+     */
+    copyMessageToServer(msg: FetchedMessage, targetClient: ImapClient, targetMailbox: string, preserveFlags?: boolean): Promise<void>;
+    /**
+     * Move a message to another IMAP server/account (copy then delete from source)
+     * @param msg Message to move
+     * @param sourceMailbox Source mailbox path
+     * @param targetClient Target ImapClient (different server/account)
+     * @param targetMailbox Target mailbox on the destination server
+     * @param preserveFlags Whether to copy message flags (default: true)
+     */
+    moveMessageToServer(msg: FetchedMessage, sourceMailbox: string, targetClient: ImapClient, targetMailbox: string, preserveFlags?: boolean): Promise<void>;
     getFolderList(): Promise<imapflow.ListResponse[]>;
     getFolderTree(): Promise<imapflow.ListTreeResponse>;
     getSpecialFolders(mailboxes: Awaited<ReturnType<ImapClient["getFolderList"]>>): {
@@ -29,6 +82,17 @@ export declare class ImapClient {
         junk: string;
     };
     createmailbox(folder: string[] | string): Promise<imapflow.MailboxCreateResponse>;
+    /** Add flags to a message by UID */
+    addFlags(mailbox: string, uid: number, flags: string[]): Promise<boolean>;
+    /** Remove flags from a message by UID */
+    removeFlags(mailbox: string, uid: number, flags: string[]): Promise<boolean>;
+    /** Get flags for a message by UID */
+    getFlags(mailbox: string, uid: number): Promise<string[]>;
+    /** Delete a message by UID from a mailbox */
+    deleteMessageByUid(mailbox: string, uid: number): Promise<void>;
+    /** Watch a mailbox for new messages via IMAP IDLE. Calls onNew when messages arrive.
+     *  Returns a stop function to end the watch. */
+    watchMailbox(mailbox: string, onNew: (count: number) => void): Promise<() => void>;
     logout(): Promise<void>;
     connect(): Promise<void>;
 }

package/imaplib/ImapClient.js

@@ -11,57 +11,80 @@ export class ImapClient {
     config;
     isDestroying = false;
     connectionPromise = null;
+    initialized;
+    reconnectAttempts = 0;
     constructor(cfg) {
         this.config = cfg;
-        this.init();
+        if (!cfg.password && !cfg.tokenProvider) {
+            throw new Error('ImapClientConfig requires either password or tokenProvider');
+        }
+        this.initialized = this.init();
     }
-    init() {
+    async init() {
+        const auth = await this.getAuth();
         this.client = new ImapFlow({
             host: this.config.server,
             port: this.config.port,
             secure: true,
-            auth: {
-                user: this.config.username,
-                pass: this.config.password
-            },
+            auth,
             logger: false, // Disable internal logging
+            tls: {
+                rejectUnauthorized: this.config.rejectUnauthorized !== false // Default to true (secure), but allow override
+            }
         });
         // Set up error handlers
         this.client.on('error', (err) => {
-            console.error(`ImapFlow socket error: ${err.message}`);
+            console.error(`${new Date().toISOString()} ImapFlow socket error: ${err.message}`);
             if (!this.isDestroying) {
                 this.handleReconnection();
             }
         });
         this.client.on('close', () => {
-            console.error(`ImapFlow connection closed`);
+            console.error(`${new Date().toISOString()} ImapFlow connection closed`);
             if (!this.isDestroying) {
                 this.handleReconnection();
             }
         });
     }
+    async getAuth() {
+        if (this.config.tokenProvider) {
+            const accessToken = await this.config.tokenProvider();
+            return { user: this.config.username, accessToken };
+        }
+        return { user: this.config.username, pass: this.config.password };
+    }
     async handleReconnection() {
         if (this.connectionPromise)
             return; // Already reconnecting
+        this.reconnectAttempts++;
+        const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts - 1), 30000); // Backoff: 1s, 2s, 4s, ... 30s max
         this.connectionPromise = new Promise(async (resolve) => {
             try {
-                // Clean up old client
+                // Clean up old client listeners
                 this.cleanup();
-                // Wait before reconnecting
-                await new Promise(r => setTimeout(r, 1000));
-                // Reinitialize
-                this.init();
+                // Force-close the underlying socket to stop repeated error events
+                try {
+                    if (this.client) {
+                        this.client.close();
+                    }
+                }
+                catch { /* ignore close errors */ }
+                console.log(`${new Date().toISOString()} Reconnecting (attempt ${this.reconnectAttempts}, waiting ${delay}ms)...`);
+                await new Promise(r => setTimeout(r, delay));
+                // Reinitialize (re-fetches token if using OAuth)
+                await this.init();
                 try {
                     await this.client.connect();
-                    console.log('Reconnected successfully');
+                    console.log(`${new Date().toISOString()} Reconnected successfully`);
+                    this.reconnectAttempts = 0; // Reset on success
                 }
                 catch (err) {
-                    console.error('Reconnection failed, will retry:', err);
+                    console.error(`${new Date().toISOString()} Reconnection failed: ${err.message}`);
                     // Will trigger another reconnection attempt via error handler
                 }
             }
             catch (err) {
-                console.error('Error during reconnection process:', err);
+                console.error(`${new Date().toISOString()} Error during reconnection process: ${err.message}`);
             }
             finally {
                 this.connectionPromise = null;
@@ -83,13 +106,15 @@ export class ImapClient {
             return await operation();
         }
         catch (err) {
-            console.error(`Operation failed: ${err.message}`);
+            console.error(`${new Date().toISOString()} Operation failed: ${err.message}`);
             // Check if it's a connection-related error
             if (err.code === 'ECONNRESET' || err.code === 'ENOTFOUND' ||
                 err.code === 'ETIMEDOUT' || err.code === 'ECONNREFUSED' ||
-                err.message.includes('connection') || err.message.includes('socket')) {
+                err.code === 'CERT_HAS_EXPIRED' || err.code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE' ||
+                err.message.includes('connection') || err.message.includes('socket') ||
+                err.message.includes('certificate')) {
                 if (!this.isDestroying) {
-                    console.log('Connection error detected, attempting reconnection...');
+                    console.log(`${new Date().toISOString()} Connection error detected, attempting reconnection...`);
                     await this.handleReconnection();
                     // Retry the operation once after reconnection
                     try {
@@ -97,7 +122,7 @@ export class ImapClient {
                         return await operation();
                     }
                     catch (retryErr) {
-                        console.error(`Operation failed after reconnection: ${retryErr}`);
+                        console.error(`${new Date().toISOString()} Operation failed after reconnection: ${retryErr}`);
                         throw retryErr;
                     }
                 }
@@ -113,6 +138,55 @@ export class ImapClient {
             return status.messages;
         });
     }
+    /** Get all UIDs in a mailbox (lightweight — no message data fetched) */
+    async getUids(mailbox) {
+        try {
+            await this.connect();
+            await this.client.mailboxOpen(mailbox, { readOnly: true });
+            const uids = await this.client.search({ all: true }, { uid: true });
+            return uids;
+        }
+        catch (error) {
+            console.error(`Error getting UIDs: ${error.message}`);
+            throw error;
+        }
+        finally {
+            await this.client.mailboxClose();
+        }
+    }
+    /**
+     * Search messages in a mailbox using IMAP SEARCH criteria.
+     * Returns UIDs of matching messages. Use fetchMessageByUid to get full content.
+     *
+     * @param mailbox Mailbox path (e.g., "INBOX")
+     * @param criteria imapflow SearchObject — supports from, to, subject, body,
+     *   before/since dates, flags, size, header, boolean (or/not), and Gmail raw search (gmraw).
+     *   See: https://imapflow.com/module-imapflow-ImapFlow.html#search
+     * @returns Array of matching UIDs
+     *
+     * @example
+     *   // Text search in body
+     *   await client.searchMessages("INBOX", { body: "meeting" });
+     *   // From + date range
+     *   await client.searchMessages("INBOX", { from: "bob", since: new Date("2026-01-01") });
+     *   // Gmail native search
+     *   await client.searchMessages("INBOX", { gmraw: "has:attachment from:alice" });
+     */
+    async searchMessages(mailbox, criteria) {
+        try {
+            await this.connect();
+            await this.client.mailboxOpen(mailbox, { readOnly: true });
+            const uids = await this.client.search(criteria, { uid: true });
+            return uids;
+        }
+        catch (error) {
+            console.error(`Search error in ${mailbox}: ${error.message}`);
+            throw error;
+        }
+        finally {
+            await this.client.mailboxClose();
+        }
+    }
     async fetchMessageByDate(mailbox, start, endingx, options) {
         try {
             options = { ...defaultFetchOptions, ...options }; // Merge with default options
@@ -183,6 +257,61 @@ export class ImapClient {
             // await this.client.logout();
         }
     }
+    /** Fetch messages with UID greater than sinceUid */
+    async fetchMessagesSinceUid(mailbox, sinceUid, options) {
+        try {
+            options = { ...defaultFetchOptions, ...options };
+            await this.connect();
+            await this.client.mailboxOpen(mailbox, { readOnly: true });
+            // UID range: sinceUid+1:* means all UIDs after sinceUid
+            const range = `${sinceUid + 1}:*`;
+            const fetchQuery = {
+                uid: true,
+                envelope: true,
+                flags: true,
+                headers: true,
+                source: options.source
+            };
+            const messageObjects = await this.client.fetchAll(range, fetchQuery, { uid: true });
+            return messageObjects.map(msg => new FetchedMessage(msg));
+        }
+        catch (error) {
+            // "Nothing to fetch" just means no new messages
+            if (error.responseText?.includes("Nothing to fetch"))
+                return [];
+            console.error(`Error fetching messages since UID ${sinceUid}: ${error.message}`);
+            throw error;
+        }
+        finally {
+            await this.client.mailboxClose();
+        }
+    }
+    /** Fetch a single message by UID, returning source by default */
+    async fetchMessageByUid(mailbox, uid, options) {
+        try {
+            options = { ...defaultFetchOptions, ...options };
+            await this.connect();
+            await this.client.mailboxOpen(mailbox, { readOnly: true });
+            const fetchQuery = {
+                uid: true,
+                envelope: true,
+                flags: true,
+                headers: true,
+                source: options.source
+            };
+            const msg = await this.client.fetchOne(uid, fetchQuery, { uid: true });
+            if (!msg)
+                return null;
+            return new FetchedMessage(msg);
+        }
+        catch (error) {
+            console.error(`Error fetching message UID ${uid}: ${error.message}`);
+            throw error;
+        }
+        finally {
+            await this.client.mailboxClose();
+        }
+    }
     // async moveMessage(uid: number, sourceMailbox: string, targetMailbox: string) {
     async moveMessage(msg, sourceMailbox, targetMailbox) {
         try {
@@ -208,6 +337,82 @@ export class ImapClient {
             await this.client.mailboxClose();
         }
     }
+    /**
+     * Append a raw message to a mailbox
+     * @param mailbox Target mailbox path
+     * @param rawMessage Raw RFC822 message content
+     * @param flags Optional message flags (e.g., ['\\Seen', '\\Flagged'])
+     * @param internalDate Optional internal date for the message
+     */
+    async appendMessage(mailbox, rawMessage, flags, internalDate) {
+        try {
+            await this.connect();
+            const result = await this.client.append(mailbox, rawMessage, flags, internalDate);
+            return result;
+        }
+        catch (error) {
+            console.error(`Error appending message to ${mailbox}: ${error.message}`);
+            throw error;
+        }
+    }
+    /**
+     * Copy a message to another IMAP server/account
+     * @param msg Message to copy
+     * @param targetClient Target ImapClient (different server/account)
+     * @param targetMailbox Target mailbox on the destination server
+     * @param preserveFlags Whether to copy message flags (default: true)
+     */
+    async copyMessageToServer(msg, targetClient, targetMailbox, preserveFlags = true) {
+        try {
+            if (!msg.source) {
+                throw new Error('Message source is required for cross-server copy. Fetch with source: true');
+            }
+            // Prepare flags if preserving them
+            const flags = [];
+            if (preserveFlags) {
+                if (msg.flagged)
+                    flags.push('\\Flagged');
+                if (msg.seen)
+                    flags.push('\\Seen');
+                if (msg.answered)
+                    flags.push('\\Answered');
+                if (msg.draft)
+                    flags.push('\\Draft');
+            }
+            // Append to target server
+            const date = msg.internalDate instanceof Date ? msg.internalDate : undefined;
+            await targetClient.appendMessage(targetMailbox, msg.source, flags, date);
+        }
+        catch (error) {
+            console.error(`Error copying message to another server: ${error.message}`);
+            throw error;
+        }
+    }
+    /**
+     * Move a message to another IMAP server/account (copy then delete from source)
+     * @param msg Message to move
+     * @param sourceMailbox Source mailbox path
+     * @param targetClient Target ImapClient (different server/account)
+     * @param targetMailbox Target mailbox on the destination server
+     * @param preserveFlags Whether to copy message flags (default: true)
+     */
+    async moveMessageToServer(msg, sourceMailbox, targetClient, targetMailbox, preserveFlags = true) {
+        try {
+            // First copy to target
+            await this.copyMessageToServer(msg, targetClient, targetMailbox, preserveFlags);
+            // Then delete from source
+            await this.connect();
+            await this.client.mailboxOpen(sourceMailbox, { readOnly: false });
+            await this.client.messageDelete([msg.uid], { uid: true });
+        }
+        catch (error) {
+            console.error(`Error moving message to another server: ${error.message}`);
+            throw error;
+        }
+        finally {
+            await this.client.mailboxClose();
+        }
+    }
     async getFolderList() {
         return this.withConnection(async () => {
             return await this.client.list();
@@ -280,6 +485,88 @@ export class ImapClient {
             return info;
         });
     }
+    /** Add flags to a message by UID */
+    async addFlags(mailbox, uid, flags) {
+        try {
+            await this.connect();
+            await this.client.mailboxOpen(mailbox, { readOnly: false });
+            return await this.client.messageFlagsAdd([uid], flags, { uid: true });
+        }
+        catch (error) {
+            console.error(`Error adding flags to UID ${uid}: ${error.message}`);
+            throw error;
+        }
+        finally {
+            await this.client.mailboxClose();
+        }
+    }
+    /** Remove flags from a message by UID */
+    async removeFlags(mailbox, uid, flags) {
+        try {
+            await this.connect();
+            await this.client.mailboxOpen(mailbox, { readOnly: false });
+            return await this.client.messageFlagsRemove([uid], flags, { uid: true });
+        }
+        catch (error) {
+            console.error(`Error removing flags from UID ${uid}: ${error.message}`);
+            throw error;
+        }
+        finally {
+            await this.client.mailboxClose();
+        }
+    }
+    /** Get flags for a message by UID */
+    async getFlags(mailbox, uid) {
+        try {
+            await this.connect();
+            await this.client.mailboxOpen(mailbox, { readOnly: true });
+            const msg = await this.client.fetchOne(uid, { flags: true }, { uid: true });
+            if (!msg)
+                return [];
+            return [...msg.flags];
+        }
+        catch (error) {
+            console.error(`Error getting flags for UID ${uid}: ${error.message}`);
+            throw error;
+        }
+        finally {
+            await this.client.mailboxClose();
+        }
+    }
+    /** Delete a message by UID from a mailbox */
+    async deleteMessageByUid(mailbox, uid) {
+        try {
+            await this.connect();
+            await this.client.mailboxOpen(mailbox, { readOnly: false });
+            await this.client.messageDelete([uid], { uid: true });
+        }
+        catch (error) {
+            console.error(`Error deleting UID ${uid} from ${mailbox}: ${error.message}`);
+            throw error;
+        }
+        finally {
+            await this.client.mailboxClose();
+        }
+    }
+    /** Watch a mailbox for new messages via IMAP IDLE. Calls onNew when messages arrive.
+     *  Returns a stop function to end the watch. */
+    async watchMailbox(mailbox, onNew) {
+        await this.connect();
+        await this.client.mailboxOpen(mailbox, { readOnly: true });
+        const handler = (data) => {
+            if (data.count > data.prevCount) {
+                onNew(data.count - data.prevCount);
+            }
+        };
+        this.client.on('exists', handler);
+        return async () => {
+            this.client.off('exists', handler);
+            try {
+                await this.client.mailboxClose();
+            }
+            catch { /* ignore */ }
+        };
+    }
     async logout() {
         this.isDestroying = true;
         this.cleanup();
@@ -293,6 +580,7 @@ export class ImapClient {
     }
     async connect() {
         try {
+            await this.initialized; // Ensure async init completed
             if (this.connectionPromise) {
                 await this.connectionPromise;
             }
@@ -301,7 +589,7 @@ export class ImapClient {
             }
         }
         catch (err) {
-            console.error(`Connection failed: ${err.message}`);
+            console.error(`${new Date().toISOString()} Connection failed: ${err.message}`);
             if (!this.isDestroying) {
                 await this.handleReconnection();
             }

package/imaplib/gmail.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Gmail-specific IMAP support with OAuth authentication
+ */
+import { ImapClientConfig } from './types.js';
+export interface OAuthImapConfig {
+    username: string;
+    credentialsPath?: string;
+    tokenDirectory?: string;
+}
+/**
+ * Check if email address is Gmail
+ */
+export declare function isGmailUser(username: string): boolean;
+/**
+ * Check if a server is Gmail
+ */
+export declare function isGmailServer(server: string): boolean;
+/**
+ * Creates an ImapClientConfig with OAuth tokenProvider
+ * Auto-detects Gmail from @gmail.com email addresses
+ * Tokens stored in <tokenDirectory>/tokens/<sanitized-email>/token.json
+ *
+ * Credentials and tokens are stored in the iflow package directory by default
+ */
+export declare function createImapConfig(config: OAuthImapConfig): ImapClientConfig;
+/** @deprecated Use createImapConfig instead */
+export declare const createGmailConfig: typeof createImapConfig;
+/**
+ * Auto-configure IMAP client - detects Gmail and uses OAuth, otherwise uses password
+ * This is the main function to use - it handles all authentication logic internally
+ *
+ * @param config - Server configuration with username, password (optional for Gmail), server, port
+ * @returns ImapClientConfig ready to use with ImapClient
+ */
+export declare function createAutoImapConfig(config: {
+    server: string;
+    port: number;
+    username: string;
+    password?: string;
+    verbose?: boolean;
+    rejectUnauthorized?: boolean;
+}): ImapClientConfig;
+//# sourceMappingURL=gmail.d.ts.map