imapflow 1.0.101 → 1.0.104

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+-   1.0.102 - 2022-08-18
+
+    -   Added new option `{statusQuery: {<statusOptions>}` for `list()` method
+    -   Added support for LIST-STATUS extension https://datatracker.ietf.org/doc/html/rfc5819
+
 -   1.0.100 - 2022-06-17
 
     -   Emit new message notification if appending to currently opened folder

package/lib/commands/list.js

@@ -14,8 +14,46 @@ module.exports = async (connection, reference, mailbox, options) => {
         let flagsSeen = new Set();
         let entries = [];
 
+        let statusMap = new Map();
+        let returnArgs = [];
+        let statusQueryAttributes = [];
+
+        if (options.statusQuery) {
+            Object.keys(options.statusQuery || {}).forEach(key => {
+                if (!options.statusQuery[key]) {
+                    return;
+                }
+
+                switch (key.toUpperCase()) {
+                    case 'MESSAGES':
+                    case 'RECENT':
+                    case 'UIDNEXT':
+                    case 'UIDVALIDITY':
+                    case 'UNSEEN':
+                        statusQueryAttributes.push({ type: 'ATOM', value: key.toUpperCase() });
+                        break;
+
+                    case 'HIGHESTMODSEQ':
+                        if (connection.capabilities.has('CONDSTORE')) {
+                            statusQueryAttributes.push({ type: 'ATOM', value: key.toUpperCase() });
+                        }
+                        break;
+                }
+            });
+        }
+
+        if (listCommand === 'LIST' && connection.capabilities.has('LIST-STATUS') && statusQueryAttributes.length) {
+            returnArgs.push({ type: 'ATOM', value: 'STATUS' }, statusQueryAttributes);
+        }
+
         let runList = async (reference, mailbox) => {
-            response = await connection.exec(listCommand, [encodePath(connection, reference), encodePath(connection, mailbox)], {
+            const cmdArgs = [encodePath(connection, reference), encodePath(connection, mailbox)];
+
+            if (returnArgs.length) {
+                cmdArgs.push({ type: 'ATOM', value: 'RETURN' }, returnArgs);
+            }
+
+            response = await connection.exec(listCommand, cmdArgs, {
                 untagged: {
                     [listCommand]: async untagged => {
                         if (!untagged.attributes || !untagged.attributes.length) {
@@ -57,6 +95,67 @@ module.exports = async (connection, reference, mailbox, options) => {
                         }
 
                         entries.push(entry);
+                    },
+
+                    STATUS: async untagged => {
+                        let statusPath = normalizePath(connection, decodePath(connection, (untagged.attributes[0] && untagged.attributes[0].value) || ''));
+                        let statusList = untagged.attributes && Array.isArray(untagged.attributes[1]) ? untagged.attributes[1] : false;
+                        if (!statusList || !statusPath) {
+                            return;
+                        }
+
+                        let key;
+
+                        let map = { path: statusPath };
+
+                        statusList.forEach((entry, i) => {
+                            if (i % 2 === 0) {
+                                key = entry && typeof entry.value === 'string' ? entry.value : false;
+                                return;
+                            }
+                            if (!key || !entry || typeof entry.value !== 'string') {
+                                return;
+                            }
+                            let value = false;
+                            switch (key.toUpperCase()) {
+                                case 'MESSAGES':
+                                    key = 'messages';
+                                    value = !isNaN(entry.value) ? Number(entry.value) : false;
+                                    break;
+
+                                case 'RECENT':
+                                    key = 'recent';
+                                    value = !isNaN(entry.value) ? Number(entry.value) : false;
+                                    break;
+
+                                case 'UIDNEXT':
+                                    key = 'uidNext';
+                                    value = !isNaN(entry.value) ? Number(entry.value) : false;
+                                    break;
+
+                                case 'UIDVALIDITY':
+                                    key = 'uidValidity';
+                                    value = !isNaN(entry.value) ? BigInt(entry.value) : false;
+                                    break;
+
+                                case 'UNSEEN':
+                                    key = 'unseen';
+                                    value = !isNaN(entry.value) ? Number(entry.value) : false;
+                                    break;
+
+                                case 'HIGHESTMODSEQ':
+                                    key = 'highestModseq';
+                                    value = !isNaN(entry.value) ? BigInt(entry.value) : false;
+                                    break;
+                            }
+                            if (value === false) {
+                                return;
+                            }
+
+                            map[key] = value;
+                        });
+
+                        statusMap.set(statusPath, map);
                     }
                 }
             });
@@ -75,6 +174,23 @@ module.exports = async (connection, reference, mailbox, options) => {
             await runList('', 'INBOX');
         }
 
+        if (options.statusQuery) {
+            for (let entry of entries) {
+                if (!entry.flags.has('\\Noselect') && !entry.flags.has('\\NonExistent')) {
+                    if (statusMap.has(entry.path)) {
+                        entry.status = statusMap.get(entry.path);
+                    } else if (!statusMap.size) {
+                        // run STATUS command
+                        try {
+                            entry.status = await connection.run('STATUS', entry.path, options.statusQuery);
+                        } catch (err) {
+                            entry.status = { error: err };
+                        }
+                    }
+                }
+            }
+        }
+
         response = await connection.exec(
             'LSUB',
             [encodePath(connection, normalizePath(connection, reference || '')), encodePath(connection, normalizePath(connection, mailbox || '', true))],

package/lib/commands/select.js

@@ -47,9 +47,11 @@ module.exports = async (connection, path, options) => {
             map.qresync = true;
         }
 
+        let encodedPath = encodePath(connection, path);
+
         response = await connection.exec(
             !options.readOnly ? 'SELECT' : 'EXAMINE',
-            [{ type: 'ATOM', value: encodePath(connection, path) }].concat(extraArgs || []),
+            [{ type: encodedPath.indexOf('&') >= 0 ? 'STRING' : 'ATOM', value: encodedPath }].concat(extraArgs || []),
             {
                 untagged: {
                     OK: async untagged => {

package/lib/commands/status.js

@@ -10,8 +10,9 @@ module.exports = async (connection, path, query) => {
     }
 
     path = normalizePath(connection, path);
+    let encodedPath = encodePath(connection, path);
 
-    let attributes = [{ type: 'ATOM', value: encodePath(connection, path) }];
+    let attributes = [{ type: encodedPath.indexOf('&') >= 0 ? 'STRING' : 'ATOM', value: encodedPath }];
 
     let queryAttributes = [];
     Object.keys(query || {}).forEach(key => {

package/lib/imap-flow.js

@@ -127,10 +127,11 @@ class ImapFlow extends EventEmitter {
      * @param {Boolean} [options.logRaw=false] If true then log data read from and written to socket encoded in base64
      * @param {Boolean} [options.emitLogs=false] If `true` then in addition of sending data to logger, ImapFlow emits 'log' events with the same data
      * @param {Boolean} [options.verifyOnly=false] If `true` then logs out automatically after successful authentication
-     * @param {Boolean} [options.proxy] Optional proxy URL. Supports HTTP CONNECT (`http://`, `https://`) and SOCKS (`socks://`, `socks4://`, `socks5://`) proxies
+     * @param {String} [options.proxy] Optional proxy URL. Supports HTTP CONNECT (`http://`, `https://`) and SOCKS (`socks://`, `socks4://`, `socks5://`) proxies
      * @param {Boolean} [options.qresync=false] If true, then enables QRESYNC support. EXPUNGE notifications will include `uid` property instead of `seq`
      * @param {Number} [options.maxIdleTime] If set, then breaks and restarts IDLE every maxIdleTime ms
      * @param {Boolean} [options.disableBinary=false] If true, then ignores the BINARY extension when making FETCH and APPEND calls
+     * @param {Boolean} [options.disableAutoEnable] Do not enable supported extensions by default
      */
     constructor(options) {
         super({ captureRejections: true });
@@ -211,6 +212,7 @@ class ImapFlow extends EventEmitter {
          * @type {Map<string, boolean|number>}
          */
         this.capabilities = new Map();
+        this.rawCapabilities = null;
 
         this.expectCapabilityUpdate = false; // force CAPABILITY after LOGIN
 
@@ -645,8 +647,10 @@ class ImapFlow extends EventEmitter {
             await this.compress();
         }
 
-        // enable extensions if possible
-        await this.run('ENABLE', ['CONDSTORE', 'UTF8=ACCEPT'].concat(this.options.qresync ? 'QRESYNC' : []));
+        if (!this.options.disableAutoEnable) {
+            // enable extensions if possible
+            await this.run('ENABLE', ['CONDSTORE', 'UTF8=ACCEPT'].concat(this.options.qresync ? 'QRESYNC' : []));
+        }
 
         this.usable = true;
     }
@@ -920,6 +924,7 @@ class ImapFlow extends EventEmitter {
     }
 
     async sectionCapability(section) {
+        this.rawCapabilities = section;
         this.capabilities = updateCapabilities(section);
         if (this.expectCapabilityUpdate) {
             this.expectCapabilityUpdate = false;
@@ -927,6 +932,7 @@ class ImapFlow extends EventEmitter {
     }
 
     async untaggedCapability(untagged) {
+        this.rawCapabilities = untagged.attributes;
         this.capabilities = updateCapabilities(untagged.attributes);
         if (this.expectCapabilityUpdate) {
             this.expectCapabilityUpdate = false;
@@ -1392,19 +1398,28 @@ class ImapFlow extends EventEmitter {
      * @property {String} specialUse one of special-use flags (if applicable): "\All", "\Archive", "\Drafts", "\Flagged", "\Junk", "\Sent", "\Trash". Additionally INBOX has non-standard "\Inbox" flag set
      * @property {Boolean} listed `true` if mailbox was found from the output of LIST command
      * @property {Boolean} subscribed `true` if mailbox was found from the output of LSUB command
+     * @property {StatusObject} [status] If `statusQuery` was used, then this value includes the status response
      */
 
     /**
      * Lists available mailboxes as an Array
      *
+     * @param {Object} [options] defines additional listing options
+     * @param {Object} [options.statusQuery] request status items for every listed entry
+     * @param {Boolean} [options.statusQuery.messages] if `true` request count of messages
+     * @param {Boolean} [options.statusQuery.recent] if `true` request count of messages with \\Recent tag
+     * @param {Boolean} [options.statusQuery.uidNext] if `true` request predicted next UID
+     * @param {Boolean} [options.statusQuery.uidValidity] if `true` request mailbox `UIDVALIDITY` value
+     * @param {Boolean} [options.statusQuery.unseen] if `true` request count of unseen messages
+     * @param {Boolean} [options.statusQuery.highestModseq] if `true` request last known modseq value
      * @returns {Promise<ListResponse[]>} An array of ListResponse objects
      *
      * @example
      * let list = await client.list();
      * list.forEach(mailbox=>console.log(mailbox.path));
      */
-    async list() {
-        let folders = await this.run('LIST', '', '*');
+    async list(options) {
+        let folders = await this.run('LIST', '', '*', options);
         this.folders = new Map(folders.map(folder => [folder.path, folder]));
         return folders;
     }
@@ -2602,6 +2617,20 @@ class ImapFlow extends EventEmitter {
 
         return synteticLogger;
     }
+
+    unbind() {
+        this.socket.unpipe(this.streamer);
+
+        this.socket.removeListener('error', this._socketError);
+        this.socket.removeListener('close', this._socketClose);
+        this.socket.removeListener('end', this._socketEnd);
+        this.socket.removeListener('tlsClientError', this._socketError);
+        this.socket.removeListener('timeout', this._socketTimeout);
+
+        return {
+            socket: this.socket
+        };
+    }
 }
 
 /**

package/lib/types.d.ts

@@ -30,6 +30,7 @@ declare module "imapflow" {
      * @param [options.qresync = false] - If true, then enables QRESYNC support. EXPUNGE notifications will include `uid` property instead of `seq`
      * @param [options.maxIdleTime] - If set, then breaks and restarts IDLE every maxIdleTime ms
      * @param [options.disableBinary = false] - If true, then ignores the BINARY extension when making FETCH and APPEND calls
+     * @param [options.disableAutoEnable] - Do not enable supported extensions by default
      */
     class ImapFlow extends EventEmitter {
         constructor(options: {
@@ -54,10 +55,11 @@ declare module "imapflow" {
             logRaw?: boolean;
             emitLogs?: boolean;
             verifyOnly?: boolean;
-            proxy?: boolean;
+            proxy?: string;
             qresync?: boolean;
             maxIdleTime?: number;
             disableBinary?: boolean;
+            disableAutoEnable?: boolean;
         });
         /**
          * Current module version as a static class property
@@ -151,9 +153,26 @@ declare module "imapflow" {
          * @example
          * let list = await client.list();
          * list.forEach(mailbox=>console.log(mailbox.path));
+         * @param [options] - defines additional listing options
+         * @param [options.statusQuery] - request status items for every listed entry
+         * @param [options.statusQuery.messages] - if `true` request count of messages
+         * @param [options.statusQuery.recent] - if `true` request count of messages with \\Recent tag
+         * @param [options.statusQuery.uidNext] - if `true` request predicted next UID
+         * @param [options.statusQuery.uidValidity] - if `true` request mailbox `UIDVALIDITY` value
+         * @param [options.statusQuery.unseen] - if `true` request count of unseen messages
+         * @param [options.statusQuery.highestModseq] - if `true` request last known modseq value
          * @returns An array of ListResponse objects
          */
-        list(): Promise<ListResponse[]>;
+        list(options?: {
+            statusQuery?: {
+                messages?: boolean;
+                recent?: boolean;
+                uidNext?: boolean;
+                uidValidity?: boolean;
+                unseen?: boolean;
+                highestModseq?: boolean;
+            };
+        }): Promise<ListResponse[]>;
         /**
          * Lists available mailboxes as a tree structured object
          * @example
@@ -581,6 +600,7 @@ declare type QuotaResponse = {
  * @property specialUse - one of special-use flags (if applicable): "\All", "\Archive", "\Drafts", "\Flagged", "\Junk", "\Sent", "\Trash". Additionally INBOX has non-standard "\Inbox" flag set
  * @property listed - `true` if mailbox was found from the output of LIST command
  * @property subscribed - `true` if mailbox was found from the output of LSUB command
+ * @property [status] - If `statusQuery` was used, then this value includes the status response
  */
 declare type ListResponse = {
     path: string;
@@ -593,6 +613,7 @@ declare type ListResponse = {
     specialUse: string;
     listed: boolean;
     subscribed: boolean;
+    status?: StatusObject;
 };
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.0.101",
+    "version": "1.0.104",
     "description": "IMAP Client for Node",
     "main": "./lib/imap-flow.js",
     "scripts": {
@@ -31,9 +31,9 @@
         "@babel/eslint-plugin": "7.18.10",
         "@babel/plugin-syntax-class-properties": "7.12.13",
         "@babel/preset-env": "7.18.10",
-        "@types/node": "18.6.5",
+        "@types/node": "18.7.9",
         "braintree-jsdoc-template": "3.3.0",
-        "eslint": "8.21.0",
+        "eslint": "8.22.0",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "8.5.0",
         "grunt": "1.5.3",
@@ -51,8 +51,8 @@
         "libmime": "5.1.0",
         "libqp": "1.1.0",
         "mailsplit": "5.3.2",
-        "nodemailer": "6.7.7",
-        "pino": "8.4.0",
+        "nodemailer": "6.7.8",
+        "pino": "8.4.2",
         "socks": "2.7.0"
     }
 }