imapflow 1.7.7 → 2.0.0

package/dist/esm/errors.d.ts

@@ -0,0 +1,83 @@
+import type { ImapResponse } from './handler/types.js';
+/**
+ * An Error raised by ImapFlow, with the extra properties the library attaches to describe
+ * the failure. Every property is optional: which ones are present depends on where the
+ * error came from.
+ */
+export interface ImapFlowError extends Error {
+    /** Error code, e.g. 'NoConnection', 'ETIMEOUT', 'LockTimeout' or a parser error code */
+    code?: string | undefined;
+    /** Connection id the error belongs to */
+    cid?: string | undefined;
+    /** Connection id, stamped by emitError() */
+    _connId?: string | undefined;
+    /** Which internal site rejected with this error */
+    rejectedFrom?: string | undefined;
+    /** The command that was affected */
+    command?: string | undefined;
+    /** The mailbox path that was affected */
+    path?: string | undefined;
+    /** Status of the tagged response that failed the command: 'NO' or 'BAD' */
+    responseStatus?: string | undefined;
+    /** Human readable text of the failed tagged response */
+    responseText?: string | undefined;
+    /** The server response: the parsed response, or its text once enhanceCommandError() ran */
+    response?: ImapResponse | string | false | undefined;
+    /** Response code of the failed tagged response, e.g. 'AUTHENTICATIONFAILED' */
+    serverResponseCode?: string | undefined;
+    /** The command as it was sent, for logging */
+    executedCommand?: string | undefined;
+    /** Set when authentication failed */
+    authenticationFailed?: boolean | undefined;
+    /** Set when a TLS or STARTTLS upgrade failed */
+    tlsFailed?: boolean | undefined;
+    /** Server suggested back-off in milliseconds for an ETHROTTLE error */
+    throttleReset?: number | undefined;
+    /** Additional details, e.g. the timeouts that applied */
+    details?: {
+        [key: string]: any;
+    } | undefined;
+    /** The underlying error */
+    _err?: Error | undefined;
+    /** Server BYE reason */
+    reason?: string | undefined;
+    /** Set when a mailbox could not be selected because it does not exist */
+    mailboxMissing?: boolean | undefined;
+    /** Id of the mailbox lock that timed out */
+    lockId?: number | undefined;
+    /** The parser error that failed a command completion */
+    parserError?: ImapFlowError | undefined;
+    /** Parser diagnostics */
+    parserContext?: {
+        [key: string]: any;
+    } | undefined;
+    /** The tag the parser had already read before it failed */
+    parsedTag?: string | undefined;
+    /** The declared size of a rejected literal */
+    literalSize?: number | undefined;
+    /** The length of a rejected line */
+    lineLength?: number | undefined;
+    /** The size of a rejected response */
+    responseSize?: number | undefined;
+    /** The bound that was exceeded */
+    maxSize?: number | undefined;
+    /** OAuth error details from the server, for XOAUTH2 authentication failures */
+    oauthError?: any;
+    /** The IMAP string that could not be parsed */
+    _imapStr?: string | undefined;
+}
+/**
+ * The fields a connection error is stamped with to say where it was rejected, see
+ * buildConnectionError() in tools.ts
+ */
+export type ConnectionErrorSite = Pick<ImapFlowError, 'rejectedFrom' | 'command' | 'path'>;
+/**
+ * Error subclass thrown when IMAP authentication fails.
+ */
+export declare class AuthenticationFailure extends Error implements ImapFlowError {
+    authenticationFailed: true;
+    serverResponseCode?: string | undefined;
+    /** Text of the server's error response */
+    response?: string | undefined;
+    oauthError?: any;
+}

package/dist/esm/errors.js

@@ -0,0 +1,9 @@
+/**
+ * Error subclass thrown when IMAP authentication fails.
+ */
+export class AuthenticationFailure extends Error {
+    constructor() {
+        super(...arguments);
+        this.authenticationFailed = true;
+    }
+}

package/dist/esm/handler/imap-compiler.d.ts

