imapflow 1.7.7 → 2.0.0

package/dist/cjs/commands/enable.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = enable;
+const tools_js_1 = require("../tools.js");
+/**
+ * Enables IMAP extensions on the server.
+ *
+ * @param connection - IMAP connection instance
+ * @param extensionList - List of extension names to enable
+ * @returns Set of enabled extensions, false on failure, or undefined if not applicable
+ */
+async function enable(connection, extensionList) {
+    // ENABLE is part of base IMAP4rev2, so rev2-only servers may omit the token
+    if (!(0, tools_js_1.hasCapability)(connection, 'ENABLE') || connection.state !== connection.states.AUTHENTICATED) {
+        // nothing to do here
+        return;
+    }
+    // Pre-filter: only request extensions the server actually advertised in its
+    // CAPABILITY response. Requesting unsupported extensions would cause an error.
+    // Compared case-insensitively - the capability map keeps canonical casing for
+    // some keys (e.g. IMAP4rev2).
+    let advertised = new Set([...connection.capabilities.keys()].map(capability => capability.toUpperCase()));
+    extensionList = extensionList.filter(extension => advertised.has(extension.toUpperCase()));
+    if (!extensionList.length) {
+        return;
+    }
+    let response;
+    try {
+        let enabled = new Set();
+        response = await connection.exec('ENABLE', extensionList.map((extension) => ({ type: 'ATOM', value: extension.toUpperCase() })), {
+            untagged: {
+                // The untagged ENABLED response is a flat list of extension names
+                // (e.g., "* ENABLED CONDSTORE UTF8=ACCEPT"), NOT key-value pairs.
+                // Each attribute is a single extension identifier.
+                ENABLED: async (untagged) => {
+                    if (!untagged.attributes || !untagged.attributes.length) {
+                        return;
+                    }
+                    untagged.attributes.forEach(attr => {
+                        let value = attr.value;
+                        if (value && typeof value === 'string') {
+                            enabled.add(value.toUpperCase().trim());
+                        }
+                    });
+                }
+            }
+        });
+        // Merge instead of replace - the untagged ENABLED response only lists
+        // extensions enabled by this command (RFC 5161), so a replace would drop
+        // grants from an earlier ENABLE call
+        connection.enabled = new Set([...connection.enabled, ...enabled]);
+        response.next();
+        return connection.enabled;
+    }
+    catch (err) {
+        connection.log.warn({ err, cid: connection.id });
+        return false;
+    }
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/esearch-parser.d.ts

@@ -0,0 +1,17 @@
+import type { ImapAttributeList } from '../handler/types.js';
+import type { ESearchResult } from '../types.js';
+/**
+ * Parses the key-value attributes from an ESEARCH untagged response.
+ *
+ * Receives the attribute list AFTER stripping the leading (TAG "X") list
+ * and the UID atom, i.e. only the result keyword/value pairs remain.
+ *
+ * ALL and PARTIAL.messages are kept as compact sequence-set strings.
+ * Use expandRange() from tools.ts if you need to expand them.
+ * MODSEQ (RFC 7162, sent when the search used a MODSEQ criterion) is
+ * returned as a BigInt.
+ *
+ * @param attrs - Attribute array from the IMAP parser
+ * @returns ESearchResult object
+ */
+export declare function parseEsearchResponse(attrs: ImapAttributeList): ESearchResult;

package/dist/cjs/commands/esearch-parser.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEsearchResponse = parseEsearchResponse;
+const tools_js_1 = require("../tools.js");
+/**
+ * Parses the key-value attributes from an ESEARCH untagged response.
+ *
+ * Receives the attribute list AFTER stripping the leading (TAG "X") list
+ * and the UID atom, i.e. only the result keyword/value pairs remain.
+ *
+ * ALL and PARTIAL.messages are kept as compact sequence-set strings.
+ * Use expandRange() from tools.ts if you need to expand them.
+ * MODSEQ (RFC 7162, sent when the search used a MODSEQ criterion) is
+ * returned as a BigInt.
+ *
+ * @param attrs - Attribute array from the IMAP parser
+ * @returns ESearchResult object
+ */
+function parseEsearchResponse(attrs) {
+    const result = {};
+    let i = 0;
+    while (i < attrs.length) {
+        const token = attrs[i];
+        if (!token || token.type !== 'ATOM') {
+            i++;
+            continue;
+        }
+        const key = token.value.toUpperCase();
+        if (i + 1 >= attrs.length) {
+            i++;
+            continue;
+        }
+        switch (key) {
+            // COUNT is a plain message count; MIN and MAX are sequence numbers or UIDs. All
+            // three are bounded decimal runs - isNaN() would also admit '1e400' (Infinity)
+            case 'COUNT': {
+                const n = (0, tools_js_1.parseUintValue)(attrs[++i]?.value, tools_js_1.MAX_UINT32_DIGITS);
+                if (n !== false)
+                    result.count = n;
+                break;
+            }
+            case 'MIN': {
+                const n = (0, tools_js_1.parseUintValue)(attrs[++i]?.value, tools_js_1.MAX_UINT32_DIGITS);
+                if (n !== false)
+                    result.min = n;
+                break;
+            }
+            case 'MAX': {
+                const n = (0, tools_js_1.parseUintValue)(attrs[++i]?.value, tools_js_1.MAX_UINT32_DIGITS);
+                if (n !== false)
+                    result.max = n;
+                break;
+            }
+            case 'MODSEQ': {
+                // RFC 7162 section 3.1.5: present when the SEARCH used a MODSEQ
+                // criterion on a CONDSTORE-enabled session. BigInt because
+                // mod-sequence values are unsigned 63-bit
+                const modseq = (0, tools_js_1.parseBigIntValue)(attrs[++i]?.value);
+                if (modseq !== false)
+                    result.modseq = modseq;
+                break;
+            }
+            case 'ALL': {
+                const allToken = attrs[++i];
+                if (allToken && typeof allToken.value === 'string') {
+                    result.all = allToken.value;
+                }
+                break;
+            }
+            case 'PARTIAL': {
+                const listToken = attrs[++i];
+                const items = Array.isArray(listToken) ? listToken : null;
+                if (!items || items.length < 2)
+                    break;
+                result.partial = {
+                    range: items[0].value,
+                    messages: items[1].value
+                };
+                break;
+            }
+            default:
+                // Skip the value token for unknown keys to keep the stream aligned.
+                // The loop's unconditional i++ at the bottom advances past the key;
+                // this extra i++ advances past the value token.
+                i++;
+                break;
+        }
+        i++;
+    }
+    return result;
+}

package/dist/cjs/commands/expunge.d.ts

@@ -0,0 +1,12 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { MessageRangeOptions } from '../types.js';
+/**
+ * Deletes specified messages by flagging them as Deleted and expunging.
+ *
+ * @param connection - IMAP connection instance
+ * @param range - Message sequence number or UID range
+ * @param options - Expunge options
+ * @param options.uid - If true, use UID EXPUNGE when UIDPLUS is available
+ * @returns True on success, false on failure, or undefined if preconditions not met
+ */
+export default function expunge(connection: ImapFlow, range: string, options?: MessageRangeOptions | undefined): Promise<boolean | undefined>;

package/dist/cjs/commands/expunge.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = expunge;
+const tools_js_1 = require("../tools.js");
+/**
+ * Deletes specified messages by flagging them as Deleted and expunging.
+ *
+ * @param connection - IMAP connection instance
+ * @param range - Message sequence number or UID range
+ * @param options - Expunge options
+ * @param options.uid - If true, use UID EXPUNGE when UIDPLUS is available
+ * @returns True on success, false on failure, or undefined if preconditions not met
+ */
+async function expunge(connection, range, options) {
+    if (connection.state !== connection.states.SELECTED || !range) {
+        // nothing to do here
+        return;
+    }
+    options = options || {};
+    // Two-step deletion process per IMAP protocol:
+    // Step 1: Mark the target messages with the \Deleted flag.
+    await connection.messageFlagsAdd(range, ['\\Deleted'], options);
+    // Step 2: Issue EXPUNGE to permanently remove \Deleted messages.
+    // With UIDPLUS (RFC 4315): "UID EXPUNGE <uids>" removes only the specified UIDs,
+    // leaving other \Deleted messages untouched, important for concurrent access.
+    // Without UIDPLUS: plain "EXPUNGE" removes ALL messages flagged \Deleted in the mailbox.
+    let byUid = options.uid && (0, tools_js_1.hasCapability)(connection, 'UIDPLUS');
+    let command = byUid ? 'UID EXPUNGE' : 'EXPUNGE';
+    let attributes = byUid ? [{ type: 'SEQUENCE', value: range }] : false;
+    let response;
+    try {
+        response = await connection.exec(command, attributes);
+        // CONDSTORE (RFC 7162): the server may return HIGHESTMODSEQ in the response code
+        // (e.g., "A OK [HIGHESTMODSEQ 9122] Expunge completed").
+        // Track this so the client can detect concurrent mailbox changes via mod-sequences.
+        let section = response.response.attributes && response.response.attributes[0] && response.response.attributes[0].section;
+        let responseCode = section && section.length && section[0] && typeof section[0].value === 'string' ? section[0].value : '';
+        if (responseCode.toUpperCase() === 'HIGHESTMODSEQ') {
+            // A response code always comes with its section, see responseCode above
+            let codeSection = section;
+            let mailbox = connection.mailbox;
+            // Bounded digit runs only: isNaN() also passes '1e5', which BigInt() rejects with
+            // a throw that the catch below would swallow, making messageDelete() report false
+            // even though the server expunged the messages.
+            let highestModseq = (0, tools_js_1.parseBigIntValue)(codeSection[1] && codeSection[1].value);
+            if (highestModseq && (!mailbox.highestModseq || highestModseq > mailbox.highestModseq)) {
+                mailbox.highestModseq = highestModseq;
+            }
+        }
+        response.next();
+        return true;
+    }
+    catch (err) {
+        await (0, tools_js_1.enhanceCommandError)(err);
+        connection.log.warn({ err, cid: connection.id });
+        return false;
+    }
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/fetch.d.ts

@@ -0,0 +1,30 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { FetchMessageObject, FetchOptions, FetchQueryObject } from '../types.js';
+/**
+ * Options for the FETCH command
+ */
+export interface FetchCommandOptions extends Omit<FetchOptions, 'changedSince'> {
+    /** Only fetch messages changed since this modseq value */
+    changedSince?: bigint | number | string | undefined;
+    /** Callback for processing each fetched message individually. Call `next()` to release the next message */
+    onUntaggedFetch?: ((message: FetchMessageObject, next: (err?: Error | null | undefined) => void) => void) | undefined;
+}
+/**
+ * Result of the FETCH command
+ */
+export interface FetchCommandResult {
+    /** Number of untagged FETCH responses received */
+    count: number;
+    /** Formatted messages, empty when `onUntaggedFetch` consumed them */
+    list: FetchMessageObject[];
+}
+/**
+ * Fetches emails from the server.
+ *
+ * @param connection - IMAP connection instance
+ * @param range - Message sequence number or UID range
+ * @param query - Fetch query specifying which data to retrieve (e.g., flags, envelope, bodyStructure, headers, source, bodyParts)
+ * @param options - Fetch options
+ * @returns Object with message count and list, or undefined if not in SELECTED state
+ */
+export default function fetch(connection: ImapFlow, range: string, query: FetchQueryObject, options?: FetchCommandOptions | undefined): Promise<FetchCommandResult | undefined>;

package/dist/cjs/commands/fetch.js

@@ -0,0 +1,241 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = fetch;
+const tools_js_1 = require("../tools.js");
+/**
+ * Fetches emails from the server.
+ *
+ * @param connection - IMAP connection instance
+ * @param range - Message sequence number or UID range
+ * @param query - Fetch query specifying which data to retrieve (e.g., flags, envelope, bodyStructure, headers, source, bodyParts)
+ * @param options - Fetch options
+ * @returns Object with message count and list, or undefined if not in SELECTED state
+ */
+async function fetch(connection, range, query, options) {
+    if (connection.state !== connection.states.SELECTED || !range) {
+        // nothing to do here
+        return;
+    }
+    options = options || {};
+    let mailbox = connection.mailbox;
+    // Use BINARY extension for fetching if supported and requested, otherwise fall back to BODY.
+    // RFC 9051 folds the FETCH side of the BINARY extension into base IMAP4rev2, so an active
+    // rev2 session can use it even without the BINARY capability token (the APPEND side is NOT
+    // folded in and stays gated on the token in append.ts)
+    const canUseBinary = connection.capabilities.has('BINARY') || (0, tools_js_1.isRev2Active)(connection);
+    const commandKey = canUseBinary && options.binary && !connection.disableBinary ? 'BINARY' : 'BODY';
+    // Retry logic for ETHROTTLE errors (server rate limiting) with exponential backoff
+    let retryCount = 0;
+    const maxRetries = 4;
+    const baseDelay = 1000; // Start with 1 second delay
+    while (retryCount < maxRetries) {
+        let messages = {
+            count: 0,
+            list: []
+        };
+        let response;
+        try {
+            /* c8 ignore next */ // range is guaranteed truthy by the early-return guard above, so the '*' fallback is unreachable
+            let attributes = [{ type: 'SEQUENCE', value: (range || '*').toString() }];
+            let queryStructure = [];
+            // Helper to build BODY.PEEK[section]<partial> or BINARY.PEEK[section]<partial> atoms.
+            // PEEK avoids marking messages as \Seen. Section identifies what to fetch (HEADER, specific part, etc.)
+            // Partial is an optional byte range [start, maxLength].
+            let setBodyPeek = (attributes, partial) => {
+                let section = [].concat(attributes || []);
+                // BINARY may only address the empty section or a numeric part specifier
+                // (RFC 3516 / RFC 9051 section-binary) - HEADER, HEADER.FIELDS, TEXT and
+                // n.MIME are invalid after BINARY and must stay BODY fetches
+                let first = section[0];
+                let binaryAddressable = !section.length || (section.length === 1 && typeof first.value === 'string' && /^\d+(\.\d+)*$/.test(first.value));
+                let bodyPeek = {
+                    type: 'ATOM',
+                    value: `${binaryAddressable ? commandKey : 'BODY'}.PEEK`,
+                    section: section,
+                    partial
+                };
+                queryStructure.push(bodyPeek);
+            };
+            // IMAP fetch macros (ALL, FAST, FULL) and standard data items map directly to IMAP atoms
+            ['all', 'fast', 'full', 'uid', 'flags', 'bodyStructure', 'envelope', 'internalDate'].forEach(key => {
+                if (query[key]) {
+                    queryStructure.push({ type: 'ATOM', value: key.toUpperCase() });
+                }
+            });
+            if (query.size) {
+                queryStructure.push({ type: 'ATOM', value: 'RFC822.SIZE' });
+            }
+            // Fetch full message source, optionally with byte range (start/maxLength)
+            if (query.source) {
+                let partial;
+                if (typeof query.source === 'object' && (query.source.start || query.source.maxLength)) {
+                    partial = [Number(query.source.start) || 0];
+                    if (query.source.maxLength && !isNaN(query.source.maxLength)) {
+                        partial.push(Number(query.source.maxLength));
+                    }
+                }
+                setBodyPeek(null, partial);
+            }
+            // Always request a unique email ID for message deduplication.
+            // Prefer OBJECTID (RFC 8474) over Gmail's X-GM-MSGID extension.
+            if (connection.capabilities.has('OBJECTID')) {
+                queryStructure.push({ type: 'ATOM', value: 'EMAILID' });
+            }
+            else if (connection.capabilities.has('X-GM-EXT-1')) {
+                queryStructure.push({ type: 'ATOM', value: 'X-GM-MSGID' });
+            }
+            // Thread ID: OBJECTID's THREADID or Gmail's X-GM-THRID
+            if (query.threadId) {
+                if (connection.capabilities.has('OBJECTID')) {
+                    queryStructure.push({ type: 'ATOM', value: 'THREADID' });
+                }
+                else if (connection.capabilities.has('X-GM-EXT-1')) {
+                    queryStructure.push({ type: 'ATOM', value: 'X-GM-THRID' });
+                }
+            }
+            // Gmail labels are only available with X-GM-EXT-1 extension
+            if (query.labels) {
+                if (connection.capabilities.has('X-GM-EXT-1')) {
+                    queryStructure.push({ type: 'ATOM', value: 'X-GM-LABELS' });
+                }
+            }
+            // always ask for modseq if possible
+            if (connection.enabled.has('CONDSTORE') && !mailbox.noModseq) {
+                queryStructure.push({ type: 'ATOM', value: 'MODSEQ' });
+            }
+            // Always include UID in the response even if not explicitly requested,
+            // since we use it internally for message identification and tracking
+            if (!query.uid) {
+                queryStructure.push({ type: 'ATOM', value: 'UID' });
+            }
+            // Headers: fetch all headers or only specific ones via HEADER.FIELDS
+            if (query.headers) {
+                if (Array.isArray(query.headers)) {
+                    setBodyPeek([{ type: 'ATOM', value: 'HEADER.FIELDS' }, query.headers.map(header => ({ type: 'ATOM', value: header }))]);
+                }
+                else {
+                    setBodyPeek({ type: 'ATOM', value: 'HEADER' });
+                }
+            }
+            // Fetch specific body parts by MIME part number (e.g., "1", "1.2", "2.MIME")
+            // Each part can optionally include a byte range (start/maxLength)
+            if (query.bodyParts && query.bodyParts.length) {
+                query.bodyParts.forEach(part => {
+                    if (!part) {
+                        return;
+                    }
+                    let key;
+                    let partial;
+                    if (typeof part === 'object') {
+                        if (!part.key || typeof part.key !== 'string') {
+                            return;
+                        }
+                        key = part.key.toUpperCase();
+                        if (part.start || part.maxLength) {
+                            partial = [Number(part.start) || 0];
+                            if (part.maxLength && !isNaN(part.maxLength)) {
+                                partial.push(Number(part.maxLength));
+                            }
+                        }
+                    }
+                    else if (typeof part === 'string') {
+                        key = part.toUpperCase();
+                    }
+                    else {
+                        return;
+                    }
+                    setBodyPeek({ type: 'ATOM', value: key }, partial);
+                });
+            }
+            // IMAP requires a single item to not be wrapped in parentheses, but
+            // multiple items must be in a list. If only one item, unwrap the array.
+            let queryAttribute = queryStructure;
+            if (queryStructure.length === 1) {
+                queryAttribute = queryStructure.pop();
+            }
+            attributes.push(queryAttribute);
+            // CONDSTORE extension: only fetch messages with modseq higher than the given value.
+            // QRESYNC adds VANISHED to also get expunged UIDs since last sync.
+            if (options.changedSince && connection.enabled.has('CONDSTORE') && !mailbox.noModseq) {
+                let changedSinceArgs = [
+                    {
+                        type: 'ATOM',
+                        value: 'CHANGEDSINCE'
+                    },
+                    {
+                        type: 'ATOM',
+                        value: options.changedSince.toString()
+                    }
+                ];
+                if (options.uid && connection.enabled.has('QRESYNC')) {
+                    changedSinceArgs.push({
+                        type: 'ATOM',
+                        value: 'VANISHED'
+                    });
+                }
+                attributes.push(changedSinceArgs);
+            }
+            response = await connection.exec(options.uid ? 'UID FETCH' : 'FETCH', attributes, {
+                untagged: {
+                    // Each matching message triggers an untagged FETCH response.
+                    // If onUntaggedFetch callback is provided, stream messages to it one by one
+                    // (useful for large result sets). Otherwise, collect all into messages.list.
+                    FETCH: async (untagged) => {
+                        messages.count++;
+                        let formatted = await (0, tools_js_1.formatMessageResponse)(untagged, mailbox);
+                        if (typeof options.onUntaggedFetch === 'function') {
+                            await new Promise((resolve, reject) => {
+                                options.onUntaggedFetch(formatted, err => {
+                                    if (err) {
+                                        reject(err);
+                                    }
+                                    else {
+                                        resolve();
+                                    }
+                                });
+                            });
+                        }
+                        else {
+                            messages.list.push(formatted);
+                        }
+                    }
+                }
+            });
+            response.next();
+            return messages;
+        }
+        catch (err) {
+            if (err.code === 'ETHROTTLE') {
+                // Server returned a throttle error (rate limiting). Retry with exponential backoff.
+                // Delay doubles each retry: 1s, 2s, 4s, 8s (capped at 30s).
+                // If server provides a throttleReset hint, use that if longer.
+                const backoffDelay = Math.min(baseDelay * Math.pow(2, retryCount), 30000); // Cap at 30 seconds
+                // Use throttle reset time if provided and longer than backoff. The hint is
+                // server-controlled, so the wait goes through connection.throttleWait(), which caps
+                // it and keeps the timer tracked and abortable.
+                const delay = err.throttleReset && err.throttleReset > backoffDelay ? err.throttleReset : backoffDelay;
+                connection.log.warn({
+                    msg: 'Retrying throttled request with exponential backoff',
+                    cid: connection.id,
+                    code: err.code,
+                    response: err.responseText,
+                    throttleReset: err.throttleReset,
+                    retryCount,
+                    delayMs: delay
+                });
+                // An aborted wait means the client was closed, so give up rather than reissuing
+                // the FETCH on a connection that is already gone.
+                let aborted = await connection.throttleWait(delay);
+                if (aborted) {
+                    throw connection.createNoConnectionError(connection.byeReason, { rejectedFrom: 'throttleAbort', command: 'FETCH' });
+                }
+                retryCount++;
+                continue;
+            }
+            connection.log.warn({ err, cid: connection.id });
+            throw err;
+        }
+    }
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/id.d.ts

@@ -0,0 +1,10 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { IdInfoObject } from '../types.js';
+/**
+ * Sends ID info to the server and updates server info data based on the response.
+ *
+ * @param connection - IMAP connection instance
+ * @param clientInfo - Client identification key-value pairs to send to the server
+ * @returns Server information map, false on failure, or undefined if ID not supported
+ */
+export default function id(connection: ImapFlow, clientInfo?: IdInfoObject | null | undefined): Promise<IdInfoObject | false | undefined>;

package/dist/cjs/commands/id.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = id;
+const tools_js_1 = require("../tools.js");
+/**
+ * Sends ID info to the server and updates server info data based on the response.
+ *
+ * @param connection - IMAP connection instance
+ * @param clientInfo - Client identification key-value pairs to send to the server
+ * @returns Server information map, false on failure, or undefined if ID not supported
+ */
+// RFC 2971: The ID command exchanges client/server implementation info
+// (name, version, vendor, etc.) for diagnostic and compatibility purposes.
+async function id(connection, clientInfo) {
+    if (!connection.capabilities.has('ID')) {
+        // nothing to do here
+        return;
+    }
+    let response;
+    try {
+        let map = {};
+        // Convert the clientInfo object into a flat array of alternating key-value strings
+        // for the IMAP wire format: ("key1" "value1" "key2" "value2" ...)
+        let formattedClientInfo = !clientInfo
+            ? null
+            : Object.keys(clientInfo)
+                .map(key => [key, formatValue(key, clientInfo[key])])
+                .filter(entry => entry[1])
+                .flatMap(entry => entry);
+        if (formattedClientInfo && !formattedClientInfo.length) {
+            // value array has no elements
+            formattedClientInfo = null;
+        }
+        response = await connection.exec('ID', [formattedClientInfo], {
+            untagged: {
+                // Parse the server's ID response: a flat list of alternating key-value atoms.
+                // Even indices (i % 2 === 0) are keys, odd indices are the corresponding values.
+                ID: async (untagged) => {
+                    let params = untagged.attributes && untagged.attributes[0];
+                    let key;
+                    (Array.isArray(params) ? params : [].concat(params || [])).forEach((val, i) => {
+                        if (i % 2 === 0) {
+                            key = val.value;
+                        }
+                        else if (typeof key === 'string' && typeof val.value === 'string') {
+                            map[key.toLowerCase().trim()] = val.value;
+                        }
+                    });
+                }
+            }
+        });
+        connection.serverInfo = map;
+        response.next();
+        return map;
+    }
+    catch (err) {
+        connection.log.warn({ err, cid: connection.id });
+        return false;
+    }
+}
+/**
+ * Formats a client info value for the ID command.
+ *
+ * @param key - The info key name
+ * @param value - The value to format
+ * @returns Formatted value string
+ */
+function formatValue(key, value) {
+    switch (key.toLowerCase()) {
+        case 'date':
+            // RFC 2971 requires the "date" field to use IMAP date-time format
+            // (e.g., "06-Feb-2026 12:00:00 +0000"), not ISO 8601 or other formats.
+            return (0, tools_js_1.formatDateTime)(value);
+        default:
+            // Other values are strings without newlines
+            return (value || '').toString().replace(/\s+/g, ' ');
+    }
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/idle.d.ts

@@ -0,0 +1,9 @@
+import type { ImapFlow } from '../imap-flow.js';
+/**
+ * Listens for changes in the selected mailbox using IDLE or NOOP polling fallback.
+ *
+ * @param connection - IMAP connection instance
+ * @param maxIdleTime - Maximum time in milliseconds to stay in IDLE before restarting
+ * @returns Void on success, false on failure, or undefined if not in SELECTED state
+ */
+export default function idle(connection: ImapFlow, maxIdleTime?: number | false | undefined): Promise<void | false | undefined>;