imapflow 1.7.8 → 2.0.0

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

@@ -0,0 +1,676 @@
+/**
+ * @module imapflow
+ */
+import tls from 'node:tls';
+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';
+export type * from './types.js';
+export type { ImapFlowError } from './errors.js';
+export { AuthenticationFailure } from './errors.js';
+export type { ImapAttribute, ImapAttributeList, ImapAttributeNode, ImapResponse } from './handler/types.js';
+declare const stateValues: {
+    readonly NOT_AUTHENTICATED: 1;
+    readonly AUTHENTICATED: 2;
+    readonly SELECTED: 3;
+    readonly LOGOUT: 4;
+};
+/** One of the `ImapFlow#states` values */
+export type ConnectionState = (typeof stateValues)[keyof typeof stateValues];
+/**
+ * The connection state constants, see `ImapFlow#states`. Every member is typed as the whole
+ * union, so a list of states accepts any state in an `includes()` check
+ */
+export type ConnectionStates = {
+    readonly [K in keyof typeof stateValues]: ConnectionState;
+};
+/**
+ * The socket carrying the IMAP session. A TLS socket exposes `getCipher()` and `authorized`, a
+ * cleartext socket does not, and the code checks for them at runtime.
+ */
+export type ImapSocket = net.Socket & {
+    getCipher?: (() => tls.CipherNameAndProtocol) | undefined;
+    authorized?: boolean | undefined;
+};
+/**
+ * Where outgoing bytes are written: the socket itself, or the PassThrough that feeds the
+ * DEFLATE stream once compression is active
+ */
+export type WriteSocket = (ImapSocket | PassThrough) & {
+    destroySoon?: (() => void) | undefined;
+};
+/**
+ * Typed event overloads of the {@link ImapFlow} class, see {@link ImapFlowEvents}
+ */
+export interface ImapFlow {
+    on<K extends keyof ImapFlowEvents>(event: K, listener: (...args: ImapFlowEvents[K]) => void): this;
+    on(event: string | symbol, listener: (...args: any[]) => void): this;
+    once<K extends keyof ImapFlowEvents>(event: K, listener: (...args: ImapFlowEvents[K]) => void): this;
+    once(event: string | symbol, listener: (...args: any[]) => void): this;
+    off<K extends keyof ImapFlowEvents>(event: K, listener: (...args: ImapFlowEvents[K]) => void): this;
+    off(event: string | symbol, listener: (...args: any[]) => void): this;
+    addListener<K extends keyof ImapFlowEvents>(event: K, listener: (...args: ImapFlowEvents[K]) => void): this;
+    addListener(event: string | symbol, listener: (...args: any[]) => void): this;
+    removeListener<K extends keyof ImapFlowEvents>(event: K, listener: (...args: ImapFlowEvents[K]) => void): this;
+    removeListener(event: string | symbol, listener: (...args: any[]) => void): this;
+    prependListener<K extends keyof ImapFlowEvents>(event: K, listener: (...args: ImapFlowEvents[K]) => void): this;
+    prependListener(event: string | symbol, listener: (...args: any[]) => void): this;
+    prependOnceListener<K extends keyof ImapFlowEvents>(event: K, listener: (...args: ImapFlowEvents[K]) => void): this;
+    prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this;
+    emit<K extends keyof ImapFlowEvents>(event: K, ...args: ImapFlowEvents[K]): boolean;
+    emit(event: string | symbol, ...args: any[]): boolean;
+}
+/**
+ * IMAP client class for accessing IMAP mailboxes
+ */
+export declare class ImapFlow extends EventEmitter {
+    /**
+     * Current module version as a static class property
+     */
+    static version: string;
+    /** IMAP connection options, see {@link ImapFlowOptions} */
+    options: ImapFlowOptions;
+    /** Instance ID for logs */
+    id: string;
+    /** Client identification info sent with the ID command */
+    clientInfo: IdInfoObject;
+    /**
+     * Server identification info. Available after successful `connect()`.
+     * If server does not provide identification info then this value is `null`.
+     */
+    serverInfo: IdInfoObject | null;
+    /** Connection logger. Every level is callable, see `getLogger()` */
+    log: InternalLogger;
+    /** Is the connection currently encrypted or not */
+    secureConnection: boolean;
+    /** Port number the connection is made to */
+    port: number;
+    /** Hostname the connection is made to */
+    host: string;
+    /** Server name for SNI, or false when connecting to an IP literal */
+    servername: string | false;
+    /** Set once `close()` has run */
+    isClosed: boolean;
+    /** Connection state constants */
+    states: ConnectionStates;
+    /** Current connection state, one of `states` */
+    state: ConnectionState;
+    /**
+     * Active IMAP capabilities. Value is either `true` for toggleable capabilities (eg. `UIDPLUS`)
+     * or a number for capabilities with a value (eg. `APPENDLIMIT`)
+     */
+    capabilities: Map<string, boolean | number>;
+    /**
+     * Enabled capabilities. Usually `CONDSTORE` and `UTF8=ACCEPT` if server supports these.
+     */
+    enabled: Set<string>;
+    /**
+     * Is the connection currently usable or not
+     */
+    usable: boolean;
+    /**
+     * Currently authenticated user or `false` if mailbox is not open
+     * or `true` if connection was authenticated by PREAUTH
+     */
+    authenticated: string | boolean;
+    /**
+     * Currently selected mailbox or `false` if mailbox is not open
+     */
+    mailbox: MailboxObject | false;
+    /**
+     * Is current mailbox idling (`true`) or not (`false`)
+     */
+    idling: boolean;
+    /** Whether log entries are also emitted as 'log' events, see the `emitLogs` option */
+    emitLogs: boolean;
+    /** The personal namespace, from the NAMESPACE command */
+    namespace: NamespaceObject | undefined;
+    /** Every namespace the server reported */
+    namespaces: NamespacesObject | undefined;
+    /** Human readable text of the server greeting */
+    greeting: string | undefined;
+    /** Reason text of the server's BYE response, if the server closed the session */
+    byeReason: string | undefined;
+    /** Negotiated TLS session details, `false` for a cleartext connection */
+    tls: TlsInfo | false | undefined;
+    constructor(options?: ImapFlowOptions | undefined);
+    /**
+     * Returns byte counters for the current connection.
+     *
+     * @param reset If `true` then resets the byte counters after returning the current values
+     * @returns Byte counters: bytes sent to and received from the server
+     */
+    stats(reset?: boolean): {
+        sent: number;
+        received: number;
+    };
+    /**
+     * Tries to upgrade the connection to TLS using STARTTLS.
+     * @throws if STARTTLS is required, but not possible.
+     * @returns true, if the connection is now protected by TLS, either direct TLS or STARTTLS.
+     */
+    upgradeToSTARTTLS(): Promise<boolean>;
+    /**
+     * Initiates a connection against IMAP server. Throws if anything goes wrong. This is something you have to call before you can run any IMAP commands
+     *
+     * @throws Will throw an error if connection or authentication fails
+     * @example
+     * let client = new ImapFlow({...});
+     * await client.connect();
+     */
+    connect(): Promise<void>;
+    /**
+     * Graceful connection close by sending logout command to server. TCP connection is closed once command is finished.
+     *
+     * @example
+     * let client = new ImapFlow({...});
+     * await client.connect();
+     * ...
+     * await client.logout();
+     */
+    logout(): Promise<void>;
+    /**
+     * Close the TCP connection.
+     * Unlike `close()`, return immediately from this function, allowing the
+     * caller function to proceed, and run `close()` function afterwards.
+     */
+    closeAfter(): void;
+    /**
+     * Closes TCP connection without notifying the server.
+     *
+     * @example
+     * let client = new ImapFlow({...});
+     * await client.connect();
+     * ...
+     * client.close();
+     */
+    close(): void;
+    /**
+     * Returns current quota
+     *
+     * @param path Optional mailbox path if you want to check quota for specific folder. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
+     * @returns Quota information or `false` if QUOTA extension is not supported or requested path does not exist
+     *
+     * @example
+     * let quota = await client.getQuota();
+     * console.log(quota.storage.used, quota.storage.limit)
+     */
+    getQuota(path?: string | string[] | undefined): Promise<QuotaResponse | false>;
+    /**
+     * Lists available mailboxes as an Array
+     *
+     * @param options defines additional listing options
+     * @returns An array of ListResponse objects
+     *
+     * @example
+     * let list = await client.list();
+     * list.forEach(mailbox=>console.log(mailbox.path));
+     */
+    list(options?: ListOptions | undefined): Promise<ListResponse[]>;
+    /**
+     * Lists available mailboxes as a tree structured object
+     *
+     * @param options defines additional listing options
+     * @returns Tree structured object
+     *
+     * @example
+     * let tree = await client.listTree();
+     * tree.folders.forEach(mailbox=>console.log(mailbox.path));
+     */
+    listTree(options?: ListOptions | undefined): Promise<ListTreeResponse>;
+    /**
+     * Performs a no-op call against server
+     */
+    noop(): Promise<void>;
+    /**
+     * Creates a new mailbox folder and sets up subscription for the created mailbox. Throws on error.
+     *
+     * @param path Full mailbox path. Unicode is allowed. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
+     * @returns Mailbox info
+     * @throws Will throw an error if mailbox can not be created
+     *
+     * @example
+     * let info = await client.mailboxCreate(['parent', 'child']);
+     * console.log(info.path);
+     * // "INBOX.parent.child" // assumes "INBOX." as namespace prefix and "." as delimiter
+     */
+    mailboxCreate(path: string | string[]): Promise<MailboxCreateResponse>;
+    /**
+     * Renames a mailbox. Throws on error.
+     *
+     * @param path  Path for the mailbox to rename. Unicode is allowed. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
+     * @param newPath New path for the mailbox
+     * @returns Mailbox info
+     * @throws Will throw an error if mailbox does not exist or can not be renamed
+     *
+     * @example
+     * let info = await client.mailboxRename('parent.child', 'Important stuff');
+     * console.log(info.newPath);
+     * // "INBOX.Important stuff" // assumes "INBOX." as namespace prefix
+     */
+    mailboxRename(path: string | string[], newPath: string | string[]): Promise<MailboxRenameResponse>;
+    /**
+     * Deletes a mailbox. Throws on error.
+     *
+     * @param path Path for the mailbox to delete. Unicode is allowed. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
+     * @returns Mailbox info
+     * @throws Will throw an error if mailbox does not exist or can not be deleted
+     *
+     * @example
+     * let info = await client.mailboxDelete('Important stuff');
+     * console.log(info.path);
+     * // "INBOX.Important stuff" // assumes "INBOX." as namespace prefix
+     */
+    mailboxDelete(path: string | string[]): Promise<MailboxDeleteResponse>;
+    /**
+     * Subscribes to a mailbox
+     *
+     * @param path Path for the mailbox to subscribe to. Unicode is allowed. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
+     * @returns `true` if subscription operation succeeded, `false` otherwise
+     *
+     * @example
+     * await client.mailboxSubscribe('Important stuff');
+     */
+    mailboxSubscribe(path: string | string[]): Promise<boolean>;
+    /**
+     * Unsubscribes from a mailbox
+     *
+     * @param path **Path for the mailbox** to unsubscribe from. Unicode is allowed. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
+     * @returns `true` if unsubscription operation succeeded, `false` otherwise
+     *
+     * @example
+     * await client.mailboxUnsubscribe('Important stuff');
+     */
+    mailboxUnsubscribe(path: string | string[]): Promise<boolean>;
+    /**
+     * Opens a mailbox to access messages. You can perform message operations only against an opened mailbox.
+     * Using {@link ImapFlow#getMailboxLock} instead of `mailboxOpen()` is preferred. Both do the same thing
+     * but next `getMailboxLock()` call is not executed until previous one is released.
+     *
+     * @param path **Path for the mailbox** to open
+     * @param options optional options
+     * @returns Mailbox info
+     * @throws Will throw an error if mailbox does not exist or can not be opened
+     *
+     * @example
+     * let mailbox = await client.mailboxOpen('Important stuff');
+     * console.log(mailbox.exists);
+     * // 125
+     */
+    mailboxOpen(path: string | string[], options?: MailboxOpenOptions | undefined): Promise<MailboxObject>;
+    /**
+     * Closes a previously opened mailbox
+     *
+     * @returns Did the operation succeed or not
+     *
+     * @example
+     * let mailbox = await client.mailboxOpen('INBOX');
+     * await client.mailboxClose();
+     */
+    mailboxClose(): Promise<boolean>;
+    /**
+     * Requests the status of the indicated mailbox. Only requested status values will be returned.
+     *
+     * @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
+     *
+     * @example
+     * let status = await client.status('INBOX', {unseen: true});
+     * console.log(status.unseen);
+     * // 123
+     */
+    status(path: string | string[], query: StatusQuery): Promise<StatusObject>;
+    /**
+     * 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
+     *
+     * @example
+     * let mailbox = await client.mailboxOpen('INBOX');
+     *
+     * await client.idle();
+     */
+    idle(): Promise<boolean | undefined>;
+    /**
+     * Sets flags for a message or message range
+     *
+     * @param range Range to filter the messages
+     * @param flags Array of flags to set. Only flags that are permitted to set are used, other flags are ignored
+     * @param options Store options
+     * @returns Did the operation succeed or not
+     *
+     * @example
+     * let mailbox = await client.mailboxOpen('INBOX');
+     * // mark all unseen messages as seen (and remove other flags)
+     * await client.messageFlagsSet({seen: false}, ['\Seen]);
+     */
+    messageFlagsSet(range: MessageRange, flags: string[], options?: StoreOptions | undefined): Promise<boolean>;
+    /**
+     * Adds flags for a message or message range
+     *
+     * @param range Range to filter the messages
+     * @param flags Array of flags to set. Only flags that are permitted to set are used, other flags are ignored
+     * @param options Store options
+     * @returns Did the operation succeed or not
+     *
+     * @example
+     * let mailbox = await client.mailboxOpen('INBOX');
+     * // mark all unseen messages as seen (and keep other flags as is)
+     * await client.messageFlagsAdd({seen: false}, ['\Seen]);
+     */
+    messageFlagsAdd(range: MessageRange, flags: string[], options?: StoreOptions | undefined): Promise<boolean>;
+    /**
+     * Remove specific flags from a message or message range
+     *
+     * @param range Range to filter the messages
+     * @param flags Array of flags to remove. Only flags that are permitted to set are used, other flags are ignored
+     * @param options Store options
+     * @returns Did the operation succeed or not
+     *
+     * @example
+     * let mailbox = await client.mailboxOpen('INBOX');
+     * // mark all seen messages as unseen by removing \\Seen flag
+     * await client.messageFlagsRemove({seen: true}, ['\Seen]);
+     */
+    messageFlagsRemove(range: MessageRange, flags: string[], options?: StoreOptions | undefined): Promise<boolean>;
+    /**
+     * Sets a colored flag for an email. Only supported by mail clients like Apple Mail
+     *
+     * @param range Range to filter the messages
+     * @param color The color to set. One of 'red', 'orange', 'yellow', 'green', 'blue', 'purple', and 'grey'
+     * @param options Store options
+     * @returns Did the operation succeed or not
+     *
+     * @example
+     * let mailbox = await client.mailboxOpen('INBOX');
+     * // add a purple flag for all emails
+     * await client.setFlagColor('1:*', 'Purple');
+     */
+    setFlagColor(range: MessageRange, color: string, options?: StoreOptions | undefined): Promise<boolean>;
+    /**
+     * Delete messages from the currently opened mailbox. Method does not indicate info about deleted messages,
+     * instead you should be using the `expunge` event for this
+     *
+     * @param range Range to filter the messages
+     * @param options Range options
+     * @returns Did the operation succeed or not
+     *
+     * @example
+     * let mailbox = await client.mailboxOpen('INBOX');
+     * // delete all seen messages
+     * await client.messageDelete({seen: true});
+     */
+    messageDelete(range: MessageRange, options?: MessageRangeOptions | undefined): Promise<boolean>;
+    /**
+     * Appends a new message to a mailbox
+     *
+     * @param path Mailbox path to upload the message to (unicode string). If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
+     * @param content RFC822 formatted email message
+     * @param flags an array of flags to be set for the uploaded message
+     * @param idate internal date to be set for the message
+     * @returns info about uploaded message
+     *
+     * @example
+     * await client.append('INBOX', rawMessageBuffer, ['\\Seen'], new Date(2000, 1, 1));
+     */
+    append(path: string | string[], content: string | Buffer, flags?: string[] | undefined, idate?: Date | string | undefined): Promise<AppendResponseObject | false>;
+    /**
+     * Copies messages from current mailbox to destination mailbox
+     *
+     * @param range Range of messages to copy
+     * @param destination Mailbox path to copy the messages to. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
+     * @param options Range options
+     * @returns info about copies messages
+     *
+     * @example
+     * await client.mailboxOpen('INBOX');
+     * // copy all messages to a mailbox called "Backup" (must exist)
+     * let result = await client.messageCopy('1:*', 'Backup');
+     * console.log('Copied %s messages', result.uidMap.size);
+     */
+    messageCopy(range: MessageRange, destination: string | string[], options?: MessageRangeOptions | undefined): Promise<CopyResponseObject | false>;
+    /**
+     * Moves messages from current mailbox to destination mailbox
+     *
+     * @param range Range of messages to move
+     * @param destination Mailbox path to move the messages to. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
+     * @param options Range options
+     * @returns info about moved messages
+     *
+     * @example
+     * await client.mailboxOpen('INBOX');
+     * // move all messages to a mailbox called "Trash" (must exist)
+     * let result = await client.messageMove('1:*', 'Trash');
+     * console.log('Moved %s messages', result.uidMap.size);
+     */
+    messageMove(range: MessageRange, destination: string | string[], options?: MessageRangeOptions | undefined): Promise<CopyResponseObject | false>;
+    /**
+     * Search messages from the currently opened mailbox
+     *
+     * @param query Query to filter the messages
+     * @param options Search options. With `returnOptions` set the result is an ESEARCH result object
+     * @returns An array of sequence or UID numbers, or an ESearchResult when `returnOptions` was used
+     *
+     * @example
+     * let mailbox = await client.mailboxOpen('INBOX');
+     * // find all unseen messages
+     * let list = await client.search({seen: false});
+     * // use OR modifier (array of 2 or more search queries)
+     * let list = await client.search({
+     *   seen: false,
+     *   or: [
+     *     {flagged: true},
+     *     {from: 'andris'},
+     *     {subject: 'test'}
+     *   ]});
+     */
+    search(query: SearchObject, options?: MessageRangeOptions | undefined): Promise<number[] | false | undefined>;
+    search(query: SearchObject, options: SearchOptions & {
+        returnOptions: SearchReturnOption[];
+    }): Promise<ESearchResult | number[] | false | undefined>;
+    search(query: SearchObject, options?: SearchOptions | undefined): Promise<ESearchResult | number[] | false | undefined>;
+    /**
+     * Fetch messages from the currently opened mailbox
+     *
+     * @param range Range of messages to fetch
+     * @param query Fetch query
+     * @param options Fetch options
+     * @yields Message data object
+     *
+     * @example
+     * let mailbox = await client.mailboxOpen('INBOX');
+     * // fetch UID for all messages in a mailbox
+     * for await (let msg of client.fetch('1:*', {uid: true})){
+     *     console.log(msg.uid);
+     *     // NB! You can not run any IMAP commands in this loop
+     *     // otherwise you will end up in a deadloop
+     * }
+     */
+    fetch(range: MessageRange, query: FetchQueryObject, options?: FetchOptions | undefined): AsyncGenerator<FetchMessageObject, false | void, undefined>;
+    /**
+     * Fetch messages from the currently opened mailbox.
+     *
+     * This method will fetch all messages before resolving the promise, unlike .fetch(), which
+     * is an async generator. Do not use large ranges like 1:*, as this might exhaust all available
+     * memory if the mailbox contains a large number of emails.
+     * @param range Range of messages to fetch
+     * @param query Fetch query
+     * @param options Fetch options
+     * @returns Array of Message data object
+     *
+     * @example
+     * let mailbox = await client.mailboxOpen('INBOX');
+     * // fetch UID for all messages in a mailbox
+     * const messages = await client.fetchAll('1:*', {uid: true});
+     * for (let msg of messages){
+     *     console.log(msg.uid);
+     * }
+     */
+    fetchAll(range: MessageRange, query: FetchQueryObject, options?: FetchOptions | undefined): Promise<FetchMessageObject[]>;
+    /**
+     * Fetch a single message from the currently opened mailbox
+     *
+     * @param seq Single UID or sequence number of the message to fetch for
+     * @param query Fetch query
+     * @param options Fetch options
+     * @returns Message data object
+     *
+     * @example
+     * let mailbox = await client.mailboxOpen('INBOX');
+     * // fetch UID for the last email in the selected mailbox
+     * let lastMsg = await client.fetchOne('*', {uid: true})
+     * console.log(lastMsg.uid);
+     */
+    fetchOne(seq: SequenceString, query: FetchQueryObject, options?: FetchOptions | undefined): Promise<FetchMessageObject | false | undefined>;
+    /**
+     * Download either full rfc822 formatted message or a specific bodystructure part as a Stream.
+     * Bodystructure parts are decoded so the resulting stream is a binary file. Text content
+     * is automatically converted to UTF-8 charset.
+     *
+     * @param range UID or sequence number for the message to fetch
+     * @param part If not set then downloads entire rfc822 formatted message, otherwise downloads specific bodystructure part
+     * @param options Download options
+     * @returns Download data object. Resolves with an empty object when no mailbox is selected or the message or part was not found
+     *
+     * @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));
+     */
+    download(range: SequenceString, part?: string | undefined, options?: DownloadOptions | undefined): Promise<DownloadObject>;
+    /**
+     * Fetch multiple attachments as Buffer values
+     *
+     * @param range UID or sequence number for the message to fetch
+     * @param parts A list of bodystructure parts
+     * @param options Download options
+     * @returns Download data object, keyed by part
+     *
+     * @example
+     * let mailbox = await client.mailboxOpen('INBOX');
+     * // download body parts '2', and '3' from all messages in the selected mailbox
+     * let response = await client.downloadMany('*', ['2', '3']);
+     * process.stdout.write(response[2].content)
+     * process.stdout.write(response[3].content)
+     */
+    downloadMany(range: SequenceString, parts: string[], options?: DownloadManyOptions | undefined): Promise<DownloadManyResult>;
+    /**
+     * Opens a mailbox if not already open and returns a lock. Next call to `getMailboxLock()` is queued
+     * until previous lock is released. This is suggested over {@link ImapFlow#mailboxOpen} as
+     * `getMailboxLock()` gives you a weak transaction while `mailboxOpen()` has no guarantees whatsoever that another
+     * mailbox is opened while you try to call multiple fetch or store commands.
+     *
+     * @param path **Path for the mailbox** to open
+     * @param options optional options
+     * @returns Mailbox lock
+     * @throws Will throw an error if mailbox does not exist or can not be opened
+     *
+     * @example
+     * let lock = await client.getMailboxLock('INBOX');
+     * try {
+     *   // do something in the mailbox
+     * } finally {
+     *   // use finally{} to make sure lock is released even if exception occurs
+     *   lock.release();
+     * }
+     */
+    getMailboxLock(path: string | string[], options?: MailboxLockOptions | undefined): Promise<MailboxLockObject>;
+    /**
+     * Detaches sockets from the IMAP pipeline. Useful for upgrading the connection
+     * (e.g., STARTTLS) or transferring socket ownership.
+     *
+     * @returns Socket objects: `readSocket` is the read socket (inflated socket if compression is enabled, raw socket otherwise),
+     *   `writeSocket` the write socket and `socket` the raw underlying socket (same as readSocket/writeSocket when compression is disabled)
+     */
+    unbind(): {
+        readSocket: Readable;
+        writeSocket: WriteSocket;
+        socket: ImapSocket;
+    };
+}
+/**
+ * Connection close event. **NB!** ImapFlow does not handle reconnects automatically.
+ * So whenever a 'close' event occurs you must create a new connection yourself.
+ *
+ * @event ImapFlow#close
+ */
+/**
+ * Error event. In most cases getting an error event also means that connection is closed
+ * and pending operations should return with a failure.
+ *
+ * @event ImapFlow#error
+ * @example
+ * client.on('error', err=>{
+ *     console.log(`Error occurred: ${err.message}`);
+ * });
+ */
+/**
+ * Message count in currently opened mailbox changed
+ *
+ * @event ImapFlow#exists
+ * @example
+ * client.on('exists', data=>{
+ *     console.log(`Message count in "${data.path}" is ${data.count}`);
+ * });
+ */
+/**
+ * Deleted message sequence number in currently opened mailbox. One event is fired for every deleted email.
+ *
+ * @event ImapFlow#expunge
+ * @example
+ * client.on('expunge', data=>{
+ *     console.log(`Message #${data.seq} was deleted from "${data.path}"`);
+ * });
+ */
+/**
+ * Flags were updated for a message. Not all servers fire this event.
+ *
+ * @event ImapFlow#flags
+ * @example
+ * client.on('flags', data=>{
+ *     console.log(`Flag set for #${data.seq} is now "${Array.from(data.flags).join(', ')}"`);
+ * });
+ */
+/**
+ * Mailbox was opened
+ *
+ * @event ImapFlow#mailboxOpen
+ * @example
+ * client.on('mailboxOpen', mailbox => {
+ *     console.log(`Mailbox ${mailbox.path} was opened`);
+ * });
+ */
+/**
+ * Mailbox was closed
+ *
+ * Emitted both when a selected mailbox is closed explicitly, by `mailboxClose()` or by
+ * selecting a different mailbox, and when the connection itself goes away while a mailbox
+ * was still selected, whether through a clean logout or a lost transport. The transition is
+ * reported once per selected mailbox, before the `close` event.
+ *
+ * @event ImapFlow#mailboxClose
+ * @example
+ * client.on('mailboxClose', mailbox => {
+ *     console.log(`Mailbox ${mailbox.path} was closed`);
+ * });
+ */
+/**
+ * Log event if `emitLogs=true`
+ *
+ * @event ImapFlow#log
+ * @example
+ * client.on('log', entry => {
+ *     console.log(`${entry.cid} ${entry.msg}`);
+ * });
+ */
+declare const imapflow: {
+    ImapFlow: typeof ImapFlow;
+    AuthenticationFailure: typeof AuthenticationFailure;
+};
+export default imapflow;