imapflow 2.2.9 → 2.2.11

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [2.2.11](https://github.com/postalsys/imapflow/compare/v2.2.10...v2.2.11) (2026-10-08)
+
+
+### Bug Fixes
+
+* ask a download chunk again when the answer comes back empty instead of failing the download ([0e6e46a](https://github.com/postalsys/imapflow/commit/0e6e46aa81a16a44ccb78df25382ab78a5708ce3))
+* read NAMESPACE prefixes, QUOTAROOT names and ID values that the server sends as literals ([9c77594](https://github.com/postalsys/imapflow/commit/9c7759468f7d64ad6ef857b1861d4a846a8c7c04))
+
+## [2.2.10](https://github.com/postalsys/imapflow/compare/v2.2.9...v2.2.10) (2026-10-07)
+
+
+### Bug Fixes
+
+* log socket errors after a failed STARTTLS upgrade instead of throwing them on Bun ([74fad57](https://github.com/postalsys/imapflow/commit/74fad57386cde6a60211b9b1671228b72aa9f94a))
+* take the requested message in fetchOne() when a FETCH answer also carries unsolicited rows ([74fad57](https://github.com/postalsys/imapflow/commit/74fad57386cde6a60211b9b1671228b72aa9f94a)), closes [#426](https://github.com/postalsys/imapflow/issues/426)
+
 ## [2.2.9](https://github.com/postalsys/imapflow/compare/v2.2.8...v2.2.9) (2026-10-07)
 
 

package/dist/cjs/commands/id.js

@@ -39,17 +39,19 @@ async function id(connection, clientInfo) {
                     let params = untagged.attributes && untagged.attributes[0];
                     let key;
                     (Array.isArray(params) ? params : [].concat(params || [])).forEach((val, i) => {
+                        // keys are strings and values nstrings, either may come as a literal
+                        let value = (0, tools_js_1.getStringValue)(val);
                         if (i % 2 === 0) {
-                            key = val.value;
+                            key = value;
                         }
-                        else if (typeof key === 'string' && typeof val.value === 'string') {
+                        else if (key !== undefined && value !== undefined) {
                             // The server picks the keys of this object, which the caller reads
                             // back as serverInfo: a prototype-chain name is skipped as it is for
                             // every other server-named key, so it can neither be shadowed nor
                             // written through
                             let name = key.toLowerCase().trim();
                             if (!(0, tools_js_1.isUnsafeKey)(name)) {
-                                map[name] = val.value;
+                                map[name] = value;
                             }
                         }
                     });

package/dist/cjs/commands/list.js

@@ -158,7 +158,7 @@ async function list(connection, reference, mailbox, options) {
                             path: (0, tools_js_1.normalizePath)(connection, (0, tools_js_1.decodePath)(connection, rawPath)),
                             pathAsListed: rawPath,
                             flags: new Set((0, tools_js_1.getStringList)(untagged.attributes[0])),
-                            delimiter: (untagged.attributes[1] && untagged.attributes[1].value),
+                            delimiter: (0, tools_js_1.getStringValue)(untagged.attributes[1]),
                             listed: true
                         };
                         normalizeFlags(entry);
@@ -399,7 +399,7 @@ async function list(connection, reference, mailbox, options) {
                             path: (0, tools_js_1.normalizePath)(connection, (0, tools_js_1.decodePath)(connection, rawPath)),
                             pathAsListed: rawPath,
                             flags: new Set((0, tools_js_1.getStringList)(untagged.attributes[0])),
-                            delimiter: (untagged.attributes[1] && untagged.attributes[1].value),
+                            delimiter: (0, tools_js_1.getStringValue)(untagged.attributes[1]),
                             subscribed: true
                         };
                         if (entry.path.toUpperCase() === 'INBOX') {

package/dist/cjs/commands/namespace.js

@@ -94,8 +94,9 @@ async function getListPrefix(connection) {
                         return;
                     }
                     map.flags = new Set((0, tools_js_1.getStringList)(untagged.attributes[0]));
-                    map.delimiter = (untagged.attributes[1] && untagged.attributes[1].value);
-                    map.prefix = ((untagged.attributes[2] && untagged.attributes[2].value) || '');
+                    // the name may be a literal, which arrives as a Buffer
+                    map.delimiter = (0, tools_js_1.getStringValue)(untagged.attributes[1]) || null;
+                    map.prefix = (0, tools_js_1.getStringValue)(untagged.attributes[2]) || '';
                     if (map.delimiter && map.prefix.charAt(0) === map.delimiter) {
                         map.prefix = map.prefix.slice(1);
                     }
@@ -120,24 +121,27 @@ function getNamsepaceInfo(attribute) {
     if (!attribute || !Array.isArray(attribute) || !attribute.length) {
         return false;
     }
-    return attribute
-        .filter(entry => {
-        let pair = entry;
-        // RFC 2342 section 5 allows the delimiter to be NIL when the namespace has
-        // no hierarchy. The token parser emits a literal `null` for NIL.
-        return pair.length >= 2 && pair[0] && typeof pair[0].value === 'string' && (pair[1] === null || (pair[1] && typeof pair[1].value === 'string'));
-    })
-        .map(entry => {
+    let entries = [];
+    for (let entry of attribute) {
+        if (!Array.isArray(entry)) {
+            continue;
+        }
         let pair = entry;
-        let prefix = pair[0].value;
-        let delimiter = pair[1] === null ? null : pair[1].value;
+        let prefix = (0, tools_js_1.getStringValue)(pair[0]);
+        // RFC 2342 section 5 allows the delimiter to be NIL when the namespace has no hierarchy.
+        // The token parser emits a literal `null` for NIL.
+        let delimiter = pair[1] === null ? null : (0, tools_js_1.getStringValue)(pair[1]);
+        if (pair.length < 2 || prefix === undefined || delimiter === undefined) {
+            continue;
+        }
         // Append the delimiter to the prefix if it doesn't already end with one,
         // so callers can construct full paths by simply concatenating prefix + name.
         if (delimiter && prefix && prefix.charAt(prefix.length - 1) !== delimiter) {
             prefix += delimiter;
         }
-        return { prefix, delimiter };
-    });
+        entries.push({ prefix, delimiter });
+    }
+    return entries;
 }
 module.exports = exports.default;
 Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/quota.js

@@ -82,9 +82,8 @@ async function quota(connection, path) {
                 // QUOTAROOT response tells us which quota root applies to this mailbox.
                 // A mailbox may have zero or one quota root.
                 QUOTAROOT: async (untagged) => {
-                    let quotaRoot = untagged.attributes && untagged.attributes[1] && typeof untagged.attributes[1].value === 'string'
-                        ? untagged.attributes[1].value
-                        : false;
+                    // the root name is an astring, which may come as a literal
+                    let quotaRoot = (0, tools_js_1.getStringValue)(untagged.attributes && untagged.attributes[1]);
                     if (quotaRoot) {
                         map.quotaRoot = quotaRoot;
                     }

package/dist/cjs/download.js

@@ -40,8 +40,9 @@ const partialStarts = (requests) => {
     }
     return starts;
 };
-// How many times a request is repeated after answers that belong to another request
-const MAX_FOREIGN_ANSWERS = 3;
+// Attempts per request when the answer belongs to another request or, for a message known to
+// exist, is empty
+const MAX_FETCH_ATTEMPTS = 3;
 const requestedUid = (range, options) => options.uid && /^\d+$/.test(String(range)) ? Number(range) : undefined;
 const isForeignAnswer = (response, expected) => {
     if (expected.uid && response.uid && response.uid !== expected.uid) {
@@ -63,11 +64,19 @@ const isForeignAnswer = (response, expected) => {
  * within the answer to the next one. Taken at face value it would be the data of that next
  * request, and a download would end without an error but with misplaced bytes. An answer for
  * another UID, or with a partial section that starts at another offset than asked, is dropped
- * and the request repeated.
+ * and the request repeated. An empty answer is repeated too while `expected.retryEmpty()` says
+ * the message exists, as the data of a late answer arrives with the repeated request.
  */
 async function fetchExpected(client, range, query, options, expected) {
     for (let attempt = 1;; attempt++) {
         let response = await client.fetchOne(range, query, options);
+        if (response === false && expected.retryEmpty && expected.retryEmpty() && attempt < MAX_FETCH_ATTEMPTS) {
+            // The answer may come late instead (after the tagged OK, with the next answer), then
+            // it shows up in the answer to the repeated request. A message that is really gone
+            // answers empty every time, and the caller reports it.
+            client.log.warn({ msg: 'Server answered a request for an existing message with no data, asking again', attempt, cid: client.id });
+            continue;
+        }
         if (!response || !isForeignAnswer(response, expected)) {
             return response;
         }
@@ -78,7 +87,7 @@ async function fetchExpected(client, range, query, options, expected) {
             attempt,
             cid: client.id
         });
-        if (attempt >= MAX_FOREIGN_ANSWERS) {
+        if (attempt >= MAX_FETCH_ATTEMPTS) {
             let err = new Error('Server kept answering with data of another request');
             err.code = 'DownloadIncomplete';
             err.cid = client.id;
@@ -108,7 +117,8 @@ async function refetchDroppedSections(client, response, range, options, sections
     let uid = response.uid;
     let retry = await fetchExpected(client, uid || range, { uid: true, bodyParts: sections }, uid ? { ...options, uid: true } : options, {
         uid,
-        origins: partialStarts(sections)
+        origins: partialStarts(sections),
+        retryEmpty: () => true
     });
     if (!retry) {
         return;
@@ -170,6 +180,13 @@ async function downloadMessage(client, range, part, options) {
             part = 'TEXT';
         }
     }
+    // The decoder pipeline, built once the head chunk told what the part is (see below)
+    let stream;
+    let output;
+    let fetchAborted = false;
+    // A consumer that gave up: its 'close' may still be a tick away from setting fetchAborted,
+    // so the stream's own flag is checked as well
+    let downloadAborted = () => fetchAborted || output.destroyed;
     let getNextPart = async (query) => {
         query = query || {};
         let mimeKey;
@@ -205,7 +222,9 @@ async function downloadMessage(client, range, part, options) {
         }
         let expected = {
             uid: uid || requestedUid(range, downloadOptions),
-            origins: new Map([[part || '', processed]])
+            origins: new Map([[part || '', processed]]),
+            // every chunk after the first is of a message that was there a moment ago
+            retryEmpty: processed > 0 ? () => !downloadAborted() : undefined
         };
         let response = await fetchExpected(client, range, query, downloadOptions, expected);
         if (!response) {
@@ -316,9 +335,6 @@ async function downloadMessage(client, range, part, options) {
             meta.filename = filename;
         }
     }
-    let stream;
-    let output;
-    let fetchAborted = false;
     // Build a decoder pipeline that progressively transforms the raw FETCH data:
     //   1. Transfer-encoding decoder (base64 or quoted-printable -> binary)
     //   2. Format decoder (format=flowed -> plain text, if applicable)
@@ -480,9 +496,8 @@ async function downloadMessage(client, range, part, options) {
                 throw err;
             }
             let { response, chunk } = await getNextPart();
-            // A consumer that gave up while the chunk was in flight: its 'close' may still be a
-            // tick away from setting fetchAborted, so the stream's own flag is checked as well
-            if (fetchAborted || output.destroyed) {
+            // A consumer that gave up while the chunk was in flight
+            if (downloadAborted()) {
                 break;
             }
             if (response === false) {

package/dist/cjs/imap-flow.js

@@ -1512,6 +1512,13 @@ class ImapFlow extends node_events_1.EventEmitter {
             // socket event cannot re-enter an already settled upgrade or leave state behind.
             const settle = (err, result) => {
                 if (settled) {
+                    // A failed handshake can produce more than one error (Bun emits ECONNRESET on
+                    // the TLS socket after the one that settled the upgrade). settle() stays the
+                    // error listener of both sockets until they are torn down, so later errors
+                    // end up here instead of being thrown as unhandled 'error' events.
+                    if (err) {
+                        this.log.debug({ msg: 'Socket error after the TLS upgrade was settled', err, cid: this.id });
+                    }
                     return;
                 }
                 settled = true;
@@ -1519,9 +1526,12 @@ class ImapFlow extends node_events_1.EventEmitter {
                 this.upgradeTimeout = null;
                 this.upgrading = false;
                 this._upgradeReject = null;
-                socketPlain.removeListener('error', settle);
-                if (this.socket && this.socket !== socketPlain) {
-                    this.socket.removeListener('error', settle);
+                if (!err) {
+                    // the generic socket handlers took over in the success callback
+                    socketPlain.removeListener('error', settle);
+                    if (this.socket && this.socket !== socketPlain) {
+                        this.socket.removeListener('error', settle);
+                    }
                 }
                 if (err) {
                     (0, tools_js_1.clearTimer)(this.connectTimeout);
@@ -1539,7 +1549,7 @@ class ImapFlow extends node_events_1.EventEmitter {
             // one function, one settlement, and removeListener() in settle() needs no separate
             // handler references. A TLS handshake failure (bad certificate, protocol mismatch)
             // is emitted on the new TLS socket rather than on the plain one, so both are covered.
-            socketPlain.once('error', settle);
+            socketPlain.on('error', settle);
             /* c8 ignore start */ // UPGRADE_TIMEOUT is 10s; firing it deterministically would make the test suite hang
             this.upgradeTimeout = setTimeout(() => {
                 let err = new Error('Failed to upgrade connection in required time');
@@ -1617,7 +1627,7 @@ class ImapFlow extends node_events_1.EventEmitter {
             // error listener during the handshake window; the generic handlers are installed
             // by setSocketHandlers() inside the success callback above, so a handshake error
             // has a single error path.
-            tlsSocket.once('error', settle);
+            tlsSocket.on('error', settle);
             this.writeSocket = tlsSocket;
         });
         if (upgraded) {
@@ -3152,7 +3162,21 @@ class ImapFlow extends node_events_1.EventEmitter {
         if (!response || !response.list || !response.list.length) {
             return false;
         }
-        return response.list[0];
+        // Every FETCH row that arrived during the command is in the list, also unsolicited ones
+        // for other messages or with only a flag change, and a server may split the answer for
+        // one message over several rows. Taking the first row returned a flag update instead
+        // of the requested data, which ended a download after its first chunk (issue #426).
+        let rows = response.list;
+        let requested = (0, tools_js_1.parseUintValue)(String(seq), tools_js_1.MAX_UINT32_DIGITS);
+        // a range: the first message of the answer, as before
+        let target = requested === false ? rows[0] : rows.find(row => (options && options.uid ? row.uid : row.seq) === requested);
+        if (!target) {
+            return false;
+        }
+        // rows of the same message, without the ones a malformed answer gives no usable
+        // sequence number or another UID
+        let { seq: targetSeq, uid: targetUid } = target;
+        return targetSeq ? (0, tools_js_1.mergeFetchRows)(rows.filter(row => row.seq === targetSeq && (!row.uid || !targetUid || row.uid === targetUid))) : target;
     }
     /**
      * Download either full rfc822 formatted message or a specific bodystructure part as a Stream.

package/dist/cjs/package-info.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.2.9";
+export declare const version = "2.2.11";
 export declare const homepage = "https://imapflow.com/";

package/dist/cjs/package-info.js

@@ -3,5 +3,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.homepage = exports.version = exports.name = void 0;
 exports.name = "imapflow";
-exports.version = "2.2.9";
+exports.version = "2.2.11";
 exports.homepage = "https://imapflow.com/";

package/dist/cjs/tools.d.ts

@@ -287,6 +287,16 @@ export declare function getColorFlags(color: string | null | undefined): {
     add: string[];
     remove: string[];
 } | null;
+/**
+ * Merges the FETCH rows a server sent for one message into one message object. A server may
+ * split the data items of a message over several FETCH responses, and may put an unsolicited
+ * one (a flag change made by another session) in between (RFC 9051 sections 7.5.2 and 5.2).
+ * Later rows win for single values, bodyParts, binaryParts and partialOrigins are combined.
+ *
+ * @param rows - Formatted rows of the same message, in the order they arrived
+ * @returns One message object holding the data of every row
+ */
+export declare function mergeFetchRows(rows: FetchMessageObject[]): FetchMessageObject;
 /**
  * Formats a raw untagged FETCH response into a structured message object.
  *
@@ -423,6 +433,14 @@ export declare function isUnsafeKey(key: unknown): boolean;
  * @returns The string values, in order, with unusable entries dropped.
  */
 export declare function getStringList(list: unknown): string[];
+/**
+ * Reads the text of a string value from a response. A server may send any string as a literal,
+ * which arrives as a Buffer and is decoded as UTF-8.
+ *
+ * @param attribute - Parsed attribute from a response
+ * @returns The string, or undefined when the attribute holds no string (NIL, a list)
+ */
+export declare function getStringValue(attribute: unknown): string | undefined;
 /**
  * Parses an untrusted decimal value from a server response into a BigInt.
  *

package/dist/cjs/tools.js

@@ -32,6 +32,7 @@ exports.getSelectedMailbox = getSelectedMailbox;
 exports.getFolderTree = getFolderTree;
 exports.getFlagColor = getFlagColor;
 exports.getColorFlags = getColorFlags;
+exports.mergeFetchRows = mergeFetchRows;
 exports.formatMessageResponse = formatMessageResponse;
 exports.processName = processName;
 exports.decodeText = decodeText;
@@ -48,6 +49,7 @@ exports.isValidSequenceValue = isValidSequenceValue;
 exports.isDecimalString = isDecimalString;
 exports.isUnsafeKey = isUnsafeKey;
 exports.getStringList = getStringList;
+exports.getStringValue = getStringValue;
 exports.parseBigIntValue = parseBigIntValue;
 exports.parseUintValue = parseUintValue;
 exports.expandRange = expandRange;
@@ -713,6 +715,34 @@ function getColorFlags(color) {
     }
     return result;
 }
+/**
+ * Merges the FETCH rows a server sent for one message into one message object. A server may
+ * split the data items of a message over several FETCH responses, and may put an unsolicited
+ * one (a flag change made by another session) in between (RFC 9051 sections 7.5.2 and 5.2).
+ * Later rows win for single values, bodyParts, binaryParts and partialOrigins are combined.
+ *
+ * @param rows - Formatted rows of the same message, in the order they arrived
+ * @returns One message object holding the data of every row
+ */
+function mergeFetchRows(rows) {
+    if (rows.length === 1) {
+        return rows[0];
+    }
+    let merged = {};
+    let partialOrigins;
+    for (let row of rows) {
+        let { bodyParts, binaryParts, ...rest } = row;
+        Object.assign(merged, rest);
+        // combined into collections of their own, so the rows stay untouched
+        bodyParts?.forEach((value, key) => (merged.bodyParts ??= new Map()).set(key, value));
+        binaryParts?.forEach(key => (merged.binaryParts ??= new Set()).add(key));
+        row.partialOrigins?.forEach((value, key) => (partialOrigins ??= new Map()).set(key, value));
+    }
+    if (partialOrigins) {
+        Object.defineProperty(merged, 'partialOrigins', { value: partialOrigins, writable: true, configurable: true });
+    }
+    return merged;
+}
 /**
  * Formats a raw untagged FETCH response into a structured message object.
  *
@@ -1473,16 +1503,27 @@ function getStringList(list) {
     }
     let strings = [];
     for (let entry of list) {
-        let value = entry && entry.value;
-        if (Buffer.isBuffer(value)) {
-            value = value.toString();
-        }
-        if (value && typeof value === 'string') {
+        let value = getStringValue(entry);
+        if (value) {
             strings.push(value);
         }
     }
     return strings;
 }
+/**
+ * Reads the text of a string value from a response. A server may send any string as a literal,
+ * which arrives as a Buffer and is decoded as UTF-8.
+ *
+ * @param attribute - Parsed attribute from a response
+ * @returns The string, or undefined when the attribute holds no string (NIL, a list)
+ */
+function getStringValue(attribute) {
+    let value = attribute && attribute.value;
+    if (Buffer.isBuffer(value)) {
+        return value.toString();
+    }
+    return typeof value === 'string' ? value : undefined;
+}
 /**
  * Parses an untrusted decimal value from a server response into a BigInt.
  *

package/dist/esm/commands/id.js

@@ -1,4 +1,4 @@
-import { formatDateTime, isUnsafeKey } from '../tools.js';
+import { formatDateTime, isUnsafeKey, getStringValue } from '../tools.js';
 /**
  * Sends ID info to the server and updates server info data based on the response.
  *
@@ -36,17 +36,19 @@ export default async function id(connection, clientInfo) {
                     let params = untagged.attributes && untagged.attributes[0];
                     let key;
                     (Array.isArray(params) ? params : [].concat(params || [])).forEach((val, i) => {
+                        // keys are strings and values nstrings, either may come as a literal
+                        let value = getStringValue(val);
                         if (i % 2 === 0) {
-                            key = val.value;
+                            key = value;
                         }
-                        else if (typeof key === 'string' && typeof val.value === 'string') {
+                        else if (key !== undefined && value !== undefined) {
                             // The server picks the keys of this object, which the caller reads
                             // back as serverInfo: a prototype-chain name is skipped as it is for
                             // every other server-named key, so it can neither be shadowed nor
                             // written through
                             let name = key.toLowerCase().trim();
                             if (!isUnsafeKey(name)) {
-                                map[name] = val.value;
+                                map[name] = value;
                             }
                         }
                     });

package/dist/esm/commands/list.js

@@ -1,4 +1,4 @@
-import { decodePath, encodePath, normalizePath, enhanceCommandError, hasCapability, isRev2Active, buildStatusQueryAttributes, getStringList } from '../tools.js';
+import { decodePath, encodePath, normalizePath, enhanceCommandError, hasCapability, isRev2Active, buildStatusQueryAttributes, getStringList, getStringValue } from '../tools.js';
 import { parseStatusList } from './status-fields.js';
 import { specialUse } from '../special-use.js';
 /**
@@ -155,7 +155,7 @@ export default async function list(connection, reference, mailbox, options) {
                             path: normalizePath(connection, decodePath(connection, rawPath)),
                             pathAsListed: rawPath,
                             flags: new Set(getStringList(untagged.attributes[0])),
-                            delimiter: (untagged.attributes[1] && untagged.attributes[1].value),
+                            delimiter: getStringValue(untagged.attributes[1]),
                             listed: true
                         };
                         normalizeFlags(entry);
@@ -396,7 +396,7 @@ export default async function list(connection, reference, mailbox, options) {
                             path: normalizePath(connection, decodePath(connection, rawPath)),
                             pathAsListed: rawPath,
                             flags: new Set(getStringList(untagged.attributes[0])),
-                            delimiter: (untagged.attributes[1] && untagged.attributes[1].value),
+                            delimiter: getStringValue(untagged.attributes[1]),
                             subscribed: true
                         };
                         if (entry.path.toUpperCase() === 'INBOX') {

package/dist/esm/commands/namespace.js

@@ -1,4 +1,4 @@
-import { hasCapability, getStringList, isAuthenticatedState } from '../tools.js';
+import { hasCapability, getStringList, getStringValue, isAuthenticatedState } from '../tools.js';
 /**
  * Requests NAMESPACE info from the server.
  *
@@ -91,8 +91,9 @@ async function getListPrefix(connection) {
                         return;
                     }
                     map.flags = new Set(getStringList(untagged.attributes[0]));
-                    map.delimiter = (untagged.attributes[1] && untagged.attributes[1].value);
-                    map.prefix = ((untagged.attributes[2] && untagged.attributes[2].value) || '');
+                    // the name may be a literal, which arrives as a Buffer
+                    map.delimiter = getStringValue(untagged.attributes[1]) || null;
+                    map.prefix = getStringValue(untagged.attributes[2]) || '';
                     if (map.delimiter && map.prefix.charAt(0) === map.delimiter) {
                         map.prefix = map.prefix.slice(1);
                     }
@@ -117,22 +118,25 @@ function getNamsepaceInfo(attribute) {
     if (!attribute || !Array.isArray(attribute) || !attribute.length) {
         return false;
     }
-    return attribute
-        .filter(entry => {
-        let pair = entry;
-        // RFC 2342 section 5 allows the delimiter to be NIL when the namespace has
-        // no hierarchy. The token parser emits a literal `null` for NIL.
-        return pair.length >= 2 && pair[0] && typeof pair[0].value === 'string' && (pair[1] === null || (pair[1] && typeof pair[1].value === 'string'));
-    })
-        .map(entry => {
+    let entries = [];
+    for (let entry of attribute) {
+        if (!Array.isArray(entry)) {
+            continue;
+        }
         let pair = entry;
-        let prefix = pair[0].value;
-        let delimiter = pair[1] === null ? null : pair[1].value;
+        let prefix = getStringValue(pair[0]);
+        // RFC 2342 section 5 allows the delimiter to be NIL when the namespace has no hierarchy.
+        // The token parser emits a literal `null` for NIL.
+        let delimiter = pair[1] === null ? null : getStringValue(pair[1]);
+        if (pair.length < 2 || prefix === undefined || delimiter === undefined) {
+            continue;
+        }
         // Append the delimiter to the prefix if it doesn't already end with one,
         // so callers can construct full paths by simply concatenating prefix + name.
         if (delimiter && prefix && prefix.charAt(prefix.length - 1) !== delimiter) {
             prefix += delimiter;
         }
-        return { prefix, delimiter };
-    });
+        entries.push({ prefix, delimiter });
+    }
+    return entries;
 }

package/dist/esm/commands/quota.js

@@ -1,4 +1,4 @@
-import { encodePath, normalizePath, parseUintValue, isUnsafeKey, isAuthenticatedState, reportCommandError } from '../tools.js';
+import { encodePath, normalizePath, parseUintValue, isUnsafeKey, isAuthenticatedState, reportCommandError, getStringValue } from '../tools.js';
 /**
  * Requests quota information for a mailbox.
  *
@@ -79,9 +79,8 @@ export default async function quota(connection, path) {
                 // QUOTAROOT response tells us which quota root applies to this mailbox.
                 // A mailbox may have zero or one quota root.
                 QUOTAROOT: async (untagged) => {
-                    let quotaRoot = untagged.attributes && untagged.attributes[1] && typeof untagged.attributes[1].value === 'string'
-                        ? untagged.attributes[1].value
-                        : false;
+                    // the root name is an astring, which may come as a literal
+                    let quotaRoot = getStringValue(untagged.attributes && untagged.attributes[1]);
                     if (quotaRoot) {
                         map.quotaRoot = quotaRoot;
                     }

package/dist/esm/download.js

@@ -33,8 +33,9 @@ const partialStarts = (requests) => {
     }
     return starts;
 };
-// How many times a request is repeated after answers that belong to another request
-const MAX_FOREIGN_ANSWERS = 3;
+// Attempts per request when the answer belongs to another request or, for a message known to
+// exist, is empty
+const MAX_FETCH_ATTEMPTS = 3;
 const requestedUid = (range, options) => options.uid && /^\d+$/.test(String(range)) ? Number(range) : undefined;
 const isForeignAnswer = (response, expected) => {
     if (expected.uid && response.uid && response.uid !== expected.uid) {
@@ -56,11 +57,19 @@ const isForeignAnswer = (response, expected) => {
  * within the answer to the next one. Taken at face value it would be the data of that next
  * request, and a download would end without an error but with misplaced bytes. An answer for
  * another UID, or with a partial section that starts at another offset than asked, is dropped
- * and the request repeated.
+ * and the request repeated. An empty answer is repeated too while `expected.retryEmpty()` says
+ * the message exists, as the data of a late answer arrives with the repeated request.
  */
 async function fetchExpected(client, range, query, options, expected) {
     for (let attempt = 1;; attempt++) {
         let response = await client.fetchOne(range, query, options);
+        if (response === false && expected.retryEmpty && expected.retryEmpty() && attempt < MAX_FETCH_ATTEMPTS) {
+            // The answer may come late instead (after the tagged OK, with the next answer), then
+            // it shows up in the answer to the repeated request. A message that is really gone
+            // answers empty every time, and the caller reports it.
+            client.log.warn({ msg: 'Server answered a request for an existing message with no data, asking again', attempt, cid: client.id });
+            continue;
+        }
         if (!response || !isForeignAnswer(response, expected)) {
             return response;
         }
@@ -71,7 +80,7 @@ async function fetchExpected(client, range, query, options, expected) {
             attempt,
             cid: client.id
         });
-        if (attempt >= MAX_FOREIGN_ANSWERS) {
+        if (attempt >= MAX_FETCH_ATTEMPTS) {
             let err = new Error('Server kept answering with data of another request');
             err.code = 'DownloadIncomplete';
             err.cid = client.id;
@@ -101,7 +110,8 @@ async function refetchDroppedSections(client, response, range, options, sections
     let uid = response.uid;
     let retry = await fetchExpected(client, uid || range, { uid: true, bodyParts: sections }, uid ? { ...options, uid: true } : options, {
         uid,
-        origins: partialStarts(sections)
+        origins: partialStarts(sections),
+        retryEmpty: () => true
     });
     if (!retry) {
         return;
@@ -163,6 +173,13 @@ export async function downloadMessage(client, range, part, options) {
             part = 'TEXT';
         }
     }
+    // The decoder pipeline, built once the head chunk told what the part is (see below)
+    let stream;
+    let output;
+    let fetchAborted = false;
+    // A consumer that gave up: its 'close' may still be a tick away from setting fetchAborted,
+    // so the stream's own flag is checked as well
+    let downloadAborted = () => fetchAborted || output.destroyed;
     let getNextPart = async (query) => {
         query = query || {};
         let mimeKey;
@@ -198,7 +215,9 @@ export async function downloadMessage(client, range, part, options) {
         }
         let expected = {
             uid: uid || requestedUid(range, downloadOptions),
-            origins: new Map([[part || '', processed]])
+            origins: new Map([[part || '', processed]]),
+            // every chunk after the first is of a message that was there a moment ago
+            retryEmpty: processed > 0 ? () => !downloadAborted() : undefined
         };
         let response = await fetchExpected(client, range, query, downloadOptions, expected);
         if (!response) {
@@ -309,9 +328,6 @@ export async function downloadMessage(client, range, part, options) {
             meta.filename = filename;
         }
     }
-    let stream;
-    let output;
-    let fetchAborted = false;
     // Build a decoder pipeline that progressively transforms the raw FETCH data:
     //   1. Transfer-encoding decoder (base64 or quoted-printable -> binary)
     //   2. Format decoder (format=flowed -> plain text, if applicable)
@@ -473,9 +489,8 @@ export async function downloadMessage(client, range, part, options) {
                 throw err;
             }
             let { response, chunk } = await getNextPart();
-            // A consumer that gave up while the chunk was in flight: its 'close' may still be a
-            // tick away from setting fetchAborted, so the stream's own flag is checked as well
-            if (fetchAborted || output.destroyed) {
+            // A consumer that gave up while the chunk was in flight
+            if (downloadAborted()) {
                 break;
             }
             if (response === false) {

package/dist/esm/imap-flow.js

@@ -16,7 +16,7 @@ import { ConnectionDeadline } from './connection-deadline.js';
 import { downloadMessage, downloadMessageParts } from './download.js';
 import { AuthenticationFailure } from './errors.js';
 import imapCommands from './imap-commands.js';
-import { comparePaths, updateCapabilities, getFolderTree, formatMessageResponse, packMessageRange, normalizePath, expandRange, getColorFlags, hasCapability, isRev2Active, logConnectionError, unrefTimer, clearTimer, parseUintValue, getStringList, getTextValues, emitSafe, buildConnectionError, guardedPromise, guardedReject, MAX_UINT32_DIGITS } from './tools.js';
+import { comparePaths, updateCapabilities, getFolderTree, formatMessageResponse, mergeFetchRows, packMessageRange, normalizePath, expandRange, getColorFlags, hasCapability, isRev2Active, logConnectionError, unrefTimer, clearTimer, parseUintValue, getStringList, getTextValues, emitSafe, buildConnectionError, guardedPromise, guardedReject, MAX_UINT32_DIGITS } from './tools.js';
 export { AuthenticationFailure, ImapFlowErrorCode } from './errors.js';
 const GREETING_TIMEOUT = 16 * 1000;
 const UPGRADE_TIMEOUT = 10 * 1000;
@@ -1471,6 +1471,13 @@ export class ImapFlow extends EventEmitter {
             // socket event cannot re-enter an already settled upgrade or leave state behind.
             const settle = (err, result) => {
                 if (settled) {
+                    // A failed handshake can produce more than one error (Bun emits ECONNRESET on
+                    // the TLS socket after the one that settled the upgrade). settle() stays the
+                    // error listener of both sockets until they are torn down, so later errors
+                    // end up here instead of being thrown as unhandled 'error' events.
+                    if (err) {
+                        this.log.debug({ msg: 'Socket error after the TLS upgrade was settled', err, cid: this.id });
+                    }
                     return;
                 }
                 settled = true;
@@ -1478,9 +1485,12 @@ export class ImapFlow extends EventEmitter {
                 this.upgradeTimeout = null;
                 this.upgrading = false;
                 this._upgradeReject = null;
-                socketPlain.removeListener('error', settle);
-                if (this.socket && this.socket !== socketPlain) {
-                    this.socket.removeListener('error', settle);
+                if (!err) {
+                    // the generic socket handlers took over in the success callback
+                    socketPlain.removeListener('error', settle);
+                    if (this.socket && this.socket !== socketPlain) {
+                        this.socket.removeListener('error', settle);
+                    }
                 }
                 if (err) {
                     clearTimer(this.connectTimeout);
@@ -1498,7 +1508,7 @@ export class ImapFlow extends EventEmitter {
             // one function, one settlement, and removeListener() in settle() needs no separate
             // handler references. A TLS handshake failure (bad certificate, protocol mismatch)
             // is emitted on the new TLS socket rather than on the plain one, so both are covered.
-            socketPlain.once('error', settle);
+            socketPlain.on('error', settle);
             /* c8 ignore start */ // UPGRADE_TIMEOUT is 10s; firing it deterministically would make the test suite hang
             this.upgradeTimeout = setTimeout(() => {
                 let err = new Error('Failed to upgrade connection in required time');
@@ -1576,7 +1586,7 @@ export class ImapFlow extends EventEmitter {
             // error listener during the handshake window; the generic handlers are installed
             // by setSocketHandlers() inside the success callback above, so a handshake error
             // has a single error path.
-            tlsSocket.once('error', settle);
+            tlsSocket.on('error', settle);
             this.writeSocket = tlsSocket;
         });
         if (upgraded) {
@@ -3111,7 +3121,21 @@ export class ImapFlow extends EventEmitter {
         if (!response || !response.list || !response.list.length) {
             return false;
         }
-        return response.list[0];
+        // Every FETCH row that arrived during the command is in the list, also unsolicited ones
+        // for other messages or with only a flag change, and a server may split the answer for
+        // one message over several rows. Taking the first row returned a flag update instead
+        // of the requested data, which ended a download after its first chunk (issue #426).
+        let rows = response.list;
+        let requested = parseUintValue(String(seq), MAX_UINT32_DIGITS);
+        // a range: the first message of the answer, as before
+        let target = requested === false ? rows[0] : rows.find(row => (options && options.uid ? row.uid : row.seq) === requested);
+        if (!target) {
+            return false;
+        }
+        // rows of the same message, without the ones a malformed answer gives no usable
+        // sequence number or another UID
+        let { seq: targetSeq, uid: targetUid } = target;
+        return targetSeq ? mergeFetchRows(rows.filter(row => row.seq === targetSeq && (!row.uid || !targetUid || row.uid === targetUid))) : target;
     }
     /**
      * Download either full rfc822 formatted message or a specific bodystructure part as a Stream.

package/dist/esm/package-info.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.2.9";
+export declare const version = "2.2.11";
 export declare const homepage = "https://imapflow.com/";

package/dist/esm/package-info.js

@@ -1,4 +1,4 @@
 // Generated by scripts/build.js from package.json. Do not edit by hand.
 export const name = "imapflow";
-export const version = "2.2.9";
+export const version = "2.2.11";
 export const homepage = "https://imapflow.com/";

package/dist/esm/tools.d.ts

@@ -287,6 +287,16 @@ export declare function getColorFlags(color: string | null | undefined): {
     add: string[];
     remove: string[];
 } | null;
+/**
+ * Merges the FETCH rows a server sent for one message into one message object. A server may
+ * split the data items of a message over several FETCH responses, and may put an unsolicited
+ * one (a flag change made by another session) in between (RFC 9051 sections 7.5.2 and 5.2).
+ * Later rows win for single values, bodyParts, binaryParts and partialOrigins are combined.
+ *
+ * @param rows - Formatted rows of the same message, in the order they arrived
+ * @returns One message object holding the data of every row
+ */
+export declare function mergeFetchRows(rows: FetchMessageObject[]): FetchMessageObject;
 /**
  * Formats a raw untagged FETCH response into a structured message object.
  *
@@ -423,6 +433,14 @@ export declare function isUnsafeKey(key: unknown): boolean;
  * @returns The string values, in order, with unusable entries dropped.
  */
 export declare function getStringList(list: unknown): string[];
+/**
+ * Reads the text of a string value from a response. A server may send any string as a literal,
+ * which arrives as a Buffer and is decoded as UTF-8.
+ *
+ * @param attribute - Parsed attribute from a response
+ * @returns The string, or undefined when the attribute holds no string (NIL, a list)
+ */
+export declare function getStringValue(attribute: unknown): string | undefined;
 /**
  * Parses an untrusted decimal value from a server response into a BigInt.
  *

package/dist/esm/tools.js

@@ -657,6 +657,34 @@ export function getColorFlags(color) {
     }
     return result;
 }
+/**
+ * Merges the FETCH rows a server sent for one message into one message object. A server may
+ * split the data items of a message over several FETCH responses, and may put an unsolicited
+ * one (a flag change made by another session) in between (RFC 9051 sections 7.5.2 and 5.2).
+ * Later rows win for single values, bodyParts, binaryParts and partialOrigins are combined.
+ *
+ * @param rows - Formatted rows of the same message, in the order they arrived
+ * @returns One message object holding the data of every row
+ */
+export function mergeFetchRows(rows) {
+    if (rows.length === 1) {
+        return rows[0];
+    }
+    let merged = {};
+    let partialOrigins;
+    for (let row of rows) {
+        let { bodyParts, binaryParts, ...rest } = row;
+        Object.assign(merged, rest);
+        // combined into collections of their own, so the rows stay untouched
+        bodyParts?.forEach((value, key) => (merged.bodyParts ??= new Map()).set(key, value));
+        binaryParts?.forEach(key => (merged.binaryParts ??= new Set()).add(key));
+        row.partialOrigins?.forEach((value, key) => (partialOrigins ??= new Map()).set(key, value));
+    }
+    if (partialOrigins) {
+        Object.defineProperty(merged, 'partialOrigins', { value: partialOrigins, writable: true, configurable: true });
+    }
+    return merged;
+}
 /**
  * Formats a raw untagged FETCH response into a structured message object.
  *
@@ -1417,16 +1445,27 @@ export function getStringList(list) {
     }
     let strings = [];
     for (let entry of list) {
-        let value = entry && entry.value;
-        if (Buffer.isBuffer(value)) {
-            value = value.toString();
-        }
-        if (value && typeof value === 'string') {
+        let value = getStringValue(entry);
+        if (value) {
             strings.push(value);
         }
     }
     return strings;
 }
+/**
+ * Reads the text of a string value from a response. A server may send any string as a literal,
+ * which arrives as a Buffer and is decoded as UTF-8.
+ *
+ * @param attribute - Parsed attribute from a response
+ * @returns The string, or undefined when the attribute holds no string (NIL, a list)
+ */
+export function getStringValue(attribute) {
+    let value = attribute && attribute.value;
+    if (Buffer.isBuffer(value)) {
+        return value.toString();
+    }
+    return typeof value === 'string' ? value : undefined;
+}
 /**
  * Parses an untrusted decimal value from a server response into a BigInt.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "2.2.9",
+    "version": "2.2.11",
     "description": "IMAP Client for Node",
     "type": "module",
     "main": "./dist/cjs/imap-flow.js",
@@ -75,7 +75,7 @@
         "eslint": "10.12.0",
         "eslint-config-prettier": "10.1.8",
         "globals": "17.13.0",
-        "imapkit": "4.1.0",
+        "imapkit": "4.3.1",
         "prettier": "3.9.9",
         "tsx": "4.23.15",
         "types-node-legacy": "npm:@types/node@20.0.0",