imapflow 1.2.8 → 1.2.10

package/lib/commands/authenticate.js

@@ -2,18 +2,54 @@
 
 const { getStatusCode, getErrorText } = require('../tools.js');
 
+/**
+ * Handles authentication errors by enriching the error object with server response details.
+ *
+ * @param {Error} err - The original authentication error
+ * @param {Object} [errorResponse] - Optional OAuth error response from the server
+ * @throws {Error} Always throws the enriched error
+ */
+async function handleAuthError(err, errorResponse) {
+    let errorCode = getStatusCode(err.response);
+    if (errorCode) {
+        err.serverResponseCode = errorCode;
+    }
+    err.authenticationFailed = true;
+    err.response = await getErrorText(err.response);
+    if (errorResponse) {
+        err.oauthError = errorResponse;
+    }
+    throw err;
+}
+
+/**
+ * Authenticates using OAuth (OAUTHBEARER or XOAUTH2).
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} username - The username to authenticate with
+ * @param {string} accessToken - The OAuth2 access token
+ * @returns {Promise<string>} The authenticated username
+ * @throws {Error} If authentication fails
+ */
 async function authOauth(connection, username, accessToken) {
     let oauthbearer;
     let command;
     let breaker;
 
     if (connection.capabilities.has('AUTH=OAUTHBEARER')) {
+        // OAUTHBEARER payload per RFC 7628: fields separated by \x01 (SASL GS2 framing).
+        // Format: "n,a=<user>," \x01 "host=..." \x01 "port=..." \x01 "auth=Bearer <token>" \x01 \x01
+        // The trailing empty strings produce the required double-\x01 terminator.
         oauthbearer = [`n,a=${username},`, `host=${connection.servername}`, `port=993`, `auth=Bearer ${accessToken}`, '', ''].join('\x01');
         command = 'OAUTHBEARER';
+        // "AQ==" is base64 for \x01 -- sent as the error continuation to abort the SASL exchange
         breaker = 'AQ==';
     } else if (connection.capabilities.has('AUTH=XOAUTH') || connection.capabilities.has('AUTH=XOAUTH2')) {
+        // XOAUTH2 payload (Google-specific): simpler format, also \x01-delimited.
+        // Format: "user=<user>" \x01 "auth=Bearer <token>" \x01 \x01
         oauthbearer = [`user=${username}`, `auth=Bearer ${accessToken}`, '', ''].join('\x01');
         command = 'XOAUTH2';
+        // Empty breaker: XOAUTH2 expects an empty response to abort the SASL exchange
         breaker = '';
     }
 
@@ -26,6 +62,8 @@ async function authOauth(connection, username, accessToken) {
                 { type: 'ATOM', value: Buffer.from(oauthbearer).toString('base64'), sensitive: true }
             ],
             {
+                // Server sends a "+" continuation if auth fails, with a base64 JSON error payload.
+                // We decode it for diagnostics, then send the breaker to terminate the exchange.
                 onPlusTag: async resp => {
                     if (resp.attributes && resp.attributes[0] && resp.attributes[0].type === 'TEXT') {
                         try {
@@ -46,46 +84,43 @@ async function authOauth(connection, username, accessToken) {
 
         return username;
     } catch (err) {
-        let errorCode = getStatusCode(err.response);
-        if (errorCode) {
-            err.serverResponseCode = errorCode;
-        }
-        err.authenticationFailed = true;
-        err.response = await getErrorText(err.response);
-        if (errorResponse) {
-            err.oauthError = errorResponse;
-        }
-        throw err;
+        await handleAuthError(err, errorResponse);
     }
 }
 
+/**
+ * Authenticates using the SASL LOGIN mechanism.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} username - The username to authenticate with
+ * @param {string} password - The password to authenticate with
+ * @returns {Promise<string>} The authenticated username
+ * @throws {Error} If authentication fails
+ */
 async function authLogin(connection, username, password) {
     let errorResponse = false;
     try {
+        // SASL LOGIN is a challenge-response mechanism: the server sends base64-encoded
+        // prompts ("Username:" and "Password:") and the client responds with base64-encoded values.
         let response = await connection.exec('AUTHENTICATE', [{ type: 'ATOM', value: 'LOGIN' }], {
             onPlusTag: async resp => {
                 if (resp.attributes && resp.attributes[0] && resp.attributes[0].type === 'TEXT') {
-                    let question = Buffer.from(resp.attributes[0].value, 'base64').toString();
-                    switch (
-                        question.toLowerCase().replace(/[:\x00]*$/, '') // eslint-disable-line no-control-regex
-                    ) {
-                        case 'username':
-                        case 'user name': {
-                            let encodedUsername = Buffer.from(username).toString('base64');
-                            connection.log.debug({ src: 'c', msg: encodedUsername, comment: `Encoded username for AUTH=LOGIN` });
-                            connection.write(encodedUsername);
-                            break;
-                        }
-
-                        case 'password':
-                            connection.log.debug({ src: 'c', msg: '(* value hidden *)', comment: `Encoded password for AUTH=LOGIN` });
-                            connection.write(Buffer.from(password).toString('base64'));
-                            break;
-
-                        default: {
-                            let error = new Error(`Unknown LOGIN question "${question}"`);
-                            throw error;
-                        }
+                    // Decode the server's base64 challenge to determine what it's asking for.
+                    // Strip trailing colons and null bytes (\x00) that some servers append to the prompt.
+                    let question = Buffer.from(resp.attributes[0].value, 'base64')
+                        .toString()
+                        .toLowerCase()
+                        .replace(/[:\x00]*$/, ''); // eslint-disable-line no-control-regex
+
+                    if (question === 'username' || question === 'user name') {
+                        let encodedUsername = Buffer.from(username).toString('base64');
+                        connection.log.debug({ src: 'c', msg: encodedUsername, comment: `Encoded username for AUTH=LOGIN` });
+                        connection.write(encodedUsername);
+                    } else if (question === 'password') {
+                        connection.log.debug({ src: 'c', msg: '(* value hidden *)', comment: `Encoded password for AUTH=LOGIN` });
+                        connection.write(Buffer.from(password).toString('base64'));
+                    } else {
+                        throw new Error(`Unknown LOGIN question "${question}"`);
                     }
                 }
             }
@@ -97,19 +132,20 @@ async function authLogin(connection, username, password) {
 
         return username;
     } catch (err) {
-        let errorCode = getStatusCode(err.response);
-        if (errorCode) {
-            err.serverResponseCode = errorCode;
-        }
-        err.authenticationFailed = true;
-        err.response = await getErrorText(err.response);
-        if (errorResponse) {
-            err.oauthError = errorResponse;
-        }
-        throw err;
+        await handleAuthError(err, errorResponse);
     }
 }
 
+/**
+ * Authenticates using the SASL PLAIN mechanism.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} username - The authentication identity (authcid)
+ * @param {string} password - The password to authenticate with
+ * @param {string} [authzid] - Optional authorization identity to impersonate
+ * @returns {Promise<string>} The authorized identity (authzid if provided, otherwise username)
+ * @throws {Error} If authentication fails
+ */
 async function authPlain(connection, username, password, authzid) {
     let errorResponse = false;
     try {
@@ -133,26 +169,37 @@ async function authPlain(connection, username, password, authzid) {
         // Return the identity we're authorized as (authzid if provided, otherwise username)
         return authzid || username;
     } catch (err) {
-        let errorCode = getStatusCode(err.response);
-        if (errorCode) {
-            err.serverResponseCode = errorCode;
-        }
-        err.authenticationFailed = true;
-        err.response = await getErrorText(err.response);
-        if (errorResponse) {
-            err.oauthError = errorResponse;
-        }
-        throw err;
+        await handleAuthError(err, errorResponse);
     }
 }
 
-// Authenticates user using LOGIN
+/**
+ * Authenticates user using the best available method.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} username - The username to authenticate with
+ * @param {Object} credentials - Authentication credentials
+ * @param {string} [credentials.accessToken] - OAuth2 access token for OAUTHBEARER/XOAUTH2 authentication
+ * @param {string} [credentials.password] - Password for PLAIN or LOGIN authentication
+ * @param {string} [credentials.loginMethod] - Force a specific login method (e.g., 'AUTH=PLAIN', 'AUTH=LOGIN')
+ * @param {string} [credentials.authzid] - Authorization identity for PLAIN authentication
+ * @returns {Promise<string|undefined>} The authenticated username, or undefined if already authenticated
+ * @throws {Error} If no supported authentication mechanism is available or if authentication fails
+ */
 module.exports = async (connection, username, { accessToken, password, loginMethod, authzid }) => {
     if (connection.state !== connection.states.NOT_AUTHENTICATED) {
         // nothing to do here
         return;
     }
 
+    // Authentication method selection order:
+    // 1. OAuth (OAUTHBEARER > XOAUTH2) -- preferred when an accessToken is provided,
+    //    as it avoids transmitting passwords entirely.
+    // 2. SASL PLAIN -- preferred over LOGIN because it supports authzid (impersonation)
+    //    and sends credentials in a single round trip.
+    // 3. SASL LOGIN -- fallback; an older challenge-response mechanism (two round trips).
+    // If loginMethod is explicitly set, it overrides the automatic capability-based selection.
+
     if (accessToken) {
         // AUTH=OAUTHBEARER and AUTH=XOAUTH in the context of OAuth2 or very similar so we can handle these together
         if (connection.capabilities.has('AUTH=OAUTHBEARER') || connection.capabilities.has('AUTH=XOAUTH') || connection.capabilities.has('AUTH=XOAUTH2')) {

package/lib/commands/capability.js

@@ -1,6 +1,15 @@
 'use strict';
 
-// Refresh capabilities from server
+/**
+ * Refreshes capabilities from server.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @returns {Promise<Map|boolean>} Server capabilities map, or false on failure
+ */
+// Capabilities are normally received and updated by the global response handler
+// (e.g., from the server greeting or after authentication). This explicit CAPABILITY
+// command is only needed when capabilities must be refreshed on demand, such as
+// after STARTTLS or when the server signals a capability change.
 module.exports = async connection => {
     if (connection.capabilities.size && !connection.expectCapabilityUpdate) {
         return connection.capabilities;
@@ -8,7 +17,8 @@ module.exports = async connection => {
 
     let response;
     try {
-        // untagged capability response is processed by global handler
+        // The actual parsing of the untagged CAPABILITY response is handled by the
+        // global handler, not here. We just trigger the server to send it.
         response = await connection.exec('CAPABILITY');
 
         response.next();

package/lib/commands/close.js

@@ -1,6 +1,11 @@
 'use strict';
 
-// Closes a mailbox
+/**
+ * Closes the currently selected mailbox.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @returns {Promise<boolean|undefined>} True on success, false on failure, or undefined if not in SELECTED state
+ */
 module.exports = async connection => {
     if (connection.state !== connection.states.SELECTED) {
         // nothing to do here
@@ -9,9 +14,14 @@ module.exports = async connection => {
 
     let response;
     try {
+        // IMAP CLOSE (RFC 3501 6.4.2): permanently removes all messages flagged \Deleted
+        // from the currently selected mailbox (implicit expunge) and deselects it.
+        // Unlike EXPUNGE, CLOSE does not send individual untagged EXPUNGE responses.
         response = await connection.exec('CLOSE');
         response.next();
 
+        // Transition from SELECTED back to AUTHENTICATED state.
+        // Clear mailbox metadata so subsequent operations know no mailbox is selected.
         let currentMailbox = connection.mailbox;
         connection.mailbox = false;
         connection.currentSelectCommand = false;

package/lib/commands/compress.js

@@ -1,7 +1,16 @@
 'use strict';
 
-// Requests compression from server
+/**
+ * Requests DEFLATE compression from the server.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @returns {Promise<boolean>} True if compression was enabled, false otherwise
+ */
+// COMPRESS=DEFLATE (RFC 4978): enables zlib compression on the IMAP connection
+// to reduce bandwidth. Once enabled, all subsequent data in both directions is compressed.
 module.exports = async connection => {
+    // Skip if the server doesn't support COMPRESS=DEFLATE, or if compression
+    // is already active (connection._inflate exists) to avoid double-compression.
     if (!connection.capabilities.has('COMPRESS=DEFLATE') || connection._inflate) {
         // nothing to do here
         return false;

package/lib/commands/copy.js

@@ -2,7 +2,16 @@
 
 const { normalizePath, encodePath, expandRange, enhanceCommandError } = require('../tools.js');
 
-// Copies messages from current mailbox to some other mailbox
+/**
+ * Copies messages from the current mailbox to another mailbox.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} range - Message sequence number or UID range
+ * @param {string} destination - Destination mailbox path
+ * @param {Object} [options] - Copy options
+ * @param {boolean} [options.uid] - If true, use UID COPY instead of COPY
+ * @returns {Promise<{path: string, destination: string, uidValidity?: BigInt, uidMap?: Map}|boolean|undefined>} Copy result with UID mapping if available, false on failure, or undefined if preconditions not met
+ */
 module.exports = async (connection, range, destination, options) => {
     if (connection.state !== connection.states.SELECTED || !range || !destination) {
         // nothing to do here
@@ -23,18 +32,26 @@ module.exports = async (connection, range, destination, options) => {
         response.next();
 
         let map = { path: connection.mailbox.path, destination };
+
+        // UIDPLUS (RFC 4315): the server may include a COPYUID response code in the
+        // tagged OK response, providing a mapping from source UIDs to destination UIDs.
+        // Format: [COPYUID <uidValidity> <sourceUids> <destUids>]
         let section = response.response.attributes && response.response.attributes[0] && response.response.attributes[0].section;
         let responseCode = section && section.length && section[0] && typeof section[0].value === 'string' ? section[0].value : '';
         switch (responseCode) {
             case 'COPYUID':
                 {
+                    // section[1] = destination mailbox UIDVALIDITY
                     let uidValidity = section[1] && typeof section[1].value === 'string' && !isNaN(section[1].value) ? BigInt(section[1].value) : false;
                     if (uidValidity) {
                         map.uidValidity = uidValidity;
                     }
 
+                    // section[2] = source UID set, section[3] = destination UID set
+                    // Both can be ranges (e.g., "1:3") which expandRange() converts to arrays
                     let sourceUids = section[2] && typeof section[2].value === 'string' ? expandRange(section[2].value) : false;
                     let destinationUids = section[3] && typeof section[3].value === 'string' ? expandRange(section[3].value) : false;
+                    // Build a source->destination UID map for the caller to track where messages went
                     if (sourceUids && destinationUids && sourceUids.length === destinationUids.length) {
                         map.uidMap = new Map(sourceUids.map((uid, i) => [uid, destinationUids[i]]));
                     }

package/lib/commands/create.js

@@ -2,7 +2,14 @@
 
 const { encodePath, normalizePath, getStatusCode, enhanceCommandError } = require('../tools.js');
 
-// Creates a new mailbox
+/**
+ * Creates a new mailbox and subscribes to it.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} path - Mailbox path to create
+ * @returns {Promise<{path: string, created: boolean, mailboxId?: string}|undefined>} Object with path and creation status, or undefined if preconditions not met
+ * @throws {Error} If the CREATE command fails (except when mailbox already exists)
+ */
 module.exports = async (connection, path) => {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
         // nothing to do here
@@ -18,6 +25,8 @@ module.exports = async (connection, path) => {
         };
         response = await connection.exec('CREATE', [{ type: 'ATOM', value: encodePath(connection, path) }]);
 
+        // Parse the response code section (e.g., [MAILBOXID (<id>)]) from the tagged OK response.
+        // IMAP response code attributes are structured as alternating key-value pairs.
         let section =
             response.response.attributes &&
             response.response.attributes[0] &&
@@ -29,6 +38,7 @@ module.exports = async (connection, path) => {
         if (section) {
             let key;
             section.forEach((attribute, i) => {
+                // IMAP key-value pairs: even indices (i % 2 === 0) are keys, odd indices are values
                 if (i % 2 === 0) {
                     key = attribute && typeof attribute.value === 'string' ? attribute.value : false;
                     return;
@@ -55,12 +65,15 @@ module.exports = async (connection, path) => {
         map.created = true;
         response.next();
 
-        //make sure we are subscribed to the new folder as well
+        // Auto-subscribe after creation so the new mailbox appears in LSUB listings
+        // and is visible to clients that only show subscribed folders.
         await connection.run('SUBSCRIBE', path);
 
         return map;
     } catch (err) {
         let errorCode = getStatusCode(err.response);
+        // ALREADYEXISTS (RFC 5530) means the mailbox already exists on the server.
+        // This is not a true error -- we return created:false to indicate nothing was created.
         if (errorCode === 'ALREADYEXISTS') {
             // no need to do anything, mailbox already exists
             return {

package/lib/commands/delete.js

@@ -2,7 +2,14 @@
 
 const { encodePath, normalizePath, enhanceCommandError } = require('../tools.js');
 
-// Deletes an existing mailbox
+/**
+ * Deletes an existing mailbox.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} path - Mailbox path to delete
+ * @returns {Promise<{path: string}|undefined>} Object with the deleted path, or undefined if preconditions not met
+ * @throws {Error} If the DELETE command fails
+ */
 module.exports = async (connection, path) => {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
         // nothing to do here
@@ -11,6 +18,8 @@ module.exports = async (connection, path) => {
 
     path = normalizePath(connection, path);
 
+    // If the mailbox to delete is currently selected, we must close/deselect it first.
+    // IMAP servers reject DELETE on the currently selected mailbox (RFC 3501 6.3.4).
     if (connection.state === connection.states.SELECTED && connection.mailbox.path === path) {
         await connection.run('CLOSE');
     }

package/lib/commands/enable.js

@@ -1,12 +1,20 @@
 'use strict';
 
-// Enables extensions
+/**
+ * Enables IMAP extensions on the server.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string[]} extensionList - List of extension names to enable
+ * @returns {Promise<Set|boolean|undefined>} Set of enabled extensions, false on failure, or undefined if not applicable
+ */
 module.exports = async (connection, extensionList) => {
     if (!connection.capabilities.has('ENABLE') || connection.state !== connection.states.AUTHENTICATED) {
         // nothing to do here
         return;
     }
 
+    // Pre-filter: only request extensions the server actually advertised in its
+    // CAPABILITY response. Requesting unsupported extensions would cause an error.
     extensionList = extensionList.filter(extension => connection.capabilities.has(extension.toUpperCase()));
     if (!extensionList.length) {
         return;
@@ -20,6 +28,9 @@ module.exports = async (connection, extensionList) => {
             extensionList.map(extension => ({ type: 'ATOM', value: extension.toUpperCase() })),
             {
                 untagged: {
+                    // The untagged ENABLED response is a flat list of extension names
+                    // (e.g., "* ENABLED CONDSTORE UTF8=ACCEPT"), NOT key-value pairs.
+                    // Each attribute is a single extension identifier.
                     ENABLED: async untagged => {
                         if (!untagged.attributes || !untagged.attributes.length) {
                             return;

package/lib/commands/expunge.js

@@ -2,7 +2,15 @@
 
 const { enhanceCommandError } = require('../tools.js');
 
-// Deletes specified messages
+/**
+ * Deletes specified messages by flagging them as Deleted and expunging.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} range - Message sequence number or UID range
+ * @param {Object} [options] - Expunge options
+ * @param {boolean} [options.uid] - If true, use UID EXPUNGE when UIDPLUS is available
+ * @returns {Promise<boolean|undefined>} True on success, false on failure, or undefined if preconditions not met
+ */
 module.exports = async (connection, range, options) => {
     if (connection.state !== connection.states.SELECTED || !range) {
         // nothing to do here
@@ -11,8 +19,14 @@ module.exports = async (connection, range, options) => {
 
     options = options || {};
 
+    // Two-step deletion process per IMAP protocol:
+    // Step 1: Mark the target messages with the \Deleted flag.
     await connection.messageFlagsAdd(range, ['\\Deleted'], options);
 
+    // Step 2: Issue EXPUNGE to permanently remove \Deleted messages.
+    // With UIDPLUS (RFC 4315): "UID EXPUNGE <uids>" removes only the specified UIDs,
+    // leaving other \Deleted messages untouched -- important for concurrent access.
+    // Without UIDPLUS: plain "EXPUNGE" removes ALL messages flagged \Deleted in the mailbox.
     let byUid = options.uid && connection.capabilities.has('UIDPLUS');
     let command = byUid ? 'UID EXPUNGE' : 'EXPUNGE';
     let attributes = byUid ? [{ type: 'SEQUENCE', value: range }] : false;
@@ -21,7 +35,9 @@ module.exports = async (connection, range, options) => {
     try {
         response = await connection.exec(command, attributes);
 
-        // A OK [HIGHESTMODSEQ 9122] Expunge completed (0.010 + 0.000 + 0.012 secs).
+        // CONDSTORE (RFC 7162): the server may return HIGHESTMODSEQ in the response code
+        // (e.g., "A OK [HIGHESTMODSEQ 9122] Expunge completed").
+        // Track this so the client can detect concurrent mailbox changes via mod-sequences.
         let section = response.response.attributes && response.response.attributes[0] && response.response.attributes[0].section;
         let responseCode = section && section.length && section[0] && typeof section[0].value === 'string' ? section[0].value : '';
         if (responseCode.toUpperCase() === 'HIGHESTMODSEQ') {

package/lib/commands/fetch.js

@@ -2,7 +2,19 @@
 
 const { formatMessageResponse } = require('../tools');
 
-// Fetches emails from server
+/**
+ * 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
+ */
 module.exports = async (connection, range, query, options) => {
     if (connection.state !== connection.states.SELECTED || !range) {
         // nothing to do here
@@ -13,8 +25,10 @@ module.exports = async (connection, range, query, options) => {
 
     let mailbox = connection.mailbox;
 
+    // Use BINARY extension for fetching if supported and requested, otherwise fall back to BODY
     const commandKey = connection.capabilities.has('BINARY') && 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
@@ -31,6 +45,9 @@ module.exports = async (connection, range, query, options) => {
 
             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 bodyPeek = {
                     type: 'ATOM',
@@ -50,6 +67,7 @@ module.exports = async (connection, range, query, options) => {
                 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() });
@@ -60,6 +78,7 @@ module.exports = async (connection, range, query, options) => {
                 queryStructure.push({ type: 'ATOM', value: 'RFC822.SIZE' });
             }
 
+            // Fetch full message source, optionally with byte range (start/maxLength)
             if (query.source) {
                 let partial;
                 if (typeof query.source === 'object' && (query.source.start || query.source.maxLength)) {
@@ -71,13 +90,15 @@ module.exports = async (connection, range, query, options) => {
                 queryStructure.push({ type: 'ATOM', value: `${commandKey}.PEEK`, section: [], partial });
             }
 
-            // if possible, always request for unique email id
+            // 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')) {
                 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' });
@@ -86,6 +107,7 @@ module.exports = async (connection, range, query, options) => {
                 }
             }
 
+            // 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' });
@@ -97,11 +119,13 @@ module.exports = async (connection, range, query, options) => {
                 queryStructure.push({ type: 'ATOM', value: 'MODSEQ' });
             }
 
-            // always make sure to include UID in the request as well even though server might auto-add it itself
+            // 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 }))]);
@@ -110,6 +134,8 @@ module.exports = async (connection, range, query, options) => {
                 }
             }
 
+            // 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) {
                 query.bodyParts.forEach(part => {
                     if (!part) {
@@ -138,12 +164,16 @@ module.exports = async (connection, range, query, options) => {
                 });
             }
 
+            // 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.
             if (queryStructure.length === 1) {
                 queryStructure = queryStructure.pop();
             }
 
             attributes.push(queryStructure);
 
+            // 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) {
                 let changedSinceArgs = [
                     {
@@ -168,6 +198,9 @@ module.exports = async (connection, range, query, options) => {
 
             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 => {
                         messages.count++;
                         let formatted = await formatMessageResponse(untagged, mailbox);
@@ -192,7 +225,9 @@ module.exports = async (connection, range, query, options) => {
             return messages;
         } catch (err) {
             if (err.code === 'ETHROTTLE') {
-                // Calculate exponential backoff delay
+                // 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