@withbuddi/buddi 0.1.0-pre.51 → 0.1.0-pre.53

package/node_modules/imapflow/dist/esm/imap-flow.js

@@ -14,11 +14,13 @@ import { parser, compiler } from './handler/imap-handler.js';
 import { proxyConnection, detachEarlyErrorHandler } from './proxy-connection.js';
 import { ConnectionDeadline } from './connection-deadline.js';
 import { downloadMessage, downloadMessageParts } from './download.js';
-import { AuthenticationFailure } from './errors.js';
+import { AuthenticationFailure, createImapError } 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;
+// Status responses that can carry an ALERT response code
+const ALERT_RESPONSES = new Set(['OK', 'NO', 'BAD', 'BYE', 'PREAUTH']);
 const UPGRADE_TIMEOUT = 10 * 1000;
 const SOCKET_TIMEOUT = 5 * 60 * 1000;
 // Ceiling for any throttle back-off wait. Both the connection-level back-off and the per-command
@@ -42,6 +44,10 @@ const RAW_SENSITIVE_COMMANDS = new Set(['LOGIN', 'AUTHENTICATE']);
 // Stand-in payload for a withheld raw client frame. Fixed width, so the entry says nothing
 // about the length of what it replaced.
 const RAW_HIDDEN_PLACEHOLDER = Buffer.from('(* value hidden *)\r\n').toString('base64');
+// From this size up, a Buffer written as the last part of a command gets its CRLF as a socket
+// write of its own instead of being copied to append it (see write())
+const SEPARATE_LINE_BREAK_SIZE = 64 * 1024;
+const CRLF = Buffer.from('\r\n');
 // Servers, matched by the name in their ID response, that advertise IMAP4rev2 next to
 // IMAP4rev1 and accept ENABLE IMAP4rev2, but misbehave once it is enabled. ENABLE cannot
 // be undone (RFC 5161), so these are kept in IMAP4rev1 mode from the start. Strato's
