imapflow 1.7.7 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [2.0.0](https://github.com/postalsys/imapflow/compare/v1.7.8...v2.0.0) (2026-09-07)
+
+
+### ⚠ BREAKING CHANGES
+
+* Node.js 20 or newer is required. The `lib/` directory is no longer published; use the package root or the `imapflow/lib/*` export map.
+
+### Features
+
+* migrate to TypeScript with ES module and CommonJS builds ([a2cde07](https://github.com/postalsys/imapflow/commit/a2cde0778f6d7cb8471ca8e4011534476442ae98))
+* support Bun and Cloudflare Workers ([70fff15](https://github.com/postalsys/imapflow/commit/70fff15b4a3297d4b29c8da7b1faf703ebf00876))
+
+
+### Bug Fixes
+
+* re-arm auto-IDLE after an IDLE or poll session ends on its own ([e6e5d27](https://github.com/postalsys/imapflow/commit/e6e5d27debf87748aae740b5a0a47b2afc2079b3))
+* **types:** strip the internal members of ImapFlow from the declarations ([68b7258](https://github.com/postalsys/imapflow/commit/68b72587e07ebba52676df5b68631d60f55b08c0))
+* **types:** type AuthenticationFailure.response as the string it always is ([5c3b3af](https://github.com/postalsys/imapflow/commit/5c3b3afd234bccf7d86fd999f4673e43ec131b6d))
+* **types:** type the events without the generic EventEmitter of @types/node ([a4285b2](https://github.com/postalsys/imapflow/commit/a4285b26064115bd1740b7850b2b0a14e02d96b8))
+
+## [1.7.8](https://github.com/postalsys/imapflow/compare/v1.7.7...v1.7.8) (2026-09-01)
+
+
+### Bug Fixes
+
+* **download:** keep the pipeline error forwarder across a backpressure wait ([c6b2ed7](https://github.com/postalsys/imapflow/commit/c6b2ed7f2ffb598dad0d7a4beb915055c3cfbef6))
+
 ## [1.7.7](https://github.com/postalsys/imapflow/compare/v1.7.6...v1.7.7) (2026-08-31)
 
 

package/README.md

@@ -13,7 +13,8 @@ ImapFlow provides a clean, promise-based API for working with IMAP, so you don't
 - **Automatic IMAP extension handling** - CONDSTORE, QRESYNC, IDLE, COMPRESS, and [more](https://imapflow.com/docs/)
 - **Message streaming** - async iterators for efficient processing
 - **Mailbox locking** - built-in locking mechanism for safe concurrent access
-- **TypeScript support** - type definitions included
+- **TypeScript support** - written in TypeScript, type definitions included
+- **ES modules and CommonJS** - `import { ImapFlow } from 'imapflow'` and `const { ImapFlow } = require('imapflow')` both work
 - **Proxy support** - SOCKS and HTTP CONNECT proxies
 - **Gmail support** - labels, raw search via X-GM-EXT-1
 
@@ -23,10 +24,15 @@ ImapFlow provides a clean, promise-based API for working with IMAP, so you don't
 npm install imapflow
 ```
 
+ImapFlow requires Node.js 20 or newer. The package ships both an ES module build and a CommonJS build with bundled type declarations, so no separate `@types` package is needed.
+
+The ES module build also runs on [Bun](https://bun.sh/) (tested against the latest release) and on [Cloudflare Workers](https://developers.cloudflare.com/workers/) with the `nodejs_compat` compatibility flag. On Workers connect with implicit TLS (`secure: true`, usually port 993) or in cleartext: the runtime can not upgrade an already connected socket, so a STARTTLS negotiation fails with a TLS error, and it does not allow turning certificate validation off, so `tls: { rejectUnauthorized: false }` is rejected with `ERR_OPTION_NOT_IMPLEMENTED`. COMPRESS=DEFLATE, IDLE and the default pino logger work as on Node.js.
+
 ## Quick Example
 
 ```js
-const { ImapFlow } = require('imapflow');
+import { ImapFlow } from 'imapflow';
+// or in CommonJS: const { ImapFlow } = require('imapflow');
 
 const client = new ImapFlow({
     host: 'imap.example.com',

package/dist/cjs/charsets.d.ts

@@ -0,0 +1 @@
+export declare const resolveCharset: (charset: string) => string | null;

package/dist/cjs/charsets.js

@@ -0,0 +1,294 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCharset = void 0;
+// Subset of the IANA Character Sets registry (https://www.iana.org/assignments/character-sets/).
+// Used to validate and resolve charset names found in MIME Content-Type parameters.
+// This list covers the most commonly encountered charsets in email messages.
+const CHARACTER_SETS = [
+    'US-ASCII',
+    'ISO-8859-1',
+    'ISO-8859-2',
+    'ISO-8859-3',
+    'ISO-8859-4',
+    'ISO-8859-5',
+    'ISO-8859-6',
+    'ISO-8859-7',
+    'ISO-8859-8',
+    'ISO-8859-9',
+    'ISO-8859-10',
+    'ISO_6937-2-add',
+    'JIS_X0201',
+    'JIS_Encoding',
+    'Shift_JIS',
+    'EUC-JP',
+    'Extended_UNIX_Code_Fixed_Width_for_Japanese',
+    'BS_4730',
+    'SEN_850200_C',
+    'IT',
+    'ES',
+    'DIN_66003',
+    'NS_4551-1',
+    'NF_Z_62-010',
+    'ISO-10646-UTF-1',
+    'ISO_646.basic:1983',
+    'INVARIANT',
+    'ISO_646.irv:1983',
+    'NATS-SEFI',
+    'NATS-SEFI-ADD',
+    'NATS-DANO',
+    'NATS-DANO-ADD',
+    'SEN_850200_B',
+    'KS_C_5601-1987',
+    'ISO-2022-KR',
+    'EUC-KR',
+    'ISO-2022-JP',
+    'ISO-2022-JP-2',
+    'JIS_C6220-1969-jp',
+    'JIS_C6220-1969-ro',
+    'PT',
+    'greek7-old',
+    'latin-greek',
+    'NF_Z_62-010_(1973)',
+    'Latin-greek-1',
+    'ISO_5427',
+    'JIS_C6226-1978',
+    'BS_viewdata',
+    'INIS',
+    'INIS-8',
+    'INIS-cyrillic',
+    'ISO_5427:1981',
+    'ISO_5428:1980',
+    'GB_1988-80',
+    'GB_2312-80',
+    'NS_4551-2',
+    'videotex-suppl',
+    'PT2',
+    'ES2',
+    'MSZ_7795.3',
+    'JIS_C6226-1983',
+    'greek7',
+    'ASMO_449',
+    'iso-ir-90',
+    'JIS_C6229-1984-a',
+    'JIS_C6229-1984-b',
+    'JIS_C6229-1984-b-add',
+    'JIS_C6229-1984-hand',
+    'JIS_C6229-1984-hand-add',
+    'JIS_C6229-1984-kana',
+    'ISO_2033-1983',
+    'ANSI_X3.110-1983',
+    'T.61-7bit',
+    'T.61-8bit',
+    'ECMA-cyrillic',
+    'CSA_Z243.4-1985-1',
+    'CSA_Z243.4-1985-2',
+    'CSA_Z243.4-1985-gr',
+    'ISO-8859-6-E',
+    'ISO-8859-6-I',
+    'T.101-G2',
+    'ISO-8859-8-E',
+    'ISO-8859-8-I',
+    'CSN_369103',
+    'JUS_I.B1.002',
+    'IEC_P27-1',
+    'JUS_I.B1.003-serb',
+    'JUS_I.B1.003-mac',
+    'greek-ccitt',
+    'NC_NC00-10:81',
+    'ISO_6937-2-25',
+    'GOST_19768-74',
+    'ISO_8859-supp',
+    'ISO_10367-box',
+    'latin-lap',
+    'JIS_X0212-1990',
+    'DS_2089',
+    'us-dk',
+    'dk-us',
+    'KSC5636',
+    'UNICODE-1-1-UTF-7',
+    'ISO-2022-CN',
+    'ISO-2022-CN-EXT',
+    'UTF-8',
+    'ISO-8859-13',
+    'ISO-8859-14',
+    'ISO-8859-15',
+    'ISO-8859-16',
+    'GBK',
+    'GB18030',
+    'OSD_EBCDIC_DF04_15',
+    'OSD_EBCDIC_DF03_IRV',
+    'OSD_EBCDIC_DF04_1',
+    'ISO-11548-1',
+    'KZ-1048',
+    'ISO-10646-UCS-2',
+    'ISO-10646-UCS-4',
+    'ISO-10646-UCS-Basic',
+    'ISO-10646-Unicode-Latin1',
+    'ISO-10646-J-1',
+    'ISO-Unicode-IBM-1261',
+    'ISO-Unicode-IBM-1268',
+    'ISO-Unicode-IBM-1276',
+    'ISO-Unicode-IBM-1264',
+    'ISO-Unicode-IBM-1265',
+    'UNICODE-1-1',
+    'SCSU',
+    'UTF-7',
+    'UTF-16BE',
+    'UTF-16LE',
+    'UTF-16',
+    'CESU-8',
+    'UTF-32',
+    'UTF-32BE',
+    'UTF-32LE',
+    'BOCU-1',
+    'ISO-8859-1-Windows-3.0-Latin-1',
+    'ISO-8859-1-Windows-3.1-Latin-1',
+    'ISO-8859-2-Windows-Latin-2',
+    'ISO-8859-9-Windows-Latin-5',
+    'hp-roman8',
+    'Adobe-Standard-Encoding',
+    'Ventura-US',
+    'Ventura-International',
+    'DEC-MCS',
+    'IBM850',
+    'PC8-Danish-Norwegian',
+    'IBM862',
+    'PC8-Turkish',
+    'IBM-Symbols',
+    'IBM-Thai',
+    'HP-Legal',
+    'HP-Pi-font',
+    'HP-Math8',
+    'Adobe-Symbol-Encoding',
+    'HP-DeskTop',
+    'Ventura-Math',
+    'Microsoft-Publishing',
+    'Windows-31J',
+    'GB2312',
+    'Big5',
+    'macintosh',
+    'IBM037',
+    'IBM038',
+    'IBM273',
+    'IBM274',
+    'IBM275',
+    'IBM277',
+    'IBM278',
+    'IBM280',
+    'IBM281',
+    'IBM284',
+    'IBM285',
+    'IBM290',
+    'IBM297',
+    'IBM420',
+    'IBM423',
+    'IBM424',
+    'IBM437',
+    'IBM500',
+    'IBM851',
+    'IBM852',
+    'IBM855',
+    'IBM857',
+    'IBM860',
+    'IBM861',
+    'IBM863',
+    'IBM864',
+    'IBM865',
+    'IBM868',
+    'IBM869',
+    'IBM870',
+    'IBM871',
+    'IBM880',
+    'IBM891',
+    'IBM903',
+    'IBM904',
+    'IBM905',
+    'IBM918',
+    'IBM1026',
+    'EBCDIC-AT-DE',
+    'EBCDIC-AT-DE-A',
+    'EBCDIC-CA-FR',
+    'EBCDIC-DK-NO',
+    'EBCDIC-DK-NO-A',
+    'EBCDIC-FI-SE',
+    'EBCDIC-FI-SE-A',
+    'EBCDIC-FR',
+    'EBCDIC-IT',
+    'EBCDIC-PT',
+    'EBCDIC-ES',
+    'EBCDIC-ES-A',
+    'EBCDIC-ES-S',
+    'EBCDIC-UK',
+    'EBCDIC-US',
+    'UNKNOWN-8BIT',
+    'MNEMONIC',
+    'MNEM',
+    'VISCII',
+    'VIQR',
+    'KOI8-R',
+    'HZ-GB-2312',
+    'IBM866',
+    'IBM775',
+    'KOI8-U',
+    'IBM00858',
+    'IBM00924',
+    'IBM01140',
+    'IBM01141',
+    'IBM01142',
+    'IBM01143',
+    'IBM01144',
+    'IBM01145',
+    'IBM01146',
+    'IBM01147',
+    'IBM01148',
+    'IBM01149',
+    'Big5-HKSCS',
+    'IBM1047',
+    'PTCP154',
+    'Amiga-1251',
+    'KOI7-switched',
+    'BRF',
+    'TSCII',
+    'CP51932',
+    'windows-874',
+    'windows-1250',
+    'windows-1251',
+    'windows-1252',
+    'windows-1253',
+    'windows-1254',
+    'windows-1255',
+    'windows-1256',
+    'windows-1257',
+    'windows-1258',
+    'TIS-620',
+    'CP50220'
+];
+const CHARSET_MAP = new Map();
+// Build a lookup map with normalized keys for fuzzy charset resolution.
+// Normalization strategy:
+// 1. Strip all underscores, hyphens, and spaces, then lowercase (e.g., "ISO-8859-1" -> "iso88591")
+// 2. Create additional aliases for common alternative prefixes:
+//    - "windows" -> "win" (e.g., "windows1252" also matches as "win1252")
+//    - "usascii" -> "ascii" (common shorthand)
+//    - "iso8859" -> "latin" (e.g., "iso88591" also matches as "latin1")
+// This handles the many variant spellings found in real-world email headers.
+CHARACTER_SETS.forEach(entry => {
+    let key = entry.replace(/[_-\s]/g, '').toLowerCase();
+    let modifiedKey = key
+        .replace(/^windows/, 'win')
+        .replace(/^usascii/, 'ascii')
+        .replace(/^iso8859/, 'latin');
+    CHARSET_MAP.set(key, entry);
+    if (!CHARSET_MAP.has(modifiedKey)) {
+        CHARSET_MAP.set(modifiedKey, entry);
+    }
+});
+// Resolves a charset name to its canonical IANA form using case-insensitive,
+// symbol-stripping normalization. For example, "WIN-1252", "windows_1252",
+// and "WINDOWS-1252" all resolve to "windows-1252".
+// Returns null if the charset is not recognized.
+const resolveCharset = (charset) => {
+    let key = charset.replace(/[_-\s]/g, '').toLowerCase();
+    return CHARSET_MAP.get(key) ?? null;
+};
+exports.resolveCharset = resolveCharset;

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

@@ -0,0 +1,22 @@
+import type { ImapFlow } from '../imap-flow.js';
+import type { AppendResponseObject } from '../types.js';
+/**
+ * Result of an APPEND: the destination, the selected mailbox path at the time of the append,
+ * and the UID information the server reported
+ */
+export interface AppendResult extends AppendResponseObject {
+    /** Path of the currently selected mailbox, if any */
+    path?: string | undefined;
+}
+/**
+ * Appends a message to a mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param destination - Destination mailbox path
+ * @param content - Message content (RFC 822 format)
+ * @param flags - Message flags to set on the appended message
+ * @param idate - Internal date to set for the message
+ * @returns Append result with UID info if available, or undefined if preconditions not met
+ * @throws {Error} If the APPEND command fails or message exceeds APPENDLIMIT
+ */
+export default function append(connection: ImapFlow, destination: string | string[], content: Buffer | string, flags?: string | string[] | undefined, idate?: Date | string | false | undefined): Promise<AppendResult | undefined>;

package/dist/cjs/commands/append.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = append;
+const tools_js_1 = require("../tools.js");
+/**
+ * Appends a message to a mailbox.
+ *
+ * @param connection - IMAP connection instance
+ * @param destination - Destination mailbox path
+ * @param content - Message content (RFC 822 format)
+ * @param flags - Message flags to set on the appended message
+ * @param idate - Internal date to set for the message
+ * @returns Append result with UID info if available, or undefined if preconditions not met
+ * @throws {Error} If the APPEND command fails or message exceeds APPENDLIMIT
+ */
+async function append(connection, destination, content, flags, idate) {
+    if (![connection.states.AUTHENTICATED, connection.states.SELECTED].includes(connection.state) || !destination) {
+        // nothing to do here
+        return;
+    }
+    if (typeof content === 'string') {
+        content = Buffer.from(content);
+    }
+    // APPENDLIMIT capability (RFC 7889): server may advertise the maximum message
+    // size it accepts. Check before sending to avoid a wasted round-trip.
+    if (connection.capabilities.has('APPENDLIMIT')) {
+        let appendLimit = connection.capabilities.get('APPENDLIMIT');
+        if (typeof appendLimit === 'number' && appendLimit < content.length) {
+            let err = new Error('Message content too big for APPENDLIMIT=' + appendLimit);
+            err.serverResponseCode = 'APPENDLIMIT';
+            throw err;
+        }
+    }
+    destination = (0, tools_js_1.normalizePath)(connection, destination);
+    // If appending to the currently selected mailbox, we can listen for the
+    // untagged EXISTS response to capture the new message's sequence number.
+    let expectExists = (0, tools_js_1.comparePaths)(connection, connection.mailbox.path, destination);
+    // Validate and format flags. Only flags allowed by the mailbox's permanentFlags are included.
+    flags = (Array.isArray(flags) ? flags : [].concat(flags || []))
+        .map(flag => flag && (0, tools_js_1.formatFlag)(flag.toString()))
+        .filter((flag) => !!flag && (0, tools_js_1.canUseFlag)(connection.mailbox, flag));
+    // APPEND command format: APPEND <mailbox> [<flags>] [<date-time>] <literal>
+    let attributes = [{ type: 'ATOM', value: (0, tools_js_1.encodePath)(connection, destination) }];
+    // Internal date: the date the server should record for this message.
+    // Must be quoted (STRING type) per the IMAP date-time grammar.
+    idate = idate ? (0, tools_js_1.formatDateTime)(idate) : false;
+    // Flags and date are optional; flags must come before date if both are present
+    if (flags.length || idate) {
+        attributes.push(flags.map(flag => ({ type: 'ATOM', value: flag })));
+    }
+    if (idate) {
+        attributes.push({ type: 'STRING', value: idate });
+    }
+    // BINARY extension (RFC 3516): if the message content contains NUL bytes,
+    // use literal8 syntax (~{size}\r\n) instead of regular literal ({size}\r\n).
+    // Regular literals cannot contain NUL bytes per the IMAP grammar.
+    let isLiteral8 = false;
+    if (connection.capabilities.has('BINARY') && !connection.disableBinary) {
+        isLiteral8 = content.indexOf(Buffer.from([0])) >= 0;
+    }
+    attributes.push({ type: 'LITERAL', value: content, isLiteral8 });
+    let map = { destination };
+    if (connection.mailbox && connection.mailbox.path) {
+        map.path = connection.mailbox.path;
+    }
+    // Handler for untagged EXISTS: captures the new message count which gives
+    // us the sequence number of the appended message (it's the latest message).
+    const handleExistsUpdate = (untagged) => {
+        // The count is written into the live mailbox state below, so it has to clear the
+        // same bar untaggedExists() applies: a digit run long enough to coerce to Infinity
+        // would make resolveRange('*') compile to the literal string "Infinity" and break
+        // every range-based command until the next SELECT.
+        let seq = (0, tools_js_1.parseUintValue)(untagged.command, tools_js_1.MAX_UINT32_DIGITS);
+        if (seq === false) {
+            return;
+        }
+        map.seq = seq;
+        // Update the connection's mailbox state and emit 'exists' event if the
+        // count changed (notifies listeners about the new message).
+        if (expectExists) {
+            let mailbox = connection.mailbox;
+            let prevCount = mailbox.exists;
+            if (map.seq !== prevCount) {
+                mailbox.exists = map.seq;
+                connection.emit('exists', {
+                    path: mailbox.path,
+                    count: map.seq,
+                    prevCount
+                });
+            }
+        }
+    };
+    let response;
+    try {
+        response = await connection.exec('APPEND', attributes, {
+            // Only listen for EXISTS if we're appending to the currently selected mailbox
+            untagged: expectExists ? { EXISTS: handleExistsUpdate } : false
+        });
+        // UIDPLUS (RFC 4315): the server may include APPENDUID response code in
+        // the tagged OK. Format: [APPENDUID <uidValidity> <uid>]
+        let section = response.response.attributes && response.response.attributes[0] && response.response.attributes[0].section;
+        if (section && section.length) {
+            let first = section[0];
+            let responseCode = first && typeof first.value === 'string' ? first.value : '';
+            if (responseCode.toUpperCase() === 'APPENDUID') {
+                // Bounded digit runs only: isNaN() also passes '1e5', which BigInt() rejects
+                // with a throw - and this catch rethrows, so the append would reject after the
+                // message was already stored and a retrying caller would duplicate it.
+                let uidValidity = (0, tools_js_1.parseBigIntValue)(section[1] && section[1].value, tools_js_1.MAX_UINT32_DIGITS);
+                let uid = (0, tools_js_1.parseUintValue)(section[2] && section[2].value, tools_js_1.MAX_UINT32_DIGITS);
+                if (uidValidity !== false) {
+                    map.uidValidity = uidValidity;
+                }
+                if (uid) {
+                    map.uid = uid;
+                }
+            }
+        }
+        response.next();
+        // If we didn't get an EXISTS during APPEND (some servers don't send it
+        // until the next command), issue a NOOP to flush pending notifications.
+        if (expectExists && !map.seq) {
+            try {
+                response = await connection.exec('NOOP', false, {
+                    untagged: { EXISTS: handleExistsUpdate },
+                    comment: 'Sequence not found from APPEND output'
+                });
+                response.next();
+            }
+            catch (err) {
+                connection.log.warn({ err, cid: connection.id });
+            }
+        }
+        // If we have a sequence number but no UID (server doesn't support UIDPLUS),
+        // look up the UID via SEARCH to provide a consistent result to the caller.
+        if (map.seq && !map.uid) {
+            let list = await connection.search({ seq: map.seq }, { uid: true });
+            if (Array.isArray(list) && list.length) {
+                map.uid = list[0];
+            }
+        }
+        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/authenticate.d.ts

@@ -0,0 +1,24 @@
+import type { ImapFlow } from '../imap-flow.js';
+/**
+ * Credentials for the AUTHENTICATE command
+ */
+export interface AuthenticateCredentials {
+    /** OAuth2 access token for OAUTHBEARER/XOAUTH2 authentication */
+    accessToken?: string | undefined;
+    /** Password for PLAIN or LOGIN authentication */
+    password?: string | undefined;
+    /** Force a specific login method (e.g., 'AUTH=PLAIN', 'AUTH=LOGIN') */
+    loginMethod?: string | undefined;
+    /** Authorization identity for PLAIN authentication */
+    authzid?: string | undefined;
+}
+/**
+ * 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
+ */
+export default function authenticate(connection: ImapFlow, username: string, { accessToken, password, loginMethod, authzid }: AuthenticateCredentials): Promise<string | undefined>;