imapflow 2.0.6 → 2.0.8

package/dist/cjs/imap-flow.d.ts

@@ -6,7 +6,7 @@ import net from 'node:net';
 import { EventEmitter } from 'node:events';
 import { PassThrough, type Readable } from 'node:stream';
 import { AuthenticationFailure } from './errors.js';
-import type { AppendResponseObject, CopyResponseObject, DownloadManyOptions, DownloadManyResult, DownloadObject, DownloadOptions, ESearchResult, FetchMessageObject, FetchOptions, FetchQueryObject, IdInfoObject, ImapFlowEvents, ImapFlowOptions, InternalLogger, ListOptions, ListResponse, ListTreeResponse, MailboxCreateResponse, MailboxDeleteResponse, MailboxLockObject, MailboxLockOptions, MailboxObject, MailboxOpenOptions, MailboxRenameResponse, MessageRange, MessageRangeOptions, NamespaceObject, NamespacesObject, QuotaResponse, SearchObject, SearchOptions, SearchReturnOption, SequenceString, StatusObject, StatusQuery, StoreOptions, TlsInfo } from './types.js';
+import type { AppendResponseObject, CopyResponseObject, DownloadManyOptions, DownloadManyResult, DownloadObject, DownloadNotFound, DownloadOptions, ESearchResult, FetchMessageObject, FetchOptions, FetchQueryObject, IdInfoObject, ImapFlowEvents, ImapFlowOptions, InternalLogger, ListOptions, ListResponse, ListTreeResponse, MailboxCreateResponse, MailboxDeleteResponse, MailboxLockObject, MailboxLockOptions, MailboxObject, MailboxOpenOptions, MailboxRenameResponse, MessageRange, MessageRangeOptions, NamespaceObject, NamespacesObject, QuotaResponse, SearchObject, SearchOptions, SearchReturnOption, SequenceString, StatusObject, StatusQuery, StoreOptions, TlsInfo } from './types.js';
 export type * from './types.js';
 export type { ImapFlowError } from './errors.js';
 export { AuthenticationFailure } from './errors.js';
@@ -135,6 +135,9 @@ export declare class ImapFlow extends EventEmitter {
     byeReason: string | undefined;
     /** Negotiated TLS session details, `false` for a cleartext connection */
     tls: TlsInfo | false | undefined;
+    /**
+     * Creates a client for one IMAP connection. Nothing is sent before `connect()` is called
+     */
     constructor(options?: ImapFlowOptions | undefined);
     /**
      * Returns byte counters for the current connection.
@@ -315,20 +318,20 @@ export declare class ImapFlow extends EventEmitter {
      *
      * @param path mailbox path to check for (unicode string). If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
      * @param query defines requested status items
-     * @returns status of the indicated mailbox
+     * @returns status of the indicated mailbox, or `false` if the server rejected the request
      *
      * @example
      * let status = await client.status('INBOX', {unseen: true});
      * console.log(status.unseen);
      * // 123
      */
-    status(path: string | string[], query: StatusQuery): Promise<StatusObject>;
+    status(path: string | string[], query: StatusQuery): Promise<StatusObject | false>;
     /**
      * Starts listening for new or deleted messages from the currently opened mailbox. Only required if `disableAutoIdle` is set to `true`
      * otherwise IDLE is started by default on connection inactivity. NB! If `idle()` is called manually then it does not
      * return until IDLE is finished which means you would have to call some other command out of scope.
      *
-     * @returns Did the operation succeed or not
+     * @returns `false` if IDLE failed, `undefined` otherwise
      *
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
@@ -470,6 +473,10 @@ export declare class ImapFlow extends EventEmitter {
      *   ]});
      */
     search(query: SearchObject, options?: MessageRangeOptions | undefined): Promise<number[] | false | undefined>;
+    /**
+     * Search with `returnOptions` set: an ESEARCH result object from a server that supports
+     * ESEARCH, the plain list of numbers otherwise
+     */
     search(query: SearchObject, options: SearchOptions & {
         returnOptions: SearchReturnOption[];
     }): Promise<ESearchResult | number[] | false | undefined>;
@@ -540,10 +547,12 @@ export declare class ImapFlow extends EventEmitter {
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
      * // download body part nr '1.2' from latest message
-     * let {meta, content} = await client.download('*', '1.2');
-     * content.pipe(fs.createWriteStream(meta.filename));
+     * let download = await client.download('*', '1.2');
+     * if (download.content) {
+     *     download.content.pipe(fs.createWriteStream(download.meta.filename));
+     * }
      */
-    download(range: SequenceString, part?: string | undefined, options?: DownloadOptions | undefined): Promise<DownloadObject>;
+    download(range: SequenceString, part?: string | undefined, options?: DownloadOptions | undefined): Promise<DownloadObject | DownloadNotFound>;
     /**
      * Fetch multiple attachments as Buffer values
      *