imapflow 1.0.78 → 1.0.82

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # CHANGELOG
 
+-   1.0.82 - 2022-02-15
+
+    -   Added extra option `expungeHandler`
+
+-   1.0.81 - 2022-02-15
+
+    -   Added support for the QRESYNC extension and untagged VANISHED responses
+
+-   1.0.80 - 2022-02-07
+
+    -   Added support for the missing NOMODSEQ mailbox modifier
+
+-   1.0.79 - 2021-12-29
+
+    -   Added property `greeting` that contains that first response from the server
+
 -   1.0.78 - 2021-11-28
 
     -   Proxy support. Use configuration options `proxy: "url"` to use proxies

package/README.md

@@ -2,13 +2,13 @@
 
 ---
 
-> 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 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.
 
 ---
 
-The focus for ImapFlow is to provide easy to use API over IMAP. Using ImapFlow does not expect knowledge about specific IMAP details, general understanding is good enough.
+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/expunge.js

@@ -20,6 +20,17 @@ module.exports = async (connection, range, options) => {
     let response;
     try {
         response = await connection.exec(command, attributes);
+
+        // A OK [HIGHESTMODSEQ 9122] Expunge completed (0.010 + 0.000 + 0.012 secs).
+        let section = response.response.attributes && response.response.attributes[0] && response.response.attributes[0].section;
+        let responseCode = section && section.length && section[0] && typeof section[0].value === 'string' ? section[0].value : '';
+        if (responseCode.toUpperCase() === 'HIGHESTMODSEQ') {
+            let highestModseq = section[1] && typeof section[1].value === 'string' && !isNaN(section[1].value) ? BigInt(section[1].value) : false;
+            if (highestModseq && (!connection.mailbox.highestModseq || highestModseq > connection.mailbox.highestModseq)) {
+                connection.mailbox.highestModseq = highestModseq;
+            }
+        }
+
         response.next();
         return true;
     } catch (err) {

package/lib/commands/fetch.js

@@ -86,7 +86,7 @@ module.exports = async (connection, range, query, options) => {
         }
 
         // always ask for modseq if possible
-        if (connection.enabled.has('CONDSTORE')) {
+        if (connection.enabled.has('CONDSTORE') && !mailbox.noModseq) {
             queryStructure.push({ type: 'ATOM', value: 'MODSEQ' });
         }
 
@@ -137,8 +137,8 @@ module.exports = async (connection, range, query, options) => {
 
         attributes.push(queryStructure);
 
-        if (options.changedSince && connection.enabled.has('CONDSTORE')) {
-            attributes.push([
+        if (options.changedSince && connection.enabled.has('CONDSTORE') && !mailbox.noModseq) {
+            let changedSinceArgs = [
                 {
                     type: 'ATOM',
                     value: 'CHANGEDSINCE'
@@ -147,7 +147,16 @@ module.exports = async (connection, range, query, options) => {
                     type: 'ATOM',
                     value: options.changedSince.toString()
                 }
-            ]);
+            ];
+
+            if (options.uid && connection.enabled.has('QRESYNC')) {
+                changedSinceArgs.push({
+                    type: 'ATOM',
+                    value: 'VANISHED'
+                });
+            }
+
+            attributes.push(changedSinceArgs);
         }
 
         response = await connection.exec(options.uid ? 'UID FETCH' : 'FETCH', attributes, {

package/lib/commands/select.js

@@ -21,6 +21,7 @@ module.exports = async (connection, path, options) => {
             connection.folders.set(folder.path, folder);
         });
     }
+
     let folderListData = connection.folders.has(path) ? connection.folders.get(path) : false;
 
     let response;
@@ -33,7 +34,19 @@ module.exports = async (connection, path, options) => {
                 }
             });
         }
-        response = await connection.exec(!options.readOnly ? 'SELECT' : 'EXAMINE', [{ type: 'ATOM', value: path }], {
+
+        let extraArgs = [];
+        if (connection.enabled.has('QRESYNC') && options.changedSince && options.uidValidity) {
+            extraArgs.push([
+                { type: 'ATOM', value: 'QRESYNC' },
+                [
+                    { type: 'ATOM', value: options.uidValidity },
+                    { type: 'ATOM', value: options.changedSince }
+                ]
+            ]);
+        }
+
+        response = await connection.exec(!options.readOnly ? 'SELECT' : 'EXAMINE', [{ type: 'ATOM', value: path }].concat(extraArgs || []), {
             untagged: {
                 OK: async untagged => {
                     if (!untagged.attributes || !untagged.attributes.length) {
@@ -85,6 +98,16 @@ module.exports = async (connection, path, options) => {
 
                         map[key] = value;
                     }
+
+                    if (section && section.length === 1 && section[0].type === 'ATOM' && typeof section[0].value === 'string') {
+                        let key = section[0].value.toLowerCase();
+                        switch (key) {
+                            case 'nomodseq':
+                                key = 'noModseq';
+                                map[key] = true;
+                                break;
+                        }
+                    }
                 },
                 FLAGS: async untagged => {
                     if (!untagged.attributes || (!untagged.attributes.length && Array.isArray(untagged.attributes[0]))) {
@@ -100,6 +123,21 @@ module.exports = async (connection, path, options) => {
                     }
 
                     map.exists = num;
+                },
+                VANISHED: async untagged => {
+                    await connection.untaggedVanished(
+                        untagged,
+                        // mailbox is not yet open, so use a dummy mailbox object
+                        { path, uidNext: false, uidValidity: false }
+                    );
+                },
+                // we should only get an untagged FETCH for a SELECT/EXAMINE if QRESYNC was asked for
+                FETCH: async untagged => {
+                    await connection.untaggedFetch(
+                        untagged,
+                        // mailbox is not yet open, so use a dummy mailbox object
+                        { path, uidNext: false, uidValidity: false }
+                    );
                 }
             }
         });

package/lib/commands/store.js

@@ -53,7 +53,7 @@ module.exports = async (connection, range, flags, options) => {
 
     let attributes = [{ type: 'SEQUENCE', value: range }, { type: 'ATOM', value: operation }, flags.map(flag => ({ type: 'ATOM', value: flag }))];
 
-    if (options.unchangedSince && connection.enabled.has('CONDSTORE')) {
+    if (options.unchangedSince && connection.enabled.has('CONDSTORE') && !connection.mailbox.noModseq) {
         attributes.push([
             {
                 type: 'ATOM',

package/lib/handler/imap-compiler.js

@@ -117,11 +117,13 @@ module.exports = async (response, options) => {
             case 'SECTION':
                 val = (node.value || '').toString('binary');
 
-                if (node.value === '' || imapFormalSyntax.verify(val.charAt(0) === '\\' ? val.substr(1) : val, imapFormalSyntax['ATOM-CHAR']()) >= 0) {
-                    val = JSON.stringify(val);
-                }
+                if (!node.section || val) {
+                    if (node.value === '' || imapFormalSyntax.verify(val.charAt(0) === '\\' ? val.substr(1) : val, imapFormalSyntax['ATOM-CHAR']()) >= 0) {
+                        val = JSON.stringify(val);
+                    }
 
-                resp += val;
+                    resp += val;
+                }
 
                 if (node.section) {
                     resp += '[';

package/lib/imap-flow.js

@@ -29,7 +29,7 @@ const { PassThrough } = require('stream');
 
 const { proxyConnection } = require('./proxy-connection');
 
-const { comparePaths, updateCapabilities, getFolderTree, formatMessageResponse, getDecoder, packMessageRange, normalizePath } = require('./tools');
+const { comparePaths, updateCapabilities, getFolderTree, formatMessageResponse, getDecoder, packMessageRange, normalizePath, expandRange } = require('./tools');
 
 const imapCommands = require('./imap-commands.js');
 
@@ -58,6 +58,7 @@ const states = {
  * @property {Set<string>} permanentFlags A Set of flags available to use in this mailbox. If it is not set or includes special flag "\\\*" then any flag can be used.
  * @property {String} [mailboxId] unique mailbox ID if server has `OBJECTID` extension enabled
  * @property {BigInt} [highestModseq] latest known modseq value if server has CONDSTORE or XYMHIGHESTMODSEQ enabled
+ * @property {String} [noModseq] if true then the server doesn't support the persistent storage of mod-sequences for the mailbox
  * @property {BigInt} uidValidity Mailbox `UIDVALIDITY` value
  * @property {Number} uidNext Next predicted UID
  * @property {Number} exists Messages in this folder
@@ -127,9 +128,10 @@ class ImapFlow extends EventEmitter {
      * @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 {Boolean} [options.qresync=false] If true, then enables QRESYNC support. EXPUNGE notifications will include `uid` property instead of `seq`
      */
     constructor(options) {
-        super();
+        super({ captureRejections: true });
 
         this.options = options || {};
 
@@ -616,7 +618,7 @@ class ImapFlow extends EventEmitter {
         }
 
         // enable extensions if possible
-        await this.run('ENABLE', ['CONDSTORE', 'UTF8=ACCEPT']);
+        await this.run('ENABLE', ['CONDSTORE', 'UTF8=ACCEPT'].concat(this.options.qresync ? 'QRESYNC' : []));
 
         this.usable = true;
     }
@@ -808,7 +810,13 @@ class ImapFlow extends EventEmitter {
         return false;
     }
 
-    async initialOK() {
+    async initialOK(message) {
+        this.greeting = (message.attributes || [])
+            .filter(entry => entry.type === 'TEXT')
+            .map(entry => entry.value)
+            .filter(entry => entry)
+            .join('');
+
         clearTimeout(this.greetingTimeout);
         this.untaggedHandlers.OK = null;
         this.untaggedHandlers.PREAUTH = null;
@@ -934,23 +942,76 @@ class ImapFlow extends EventEmitter {
         let seq = Number(untagged.command);
         if (seq && seq <= this.mailbox.exists) {
             this.mailbox.exists--;
-            this.emit('expunge', {
+            let payload = {
                 path: this.mailbox.path,
-                seq
-            });
+                seq,
+                vanished: false
+            };
+
+            if (typeof this.options.expungeHandler === 'function') {
+                try {
+                    await this.options.expungeHandler(payload);
+                } catch (err) {
+                    this.log.error({ msg: 'Failed to notify expunge event', payload, error: err, cid: this.id });
+                }
+            } else {
+                this.emit('expunge', payload);
+            }
         }
     }
 
-    async untaggedFetch(untagged) {
-        if (!this.mailbox) {
+    async untaggedVanished(untagged, mailbox) {
+        mailbox = mailbox || this.mailbox;
+        if (!mailbox) {
+            // mailbox closed, ignore
+            return;
+        }
+
+        let tags = [];
+        let uids = false;
+
+        if (untagged.attributes.length > 1 && Array.isArray(untagged.attributes[0])) {
+            tags = untagged.attributes[0].map(entry => (typeof entry.value === 'string' ? entry.value.toUpperCase() : false)).filter(value => value);
+            untagged.attributes.shift();
+        }
+
+        if (untagged.attributes[0] && typeof untagged.attributes[0].value === 'string') {
+            uids = untagged.attributes[0].value;
+        }
+
+        let uidList = expandRange(uids);
+
+        for (let uid of uidList) {
+            let payload = {
+                path: mailbox.path,
+                uid,
+                vanished: true,
+                earlier: tags.includes('EARLIER')
+            };
+
+            if (typeof this.options.expungeHandler === 'function') {
+                try {
+                    await this.options.expungeHandler(payload);
+                } catch (err) {
+                    this.log.error({ msg: 'Failed to notify expunge event', payload, error: err, cid: this.id });
+                }
+            } else {
+                this.emit('expunge', payload);
+            }
+        }
+    }
+
+    async untaggedFetch(untagged, mailbox) {
+        mailbox = mailbox || this.mailbox;
+        if (!mailbox) {
             // mailbox closed, ignore
             return;
         }
 
-        let message = await formatMessageResponse(untagged, this.mailbox);
+        let message = await formatMessageResponse(untagged, mailbox);
         if (message.flags) {
             let updateEvent = {
-                path: this.mailbox.path,
+                path: mailbox.path,
                 seq: message.seq
             };
 
@@ -1053,10 +1114,13 @@ class ImapFlow extends EventEmitter {
         this.untaggedHandlers.CAPABILITY = (...args) => this.untaggedCapability(...args);
         this.sectionHandlers.CAPABILITY = (...args) => this.sectionCapability(...args);
 
-        this.untaggedHandlers.FETCH = (...args) => this.untaggedFetch(...args);
         this.untaggedHandlers.EXISTS = (...args) => this.untaggedExists(...args);
         this.untaggedHandlers.EXPUNGE = (...args) => this.untaggedExpunge(...args);
 
+        // these methods take an optional second argument, so make sure that some random IMAP tag is not used as the second argument
+        this.untaggedHandlers.FETCH = untagged => this.untaggedFetch(untagged);
+        this.untaggedHandlers.VANISHED = untagged => this.untaggedVanished(untagged);
+
         let socket = false;
         if (this.options.proxy) {
             try {

package/lib/types.d.ts

@@ -27,6 +27,7 @@ declare module "imapflow" {
      * @param [options.emitLogs = false] - If `true` then in addition of sending data to logger, ImapFlow emits 'log' events with the same data
      * @param [options.verifyOnly = false] - If `true` then logs out automatically after successful authentication
      * @param [options.proxy] - Optional proxy URL. Supports HTTP CONNECT (`http://`, `https://`) and SOCKS (`socks://`, `socks4://`, `socks5://`) proxies
+     * @param [options.qresync = false] - If true, then enables QRESYNC support. EXPUNGE notifications will include `uid` property instead of `seq`
      */
     class ImapFlow extends EventEmitter {
         constructor(options: {
@@ -52,6 +53,7 @@ declare module "imapflow" {
             emitLogs?: boolean;
             verifyOnly?: boolean;
             proxy?: boolean;
+            qresync?: boolean;
         });
         /**
          * Current module version as a static class property
@@ -483,6 +485,7 @@ declare module "imapflow" {
  * @property permanentFlags - A Set of flags available to use in this mailbox. If it is not set or includes special flag "\\\*" then any flag can be used.
  * @property [mailboxId] - unique mailbox ID if server has `OBJECTID` extension enabled
  * @property [highestModseq] - latest known modseq value if server has CONDSTORE or XYMHIGHESTMODSEQ enabled
+ * @property [noModseq] - if true then the server doesn't support the persistent storage of mod-sequences for the mailbox
  * @property uidValidity - Mailbox `UIDVALIDITY` value
  * @property uidNext - Next predicted UID
  * @property exists - Messages in this folder
@@ -497,6 +500,7 @@ declare type MailboxObject = {
     permanentFlags: Set<string>;
     mailboxId?: string;
     highestModseq?: bigint;
+    noModseq?: string;
     uidValidity: bigint;
     uidNext: number;
     exists: number;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.0.78",
+    "version": "1.0.82",
     "description": "IMAP Client for Node",
     "main": "./lib/imap-flow.js",
     "scripts": {
@@ -26,20 +26,20 @@
     },
     "homepage": "https://imapflow.com/",
     "devDependencies": {
-        "@babel/eslint-parser": "7.16.3",
-        "@babel/eslint-plugin": "7.14.5",
+        "@babel/eslint-parser": "7.17.0",
+        "@babel/eslint-plugin": "7.16.5",
         "@babel/plugin-syntax-class-properties": "7.12.13",
-        "@babel/preset-env": "7.16.4",
-        "@types/node": "16.11.10",
+        "@babel/preset-env": "7.16.11",
+        "@types/node": "17.0.18",
         "braintree-jsdoc-template": "3.3.0",
-        "eslint": "8.3.0",
+        "eslint": "8.9.0",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "8.3.0",
         "grunt": "1.4.1",
         "grunt-cli": "1.4.3",
         "grunt-contrib-nodeunit": "4.0.0",
         "grunt-eslint": "24.0.0",
-        "jsdoc": "3.6.7",
+        "jsdoc": "3.6.10",
         "tsd-jsdoc": "2.5.0"
     },
     "dependencies": {
@@ -50,7 +50,7 @@
         "libqp": "1.1.0",
         "mailsplit": "5.3.1",
         "nodemailer": "6.7.2",
-        "pino": "7.4.1",
-        "socks": "2.6.1"
+        "pino": "7.8.0",
+        "socks": "2.6.2"
     }
 }