imapflow 1.0.100 → 1.0.103

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/README.md

@@ -1,14 +1,16 @@
 # ImapFlow
 
+ImapFlow is a modern and easy-to-use IMAP client library for Node.js.
+
 ---
 
-> Managing IMAP connections is cool, but if you are only looking for an easy way to integrate email accounts, then ImapFlow was built for [EmailEngine Email API](https://emailengine.app/). It's a self-hosted software that converts all IMAP accounts to easy-to-use REST interfaces.
+> Managing an IMAP connection is cool, but if you are only looking for an easy way to integrate email accounts, then ImapFlow was built for [EmailEngine Email API](https://emailengine.app/). It's a self-hosted software that converts all IMAP accounts to easy-to-use REST interfaces.
 
 ---
 
 The focus for ImapFlow is to provide easy to use API over IMAP. Using ImapFlow does not expect knowledge about specific IMAP details. A general understanding is good enough.
 
-IMAP extensions are handled in the background, so for example, you can always request `labels` value from a {@link FetchQueryObject|fetch()} call, but if the IMAP server does not support `X-GM-EXT1` extension, then `labels` value is not included in the response.
+IMAP extensions are handled in the background, so, for example, you can always request `labels` value from a {@link FetchQueryObject|fetch()} call, but if the IMAP server does not support `X-GM-EXT1` extension, then `labels` value is not included in the response.
 
 ## Source
 

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

@@ -121,7 +121,7 @@ class ImapFlow extends EventEmitter {
      * @param {Boolean} [options.disableAutoIdle=false] if `true` then IDLE is not started automatically. Useful if you only need to perform specific tasks over the connection
      * @param {Object} [options.tls] Additional TLS options (see [Node.js TLS connect](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback) for all available options)
      * @param {Boolean} [options.tls.rejectUnauthorized=true] if `false` then client accepts self-signed and expired certificates from the server
-     * @param {String} [options.tls.minVersion=TLSv1.2] latest Node.js defaults to *'TLSv1.2'*, for older mail servers you might need to use something else, eg *'TLSv1'*
+     * @param {String} [options.tls.minVersion=TLSv1] To improvde security you might need to use something newer, eg *'TLSv1.2'*
      * @param {Number} [options.tls.minDHSize=1024] Minimum size of the DH parameter in bits to accept a TLS connection
      * @param {Object} [options.logger] Custom logger instance with `debug(obj)`, `info(obj)`, `warn(obj)` and `error(obj)` methods. If not provided then ImapFlow logs to console using pino format
      * @param {Boolean} [options.logRaw=false] If true then log data read from and written to socket encoded in base64
@@ -731,7 +731,8 @@ class ImapFlow extends EventEmitter {
                     socket: this.socket,
                     servername: this.servername,
                     port: this.port,
-                    minVersion: 'TLSv1'
+                    minVersion: 'TLSv1',
+                    minDHSize: 1024
                 },
                 this.options.tls || {}
             );
@@ -1140,7 +1141,8 @@ class ImapFlow extends EventEmitter {
                 host: this.host,
                 servername: this.servername,
                 port: this.port,
-                minVersion: 'TLSv1'
+                minVersion: 'TLSv1',
+                minDHSize: 1024
             },
             this.options.tls || {}
         );
@@ -1390,19 +1392,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;
     }

package/lib/search-compiler.js

@@ -120,6 +120,10 @@ module.exports.searchCompiler = (connection, query) => {
                 case 'GMRAW':
                     if (connection.capabilities.has('X-GM-EXT-1')) {
                         setOpt(attributes, 'X-GM-RAW', params[term]);
+                    } else {
+                        let error = new Error('Server does not support X-GM-EXT-1 extension required for X-GM-RAW');
+                        error.code = 'MissingServerExtension';
+                        throw error;
                     }
                     break;
 

package/lib/types.d.ts

@@ -20,7 +20,7 @@ declare module "imapflow" {
      * @param [options.disableAutoIdle = false] - if `true` then IDLE is not started automatically. Useful if you only need to perform specific tasks over the connection
      * @param [options.tls] - Additional TLS options (see [Node.js TLS connect](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback) for all available options)
      * @param [options.tls.rejectUnauthorized = true] - if `false` then client accepts self-signed and expired certificates from the server
-     * @param [options.tls.minVersion = TLSv1.2] - latest Node.js defaults to *'TLSv1.2'*, for older mail servers you might need to use something else, eg *'TLSv1'*
+     * @param [options.tls.minVersion = TLSv1] - To improvde security you might need to use something newer, eg *'TLSv1.2'*
      * @param [options.tls.minDHSize = 1024] - Minimum size of the DH parameter in bits to accept a TLS connection
      * @param [options.logger] - Custom logger instance with `debug(obj)`, `info(obj)`, `warn(obj)` and `error(obj)` methods. If not provided then ImapFlow logs to console using pino format
      * @param [options.logRaw = false] - If true then log data read from and written to socket encoded in base64
@@ -151,9 +151,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 +598,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 +611,7 @@ declare type ListResponse = {
     specialUse: string;
     listed: boolean;
     subscribed: boolean;
+    status?: StatusObject;
 };
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.0.100",
+    "version": "1.0.103",
     "description": "IMAP Client for Node",
     "main": "./lib/imap-flow.js",
     "scripts": {
@@ -27,20 +27,20 @@
     },
     "homepage": "https://imapflow.com/",
     "devDependencies": {
-        "@babel/eslint-parser": "7.18.2",
-        "@babel/eslint-plugin": "7.17.7",
+        "@babel/eslint-parser": "7.18.9",
+        "@babel/eslint-plugin": "7.18.10",
         "@babel/plugin-syntax-class-properties": "7.12.13",
-        "@babel/preset-env": "7.18.2",
-        "@types/node": "18.0.0",
+        "@babel/preset-env": "7.18.10",
+        "@types/node": "18.7.6",
         "braintree-jsdoc-template": "3.3.0",
-        "eslint": "8.18.0",
+        "eslint": "8.22.0",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "8.5.0",
         "grunt": "1.5.3",
         "grunt-cli": "1.4.3",
         "grunt-contrib-nodeunit": "4.0.0",
         "grunt-eslint": "24.0.0",
-        "jsdoc": "3.6.10",
+        "jsdoc": "3.6.11",
         "st": "3.0.0",
         "tsd-jsdoc": "2.5.0"
     },
@@ -51,8 +51,8 @@
         "libmime": "5.1.0",
         "libqp": "1.1.0",
         "mailsplit": "5.3.2",
-        "nodemailer": "6.7.5",
-        "pino": "8.0.0",
-        "socks": "2.6.2"
+        "nodemailer": "6.7.8",
+        "pino": "8.4.1",
+        "socks": "2.7.0"
     }
 }