imapflow 1.7.8 → 2.0.0

package/dist/esm/commands/fetch.d.ts

@@ -0,0 +1,30 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { FetchMessageObject, FetchOptions, FetchQueryObject } from '../types.js';
+/**
+ * Options for the FETCH command
+ */
+export interface FetchCommandOptions extends Omit<FetchOptions, 'changedSince'> {
+    /** Only fetch messages changed since this modseq value */
+    changedSince?: bigint | number | string | undefined;
+    /** Callback for processing each fetched message individually. Call `next()` to release the next message */
+    onUntaggedFetch?: ((message: FetchMessageObject, next: (err?: Error | null | undefined) => void) => void) | undefined;
+}
+/**
+ * Result of the FETCH command
+ */
+export interface FetchCommandResult {
+    /** Number of untagged FETCH responses received */
+    count: number;
+    /** Formatted messages, empty when `onUntaggedFetch` consumed them */
+    list: FetchMessageObject[];
+}
+/**
+ * Fetches emails from the server.
+ *
+ * @param connection - IMAP connection instance
+ * @param range - Message sequence number or UID range
+ * @param query - Fetch query specifying which data to retrieve (e.g., flags, envelope, bodyStructure, headers, source, bodyParts)
+ * @param options - Fetch options
+ * @returns Object with message count and list, or undefined if not in SELECTED state
+ */
+export default function fetch(connection: ImapFlow, range: string, query: FetchQueryObject, options?: FetchCommandOptions | undefined): Promise<FetchCommandResult | undefined>;

package/{lib → dist/esm}/commands/fetch.js

@@ -1,88 +1,67 @@
-'use strict';
-
-const { formatMessageResponse, isRev2Active } = require('../tools');
-
+import { formatMessageResponse, isRev2Active } from '../tools.js';
 /**
  * Fetches emails from the server.
  *
- * @param {Object} connection - IMAP connection instance
- * @param {string} range - Message sequence number or UID range
- * @param {Object} query - Fetch query specifying which data to retrieve (e.g., flags, envelope, bodyStructure, headers, source, bodyParts)
- * @param {Object} [options] - Fetch options
- * @param {boolean} [options.uid] - If true, use UID FETCH instead of FETCH
- * @param {boolean} [options.binary] - If true, use BINARY fetch when available
- * @param {string} [options.changedSince] - Only fetch messages changed since this modseq value
- * @param {Function} [options.onUntaggedFetch] - Callback for processing each fetched message individually
- * @returns {Promise<{count: number, list: Object[]}|undefined>} Object with message count and list, or undefined if not in SELECTED state
+ * @param connection - IMAP connection instance
+ * @param range - Message sequence number or UID range
+ * @param query - Fetch query specifying which data to retrieve (e.g., flags, envelope, bodyStructure, headers, source, bodyParts)
+ * @param options - Fetch options
+ * @returns Object with message count and list, or undefined if not in SELECTED state
  */
