imapflow 2.0.6 → 2.0.8

package/dist/esm/jp-decoder.js

@@ -31,7 +31,7 @@ export class JPDecoder extends Transform {
             chunk = Buffer.from(chunk, encoding);
         }
         if (this.chunklen + chunk.length > this.maxBytes) {
-            chunk = chunk.slice(0, Math.max(0, this.maxBytes - this.chunklen));
+            chunk = chunk.subarray(0, Math.max(0, this.maxBytes - this.chunklen));
         }
         if (chunk.length) {
             this.chunks.push(chunk);

package/dist/esm/package-info.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.0.6";
+export declare const version = "2.0.8";
 export declare const homepage = "https://imapflow.com/";

package/dist/esm/package-info.js

@@ -1,4 +1,4 @@
 // Generated by scripts/build.js from package.json. Do not edit by hand.
-export const name = 'imapflow';
-export const version = '2.0.6';
-export const homepage = 'https://imapflow.com/';
+export const name = "imapflow";
+export const version = "2.0.8";
+export const homepage = "https://imapflow.com/";

package/dist/esm/search-compiler.js

@@ -403,21 +403,14 @@ export const searchCompiler = (connection, query) => {
                          * @returns Binary tree structure
                          */
                         let genOrTree = (list) => {
-                            let group = false;
                             let groups = [];
                             // Group items in pairs
-                            list.forEach((entry, i) => {
-                                if (i % 2 === 0) {
-                                    group = [entry];
-                                }
-                                else {
-                                    group.push(entry);
-                                    groups.push(group);
-                                    group = false;
-                                }
-                            });
+                            for (let i = 0; i + 1 < list.length; i += 2) {
+                                groups.push([list[i], list[i + 1]]);
+                            }
                             // Handle odd number of items
-                            if (group && group.length) {
+                            if (list.length % 2) {
+                                let group = [list[list.length - 1]];
                                 while (group.length === 1 && Array.isArray(group[0])) {
                                     group = group[0];
                                 }

package/dist/esm/tools.d.ts

@@ -2,7 +2,7 @@ import type { Transform } from 'node:stream';
 import type { ImapFlow } from './imap-flow.js';
 import type { ConnectionErrorSite, ImapFlowError } from './errors.js';
 import type { ImapAttributeList, ImapAttributeNode, ImapResponse } from './handler/types.js';
-import type { FetchMessageObject, ListResponse, ListTreeResponse, MailboxObject, MessageEnvelopeObject, MessageStructureObject, StatusQuery } from './types.js';
+import type { FetchMessageObject, ListResponse, ListTreeResponse, MailboxObject, MessageEnvelopeObject, MessageStructureObject, ImapFlowEvents, StatusQuery } from './types.js';
 export { AuthenticationFailure } from './errors.js';
 export declare const EXPANDED_RANGE_LIMIT = 16777216;
 export declare const MAX_UINT32_DIGITS = 10;
@@ -80,6 +80,13 @@ export declare function guardedPromise<T>(executor: (resolve: (value: T | Promis
  * @returns Rejected promise, with its rejection already observed
  */
 export declare function guardedReject(error: Error): Promise<never>;
+/**
+ * Clears a timer that may already have been dropped. `clearTimeout()` accepts undefined but not
+ * null, and the connection nulls its timer fields once cleared, so every site clears through here.
+ *
+ * @param timer - Timer handle returned by setTimeout, or null/undefined when none is armed
+ */
+export declare function clearTimer(timer: NodeJS.Timeout | null | undefined): void;
 /**
  * Detaches a background timer from the event loop, so it cannot keep the process alive on its
  * own. Applied to every background timer (auto-IDLE, IDLE restart, fallback polling, throttle
@@ -89,13 +96,6 @@ export declare function guardedReject(error: Error): Promise<never>;
  * @param timer - Timer handle returned by setTimeout
  * @returns The same timer handle
  */
-/**
- * Clears a timer that may already have been dropped. `clearTimeout()` accepts undefined but not
- * null, and the connection nulls its timer fields once cleared, so every site clears through here.
- *
- * @param timer - Timer handle returned by setTimeout, or null/undefined when none is armed
- */
-export declare function clearTimer(timer: NodeJS.Timeout | null | undefined): void;
 export declare function unrefTimer<T extends NodeJS.Timeout | null | undefined>(timer: T): T;
 /**
  * Logs a failure from background connection work at the level its cause deserves.
@@ -200,6 +200,25 @@ export declare function updateCapabilities(list: ImapAttributeList | null | unde
  * @returns Uppercase status code string, or false if not found
  */
 export declare function getStatusCode(response: ImapResponse | string | false | undefined): string | false;
+/**
+ * Emits a state-change event from inside the command pipeline. A listener that throws must not
+ * abort the code that emitted it: select() emits before it releases the response, so the throw
+ * would leave the reader loop waiting forever, and close() would never get to emit 'close'. The
+ * error is logged instead, the same contract untagged handlers and the 'response' event get.
+ *
+ * @param connection - IMAP connection instance
+ * @param event - Event name
+ * @param args - Event arguments
+ */
+export declare function emitSafe<K extends keyof ImapFlowEvents>(connection: ImapFlow, event: K, ...args: ImapFlowEvents[K]): void;
+/**
+ * Collects the values of the TEXT tokens of a parsed response (the human-readable
+ * part of a status response, a greeting or a BYE).
+ *
+ * @param attributes - Attributes of a parsed IMAP response
+ * @returns Values of the TEXT tokens, in order
+ */
+export declare function getTextValues(attributes: ImapAttributeList | undefined): string[];
 /**
  * Compiles an IMAP response object back into a human-readable string.
  *
@@ -214,6 +233,28 @@ export declare function getErrorText(response: ImapResponse | string | false | u
  * @returns The enhanced error with `serverResponseCode` and string `response`
  */
 export declare function enhanceCommandError(err: ImapFlowError): Promise<ImapFlowError>;
+/**
+ * Enhances a failed command's error (see enhanceCommandError()) and logs it, the shared first
+ * step of every command's failure path. The caller decides whether to throw or return.
+ *
+ * @param connection - IMAP connection instance
+ * @param err - The command error
+ */
+export declare function reportCommandError(connection: ImapFlow, err: ImapFlowError): Promise<void>;
+/**
+ * Whether the session is authenticated, that is in the AUTHENTICATED or SELECTED state, which
+ * every mailbox-level command requires.
+ *
+ * @param connection - IMAP connection instance
+ */
+export declare function isAuthenticatedState(connection: ImapFlow): boolean;
+/**
+ * Returns the selected mailbox, or false when the connection is not in the SELECTED state.
+ * Message-level commands use it as their precondition, which also narrows the mailbox type.
+ *
+ * @param connection - IMAP connection instance
+ */
+export declare function getSelectedMailbox(connection: ImapFlow): MailboxObject | false;
 /**
  * Converts a flat list of mailbox folders into a tree structure.
  *
@@ -305,14 +346,14 @@ export declare function toValidDate(value: unknown): Date | null;
  * @param value - Date to format
  * @returns Formatted date string, or undefined if invalid
  */
-export declare function formatDate(value: Date | string | null | undefined): string | undefined;
+export declare function formatDate(value: unknown): string | undefined;
 /**
  * Formats a date value into IMAP date-time format (DD-Mon-YYYY HH:MM:SS +0000).
  *
  * @param value - Date to format
  * @returns Formatted date-time string, or undefined if invalid
  */
-export declare function formatDateTime(value: Date | string | null | undefined): string | undefined;
+export declare function formatDateTime(value: unknown): string | undefined;
 /**
  * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent),
  * and capitalizes system flags properly.

package/dist/esm/tools.js

@@ -158,15 +158,6 @@ export function guardedReject(error) {
     promise.catch(noop);
     return promise;
 }
-/**
- * Detaches a background timer from the event loop, so it cannot keep the process alive on its
- * own. Applied to every background timer (auto-IDLE, IDLE restart, fallback polling, throttle
- * back-off, held-lock diagnostics); connection and greeting deadlines are deliberately left
- * attached, because a caller is waiting for connect() to settle.
- *
- * @param timer - Timer handle returned by setTimeout
- * @returns The same timer handle
- */
 /**
  * Clears a timer that may already have been dropped. `clearTimeout()` accepts undefined but not
  * null, and the connection nulls its timer fields once cleared, so every site clears through here.
@@ -178,6 +169,15 @@ export function clearTimer(timer) {
         clearTimeout(timer);
     }
 }
+/**
+ * Detaches a background timer from the event loop, so it cannot keep the process alive on its
+ * own. Applied to every background timer (auto-IDLE, IDLE restart, fallback polling, throttle
+ * back-off, held-lock diagnostics); connection and greeting deadlines are deliberately left
+ * attached, because a caller is waiting for connect() to settle.
+ *
+ * @param timer - Timer handle returned by setTimeout
+ * @returns The same timer handle
+ */
 export function unrefTimer(timer) {
     /* c8 ignore next 3 */ // node timers always expose unref(); the guard covers replaced globals in tests
     if (timer && typeof timer.unref === 'function') {
@@ -393,7 +393,7 @@ export function updateCapabilities(list) {
             }
             if (capability.startsWith('APPENDLIMIT=')) {
                 let splitPos = capability.indexOf('=');
-                map.set('APPENDLIMIT', parseUintValue(capability.substr(splitPos + 1)) || 0);
+                map.set('APPENDLIMIT', parseUintValue(capability.slice(splitPos + 1)) || 0);
                 return;
             }
             map.set(capability, true);
@@ -419,6 +419,34 @@ export function getStatusCode(response) {
         ? response.attributes[0].section[0].value.toUpperCase().trim()
         : false;
 }
+/**
+ * Emits a state-change event from inside the command pipeline. A listener that throws must not
+ * abort the code that emitted it: select() emits before it releases the response, so the throw
+ * would leave the reader loop waiting forever, and close() would never get to emit 'close'. The
+ * error is logged instead, the same contract untagged handlers and the 'response' event get.
+ *
+ * @param connection - IMAP connection instance
+ * @param event - Event name
+ * @param args - Event arguments
+ */
+export function emitSafe(connection, event, ...args) {
+    try {
+        connection.emit(event, ...args);
+    }
+    catch (err) {
+        connection.log.warn({ msg: 'Event listener failed', event, err, cid: connection.id });
+    }
+}
+/**
+ * Collects the values of the TEXT tokens of a parsed response (the human-readable
+ * part of a status response, a greeting or a BYE).
+ *
+ * @param attributes - Attributes of a parsed IMAP response
+ * @returns Values of the TEXT tokens, in order
+ */
+export function getTextValues(attributes) {
+    return (attributes || []).filter(attr => attr?.type === 'TEXT').map(attr => String(attr?.value ?? ''));
+}
 /**
  * Compiles an IMAP response object back into a human-readable string.
  *
@@ -456,6 +484,35 @@ export async function enhanceCommandError(err) {
     err.response = await getErrorText(err.response);
     return err;
 }
+/**
+ * Enhances a failed command's error (see enhanceCommandError()) and logs it, the shared first
+ * step of every command's failure path. The caller decides whether to throw or return.
+ *
+ * @param connection - IMAP connection instance
+ * @param err - The command error
+ */
+export async function reportCommandError(connection, err) {
+    await enhanceCommandError(err);
+    connection.log.warn({ err, cid: connection.id });
+}
+/**
+ * Whether the session is authenticated, that is in the AUTHENTICATED or SELECTED state, which
+ * every mailbox-level command requires.
+ *
+ * @param connection - IMAP connection instance
+ */
+export function isAuthenticatedState(connection) {
+    return connection.state === connection.states.AUTHENTICATED || connection.state === connection.states.SELECTED;
+}
+/**
+ * Returns the selected mailbox, or false when the connection is not in the SELECTED state.
+ * Message-level commands use it as their precondition, which also narrows the mailbox type.
+ *
+ * @param connection - IMAP connection instance
+ */
+export function getSelectedMailbox(connection) {
+    return connection.state === connection.states.SELECTED && connection.mailbox ? connection.mailbox : false;
+}
 /**
  * Converts a flat list of mailbox folders into a tree structure.
  *
@@ -631,6 +688,12 @@ export async function formatMessageResponse(untagged, mailbox) {
             if (Buffer.isBuffer(attribute.value)) {
                 return attribute.value;
             }
+            // A section is an nstring, so a server may answer with a quoted string
+            // instead of a literal (Yahoo does for small parts). The tokenizer decoded
+            // the line as UTF-8, so encoding the same way restores the bytes it sent.
+            if (typeof attribute.value === 'string') {
+                return Buffer.from(attribute.value);
+            }
         };
         // NIL (parsed as null) and other non-array values yield an empty array, so callers
         // can safely index into the result. RFC 8474 allows e.g. `THREADID NIL` when the
@@ -937,7 +1000,7 @@ export function getStructuredParams(arr) {
             // nothing to do here, does not seem like a continuation param
             return;
         }
-        actualKey = key.substr(0, match.index).toLowerCase();
+        actualKey = key.substring(0, match.index).toLowerCase();
         nr = Number(match[2]) || 0;
         if (isUnsafeKey(actualKey)) {
             // A continuation key like "__proto__*0*" would group under "__proto__":
@@ -1189,7 +1252,7 @@ export function formatDate(value) {
     if (!date) {
         return;
     }
-    let dateParts = date.toISOString().substr(0, 10).split('-');
+    let dateParts = date.toISOString().substring(0, 10).split('-');
     dateParts.reverse();
     let months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
     dateParts[1] = months[Number(dateParts[1]) - 1];
@@ -1207,7 +1270,7 @@ export function formatDateTime(value) {
         return;
     }
     let dateStr = formatDate(date).replace(/^0/, ' '); //starts with date-day-fixed with leading 0 replaced by SP
-    let timeStr = date.toISOString().substr(11, 8);
+    let timeStr = date.toISOString().substring(11, 19);
     return `${dateStr} ${timeStr} +0000`;
 }
 /**
@@ -1361,8 +1424,8 @@ export function expandRange(range) {
             }
             continue;
         }
-        let first = Number(entry.substr(0, colon));
-        let second = Number(entry.substr(colon + 1));
+        let first = Number(entry.substring(0, colon));
+        let second = Number(entry.slice(colon + 1));
         if (!isValidSequenceValue(first) || !isValidSequenceValue(second)) {
             continue;
         }

package/dist/esm/types.d.ts

@@ -207,26 +207,32 @@ export interface IdInfoObject {
     'support-url'?: string | false | undefined;
     /** Date program was released */
     date?: Date | string | false | undefined;
-    [key: string]: any;
+    /** Any other field, sent as its string form */
+    [key: string]: unknown;
+}
+/**
+ * Usage and limit of one quota resource. The `storage` values are bytes (the wire format is
+ * kilobytes), the other resources are counts
+ */
+export interface QuotaResource {
+    /** Current usage, missing when the server did not send a usable number */
+    usage?: number | undefined;
+    /** The limit, missing when the server did not send a usable number */
+    limit?: number | undefined;
+    /** Usage as a percentage of the limit, e.g. "50%", set once a limit above zero is known */
+    status?: string | undefined;
 }
 export interface QuotaResponse {
     /** Mailbox path this quota applies to */
     path: string;
-    /** Storage quota if provided by server */
-    storage?: {
-        /** Used storage in bytes */
-        used: number;
-        /** Total storage available */
-        limit: number;
-    } | undefined;
-    /** Message count quota if provided by server */
-    messages?: {
-        /** Stored messages */
-        used: number;
-        /** Maximum messages allowed */
-        limit: number;
-    } | undefined;
-    [resource: string]: any;
+    /** The quota root the server reported for the mailbox, if any */
+    quotaRoot?: string | undefined;
+    /** The STORAGE resource, if the server reports one */
+    storage?: QuotaResource | undefined;
+    /** The MESSAGE resource, if the server reports one */
+    message?: QuotaResource | undefined;
+    /** Any other resource the server reports, under its lowercased name (e.g. "mailbox") */
+    [resource: string]: QuotaResource | string | undefined;
 }
 /**
  * Status data items to request with `status()` or the `statusQuery` listing option
@@ -616,6 +622,14 @@ export interface DownloadObject {
     /** Streamed content */
     content: Readable;
 }
+/**
+ * What `download()` resolves with when there is nothing to download: no mailbox is selected, or
+ * the message or part was not found. Check `content` before using the result.
+ */
+export interface DownloadNotFound {
+    meta?: undefined;
+    content?: undefined;
+}
 export interface DownloadOptions {
     /** If true then uses UID number instead of sequence number for `range` */
     uid?: boolean | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "2.0.6",
+    "version": "2.0.8",
     "description": "IMAP Client for Node",
     "type": "module",
     "main": "./dist/cjs/imap-flow.js",
@@ -47,7 +47,7 @@
         "test:rev2": "bash test/integration/run-rev2-tests.sh",
         "format": "prettier --write \"**/*.{js,cjs,ts,json,md,yml,yaml}\"",
         "format:check": "prettier --check \"**/*.{js,cjs,ts,json,md,yml,yaml}\"",
-        "lint": "eslint . && npm run typecheck",
+        "lint": "npm run typecheck && eslint .",
         "lint:fix": "eslint . --fix",
         "prepare": "npm run build",
         "update": "rm -rf node_modules package-lock.json && ncu -u && npm install"
@@ -73,12 +73,12 @@
         "eslint": "10.11.0",
         "eslint-config-prettier": "10.1.8",
         "globals": "17.12.0",
-        "prettier": "3.9.8",
+        "prettier": "3.9.9",
         "tsx": "4.23.15",
         "types-node-legacy": "npm:@types/node@20.0.0",
         "typescript": "6.0.3",
         "typescript-eslint": "8.70.1",
-        "wrangler": "4.136.3"
+        "wrangler": "4.141.0"
     },
     "dependencies": {
         "@zone-eu/mailsplit": "5.4.17",