imapkit 4.3.1 → 5.0.1

package/dist/cjs/control.d.ts

@@ -0,0 +1,425 @@
+/**
+ * The control API, `server.control`: inspects and changes the server state from a test, without an IMAP session.
+ * Every change reaches the connected sessions as if another session had made it (EXISTS, EXPUNGE or VANISHED,
+ * unsolicited FETCH, BYE, NOTIFY events, CONDSTORE mod-sequences), with no session as its origin. The API is the
+ * operator: ACL does not apply, but every argument is checked. Mailboxes are addressed by their storage name
+ * (modified UTF-7), messages by mailbox and UID. Methods return plain data and throw an ImapKitError with a `code`:
+ * NONEXISTENT, ALREADYEXISTS, INVALID, or the response code of a failed mailbox operation (CANNOT, HASCHILDREN ...)
+ */
+import { ImapKitError } from './store-operations.js';
+import type { FlagMode, UidValidityOptions } from './store-operations.js';
+import type { IMAPConnection, IMAPServer, Mailbox, Message, StorageMailbox, StorageNamespace, UserData } from './types.js';
+/** A mailbox as `getMailbox()` and `listMailboxes()` describe it */
+interface MailboxInfo {
+    path: string;
+    delimiter: string;
+    /** mailbox attributes, e.g. \Noselect, \HasChildren */
+    flags: string[];
+    /** false for a \Noselect name that only holds child mailboxes */
+    selectable: boolean;
+    subscribed: boolean;
+    messages: number;
+    unseen: number;
+    uidnext: number;
+    uidvalidity: number;
+    /** the flags of the FLAGS response, SELECT adds \* to PERMANENTFLAGS when new keywords are allowed */
+    permanentFlags: string[];
+    /** only with CONDSTORE */
+    highestModseq?: number;
+    /** only with SPECIAL-USE */
+    specialUse?: string[];
+    /** only with OBJECTID */
+    mailboxId?: string;
+}
+/** A message as `getMessage()` and `listMessages()` describe it */
+interface MessageInfo {
+    uid: number;
+    flags: string[];
+    internaldate: string;
+    /** size of the source in octets */
+    size: number;
+    /** only with CONDSTORE */
+    modseq?: number;
+    /** only with OBJECTID */
+    emailId?: string;
+    threadId?: string;
+    /** the message source, only when asked for */
+    raw?: Buffer;
+}
+/** A connected session as `sessions()` describes it */
+interface SessionInfo {
+    session: number;
+    user: string | null;
+    state: string;
+    /** storage name of the selected mailbox */
+    mailbox: string | null;
+    readOnly: boolean;
+    /** extensions enabled with ENABLE */
+    enabled: string[];
+    secure: boolean;
+    compressed: boolean;
+    remoteAddress: string | null;
+}
+interface NewMessage {
+    /** the message source, a string is encoded as UTF-8 */
+    raw: string | Uint8Array;
+    flags?: string[] | undefined;
+    /** a Date or a RFC 3501 date-time string, the current time if not set */
+    internaldate?: Date | string | undefined;
+}
+/** The credentials of a user, see UserData */
+type UserOptions = Pick<UserData, 'password' | 'xoauth2'>;
+/** What a REST route handler gets, see src/rest.ts */
+interface RouteRequest {
+    params: Record<string, string>;
+    query: URLSearchParams;
+    body: any;
+}
+/** A REST route of the control API, see src/rest.ts */
+interface ControlRoute {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** URL path, `{name}` matches one URL encoded segment */
+    path: string;
+    summary: string;
+    /** returns the response body, `{ status, body }` for another status than 200 */
+    handler(request: RouteRequest): unknown;
+}
+/** Selects sessions: a session number, or the sessions of a user */
+type SessionFilter = number | {
+    session?: number | undefined;
+    user?: string | undefined;
+};
+declare class Control {
+    [key: string]: any;
+    server: IMAPServer;
+    /** REST routes that plugins registered, the REST API serves them after its own */
+    routes: ControlRoute[];
+    /** `(mailbox, copy)` functions that put plugin data that is not JSON into the snapshot of a mailbox */
+    snapshotHandlers: ((mailbox: Mailbox, copy: StorageMailbox) => void)[];
+    /** `(mailbox, info)` and `(message, info)` functions that add plugin fields to getMailbox() and getMessage() */
+    mailboxInfoHandlers: ((mailbox: Mailbox, info: MailboxInfo) => void)[];
+    messageInfoHandlers: ((message: Message, info: MessageInfo) => void)[];
+    constructor(server: IMAPServer);
+    /**
+     * Adds an operation of a plugin, e.g. `server.control.setAcl()` of ACL, so that a plugin that is not loaded
+     * leaves no trace. The operation runs with no session as its origin, like the built-in ones, and throws
+     * ImapKitErrors (see storeError() in store-operations.ts)
+     *
+     * @param {String} name Method name on server.control
+     * @param {Function} fn Operation
+     * @param {Array} [routes] REST routes of the operation
+     */
+    register(name: string, fn: (...args: any[]) => unknown, routes?: ControlRoute[]): void;
+    /**
+     * Runs a change with no session as its origin, also when a listener of a command event calls the API
+     *
+     * @param {Function} fn Change
+     * @return {*} the result of fn
+     */
+    run<T>(fn: () => T): T;
+    /**
+     * Finds a mailbox by its storage name
+     *
+     * @param {String} path Storage name, INBOX in any case
+     * @param {Boolean} [selectable] true if the mailbox must hold messages (not \Noselect)
+     * @return {Object} mailbox
+     * @throws {ImapKitError} NONEXISTENT
+     */
+    requireMailbox(path: unknown, selectable?: boolean): Mailbox;
+    /**
+     * Checks a new mailbox name
+     *
+     * @param {String} path Storage name
+     * @throws {ImapKitError} INVALID for a name that is not valid modified UTF-7
+     */
+    checkName(path: unknown): asserts path is string;
+    /**
+     * Checks that a mailbox argument is a name, the store operations check the rest
+     *
+     * @param {String} path Storage name
+     * @throws {ImapKitError} INVALID
+     */
+    checkPath(path: unknown): asserts path is string;
+    /**
+     * Finds messages by UID
+     *
+     * @param {Object} mailbox Mailbox
+     * @param {Array} uids UIDs of the messages
+     * @return {Array} messages in the order of the UIDs, without duplicates
+     * @throws {ImapKitError} INVALID for a list that is not UIDs, NONEXISTENT for a UID that is not in the mailbox
+     */
+    requireMessages(mailbox: Mailbox, uids: unknown): Message[];
+    /**
+     * Finds the sessions a filter selects
+     *
+     * @param {Number|Object} filter A session number, or `{ session, user }`
+     * @return {Array} connections
+     */
+    findSessions(filter: SessionFilter): IMAPConnection[];
+    /**
+     * Returns the storage as JSON data in the shape of the `storage` option, so that `imapkit({ storage })` with it
+     * starts from the same mailboxes, messages, UIDs, flags and subscriptions. Plugin data on mailboxes and messages
+     * is included as far as it is JSON data. Subscriptions of names that are not mailboxes are not part of it
+     *
+     * @return {Object} storage
+     */
+    snapshot(): Record<string, StorageNamespace>;
+    /**
+     * Describes every mailbox, including \Noselect hierarchy levels
+     *
+     * @return {Array} mailboxes ordered by name
+     */
+    listMailboxes(): MailboxInfo[];
+    /**
+     * Describes a mailbox
+     *
+     * @param {String} path Storage name
+     * @return {Object} mailbox info
+     */
+    getMailbox(path: string): MailboxInfo;
+    describeMailbox(mailbox: Mailbox): MailboxInfo;
+    /**
+     * Describes the messages of a mailbox
+     *
+     * @param {String} path Storage name
+     * @param {Object} [options] `{ uids, raw }`: only these UIDs, include the message source
+     * @return {Array} messages ordered by UID
+     */
+    listMessages(path: string, options?: {
+        uids?: number[] | undefined;
+        raw?: boolean | undefined;
+    }): MessageInfo[];
+    /**
+     * Describes a message
+     *
+     * @param {String} path Storage name
+     * @param {Number} uid UID of the message
+     * @param {Object} [options] `{ raw }`: include the message source, true by default
+     * @return {Object} message info
+     */
+    getMessage(path: string, uid: number, options?: {
+        raw?: boolean | undefined;
+    }): MessageInfo;
+    describeMessage(message: Message, raw: boolean): MessageInfo;
+    /**
+     * Describes the connected sessions
+     *
+     * @return {Array} sessions ordered by number
+     */
+    sessions(): SessionInfo[];
+    /**
+     * Adds a message to a mailbox, like a delivery from outside: sessions that have the mailbox selected get EXISTS,
+     * the first read-write one sees it as \Recent
+     *
+     * @param {String} path Storage name
+     * @param {Object} message `{ raw, flags, internaldate }`
+     * @param {Object} [options] `{ checks }`: true runs the checks APPEND runs (QUOTA, APPENDLIMIT ...), a failed
+     *   one throws an ImapKitError with its response code, e.g. OVERQUOTA
+     * @return {Object} `{ uid, uidvalidity }`
+     */
+    addMessage(path: string, message: NewMessage, options?: {
+        checks?: boolean | undefined;
+    }): {
+        uid: number;
+        uidvalidity: number;
+    };
+    /**
+     * Changes the flags of messages. Sessions that have the mailbox selected get unsolicited FETCH responses, with
+     * CONDSTORE the messages get new mod-sequences
+     *
+     * @param {String} path Storage name
+     * @param {Array} uids UIDs of the messages
+     * @param {Array} flags Flags
+     * @param {String} [mode] "set" (default), "add" or "remove"
+     * @return {Array} `{ uid, flags }` of every message
+     */
+    setFlags(path: string, uids: number[], flags: string[], mode?: FlagMode): {
+        uid: number;
+        flags: string[];
+    }[];
+    /**
+     * Removes messages. Sessions that have the mailbox selected get EXPUNGE (VANISHED with QRESYNC), following the
+     * RFC 2180 rules a session's EXPUNGE would
+     *
+     * @param {String} path Storage name
+     * @param {Array} uids UIDs of the messages
+     * @return {Array} the removed UIDs
+     */
+    expungeMessages(path: string, uids: number[]): number[];
+    /**
+     * Copies messages to another mailbox, the copies keep flags and internal date and get new UIDs
+     *
+     * @param {String} path Storage name of the source
+     * @param {Array} uids UIDs of the messages
+     * @param {String} target Storage name of the target
+     * @return {Object} `{ uidvalidity, uids }`: UIDVALIDITY of the target, `{ uid, targetUid }` for every message
+     */
+    copyMessages(path: string, uids: number[], target: string): {
+        uidvalidity: number;
+        uids: {
+            uid: number;
+            targetUid: number;
+        }[];
+    };
+    /**
+     * Moves messages to another mailbox: copies them and expunges them from the source
+     *
+     * @param {String} path Storage name of the source
+     * @param {Array} uids UIDs of the messages
+     * @param {String} target Storage name of the target
+     * @return {Object} `{ uidvalidity, uids }`: UIDVALIDITY of the target, `{ uid, targetUid }` for every message
+     */
+    moveMessages(path: string, uids: number[], target: string): {
+        uidvalidity: number;
+        uids: {
+            uid: number;
+            targetUid: number;
+        }[];
+    };
+    transfer(path: string, uids: number[], target: string, move: boolean): {
+        uidvalidity: number;
+        uids: {
+            uid: number;
+            targetUid: number;
+        }[];
+    };
+    /**
+     * Replaces a message. The content of a UID never changes (RFC 9051 section 2.3.1.1), so this adds the new
+     * message and expunges the old one, the new message gets a new UID. Flags and internal date of the old
+     * message are kept unless given
+     *
+     * @param {String} path Storage name
+     * @param {Number} uid UID of the message to replace
+     * @param {Object} message `{ raw, flags, internaldate }`
+     * @return {Object} `{ uid, uidvalidity }` of the new message
+     */
+    replaceMessage(path: string, uid: number, message: NewMessage): {
+        uid: number;
+        uidvalidity: number;
+    };
+    /**
+     * Creates a mailbox, with any missing superior levels
+     *
+     * @param {String} path Storage name
+     * @param {Object} [options] `{ subscribed }`
+     * @return {Object} mailbox info
+     */
+    createMailbox(path: string, options?: {
+        subscribed?: boolean | undefined;
+    }): MailboxInfo;
+    /**
+     * Deletes a mailbox. Sessions that have it selected are disconnected with BYE, like after DELETE in another session
+     *
+     * @param {String} path Storage name
+     */
+    deleteMailbox(path: string): void;
+    /**
+     * Renames a mailbox, with the RENAME rules (renaming INBOX moves its messages)
+     *
+     * @param {String} path Storage name
+     * @param {String} newPath New storage name
+     * @return {Object} info of the renamed mailbox
+     */
+    renameMailbox(path: string, newPath: string): MailboxInfo;
+    /**
+     * Gives a mailbox a new UIDVALIDITY, optionally with new UIDs ("keep", "renumber", "shuffle" or "offset"). Sessions
+     * that have the mailbox selected are disconnected with BYE, as a UID must not change during a session
+     *
+     * @param {String} path Storage name
+     * @param {Object} [options] `{ uidvalidity, uids, offset, seed }`
+     * @return {Object} `{ uidvalidity, uidnext, uids }`, `uids` lists `{ uid, newUid }` for every message
+     */
+    resetUidValidity(path: string, options?: UidValidityOptions): {
+        uidvalidity: number;
+        uidnext: number;
+        uids: {
+            uid: number;
+            newUid: number;
+        }[];
+    };
+    /**
+     * Subscribes a mailbox
+     *
+     * @param {String} path Storage name
+     * @return {Boolean} true if the subscription changed
+     */
+    subscribe(path: string): boolean;
+    /**
+     * Unsubscribes a name, it does not have to be a mailbox
+     *
+     * @param {String} path Storage name
+     * @return {Boolean} true if the subscription changed
+     */
+    unsubscribe(path: string): boolean;
+    /**
+     * Lists the users, without credentials
+     *
+     * @return {Array} `{ name, xoauth2 }`, xoauth2 is true for a user with an access token
+     */
+    listUsers(): {
+        name: string;
+        xoauth2: boolean;
+    }[];
+    /**
+     * Adds a user
+     *
+     * @param {String} name User name
+     * @param {Object} options `{ password, xoauth2: { accessToken, sessionTimeout } }`
+     */
+    addUser(name: string, options: UserOptions): void;
+    /**
+     * Changes the password or the XOAUTH2 token of a user
+     *
+     * @param {String} name User name
+     * @param {Object} options `{ password, xoauth2 }`, null xoauth2 removes the token
+     */
+    updateUser(name: string, options: UserOptions): void;
+    /**
+     * Deletes a user, its sessions are disconnected with BYE unless `disconnect` is false
+     *
+     * @param {String} name User name
+     * @param {Object} [options] `{ disconnect }`
+     */
+    deleteUser(name: string, options?: {
+        disconnect?: boolean | undefined;
+    }): void;
+    requireUser(name: unknown): UserData;
+    userData(user: UserData, options: UserOptions): UserData;
+    /**
+     * Disconnects sessions
+     *
+     * @param {Number|Object} filter A session number, or `{ session, user }`
+     * @param {Object} [options] `{ text, reset }`: the text of the untagged BYE, or reset the TCP connection without BYE
+     * @return {Number} how many sessions were disconnected
+     */
+    disconnect(filter: SessionFilter, options?: {
+        text?: string | undefined;
+        reset?: boolean | undefined;
+    }): number;
+    /**
+     * Writes bytes to a session as they are, e.g. an untagged response between commands (ALERT, BYE, EXISTS).
+     * Nothing checks that they are valid IMAP
+     *
+     * @param {Number} session Session number
+     * @param {String|Buffer} data Bytes to send, a string is encoded as UTF-8
+     */
+    inject(session: number, data: string | Uint8Array): void;
+    /**
+     * Restores the mailboxes and users of the server options and disconnects every session with BYE, so that a
+     * long running server (the imapkit command) can be reused between tests. Plugins restore their own state on
+     * the `reset` event (QUOTA limits, server annotations). Script rules stay, `server.script.clear()` removes them
+     */
+    reset(): void;
+    /**
+     * Stops the server. A graceful shutdown stops accepting connections and waits until the clients disconnect,
+     * otherwise the sessions are closed right away
+     *
+     * @param {Object} [options] `{ graceful }`, true by default
+     * @return {Promise} resolves when the server is closed
+     */
+    shutdown(options?: {
+        graceful?: boolean | undefined;
+    }): Promise<void>;
+}
+export { Control, ImapKitError };
+export type { MailboxInfo, MessageInfo, SessionInfo, NewMessage, UserOptions, SessionFilter, ControlRoute, RouteRequest };