imapflow 2.2.11 → 2.4.0

package/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, 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;
         };
@@ -1511,8 +1541,7 @@ export class ImapFlow extends EventEmitter {
             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 */
@@ -2016,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' });
@@ -2106,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);
@@ -2337,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) {
@@ -2850,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
@@ -3152,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) {
@@ -3489,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/dist/esm/package-info.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.2.11";
+export declare const version = "2.4.0";
 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.11";
+export const version = "2.4.0";
 export const homepage = "https://imapflow.com/";

package/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/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/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;
 /**

package/dist/esm/tools.js

@@ -6,7 +6,7 @@ import imapFormalSyntax from './handler/imap-formal-syntax.js';
 import { createHash } from 'node:crypto';
 import { JPDecoder } from './jp-decoder.js';
 import iconv from 'iconv-lite';
-import { ImapFlowErrorCode } from './errors.js';
+import { createImapError, ImapFlowErrorCode } from './errors.js';
 export { AuthenticationFailure } from './errors.js';
 const FLAG_COLORS = ['red', 'orange', 'yellow', 'green', 'blue', 'purple', 'grey'];
 // Error codes that only mean the connection is no longer usable. See logConnectionError().
@@ -88,13 +88,7 @@ const CONNECTION_ERROR_SITE_KEYS = ['rejectedFrom', 'command', 'path'];
  * @returns The stamped error
  */
 export function buildConnectionError(cid, code, message, meta) {
-    const error = new Error(message);
-    error.code = code;
-    error.cid = cid;
-    if (meta) {
-        Object.assign(error, meta);
-    }
-    return error;
+    return createImapError(message, code, { cid, ...meta });
 }
 /**
  * Re-stamps an existing connection error for a different rejection site.
@@ -116,6 +110,7 @@ export function buildConnectionError(cid, code, message, meta) {
  * @returns A separate error describing the same failure at the new site
  */
 export function restampConnectionError(err, meta) {
+    // the original code is carried over unchanged, whatever its origin
     let error = buildConnectionError(err.cid, err.code, err.message, err);
     for (let key of CONNECTION_ERROR_SITE_KEYS) {
         delete error[key];
@@ -215,12 +210,15 @@ export function logConnectionError(connection, msg, err) {
 /**
  * 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 function isServerRefusal(err) {
-    return !!err && (err.responseStatus === 'NO' || err.responseStatus === 'BAD');
+    return !!err && (err.responseStatus === 'NO' || err.responseStatus === 'BAD') && err.code !== ImapFlowErrorCode.ETHROTTLE;
 }
 /**
  * Checks whether IMAP4rev2 semantics are active for the connection: either the
@@ -466,12 +464,13 @@ export function getTextValues(attributes) {
  * @param response - Parsed IMAP server response
  * @returns Compiled response text, or false if no response
  */
+// Async although nothing in it awaits any more: `imapflow/lib/tools` deep imports may chain on the promise
 export async function getErrorText(response) {
     if (!response) {
         return false;
     }
     try {
-        return (await compiler(response)).toString();
+        return compiler(response).toString();
     }
     catch {
         // The wire encoder refuses values that cannot be expressed as a valid IMAP
@@ -480,7 +479,7 @@ export async function getErrorText(response) {
         // tolerates stray bytes inside an OK/NO/BAD atom, and those bytes then have
         // no valid re-encoding. This text is diagnostic, so fall back to the logging
         // encoder rather than replacing the server's error with an encoding failure.
-        return (await compiler(response, { isLogging: true })).toString();
+        return compiler(response, { isLogging: true }).toString();
     }
 }
 /**
@@ -694,6 +693,7 @@ export function mergeFetchRows(rows) {
  * @param connection - Connection the response arrived on, decodes Gmail labels like mailbox names
  * @returns Formatted message object with properties like seq, uid, flags, envelope, etc.
  */
+// Async although nothing in it awaits any more: `imapflow/lib/tools` deep imports may chain on the promise
 export async function formatMessageResponse(untagged, mailbox, idHashAlgorithm, connection) {
     let map = {};
     // The sequence number indexes into mailbox state, so an unusable one is dropped rather
@@ -716,9 +716,9 @@ export async function formatMessageResponse(untagged, mailbox, idHashAlgorithm,
         let attribute = attributes[i];
         if (i % 2 === 0) {
             origin = false;
-            key = (await compiler({
+            key = compiler({
                 attributes: [attribute]
-            }))
+            })
                 .toString()
                 .toLowerCase()
                 .replace(/<(\d+)(\.\d+)?>$/, (match, start) => {

package/dist/esm/types.d.ts

@@ -805,6 +805,15 @@ export interface LogEvent {
     /** Additional log data */
     [key: string]: any;
 }
+/** A message the server marked with the ALERT response code, to be shown to the user (RFC 9051 section 7.1) */
+export interface AlertEvent {
+    /** The alert text */
+    message: string;
+    /** The response that carried it */
+    response: 'OK' | 'NO' | 'BAD' | 'BYE' | 'PREAUTH';
+    /** Tag of the command it completed, missing for an untagged response */
+    tag?: string | undefined;
+}
 export interface ResponseEvent {
     /** Response type */
     response: string;
@@ -870,4 +879,6 @@ export interface ImapFlowEvents {
     log: [entry: LogEvent];
     /** Response event */
     response: [response: ResponseEvent];
+    /** The server sent an ALERT: text meant for the user, such as a planned shutdown or an account problem */
+    alert: [alert: AlertEvent];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "2.2.11",
+    "version": "2.4.0",
     "description": "IMAP Client for Node",
     "type": "module",
     "main": "./dist/cjs/imap-flow.js",
@@ -75,13 +75,13 @@
         "eslint": "10.12.0",
         "eslint-config-prettier": "10.1.8",
         "globals": "17.13.0",
-        "imapkit": "4.3.1",
+        "imapkit": "5.0.1",
         "prettier": "3.9.9",
         "tsx": "4.23.15",
         "types-node-legacy": "npm:@types/node@20.0.0",
         "typescript": "6.0.3",
         "typescript-eslint": "8.71.1",
-        "wrangler": "4.148.0"
+        "wrangler": "4.149.0"
     },
     "dependencies": {
         "@zone-eu/mailsplit": "5.4.20",
@@ -95,5 +95,8 @@
     },
     "engines": {
         "node": ">=20.0.0"
+    },
+    "overrides": {
+        "sharp": "0.35.5"
     }
 }