imapflow 1.2.8 → 1.2.9

package/.ncurc.js

@@ -1,4 +1,4 @@
 module.exports = {
     upgrade: true,
-    reject: ['jsdoc', 'grunt-eslint']
+    reject: ['grunt-eslint']
 };

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.2.8"
+    ".": "1.2.9"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.2.9](https://github.com/postalsys/imapflow/compare/v1.2.8...v1.2.9) (2026-02-06)
+
+
+### Bug Fixes
+
+* trigger build ([fd7a4c2](https://github.com/postalsys/imapflow/commit/fd7a4c2012d0b7742c45a2aced2d05da8401aa9a))
+
 ## [1.2.8](https://github.com/postalsys/imapflow/compare/v1.2.7...v1.2.8) (2026-01-28)
 
 

package/README.md

@@ -7,7 +7,7 @@ ImapFlow is a modern and easy-to-use IMAP client library for Node.js.
 
 The focus for ImapFlow is to provide easy to use API over IMAP. Using ImapFlow does not expect knowledge about specific IMAP details. A general understanding is good enough.
 
-IMAP extensions are handled in the background, so, for example, you can always request `labels` value from a {@link FetchQueryObject|fetch()} call, but if the IMAP server does not support `X-GM-EXT-1` extension, then `labels` value is not included in the response.
+IMAP extensions are handled in the background, so, for example, you can always request `labels` value from a `fetch()` call, but if the IMAP server does not support `X-GM-EXT-1` extension, then `labels` value is not included in the response.
 
 ## Source
 
@@ -100,10 +100,10 @@ await client.connect();
 
 ## Documentation
 
-[API reference](https://imapflow.com/module-imapflow-ImapFlow.html).
+[API reference](https://imapflow.com/docs/api/imapflow-client).
 
 ## License
 
-© 2020-2024 Postal Systems OÜ
+© 2020-2025 Postal Systems OÜ
 
 Licensed under **MIT-license**

package/lib/charsets.js

@@ -1,5 +1,8 @@
 'use strict';
 
+// Subset of the IANA Character Sets registry (https://www.iana.org/assignments/character-sets/).
+// Used to validate and resolve charset names found in MIME Content-Type parameters.
+// This list covers the most commonly encountered charsets in email messages.
 const CHARACTER_SETS = [
     'US-ASCII',
     'ISO-8859-1',
@@ -262,6 +265,14 @@ const CHARACTER_SETS = [
 
 const CHARSET_MAP = new Map();
 
+// Build a lookup map with normalized keys for fuzzy charset resolution.
+// Normalization strategy:
+// 1. Strip all underscores, hyphens, and spaces, then lowercase (e.g., "ISO-8859-1" -> "iso88591")
+// 2. Create additional aliases for common alternative prefixes:
+//    - "windows" -> "win" (e.g., "windows1252" also matches as "win1252")
+//    - "usascii" -> "ascii" (common shorthand)
+//    - "iso8859" -> "latin" (e.g., "iso88591" also matches as "latin1")
+// This handles the many variant spellings found in real-world email headers.
 CHARACTER_SETS.forEach(entry => {
     let key = entry.replace(/[_-\s]/g, '').toLowerCase();
     let modifiedKey = key
@@ -274,6 +285,10 @@ CHARACTER_SETS.forEach(entry => {
     }
 });
 
+// Resolves a charset name to its canonical IANA form using case-insensitive,
+// symbol-stripping normalization. For example, "WIN-1252", "windows_1252",
+// and "WINDOWS-1252" all resolve to "windows-1252".
+// Returns null if the charset is not recognized.
 module.exports.resolveCharset = charset => {
     let key = charset.replace(/[_-\s]/g, '').toLowerCase();
     if (CHARSET_MAP.has(key)) {

package/lib/commands/append.js

@@ -2,7 +2,17 @@
 
 const { formatFlag, canUseFlag, formatDateTime, normalizePath, encodePath, comparePaths, enhanceCommandError } = require('../tools.js');
 
-// Appends a message to a mailbox
+/**
+ * Appends a message to a mailbox.
+ *
+ * @param {Object} connection - IMAP connection instance
+ * @param {string} destination - Destination mailbox path
+ * @param {Buffer|string} content - Message content (RFC 822 format)
+ * @param {string|string[]} [flags] - Message flags to set on the appended message
+ * @param {Date|string} [idate] - Internal date to set for the message
+ * @returns {Promise<{destination: string, path?: string, uid?: number, uidValidity?: BigInt, seq?: number}|undefined>} Append result with UID info if available, or undefined if preconditions not met
+ * @throws {Error} If the APPEND command fails or message exceeds APPENDLIMIT
+ */
 module.exports = async (connection, destination, content, flags, idate) => {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state) || !destination) {
         // nothing to do here
@@ -13,6 +23,8 @@ module.exports = async (connection, destination, content, flags, idate) => {
         content = Buffer.from(content);
     }
 
+    // APPENDLIMIT capability (RFC 7889): server may advertise the maximum message
+    // size it accepts. Check before sending to avoid a wasted round-trip.
     if (connection.capabilities.has('APPENDLIMIT')) {
         let appendLimit = connection.capabilities.get('APPENDLIMIT');
         if (typeof appendLimit === 'number' && appendLimit < content.length) {
@@ -24,28 +36,36 @@ module.exports = async (connection, destination, content, flags, idate) => {
 
     destination = normalizePath(connection, destination);
 
+    // If appending to the currently selected mailbox, we can listen for the
+    // untagged EXISTS response to capture the new message's sequence number.
     let expectExists = comparePaths(connection, connection.mailbox.path, destination);
 
+    // Validate and format flags. Only flags allowed by the mailbox's permanentFlags are included.
     flags = (Array.isArray(flags) ? flags : [].concat(flags || []))
         .map(flag => flag && formatFlag(flag.toString()))
         .filter(flag => flag && canUseFlag(connection.mailbox, flag));
 
+    // APPEND command format: APPEND <mailbox> [<flags>] [<date-time>] <literal>
     let attributes = [{ type: 'ATOM', value: encodePath(connection, destination) }];
 
+    // Internal date: the date the server should record for this message.
+    // Must be quoted (STRING type) per the IMAP date-time grammar.
     idate = idate ? formatDateTime(idate) : false;
 
+    // Flags and date are optional; flags must come before date if both are present
     if (flags.length || idate) {
         attributes.push(flags.map(flag => ({ type: 'ATOM', value: flag })));
     }
 
     if (idate) {
-        attributes.push({ type: 'STRING', value: idate }); // force quotes as required by date-time
+        attributes.push({ type: 'STRING', value: idate });
     }
 
+    // BINARY extension (RFC 3516): if the message content contains NUL bytes,
+    // use literal8 syntax (~{size}\r\n) instead of regular literal ({size}\r\n).
+    // Regular literals cannot contain NUL bytes per the IMAP grammar.
     let isLiteral8 = false;
     if (connection.capabilities.has('BINARY') && !connection.disableBinary) {
-        // Value is literal8 if it contains NULL bytes. The server must support the BINARY extension
-        // and if it does not then send the value as a regular literal and hope for the best
         isLiteral8 = content.indexOf(Buffer.from([0])) >= 0;
     }
 
@@ -56,72 +76,58 @@ module.exports = async (connection, destination, content, flags, idate) => {
         map.path = connection.mailbox.path;
     }
 
+    // Handler for untagged EXISTS: captures the new message count which gives
+    // us the sequence number of the appended message (it's the latest message).
+    const handleExistsUpdate = untagged => {
+        map.seq = Number(untagged.command);
+
+        // Update the connection's mailbox state and emit 'exists' event if the
+        // count changed (notifies listeners about the new message).
+        if (expectExists) {
+            let prevCount = connection.mailbox.exists;
+            if (map.seq !== prevCount) {
+                connection.mailbox.exists = map.seq;
+                connection.emit('exists', {
+                    path: connection.mailbox.path,
+                    count: map.seq,
+                    prevCount
+                });
+            }
+        }
+    };
+
     let response;
     try {
         response = await connection.exec('APPEND', attributes, {
-            untagged: expectExists
-                ? {
-                      EXISTS: async untagged => {
-                          map.seq = Number(untagged.command);
-
-                          if (expectExists) {
-                              let prevCount = connection.mailbox.exists;
-                              if (map.seq !== prevCount) {
-                                  connection.mailbox.exists = map.seq;
-                                  connection.emit('exists', {
-                                      path: connection.mailbox.path,
-                                      count: map.seq,
-                                      prevCount
-                                  });
-                              }
-                          }
-                      }
-                  }
-                : false
+            // Only listen for EXISTS if we're appending to the currently selected mailbox
+            untagged: expectExists ? { EXISTS: handleExistsUpdate } : false
         });
 
+        // UIDPLUS (RFC 4315): the server may include APPENDUID response code in
+        // the tagged OK. Format: [APPENDUID <uidValidity> <uid>]
         let section = response.response.attributes && response.response.attributes[0] && response.response.attributes[0].section;
         if (section && section.length) {
             let responseCode = section[0] && typeof section[0].value === 'string' ? section[0].value : '';
-            switch (responseCode.toUpperCase()) {
-                case 'APPENDUID':
-                    {
-                        let uidValidity = section[1] && typeof section[1].value === 'string' && !isNaN(section[1].value) ? BigInt(section[1].value) : false;
-                        let uid = section[2] && typeof section[2].value === 'string' && !isNaN(section[2].value) ? Number(section[2].value) : false;
-                        if (uidValidity) {
-                            map.uidValidity = uidValidity;
-                        }
-                        if (uid) {
-                            map.uid = uid;
-                        }
-                    }
-                    break;
+            if (responseCode.toUpperCase() === 'APPENDUID') {
+                let uidValidity = section[1] && typeof section[1].value === 'string' && !isNaN(section[1].value) ? BigInt(section[1].value) : false;
+                let uid = section[2] && typeof section[2].value === 'string' && !isNaN(section[2].value) ? Number(section[2].value) : false;
+                if (uidValidity) {
+                    map.uidValidity = uidValidity;
+                }
+                if (uid) {
+                    map.uid = uid;
+                }
             }
         }
 
         response.next();
 
+        // If we didn't get an EXISTS during APPEND (some servers don't send it
+        // until the next command), issue a NOOP to flush pending notifications.
         if (expectExists && !map.seq) {
-            // try to use NOOP to get the new sequence number
             try {
                 response = await connection.exec('NOOP', false, {
-                    untagged: {
-                        EXISTS: async untagged => {
-                            map.seq = Number(untagged.command);
-
-                            if (expectExists) {
-                                let prevCount = connection.mailbox.exists;
-                                if (map.seq !== prevCount) {
-                                    connection.mailbox.exists = map.seq;
-                                    connection.emit('exists', {
-                                        path: connection.mailbox.path,
-                                        count: map.seq,
-                                        prevCount
-                                    });
-                                }
-                            }
-                        }
-                    },
+                    untagged: { EXISTS: handleExistsUpdate },
                     comment: 'Sequence not found from APPEND output'
                 });
                 response.next();
@@ -130,6 +136,8 @@ module.exports = async (connection, destination, content, flags, idate) => {
             }
         }
 
+        // If we have a sequence number but no UID (server doesn't support UIDPLUS),
+        // look up the UID via SEARCH to provide a consistent result to the caller.
         if (map.seq && !map.uid) {
             let list = await connection.search({ seq: map.seq }, { uid: true });
             if (list && list.length) {

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 {