imapflow 2.0.7 → 2.1.0

package/dist/esm/errors.d.ts

@@ -1,11 +1,58 @@
 import type { ImapResponse } from './handler/types.js';
+/**
+ * The `code` values ImapFlow sets on the errors it raises, so they can be matched without
+ * string literals: `if (err.code === ImapFlowErrorCode.NoConnection)`.
+ *
+ * Parser failures use `ParserError` followed by a number (`ParserError11`) and are not listed
+ * one by one, test them with `err.code?.startsWith('ParserError')`. Errors from the socket, TLS
+ * or DNS layer pass through with Node's own code (`ECONNREFUSED`, `ENOTFOUND`, ...).
+ */
+export declare const ImapFlowErrorCode: {
+    readonly NoConnection: "NoConnection";
+    readonly EConnectionClosed: "EConnectionClosed";
+    readonly StateLogout: "StateLogout";
+    readonly ClosedAfterConnectText: "ClosedAfterConnectText";
+    readonly ClosedAfterConnectTLS: "ClosedAfterConnectTLS";
+    readonly CONNECT_TIMEOUT: "CONNECT_TIMEOUT";
+    readonly GREETING_TIMEOUT: "GREETING_TIMEOUT";
+    readonly UPGRADE_TIMEOUT: "UPGRADE_TIMEOUT";
+    readonly ETIMEOUT: "ETIMEOUT";
+    readonly LockTimeout: "LockTimeout";
+    readonly ETHROTTLE: "ETHROTTLE";
+    readonly UnexpectedTag: "UnexpectedTag";
+    readonly InvalidResponse: "InvalidResponse";
+    readonly ResponseProcessingFailed: "ResponseProcessingFailed";
+    readonly STARTTLS_INJECTION: "STARTTLS_INJECTION";
+    readonly COMPRESS_TRAILING_DATA: "COMPRESS_TRAILING_DATA";
+    readonly PollFailed: "PollFailed";
+    readonly NotFound: "NotFound";
+    readonly MissingServerExtension: "MissingServerExtension";
+    readonly ParserError: "ParserError";
+    readonly ParserErrorExchange: "ParserErrorExchange";
+    readonly MAX_IMAP_NESTING_REACHED: "MAX_IMAP_NESTING_REACHED";
+    readonly LineTooLarge: "LineTooLarge";
+    readonly LiteralTooLarge: "LiteralTooLarge";
+    readonly ResponseTooLarge: "ResponseTooLarge";
+    readonly InvalidStringValue: "InvalidStringValue";
+    readonly InvalidTokenValue: "InvalidTokenValue";
+    readonly InvalidTextValue: "InvalidTextValue";
+    readonly InvalidSequenceSet: "InvalidSequenceSet";
+    readonly DownloadOverflow: "DownloadOverflow";
+    readonly DownloadIncomplete: "DownloadIncomplete";
+    readonly ProxyError: "ProxyError";
+    readonly EPROXY: "EPROXY";
+    readonly UnsupportedProxyAddress: "UnsupportedProxyAddress";
+    readonly ERR_INVALID_URL: "ERR_INVALID_URL";
+};
+/** One of the {@link ImapFlowErrorCode} values */
+export type ImapFlowErrorCode = (typeof ImapFlowErrorCode)[keyof typeof ImapFlowErrorCode];
 /**
  * An Error raised by ImapFlow, with the extra properties the library attaches to describe
  * the failure. Every property is optional: which ones are present depends on where the
  * error came from.
  */
 export interface ImapFlowError extends Error {
-    /** Error code, e.g. 'NoConnection', 'ETIMEOUT', 'LockTimeout' or a parser error code */
+    /** Error code, one of {@link ImapFlowErrorCode}, a parser error code or a code from Node */
     code?: string | undefined;
     /** Connection id the error belongs to */
     cid?: string | undefined;
@@ -33,6 +80,8 @@ export interface ImapFlowError extends Error {
     tlsFailed?: boolean | undefined;
     /** Server suggested back-off in milliseconds for an ETHROTTLE error */
     throttleReset?: number | undefined;
+    /** Milliseconds of the ETHROTTLE back-off the connection already waited before rejecting */
+    throttleWaited?: number | undefined;
     /** Additional details, e.g. the timeouts that applied */
     details?: {
         [key: string]: any;

package/dist/esm/errors.js

@@ -1,3 +1,55 @@
+/**
+ * The `code` values ImapFlow sets on the errors it raises, so they can be matched without
+ * string literals: `if (err.code === ImapFlowErrorCode.NoConnection)`.
+ *
+ * Parser failures use `ParserError` followed by a number (`ParserError11`) and are not listed
+ * one by one, test them with `err.code?.startsWith('ParserError')`. Errors from the socket, TLS
+ * or DNS layer pass through with Node's own code (`ECONNREFUSED`, `ENOTFOUND`, ...).
+ */
+export const ImapFlowErrorCode = {
+    // the connection is gone, the command was not (or can no longer be) completed
+    NoConnection: 'NoConnection',
+    EConnectionClosed: 'EConnectionClosed',
+    StateLogout: 'StateLogout',
+    ClosedAfterConnectText: 'ClosedAfterConnectText',
+    ClosedAfterConnectTLS: 'ClosedAfterConnectTLS',
+    // timeouts
+    CONNECT_TIMEOUT: 'CONNECT_TIMEOUT',
+    GREETING_TIMEOUT: 'GREETING_TIMEOUT',
+    UPGRADE_TIMEOUT: 'UPGRADE_TIMEOUT',
+    ETIMEOUT: 'ETIMEOUT',
+    LockTimeout: 'LockTimeout',
+    // the server
+    ETHROTTLE: 'ETHROTTLE',
+    UnexpectedTag: 'UnexpectedTag',
+    InvalidResponse: 'InvalidResponse',
+    ResponseProcessingFailed: 'ResponseProcessingFailed',
+    STARTTLS_INJECTION: 'STARTTLS_INJECTION',
+    COMPRESS_TRAILING_DATA: 'COMPRESS_TRAILING_DATA',
+    PollFailed: 'PollFailed',
+    NotFound: 'NotFound',
+    MissingServerExtension: 'MissingServerExtension',
+    // response parsing and size limits
+    ParserError: 'ParserError',
+    ParserErrorExchange: 'ParserErrorExchange',
+    MAX_IMAP_NESTING_REACHED: 'MAX_IMAP_NESTING_REACHED',
+    LineTooLarge: 'LineTooLarge',
+    LiteralTooLarge: 'LiteralTooLarge',
+    ResponseTooLarge: 'ResponseTooLarge',
+    // invalid values in a command
+    InvalidStringValue: 'InvalidStringValue',
+    InvalidTokenValue: 'InvalidTokenValue',
+    InvalidTextValue: 'InvalidTextValue',
+    InvalidSequenceSet: 'InvalidSequenceSet',
+    // download()
+    DownloadOverflow: 'DownloadOverflow',
+    DownloadIncomplete: 'DownloadIncomplete',
+    // proxy connections
+    ProxyError: 'ProxyError',
+    EPROXY: 'EPROXY',
+    UnsupportedProxyAddress: 'UnsupportedProxyAddress',
+    ERR_INVALID_URL: 'ERR_INVALID_URL'
+};
 /**
  * Error subclass thrown when IMAP authentication fails.
  */

package/dist/esm/handler/imap-compiler.js

@@ -238,7 +238,7 @@ async function compiler(response, options) {
                     // Strip a leading backslash before checking (system flags like \Seen start with '\').
                     // If any character fails verification, fall back to an IMAP quoted string
                     // (JSON.stringify is used only for log output, where values are display-escaped).
-                    if (node.value === '' || imapFormalSyntax.verify(val.charAt(0) === '\\' ? val.substr(1) : val, imapFormalSyntax['ATOM-CHAR']()) >= 0) {
+                    if (node.value === '' || imapFormalSyntax.verify(val.charAt(0) === '\\' ? val.slice(1) : val, imapFormalSyntax['ATOM-CHAR']()) >= 0) {
                         val = isLogging ? JSON.stringify(val) : quoteString(val);
                     }
                     resp.push(emitEntry(val));

package/dist/esm/handler/imap-stream.d.ts

@@ -145,13 +145,24 @@ export declare class ImapStream extends Transform {
      * pushed downstream as a readable object.
      *
      * @param chunk - The raw data chunk to process.
-     * @param startPos - The byte offset within the chunk to start processing from.
      */
-    processInputChunk(chunk: Buffer, startPos?: number | undefined): Promise<void>;
+    processInputChunk(chunk: Buffer): Promise<void>;
+    /**
+     * Processes the chunk from `startPos` until the parser state changes or the chunk ends.
+     *
+     * @returns The offset to continue from after a state switch, or `null` when done with the chunk.
+     */
+    processChunkSegment(chunk: Buffer, startPos: number): Promise<number | null>;
     /**
      * Drains the input queue by processing each queued chunk sequentially.
      * Yields to the event loop every 10 chunks to prevent CPU blocking on
      * large bursts of incoming data.
+     *
+     * The `processingInput` guard is cleared in the same synchronous step that finds the queue
+     * empty. Clearing it later (in a promise handler) leaves a gap of a few microtasks where a
+     * chunk delivered by the writable side is queued but no loop is started for it, so its
+     * transform callback is never called and the socket is never read again. Workers deliver
+     * the next chunk inside that gap.
      */
     processInput(): Promise<void>;
     /**

package/dist/esm/handler/imap-stream.js

@@ -217,12 +217,23 @@ export class ImapStream extends Transform {
      * pushed downstream as a readable object.
      *
      * @param chunk - The raw data chunk to process.
-     * @param startPos - The byte offset within the chunk to start processing from.
      */
-    async processInputChunk(chunk, startPos) {
-        startPos = startPos || 0;
+    async processInputChunk(chunk) {
+        // Every state switch hands back the offset to resume from instead of recursing, so a
+        // chunk packed with thousands of small literals can not exhaust the call stack
+        let nextPos = 0;
+        while (nextPos !== null) {
+            nextPos = await this.processChunkSegment(chunk, nextPos);
+        }
+    }
+    /**
+     * Processes the chunk from `startPos` until the parser state changes or the chunk ends.
+     *
+     * @returns The offset to continue from after a state switch, or `null` when done with the chunk.
+     */
+    async processChunkSegment(chunk, startPos) {
         if (this.destroyed || startPos >= chunk.length) {
-            return;
+            return null;
         }
         switch (this.state) {
             case LINE: {
@@ -232,9 +243,9 @@ export class ImapStream extends Transform {
                         // line end found. Measure the completed line (terminator included) before
                         // concatenating or emitting anything, so the cap does not depend on where
                         // TCP chunk boundaries happen to fall.
-                        let segment = chunk.slice(lineStart, i + 1);
+                        let segment = chunk.subarray(lineStart, i + 1);
                         if (!this.checkLineLength(this.lineBytes + segment.length)) {
-                            return;
+                            return null;
                         }
                         this.lineBuffer.push(segment);
                         lineStart = i + 1;
@@ -246,18 +257,18 @@ export class ImapStream extends Transform {
                         // would otherwise be emitted as part of the rejected command.
                         let isLiteralMarker = this.checkLiteralMarker(line);
                         if (this.destroyed) {
-                            return;
+                            return null;
                         }
                         // Count the line itself and, for a literal marker, the declared
                         // literal bytes against the cumulative per-response budget, so a
                         // response assembled from many tokens stays bounded as a whole
                         if (!this.checkResponseSize(line.length + (isLiteralMarker ? this.literalWaiting : 0))) {
-                            return;
+                            return null;
                         }
                         this.inputBuffer.push(line);
                         if (isLiteralMarker) {
                             // switch into literal mode and start over
-                            return await this.processInputChunk(chunk, lineStart);
+                            return lineStart;
                         }
                         // reached end of command input, emit it
                         let payload = this.inputBuffer.length === 1 ? this.inputBuffer[0] : Buffer.concat(this.inputBuffer);
@@ -272,7 +283,7 @@ export class ImapStream extends Transform {
                                 if (end > 0 && payload[end - 1] === CR) {
                                     end--;
                                 }
-                                payload = payload.slice(0, end);
+                                payload = payload.subarray(0, end);
                             }
                             if (payload.length) {
                                 // Whether more buffered input already followed this command on the
@@ -291,7 +302,7 @@ export class ImapStream extends Transform {
                                 });
                                 this.pendingPush = null;
                                 if (this.destroyed) {
-                                    return;
+                                    return null;
                                 }
                             }
                         }
@@ -300,14 +311,14 @@ export class ImapStream extends Transform {
                 if (lineStart < chunk.length) {
                     // No line terminator was found in the remaining bytes; carry the tail over to
                     // the next chunk after measuring the line it belongs to.
-                    let tail = chunk.slice(lineStart);
+                    let tail = chunk.subarray(lineStart);
                     // The response counter is only committed when a line completes, so an
                     // in-progress line is measured against the remaining budget separately.
                     // Without this a response cap lowered to bound parser memory buys nothing
                     // while a server streams a line that never terminates - only the much
                     // larger line cap would hold it back.
                     if (!this.checkLineLength(this.lineBytes + tail.length) || !this.checkResponseSize(this.lineBytes + tail.length, true)) {
-                        return;
+                        return null;
                     }
                     this.lineBytes += tail.length;
                     this.lineBuffer.push(tail);
@@ -317,7 +328,7 @@ export class ImapStream extends Transform {
             case LITERAL: {
                 const remainingInChunk = chunk.length - startPos;
                 const bytesToRead = Math.min(remainingInChunk, this.literalWaiting);
-                const partial = startPos === 0 && bytesToRead === chunk.length ? chunk : chunk.slice(startPos, startPos + bytesToRead);
+                const partial = startPos === 0 && bytesToRead === chunk.length ? chunk : chunk.subarray(startPos, startPos + bytesToRead);
                 this.literalBuffer.push(partial);
                 this.literalWaiting -= bytesToRead;
                 if (this.literalWaiting === 0) {
@@ -325,33 +336,45 @@ export class ImapStream extends Transform {
                     this.literalBuffer = [];
                     this.state = LINE;
                     if (remainingInChunk > bytesToRead) {
-                        return await this.processInputChunk(chunk, startPos + bytesToRead);
+                        return startPos + bytesToRead;
                     }
                 }
                 break;
             }
         }
+        return null;
     }
     /**
      * Drains the input queue by processing each queued chunk sequentially.
      * Yields to the event loop every 10 chunks to prevent CPU blocking on
      * large bursts of incoming data.
+     *
+     * The `processingInput` guard is cleared in the same synchronous step that finds the queue
+     * empty. Clearing it later (in a promise handler) leaves a gap of a few microtasks where a
+     * chunk delivered by the writable side is queued but no loop is started for it, so its
+     * transform callback is never called and the socket is never read again. Workers deliver
+     * the next chunk inside that gap.
      */
     async processInput() {
-        let data;
-        let processedCount = 0;
-        while (!this.destroyed && (data = this.inputQueue.shift())) {
-            this.activeInput = data;
-            await this.processInputChunk(data.chunk);
-            this.activeInput = null;
-            // mark chunk as processed
-            this.releaseInput(data);
-            // Yield to event loop every 10 chunks to prevent CPU blocking
-            processedCount++;
-            if (processedCount % 10 === 0) {
-                await new Promise(resolve => setImmediate(resolve));
+        try {
+            let data;
+            let processedCount = 0;
+            while (!this.destroyed && (data = this.inputQueue.shift())) {
+                this.activeInput = data;
+                await this.processInputChunk(data.chunk);
+                this.activeInput = null;
+                // mark chunk as processed
+                this.releaseInput(data);
+                // Yield to event loop every 10 chunks to prevent CPU blocking
+                processedCount++;
+                if (processedCount % 10 === 0) {
+                    await new Promise(resolve => setImmediate(resolve));
+                }
             }
         }
+        finally {
+            this.processingInput = false;
+        }
     }
     /**
      * Transform stream implementation. Receives raw data chunks from the writable side,
@@ -391,9 +414,7 @@ export class ImapStream extends Transform {
         this.inputQueue.push({ chunk, next });
         if (!this.processingInput) {
             this.processingInput = true;
-            this.processInput()
-                .catch(err => this.failStream(err))
-                .finally(() => (this.processingInput = false));
+            this.processInput().catch(err => this.failStream(err));
         }
     }
     /**

package/dist/esm/handler/parser-instance.js

@@ -160,7 +160,7 @@ export class ParserInstance {
             throw error;
         }
         this.pos += match[0].length;
-        this.remainder = this.remainder.substr(match[0].length);
+        this.remainder = this.remainder.slice(match[0].length);
         return element;
     }
     /**
@@ -187,7 +187,7 @@ export class ParserInstance {
             throw error;
         }
         this.pos++;
-        this.remainder = this.remainder.substr(1);
+        this.remainder = this.remainder.slice(1);
     }
     /**
      * Parses the remaining input as IMAP attributes using the TokenParser.

package/dist/esm/handler/token-parser.js

@@ -310,7 +310,7 @@ export class TokenParser {
                                 // IMAP URL (e.g., imap://user@host/mailbox) which contains characters
                                 // that would break normal ATOM parsing (colons, slashes, etc.).
                                 // We handle this by consuming everything up to ']' as a single ATOM value.
-                                if (this.str.substr(i + 1, 9).toUpperCase() === 'REFERRAL ') {
+                                if (this.str.substring(i + 1, i + 10).toUpperCase() === 'REFERRAL ') {
                                     // create the REFERRAL atom
                                     this.currentNode = this.createNode(this.currentNode, this.pos + i + 1);
                                     this.currentNode.type = 'ATOM';
@@ -321,15 +321,21 @@ export class TokenParser {
                                     this.currentNode = this.createNode(this.currentNode, this.pos + i + 10);
                                     // just call this an ATOM, even though IMAPURL might be more correct
                                     this.currentNode.type = 'ATOM';
-                                    // jump i to the ']'
-                                    i = this.str.indexOf(']', i + 10);
-                                    if (i < 0) {
-                                        // Malformed REFERRAL with no closing ']'. Consume the rest
-                                        // of the string (there is no ']' to exclude) instead of
-                                        // computing a negative-index substring, which would yield
-                                        // garbage.
-                                        i = this.str.length;
+                                    // jump i to the ']' that closes the section. The URL itself can
+                                    // hold a bracketed IPv6 host (imap://[::1]/INBOX), so brackets
+                                    // opened inside the URL are matched before the closing one.
+                                    let depth = 0;
+                                    for (i = i + 10; i < this.str.length; i++) {
+                                        let urlChr = this.str.charAt(i);
+                                        if (urlChr === '[') {
+                                            depth++;
+                                        }
+                                        else if (urlChr === ']' && depth-- === 0) {
+                                            break;
+                                        }
                                     }
+                                    // A malformed REFERRAL with no closing ']' leaves i at the end of
+                                    // the string, so the URL takes the rest of it.
                                     this.currentNode.endPos = this.pos + i - 1;
                                     this.currentNode.value = this.str.substring(this.currentNode.startPos - this.pos, this.currentNode.endPos - this.pos + 1);
                                     this.currentNode = this.currentNode.parentNode;

package/dist/esm/imap-flow.d.ts

@@ -6,10 +6,10 @@ import net from 'node:net';
 import { EventEmitter } from 'node:events';
 import { PassThrough, type Readable } from 'node:stream';
 import { AuthenticationFailure } from './errors.js';
-import type { AppendResponseObject, CopyResponseObject, DownloadManyOptions, DownloadManyResult, DownloadObject, DownloadOptions, ESearchResult, FetchMessageObject, FetchOptions, FetchQueryObject, IdInfoObject, ImapFlowEvents, ImapFlowOptions, InternalLogger, ListOptions, ListResponse, ListTreeResponse, MailboxCreateResponse, MailboxDeleteResponse, MailboxLockObject, MailboxLockOptions, MailboxObject, MailboxOpenOptions, MailboxRenameResponse, MessageRange, MessageRangeOptions, NamespaceObject, NamespacesObject, QuotaResponse, SearchObject, SearchOptions, SearchReturnOption, SequenceString, StatusObject, StatusQuery, StoreOptions, TlsInfo } from './types.js';
+import type { AppendResponseObject, CopyResponseObject, DownloadManyOptions, DownloadManyResult, DownloadObject, DownloadNotFound, DownloadOptions, ESearchResult, FetchMessageObject, FetchOptions, FetchQueryObject, IdInfoObject, ImapFlowEvents, ImapFlowOptions, InternalLogger, ListOptions, ListResponse, ListTreeResponse, MailboxCreateResponse, MailboxDeleteResponse, MailboxLockObject, MailboxLockOptions, MailboxObject, MailboxOpenOptions, MailboxRenameResponse, MessageRange, MessageRangeOptions, NamespaceObject, NamespacesObject, QuotaResponse, SearchObject, SearchOptions, SearchReturnOption, SequenceString, StatusObject, StatusQuery, StoreOptions, TlsInfo } from './types.js';
 export type * from './types.js';
 export type { ImapFlowError } from './errors.js';
-export { AuthenticationFailure } from './errors.js';
+export { AuthenticationFailure, ImapFlowErrorCode } from './errors.js';
 export type { ImapAttribute, ImapAttributeList, ImapAttributeNode, ImapResponse } from './handler/types.js';
 declare const stateValues: {
     readonly NOT_AUTHENTICATED: 1;
@@ -61,6 +61,17 @@ export interface ImapFlow {
     prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this;
     emit<K extends keyof ImapFlowEvents>(event: K, ...args: ImapFlowEvents[K]): boolean;
     emit(event: string | symbol, ...args: any[]): boolean;
+    /**
+     * Logs out and closes the connection when the scope of an `await using` declaration ends.
+     * Never throws, the connection is closed whether LOGOUT succeeds or not. Only present on
+     * runtimes that define `Symbol.asyncDispose` (Node.js 20.4 and newer).
+     *
+     * @example
+     * await using client = new ImapFlow({...});
+     * await client.connect();
+     * // client.logout() runs automatically when the scope exits, even on a throw
+     */
+    [Symbol.asyncDispose](): Promise<void>;
 }
 /**
  * IMAP client class for accessing IMAP mailboxes
@@ -135,6 +146,9 @@ export declare class ImapFlow extends EventEmitter {
     byeReason: string | undefined;
     /** Negotiated TLS session details, `false` for a cleartext connection */
     tls: TlsInfo | false | undefined;
+    /**
+     * Creates a client for one IMAP connection. Nothing is sent before `connect()` is called
+     */
     constructor(options?: ImapFlowOptions | undefined);
     /**
      * Returns byte counters for the current connection.
@@ -315,20 +329,20 @@ export declare class ImapFlow extends EventEmitter {
      *
      * @param path mailbox path to check for (unicode string). If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
      * @param query defines requested status items
-     * @returns status of the indicated mailbox
+     * @returns status of the indicated mailbox, or `false` if the server rejected the request
      *
      * @example
      * let status = await client.status('INBOX', {unseen: true});
      * console.log(status.unseen);
      * // 123
      */
-    status(path: string | string[], query: StatusQuery): Promise<StatusObject>;
+    status(path: string | string[], query: StatusQuery): Promise<StatusObject | false>;
     /**
      * Starts listening for new or deleted messages from the currently opened mailbox. Only required if `disableAutoIdle` is set to `true`
      * otherwise IDLE is started by default on connection inactivity. NB! If `idle()` is called manually then it does not
      * return until IDLE is finished which means you would have to call some other command out of scope.
      *
-     * @returns Did the operation succeed or not
+     * @returns `false` if IDLE failed, `undefined` otherwise
      *
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
@@ -470,6 +484,10 @@ export declare class ImapFlow extends EventEmitter {
      *   ]});
      */
     search(query: SearchObject, options?: MessageRangeOptions | undefined): Promise<number[] | false | undefined>;
+    /**
+     * Search with `returnOptions` set: an ESEARCH result object from a server that supports
+     * ESEARCH, the plain list of numbers otherwise
+     */
     search(query: SearchObject, options: SearchOptions & {
         returnOptions: SearchReturnOption[];
     }): Promise<ESearchResult | number[] | false | undefined>;
@@ -540,10 +558,12 @@ export declare class ImapFlow extends EventEmitter {
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
      * // download body part nr '1.2' from latest message
-     * let {meta, content} = await client.download('*', '1.2');
-     * content.pipe(fs.createWriteStream(meta.filename));
+     * let download = await client.download('*', '1.2');
+     * if (download.content) {
+     *     download.content.pipe(fs.createWriteStream(download.meta.filename));
+     * }
      */
-    download(range: SequenceString, part?: string | undefined, options?: DownloadOptions | undefined): Promise<DownloadObject>;
+    download(range: SequenceString, part?: string | undefined, options?: DownloadOptions | undefined): Promise<DownloadObject | DownloadNotFound>;
     /**
      * Fetch multiple attachments as Buffer values
      *
@@ -583,7 +603,8 @@ export declare class ImapFlow extends EventEmitter {
     getMailboxLock(path: string | string[], options?: MailboxLockOptions | undefined): Promise<MailboxLockObject>;
     /**
      * Detaches sockets from the IMAP pipeline. Useful for upgrading the connection
-     * (e.g., STARTTLS) or transferring socket ownership.
+     * (e.g., STARTTLS) or transferring socket ownership. Call it while the connection is not
+     * idling: an IDLE in progress is not broken first, so the server still expects `DONE`.
      *
      * @returns Socket objects: `readSocket` is the read socket (inflated socket if compression is enabled, raw socket otherwise),
      *   `writeSocket` the write socket and `socket` the raw underlying socket (same as readSocket/writeSocket when compression is disabled)
@@ -594,81 +615,6 @@ export declare class ImapFlow extends EventEmitter {
         socket: ImapSocket;
     };
 }
-/**
- * Connection close event. **NB!** ImapFlow does not handle reconnects automatically.
- * So whenever a 'close' event occurs you must create a new connection yourself.
- *
- * @event ImapFlow#close
- */
-/**
- * Error event. In most cases getting an error event also means that connection is closed
- * and pending operations should return with a failure.
- *
- * @event ImapFlow#error
- * @example
- * client.on('error', err=>{
- *     console.log(`Error occurred: ${err.message}`);
- * });
- */
-/**
- * Message count in currently opened mailbox changed
- *
- * @event ImapFlow#exists
- * @example
- * client.on('exists', data=>{
- *     console.log(`Message count in "${data.path}" is ${data.count}`);
- * });
- */
-/**
- * Deleted message sequence number in currently opened mailbox. One event is fired for every deleted email.
- *
- * @event ImapFlow#expunge
- * @example
- * client.on('expunge', data=>{
- *     console.log(`Message #${data.seq} was deleted from "${data.path}"`);
- * });
- */
-/**
- * Flags were updated for a message. Not all servers fire this event.
- *
- * @event ImapFlow#flags
- * @example
- * client.on('flags', data=>{
- *     console.log(`Flag set for #${data.seq} is now "${Array.from(data.flags).join(', ')}"`);
- * });
- */
-/**
- * Mailbox was opened
- *
- * @event ImapFlow#mailboxOpen
- * @example
- * client.on('mailboxOpen', mailbox => {
- *     console.log(`Mailbox ${mailbox.path} was opened`);
- * });
- */
-/**
- * Mailbox was closed
- *
- * Emitted both when a selected mailbox is closed explicitly, by `mailboxClose()` or by
- * selecting a different mailbox, and when the connection itself goes away while a mailbox
- * was still selected, whether through a clean logout or a lost transport. The transition is
- * reported once per selected mailbox, before the `close` event.
- *
- * @event ImapFlow#mailboxClose
- * @example
- * client.on('mailboxClose', mailbox => {
- *     console.log(`Mailbox ${mailbox.path} was closed`);
- * });
- */
-/**
- * Log event if `emitLogs=true`
- *
- * @event ImapFlow#log
- * @example
- * client.on('log', entry => {
- *     console.log(`${entry.cid} ${entry.msg}`);
- * });
- */
 declare const imapflow: {
     ImapFlow: typeof ImapFlow;
     AuthenticationFailure: typeof AuthenticationFailure;