imapflow 1.7.8 → 2.0.0

package/dist/esm/commands/move.d.ts

@@ -0,0 +1,13 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { CopyResponseObject, MessageRangeOptions } from '../types.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
+ */
+export default function move(connection: ImapFlow, range: string, destination: string | string[], options?: MessageRangeOptions | undefined): Promise<CopyResponseObject | false | undefined>;

package/{lib → dist/esm}/commands/move.js

@@ -1,34 +1,27 @@
-'use strict';
-
-const { normalizePath, encodePath, enhanceCommandError, hasCapability } = require('../tools.js');
-const { parseCopyUid } = require('./copyuid-parser.js');
-
+import { normalizePath, encodePath, enhanceCommandError, hasCapability } from '../tools.js';
+import { parseCopyUid } from './copyuid-parser.js';
 /**
  * Moves messages from the current mailbox to another mailbox.
  *
- * @param {Object} connection - IMAP connection instance
- * @param {string} range - Message sequence number or UID range
- * @param {string} destination - Destination mailbox path
- * @param {Object} [options] - Move options
- * @param {boolean} [options.uid] - If true, use UID MOVE instead of MOVE
- * @returns {Promise<{path: string, destination: string, uidValidity?: BigInt, uidMap?: Map}|boolean|undefined>} Move result with UID mapping if available, false on failure, or undefined if preconditions not met
+ * @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
  */
-module.exports = async (connection, range, destination, options) => {
+export default async function move(connection, range, destination, options) {
     if (connection.state !== connection.states.SELECTED || !range || !destination) {
         // nothing to do here
         return;
     }
-
     options = options || {};
     destination = normalizePath(connection, destination);
-
     let attributes = [
         { type: 'SEQUENCE', value: range },
         { type: 'ATOM', value: 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 (!hasCapability(connection, 'MOVE')) {
@@ -36,25 +29,24 @@ module.exports = async (connection, 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 => {
+                OK: async (untagged) => {
                     parseCopyUid(untagged, map);
                 }
             }
         });
         response.next();
-
         parseCopyUid(response.response, map);
         return map;
-    } catch (err) {
+    }
+    catch (err) {
         await enhanceCommandError(err);
         connection.log.warn({ err, cid: connection.id });
         return false;
     }
-};
+}

package/dist/esm/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/{lib → dist/esm}/commands/namespace.js

@@ -1,19 +1,15 @@
-'use strict';
-
-const { hasCapability, getStringList } = require('../tools.js');
-
+import { hasCapability, getStringList } from '../tools.js';
 /**
  * Requests NAMESPACE info from the server.
  *
- * @param {Object} connection - IMAP connection instance
- * @returns {Promise<{prefix: string, delimiter: string|null}|{error: boolean, status: string, text: string}>} The primary personal namespace, or an error object on failure
+ * @param connection - IMAP connection instance
+ * @returns The primary personal namespace, or an error object on failure
  */
-module.exports = async connection => {
+export default async function namespace(connection) {
     if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
         // nothing to do here
         return;
     }
-
     if (!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
@@ -33,7 +29,6 @@ module.exports = async connection => {
         connection.namespace = connection.namespaces.personal[0];
         return connection.namespace;
     }
-
     let response;
     try {
         let map = {};
@@ -44,7 +39,7 @@ module.exports = async connection => {
                 //   [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 => {
+                NAMESPACE: async (untagged) => {
                     if (!untagged.attributes || !untagged.attributes.length) {
                         return;
                     }
@@ -55,18 +50,16 @@ module.exports = async connection => {
             }
         });
         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) {
+    }
+    catch (err) {
         connection.log.warn({ err, cid: connection.id });
         return {
             error: true,
@@ -74,13 +67,12 @@ module.exports = async connection => {
             text: err.responseText
         };
     }
-};
-
+}
 /**
  * Derives namespace prefix and delimiter from a LIST command when NAMESPACE is not supported.
  *
- * @param {Object} connection - IMAP connection instance
- * @returns {Promise<{prefix?: string, delimiter?: string, flags?: Set}>} Object with prefix, delimiter, and flags, or empty object on failure
+ * @param connection - IMAP connection instance
+ * @returns Object with prefix, delimiter, and flags, or empty object on failure
  */
 async function getListPrefix(connection) {
     let response;
@@ -90,14 +82,13 @@ async function getListPrefix(connection) {
         // and the root name, without listing any actual mailboxes.
         response = await connection.exec('LIST', ['', ''], {
             untagged: {
-                LIST: async untagged => {
+                LIST: async (untagged) => {
                     if (!untagged.attributes || !untagged.attributes.length) {
                         return;
                     }
-
                     map.flags = new Set(getStringList(untagged.attributes[0]));
-                    map.delimiter = untagged.attributes[1] && untagged.attributes[1].value;
-                    map.prefix = (untagged.attributes[2] && untagged.attributes[2].value) || '';
+                    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);
                     }
@@ -106,39 +97,38 @@ async function getListPrefix(connection) {
         });
         response.next();
         return map;
-    } catch (err) {
+    }
+    catch (err) {
         connection.log.warn({ err, cid: connection.id });
         return {};
     }
 }
-
 /**
  * Parses namespace information from an IMAP NAMESPACE response attribute.
  *
- * @param {Array} attribute - Namespace attribute array from the server response
- * @returns {Array<{prefix: string, delimiter: string|null}>|boolean} Array of namespace entries, or false if empty
+ * @param attribute - Namespace attribute array from the server response
+ * @returns Array of namespace entries, or false if empty
  */
 function getNamsepaceInfo(attribute) {
-    if (!attribute || !attribute.length) {
+    if (!attribute || !Array.isArray(attribute) || !attribute.length) {
         return false;
     }
-
     return attribute
-        .filter(
-            entry =>
-                // RFC 2342 §5 allows the delimiter to be NIL when the namespace has
-                // no hierarchy. The token parser emits a literal `null` for NIL.
-                entry.length >= 2 && entry[0] && typeof entry[0].value === 'string' && (entry[1] === null || (entry[1] && typeof entry[1].value === 'string'))
-        )
+        .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 prefix = entry[0].value;
-            let delimiter = entry[1] === null ? null : entry[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 };
-        });
+        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 };
+    });
 }