-module.exports = async (connection, range, query, options) => {
+export default async function fetch(connection, range, query, options) {
     if (connection.state !== connection.states.SELECTED || !range) {
         // nothing to do here
         return;
     }
-
     options = options || {};
-
     let mailbox = connection.mailbox;
-
     // Use BINARY extension for fetching if supported and requested, otherwise fall back to BODY.
     // RFC 9051 folds the FETCH side of the BINARY extension into base IMAP4rev2, so an active
     // rev2 session can use it even without the BINARY capability token (the APPEND side is NOT
-    // folded in and stays gated on the token in append.js)
+    // folded in and stays gated on the token in append.ts)
     const canUseBinary = connection.capabilities.has('BINARY') || isRev2Active(connection);
     const commandKey = canUseBinary && options.binary && !connection.disableBinary ? 'BINARY' : 'BODY';
-
     // Retry logic for ETHROTTLE errors (server rate limiting) with exponential backoff
     let retryCount = 0;
     const maxRetries = 4;
     const baseDelay = 1000; // Start with 1 second delay
-
     while (retryCount < maxRetries) {
         let messages = {
             count: 0,
             list: []
         };
-
         let response;
         try {
             /* c8 ignore next */ // range is guaranteed truthy by the early-return guard above, so the '*' fallback is unreachable
             let attributes = [{ type: 'SEQUENCE', value: (range || '*').toString() }];
-
             let queryStructure = [];
-
             // Helper to build BODY.PEEK[section]<partial> or BINARY.PEEK[section]<partial> atoms.
             // PEEK avoids marking messages as \Seen. Section identifies what to fetch (HEADER, specific part, etc.)
             // Partial is an optional byte range [start, maxLength].
             let setBodyPeek = (attributes, partial) => {
                 let section = [].concat(attributes || []);
-
                 // BINARY may only address the empty section or a numeric part specifier
                 // (RFC 3516 / RFC 9051 section-binary) - HEADER, HEADER.FIELDS, TEXT and
                 // n.MIME are invalid after BINARY and must stay BODY fetches
-                let binaryAddressable =
-                    !section.length || (section.length === 1 && typeof section[0].value === 'string' && /^\d+(\.\d+)*$/.test(section[0].value));
-
+                let first = section[0];
+                let binaryAddressable = !section.length || (section.length === 1 && typeof first.value === 'string' && /^\d+(\.\d+)*$/.test(first.value));
                 let bodyPeek = {
                     type: 'ATOM',
                     value: `${binaryAddressable ? commandKey : 'BODY'}.PEEK`,
-                    section,
+                    section: section,
                     partial
                 };
-
                 queryStructure.push(bodyPeek);
             };
-
             // IMAP fetch macros (ALL, FAST, FULL) and standard data items map directly to IMAP atoms
             ['all', 'fast', 'full', 'uid', 'flags', 'bodyStructure', 'envelope', 'internalDate'].forEach(key => {
                 if (query[key]) {
                     queryStructure.push({ type: 'ATOM', value: key.toUpperCase() });
                 }
             });
-
             if (query.size) {
                 queryStructure.push({ type: 'ATOM', value: 'RFC822.SIZE' });
             }
-
             // Fetch full message source, optionally with byte range (start/maxLength)
             if (query.source) {
                 let partial;
@@ -94,51 +73,47 @@ module.exports = async (connection, range, query, options) => {
                 }
                 setBodyPeek(null, partial);
             }
-
             // Always request a unique email ID for message deduplication.
             // Prefer OBJECTID (RFC 8474) over Gmail's X-GM-MSGID extension.
             if (connection.capabilities.has('OBJECTID')) {
                 queryStructure.push({ type: 'ATOM', value: 'EMAILID' });
-            } else if (connection.capabilities.has('X-GM-EXT-1')) {
+            }
+            else if (connection.capabilities.has('X-GM-EXT-1')) {
                 queryStructure.push({ type: 'ATOM', value: 'X-GM-MSGID' });
             }
-
             // Thread ID: OBJECTID's THREADID or Gmail's X-GM-THRID
             if (query.threadId) {
                 if (connection.capabilities.has('OBJECTID')) {
                     queryStructure.push({ type: 'ATOM', value: 'THREADID' });
-                } else if (connection.capabilities.has('X-GM-EXT-1')) {
+                }
+                else if (connection.capabilities.has('X-GM-EXT-1')) {
                     queryStructure.push({ type: 'ATOM', value: 'X-GM-THRID' });
                 }
             }
-
             // Gmail labels are only available with X-GM-EXT-1 extension
             if (query.labels) {
                 if (connection.capabilities.has('X-GM-EXT-1')) {
                     queryStructure.push({ type: 'ATOM', value: 'X-GM-LABELS' });
                 }
             }
-
             // always ask for modseq if possible
             if (connection.enabled.has('CONDSTORE') && !mailbox.noModseq) {
                 queryStructure.push({ type: 'ATOM', value: 'MODSEQ' });
             }
-
             // Always include UID in the response even if not explicitly requested,
             // since we use it internally for message identification and tracking
             if (!query.uid) {
                 queryStructure.push({ type: 'ATOM', value: 'UID' });
             }
-
             // Headers: fetch all headers or only specific ones via HEADER.FIELDS
             if (query.headers) {
                 if (Array.isArray(query.headers)) {
                     setBodyPeek([{ type: 'ATOM', value: 'HEADER.FIELDS' }, query.headers.map(header => ({ type: 'ATOM', value: header }))]);
-                } else {
+                }
+                else {
                     setBodyPeek({ type: 'ATOM', value: 'HEADER' });
                 }
             }
-
             // Fetch specific body parts by MIME part number (e.g., "1", "1.2", "2.MIME")
             // Each part can optionally include a byte range (start/maxLength)
             if (query.bodyParts && query.bodyParts.length) {
@@ -159,24 +134,23 @@ module.exports = async (connection, range, query, options) => {
                                 partial.push(Number(part.maxLength));
                             }
                         }
-                    } else if (typeof part === 'string') {
+                    }
+                    else if (typeof part === 'string') {
                         key = part.toUpperCase();
-                    } else {
+                    }
+                    else {
                         return;
                     }
-
                     setBodyPeek({ type: 'ATOM', value: key }, partial);
                 });
             }
