imapflow 1.2.8 → 1.2.10

package/lib/tools.js

@@ -11,11 +11,21 @@ const iconv = require('iconv-lite');
 
 const FLAG_COLORS = ['red', 'orange', 'yellow', 'green', 'blue', 'purple', 'grey'];
 
+/**
+ * Error subclass thrown when IMAP authentication fails.
+ */
 class AuthenticationFailure extends Error {
     authenticationFailed = true;
 }
 
 const tools = {
+    /**
+     * Encodes a mailbox path to modified UTF-7 if the server does not support UTF8=ACCEPT.
+     *
+     * @param {Object} connection - IMAP connection instance
+     * @param {String} path - Mailbox path to encode
+     * @returns {String} Encoded mailbox path
+     */
     encodePath(connection, path) {
         path = (path || '').toString();
         if (!connection.enabled.has('UTF8=ACCEPT') && /[&\x00-\x08\x0b-\x0c\x0e-\x1f\u0080-\uffff]/.test(path)) {
@@ -28,6 +38,13 @@ const tools = {
         return path;
     },
 
+    /**
+     * Decodes a mailbox path from modified UTF-7 if the server does not support UTF8=ACCEPT.
+     *
+     * @param {Object} connection - IMAP connection instance
+     * @param {String} path - Mailbox path to decode
+     * @returns {String} Decoded mailbox path
+     */
     decodePath(connection, path) {
         path = (path || '').toString();
         if (!connection.enabled.has('UTF8=ACCEPT') && /[&]/.test(path)) {
@@ -40,6 +57,15 @@ const tools = {
         return path;
     },
 
+    /**
+     * Normalizes a mailbox path by joining array segments with the namespace delimiter,
+     * uppercasing INBOX, and prepending the namespace prefix if needed.
+     *
+     * @param {Object} connection - IMAP connection instance
+     * @param {String|String[]} path - Mailbox path or array of path segments
+     * @param {Boolean} [skipNamespace] - If true, skips prepending the namespace prefix
+     * @returns {String} Normalized mailbox path
+     */
     normalizePath(connection, path, skipNamespace) {
         if (Array.isArray(path)) {
             path = path.join((connection.namespace && connection.namespace.delimiter) || '');
@@ -58,6 +84,14 @@ const tools = {
         return path;
     },
 
+    /**
+     * Compares two mailbox paths for equality after normalization.
+     *
+     * @param {Object} connection - IMAP connection instance
+     * @param {String} a - First mailbox path
+     * @param {String} b - Second mailbox path
+     * @returns {Boolean} True if the paths are equal after normalization
+     */
     comparePaths(connection, a, b) {
         if (!a || !b) {
             return false;
@@ -65,6 +99,12 @@ const tools = {
         return tools.normalizePath(connection, a) === tools.normalizePath(connection, b);
     },
 
+    /**
+     * Parses a capability response list into a Map of capability names to values.
+     *
+     * @param {Array} list - Array of capability objects from IMAP response
+     * @returns {Map<string, boolean|number>} Map of capability names to `true` or numeric values
+     */
     updateCapabilities(list) {
         let map = new Map();
 
@@ -96,6 +136,13 @@ const tools = {
 
     AuthenticationFailure,
 
+    /**
+     * Extracts the IMAP response status code (e.g. AUTHENTICATIONFAILED, NONEXISTENT)
+     * from a parsed server response.
+     *
+     * @param {Object} response - Parsed IMAP server response
+     * @returns {String|false} Uppercase status code string, or false if not found
+     */
     getStatusCode(response) {
         return response &&
             response.attributes &&
@@ -107,6 +154,12 @@ const tools = {
             : false;
     },
 
+    /**
+     * Compiles an IMAP response object back into a human-readable string.
+     *
+     * @param {Object} response - Parsed IMAP server response
+     * @returns {Promise<String|false>} Compiled response text, or false if no response
+     */
     async getErrorText(response) {
         if (!response) {
             return false;
@@ -115,6 +168,12 @@ const tools = {
         return (await compiler(response)).toString();
     },
 
+    /**
+     * Enhances an IMAP command error with the server response code and text.
+     *
+     * @param {Error} err - Error object with a `response` property
+     * @returns {Promise<Error>} The enhanced error with `serverResponseCode` and string `response`
+     */
     async enhanceCommandError(err) {
         let errorCode = tools.getStatusCode(err.response);
         if (errorCode) {
@@ -124,6 +183,12 @@ const tools = {
         return err;
     },
 
+    /**
+     * Converts a flat list of mailbox folders into a tree structure.
+     *
+     * @param {Object[]} folders - Array of folder objects from LIST/LSUB response
+     * @returns {Object} Tree structure with a `root` flag and nested `folders` arrays
+     */
     getFolderTree(folders) {
         let tree = {
             root: true,
@@ -212,11 +277,21 @@ const tools = {
         return tree;
     },
 
+    /**
+     * Derives a flag color name from a message's flags Set using Apple Mail color flag rules.
+     *
+     * @param {Set<string>} flags - Message flags Set
+     * @returns {String|null} Color name (e.g. 'red', 'orange') or null if not flagged
+     */
     getFlagColor(flags) {
         if (!flags.has('\\Flagged')) {
             return null;
         }
 
+        // Apple Mail encodes flag colors as a 3-bit value using $MailFlagBit0/1/2 keywords.
+        // Bit 0 = 1, Bit 1 = 2, Bit 2 = 4. The resulting integer (0-6) indexes into FLAG_COLORS:
+        // 0=red, 1=orange, 2=yellow, 3=green, 4=blue, 5=purple, 6=grey.
+        // Value 7 (all bits set) is unused; defaults to red.
         const bit0 = flags.has('$MailFlagBit0') ? 1 : 0;
         const bit1 = flags.has('$MailFlagBit1') ? 2 : 0;
         const bit2 = flags.has('$MailFlagBit2') ? 4 : 0;
@@ -226,19 +301,30 @@ const tools = {
         return FLAG_COLORS[color] || 'red'; // default to red for the unused \b111
     },
 
+    /**
+     * Converts a color name to the corresponding flag add/remove operations for Apple Mail color flags.
+     *
+     * @param {String} color - Color name (e.g. 'red', 'orange', 'yellow')
+     * @returns {Object|null} Object with `add` and `remove` arrays of flag strings, or null if invalid color
+     */
     getColorFlags(color) {
+        // Reverse mapping from a color name to the Apple Mail $MailFlagBit0/1/2 flags.
+        // Returns an object with 'add' and 'remove' arrays so the caller can STORE +FLAGS/-FLAGS.
         const colorCode = color ? FLAG_COLORS.indexOf((color || '').toString().toLowerCase().trim()) : null;
         if (colorCode < 0 && colorCode !== null) {
             return null;
         }
 
+        // Decompose color index back into its 3-bit representation
         const bits = [];
         bits[0] = colorCode & 1; // eslint-disable-line no-bitwise
         bits[1] = colorCode & 2; // eslint-disable-line no-bitwise
         bits[2] = colorCode & 4; // eslint-disable-line no-bitwise
 
+        // If colorCode is truthy (non-zero), add \Flagged; if zero/null, remove \Flagged
         let result = { add: colorCode ? ['\\Flagged'] : [], remove: colorCode ? [] : ['\\Flagged'] };
 
+        // For each bit, add the corresponding $MailFlagBitN if set, remove it if unset
         for (let i = 0; i < bits.length; i++) {
             if (bits[i]) {
                 result.add.push(`$MailFlagBit${i}`);
@@ -249,6 +335,13 @@ const tools = {
         return result;
     },
 
+    /**
+     * Formats a raw untagged FETCH response into a structured message object.
+     *
+     * @param {Object} untagged - Parsed untagged IMAP response
+     * @param {Object} mailbox - Current mailbox state object
+     * @returns {Promise<Object>} Formatted message object with properties like seq, uid, flags, envelope, etc.
+     */
     async formatMessageResponse(untagged, mailbox) {
         let map = {};
 
@@ -309,25 +402,33 @@ const tools = {
 
                 case 'uid':
                     map.uid = Number(getString(attribute));
+                    // If the UID we just saw is >= the mailbox's uidNext, bump uidNext.
+                    // This keeps the local uidNext estimate current without requiring a
+                    // separate STATUS command, handling cases where new messages arrived
+                    // since the last SELECT/EXAMINE.
                     if (map.uid && (!mailbox.uidNext || mailbox.uidNext <= map.uid)) {
-                        // current uidNext seems to be outdated, bump it
                         mailbox.uidNext = map.uid + 1;
                     }
                     break;
 
                 case 'modseq':
                     map.modseq = BigInt(getArray(attribute)[0]);
+                    // Similarly, keep the local highestModseq estimate up to date.
+                    // This is critical for CONDSTORE/QRESYNC delta syncing.
                     if (map.modseq && (!mailbox.highestModseq || mailbox.highestModseq < map.modseq)) {
-                        // current highestModseq seems to be outdated, bump it
                         mailbox.highestModseq = map.modseq;
                     }
                     break;
 
                 case 'emailid':
+                    // OBJECTID extension (RFC 8474): server-assigned stable email identifier
                     map.emailId = getArray(attribute)[0];
                     break;
 
                 case 'x-gm-msgid':
+                    // Gmail extension: X-GM-MSGID is Gmail's unique message ID.
+                    // Mapped to the same emailId field as OBJECTID for a unified API,
+                    // but this is a Gmail-specific numeric string, not an RFC 8474 ObjectID.
                     map.emailId = getString(attribute);
                     break;
 
@@ -423,6 +524,12 @@ const tools = {
         return map;
     },
 
+    /**
+     * Strips surrounding double quotes from a name string.
+     *
+     * @param {String} name - Raw name string potentially wrapped in quotes
+     * @returns {String} Name with surrounding quotes removed
+     */
     processName(name) {
         name = (name || '').toString();
         if (name.length > 2 && name.at(0) === '"' && name.at(-1) === '"') {
@@ -431,6 +538,12 @@ const tools = {
         return name;
     },
 
+    /**
+     * Parses a raw IMAP ENVELOPE response into a structured envelope object.
+     *
+     * @param {Array} entry - Raw envelope data array from IMAP response
+     * @returns {Object} Parsed envelope with date, subject, from, to, cc, bcc, messageId, etc.
+     */
     parseEnvelope(entry) {
         let getStrValue = obj => {
             if (!obj) {
@@ -510,11 +623,19 @@ const tools = {
         return envelope;
     },
 
+    /**
+     * Parses structured MIME parameter arrays (including RFC 2231 continuations)
+     * into a flat key-value object.
+     *
+     * @param {Array} arr - Raw parameter array from BODYSTRUCTURE response
+     * @returns {Object} Key-value object of decoded parameters
+     */
     getStructuredParams(arr) {
         let key;
 
         let params = {};
 
+        // BODYSTRUCTURE parameters come as flat key/value pairs: [key1, val1, key2, val2, ...]
         [].concat(arr || []).forEach((val, j) => {
             if (j % 2) {
                 params[key] = libmime.decodeWords(((val && val.value) || '').toString());
@@ -523,6 +644,8 @@ const tools = {
             }
         });
 
+        // Detect RFC 2231 encoded filenames that were placed in the plain 'filename' param
+        // instead of 'filename*'. The pattern charset'language'encoded_value indicates encoding.
         if (params.filename && !params['filename*'] && /^[a-z\-_0-9]+'[a-z]*'[^'\x00-\x08\x0b\x0c\x0e-\x1f\u0080-\uFFFF]+/.test(params.filename)) {
             // seems like encoded value
             let [encoding, , encodedValue] = params.filename.split("'");
@@ -531,12 +654,15 @@ const tools = {
             }
         }
 
-        // preprocess values
+        // RFC 2231 parameter continuations: parameters like filename*0, filename*1, etc.
+        // are split parts of a single value. Parameters ending with '*' contain charset info.
+        // This pass collects continuation parts and groups them by their base key name.
         Object.keys(params).forEach(key => {
             let actualKey;
             let nr;
             let value;
 
+            // Match keys ending with *N or *N* (where N is the continuation index)
             let match = key.match(/\*((\d+)\*?)?$/);
 
             if (!match) {
@@ -556,6 +682,7 @@ const tools = {
 
             value = params[key];
 
+            // The first segment (*0*) may contain charset and language: charset'language'value
             if (nr === 0 && match[0].charAt(match[0].length - 1) === '*' && (match = value.match(/^([^']*)'[^']*'(.*)$/))) {
                 params[actualKey].charset = match[1] || 'utf-8';
                 value = match[2];
@@ -567,7 +694,9 @@ const tools = {
             delete params[key];
         });
 
-        // concatenate split rfc2231 strings and convert encoded strings to mime encoded words
+        // Reassemble split RFC 2231 strings by sorting continuation parts and joining them.
+        // For charset-encoded values, convert URL-encoded (%XX) sequences to MIME quoted-printable
+        // format (=?charset?Q?...?=) so libmime.decodeWords can decode them to Unicode.
         Object.keys(params).forEach(key => {
             let value;
             if (params[key] && Array.isArray(params[key].values)) {
@@ -577,7 +706,10 @@ const tools = {
                     .join('');
 
                 if (params[key].charset) {
-                    // convert "%AB" to "=?charset?Q?=AB?=" and then to unicode
+                    // Convert URL encoding (%AB) to MIME quoted-printable (=AB) by:
+                    // 1. Escaping QP-special chars (=, ?, _, space) as %XX
+                    // 2. Replacing all '%' with '=' to switch from URL encoding to QP encoding
+                    // 3. Wrapping in =?charset?Q?...?= for libmime to decode
                     params[key] = libmime.decodeWords(
                         '=?' +
                             params[key].charset +
@@ -605,7 +737,16 @@ const tools = {
         return params;
     },
 
+    /**
+     * Parses a raw IMAP BODYSTRUCTURE response into a structured tree of body parts.
+     *
+     * @param {Array} entry - Raw BODYSTRUCTURE data array from IMAP response
+     * @returns {Object} Parsed body structure tree with part numbers, types, parameters, and child nodes
+     */
     parseBodystructure(entry) {
+        // Recursively walks the BODYSTRUCTURE tree, building MIME part numbers.
+        // Part numbers follow the IMAP dot-notation: "1", "1.1", "2.3", etc.
+        // The root multipart has no part number; its children start at 1.
         let walk = (node, path) => {
             path = path || [];
 
@@ -613,13 +754,15 @@ const tools = {
                 i = 0,
                 part = 0;
 
+            // Build the dot-separated part number from the path array (e.g., [1,2] -> "1.2")
             if (path.length) {
                 curNode.part = path.join('.');
             }
 
-            // multipart
+            // multipart: first elements are arrays (child body parts), followed by the subtype string
             if (Array.isArray(node[0])) {
                 curNode.childNodes = [];
+                // Each child array is a nested body part; increment part counter for each
                 while (Array.isArray(node[i])) {
                     curNode.childNodes.push(walk(node[i], path.concat(++part)));
                     i++;
@@ -672,9 +815,11 @@ const tools = {
                 i++;
 
                 if (curNode.type === 'message/rfc822') {
-                    // message/rfc adds additional envelope, bodystructure and line count values
+                    // message/rfc822 is special in IMAP BODYSTRUCTURE: after the standard
+                    // 7 fields, it includes an embedded envelope, a nested bodystructure,
+                    // and a line count for the encapsulated message.
 
-                    // envelope
+                    // envelope of the encapsulated message
                     if (node[i]) {
                         curNode.envelope = tools.parseEnvelope([].concat(node[i] || []));
                     }
@@ -682,9 +827,10 @@ const tools = {
 
                     if (node[i]) {
                         curNode.childNodes = [
-                            // rfc822 bodyparts share the same path, difference is between MIME and HEADER
-                            // path.MIME returns message/rfc822 header
-                            // path.HEADER returns inlined message header
+                            // The nested bodystructure reuses the same path (not path+1) because
+                            // the encapsulated message shares the part number with its wrapper.
+                            // Distinction is via suffixes: path.MIME = wrapper headers,
+                            // path.HEADER = encapsulated message headers.
                             walk(node[i], path)
                         ];
                     }
@@ -698,12 +844,13 @@ const tools = {
                 }
 
                 if (/^text\//.test(curNode.type)) {
-                    // text/* adds additional line count value
+                    // Per RFC 3501, text/* parts include an additional line count field after size.
+                    // However, some servers omit this field, producing 11 elements instead of 12+.
 
                     // NB! some less known servers do not include the line count value
                     // length should be 12+
                     if (node.length === 11 && Array.isArray(node[i + 1]) && !Array.isArray(node[i + 2])) {
-                        // invalid structure, disposition params are shifted
+                        // invalid structure, disposition params are shifted -- skip the line count
                     } else {
                         // correct structure, line count number is provided
                         if (node[i]) {
@@ -763,10 +910,22 @@ const tools = {
         return walk(entry);
     },
 
+    /**
+     * Checks if a value is a Date object.
+     *
+     * @param {*} obj - Value to check
+     * @returns {Boolean} True if the value is a Date object
+     */
     isDate(obj) {
         return Object.prototype.toString.call(obj) === '[object Date]';
     },
 
+    /**
+     * Converts a value to a valid Date object, or returns null.
+     *
+     * @param {*} value - Date object or date string to convert
+     * @returns {Date|null} Valid Date object, or null if conversion fails
+     */
     toValidDate(value) {
         if (!value) {
             return null;
@@ -780,6 +939,12 @@ const tools = {
         return value;
     },
 
+    /**
+     * Formats a date value into IMAP date format (DD-Mon-YYYY).
+     *
+     * @param {Date|String} value - Date to format
+     * @returns {String|undefined} Formatted date string, or undefined if invalid
+     */
     formatDate(value) {
         value = tools.toValidDate(value);
         if (!value) {
@@ -795,6 +960,12 @@ const tools = {
         return dateParts.join('-');
     },
 
+    /**
+     * Formats a date value into IMAP date-time format (DD-Mon-YYYY HH:MM:SS +0000).
+     *
+     * @param {Date|String} value - Date to format
+     * @returns {String|undefined} Formatted date-time string, or undefined if invalid
+     */
     formatDateTime(value) {
         value = tools.toValidDate(value);
         if (!value) {
@@ -807,6 +978,13 @@ const tools = {
         return `${dateStr} ${timeStr} +0000`;
     },
 
+    /**
+     * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent),
+     * and capitalizes system flags properly.
+     *
+     * @param {String} flag - Flag string to normalize
+     * @returns {String|false} Normalized flag string, or false if the flag cannot be set
+     */
     formatFlag(flag) {
         switch (flag.toLowerCase()) {
             case '\\recent':
@@ -823,10 +1001,23 @@ const tools = {
         return flag;
     },
 
+    /**
+     * Checks if a flag can be used in the given mailbox based on permanent flags.
+     *
+     * @param {Object} mailbox - Mailbox object with permanentFlags
+     * @param {String} flag - Flag to check
+     * @returns {Boolean} True if the flag is allowed
+     */
     canUseFlag(mailbox, flag) {
         return !mailbox || !mailbox.permanentFlags || mailbox.permanentFlags.has('\\*') || mailbox.permanentFlags.has(flag);
     },
 
+    /**
+     * Expands an IMAP sequence range string (e.g. "1:3,5,7:9") into an array of numbers.
+     *
+     * @param {String} range - IMAP sequence range string
+     * @returns {Number[]} Array of expanded sequence numbers
+     */
     expandRange(range) {
         return range.split(',').flatMap(entry => {
             entry = entry.trim();
@@ -853,6 +1044,13 @@ const tools = {
         });
     },
 
+    /**
+     * Returns a stream decoder for the given charset. Uses a special Japanese
+     * charset decoder for JIS/ISO-2022-JP, otherwise delegates to iconv-lite.
+     *
+     * @param {String} [charset='ascii'] - Character set name
+     * @returns {Object} A stream decoder (Transform stream) for the charset
+     */
     getDecoder(charset) {
         charset = (charset || 'ascii').toString().trim().toLowerCase();
         if (/^jis|^iso-?2022-?jp|^EUCJP/i.test(charset)) {
@@ -863,6 +1061,13 @@ const tools = {
         return iconv.decodeStream(charset);
     },
 
+    /**
+     * Packs an array of message sequence numbers into a compact IMAP range string
+     * (e.g. [1,2,3,5,7,8] becomes "1:3,5,7:8").
+     *
+     * @param {Number|Number[]} list - Sequence number or array of sequence numbers
+     * @returns {String} Packed IMAP sequence range string
+     */
     packMessageRange(list) {
         if (!Array.isArray(list)) {
             list = [].concat(list || []);

package/package.json

@@ -1,16 +1,12 @@
 {
     "name": "imapflow",
-    "version": "1.2.8",
+    "version": "1.2.10",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",
     "scripts": {
         "test": "grunt",
         "coverage": "c8 --reporter=text --reporter=html npx nodeunit test/*-test.js",
-        "prepare": "npm run build",
-        "docs": "rm -rf docs && mkdir -p docs && jsdoc lib/imap-flow.js -c jsdoc.json -R README.md --destination docs/ && cp assets/favicon.ico docs",
-        "build": "npm run docs",
-        "st": "npm run docs && st -d docs -i index.html",
         "update": "rm -rf node_modules package-lock.json && ncu -u && npm install",
         "format": "prettier --write \"**/*.{js,json,md,yml,yaml}\" --ignore-path .prettierignore",
         "lint": "eslint ."
@@ -31,13 +27,8 @@
     },
     "homepage": "https://imapflow.com/",
     "devDependencies": {
-        "@babel/eslint-parser": "7.28.6",
-        "@babel/eslint-plugin": "7.27.1",
-        "@babel/plugin-syntax-class-properties": "7.12.13",
-        "@babel/preset-env": "7.28.6",
-        "@eslint/eslintrc": "3.3.3",
         "@eslint/js": "9.39.2",
-        "@types/node": "25.1.0",
+        "@types/node": "25.3.0",
         "c8": "10.1.3",
         "eslint": "9.39.2",
         "eslint-config-nodemailer": "1.2.0",
@@ -45,12 +36,9 @@
         "grunt": "1.6.1",
         "grunt-cli": "1.5.0",
         "grunt-contrib-nodeunit": "5.0.0",
-        "grunt-eslint": "24.3.0",
-        "imapflow-jsdoc-template": "3.4.0-imapflow.3",
-        "jsdoc": "4.0.4",
+        "grunt-eslint": "26.0.0",
         "prettier": "3.8.1",
         "proxyquire": "^2.1.3",
-        "st": "3.0.3",
         "typescript": "5.9.3"
     },
     "dependencies": {
@@ -60,8 +48,8 @@
         "libbase64": "1.3.0",
         "libmime": "5.3.7",
         "libqp": "2.1.1",
-        "nodemailer": "7.0.13",
-        "pino": "10.3.0",
+        "nodemailer": "8.0.1",
+        "pino": "10.3.1",
         "socks": "2.8.7"
     }
 }

package/test/commands-integration-test.js

@@ -3858,6 +3858,39 @@ module.exports['Commands: list sort fallback path comparison'] = async test => {
     test.done();
 };
 
+module.exports['Commands: list STATUS handles unknown key in response'] = async test => {
+    const connection = createMockConnection({
+        state: 3,
+        capabilities: new Map([
+            ['SPECIAL-USE', true],
+            ['LIST-STATUS', true]
+        ]),
+        exec: async (cmd, attrs, opts) => {
+            if (cmd === 'LIST' && opts && opts.untagged) {
+                if (opts.untagged.LIST) {
+                    await opts.untagged.LIST({
+                        attributes: [[{ value: '\\HasNoChildren' }], { value: '/' }, { value: 'TestFolder' }]
+                    });
+                }
+                if (opts.untagged.STATUS) {
+                    await opts.untagged.STATUS({
+                        attributes: [{ value: 'TestFolder' }, [{ value: 'XUNKNOWN' }, { value: '999' }, { value: 'MESSAGES' }, { value: '10' }]]
+                    });
+                }
+            }
+            return { next: () => {} };
+        }
+    });
+
+    const result = await listCommand(connection, '', '*', { statusQuery: { messages: true } });
+    const folder = result.find(e => e.path === 'TestFolder');
+    test.ok(folder);
+    test.ok(folder.status);
+    test.equal(folder.status.messages, 10);
+    test.equal(folder.status.XUNKNOWN, undefined); // Unknown keys silently ignored
+    test.done();
+};
+
 // ============================================
 // SELECT Command Tests
 // ============================================