package/dist/esm/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/{lib → dist/esm}/commands/noop.js

@@ -1,18 +1,17 @@
-'use strict';
-
 /**
  * Sends a NOOP command to the server.
  *
- * @param {Object} connection - IMAP connection instance
- * @returns {Promise<boolean>} True on success, false on failure
+ * @param connection - IMAP connection instance
+ * @returns True on success, false on failure
  */
-module.exports = async connection => {
+export default async function noop(connection) {
     try {
         let response = await connection.exec('NOOP', false, { comment: 'Requested by command' });
         response.next();
         return true;
-    } catch (err) {
+    }
+    catch (err) {
         connection.log.warn({ err, cid: connection.id });
         return false;
     }
-};
+}

package/dist/esm/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/{lib → dist/esm}/commands/quota.js

@@ -1,75 +1,61 @@
-'use strict';
-
-const { encodePath, normalizePath, enhanceCommandError, parseUintValue, isUnsafeKey } = require('../tools.js');
-
+import { encodePath, normalizePath, enhanceCommandError, parseUintValue, isUnsafeKey } from '../tools.js';
 /**
  * Requests quota information for a mailbox.
  *
- * @param {Object} connection - IMAP connection instance
- * @param {string} path - Mailbox path to query quota for
- * @returns {Promise<{path: string, quotaRoot?: string, storage?: {usage: number, limit: number, status: string}, message?: {usage: number, limit: number, status: string}}|boolean|undefined>} Quota information object, false if QUOTA not supported or on failure, or undefined if preconditions not met
+ * @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
  */
-module.exports = async (connection, path) => {
+export default 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 = 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 processQuotaResponse = (untagged) => {
         let attributes = untagged.attributes && untagged.attributes[1];
-        if (!attributes || !attributes.length) {
+        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 = 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 (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) {
+            }
+            else if (position === 2) {
                 map[key].limit = value * multiplier;
                 // Calculate usage percentage for convenient display
                 if (map[key].limit) {
@@ -78,7 +64,6 @@ module.exports = async (connection, path) => {
             }
         });
     };
-
     let quotaFound = false;
     let response;
     try {
@@ -89,31 +74,28 @@ module.exports = async (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;
+                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 => {
+                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 => {
+                    QUOTA: async (untagged) => {
                         processQuotaResponse(untagged);
                     }
                 }
@@ -122,11 +104,11 @@ module.exports = async (connection, path) => {
             // waits for the response to be handed back before parsing any further input.
             response.next();
         }
-
         return map;
-    } catch (err) {
+    }
+    catch (err) {
         await enhanceCommandError(err);
         connection.log.warn({ err, cid: connection.id });
         return false;
     }
-};
+}

package/dist/esm/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/{lib → dist/esm}/commands/rename.js

@@ -1,33 +1,27 @@
-'use strict';
-
-const { encodePath, normalizePath, enhanceCommandError } = require('../tools.js');
-
+import { encodePath, normalizePath, enhanceCommandError } from '../tools.js';
 /**
  * Renames an existing mailbox.
  *
- * @param {Object} connection - IMAP connection instance
- * @param {string} path - Current mailbox path
- * @param {string} newPath - New mailbox path
- * @returns {Promise<{path: string, newPath: string}|undefined>} Object with old and new paths, or undefined if preconditions not met
- * @throws {Error} If the RENAME command fails
+ * @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
  */
-module.exports = async (connection, path, newPath) => {
+export default 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 = normalizePath(connection, path);
     newPath = 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 = {
@@ -40,9 +34,10 @@ module.exports = async (connection, path, newPath) => {
         ]);
         response.next();
         return map;
-    } catch (err) {
+    }
+    catch (err) {
         await enhanceCommandError(err);
         connection.log.warn({ err, cid: connection.id });
         throw err;
     }
-};
+}

package/dist/esm/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>;