imapflow 1.7.8 → 2.0.0

package/dist/cjs/commands/authenticate.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = authenticate;
+const tools_js_1 = require("../tools.js");
+/**
+ * Handles authentication errors by enriching the error object with server response details.
+ *
+ * @param err - The original authentication error
+ * @param errorResponse - Optional OAuth error response from the server
+ * @returns The enriched error; the caller is expected to throw it
+ */
+async function handleAuthError(err, errorResponse) {
+    let errorCode = (0, tools_js_1.getStatusCode)(err.response);
+    if (errorCode) {
+        err.serverResponseCode = errorCode;
+    }
+    err.authenticationFailed = true;
+    err.response = await (0, tools_js_1.getErrorText)(err.response);
+    if (errorResponse) {
+        err.oauthError = errorResponse;
+    }
+    return err;
+}
+/**
+ * Authenticates using OAuth (OAUTHBEARER or XOAUTH2).
+ *
+ * @param connection - IMAP connection instance
+ * @param username - The username to authenticate with
+ * @param accessToken - The OAuth2 access token
+ * @returns The authenticated username
+ * @throws {Error} If authentication fails
+ */
+async function authOauth(connection, username, accessToken) {
+    let oauthbearer;
+    let command;
+    let breaker;
+    if (connection.capabilities.has('AUTH=OAUTHBEARER')) {
+        // OAUTHBEARER payload per RFC 7628: fields separated by \x01 (SASL GS2 framing).
+        // Format: "n,a=<user>," \x01 "host=..." \x01 "port=..." \x01 "auth=Bearer <token>" \x01 \x01
+        // The trailing empty strings produce the required double-\x01 terminator.
+        // Both fields must describe the connection actually in use. The port was hardcoded to 993,
+        // so an OAuth2 server reached over 143/STARTTLS advertised a payload that did not match, and
+        // `servername` is set to false for a bare-IP host, which rendered as a literal "host=false".
+        // A server validating either field rejects with status `invalid_request` - a permanent
+        // failure that refreshing the access token can never clear.
+        oauthbearer = [
+            `n,a=${username},`,
+            `host=${connection.servername || connection.host}`,
+            `port=${connection.port}`,
+            `auth=Bearer ${accessToken}`,
+            '',
+            ''
+        ].join('\x01');
+        command = 'OAUTHBEARER';
+        // "AQ==" is base64 for \x01, sent as the error continuation to abort the SASL exchange
+        breaker = 'AQ==';
+    }
+    else if (connection.capabilities.has('AUTH=XOAUTH') || connection.capabilities.has('AUTH=XOAUTH2')) {
+        // XOAUTH2 payload (Google-specific): simpler format, also \x01-delimited.
+        // Format: "user=<user>" \x01 "auth=Bearer <token>" \x01 \x01
+        oauthbearer = [`user=${username}`, `auth=Bearer ${accessToken}`, '', ''].join('\x01');
+        command = 'XOAUTH2';
+        // Empty breaker: XOAUTH2 expects an empty response to abort the SASL exchange
+        breaker = '';
+    }
+    let errorResponse = false;
+    try {
+        let response = await connection.exec('AUTHENTICATE', [
+            { type: 'ATOM', value: command },
+            { type: 'ATOM', value: Buffer.from(oauthbearer).toString('base64'), sensitive: true }
+        ], {
+            // Server sends a "+" continuation if auth fails, with a base64 JSON error payload.
+            // We decode it for diagnostics, then send the breaker to terminate the exchange.
+            onPlusTag: async (resp) => {
+                if (resp.attributes && resp.attributes[0] && resp.attributes[0].type === 'TEXT') {
+                    try {
+                        errorResponse = JSON.parse(Buffer.from(resp.attributes[0].value, 'base64').toString());
+                    }
+                    catch (err) {
+                        connection.log.debug({
+                            msg: 'Failed to parse OAuth error response',
+                            errorResponse: resp.attributes[0].value,
+                            err,
+                            cid: connection.id
+                        });
+                    }
+                }
+                connection.log.debug({ src: 'c', msg: breaker, comment: `Error response for ${command}`, cid: connection.id });
+                connection.write(breaker);
+            }
+        });
+        response.next();
+        connection.authCapabilities.set(`AUTH=${command}`, true);
+        return username;
+    }
+    catch (err) {
+        throw await handleAuthError(err, errorResponse);
+    }
+}
+/**
+ * Authenticates using the SASL LOGIN mechanism.
+ *
+ * @param connection - IMAP connection instance
+ * @param username - The username to authenticate with
+ * @param password - The password to authenticate with
+ * @returns The authenticated username
+ * @throws {Error} If authentication fails
+ */
+async function authLogin(connection, username, password) {
+    let errorResponse = false;
+    try {
+        // SASL LOGIN is a challenge-response mechanism: the server sends base64-encoded
+        // prompts ("Username:" and "Password:") and the client responds with base64-encoded values.
+        let response = await connection.exec('AUTHENTICATE', [{ type: 'ATOM', value: 'LOGIN' }], {
+            onPlusTag: async (resp) => {
+                if (resp.attributes && resp.attributes[0] && resp.attributes[0].type === 'TEXT') {
+                    // Decode the server's base64 challenge to determine what it's asking for.
+                    // Strip trailing colons and null bytes (\x00) that some servers append to the prompt.
+                    let question = Buffer.from(resp.attributes[0].value, 'base64')
+                        .toString()
+                        .toLowerCase()
+                        .replace(/[:\x00]*$/, '');
+                    if (question === 'username' || question === 'user name') {
+                        let encodedUsername = Buffer.from(username).toString('base64');
+                        connection.log.debug({ src: 'c', msg: encodedUsername, comment: `Encoded username for AUTH=LOGIN`, cid: connection.id });
+                        connection.write(encodedUsername);
+                    }
+                    else if (question === 'password') {
+                        connection.log.debug({ src: 'c', msg: '(* value hidden *)', comment: `Encoded password for AUTH=LOGIN`, cid: connection.id });
+                        connection.write(Buffer.from(password).toString('base64'));
+                    }
+                    else {
+                        throw new Error(`Unknown LOGIN question "${question}"`);
+                    }
+                }
+            }
+        });
+        response.next();
+        connection.authCapabilities.set(`AUTH=LOGIN`, true);
+        return username;
+    }
+    catch (err) {
+        throw await handleAuthError(err, errorResponse);
+    }
+}
+/**
+ * Authenticates using the SASL PLAIN mechanism.
+ *
+ * @param connection - IMAP connection instance
+ * @param username - The authentication identity (authcid)
+ * @param password - The password to authenticate with
+ * @param authzid - Optional authorization identity to impersonate
+ * @returns The authorized identity (authzid if provided, otherwise username)
+ * @throws {Error} If authentication fails
+ */
+async function authPlain(connection, username, password, authzid) {
+    let errorResponse = false;
+    try {
+        let response = await connection.exec('AUTHENTICATE', [{ type: 'ATOM', value: 'PLAIN' }], {
+            onPlusTag: async () => {
+                // SASL PLAIN format: [authzid]\x00authcid\x00password
+                // authzid: authorization identity (who to impersonate)
+                // authcid: authentication identity (who is authenticating)
+                let authzidValue = authzid || '';
+                let encodedResponse = Buffer.from([authzidValue, username, password].join('\x00')).toString('base64');
+                let loggedResponse = Buffer.from([authzidValue, username, '(* value hidden *)'].join('\x00')).toString('base64');
+                connection.log.debug({
+                    src: 'c',
+                    msg: loggedResponse,
+                    comment: `Encoded response for AUTH=PLAIN${authzid ? ' with authzid' : ''}`,
+                    cid: connection.id
+                });
+                connection.write(encodedResponse);
+            }
+        });
+        response.next();
+        connection.authCapabilities.set(`AUTH=PLAIN`, true);
+        // Return the identity we're authorized as (authzid if provided, otherwise username)
+        return authzid || username;
+    }
+    catch (err) {
+        throw await handleAuthError(err, errorResponse);
+    }
+}
+/**
+ * Authenticates user using the best available method.
+ *
+ * @param connection - IMAP connection instance
+ * @param username - The username to authenticate with
+ * @param credentials - Authentication credentials
+ * @returns The authenticated username, or undefined if already authenticated
+ * @throws {Error} If no supported authentication mechanism is available or if authentication fails
+ */
+async function authenticate(connection, username, { accessToken, password, loginMethod, authzid }) {
+    if (connection.state !== connection.states.NOT_AUTHENTICATED) {
+        // nothing to do here
+        return;
+    }
+    // Authentication method selection order:
+    // 1. OAuth (OAUTHBEARER > XOAUTH2), preferred when an accessToken is provided,
+    //    as it avoids transmitting passwords entirely.
+    // 2. SASL PLAIN, preferred over LOGIN because it supports authzid (impersonation)
+    //    and sends credentials in a single round trip.
+    // 3. SASL LOGIN, the fallback; an older challenge-response mechanism (two round trips).
+    // If loginMethod is explicitly set, it overrides the automatic capability-based selection.
+    if (accessToken) {
+        // AUTH=OAUTHBEARER and AUTH=XOAUTH in the context of OAuth2 or very similar so we can handle these together
+        if (connection.capabilities.has('AUTH=OAUTHBEARER') || connection.capabilities.has('AUTH=XOAUTH') || connection.capabilities.has('AUTH=XOAUTH2')) {
+            return await authOauth(connection, username, accessToken);
+        }
+    }
+    if (password) {
+        if ((!loginMethod && connection.capabilities.has('AUTH=PLAIN')) || loginMethod === 'AUTH=PLAIN') {
+            return await authPlain(connection, username, password, authzid);
+        }
+        if ((!loginMethod && connection.capabilities.has('AUTH=LOGIN')) || loginMethod === 'AUTH=LOGIN') {
+            return await authLogin(connection, username, password);
+        }
+    }
+    throw new Error('Unsupported authentication mechanism');
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/capability.d.ts

@@ -0,0 +1,8 @@
+import type { ImapFlow } from '../imap-flow.js';
+/**
+ * Refreshes capabilities from server.
+ *
+ * @param connection - IMAP connection instance
+ * @returns Server capabilities map, or false on failure
+ */
+export default function capability(connection: ImapFlow): Promise<Map<string, boolean | number> | false>;

package/dist/cjs/commands/capability.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = capability;
+/**
+ * Refreshes capabilities from server.
+ *
+ * @param connection - IMAP connection instance
+ * @returns Server capabilities map, or false on failure
+ */
+// Capabilities are normally received and updated by the global response handler
+// (e.g., from the server greeting or after authentication). This explicit CAPABILITY
+// command is only needed when capabilities must be refreshed on demand, such as
+// after STARTTLS or when the server signals a capability change.
+async function capability(connection) {
+    if (connection.capabilities.size && !connection.expectCapabilityUpdate) {
+        return connection.capabilities;
+    }
+    let response;
+    try {
+        // The actual parsing of the untagged CAPABILITY response is handled by the
+        // global handler, not here. We just trigger the server to send it.
+        response = await connection.exec('CAPABILITY');
+        response.next();
+        return connection.capabilities;
+    }
+    catch (err) {
+        connection.log.warn({ err, cid: connection.id });
+        return false;
+    }
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/close.d.ts

@@ -0,0 +1,8 @@
+import type { ImapFlow } from '../imap-flow.js';
+/**
+ * Closes the currently selected mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @returns True on success, false on failure, or undefined if not in SELECTED state
+ */
+export default function close(connection: ImapFlow): Promise<boolean | undefined>;

package/dist/cjs/commands/close.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = close;
+/**
+ * Closes the currently selected mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @returns True on success, false on failure, or undefined if not in SELECTED state
+ */
+async function close(connection) {
+    if (connection.state !== connection.states.SELECTED) {
+        // nothing to do here
+        return;
+    }
+    let response;
+    try {
+        // IMAP CLOSE (RFC 3501 6.4.2): permanently removes all messages flagged \Deleted
+        // from the currently selected mailbox (implicit expunge) and deselects it.
+        // Unlike EXPUNGE, CLOSE does not send individual untagged EXPUNGE responses.
+        response = await connection.exec('CLOSE');
+        response.next();
+        // Transition from SELECTED back to AUTHENTICATED state.
+        // Clear mailbox metadata so subsequent operations know no mailbox is selected.
+        let currentMailbox = connection.mailbox;
+        connection.mailbox = false;
+        connection.currentSelectCommand = false;
+        connection.state = connection.states.AUTHENTICATED;
+        if (currentMailbox) {
+            connection.emit('mailboxClose', currentMailbox);
+        }
+        return true;
+    }
+    catch (err) {
+        connection.log.warn({ err, cid: connection.id });
+        return false;
+    }
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/compress.d.ts

@@ -0,0 +1,8 @@
+import type { ImapFlow } from '../imap-flow.js';
+/**
+ * Requests DEFLATE compression from the server.
+ *
+ * @param connection - IMAP connection instance
+ * @returns True if compression was enabled, false otherwise
+ */
+export default function compress(connection: ImapFlow): Promise<boolean>;

package/dist/cjs/commands/compress.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = compress;
+/**
+ * Requests DEFLATE compression from the server.
+ *
+ * @param connection - IMAP connection instance
+ * @returns True if compression was enabled, false otherwise
+ */
+// COMPRESS=DEFLATE (RFC 4978): enables zlib compression on the IMAP connection
+// to reduce bandwidth. Once enabled, all subsequent data in both directions is compressed.
+async function compress(connection) {
+    // Skip if the server doesn't support COMPRESS=DEFLATE, or if compression
+    // is already active (connection._inflate exists) to avoid double-compression.
+    if (!connection.capabilities.has('COMPRESS=DEFLATE') || connection._inflate) {
+        // nothing to do here
+        return false;
+    }
+    let response;
+    try {
+        response = await connection.exec('COMPRESS', [{ type: 'ATOM', value: 'DEFLATE' }]);
+    }
+    catch (err) {
+        // The server declined (NO/BAD): nothing switched, staying uncompressed is safe.
+        connection.log.warn({ err, cid: connection.id });
+        return false;
+    }
+    // Everything after the tagged OK is already deflate-framed (RFC 4978 section 4) -
+    // the server switches at the OK, so declining the upgrade at this point is not a
+    // protocol option. The socket stays piped into the plaintext parser until the
+    // transport swaps in the inflater, so bytes that arrived in the same chunk as the
+    // OK have been consumed as cleartext and are missing from the head of the deflate
+    // stream: the session is unrecoverable in both directions. Fail it immediately
+    // (the same way STARTTLS treats post-OK trailing data) instead of letting it die
+    // slowly on garbage. Closing this window without failing needs the stream to hand
+    // back its unconsumed tail on unpipe so the transport can feed it into the
+    // inflater - not something a command module can reach from here.
+    if (response.hasTrailingData) {
+        let error = new Error('Server sent data between the COMPRESS response and the compression layer switch');
+        error.code = 'COMPRESS_TRAILING_DATA';
+        connection.log.error({ err: error, cid: connection.id });
+        // Schedule the close before releasing parser backpressure, so the buffered
+        // deflate-framed bytes cannot settle anything before teardown begins. This is
+        // why the decision lives here rather than at the connection layer the way the
+        // STARTTLS guard does (starttls.ts records a flag, upgradeToSTARTTLS decides):
+        // only the command module holds the response before its backpressure release,
+        // so only it can order teardown ahead of that release.
+        connection.closeAfter();
+        response.next();
+        throw error;
+    }
+    response.next();
+    return true;
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/copy.d.ts

@@ -0,0 +1,13 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { CopyResponseObject, MessageRangeOptions } from '../types.js';
+/**
+ * Copies 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 - Copy options
+ * @param options.uid - If true, use UID COPY instead of COPY
+ * @returns Copy result with UID mapping if available, false on failure, or undefined if preconditions not met
+ */
+export default function copy(connection: ImapFlow, range: string, destination: string | string[], options?: MessageRangeOptions | undefined): Promise<CopyResponseObject | false | undefined>;

package/dist/cjs/commands/copy.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = copy;
+const tools_js_1 = require("../tools.js");
+const copyuid_parser_js_1 = require("./copyuid-parser.js");
+/**
+ * Copies 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 - Copy options
+ * @param options.uid - If true, use UID COPY instead of COPY
+ * @returns Copy result with UID mapping if available, false on failure, or undefined if preconditions not met
+ */
+async function copy(connection, range, destination, options) {
+    if (connection.state !== connection.states.SELECTED || !range || !destination) {
+        // nothing to do here
+        return;
+    }
+    options = options || {};
+    destination = (0, tools_js_1.normalizePath)(connection, destination);
+    let attributes = [
+        { type: 'SEQUENCE', value: range },
+        { type: 'ATOM', value: (0, tools_js_1.encodePath)(connection, destination) }
+    ];
+    let response;
+    try {
+        response = await connection.exec(options.uid ? 'UID COPY' : 'COPY', attributes);
+        response.next();
+        let map = { path: connection.mailbox.path, destination };
+        // UIDPLUS (RFC 4315): the server may include a COPYUID response code in the
+        // tagged OK response, providing a mapping from source UIDs to destination UIDs.
+        (0, copyuid_parser_js_1.parseCopyUid)(response.response, map);
+        return map;
+    }
+    catch (err) {
+        await (0, tools_js_1.enhanceCommandError)(err);
+        connection.log.warn({ err, cid: connection.id });
+        return false;
+    }
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/copyuid-parser.d.ts

@@ -0,0 +1,11 @@
+import type { ImapResponse } from '../handler/types.js';
+import type { CopyResponseObject } from '../types.js';
+/**
+ * Parses COPYUID response code from an IMAP response (RFC 4315).
+ * Used by both COPY and MOVE commands to extract the UID mapping
+ * from source mailbox to destination mailbox.
+ *
+ * @param response - IMAP response object with attributes
+ * @param map - Result map to populate with uidValidity and uidMap
+ */
+export declare function parseCopyUid(response: ImapResponse, map: CopyResponseObject): void;

package/dist/cjs/commands/copyuid-parser.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCopyUid = parseCopyUid;
+const tools_js_1 = require("../tools.js");
+/**
+ * Parses COPYUID response code from an IMAP response (RFC 4315).
+ * Used by both COPY and MOVE commands to extract the UID mapping
+ * from source mailbox to destination mailbox.
+ *
+ * @param response - IMAP response object with attributes
+ * @param map - Result map to populate with uidValidity and uidMap
+ */
+function parseCopyUid(response, map) {
+    let section = response.attributes && response.attributes[0] && response.attributes[0].section;
+    let responseCode = section && section.length && section[0] && typeof section[0].value === 'string' ? section[0].value : '';
+    if (responseCode !== 'COPYUID') {
+        return;
+    }
+    // A COPYUID code always comes with its section, see responseCode above
+    let codeSection = section;
+    // Only a bounded pure digit string is accepted: isNaN() also passes values like "1e5" or
+    // "Infinity", which BigInt() then rejects with a throw that loses the uidMap.
+    let uidValidity = (0, tools_js_1.parseBigIntValue)(codeSection[1] && codeSection[1].value);
+    if (uidValidity !== false) {
+        map.uidValidity = uidValidity;
+    }
+    const sourceUids = codeSection[2] && typeof codeSection[2].value === 'string' ? (0, tools_js_1.expandRange)(codeSection[2].value) : false;
+    const destinationUids = codeSection[3] && typeof codeSection[3].value === 'string' ? (0, tools_js_1.expandRange)(codeSection[3].value) : false;
+    if (sourceUids && destinationUids && sourceUids.length === destinationUids.length) {
+        map.uidMap = new Map(sourceUids.map((uid, i) => [uid, destinationUids[i]]));
+    }
+}

package/dist/cjs/commands/create.d.ts

@@ -0,0 +1,11 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { MailboxCreateResponse } from '../types.js';
+/**
+ * Creates a new mailbox and subscribes to it.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to create
+ * @returns Object with path and creation status, or undefined if preconditions not met
+ * @throws If the CREATE command fails (except when mailbox already exists)
+ */
+export default function create(connection: ImapFlow, path: string | string[]): Promise<MailboxCreateResponse | undefined>;

package/dist/cjs/commands/create.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = create;
+const tools_js_1 = require("../tools.js");
+/**
+ * Creates a new mailbox and subscribes to it.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to create
+ * @returns Object with path and creation status, or undefined if preconditions not met
+ * @throws If the CREATE command fails (except when mailbox already exists)
+ */
+async function create(connection, path) {
+    if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
+        // nothing to do here
+        return;
+    }
+    path = (0, tools_js_1.normalizePath)(connection, path);
+    let response;
+    try {
+        let map = {
+            path
+        };
+        response = await connection.exec('CREATE', [{ type: 'ATOM', value: (0, tools_js_1.encodePath)(connection, path) }]);
+        // Parse the response code section (e.g., [MAILBOXID (<id>)]) from the tagged OK response.
+        // IMAP response code attributes are structured as alternating key-value pairs.
+        let section = response.response.attributes &&
+            response.response.attributes[0] &&
+            response.response.attributes[0].section &&
+            response.response.attributes[0].section.length
+            ? response.response.attributes[0].section
+            : false;
+        if (section) {
+            let key;
+            section.forEach((attribute, i) => {
+                // IMAP key-value pairs: even indices (i % 2 === 0) are keys, odd indices are values
+                if (i % 2 === 0) {
+                    key = attribute && typeof attribute.value === 'string' ? attribute.value : false;
+                    return;
+                }
+                if (!key) {
+                    return;
+                }
+                let value;
+                switch (key.toLowerCase()) {
+                    case 'mailboxid':
+                        key = 'mailboxId';
+                        value = Array.isArray(attribute) && attribute[0] && typeof attribute[0].value === 'string' ? attribute[0].value : false;
+                        break;
+                }
+                if (key && value) {
+                    map[key] = value;
+                }
+            });
+        }
+        map.created = true;
+        response.next();
+        // Auto-subscribe after creation so the new mailbox appears in LSUB listings
+        // and is visible to clients that only show subscribed folders.
+        await connection.run('SUBSCRIBE', path);
+        return map;
+    }
+    catch (err) {
+        let errorCode = (0, tools_js_1.getStatusCode)(err.response);
+        // ALREADYEXISTS (RFC 5530) means the mailbox already exists on the server.
+        // This is not a true error, we return created:false to indicate nothing was created.
+        if (errorCode === 'ALREADYEXISTS') {
+            // no need to do anything, mailbox already exists
+            return {
+                path,
+                created: false
+            };
+        }
+        await (0, tools_js_1.enhanceCommandError)(err);
+        connection.log.warn({ err, cid: connection.id });
+        throw err;
+    }
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/delete.d.ts

@@ -0,0 +1,11 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { MailboxDeleteResponse } from '../types.js';
+/**
+ * Deletes an existing mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to delete
+ * @returns Object with the deleted path, or undefined if preconditions not met
+ * @throws If the DELETE command fails
+ */
+export default function deleteMailbox(connection: ImapFlow, path: string | string[]): Promise<MailboxDeleteResponse | undefined>;

package/dist/cjs/commands/delete.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = deleteMailbox;
+const tools_js_1 = require("../tools.js");
+/**
+ * Deletes an existing mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param path - Mailbox path to delete
+ * @returns Object with the deleted path, or undefined if preconditions not met
+ * @throws If the DELETE command fails
+ */
+async function deleteMailbox(connection, path) {
+    if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state)) {
+        // nothing to do here
+        return;
+    }
+    path = (0, tools_js_1.normalizePath)(connection, path);
+    // If the mailbox to delete is currently selected, we must close/deselect it first.
+    // IMAP servers reject DELETE on the currently selected mailbox (RFC 3501 6.3.4).
+    if (connection.state === connection.states.SELECTED && connection.mailbox.path === path) {
+        await connection.run('CLOSE');
+    }
+    let response;
+    try {
+        let map = {
+            path
+        };
+        response = await connection.exec('DELETE', [{ type: 'ATOM', value: (0, tools_js_1.encodePath)(connection, path) }]);
+        response.next();
+        return map;
+    }
+    catch (err) {
+        await (0, tools_js_1.enhanceCommandError)(err);
+        connection.log.warn({ err, cid: connection.id });
+        throw err;
+    }
+}
+module.exports = exports.default;
+Object.defineProperty(module.exports, 'default', { value: exports.default, enumerable: false, writable: true, configurable: true });

package/dist/cjs/commands/enable.d.ts

@@ -0,0 +1,9 @@
+import type { ImapFlow } from '../imap-flow.js';
+/**
+ * Enables IMAP extensions on the server.
+ *
+ * @param connection - IMAP connection instance
+ * @param extensionList - List of extension names to enable
+ * @returns Set of enabled extensions, false on failure, or undefined if not applicable
+ */
+export default function enable(connection: ImapFlow, extensionList: string[]): Promise<Set<string> | false | undefined>;