-
             // IMAP requires a single item to not be wrapped in parentheses, but
             // multiple items must be in a list. If only one item, unwrap the array.
+            let queryAttribute = queryStructure;
             if (queryStructure.length === 1) {
-                queryStructure = queryStructure.pop();
+                queryAttribute = queryStructure.pop();
             }
-
-            attributes.push(queryStructure);
-
+            attributes.push(queryAttribute);
             // CONDSTORE extension: only fetch messages with modseq higher than the given value.
             // QRESYNC adds VANISHED to also get expunged UIDs since last sync.
             if (options.changedSince && connection.enabled.has('CONDSTORE') && !mailbox.noModseq) {
@@ -190,23 +164,20 @@ module.exports = async (connection, range, query, options) => {
                         value: options.changedSince.toString()
                     }
                 ];
-
                 if (options.uid && connection.enabled.has('QRESYNC')) {
                     changedSinceArgs.push({
                         type: 'ATOM',
                         value: 'VANISHED'
                     });
                 }
-
                 attributes.push(changedSinceArgs);
             }
-
             response = await connection.exec(options.uid ? 'UID FETCH' : 'FETCH', attributes, {
                 untagged: {
                     // Each matching message triggers an untagged FETCH response.
                     // If onUntaggedFetch callback is provided, stream messages to it one by one
                     // (useful for large result sets). Otherwise, collect all into messages.list.
-                    FETCH: async untagged => {
+                    FETCH: async (untagged) => {
                         messages.count++;
                         let formatted = await formatMessageResponse(untagged, mailbox);
                         if (typeof options.onUntaggedFetch === 'function') {
@@ -214,32 +185,32 @@ module.exports = async (connection, range, query, options) => {
                                 options.onUntaggedFetch(formatted, err => {
                                     if (err) {
                                         reject(err);
-                                    } else {
+                                    }
+                                    else {
                                         resolve();
                                     }
                                 });
                             });
-                        } else {
+                        }
+                        else {
                             messages.list.push(formatted);
                         }
                     }
                 }
             });
-
             response.next();
             return messages;
-        } catch (err) {
+        }
+        catch (err) {
             if (err.code === 'ETHROTTLE') {
                 // Server returned a throttle error (rate limiting). Retry with exponential backoff.
                 // Delay doubles each retry: 1s, 2s, 4s, 8s (capped at 30s).
                 // If server provides a throttleReset hint, use that if longer.
                 const backoffDelay = Math.min(baseDelay * Math.pow(2, retryCount), 30000); // Cap at 30 seconds
-
                 // Use throttle reset time if provided and longer than backoff. The hint is
                 // server-controlled, so the wait goes through connection.throttleWait(), which caps
                 // it and keeps the timer tracked and abortable.
                 const delay = err.throttleReset && err.throttleReset > backoffDelay ? err.throttleReset : backoffDelay;
-
                 connection.log.warn({
                     msg: 'Retrying throttled request with exponential backoff',
                     cid: connection.id,
@@ -249,20 +220,17 @@ module.exports = async (connection, range, query, options) => {
                     retryCount,
                     delayMs: delay
                 });
-
                 // An aborted wait means the client was closed, so give up rather than reissuing
                 // the FETCH on a connection that is already gone.
                 let aborted = await connection.throttleWait(delay);
                 if (aborted) {
                     throw connection.createNoConnectionError(connection.byeReason, { rejectedFrom: 'throttleAbort', command: 'FETCH' });
                 }
-
                 retryCount++;
                 continue;
             }
-
             connection.log.warn({ err, cid: connection.id });
             throw err;
         }
     }
-};
+}

