imapflow 1.3.7 → 1.4.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.3.7"
+    ".": "1.4.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.4.0](https://github.com/postalsys/imapflow/compare/v1.3.7...v1.4.0) (2026-06-09)
+
+
+### Features
+
+* add Gmail label search term to the search compiler ([4b2d173](https://github.com/postalsys/imapflow/commit/4b2d1736660441e95cd55a30ad6632a676fb605c))
+
 ## [1.3.7](https://github.com/postalsys/imapflow/compare/v1.3.6...v1.3.7) (2026-06-08)
 
 

package/lib/imap-flow.d.ts

@@ -357,6 +357,8 @@ export interface SearchObject {
     gmraw?: string;
     /** Gmail raw search query (alias for gmraw) */
     gmailraw?: string;
+    /** Gmail label filter (only for Gmail). Compiles to an X-GM-RAW "label:"/"-label:" query. "has" matches messages carrying all listed labels, "not" excludes messages carrying any listed label */
+    labels?: { has?: string[]; not?: string[] };
 }
 
 export interface FetchQueryObject {
@@ -373,12 +375,14 @@ export interface FetchQueryObject {
     /** If true then include message size in the response */
     size?: boolean;
     /** If true then include full message in the response */
-    source?: boolean | {
-        /** Include full message in the response starting from start byte */
-        start?: number;
-        /** Include full message in the response, up to maxLength bytes */
-        maxLength?: number;
-    };
+    source?:
+        | boolean
+        | {
+              /** Include full message in the response starting from start byte */
+              start?: number;
+              /** Include full message in the response, up to maxLength bytes */
+              maxLength?: number;
+          };
     /** If true then include thread ID in the response (only if server supports either OBJECTID or X-GM-EXT-1 extensions) */
     threadId?: boolean;
     /** If true then include GMail labels in the response (only if server supports X-GM-EXT-1 extension) */
@@ -740,14 +744,17 @@ export class ImapFlow extends EventEmitter {
     mailboxClose(): Promise<boolean>;
 
     /** Requests the status of the indicated mailbox */
-    status(path: string, query: {
-        messages?: boolean;
-        recent?: boolean;
-        uidNext?: boolean;
-        uidValidity?: boolean;
-        unseen?: boolean;
-        highestModseq?: boolean;
-    }): Promise<StatusObject>;
+    status(
+        path: string,
+        query: {
+            messages?: boolean;
+            recent?: boolean;
+            uidNext?: boolean;
+            uidValidity?: boolean;
+            unseen?: boolean;
+            highestModseq?: boolean;
+        }
+    ): Promise<StatusObject>;
 
     /** Starts listening for new or deleted messages from the currently opened mailbox */
     idle(): Promise<boolean>;
@@ -779,10 +786,13 @@ export class ImapFlow extends EventEmitter {
     /** Search messages from the currently opened mailbox — returns number[] (backward-compatible) */
     search(query: SearchObject, options?: { uid?: boolean }): Promise<number[] | false>;
     /** Search messages with ESEARCH RETURN options — returns ESearchResult */
-    search(query: SearchObject, options: {
-        uid?: boolean;
-        returnOptions: Array<'MIN' | 'MAX' | 'COUNT' | 'ALL' | { partial: string }>;
-    }): Promise<ESearchResult | number[] | false>;
+    search(
+        query: SearchObject,
+        options: {
+            uid?: boolean;
+            returnOptions: Array<'MIN' | 'MAX' | 'COUNT' | 'ALL' | { partial: string }>;
+        }
+    ): Promise<ESearchResult | number[] | false>;
 
     /** Fetch messages from the currently opened mailbox */
     fetch(range: SequenceString | number[] | SearchObject, query: FetchQueryObject, options?: FetchOptions): AsyncIterableIterator<FetchMessageObject>;
@@ -794,14 +804,22 @@ export class ImapFlow extends EventEmitter {
     fetchOne(seq: SequenceString, query: FetchQueryObject, options?: FetchOptions): Promise<FetchMessageObject | false>;
 
     /** Download either full rfc822 formatted message or a specific bodystructure part as a Stream */
-    download(range: SequenceString, part?: string, options?: {
-        uid?: boolean;
-        maxBytes?: number;
-        chunkSize?: number;
-    }): Promise<DownloadObject>;
+    download(
+        range: SequenceString,
+        part?: string,
+        options?: {
+            uid?: boolean;
+            maxBytes?: number;
+            chunkSize?: number;
+        }
+    ): Promise<DownloadObject>;
 
     /** Fetch multiple attachments as Buffer values */
-    downloadMany(range: SequenceString, parts: string[], options?: { uid?: boolean }): Promise<{
+    downloadMany(
+        range: SequenceString,
+        parts: string[],
+        options?: { uid?: boolean }
+    ): Promise<{
         [part: string]: {
             meta: {
                 contentType?: string;
@@ -811,7 +829,7 @@ export class ImapFlow extends EventEmitter {
                 encoding?: string;
             };
             content: Buffer | null;
-        }
+        };
     }>;
 
     /** Opens a mailbox if not already open and returns a lock */
@@ -849,4 +867,4 @@ export class ImapFlow extends EventEmitter {
 
     /** Response event */
     on(event: 'response', listener: (response: ResponseEvent) => void): this;
-}
+}

package/lib/search-compiler.js

@@ -261,6 +261,54 @@ module.exports.searchCompiler = (connection, query) => {
                     }
                     break;
 
+                // Gmail label search. Compiles { has, not } into an X-GM-RAW "label:"/"-label:" query
+                // since Gmail labels are not a native IMAP SEARCH key. Gmail-only (X-GM-EXT-1).
+                case 'LABELS': {
+                    let labelQuery = params[term];
+                    if (!labelQuery || typeof labelQuery !== 'object') {
+                        break;
+                    }
+
+                    // Collapse whitespace/quotes and quote multi-word names so they survive as a single token
+                    let formatLabel = name => {
+                        name = (name || '')
+                            .toString()
+                            .replace(/[\s"]+/g, ' ')
+                            .trim();
+                        return name.indexOf(' ') >= 0 ? `"${name}"` : name;
+                    };
+
+                    let rawParts = [];
+                    for (let name of [].concat(labelQuery.has || [])) {
+                        if (name) {
+                            rawParts.push(`label:${formatLabel(name)}`);
+                        }
+                    }
+                    for (let name of [].concat(labelQuery.not || [])) {
+                        if (name) {
+                            rawParts.push(`-label:${formatLabel(name)}`);
+                        }
+                    }
+
+                    // Empty filter is a no-op on any server (do not require the extension)
+                    if (!rawParts.length) {
+                        break;
+                    }
+
+                    if (!connection.capabilities.has('X-GM-EXT-1')) {
+                        let error = new Error('Server does not support X-GM-EXT-1 extension required for label search');
+                        error.code = 'MissingServerExtension';
+                        throw error;
+                    }
+
+                    let rawQuery = rawParts.join(' ');
+                    if (isUnicodeString(rawQuery)) {
+                        hasUnicode = true;
+                    }
+                    setOpt(attributes, 'X-GM-RAW', rawQuery);
+                    break;
+                }
+
                 // Date searches with WITHIN extension support
                 case 'BEFORE':
                 case 'SINCE':

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.3.7",
+    "version": "1.4.0",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",

package/test/search-compiler-test.js

@@ -443,6 +443,86 @@ module.exports['Search Compiler: GMRAW throws without capability'] = test => {
     test.done();
 };
 
+// ============================================
+// Gmail label search tests
+// ============================================
+
+module.exports['Search Compiler: LABELS has compiles to label: via X-GM-RAW'] = test => {
+    let connection = createMockConnection({
+        capabilities: [['X-GM-EXT-1', true]]
+    });
+    let compiled = searchCompiler(connection, { labels: { has: ['Horizon'] } });
+
+    test.ok(hasAttr(compiled, 'X-GM-RAW'));
+    test.ok(hasAttr(compiled, 'label:Horizon'));
+    test.done();
+};
+
+module.exports['Search Compiler: LABELS not compiles to -label: via X-GM-RAW'] = test => {
+    let connection = createMockConnection({
+        capabilities: [['X-GM-EXT-1', true]]
+    });
+    let compiled = searchCompiler(connection, { labels: { not: ['Horizon'] } });
+
+    test.ok(hasAttr(compiled, 'X-GM-RAW'));
+    test.ok(hasAttr(compiled, '-label:Horizon'));
+    test.done();
+};
+
+module.exports['Search Compiler: LABELS has and not combined'] = test => {
+    let connection = createMockConnection({
+        capabilities: [['X-GM-EXT-1', true]]
+    });
+    let compiled = searchCompiler(connection, { labels: { has: ['Imported'], not: ['Horizon'] } });
+
+    test.ok(hasAttr(compiled, 'label:Imported -label:Horizon'));
+    test.done();
+};
+
+module.exports['Search Compiler: LABELS quotes multi-word names'] = test => {
+    let connection = createMockConnection({
+        capabilities: [['X-GM-EXT-1', true]]
+    });
+    let compiled = searchCompiler(connection, { labels: { has: ['Some Label'] } });
+
+    test.ok(hasAttr(compiled, 'label:"Some Label"'));
+    test.done();
+};
+
+module.exports['Search Compiler: LABELS coexists with gmraw'] = test => {
+    let connection = createMockConnection({
+        capabilities: [['X-GM-EXT-1', true]]
+    });
+    let compiled = searchCompiler(connection, { gmraw: 'has:attachment', labels: { not: ['Horizon'] } });
+
+    test.ok(hasAttr(compiled, 'has:attachment'));
+    test.ok(hasAttr(compiled, '-label:Horizon'));
+    test.done();
+};
+
+module.exports['Search Compiler: LABELS throws without capability'] = test => {
+    let connection = createMockConnection();
+
+    try {
+        searchCompiler(connection, { labels: { not: ['Horizon'] } });
+        test.ok(false, 'Should have thrown');
+    } catch (err) {
+        test.equal(err.code, 'MissingServerExtension');
+        test.ok(err.message.includes('X-GM-EXT-1'));
+    }
+
+    test.done();
+};
+
+module.exports['Search Compiler: empty LABELS is a no-op without capability'] = test => {
+    let connection = createMockConnection();
+    let compiled = searchCompiler(connection, { labels: {} });
+
+    test.ok(!hasAttr(compiled, 'X-GM-RAW'));
+    test.equal(compiled.length, 0);
+    test.done();
+};
+
 // ============================================
 // Date search tests
 // ============================================