@@ -342,43 +348,47 @@ export class ImapFlow extends EventEmitter {
         // commandParts holds the remaining parts (literal data, continuation); the CRLF
         // delimiter is only added when no more parts remain (the command is complete).
         let addLineBreak = !this.commandParts.length;
-        let data;
+        // What goes to the socket, one write per entry. A large Buffer (the data of a literal)
+        // gets its CRLF as a write of its own, as concatenating would copy all of it.
+        let frames;
         if (typeof chunk === 'string') {
             if (addLineBreak) {
                 chunk += '\r\n';
             }
-            data = Buffer.from(chunk, 'binary');
+            frames = [Buffer.from(chunk, 'binary')];
         }
         else if (Buffer.isBuffer(chunk)) {
-            if (addLineBreak) {
-                data = Buffer.concat([chunk, Buffer.from('\r\n')]);
+            if (!addLineBreak) {
+                frames = [chunk];
             }
             else {
-                data = chunk;
+                frames = chunk.length >= SEPARATE_LINE_BREAK_SIZE ? [chunk, CRLF] : [Buffer.concat([chunk, CRLF])];
             }
         }
         else {
             return false;
         }
-        if (this.logRaw) {
-            // Client frames of an authentication exchange carry credentials: the LOGIN
-            // arguments, and for AUTHENTICATE also the continuation writes (SASL PLAIN
-            // response, AUTH=LOGIN password, OAuth token payload) that bypass send(). The
-            // parsed command log masks these, so the raw log must withhold them too, but
-            // `data` still carries the placeholder rather than being dropped - the field is
-            // part of the documented log format and consumers decode it unconditionally.
-            this.log.trace({
-                src: 'c',
-                msg: 'write to socket',
-                data: this.rawSensitiveCommand ? RAW_HIDDEN_PLACEHOLDER : data.toString('base64'),
-                ...(this.rawSensitiveCommand ? { hidden: true } : {}),
-                compress: !!this._deflate,
-                secure: !!this.secureConnection,
-                cid: this.id
-            });
+        for (let data of frames) {
+            if (this.logRaw) {
+                // Client frames of an authentication exchange carry credentials: the LOGIN
+                // arguments, and for AUTHENTICATE also the continuation writes (SASL PLAIN
+                // response, AUTH=LOGIN password, OAuth token payload) that bypass send(). The
+                // parsed command log masks these, so the raw log must withhold them too, but
+                // `data` still carries the placeholder rather than being dropped - the field is
+                // part of the documented log format and consumers decode it unconditionally.
+                this.log.trace({
+                    src: 'c',
+                    msg: 'write to socket',
+                    data: this.rawSensitiveCommand ? RAW_HIDDEN_PLACEHOLDER : data.toString('base64'),
+                    ...(this.rawSensitiveCommand ? { hidden: true } : {}),
+                    compress: !!this._deflate,
+                    secure: !!this.secureConnection,
+                    cid: this.id
+                });
+            }
+            this.writeBytesCounter += data.length;
+            this.writeSocket.write(data);
         }
-        this.writeBytesCounter += data.length;
-        this.writeSocket.write(data);
     }
     /**
      * Returns byte counters for the current connection.
@@ -404,6 +414,9 @@ export class ImapFlow extends EventEmitter {
     // and once as a string (for logging, with sensitive data masked).
     // When LITERAL- or LITERAL+ extensions are available, the compiler can use
     // non-synchronizing literals to avoid waiting for server "+" continuation.
+    // Async although nothing in it awaits: a failure inside it rejects one microtask later, so a
+    // close() in the same tick settles the command with NoConnection first (see
+    // test/unhandled-rejection-test.ts)
     /** @internal */
     async send(data) {
         if (this.state === this.states.LOGOUT) {
@@ -413,11 +426,11 @@ export class ImapFlow extends EventEmitter {
             // the socket watchdog.
             throw this.createNoConnectionError(false, { rejectedFrom: 'sendAfterLogout', command: data.command });
         }
-        // Classify before the first await. Every frame of this command - the command line and
-        // any continuation write that follows it - belongs to it until the next send(), because
+        // Classify once per command. Every frame of this command - the command line and any
+        // continuation write that follows it - belongs to it until the next send(), because
         // trySend() keeps one command in flight at a time. Reading currentRequest inside write()
-        // instead would be racy: rejectCurrentRequest() can clear it while the two compiler
-        // awaits below are pending, and the credential frame would then be logged in the clear.
+        // instead would be racy: rejectCurrentRequest() can clear it before a continuation frame
+        // is written, and the credential frame would then be logged in the clear.
         // Uppercased because the wire protocol is case-insensitive and exec() passes the
         // caller's spelling through unchanged. The command list covers the mechanisms whose
         // secret arrives in a continuation frame, which carries no attributes of its own; the
@@ -428,7 +441,7 @@ export class ImapFlow extends EventEmitter {
         // Compile with asArray=true: splits output into parts for literal handling.
         // First part is the command text up to the first literal, remaining parts
         // are stored in this.commandParts and sent after server "+" continuations.
-        let compiled = await compiler(data, {
+        let compiled = compiler(data, {
             asArray: true,
             // LITERAL- is part of base IMAP4rev2
             literalMinus: hasCapability(this, 'LITERAL-') || this.capabilities.has('LITERAL+')
@@ -439,7 +452,7 @@ export class ImapFlow extends EventEmitter {
         // Compile again for logging with isLogging=true: masks sensitive values
         // like passwords while producing a human-readable command string
         if (this.isLogLevelEnabled('debug')) {
-            let logCompiled = await compiler(data, {
+            let logCompiled = compiler(data, {
                 isLogging: true
             });
             this.log.debug({ src: 'c', msg: logCompiled.toString(), cid: this.id, comment: options.comment });
@@ -696,9 +709,7 @@ export class ImapFlow extends EventEmitter {
                 // parser would keep waiting on its backpressure callback forever, which is a
                 // silent permanent hang. Fail closed instead.
                 keepReading = false;
-                let error = new Error('Failed to process server response');
-                error.code = 'ResponseProcessingFailed';
-                error._err = err;
+                let error = createImapError('Failed to process server response', 'ResponseProcessingFailed', { _err: err });
                 this.log.error({ msg: 'Failed to process server response', err, cid: this.id });
                 this.rejectCurrentRequest(error);
                 this.failProtocol(error);
@@ -749,6 +760,27 @@ export class ImapFlow extends EventEmitter {
         this.rejectCurrentRequest(err);
         this.trySend().catch(sendErr => logConnectionError(this, 'Failed to dispatch command', sendErr));
     }
+    // RFC 9051 section 7.1: the text of an ALERT must be presented to the user. It can come
+    // with any status response, tagged or untagged, the greeting and BYE included. Called for
+    // responses that carry the ALERT code.
+    /** @internal */
+    reportAlert(parsed) {
+        let response = (parsed.command || '').toUpperCase();
+        if (!ALERT_RESPONSES.has(response)) {
+            return;
+        }
+        let alert = {
+            message: getTextValues(parsed.attributes)
+                .map(value => value.trim())
+                .join(' '),
+            response: response
+        };
+        if (parsed.tag && parsed.tag !== '*') {
+            alert.tag = parsed.tag;
+        }
+        this.log.info({ msg: 'Server alert', alert: alert.message, response: alert.response, cid: this.id });
+        emitSafe(this, 'alert', alert);
+    }
     /**
      * Handles a single parsed server response: telemetry, continuation requests, response-code
      * section handlers, untagged handlers and tagged command completion.
@@ -800,7 +832,7 @@ export class ImapFlow extends EventEmitter {
         // skipped when the level is off.
         let logLevel = /^\d+$/.test(parsed.command || '') && parsed.attributes && parsed.attributes[0] && parsed.attributes[0].value === 'FETCH' ? 'trace' : 'debug';
         if (this.isLogLevelEnabled(logLevel)) {
-            let logCompiled = await compiler(parsed, {
+            let logCompiled = compiler(parsed, {
                 isLogging: true
             });
             this.log[logLevel]({ src: 's', msg: logCompiled.toString(), cid: this.id, nullBytesRemoved: parsed.nullBytesRemoved });
@@ -843,6 +875,9 @@ export class ImapFlow extends EventEmitter {
         // dereference must be guarded or one such line tears down the whole connection
         if (section && section.length && section[0] && section[0].type === 'ATOM' && typeof section[0].value === 'string') {
             let sectionKey = section[0].value.toUpperCase().trim();
+            if (sectionKey === 'ALERT') {
+                this.reportAlert(parsed);
+            }
             let sectionHandler = this.getSectionHandler(sectionKey);
             if (sectionHandler) {
                 try {
@@ -903,12 +938,12 @@ export class ImapFlow extends EventEmitter {
                 // response ambiguous, so reject this request and fail the connection closed.
                 let request = this.requestTagMap.get(parsed.tag);
                 this.requestTagMap.delete(parsed.tag);
-                let err = new Error('Server sent a tagged response for a command that was not in flight');
-                err.code = 'UnexpectedTag';
-                err.details = {
-                    received: parsed.tag,
-                    expected: this.currentRequest ? this.currentRequest.tag : null
-                };
+                let err = createImapError('Server sent a tagged response for a command that was not in flight', 'UnexpectedTag', {
+                    details: {
+                        received: parsed.tag,
+                        expected: this.currentRequest ? this.currentRequest.tag : null
+                    }
+                });
                 this.log.error({ msg: 'Protocol desynchronization', err, cid: this.id });
                 request.reject(err);
                 this.failProtocol(err);
@@ -952,9 +987,9 @@ export class ImapFlow extends EventEmitter {
                 try {
                     err.executedCommand =
                         parsed.tag +
-                            (await compiler(request, {
+                            compiler(request, {
                                 isLogging: true
-                            })).toString();
+                            }).toString();
                 }
                 catch {
                     // ignore
@@ -1007,9 +1042,7 @@ export class ImapFlow extends EventEmitter {
                 break;
             }
             default: {
-                let err = new Error('Invalid server response');
-                err.code = 'InvalidResponse';
-                err.response = parsed;
+                let err = createImapError('Invalid server response', 'InvalidResponse', { response: parsed });
                 request.reject(err);
                 break;
             }
@@ -1110,11 +1143,7 @@ export class ImapFlow extends EventEmitter {
         this._socketTimeout =
             this._socketTimeout ||
                 (() => {
-                    const timeoutError = () => {
-                        const err = new Error('Socket timeout');
-                        err.code = 'ETIMEOUT';
-                        return err;
-                    };
+                    const timeoutError = () => createImapError('Socket timeout', 'ETIMEOUT');
                     if (!this.usable || !this.socket || this.socket.destroyed) {
                         this.emitError(timeoutError());
                         return;
@@ -1298,7 +1327,10 @@ export class ImapFlow extends EventEmitter {
         // to call deflate.flush() after each IMAP command to push all pending
         // compressed bytes to the server immediately (IMAP is request-response).
         const writeSocket = new PassThrough({
-            highWaterMark: 64 * 1024 // 64KB buffer limit to prevent excessive memory usage
+            highWaterMark: 64 * 1024, // 64KB buffer limit to prevent excessive memory usage
+            // read() hands out each written chunk as is: in byte mode it joins whatever is
+            // queued into a new Buffer, which copies every large literal once more
+            readableObjectMode: true
         });
         this.writeSocket = writeSocket;
         /* c8 ignore start */ // destroySoon override is never invoked by ImapFlow (close() calls destroy()); kept for stream API completeness
@@ -1426,9 +1458,7 @@ export class ImapFlow extends EventEmitter {
         // socket; injection that still races in afterwards corrupts the TLS handshake and
         // is rejected there instead (with a generic TLS error rather than STARTTLS_INJECTION).
         const failSTARTTLSInjection = () => {
-            let err = new Error('Server sent data after the STARTTLS response and before the TLS handshake; possible plaintext-injection attack');
-            err.code = 'STARTTLS_INJECTION';
-            err.tlsFailed = true;
+            let err = createImapError('Server sent data after the STARTTLS response and before the TLS handshake; possible plaintext-injection attack', 'STARTTLS_INJECTION', { tlsFailed: true });
             this.closeAfter();
             return err;
         };
@@ -1471,6 +1501,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 +1515,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,11 +1538,10 @@ 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');
-                err.code = 'UPGRADE_TIMEOUT';
+                let err = createImapError('Failed to upgrade connection in required time', 'UPGRADE_TIMEOUT');
                 settle(err);
             }, UPGRADE_TIMEOUT);
             /* c8 ignore stop */
@@ -1576,7 +1615,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) {
@@ -2006,9 +2045,7 @@ export class ImapFlow extends EventEmitter {
     async connect() {
         if (this._connectCalled) {
             // Prevent re-using ImapFlow instances by allowing to call connect just once.
-            let err = new Error('Can not re-use ImapFlow instance');
-            err.code = 'InstanceReused';
-            throw err;
+            throw createImapError('Can not re-use ImapFlow instance', 'InstanceReused');
         }
         this._connectCalled = true;
         let closedError = () => this.createNoConnectionError(this.byeReason, { rejectedFrom: 'connect' });
@@ -2096,14 +2133,14 @@ export class ImapFlow extends EventEmitter {
                     detachEarlyErrorHandler(socket);
                     this.configureSocket(this.socket);
                     this.greetingTimeout = setTimeout(() => {
-                        let err = new Error(
+                        let err = createImapError(
                         /* c8 ignore next */ // the greeting-timeout test uses a plaintext socket; the secure-socket branch of this hint is not separately exercised
-                        `Failed to receive greeting from server in required time${!this.secureConnection ? '. Maybe should use TLS?' : ''}`);
-                        err.code = 'GREETING_TIMEOUT';
-                        err.details = {
-                            /* c8 ignore next */ // firing the timeout with the default (large) value would hang the suite, so only the explicit-option path is tested
-                            greetingTimeout: this.options.greetingTimeout || GREETING_TIMEOUT
-                        };
+                        `Failed to receive greeting from server in required time${!this.secureConnection ? '. Maybe should use TLS?' : ''}`, 'GREETING_TIMEOUT', {
+                            details: {
+                                /* c8 ignore next */ // firing the timeout with the default (large) value would hang the suite, so only the explicit-option path is tested
+                                greetingTimeout: this.options.greetingTimeout || GREETING_TIMEOUT
+                            }
+                        });
                         this.log.error({ err, cid: this.id });
                         this.closeAfter();
                         reject(err);
@@ -2327,9 +2364,9 @@ export class ImapFlow extends EventEmitter {
             let reject = this.initialReject;
             this.initialResolve = false;
             this.initialReject = false;
-            let err = new Error('Unexpected close');
+            let err = createImapError('Unexpected close', 
             /* c8 ignore next */ // closing a pending connect over an already-secure socket (the TLS branch) is not separately exercised
-            err.code = `ClosedAfterConnect${this.secureConnection ? 'TLS' : 'Text'}`;
+            this.secureConnection ? 'ClosedAfterConnectTLS' : 'ClosedAfterConnectText');
             // Surface the server's BYE reason (e.g. "Too many connections") when the
             // connection was closed by an untagged BYE, so the caller sees why.
             if (this.byeReason) {
@@ -2840,7 +2877,7 @@ export class ImapFlow extends EventEmitter {
      * Appends a new message to a mailbox
      *
      * @param path Mailbox path to upload the message to (unicode string). If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
-     * @param content RFC822 formatted email message
+     * @param content RFC822 formatted email message, as a Buffer, Uint8Array or string
      * @param flags an array of flags to be set for the uploaded message
      * @param idate internal date to be set for the message
      * @returns info about uploaded message
@@ -3111,7 +3148,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.
@@ -3128,7 +3179,8 @@ export class ImapFlow extends EventEmitter {
      * // download body part nr '1.2' from latest message
      * let download = await client.download('*', '1.2');
      * if (download.content) {
-     *     download.content.pipe(fs.createWriteStream(download.meta.filename));
+     *     // pipeline() rejects when the download fails, a plain .pipe() would not report it
+     *     await stream.promises.pipeline(download.content, fs.createWriteStream(download.meta.filename));
      * }
      */
     async download(range, part, options) {
@@ -3465,9 +3517,7 @@ export class ImapFlow extends EventEmitter {
                     const idx = this.locks.indexOf(lockEntry);
                     if (idx !== -1) {
                         this.locks.splice(idx, 1);
-                        let err = new Error('Timed out waiting for mailbox lock');
-                        err.code = 'LockTimeout';
-                        err.lockId = lockEntry.lockId;
+                        let err = createImapError('Timed out waiting for mailbox lock', 'LockTimeout', { lockId: lockEntry.lockId });
                         reject(err);
                     }
                 }, Number(lockOptions.acquireTimeout));

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

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

package/node_modules/imapflow/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.8";
+export const version = "2.4.0";
 export const homepage = "https://imapflow.com/";

package/node_modules/imapflow/dist/esm/proxy-connection.js

@@ -4,6 +4,7 @@ import net from 'node:net';
 import tls from 'node:tls';
 import { ConnectionDeadline } from './connection-deadline.js';
 import { clearTimer } from './tools.js';
+import { createImapError } from './errors.js';
 // Cap the CONNECT response buffered before the header terminator, so a proxy that never sends
 // \r\n\r\n cannot grow memory without bound.
 const MAX_RESPONSE_HEADER_BYTES = 64 * 1024;
@@ -27,11 +28,7 @@ const redactUrl = (proxyUrl) => {
     }
     return redacted.href;
 };
-const proxyError = (message, code) => {
-    let err = new Error(message);
-    err.code = code || 'ProxyError';
-    return err;
-};
+const proxyError = (message, code) => createImapError(message, code || 'ProxyError');
 // URL userinfo is percent-encoded, so it has to be decoded before it can be used as credentials.
 // A password containing a bare '%' is not valid percent-encoding and makes decodeURIComponent
 // throw, so such values are used as they came in rather than failing the connection.

package/node_modules/imapflow/dist/esm/search-compiler.js

@@ -1,5 +1,6 @@
 /* eslint no-control-regex:0 */
 import { formatDate, formatFlag, toValidDate, isRev2Active } from './tools.js';
+import { createImapError } from './errors.js';
 // Matches any character outside the ASCII range
 const UNICODE_PATTERN = /[^\x00-\x7F]/;
 /**
@@ -101,9 +102,7 @@ let processDateField = (attributes, term, value) => {
  * @param message - Error message
  */
 let fail = (code, message) => {
-    let error = new Error(message);
-    error.code = code;
-    throw error;
+    throw createImapError(message, code);
 };
 /**
  * Checks whether any search value was compiled into a literal, which only

package/node_modules/imapflow/dist/esm/tools.d.ts

@@ -1,6 +1,6 @@
 import type { Transform } from 'node:stream';
 import type { ImapFlow } from './imap-flow.js';
-import { type ConnectionErrorSite, type ImapFlowError } from './errors.js';
+import { ImapFlowErrorCode, type ConnectionErrorSite, type ImapFlowError } from './errors.js';
 import type { ImapAttributeList, ImapAttributeNode, ImapResponse } from './handler/types.js';
 import type { FetchMessageObject, ListResponse, ListTreeResponse, MailboxObject, MessageEnvelopeObject, MessageStructureObject, ImapFlowEvents, StatusQuery } from './types.js';
 export { AuthenticationFailure } from './errors.js';
@@ -33,7 +33,7 @@ export type CharsetDecoder = Transform & {
  * @param meta - Fields to stamp on the error
  * @returns The stamped error
  */
-export declare function buildConnectionError(cid: string, code: string, message: string, meta?: ConnectionErrorSite | undefined): ImapFlowError;
+export declare function buildConnectionError(cid: string, code: ImapFlowErrorCode, message: string, meta?: ConnectionErrorSite | undefined): ImapFlowError;
 /**
  * Re-stamps an existing connection error for a different rejection site.
  *
@@ -122,9 +122,12 @@ export declare function logConnectionError(connection: ImapFlow, msg: string, er
 /**
  * Whether a command failed because the server answered it with a tagged NO or BAD, as opposed
  * to a lost connection, a timeout or a local failure that says nothing about the server's answer.
+ * A throttled command (ETHROTTLE, Microsoft 365 answers it with BAD) was not refused: the server
+ * asks to try again later, so a throttled login is not a rejected credential and a throttled
+ * IDLE does not mean the server lacks IDLE.
  *
  * @param err - The error the command failed with
- * @returns True for a tagged NO or BAD
+ * @returns True for a tagged NO or BAD that is not throttling
  */
 export declare function isServerRefusal(err: ImapFlowError | null | undefined): boolean;
 /**
@@ -287,6 +290,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 +436,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.
  *