package/dist/esm/commands/id.d.ts

@@ -0,0 +1,10 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { IdInfoObject } from '../types.js';
+/**
+ * Sends ID info to the server and updates server info data based on the response.
+ *
+ * @param connection - IMAP connection instance
+ * @param clientInfo - Client identification key-value pairs to send to the server
+ * @returns Server information map, false on failure, or undefined if ID not supported
+ */
+export default function id(connection: ImapFlow, clientInfo?: IdInfoObject | null | undefined): Promise<IdInfoObject | false | undefined>;

package/{lib → dist/esm}/commands/id.js

@@ -1,51 +1,45 @@
-'use strict';
-
-const { formatDateTime } = require('../tools.js');
-
+import { formatDateTime } from '../tools.js';
 /**
  * Sends ID info to the server and updates server info data based on the response.
  *
- * @param {Object} connection - IMAP connection instance
- * @param {Object} clientInfo - Client identification key-value pairs to send to the server
- * @returns {Promise<Object|boolean|undefined>} Server information map, false on failure, or undefined if ID not supported
+ * @param connection - IMAP connection instance
+ * @param clientInfo - Client identification key-value pairs to send to the server
+ * @returns Server information map, false on failure, or undefined if ID not supported
  */
 // RFC 2971: The ID command exchanges client/server implementation info
 // (name, version, vendor, etc.) for diagnostic and compatibility purposes.
-module.exports = async (connection, clientInfo) => {
+export default async function id(connection, clientInfo) {
     if (!connection.capabilities.has('ID')) {
         // nothing to do here
         return;
     }
-
     let response;
     try {
         let map = {};
-
         // Convert the clientInfo object into a flat array of alternating key-value strings
         // for the IMAP wire format: ("key1" "value1" "key2" "value2" ...)
         let formattedClientInfo = !clientInfo
             ? null
             : Object.keys(clientInfo)
-                  .map(key => [key, formatValue(key, clientInfo[key])])
-                  .filter(entry => entry[1])
-                  .flatMap(entry => entry);
-
+                .map(key => [key, formatValue(key, clientInfo[key])])
+                .filter(entry => entry[1])
+                .flatMap(entry => entry);
         if (formattedClientInfo && !formattedClientInfo.length) {
             // value array has no elements
             formattedClientInfo = null;
         }
-
         response = await connection.exec('ID', [formattedClientInfo], {
             untagged: {
                 // Parse the server's ID response: a flat list of alternating key-value atoms.
                 // Even indices (i % 2 === 0) are keys, odd indices are the corresponding values.
-                ID: async untagged => {
+                ID: async (untagged) => {
                     let params = untagged.attributes && untagged.attributes[0];
                     let key;
                     (Array.isArray(params) ? params : [].concat(params || [])).forEach((val, i) => {
                         if (i % 2 === 0) {
                             key = val.value;
-                        } else if (typeof key === 'string' && typeof val.value === 'string') {
+                        }
+                        else if (typeof key === 'string' && typeof val.value === 'string') {
                             map[key.toLowerCase().trim()] = val.value;
                         }
                     });
@@ -55,18 +49,18 @@ module.exports = async (connection, clientInfo) => {
         connection.serverInfo = map;
         response.next();
         return map;
-    } catch (err) {
+    }
+    catch (err) {
         connection.log.warn({ err, cid: connection.id });
         return false;
     }
-};
-
+}
 /**
  * Formats a client info value for the ID command.
  *
- * @param {string} key - The info key name
- * @param {*} value - The value to format
- * @returns {string} Formatted value string
+ * @param key - The info key name
+ * @param value - The value to format
+ * @returns Formatted value string
  */
 function formatValue(key, value) {
     switch (key.toLowerCase()) {

package/dist/esm/commands/idle.d.ts

@@ -0,0 +1,9 @@
+import type { ImapFlow } from '../imap-flow.js';
+/**
+ * Listens for changes in the selected mailbox using IDLE or NOOP polling fallback.
+ *
+ * @param connection - IMAP connection instance
+ * @param maxIdleTime - Maximum time in milliseconds to stay in IDLE before restarting
+ * @returns Void on success, false on failure, or undefined if not in SELECTED state
+ */
+export default function idle(connection: ImapFlow, maxIdleTime?: number | false | undefined): Promise<void | false | undefined>;