@@ -0,0 +1,24 @@
+import type { CompilerOptions, ImapCompileInput } from './types.js';
+/**
+ * Compiles an input object into a sequence of Buffers representing an IMAP protocol response string.
+ * Handles various node types including literals, strings, atoms, sections, sequences, and nested lists.
+ *
+ * @param response - The response object to compile.
+ * @param response.tag - The IMAP command tag (e.g., "*" or a sequence number).
+ * @param response.command - The IMAP command name.
+ * @param response.attributes - The response attributes to compile into IMAP format.
+ * @param options - Compilation options.
+ * @param options.asArray - If true, returns an array of Buffers (one per literal segment); otherwise returns a single concatenated Buffer.
+ * @param options.isLogging - If true, redacts sensitive values and truncates long strings/literals for logging purposes.
+ * @param options.literalPlus - If true, uses the LITERAL+ extension (appends "+" to literal length markers).
+ * @param options.literalMinus - If true, uses the LITERAL- extension for literals up to 4096 bytes.
+ * @returns A promise that resolves to an array of Buffers (if asArray is true) or a single concatenated Buffer.
+ */
+declare function compiler(response: ImapCompileInput, options: CompilerOptions & {
+    asArray: true;
+}): Promise<Buffer[]>;
+declare function compiler(response: ImapCompileInput, options?: (CompilerOptions & {
+    asArray?: false | undefined;
+}) | undefined): Promise<Buffer>;
+declare function compiler(response: ImapCompileInput, options?: CompilerOptions | undefined): Promise<Buffer | Buffer[]>;
+export default compiler;

package/{lib → dist/esm}/handler/imap-compiler.js

@@ -1,50 +1,41 @@
 /* eslint no-console: 0, new-cap: 0 */
-
-'use strict';
-
-const imapFormalSyntax = require('./imap-formal-syntax');
-
+import imapFormalSyntax from './imap-formal-syntax.js';
 // A single element of a sequence-set as defined by the RFC 9051 grammar: a number
 // or a range, where "*" stands for the largest number in use. Digit strings are not
 // range-checked here (a server rejects "0" or an overlong number on its own); the
 // point of the check is that nothing outside this alphabet can reach the wire.
 const SEQ_RANGE = /^(\d+|\*)(:(\d+|\*))?$/;
-
 // Validates a full sequence-set: comma-separated SEQ_RANGE elements, or "$"
 // (RFC 5182 SEARCHRES), which references the previous SEARCH result and is only
 // valid as the entire set. Split into per-element tests on purpose - a whole-set
 // regex with an unbounded repeat group overflows the regex engine's backtrack
 // stack with an uncoded RangeError on valid sets in the million-element range,
 // while the per-element regex is bounded.
-const isValidSequenceSet = value => value === '$' || value.split(',').every(part => SEQ_RANGE.test(part));
-
+const isValidSequenceSet = (value) => value === '$' || value.split(',').every(part => SEQ_RANGE.test(part));
 // Numeric tokens may only put the digit alphabet on the wire. Anything that does
 // not round to a bounded non-negative integer (NaN, Infinity, negatives, unsafe
 // magnitudes) degrades to 0 - the fallback the NaN coercion has always used.
