imapflow 1.7.8 → 2.0.0

package/dist/cjs/commands/move.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = move;
+const tools_js_1 = require("../tools.js");
+const copyuid_parser_js_1 = require("./copyuid-parser.js");
+/**
+ * Moves messages from the current mailbox to another mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param range - Message sequence number or UID range
+ * @param destination - Destination mailbox path
+ * @param options - Move options
+ * @param options.uid - If true, use UID MOVE instead of MOVE
+ * @returns Move result with UID mapping if available, false on failure, or undefined if preconditions not met
+ */
+async function move(connection, range, destination, options) {
+    if (connection.state !== connection.states.SELECTED || !range || !destination) {
+        // nothing to do here
+        return;
+    }
+    options = options || {};
+    destination = (0, tools_js_1.normalizePath)(connection, destination);
+    let attributes = [
+        { type: 'SEQUENCE', value: range },
+        { type: 'ATOM', value: (0, tools_js_1.encodePath)(connection, destination) }
+    ];
+    let map = { path: connection.mailbox.path, destination };
+    // Fallback for servers without the MOVE extension (RFC 6851):
+    // emulate MOVE using COPY + flag as \Deleted + EXPUNGE.
+    if (!(0, tools_js_1.hasCapability)(connection, 'MOVE')) {
+        let result = await connection.messageCopy(range, destination, options);
+        await connection.messageDelete(range, Object.assign({ silent: true }, options));
+        return result;
+    }
+    let response;
+    try {
+        // Some servers send COPYUID in an untagged OK before the tagged response,
+        // others include it in the tagged OK. We check both to be safe.
+        response = await connection.exec(options.uid ? 'UID MOVE' : 'MOVE', attributes, {
+            untagged: {
+                OK: async (untagged) => {
+                    (0, copyuid_parser_js_1.parseCopyUid)(untagged, map);
+                }
+            }
+        });
+        response.next();
+        (0, copyuid_parser_js_1.parseCopyUid)(response.response, map);
+        return map;
+    }
+    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/namespace.d.ts

@@ -0,0 +1,25 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { NamespaceObject } from '../types.js';
+/**
+ * Returned instead of a namespace when the NAMESPACE command failed
+ */
+export interface NamespaceErrorResult {
+    error: true;
+    status: string | undefined;
+    text: string | undefined;
+}
+/**
+ * Prefix and delimiter derived from `LIST "" ""`
+ */
+export interface ListPrefixInfo {
+    flags?: Set<string> | undefined;
+    delimiter?: string | null | undefined;
+    prefix?: string | undefined;
+}
+/**
+ * Requests NAMESPACE info from the server.
+ *
+ * @param connection - IMAP connection instance
+ * @returns The primary personal namespace, or an error object on failure
+ */
+export default function namespace(connection: ImapFlow): Promise<NamespaceObject | NamespaceErrorResult | undefined>;

package/dist/cjs/commands/namespace.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = namespace;
+const tools_js_1 = require("../tools.js");
+/**
+ * Requests NAMESPACE info from the server.
+ *
+ * @param connection - IMAP connection instance
+ * @returns The primary personal namespace, or an error object on failure
+ */
+async function namespace(connection) {
+    if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
+        // nothing to do here
+        return;
+    }
+    if (!(0, tools_js_1.hasCapability)(connection, 'NAMESPACE')) {
+        // Fallback: when the server does not support the NAMESPACE extension (RFC 2342),
+        // derive the prefix and delimiter from a LIST "" "" command, which returns
+        // the hierarchy delimiter and root name for the default mailbox hierarchy.
+        let { prefix, delimiter } = await getListPrefix(connection);
+        // Ensure the prefix ends with the delimiter so that appending a mailbox name
+        // produces a valid path (e.g., "INBOX." + "Sent" = "INBOX.Sent").
+        if (delimiter && prefix && prefix.charAt(prefix.length - 1) !== delimiter) {
+            prefix += delimiter;
+        }
+        let map = {
+            personal: [{ prefix: prefix || '', delimiter }],
+            other: false,
+            shared: false
+        };
+        connection.namespaces = map;
+        connection.namespace = connection.namespaces.personal[0];
+        return connection.namespace;
+    }
+    let response;
+    try {
+        let map = {};
+        response = await connection.exec('NAMESPACE', false, {
+            untagged: {
+                // The NAMESPACE response (RFC 2342) contains exactly three sections:
+                //   [0] = personal namespaces (user's own mailboxes)
+                //   [1] = other users' namespaces (shared by other users)
+                //   [2] = shared namespaces (public/organizational folders)
+                // Each section is either NIL or a list of (prefix, delimiter) pairs.
+                NAMESPACE: async (untagged) => {
+                    if (!untagged.attributes || !untagged.attributes.length) {
+                        return;
+                    }
+                    map.personal = getNamsepaceInfo(untagged.attributes[0]);
+                    map.other = getNamsepaceInfo(untagged.attributes[1]);
+                    map.shared = getNamsepaceInfo(untagged.attributes[2]);
+                }
+            }
+        });
+        connection.namespaces = map;
+        // make sure that we have the first personal namespace always set
+        if (!connection.namespaces.personal[0]) {
+            connection.namespaces.personal[0] = { prefix: '', delimiter: '.' };
+        }
+        connection.namespaces.personal[0].prefix = connection.namespaces.personal[0].prefix || '';
+        response.next();
+        connection.namespace = connection.namespaces.personal[0];
+        return connection.namespace;
+    }
+    catch (err) {
+        connection.log.warn({ err, cid: connection.id });
+        return {
+            error: true,
+            status: err.responseStatus,
+            text: err.responseText
+        };
+    }
+}
+/**
+ * Derives namespace prefix and delimiter from a LIST command when NAMESPACE is not supported.
+ *
+ * @param connection - IMAP connection instance
+ * @returns Object with prefix, delimiter, and flags, or empty object on failure
+ */
+async function getListPrefix(connection) {
+    let response;
+    try {
+        let map = {};
+        // LIST "" "" is a special form that returns only the hierarchy delimiter
+        // and the root name, without listing any actual mailboxes.
+        response = await connection.exec('LIST', ['', ''], {
+            untagged: {
+                LIST: async (untagged) => {
+                    if (!untagged.attributes || !untagged.attributes.length) {
+                        return;
+                    }
+                    map.flags = new Set((0, tools_js_1.getStringList)(untagged.attributes[0]));
+                    map.delimiter = (untagged.attributes[1] && untagged.attributes[1].value);
+                    map.prefix = ((untagged.attributes[2] && untagged.attributes[2].value) || '');
+                    if (map.delimiter && map.prefix.charAt(0) === map.delimiter) {
+                        map.prefix = map.prefix.slice(1);
+                    }
+                }
+            }
+        });
+        response.next();
+        return map;
+    }
+    catch (err) {
+        connection.log.warn({ err, cid: connection.id });
+        return {};
+    }
+}
+/**
+ * Parses namespace information from an IMAP NAMESPACE response attribute.
+ *
+ * @param attribute - Namespace attribute array from the server response
+ * @returns Array of namespace entries, or false if empty
+ */
+function getNamsepaceInfo(attribute) {
+    if (!attribute || !Array.isArray(attribute) || !attribute.length) {
+        return false;
+    }
+    return attribute
+        .filter(entry => {
+        let pair = entry;
+        // RFC 2342 section 5 allows the delimiter to be NIL when the namespace has
+        // no hierarchy. The token parser emits a literal `null` for NIL.
+        return pair.length >= 2 && pair[0] && typeof pair[0].value === 'string' && (pair[1] === null || (pair[1] && typeof pair[1].value === 'string'));
+    })
+        .map(entry => {
+        let pair = entry;
+        let prefix = pair[0].value;
+        let delimiter = pair[1] === null ? null : pair[1].value;
+        // Append the delimiter to the prefix if it doesn't already end with one,
+        // so callers can construct full paths by simply concatenating prefix + name.
+        if (delimiter && prefix && prefix.charAt(prefix.length - 1) !== delimiter) {
+            prefix += delimiter;
+        }
+        return { prefix, delimiter };
+    });
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

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

@@ -0,0 +1,8 @@
+import type { ImapFlow } from '../imap-flow.js';
+/**
+ * Sends a NOOP command to the server.
+ *
+ * @param connection - IMAP connection instance
+ * @returns True on success, false on failure
+ */
+export default function noop(connection: ImapFlow): Promise<boolean>;

package/dist/cjs/commands/noop.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = noop;
+/**
+ * Sends a NOOP command to the server.
+ *
+ * @param connection - IMAP connection instance
+ * @returns True on success, false on failure
+ */
+async function noop(connection) {
+    try {
+        let response = await connection.exec('NOOP', false, { comment: 'Requested by command' });
+        response.next();
+        return true;
+    }
+    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/quota.d.ts

@@ -0,0 +1,10 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { QuotaResponse } from '../types.js';
+/**
+ * Requests quota information for a mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to query quota for
+ * @returns Quota information object, false if QUOTA not supported or on failure, or undefined if preconditions not met
+ */
+export default function quota(connection: ImapFlow, path: string | string[]): Promise<QuotaResponse | false | undefined>;

package/dist/cjs/commands/quota.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = quota;
+const tools_js_1 = require("../tools.js");
+/**
+ * Requests quota information for a mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to query quota for
+ * @returns Quota information object, false if QUOTA not supported or on failure, or undefined if preconditions not met
+ */
+async function quota(connection, path) {
+    if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state) || !path) {
+        // nothing to do here
+        return;
+    }
+    if (!connection.capabilities.has('QUOTA')) {
+        return false;
+    }
+    path = (0, tools_js_1.normalizePath)(connection, path);
+    let map = { path };
+    // Parse a QUOTA response. The resource list uses a repeating triplet pattern (i % 3):
+    //   position 0: resource name (e.g., "STORAGE", "MESSAGE")
+    //   position 1: current usage
+    //   position 2: limit
+    // Storage values are in KB on the wire; multiply by 1024 to report bytes.
+    let processQuotaResponse = (untagged) => {
+        let attributes = untagged.attributes && untagged.attributes[1];
+        if (!attributes || !Array.isArray(attributes) || !attributes.length) {
+            return false;
+        }
+        let key = false;
+        attributes.forEach((attribute, i) => {
+            const position = i % 3;
+            if (position === 0) {
+                key = attribute && typeof attribute.value === 'string' ? attribute.value.toLowerCase() : false;
+                return;
+            }
+            if (!key) {
+                return;
+            }
+            // isNaN() also passes '1e5', ' 12 ' and 'Infinity', none of which is a usable octet count
+            let value = (0, tools_js_1.parseUintValue)(attribute && attribute.value);
+            if (value === false) {
+                return;
+            }
+            // Resource names are server-controlled. This object is returned to the caller, so it
+            // keeps a normal prototype and unsafe names are dropped instead; the fixed fields
+            // must keep their values too.
+            if ((0, tools_js_1.isUnsafeKey)(key) || key === 'path' || key === 'quotaroot') {
+                return;
+            }
+            if (!map[key]) {
+                map[key] = {};
+            }
+            // Storage quota is reported in KB by IMAP; convert to bytes for consistency
+            const multiplier = key === 'storage' ? 1024 : 1;
+            if (position === 1) {
+                map[key].usage = value * multiplier;
+            }
+            else if (position === 2) {
+                map[key].limit = value * multiplier;
+                // Calculate usage percentage for convenient display
+                if (map[key].limit) {
+                    map[key].status = Math.round(((map[key].usage || 0) / map[key].limit) * 100) + '%';
+                }
+            }
+        });
+    };
+    let quotaFound = false;
+    let response;
+    try {
+        // Two-step quota lookup: GETQUOTAROOT identifies the quota root for a mailbox,
+        // and the server usually sends the QUOTA response inline. Some servers only
+        // send the root name and require a separate GETQUOTA command.
+        response = await connection.exec('GETQUOTAROOT', [{ type: 'ATOM', value: (0, tools_js_1.encodePath)(connection, path) }], {
+            untagged: {
+                // QUOTAROOT response tells us which quota root applies to this mailbox.
+                // A mailbox may have zero or one quota root.
+                QUOTAROOT: async (untagged) => {
+                    let quotaRoot = untagged.attributes && untagged.attributes[1] && typeof untagged.attributes[1].value === 'string'
+                        ? untagged.attributes[1].value
+                        : false;
+                    if (quotaRoot) {
+                        map.quotaRoot = quotaRoot;
+                    }
+                },
+                // QUOTA response provides the actual resource usage and limits
+                QUOTA: async (untagged) => {
+                    quotaFound = true;
+                    processQuotaResponse(untagged);
+                }
+            }
+        });
+        response.next();
+        // Fallback: if we got a quota root but no QUOTA response inline,
+        // explicitly request quota for that root.
+        if (map.quotaRoot && !quotaFound) {
+            response = await connection.exec('GETQUOTA', [{ type: 'ATOM', value: map.quotaRoot }], {
+                untagged: {
+                    QUOTA: async (untagged) => {
+                        processQuotaResponse(untagged);
+                    }
+                }
+            });
+            // Release the parser: without this the connection stalls, because the reader loop
+            // waits for the response to be handed back before parsing any further input.
+            response.next();
+        }
+        return map;
+    }
+    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/rename.d.ts

@@ -0,0 +1,12 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { MailboxRenameResponse } from '../types.js';
+/**
+ * Renames an existing mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Current mailbox path
+ * @param newPath - New mailbox path
+ * @returns Object with old and new paths, or undefined if preconditions not met
+ * @throws If the RENAME command fails
+ */
+export default function rename(connection: ImapFlow, path: string | string[], newPath: string | string[]): Promise<MailboxRenameResponse | undefined>;

package/dist/cjs/commands/rename.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = rename;
+const tools_js_1 = require("../tools.js");
+/**
+ * Renames an existing mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Current mailbox path
+ * @param newPath - New mailbox path
+ * @returns Object with old and new paths, or undefined if preconditions not met
+ * @throws If the RENAME command fails
+ */
+async function rename(connection, path, newPath) {
+    if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
+        // nothing to do here
+        return;
+    }
+    // Normalize both paths (resolve special names, apply namespace prefix) and encode
+    // them for the IMAP wire format (modified UTF-7 for non-ASCII characters).
+    path = (0, tools_js_1.normalizePath)(connection, path);
+    newPath = (0, tools_js_1.normalizePath)(connection, newPath);
+    // Must close/deselect the mailbox before renaming if it's currently selected,
+    // as IMAP servers will not rename an active mailbox.
+    if (connection.state === connection.states.SELECTED && connection.mailbox.path === path) {
+        await connection.run('CLOSE');
+    }
+    let response;
+    try {
+        let map = {
+            path,
+            newPath
+        };
+        response = await connection.exec('RENAME', [
+            { type: 'ATOM', value: (0, tools_js_1.encodePath)(connection, path) },
+            { type: 'ATOM', value: (0, tools_js_1.encodePath)(connection, newPath) }
+        ]);
+        response.next();
+        return map;
+    }
+    catch (err) {
+        await (0, tools_js_1.enhanceCommandError)(err);
+        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/search.d.ts

@@ -0,0 +1,15 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { ESearchResult, SearchObject, SearchOptions } from '../types.js';
+/**
+ * Searches for messages matching the specified criteria.
+ *
+ * @param connection - IMAP connection instance
+ * @param query - Search query object, or true/empty object to match all messages
+ * @param options - Search options
+ * @param options.uid - If true, use UID SEARCH instead of SEARCH
+ * @param options.returnOptions - ESEARCH RETURN options. When present AND the
+ *   server advertises ESEARCH capability, triggers ESEARCH and returns an ESearchResult.
+ *   Items are strings ('MIN','MAX','COUNT','ALL') or objects ({ partial: '1:100' }).
+ *   When server lacks ESEARCH, falls back to plain SEARCH and returns number[].
+ */
+export default function search(connection: ImapFlow, query: SearchObject | boolean | null | undefined, options?: SearchOptions | undefined): Promise<number[] | ESearchResult | false>;