imapflow 1.0.147 → 1.0.149

package/.github/workflows/stale.yml

@@ -0,0 +1,24 @@
+name: 'Close stale issues and PRs'
+on:
+    schedule:
+        - cron: '30 1 * * *'
+
+jobs:
+    stale:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/stale@v8
+              with:
+                  stale-issue-message: 'This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.'
+                  stale-pr-message: 'This PR is stale because it has been open 45 days with no activity. Remove stale label or comment or this will be closed in 10 days.'
+                  close-issue-message: 'This issue was closed because it has been stalled for 15 days with no activity.'
+                  close-pr-message: 'This PR was closed because it has been stalled for 20 days with no activity.'
+                  days-before-issue-stale: 30
+                  days-before-pr-stale: 45
+                  days-before-issue-close: 15
+                  days-before-pr-close: 20
+                  stale-issue-label: 'no-issue-activity'
+                  exempt-issue-labels: 'pending,work-in-progress'
+                  stale-pr-label: 'no-pr-activity'
+                  exempt-pr-labels: 'awaiting-approval,work-in-progress'
+                  repo-token: ${{ secrets.GITHUB_TOKEN }}

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.0.149](https://github.com/postalsys/imapflow/compare/v1.0.148...v1.0.149) (2024-01-31)
+
+
+### Bug Fixes
+
+* **flag-colors:** added a method to set Flag Color. The color is also included in the Fetch response structure ([d840951](https://github.com/postalsys/imapflow/commit/d8409513075b864e9131665af3f1670a0714d05c))
+
+## [1.0.148](https://github.com/postalsys/imapflow/compare/v1.0.147...v1.0.148) (2024-01-16)
+
+
+### Bug Fixes
+
+* **logout:** Fixed race condition for logout and TCP close. Fixes [#161](https://github.com/postalsys/imapflow/issues/161) ([39a7333](https://github.com/postalsys/imapflow/commit/39a7333a39499e4876abb29149f7c72f2f99a63d))
+
 ## [1.0.147](https://github.com/postalsys/imapflow/compare/v1.0.146...v1.0.147) (2023-10-26)
 
 

package/jsdoc.json

@@ -23,6 +23,6 @@
         "encoding": "utf8",
         "private": true,
         "recurse": true,
-        "template": "./node_modules/braintree-jsdoc-template"
+        "template": "./node_modules/imapflow-jsdoc-template"
     }
 }

package/lib/commands/logout.js

@@ -18,6 +18,9 @@ module.exports = async connection => {
         response = await connection.exec('LOGOUT');
         return true;
     } catch (err) {
+        if (err.code === 'NoConnection') {
+            return true;
+        }
         connection.log.warn({ err, cid: connection.id });
         return false;
     } finally {

package/lib/imap-flow.js

@@ -29,7 +29,17 @@ const { PassThrough } = require('stream');
 
 const { proxyConnection } = require('./proxy-connection');
 
-const { comparePaths, updateCapabilities, getFolderTree, formatMessageResponse, getDecoder, packMessageRange, normalizePath, expandRange } = require('./tools');
+const {
+    comparePaths,
+    updateCapabilities,
+    getFolderTree,
+    formatMessageResponse,
+    getDecoder,
+    packMessageRange,
+    normalizePath,
+    expandRange,
+    getColorFlags
+} = require('./tools');
 
 const imapCommands = require('./imap-commands.js');
 
@@ -371,7 +381,9 @@ class ImapFlow extends EventEmitter {
                 let request = this.requestTagMap.get(data.tag);
                 if (request) {
                     this.requestTagMap.delete(request.tag);
-                    request.reject(new Error('Connection not available'));
+                    const error = new Error('Connection not available');
+                    error.code = 'NoConnection';
+                    request.reject(error);
                 }
             }
             return;
@@ -595,6 +607,7 @@ class ImapFlow extends EventEmitter {
 
                     default: {
                         let err = new Error('Invalid server response');
+                        err.code = 'InvalidResponse';
                         err.response = parsed;
                         request.reject(err);
                         break;
@@ -1174,6 +1187,10 @@ class ImapFlow extends EventEmitter {
 
             updateEvent.flags = message.flags;
 
+            if (message.flagColor) {
+                updateEvent.flagColor = message.flagColor;
+            }
+
             this.emit('flags', updateEvent);
         }
     }
@@ -1393,7 +1410,7 @@ class ImapFlow extends EventEmitter {
      * await client.logout();
      */
     async logout() {
-        await this.run('LOGOUT');
+        return await this.run('LOGOUT');
     }
 
     /**
@@ -1432,9 +1449,11 @@ class ImapFlow extends EventEmitter {
         // reject command that is currently processed
         if (this.currentRequest && this.requestTagMap.has(this.currentRequest.tag)) {
             let request = this.requestTagMap.get(this.currentRequest.tag);
-            if (request) {
+            if (request && ['LOGOUT'].includes(request.command)) {
                 this.requestTagMap.delete(request.tag);
-                request.reject(new Error('Connection not available'));
+                const error = new Error('Connection not available');
+                error.code = 'NoConnection';
+                request.reject(error);
             }
             this.currentRequest = false;
         }
@@ -1446,7 +1465,9 @@ class ImapFlow extends EventEmitter {
                 let request = this.requestTagMap.get(req.tag);
                 if (request) {
                     this.requestTagMap.delete(request.tag);
-                    request.reject(new Error('Connection not available'));
+                    const error = new Error('Connection not available');
+                    error.code = 'NoConnection';
+                    request.reject(error);
                 }
             }
         }
@@ -1919,6 +1940,68 @@ class ImapFlow extends EventEmitter {
         return await this.run('STORE', range, flags, queryOpts);
     }
 
+    /**
+     * Sets a colored flag for an email. Only supported by mail clients like Apple Mail
+     *
+     * @param {SequenceString | Number[] | SearchObject} range Range to filter the messages
+     * @param {string} The color to set. One of 'red', 'orange', 'yellow', 'green', 'blue', 'purple', and 'grey'
+     * @param {Object} [options]
+     * @param {Boolean} [options.uid] If `true` then uses UID {@link SequenceString} instead of sequence numbers
+     * @param {BigInt} [options.unchangedSince] If set then only messages with a lower or equal `modseq` value are updated. Ignored if server does not support `CONDSTORE` extension.
+     * @returns {Promise<Boolean>} Did the operation succeed or not
+     *
+     * @example
+     * let mailbox = await client.mailboxOpen('INBOX');
+     * // add a purple flag for all emails
+     * await client.setFlagColor('1:*', 'Purple');
+     */
+    async setFlagColor(range, color, options) {
+        options = options || {};
+
+        range = await this.resolveRange(range, options);
+        if (!range) {
+            return false;
+        }
+
+        let flagChanges = getColorFlags(color);
+        if (!flagChanges) {
+            return false;
+        }
+
+        let addResults;
+        let removeResults;
+
+        if (flagChanges.add && flagChanges.add.length) {
+            let queryOpts = Object.assign(
+                {
+                    operation: 'add'
+                },
+                options,
+                {
+                    useLabels: false, // override if set
+                    // prevent triggering a premature Flags change notification
+                    silent: flagChanges.remove && flagChanges.remove.length
+                }
+            );
+
+            addResults = await this.run('STORE', range, flagChanges.add, queryOpts);
+        }
+
+        if (flagChanges.remove && flagChanges.remove.length) {
+            let queryOpts = Object.assign(
+                {
+                    operation: 'remove'
+                },
+                options,
+                { useLabels: false } // override if set
+            );
+
+            removeResults = await this.run('STORE', range, flagChanges.remove, queryOpts);
+        }
+
+        return addResults || removeResults || false;
+    }
+
     /**
      * Delete messages from currently opened mailbox. Method does not indicate info about deleted messages,
      * instead you should be using {@link ImapFlow#expunge} event for this
@@ -2070,7 +2153,7 @@ class ImapFlow extends EventEmitter {
      * @typedef {Object} FetchQueryObject
      * @global
      * @property {Boolean} [uid] if `true` then include UID in the response
-     * @property {Boolean} [flags] if `true` then include flags Set in the response
+     * @property {Boolean} [flags] if `true` then include flags Set in the response. Also adds `flagColor` to the response if the message is flagged.
      * @property {Boolean} [bodyStructure] if `true` then include parsed BODYSTRUCTURE object in the response
      * @property {Boolean} [envelope] if `true` then include parsed ENVELOPE object in the response
      * @property {Boolean} [internalDate] if `true` then include internal date value in the response
@@ -2141,6 +2224,7 @@ class ImapFlow extends EventEmitter {
      * @property {Set<string>} [labels] a Set of labels. Only present if server supports `X-GM-EXT-1` extension
      * @property {Number} [size] message size
      * @property {Set<string>} [flags] a set of message flags
+     * @property {String} [flagColor] flag color like "red", or "yellow". This value is derived from the `flags` Set and it uses the same color rules as Apple Mail
      * @property {MessageEnvelopeObject} [envelope] message envelope
      * @property {MessageStructureObject} [bodyStructure] message body structure
      * @property {Date} [internalDate] message internal date
@@ -2602,7 +2686,7 @@ class ImapFlow extends EventEmitter {
      * @example
      * let mailbox = await client.mailboxOpen('INBOX');
      * // download body parts '2', and '3' from all messages in the selected mailbox
-     * let response = await client.downloadMany('*', ['2', '3]);
+     * let response = await client.downloadMany('*', ['2', '3']);
      * process.stdout.write(response[2].content)
      * process.stdout.write(response[3].content)
      */
@@ -2728,8 +2812,9 @@ class ImapFlow extends EventEmitter {
         }
 
         if (this.socket.destroyed) {
-            let err = new Error('Connection not available');
-            throw err;
+            const error = new Error('Connection not available');
+            error.code = 'NoConnection';
+            throw error;
         }
 
         clearTimeout(this.idleStartTimer);
@@ -2771,10 +2856,11 @@ class ImapFlow extends EventEmitter {
         const { resolve, reject, path, options, lockId } = this.locks.shift();
 
         if (!this.usable || this.socket.destroyed) {
-            // reject all
-            let err = new Error('Connection not available');
             this.log.trace({ msg: 'Failed to acquire mailbox lock', path, lockId });
-            reject(err);
+            // reject all
+            let error = new Error('Connection not available');
+            error.code = 'NoConnection';
+            reject(error);
             return await this.processLocks(true);
         }
 

package/lib/tools.js

@@ -8,6 +8,8 @@ const { createHash } = require('crypto');
 const { JPDecoder } = require('./jp-decoder');
 const iconv = require('iconv-lite');
 
+const FLAG_COLORS = ['red', 'orange', 'yellow', 'green', 'blue', 'purple', 'grey'];
+
 module.exports = {
     encodePath(connection, path) {
         path = (path || '').toString();
@@ -191,6 +193,43 @@ module.exports = {
         return tree;
     },
 
+    getFlagColor(flags) {
+        if (!flags.has('\\Flagged')) {
+            return null;
+        }
+
+        const bit0 = flags.has('$MailFlagBit0') ? 1 : 0;
+        const bit1 = flags.has('$MailFlagBit1') ? 2 : 0;
+        const bit2 = flags.has('$MailFlagBit2') ? 4 : 0;
+
+        const color = bit0 | bit1 | bit2; // eslint-disable-line no-bitwise
+
+        return FLAG_COLORS[color] || 'red'; // default to red for the unused \b111
+    },
+
+    getColorFlags(color) {
+        const colorCode = color ? FLAG_COLORS.indexOf((color || '').toString().toLowerCase().trim()) : null;
+        if (colorCode < 0 && colorCode !== null) {
+            return null;
+        }
+
+        const bits = [];
+        bits[0] = colorCode & 1; // eslint-disable-line no-bitwise
+        bits[1] = colorCode & 2; // eslint-disable-line no-bitwise
+        bits[2] = colorCode & 4; // eslint-disable-line no-bitwise
+
+        let result = { add: colorCode ? ['\\Flagged'] : [], remove: colorCode ? [] : ['\\Flagged'] };
+
+        for (let i = 0; i < bits.length; i++) {
+            if (bits[i]) {
+                result.add.push(`$MailFlagBit${i}`);
+            } else {
+                result.remove.push(`$MailFlagBit${i}`);
+            }
+        }
+        return result;
+    },
+
     async formatMessageResponse(untagged, mailbox) {
         let map = {};
 
@@ -351,6 +390,13 @@ module.exports = {
             map.id = map.emailId || createHash('md5').update([path, mailbox.uidValidity.toString(), map.uid.toString()].join(':')).digest('hex');
         }
 
+        if (map.flags) {
+            let flagColor = module.exports.getFlagColor(map.flags);
+            if (flagColor) {
+                map.flagColor = flagColor;
+            }
+        }
+
         return map;
     },
 

package/lib/types.d.ts

@@ -364,6 +364,22 @@ declare module "imapflow" {
             unchangedSince?: bigint;
             useLabels?: boolean;
         }): Promise<Boolean>;
+        /**
+         * Sets a colored flag for an email. Only supported by mail clients like Apple Mail
+         * @example
+         * let mailbox = await client.mailboxOpen('INBOX');
+         * // add a purple flag for all emails
+         * await client.setFlagColor('1:*', 'Purple');
+         * @param range - Range to filter the messages
+         * @param The - color to set. One of 'red', 'orange', 'yellow', 'green', 'blue', 'purple', and 'grey'
+         * @param [options.uid] - If `true` then uses UID {@link SequenceString} instead of sequence numbers
+         * @param [options.unchangedSince] - If set then only messages with a lower or equal `modseq` value are updated. Ignored if server does not support `CONDSTORE` extension.
+         * @returns Did the operation succeed or not
+         */
+        setFlagColor(range: SequenceString | Number[] | SearchObject, The: string, options?: {
+            uid?: boolean;
+            unchangedSince?: bigint;
+        }): Promise<Boolean>;
         /**
          * Delete messages from currently opened mailbox. Method does not indicate info about deleted messages,
          * instead you should be using {@link ImapFlow#expunge} event for this
@@ -502,7 +518,7 @@ declare module "imapflow" {
          * @example
          * let mailbox = await client.mailboxOpen('INBOX');
          * // download body parts '2', and '3' from all messages in the selected mailbox
-         * let response = await client.downloadMany('*', ['2', '3]);
+         * let response = await client.downloadMany('*', ['2', '3']);
          * process.stdout.write(response[2].content)
          * process.stdout.write(response[3].content)
          * @param range - UID or sequence number for the message to fetch
@@ -832,7 +848,7 @@ declare type CopyResponseObject = {
 
 /**
  * @property [uid] - if `true` then include UID in the response
- * @property [flags] - if `true` then include flags Set in the response
+ * @property [flags] - if `true` then include flags Set in the response. Also adds `flagColor` to the response if the message is flagged.
  * @property [bodyStructure] - if `true` then include parsed BODYSTRUCTURE object in the response
  * @property [envelope] - if `true` then include parsed ENVELOPE object in the response
  * @property [internalDate] - if `true` then include internal date value in the response
@@ -935,6 +951,7 @@ declare type MessageStructureObject = {
  * @property [labels] - a Set of labels. Only present if server supports `X-GM-EXT-1` extension
  * @property [size] - message size
  * @property [flags] - a set of message flags
+ * @property [flagColor] - flag color like "red", or "yellow". This value is derived from the `flags` Set and it uses the same color rules as Apple Mail
  * @property [envelope] - message envelope
  * @property [bodyStructure] - message body structure
  * @property [internalDate] - message internal date
@@ -951,6 +968,7 @@ declare type FetchMessageObject = {
     labels?: Set<string>;
     size?: number;
     flags?: Set<string>;
+    flagColor?: string;
     envelope?: MessageEnvelopeObject;
     bodyStructure?: MessageStructureObject;
     internalDate?: Date;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.0.147",
+    "version": "1.0.149",
     "description": "IMAP Client for Node",
     "main": "./lib/imap-flow.js",
     "scripts": {
@@ -28,19 +28,19 @@
     },
     "homepage": "https://imapflow.com/",
     "devDependencies": {
-        "@babel/eslint-parser": "7.22.15",
-        "@babel/eslint-plugin": "7.22.10",
+        "@babel/eslint-parser": "7.23.9",
+        "@babel/eslint-plugin": "7.23.5",
         "@babel/plugin-syntax-class-properties": "7.12.13",
-        "@babel/preset-env": "7.23.2",
-        "@types/node": "20.8.9",
-        "braintree-jsdoc-template": "3.3.0",
-        "eslint": "8.52.0",
+        "@babel/preset-env": "7.23.9",
+        "@types/node": "20.11.13",
+        "eslint": "8.56.0",
         "eslint-config-nodemailer": "1.2.0",
-        "eslint-config-prettier": "9.0.0",
+        "eslint-config-prettier": "9.1.0",
         "grunt": "1.6.1",
         "grunt-cli": "1.4.3",
         "grunt-contrib-nodeunit": "5.0.0",
         "grunt-eslint": "24.3.0",
+        "imapflow-jsdoc-template": "3.4.0-imapflow.1",
         "jsdoc": "3.6.11",
         "st": "3.0.0",
         "tsd-jsdoc": "2.5.0"
@@ -52,8 +52,8 @@
         "libmime": "5.2.1",
         "libqp": "2.0.1",
         "mailsplit": "5.4.0",
-        "nodemailer": "6.9.7",
-        "pino": "8.16.1",
+        "nodemailer": "6.9.8",
+        "pino": "8.17.2",
         "socks": "2.7.1"
     }
 }