-const safeNumber = value => {
+const safeNumber = (value) => {
     let num = Math.round(Number(value));
     return Number.isSafeInteger(num) && num >= 0 ? num : 0;
 };
-
 // Characters that cannot appear in an IMAP quoted string: CR and LF terminate a
 // command line, and NUL is outside the CHAR production entirely. A value carrying
 // any of them has to be sent as a literal, so quoting it is never correct.
 const NOT_QUOTABLE = /[\r\n\0]/;
-
 // A line terminator ends an IMAP command, so no token may carry one to the wire.
 const CRLF = /[\r\n]/;
-
 /**
  * Quotes a value as an IMAP quoted string. Only DQUOTE and backslash are escaped -
  * the IMAP grammar defines no other escape sequence, so JSON-style escaping (which
  * turns a tab into a literal backslash-t and a control character into \\uXXXX) would
  * silently change the value the server receives.
  *
- * @param {string} value - The value to quote.
- * @returns {string} The quoted string, ready to be written to the wire.
+ * @param value - The value to quote.
+ * @returns The quoted string, ready to be written to the wire.
  * @throws {Error} If the value contains CR, LF or NUL, which a quoted string cannot carry.
  */
-const quoteString = value => {
+const quoteString = (value) => {
     if (NOT_QUOTABLE.test(value)) {
         let error = new Error('Unquotable character in IMAP string value');
         error.code = 'InvalidStringValue';
@@ -52,26 +43,9 @@ const quoteString = value => {
     }
     return '"' + value.replace(/["\\]/g, char => '\\' + char) + '"';
 };
-
-/**
- * Compiles an input object into a sequence of Buffers representing an IMAP protocol response string.
- * Handles various node types including literals, strings, atoms, sections, sequences, and nested lists.
- *
- * @param {Object} response - The response object to compile.
- * @param {string} [response.tag] - The IMAP command tag (e.g., "*" or a sequence number).
- * @param {string} [response.command] - The IMAP command name.
- * @param {Array|Object} [response.attributes] - The response attributes to compile into IMAP format.
- * @param {Object} [options] - Compilation options.
- * @param {boolean} [options.asArray] - If true, returns an array of Buffers (one per literal segment); otherwise returns a single concatenated Buffer.
- * @param {boolean} [options.isLogging] - If true, redacts sensitive values and truncates long strings/literals for logging purposes.
- * @param {boolean} [options.literalPlus] - If true, uses the LITERAL+ extension (appends "+" to literal length markers).
- * @param {boolean} [options.literalMinus] - If true, uses the LITERAL- extension for literals up to 4096 bytes.
- * @returns {Promise<Buffer[]|Buffer>} A promise that resolves to an array of Buffers (if asArray is true) or a single concatenated Buffer.
- */
-module.exports = async (response, options) => {
+async function compiler(response, options) {
     let { asArray, isLogging, literalPlus, literalMinus } = options || {};
     const respParts = [];
-
     // Formats an entry (string, number or Buffer) into the Buffer that is written to
     // the wire, and is the choke point every emission passes through: a line
     // terminator ends an IMAP command, so no token - the tag and command name
@@ -88,33 +62,27 @@ module.exports = async (response, options) => {
             error.code = 'InvalidTokenValue';
             throw error;
         }
-
         if (typeof entry === 'string') {
             return Buffer.from(entry);
         }
-
         if (typeof entry === 'number') {
             return Buffer.from(entry.toString());
         }
-
         if (Buffer.isBuffer(entry)) {
             return entry;
         }
-
         if (returnEmpty) {
             return null;
         }
-
         return Buffer.alloc(0);
     };
-
-    let resp = [].concat(emitEntry(response.tag, { returnEmpty: true }) || []).concat(response.command ? emitEntry(' ' + response.command) : []);
+    let resp = []
+        .concat(emitEntry(response.tag, { returnEmpty: true }) || [])
+        .concat(response.command ? emitEntry(' ' + response.command) : []);
     let val;
     let lastType;
-
     let walk = async (node, options) => {
         options = options || {};
-
         // Determine whether a space separator is needed before this node.
         // Inspect the last byte written to decide context.
         let lastRespEntry = resp.length && resp[resp.length - 1];
@@ -122,7 +90,6 @@ module.exports = async (response, options) => {
         if (typeof lastRespByte === 'number') {
             lastRespByte = String.fromCharCode(lastRespByte);
         }
-
         // Add a space separator when:
         // - The previous token was a LITERAL. Literal data ends exactly at its declared length, so
         //   a following token always needs an explicit separator, even though the last written byte
@@ -136,65 +103,55 @@ module.exports = async (response, options) => {
                 resp.push(emitEntry(' '));
             }
         }
-
         if (node && node.buffer && !Buffer.isBuffer(node)) {
             // mongodb binary
             node = node.buffer;
         }
-
         if (Array.isArray(node)) {
             lastType = 'LIST';
             resp.push(emitEntry('('));
-
             // check if we need to skip separator WS between two arrays
             let subArray = node.length > 1 && Array.isArray(node[0]);
-
             for (let child of node) {
                 if (subArray && !Array.isArray(child)) {
                     subArray = false;
                 }
                 await walk(child, { subArray });
             }
-
             resp.push(emitEntry(')'));
             return;
         }
-
         if (!node && typeof node !== 'string' && typeof node !== 'number' && !Buffer.isBuffer(node)) {
             resp.push(emitEntry('NIL'));
             return;
         }
-
         if (typeof node === 'string' || Buffer.isBuffer(node)) {
             if (isLogging && node.length > 100) {
                 resp.push(emitEntry('"(* ' + node.length + 'B string *)"'));
-            } else {
+            }
+            else {
                 resp.push(emitEntry(isLogging ? JSON.stringify(node.toString()) : quoteString(node.toString())));
             }
             return;
         }
-
         if (typeof node === 'number') {
             resp.push(emitEntry(safeNumber(node))); // Only bounded non-negative integers allowed
             return;
         }
-
         lastType = node.type;
-
         if (isLogging && node.sensitive) {
             resp.push(emitEntry('"(* value hidden *)"'));
             return;
         }
-
         switch (node.type.toUpperCase()) {
             case 'LITERAL':
                 if (isLogging) {
                     resp.push(emitEntry('"(* ' + node.value.length + 'B literal *)"'));
-                } else {
+                }
+                else {
                     // The literal size marker counts octets - string values are written as
                     // UTF-8, so their UTF-16 .length would undercount multi-byte characters
                     let literalLength = !node.value ? 0 : Buffer.isBuffer(node.value) ? node.value.length : Buffer.byteLength(node.value.toString());
-
                     // Append '+' to the size marker only when the extension actually permits a
                     // non-synchronizing literal of this size (RFC 7888): LITERAL+ always,
                     // LITERAL- only up to 4096 bytes
@@ -203,16 +160,15 @@ module.exports = async (response, options) => {
                     // non-synchronizing literals always, and everything in single-buffer mode
                     // (asArray false), which has no continuation flow
                     let canAppend = !asArray || usePlus;
-
                     // Emit the literal header: optional '~' prefix for literal8, then {size[+]}\r\n
                     resp.push(emitEntry(`${node.isLiteral8 ? '~' : ''}{${literalLength}${usePlus ? '+' : ''}}\r\n`, { raw: true }));
-
                     if (canAppend) {
                         // Literal data follows immediately in the same buffer segment
                         if (node.value && node.value.length) {
                             resp.push(emitEntry(node.value, { raw: true }));
                         }
-                    } else {
+                    }
+                    else {
                         // For synchronizing literals in asArray mode, split output into separate
                         // parts. The caller must send each part and wait for a continuation
                         // response from the server before sending the next.
@@ -221,16 +177,15 @@ module.exports = async (response, options) => {
                     }
                 }
                 break;
-
             case 'STRING':
                 if (isLogging && node.value.length > 100) {
                     resp.push(emitEntry('"(* ' + node.value.length + 'B string *)"'));
-                } else {
+                }
+                else {
                     val = (node.value || '').toString();
                     resp.push(emitEntry(isLogging ? JSON.stringify(val) : quoteString(val)));
                 }
                 break;
-
             case 'SEQUENCE':
                 // Sequence sets are written verbatim - they are the one token type with
                 // no quoting to fall back on. Callers build them from user-supplied
@@ -255,7 +210,6 @@ module.exports = async (response, options) => {
                     resp.push(emitEntry(node.value, { raw: true }));
                 }
                 break;
-
             case 'TEXT':
                 // Response text is written verbatim. Only the parser produces it today, for
                 // incoming lines, so this is a re-encoding path rather than a command-building
@@ -270,18 +224,15 @@ module.exports = async (response, options) => {
                     resp.push(emitEntry(node.value));
                 }
                 break;
-
             case 'NUMBER':
                 // Coerced rather than written through: formatRespEntry passes a string or
                 // Buffer straight to the wire, so a numeric token carrying a string value
                 // would be another verbatim channel
                 resp.push(emitEntry(safeNumber(node.value)));
                 break;
-
             case 'ATOM':
             case 'SECTION':
                 val = (node.value || '').toString();
-
                 if (!node.section || val) {
                     // Verify the value contains only valid ATOM-CHAR characters.
                     // Strip a leading backslash before checking (system flags like \Seen start with '\').
@@ -290,19 +241,15 @@ module.exports = async (response, options) => {
                     if (node.value === '' || imapFormalSyntax.verify(val.charAt(0) === '\\' ? val.substr(1) : val, imapFormalSyntax['ATOM-CHAR']()) >= 0) {
                         val = isLogging ? JSON.stringify(val) : quoteString(val);
                     }
-
                     resp.push(emitEntry(val));
                 }
-
                 // Section bracket handling: emit [section-contents] after the ATOM value
                 // e.g., BODY[HEADER.FIELDS (Subject)] or BODY[1.MIME]
                 if (node.section) {
                     resp.push(emitEntry('['));
-
                     for (let child of node.section) {
                         await walk(child);
                     }
-
                     resp.push(emitEntry(']'));
                 }
                 // Partial range: emit <origin.length> after the section brackets. Coerced
@@ -316,21 +263,16 @@ module.exports = async (response, options) => {
                 break;
         }
     };
-
     if (response.attributes) {
         let attributes = Array.isArray(response.attributes) ? response.attributes : [].concat(response.attributes);
         for (let child of attributes) {
             await walk(child);
         }
     }
-
     if (resp.length) {
         respParts.push(resp);
     }
-
-    for (let i = 0; i < respParts.length; i++) {
-        respParts[i] = Buffer.concat(respParts[i]);
-    }
-
-    return asArray ? respParts : respParts.flatMap(entry => entry);
-};
+    const compiled = respParts.map(part => Buffer.concat(part));
+    return asArray ? compiled : compiled.flatMap(entry => entry);
+}
+export default compiler;

package/dist/esm/handler/imap-formal-syntax.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Verifies that every character in the given string is within the set of allowed characters.
+ *
+ * @param str - The string to validate.
+ * @param allowedChars - A string containing all allowed characters.
+ * @returns The index of the first disallowed character, or -1 if all characters are valid.
+ */
+declare function verify(str: string, allowedChars: string): number;
+declare const imapFormalSyntax: {
+    CHAR: () => string;
+    CHAR8: () => string;
+    SP: () => string;
+    CTL: () => string;
+    DQUOTE: () => string;
+    ALPHA: () => string;
+    DIGIT: () => string;
+    'ATOM-CHAR': () => string;
+    'ASTRING-CHAR': () => string;
+    'TEXT-CHAR': () => string;
+    'atom-specials': () => string;
+    'list-wildcards': () => string;
+    'quoted-specials': () => string;
+    'resp-specials': () => string;
+    tag: () => string;
+    command: () => string;
+    verify: typeof verify;
+};
+export default imapFormalSyntax;

package/dist/esm/handler/imap-formal-syntax.js

@@ -0,0 +1,117 @@
+/* eslint new-cap: 0, no-useless-concat: 0 */
+/**
+ * Defines the IMAP formal syntax character classes and validation rules as specified
+ * in RFC 3501 Section 9 (http://tools.ietf.org/html/rfc3501#section-9).
+ *
+ * Each exported method returns a string of allowed characters for a given IMAP grammar
+ * production rule (e.g., ATOM-CHAR, ASTRING-CHAR, TEXT-CHAR). Results are computed once,
+ * on first use, and cached at module level.
+ *
+ * Also exports a `verify` function for validating strings against a set of allowed characters.
+ */
+/**
+ * Generates a string containing all characters in the given Unicode code point range (inclusive).
+ *
+ * @param start - The starting character code point.
+ * @param end - The ending character code point.
+ * @returns A string containing all characters from start to end.
+ */
+function expandRange(start, end) {
+    let chars = [];
+    for (let i = start; i <= end; i++) {
+        chars.push(i);
+    }
+    return String.fromCharCode(...chars);
+}
+/**
+ * Returns a new string with all characters from the exclude string removed from the source string.
+ *
+ * @param source - The source string to filter.
+ * @param exclude - A string of characters to exclude from the source.
+ * @returns The source string with excluded characters removed.
+ */
+function excludeChars(source, exclude) {
+    return Array.prototype.filter.call(source, (ch) => exclude.indexOf(ch) < 0).join('');
+}
+/**
+ * Wraps a computation so that it runs once, on first call, and the result is reused afterwards.
+ *
+ * @param compute - Produces the character set.
+ * @returns A zero-argument function returning the cached character set.
+ */
+function memo(compute) {
+    let value = null;
+    return () => {
+        if (value === null) {
+            value = compute();
+        }
+        return value;
+    };
+}
+/** All 7-bit US-ASCII characters excluding NUL (0x01-0x7F). */
+const CHAR = memo(() => expandRange(0x01, 0x7f));
+/** All 8-bit characters excluding NUL (0x01-0xFF). */
+const CHAR8 = memo(() => expandRange(0x01, 0xff));
+/** The space character (0x20). */
+const SP = () => ' ';
+/** All control characters (0x00-0x1F and 0x7F). */
+const CTL = memo(() => expandRange(0x00, 0x1f) + '\x7F');
+/** The double-quote character. */
+const DQUOTE = () => '"';
+/** All uppercase and lowercase ASCII alphabetic characters (A-Z, a-z). */
+const ALPHA = memo(() => expandRange(0x41, 0x5a) + expandRange(0x61, 0x7a));
+/** All ASCII digit characters (0-9). */
+const DIGIT = memo(() => expandRange(0x30, 0x39));
+/** The LIST wildcard characters ("%" and "*"). */
+const listWildcards = () => '%' + '*';
+/** Characters that are special inside quoted strings (DQUOTE and backslash). */
+const quotedSpecials = memo(() => DQUOTE() + '\\');
+/** The response-special character ("]"). */
+const respSpecials = () => ']';
+/** Characters that are special in ATOMs and must be excluded: "(", ")", "{", SP, CTL, list-wildcards, quoted-specials, resp-specials. */
+const atomSpecials = memo(() => '(' + ')' + '{' + SP() + CTL() + listWildcards() + quotedSpecials() + respSpecials());
+/** Characters allowed in an IMAP ATOM (CHAR minus atom-specials). */
+const atomChar = memo(() => excludeChars(CHAR(), atomSpecials()));
+/** Characters allowed in an IMAP ASTRING (ATOM-CHAR plus resp-specials). */
+const astringChar = memo(() => atomChar() + respSpecials());
+/** Characters allowed in IMAP text (CHAR minus CR and LF). */
+const textChar = memo(() => excludeChars(CHAR(), '\r\n'));
+/** Characters allowed in an IMAP tag (ASTRING-CHAR minus "+"). */
+const tag = memo(() => excludeChars(astringChar(), '+'));
+/** Characters allowed in an IMAP command name (ALPHA, DIGIT, and hyphen). */
+const command = memo(() => ALPHA() + DIGIT() + '-');
+/**
+ * Verifies that every character in the given string is within the set of allowed characters.
+ *
+ * @param str - The string to validate.
+ * @param allowedChars - A string containing all allowed characters.
+ * @returns The index of the first disallowed character, or -1 if all characters are valid.
+ */
+function verify(str, allowedChars) {
+    for (let i = 0, len = str.length; i < len; i++) {
+        if (allowedChars.indexOf(str.charAt(i)) < 0) {
+            return i;
+        }
+    }
+    return -1;
+}
+const imapFormalSyntax = {
+    CHAR,
+    CHAR8,
+    SP,
+    CTL,
+    DQUOTE,
+    ALPHA,
+    DIGIT,
+    'ATOM-CHAR': atomChar,
+    'ASTRING-CHAR': astringChar,
+    'TEXT-CHAR': textChar,
+    'atom-specials': atomSpecials,
+    'list-wildcards': listWildcards,
+    'quoted-specials': quotedSpecials,
+    'resp-specials': respSpecials,
+    tag,
+    command,
+    verify
+};
+export default imapFormalSyntax;

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

@@ -0,0 +1,9 @@
+import parser from './imap-parser.js';
+import compiler from './imap-compiler.js';
+/**
+ * Re-exports the IMAP protocol parser and compiler as a single module.
+ *
+ * - `parser` parses raw IMAP command/response buffers into structured objects.
+ * - `compiler` compiles structured response objects into IMAP protocol Buffers.
+ */
+export { parser, compiler };

package/dist/esm/handler/imap-handler.js

@@ -0,0 +1,9 @@
+import parser from './imap-parser.js';
+import compiler from './imap-compiler.js';
+/**
+ * Re-exports the IMAP protocol parser and compiler as a single module.
+ *
+ * - `parser` parses raw IMAP command/response buffers into structured objects.
+ * - `compiler` compiles structured response objects into IMAP protocol Buffers.
+ */
+export { parser, compiler };

package/dist/esm/handler/imap-parser.d.ts

@@ -0,0 +1,16 @@
+import type { ImapResponse, ParserOptions } from './types.js';
+/**
+ * Parses a raw IMAP command or response buffer into a structured object.
+ * Handles edge cases such as null-byte-padded responses from buggy servers and
+ * multi-word commands like UID and AUTHENTICATE.
+ *
+ * @param command - The raw IMAP command or response data to parse.
+ * @param options - Parser options passed through to the underlying ParserInstance and TokenParser.
+ * @param options.literalPlus - Whether the LITERAL+ extension is in use.
+ * @param options.literals - Pre-parsed literal values extracted from the input stream.
+ * @returns A promise that resolves to a parsed response object with `tag` (the IMAP tag, e.g. "*",
+ *   "+", or a command tag like "A1"), `command` (the IMAP command or response name, e.g. "OK",
+ *   "FETCH"), `attributes` (parsed attributes of the response) and `nullBytesRemoved` (number of
+ *   leading null bytes removed, if any).
+ */
+export default function parser(command: Buffer | string, options?: ParserOptions | undefined): Promise<ImapResponse>;