imapflow 1.7.8 → 2.0.0

package/dist/cjs/commands/status.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = status;
+const tools_js_1 = require("../tools.js");
+const status_fields_js_1 = require("./status-fields.js");
+// STATUS fields that also refresh the live mailbox state when the queried mailbox is the
+// currently selected one. Keyed by the output property name parseStatusList() reports.
+const MAILBOX_UPDATERS = {
+    messages: (value, connection, path) => {
+        let mailbox = connection.mailbox;
+        let prevCount = mailbox.exists;
+        if (prevCount !== value) {
+            mailbox.exists = value;
+            connection.emit('exists', { path, count: value, prevCount });
+        }
+    },
+    uidNext: (value, connection) => {
+        connection.mailbox.uidNext = value;
+    },
+    highestModseq: (value, connection) => {
+        connection.mailbox.highestModseq = value;
+    }
+};
+/**
+ * Requests status information about a mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to query
+ * @param query - Status data items to request (e.g., {messages: true, uidNext: true, unseen: true})
+ * @returns Status information object, or false if preconditions not met or on failure
+ * @throws {Error} If the mailbox does not exist
+ */
+async function status(connection, path, query) {
+    if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state) || !path) {
+        // nothing to do here
+        return false;
+    }
+    path = (0, tools_js_1.normalizePath)(connection, path);
+    let encodedPath = (0, tools_js_1.encodePath)(connection, path);
+    // Use quoted STRING if the encoded path contains '&' (modified UTF-7 marker),
+    // otherwise use unquoted ATOM. Same approach as in SELECT.
+    let attributes = [{ type: encodedPath.indexOf('&') >= 0 ? 'STRING' : 'ATOM', value: encodedPath }];
+    // Build the list of STATUS data items the caller wants
+    let queryAttributes = (0, tools_js_1.buildStatusQueryAttributes)(connection, query);
+    // RECENT does not exist in IMAP4rev2 so it is never requested from a rev2
+    // session; its defined value there is always 0. Synthesizing it keeps the
+    // return shape identical to a rev1 session for the same query.
+    let syntheticRecent = query && query.recent && (0, tools_js_1.isRev2Active)(connection);
+    if (!queryAttributes.length) {
+        // A query that only contained items unavailable on this session - the
+        // caller still gets a status object if every such item has a defined value
+        return syntheticRecent ? { path, recent: 0 } : false;
+    }
+    attributes.push(queryAttributes);
+    let response;
+    try {
+        let map = { path };
+        response = await connection.exec('STATUS', attributes, {
+            untagged: {
+                // STATUS response: * STATUS <mailbox> (<key> <value> <key> <value> ...)
+                // Parsed as alternating key-value pairs (i % 2 pattern).
+                STATUS: async (untagged) => {
+                    // If querying the currently selected mailbox, also update the
+                    // connection's live mailbox state and emit events for changes.
+                    let updateCurrent = connection.state === connection.states.SELECTED && path === connection.mailbox.path;
+                    let list = untagged.attributes && Array.isArray(untagged.attributes[1]) ? untagged.attributes[1] : false;
+                    if (!list) {
+                        return;
+                    }
+                    (0, status_fields_js_1.parseStatusList)(list, (key, value) => {
+                        map[key] = value;
+                        let updater = MAILBOX_UPDATERS[key];
+                        if (updateCurrent && updater) {
+                            updater(value, connection, path);
+                        }
+                    });
+                }
+            }
+        });
+        response.next();
+        if (syntheticRecent) {
+            map.recent = 0;
+        }
+        return map;
+    }
+    catch (err) {
+        // A NO response usually means the mailbox doesn't exist. Verify by
+        // running LIST: if no results, throw a clear NotFound error instead
+        // of the generic IMAP error.
+        // Note: this uses run(), so when STATUS was dispatched by fallback polling through
+        // runInternal() the LIST awaits that polling session's own preCheck and cancels it.
+        // Not a deadlock, and only reachable when the server rejects the STATUS, but a polled
+        // STATUS of a missing folder ends the poll early.
+        if (err.responseStatus === 'NO') {
+            let folders = await connection.run('LIST', '', path, { listOnly: true });
+            if (folders && !folders.length) {
+                let error = new Error(`Mailbox doesn't exist: ${path}`);
+                error.code = 'NotFound';
+                error.response = err;
+                throw error;
+            }
+        }
+        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/store.d.ts

@@ -0,0 +1,19 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { StoreOptions } from '../types.js';
+/**
+ * Options for the STORE command
+ */
+export interface StoreCommandOptions extends StoreOptions {
+    /** Operation type: 'set', 'add', or 'remove' */
+    operation?: string | undefined;
+}
+/**
+ * Updates flags or labels for messages in the selected mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param range - Message sequence number or UID range
+ * @param flags - Flag(s) to set, add, or remove
+ * @param options - Store options
+ * @returns True on success, false on failure or if nothing to do
+ */
+export default function store(connection: ImapFlow, range: string, flags: string | string[], options: StoreCommandOptions): Promise<boolean>;

package/dist/cjs/commands/store.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = store;
+const tools_js_1 = require("../tools.js");
+/**
+ * Updates flags or labels for messages in the selected mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param range - Message sequence number or UID range
+ * @param flags - Flag(s) to set, add, or remove
+ * @param options - Store options
+ * @returns True on success, false on failure or if nothing to do
+ */
+async function store(connection, range, flags, options) {
+    if (connection.state !== connection.states.SELECTED || !range || (options.useLabels && !connection.capabilities.has('X-GM-EXT-1'))) {
+        // nothing to do here
+        return false;
+    }
+    /* c8 ignore next */ // options.useLabels is dereferenced in the guard above, so options is always defined here
+    options = options || {};
+    // Build the IMAP STORE operation name. The format is:
+    //   [+|-]FLAGS[.SILENT] or [+|-]X-GM-LABELS
+    // Where: no prefix = replace all, + = add, - = remove
+    // .SILENT suppresses the server from sending back updated flags (saves bandwidth).
+    let operation = 'FLAGS';
+    if (options.useLabels) {
+        // Gmail labels (X-GM-EXT-1 extension): operates on labels instead of IMAP flags
+        operation = 'X-GM-LABELS';
+    }
+    else if (options.silent) {
+        operation = `${operation}.SILENT`;
+    }
+    // Prefix determines the operation: none = set (replace), + = add, - = remove
+    switch ((options.operation || '').toLowerCase()) {
+        case 'set':
+            break;
+        case 'remove':
+            operation = `-${operation}`;
+            break;
+        case 'add':
+        default:
+            operation = `+${operation}`;
+            break;
+    }
+    // Validate each flag: format it (normalize backslash prefix for system flags),
+    // then check if the mailbox's permanentFlags allow it. Removal is always allowed
+    // since it doesn't require the flag to be in permanentFlags.
+    flags = (Array.isArray(flags) ? flags : [].concat(flags || []))
+        .map(flag => {
+        let formatted = (0, tools_js_1.formatFlag)(flag);
+        if (!(0, tools_js_1.canUseFlag)(connection.mailbox, formatted) && options.operation !== 'remove') {
+            return false;
+        }
+        return formatted;
+    })
+        .filter((flag) => !!flag);
+    // Allow empty flags only for 'set' operation (which clears all flags)
+    if (!flags.length && options.operation !== 'set') {
+        return false;
+    }
+    let attributes = [
+        { type: 'SEQUENCE', value: range },
+        { type: 'ATOM', value: operation },
+        flags.map(flag => ({ type: 'ATOM', value: flag }))
+    ];
+    // CONDSTORE (RFC 7162): UNCHANGEDSINCE modifier prevents updating messages whose
+    // mod-sequence is higher than the specified value, avoiding overwriting concurrent changes.
+    if (options.unchangedSince && connection.enabled.has('CONDSTORE') && !connection.mailbox.noModseq) {
+        attributes.push([
+            {
+                type: 'ATOM',
+                value: 'UNCHANGEDSINCE'
+            },
+            {
+                type: 'ATOM',
+                value: options.unchangedSince.toString()
+            }
+        ]);
+    }
+    let response;
+    try {
+        response = await connection.exec(options.uid ? 'UID STORE' : 'STORE', attributes);
+        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/subscribe.d.ts

@@ -0,0 +1,9 @@
+import type { ImapFlow } from '../imap-flow.js';
+/**
+ * Subscribes to a mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to subscribe to
+ * @returns True on success, false on failure, or undefined if preconditions not met
+ */
+export default function subscribe(connection: ImapFlow, path: string | string[]): Promise<boolean | undefined>;

package/dist/cjs/commands/subscribe.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = subscribe;
+const tools_js_1 = require("../tools.js");
+/**
+ * Subscribes to a mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to subscribe to
+ * @returns True on success, false on failure, or undefined if preconditions not met
+ */
+async function subscribe(connection, path) {
+    if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
+        // nothing to do here
+        return;
+    }
+    path = (0, tools_js_1.normalizePath)(connection, path);
+    let response;
+    try {
+        response = await connection.exec('SUBSCRIBE', [{ type: 'ATOM', value: (0, tools_js_1.encodePath)(connection, path) }]);
+        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/unsubscribe.d.ts

@@ -0,0 +1,9 @@
+import type { ImapFlow } from '../imap-flow.js';
+/**
+ * Unsubscribes from a mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to unsubscribe from
+ * @returns True on success, false on failure, or undefined if preconditions not met
+ */
+export default function unsubscribe(connection: ImapFlow, path: string | string[]): Promise<boolean | undefined>;

package/dist/cjs/commands/unsubscribe.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = unsubscribe;
+const tools_js_1 = require("../tools.js");
+/**
+ * Unsubscribes from a mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to unsubscribe from
+ * @returns True on success, false on failure, or undefined if preconditions not met
+ */
+async function unsubscribe(connection, path) {
+    if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
+        // nothing to do here
+        return;
+    }
+    path = (0, tools_js_1.normalizePath)(connection, path);
+    let response;
+    try {
+        response = await connection.exec('UNSUBSCRIBE', [{ type: 'ATOM', value: (0, tools_js_1.encodePath)(connection, path) }]);
+        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/connection-deadline.d.ts

@@ -0,0 +1,49 @@
+import type { ImapFlowError } from './errors.js';
+export declare const CONNECT_TIMEOUT: number;
+/**
+ * One deadline for an entire connection attempt.
+ *
+ * DNS resolution, proxy negotiation and the transport handshake all draw from the same budget, so
+ * a phase that stalls cannot extend the documented `connectionTimeout`. Every expiry - whether it
+ * comes from this deadline or is normalized from a dependency - is reported with the same
+ * `CONNECT_TIMEOUT` error shape, so callers do not need to know which phase was blocked.
+ */
+export declare class ConnectionDeadline {
+    timeout: number;
+    startedAt: number;
+    /**
+     * @param timeout Configured connection timeout in milliseconds. Normalized once
+     *   here; 0 and any other falsy or invalid value fall back to the 90 second default.
+     */
+    constructor(timeout?: number | string | undefined);
+    /**
+     * @returns Milliseconds left in the budget, never negative.
+     */
+    remaining(): number;
+    /**
+     * @returns The shared `CONNECT_TIMEOUT` error.
+     */
+    error(): ImapFlowError;
+    /**
+     * Maps a dependency's own expiry onto the shared `CONNECT_TIMEOUT` shape, so callers see one
+     * timeout error whichever layer noticed first. The original error is kept as `_err`. Anything
+     * that is not a timeout is returned unchanged.
+     *
+     * @param err Error raised by a dependency during a connection phase.
+     * @returns Either the normalized timeout error or the original error.
+     */
+    normalize<T extends ImapFlowError | null | undefined>(err: T): T | ImapFlowError;
+    /**
+     * Throws before a phase is started if the budget is already used up, so no work is begun
+     * that could only ever time out.
+     */
+    check(): void;
+    /**
+     * Races a phase against the remaining budget. The timer is always cleared, so a completed
+     * phase never leaves a pending timer behind.
+     *
+     * @param promise Phase to run under the deadline.
+     * @returns Resolves with the phase result, rejects with `CONNECT_TIMEOUT`.
+     */
+    race<T>(promise: Promise<T>): Promise<T>;
+}

package/dist/cjs/connection-deadline.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionDeadline = exports.CONNECT_TIMEOUT = void 0;
+const tools_js_1 = require("./tools.js");
+// Default upper bound for establishing a usable transport, including DNS and proxy negotiation.
+exports.CONNECT_TIMEOUT = 90 * 1000;
+/**
+ * One deadline for an entire connection attempt.
+ *
+ * DNS resolution, proxy negotiation and the transport handshake all draw from the same budget, so
+ * a phase that stalls cannot extend the documented `connectionTimeout`. Every expiry - whether it
+ * comes from this deadline or is normalized from a dependency - is reported with the same
+ * `CONNECT_TIMEOUT` error shape, so callers do not need to know which phase was blocked.
+ */
+class ConnectionDeadline {
+    /**
+     * @param timeout Configured connection timeout in milliseconds. Normalized once
+     *   here; 0 and any other falsy or invalid value fall back to the 90 second default.
+     */
+    constructor(timeout) {
+        this.timeout = Number(timeout) || exports.CONNECT_TIMEOUT;
+        this.startedAt = Date.now();
+    }
+    /**
+     * @returns Milliseconds left in the budget, never negative.
+     */
+    remaining() {
+        return Math.max(0, this.timeout - (Date.now() - this.startedAt));
+    }
+    /**
+     * @returns The shared `CONNECT_TIMEOUT` error.
+     */
+    error() {
+        let err = new Error('Failed to establish connection in required time');
+        err.code = 'CONNECT_TIMEOUT';
+        err.details = { connectionTimeout: this.timeout };
+        return err;
+    }
+    /**
+     * Maps a dependency's own expiry onto the shared `CONNECT_TIMEOUT` shape, so callers see one
+     * timeout error whichever layer noticed first. The original error is kept as `_err`. Anything
+     * that is not a timeout is returned unchanged.
+     *
+     * @param err Error raised by a dependency during a connection phase.
+     * @returns Either the normalized timeout error or the original error.
+     */
+    normalize(err) {
+        if (!err || err.code === 'CONNECT_TIMEOUT') {
+            return err;
+        }
+        // The `socks` client reports its own expiry as "Proxy connection timed out"
+        if (err.code !== 'ETIMEDOUT' && !/timed out/i.test(err.message || '')) {
+            return err;
+        }
+        let normalized = this.error();
+        normalized._err = err;
+        return normalized;
+    }
+    /**
+     * Throws before a phase is started if the budget is already used up, so no work is begun
+     * that could only ever time out.
+     */
+    check() {
+        if (!this.remaining()) {
+            throw this.error();
+        }
+    }
+    /**
+     * Races a phase against the remaining budget. The timer is always cleared, so a completed
+     * phase never leaves a pending timer behind.
+     *
+     * @param promise Phase to run under the deadline.
+     * @returns Resolves with the phase result, rejects with `CONNECT_TIMEOUT`.
+     */
+    async race(promise) {
+        this.check();
+        let timer = null;
+        try {
+            return await Promise.race([
+                promise,
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => reject(this.error()), this.remaining());
+                })
+            ]);
+        }
+        finally {
+            (0, tools_js_1.clearTimer)(timer);
+        }
+    }
+}
+exports.ConnectionDeadline = ConnectionDeadline;

package/dist/cjs/errors.d.ts

@@ -0,0 +1,83 @@
+import type { ImapResponse } from './handler/types.js';
+/**
+ * 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 */
+    code?: string | undefined;
+    /** Connection id the error belongs to */
+    cid?: string | undefined;
+    /** Connection id, stamped by emitError() */
+    _connId?: string | undefined;
+    /** Which internal site rejected with this error */
+    rejectedFrom?: string | undefined;
+    /** The command that was affected */
+    command?: string | undefined;
+    /** The mailbox path that was affected */
+    path?: string | undefined;
+    /** Status of the tagged response that failed the command: 'NO' or 'BAD' */
+    responseStatus?: string | undefined;
+    /** Human readable text of the failed tagged response */
+    responseText?: string | undefined;
+    /** The server response: the parsed response, or its text once enhanceCommandError() ran */
+    response?: ImapResponse | string | false | undefined;
+    /** Response code of the failed tagged response, e.g. 'AUTHENTICATIONFAILED' */
+    serverResponseCode?: string | undefined;
+    /** The command as it was sent, for logging */
+    executedCommand?: string | undefined;
+    /** Set when authentication failed */
+    authenticationFailed?: boolean | undefined;
+    /** Set when a TLS or STARTTLS upgrade failed */
+    tlsFailed?: boolean | undefined;
+    /** Server suggested back-off in milliseconds for an ETHROTTLE error */
+    throttleReset?: number | undefined;
+    /** Additional details, e.g. the timeouts that applied */
+    details?: {
+        [key: string]: any;
+    } | undefined;
+    /** The underlying error */
+    _err?: Error | undefined;
+    /** Server BYE reason */
+    reason?: string | undefined;
+    /** Set when a mailbox could not be selected because it does not exist */
+    mailboxMissing?: boolean | undefined;
+    /** Id of the mailbox lock that timed out */
+    lockId?: number | undefined;
+    /** The parser error that failed a command completion */
+    parserError?: ImapFlowError | undefined;
+    /** Parser diagnostics */
+    parserContext?: {
+        [key: string]: any;
+    } | undefined;
+    /** The tag the parser had already read before it failed */
+    parsedTag?: string | undefined;
+    /** The declared size of a rejected literal */
+    literalSize?: number | undefined;
+    /** The length of a rejected line */
+    lineLength?: number | undefined;
+    /** The size of a rejected response */
+    responseSize?: number | undefined;
+    /** The bound that was exceeded */
+    maxSize?: number | undefined;
+    /** OAuth error details from the server, for XOAUTH2 authentication failures */
+    oauthError?: any;
+    /** The IMAP string that could not be parsed */
+    _imapStr?: string | undefined;
+}
+/**
+ * The fields a connection error is stamped with to say where it was rejected, see
+ * buildConnectionError() in tools.ts
+ */
+export type ConnectionErrorSite = Pick<ImapFlowError, 'rejectedFrom' | 'command' | 'path'>;
+/**
+ * Error subclass thrown when IMAP authentication fails.
+ */
+export declare class AuthenticationFailure extends Error implements ImapFlowError {
+    authenticationFailed: true;
+    serverResponseCode?: string | undefined;
+    /** Text of the server's error response */
+    response?: string | undefined;
+    oauthError?: any;
+}

package/dist/cjs/errors.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthenticationFailure = void 0;
+/**
+ * Error subclass thrown when IMAP authentication fails.
+ */
+class AuthenticationFailure extends Error {
+    constructor() {
+        super(...arguments);
+        this.authenticationFailed = true;
+    }
+}
+exports.AuthenticationFailure = AuthenticationFailure;

package/dist/cjs/handler/imap-compiler.d.ts

@@ -0,0 +1,24 @@
+import type { CompilerOptions, ImapCompileInput } from './types.js';
+/**
+ * Compiles an input object into a sequence of Buffers representing an IMAP protocol response string.
+ * Handles various node types including literals, strings, atoms, sections, sequences, and nested lists.
+ *
+ * @param response - The response object to compile.
+ * @param response.tag - The IMAP command tag (e.g., "*" or a sequence number).
+ * @param response.command - The IMAP command name.
+ * @param response.attributes - The response attributes to compile into IMAP format.
+ * @param options - Compilation options.
+ * @param options.asArray - If true, returns an array of Buffers (one per literal segment); otherwise returns a single concatenated Buffer.
+ * @param options.isLogging - If true, redacts sensitive values and truncates long strings/literals for logging purposes.
+ * @param options.literalPlus - If true, uses the LITERAL+ extension (appends "+" to literal length markers).
+ * @param options.literalMinus - If true, uses the LITERAL- extension for literals up to 4096 bytes.
+ * @returns A promise that resolves to an array of Buffers (if asArray is true) or a single concatenated Buffer.
+ */
+declare function compiler(response: ImapCompileInput, options: CompilerOptions & {
+    asArray: true;
+}): Promise<Buffer[]>;
+declare function compiler(response: ImapCompileInput, options?: (CompilerOptions & {
+    asArray?: false | undefined;
+}) | undefined): Promise<Buffer>;
+declare function compiler(response: ImapCompileInput, options?: CompilerOptions | undefined): Promise<Buffer | Buffer[]>;
+export default compiler;