imapflow 1.6.6 → 1.7.1

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.6.6"
+    ".": "1.7.1"
 }

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [1.7.1](https://github.com/postalsys/imapflow/compare/v1.7.0...v1.7.1) (2026-08-14)
+
+
+### Bug Fixes
+
+* **logging:** mask credential frames in the raw log and keep error detail ([2d6563b](https://github.com/postalsys/imapflow/commit/2d6563b75410a2cd9d4fbca08a76230589b60079))
+
+## [1.7.0](https://github.com/postalsys/imapflow/compare/v1.6.6...v1.7.0) (2026-08-11)
+
+
+### Features
+
+* **idle:** make the auto-IDLE delay configurable ([311fe0c](https://github.com/postalsys/imapflow/commit/311fe0ccb0d75d4ddbe797bf5bc755df5bf0485f))
+
+
+### Bug Fixes
+
+* **idle:** align the socket watchdog with the auto-IDLE busy guard ([d5e7191](https://github.com/postalsys/imapflow/commit/d5e71915ac7a1829b7e1340da6195a5e3e9984b2))
+* **idle:** validate autoIdleDelay and keep auto-IDLE off a busy connection ([aeafdf6](https://github.com/postalsys/imapflow/commit/aeafdf62fab3b29cd488d9b8cbdffc8896107d6e))
+
 ## [1.6.6](https://github.com/postalsys/imapflow/compare/v1.6.5...v1.6.6) (2026-08-07)
 
 

package/README.md

@@ -5,7 +5,7 @@ Modern and easy-to-use IMAP client library for Node.js.
 [![npm](https://img.shields.io/npm/v/imapflow)](https://www.npmjs.com/package/imapflow)
 [![license](https://img.shields.io/npm/l/imapflow)](https://github.com/postalsys/imapflow/blob/master/LICENSE)
 
-ImapFlow provides a clean, promise-based API for working with IMAP, so you don't need in-depth knowledge of the protocol. IMAP extensions are detected and handled automatically. You write the same code regardless of server capabilities, and ImapFlow adapts behind the scenes.
+ImapFlow provides a clean, promise-based API for working with IMAP, so you don't need in-depth knowledge of the protocol. IMAP extensions are detected and handled automatically. You write the same code regardless of server capabilities, and ImapFlow adapts behind the scenes. ImapFlow is the IMAP engine that powers [EmailEngine](https://emailengine.app/?utm_source=imapflow-readme&utm_medium=readme&utm_campaign=oss-docs&utm_content=intro), a self-hosted email API built by the same team.
 
 ## Features
 
@@ -77,8 +77,7 @@ Full documentation is available at **[imapflow.com](https://imapflow.com/docs/)*
 - [Mailbox Management](https://imapflow.com/docs/guides/mailbox-management) - creating, renaming, and deleting mailboxes
 - [API Reference](https://imapflow.com/docs/api/imapflow-client) - complete method and event documentation
 
-> [!NOTE]
-> If you are looking for a complete email integration solution, ImapFlow was built for [EmailEngine](https://emailengine.app/), a self-hosted email gateway that provides REST API access to IMAP and SMTP accounts.
+> ImapFlow was built for **[EmailEngine](https://emailengine.app/?utm_source=imapflow-readme&utm_medium=readme&utm_campaign=oss-docs&utm_content=note)**, a self-hosted email API that turns Gmail, Microsoft 365, and IMAP accounts into REST endpoints, with managed OAuth2 and webhooks for incoming mail. If you need a production email integration rather than an IMAP client, start there.
 
 ## License
 

package/lib/commands/authenticate.js

@@ -81,11 +81,16 @@ async function authOauth(connection, username, accessToken) {
                         try {
                             errorResponse = JSON.parse(Buffer.from(resp.attributes[0].value, 'base64').toString());
                         } catch (err) {
-                            connection.log.debug({ errorResponse: resp.attributes[0].value, 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}` });
+                    connection.log.debug({ src: 'c', msg: breaker, comment: `Error response for ${command}`, cid: connection.id });
                     connection.write(breaker);
                 }
             }
@@ -126,10 +131,10 @@ async function authLogin(connection, username, password) {
 
                     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` });
+                        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` });
+                        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}"`);
@@ -169,7 +174,12 @@ async function authPlain(connection, username, password, authzid) {
                 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' : ''}` });
+                connection.log.debug({
+                    src: 'c',
+                    msg: loggedResponse,
+                    comment: `Encoded response for AUTH=PLAIN${authzid ? ' with authzid' : ''}`,
+                    cid: connection.id
+                });
                 connection.write(encodedResponse);
             }
         });

package/lib/commands/idle.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { hasCapability, unrefTimer } = require('../tools.js');
+const { hasCapability, logConnectionError, unrefTimer } = require('../tools.js');
 
 const NOOP_INTERVAL = 2 * 60 * 1000;
 
@@ -64,7 +64,8 @@ async function runIdle(connection) {
                     msg: `DONE`,
                     comment: `breaking IDLE`,
                     lockId: connection.currentLock?.lockId,
-                    path: connection.mailbox && connection.mailbox.path
+                    path: connection.mailbox && connection.mailbox.path,
+                    cid: connection.id
                 });
                 connection.write('DONE');
                 doneSent = true;
@@ -95,10 +96,11 @@ async function runIdle(connection) {
                 queued: preCheckWaitQueue.length,
                 doneRequested,
                 canEnd,
-                doneSent
+                doneSent,
+                cid: connection.id
             });
 
-            preCheck().catch(err => connection.log.warn({ err, cid: connection.id }));
+            preCheck().catch(err => logConnectionError(connection, 'Failed to break IDLE', err));
 
             return handler;
         };
@@ -112,13 +114,18 @@ async function runIdle(connection) {
             // After this, the server will push untagged responses for mailbox changes.
             // We can now safely send DONE if a break was already requested.
             onPlusTag: async () => {
-                connection.log.debug({ msg: `Initiated IDLE, waiting for server input`, lockId: connection.currentLock?.lockId, doneRequested });
+                connection.log.debug({
+                    msg: `Initiated IDLE, waiting for server input`,
+                    lockId: connection.currentLock?.lockId,
+                    doneRequested,
+                    cid: connection.id
+                });
                 canEnd = true;
                 if (doneRequested) {
                     try {
                         await preCheck();
                     } catch (err) {
-                        connection.log.warn({ err, cid: connection.id });
+                        logConnectionError(connection, 'Failed to break IDLE', err);
                     }
                 }
             },
@@ -128,7 +135,7 @@ async function runIdle(connection) {
         response.next();
         return;
     } catch (err) {
-        connection.log.warn({ err, cid: connection.id });
+        logConnectionError(connection, 'IDLE session failed', err);
         while (preCheckWaitQueue.length) {
             let { reject } = preCheckWaitQueue.shift();
             reject(err);
@@ -166,12 +173,12 @@ async function pollOnce(connection, session) {
 
     switch (connection.missingIdleCommand) {
         case 'SELECT':
-            connection.log.debug({ src: 'c', msg: `Running SELECT to detect changes in folder`, cid: connection.id });
+            connection.log.debug({ msg: `Running SELECT to detect changes in folder`, cid: connection.id });
             await connection.runInternal('SELECT', path, { readOnly: session.selectCommand.command === 'EXAMINE' });
             break;
 
         case 'STATUS': {
-            connection.log.debug({ src: 'c', msg: `Running STATUS to detect changes in folder`, cid: connection.id });
+            connection.log.debug({ msg: `Running STATUS to detect changes in folder`, cid: connection.id });
             // HIGHESTMODSEQ is filtered out again unless the server advertises CONDSTORE, so a
             // CONDSTORE session keeps mailbox.highestModseq current without asking a plain
             // server for an item it does not know.
@@ -240,7 +247,7 @@ async function runPollingFallback(connection, maxIdleTime) {
             };
 
             session.preCheck = async () => {
-                connection.log.debug({ src: 'c', msg: `breaking NOOP loop`, cid: connection.id });
+                connection.log.debug({ msg: `Breaking NOOP loop`, cid: connection.id });
                 cancel();
             };
             connection.preCheck = session.preCheck;
@@ -257,24 +264,45 @@ async function runPollingFallback(connection, maxIdleTime) {
 
                 pollOnce(connection, session)
                     .then(() => {
+                        // Stamped only after a poll actually completed: a failed poll must not
+                        // satisfy the resumed schedule below, or the next session would defer
+                        // its first poll a full interval past an attempt that checked nothing.
+                        connection._lastPollAt = Date.now();
                         // Cancellation is re-checked here: the session may have been broken while
                         // this poll was in flight, and an orphaned poller must not schedule again.
                         if (session.cancelled) {
                             return;
                         }
-                        session.timer = setTimeout(runPoll, interval);
-                        // Background polling must not keep the process alive
-                        unrefTimer(session.timer);
+                        scheduleNextPoll(interval);
                     })
                     .catch(err => {
-                        connection.log.warn({ err, cid: connection.id });
+                        logConnectionError(connection, 'Failed to poll for mailbox changes', err);
                         cancel();
                     });
             };
 
-            connection.log.debug({ src: 'c', msg: `initiated NOOP loop`, cid: connection.id });
-            // Keep the immediate first poll
-            runPoll();
+            function scheduleNextPoll(delay) {
+                session.timer = setTimeout(runPoll, delay);
+                // Background polling must not keep the process alive
+                unrefTimer(session.timer);
+            }
+
+            connection.log.debug({ msg: `Initiated NOOP loop`, cid: connection.id });
+
+            // Every auto-IDLE restart begins a fresh polling session, so an unconditional first
+            // poll would tie the poll rate to how often the caller runs commands rather than to
+            // `interval`: with a short autoIdleDelay, a command every few seconds turns into a
+            // poll every few seconds. The last poll timestamp lives on the connection, so a new
+            // session resumes the previous one's schedule instead of restarting it.
+            // Clamped at zero because a backward wall-clock step (NTP, VM resume) leaves the
+            // stamp in the future; however large the jump, the next poll must never be more
+            // than one full interval away.
+            let sinceLastPoll = Math.max(0, Date.now() - (connection._lastPollAt || 0));
+            if (sinceLastPoll >= interval) {
+                runPoll();
+            } else {
+                scheduleNextPoll(interval - sinceLastPoll);
+            }
         });
     } finally {
         session.cancelled = true;
@@ -318,7 +346,7 @@ module.exports = async (connection, maxIdleTime) => {
                             stillIdling = true;
                             // request IDLE break if IDLE has been running for allowed time
                             connection.log.trace({ msg: 'Max allowed IDLE time reached', cid: connection.id });
-                            connection.preCheck().catch(err => connection.log.warn({ err, cid: connection.id }));
+                            connection.preCheck().catch(err => logConnectionError(connection, 'Failed to break IDLE for restart', err));
                         }
                     }
                 }, maxIdleTime);

package/lib/imap-flow.d.ts

@@ -30,11 +30,25 @@ export interface ImapFlowOptions {
     clientInfo?: IdInfoObject;
     /** If true, then do not start IDLE when connection is established */
     disableAutoIdle?: boolean;
+    /**
+     * How long (in ms) the connection has to be inactive before IDLE is started automatically.
+     * Keep it above the pause your own code usually leaves between two commands, otherwise every
+     * command is followed by an IDLE that the next command has to break, costing two extra
+     * round-trips per command. To turn auto-IDLE off use `disableAutoIdle` rather than a very
+     * large delay: the value is capped below `socketTimeout`, because auto-IDLE has to start
+     * before the inactivity watchdog fires. On servers without IDLE support this controls when
+     * the polling fallback starts, not how often it polls - the poll interval is `maxIdleTime`,
+     * capped at 2 minutes. Default: 15000 ms.
+     */
+    autoIdleDelay?: number;
     /** Additional TLS options (see Node.js TLS documentation) */
     tls?: ConnectionOptions;
     /** Custom logger instance. Set to false to disable logging */
     logger?: Logger | false;
-    /** If true, log data read and written to socket encoded in base64 */
+    /**
+     * If true, log data read and written to socket encoded in base64. Client frames that carry
+     * credentials are replaced with a fixed placeholder and marked with `hidden: true`.
+     */
     logRaw?: boolean;
     /** If true, emit 'log' events */
     emitLogs?: boolean;