imapflow 1.3.7 → 1.4.1

package/.github/workflows/codeql.yml

@@ -57,7 +57,7 @@ jobs:
         # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
 
     # Add any setup steps before running the `github/codeql-action/init` action.
     # This includes steps like installing compilers or runtimes (`actions/setup-node`

package/.github/workflows/release.yaml

@@ -27,8 +27,8 @@ jobs:
             contents: read
             id-token: write
         steps:
-            - uses: actions/checkout@v4
-            - uses: actions/setup-node@v4
+            - uses: actions/checkout@v6
+            - uses: actions/setup-node@v6
               with:
                   node-version: 24
                   registry-url: 'https://registry.npmjs.org'

package/.github/workflows/stale.yml

@@ -12,7 +12,7 @@ jobs:
     stale:
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/stale@v8
+            - uses: actions/stale@v10
               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.'

package/.github/workflows/test.yml

@@ -7,18 +7,25 @@ on:
 permissions:
     contents: read
 
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
 jobs:
     test:
+        name: Test (Node ${{ matrix.node }})
+        timeout-minutes: 10
         strategy:
             matrix:
-                node: [20.x, 22.x, 24.x]
+                node: [22.x, 24.x]
                 os: [ubuntu-latest]
         runs-on: ${{ matrix.os }}
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v6
             - name: Use Node.js ${{ matrix.node }}
-              uses: actions/setup-node@v4
+              uses: actions/setup-node@v6
               with:
                   node-version: ${{ matrix.node }}
+                  cache: npm
             - run: npm install
             - run: npm test

package/.release-please-manifest.json

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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.4.1](https://github.com/postalsys/imapflow/compare/v1.4.0...v1.4.1) (2026-06-15)
+
+
+### Bug Fixes
+
+* ship refreshed dependencies (nodemailer 9, updated toolchain) ([e1d36e6](https://github.com/postalsys/imapflow/commit/e1d36e68c7a5dd4dd3bc9a7816dc96a01f063af3))
+
+## [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/CLAUDE.md

@@ -1,4 +1,96 @@
-# ImapFlow
+# Claude Development Guidelines
+
+## Project Overview
+
+ImapFlow is a modern, promise-based IMAP client library for Node.js. It opens
+TLS/cleartext connections to IMAP servers, authenticates, and parses untrusted
+protocol responses from those servers into a friendly API. It is published to
+npm as `imapflow` and ships TypeScript type definitions.
+
+## Project Structure
+
+- `lib/imap-flow.js` - Main `ImapFlow` client class (connection lifecycle, command dispatch, public API)
+- `lib/imap-flow.d.ts` - TypeScript type definitions (published as `types`)
+- `lib/imap-commands.js` - Registry wiring individual command implementations
+- `lib/commands/` - Per-command implementations (login, fetch, search, append, etc.)
+- `lib/handler/` - IMAP response stream parser and command compiler (tokenizer, literals, line handling)
+- `lib/search-compiler.js` - Translates the search query object into IMAP SEARCH terms
+- `lib/charsets.js`, `lib/jp-decoder.js` - Charset/encoding helpers
+- `lib/special-use.js` - SPECIAL-USE mailbox detection
+- `lib/proxy-connection.js` - SOCKS/HTTP proxy connection support
+- `lib/limited-passthrough.js`, `lib/tools.js`, `lib/logger.js` - Internal utilities
+- `test/` - Unit tests (`*-test.js`), run with nodeunit via Grunt
+- `examples/` - Standalone usage examples (not production code)
+
+## Technology Stack
+
+- **Runtime**: Node.js (CI tests on 22.x and 24.x)
+- **Module system**: CommonJS (see Packaging Constraints below)
+- **Testing**: Grunt + grunt-contrib-nodeunit, ESLint via grunt-eslint
+- **Lint/format**: ESLint (`eslint.config.js`, flat config) + Prettier
+- **Key dependencies**: `@zone-eu/mailsplit`, `libmime`, `libqp`, `libbase64`, `iconv-lite`, `encoding-japanese`, `nodemailer`, `pino`, `socks`
+
+## Development Commands
+
+```
+npm test           # Run full suite via Grunt (ESLint + nodeunit tests)
+npm run coverage   # Run tests under c8 coverage (text + html reports)
+npm run lint       # Lint with ESLint
+npm run format     # Format with Prettier (js, json, md, yml, yaml)
+npm run update     # Refresh deps: remove node_modules + lockfile, ncu -u, npm install
+```
+
+## Testing
+
+- Tests live in `test/` and are named `*-test.js`; the Grunt nodeunit glob only matches that pattern, so helpers/fixtures are never run as tests.
+- `npm test` runs `grunt`, which runs ESLint first, then the nodeunit suite. Keep the suite green and lint-clean before committing.
+- New tests go in `test/` as `*-test.js`. The parser, command compiler, and search compiler are the most security-sensitive areas - add hostile/malformed-input cases there.
+
+## Packaging Constraints (IMPORTANT)
+
+EmailEngine (see "Relationship to EmailEngine" below) bundles ImapFlow and all
+of its transitive dependencies into a single self-contained executable using
+[`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg). `pkg` works by snapshotting a
+CommonJS `require()` graph, so it **cannot bundle pure-ESM packages**.
+
+Therefore ImapFlow itself and every dependency it pulls in must stay
+CommonJS-compatible:
+
+- ImapFlow source stays CommonJS (`require`/`module.exports`). Do not convert the library to ESM.
+- Do not add a dependency that is pure ESM (`"type": "module"` with only an `import`/ESM entry and no CommonJS export). It must be `require()`-able.
+- When `npm run update` or a new dependency would pull in a pure-ESM package (a common outcome of major-version bumps), pin to the last CommonJS-compatible version instead, or find a CommonJS alternative. Verify with a quick `require()` of the package after updating.
+- Keep dynamic `require()` paths static enough for `pkg` to detect; avoid building module paths at runtime in ways the bundler can't trace.
+
+## Code Style Rules
+
+- Never use emojis in code or documentation, only printable ASCII characters.
+- Use a single hyphen-minus (`-`) as a dash in user-facing strings and docs. Never use double hyphens (`--`), em dashes, or en dashes.
+- When composing git commit messages, do not include Claude as a co-contributor.
+- Use Conventional Commit prefixes (`feat:`, `fix:`, `chore:`, `docs:`, `test:`, `ci:`, ...). Versioning and the changelog are driven by these prefixes via release-please.
+- For commits that do not change published runtime behavior (docs, comments, CI/workflow tweaks, formatting), append `[skip ci]` to the commit message to avoid triggering the GitHub Actions workflows. Exception: do not add `[skip ci]` to commits using a `fix:` or `feat:` prefix - those must run so the release action is triggered.
+- After making code changes:
+    1. Run `npm run format` and `npm run lint`
+    2. Run `npm test` and keep it green
+    3. For non-trivial changes, run `/simplify` to review changed code and `/security-review` to check for security issues before committing
+- After pushing, check the GitHub Actions runs for the push (e.g. `gh run list --branch master`) and report their status, including the CodeQL "CodeQL Advanced" code-scanning run. If a run fails for a strange or unrelated reason (for example a checkout step reporting "account suspended", HTTP 403, or other auth/infrastructure errors that have nothing to do with the change), check <https://www.githubstatus.com/> for an active GitHub incident before assuming the failure is caused by the change.
+
+## Relationship to EmailEngine
+
+ImapFlow is developed and maintained primarily as the IMAP client used by
+[EmailEngine](https://github.com/postalsys/emailengine). The local development
+copy of EmailEngine lives at `../emailengine` relative to this project root. When
+EmailEngine hits a bug or unhandled promise rejection that originates in
+ImapFlow, the fix belongs here in the ImapFlow source rather than as a
+workaround in EmailEngine. Because EmailEngine packages this library with
+`@yao-pkg/pkg`, never make a change here that breaks CommonJS packaging (see
+Packaging Constraints).
+
+## Security
+
+Security policy and private reporting channels are documented in
+[`SECURITY.md`](SECURITY.md) / [`SECURITY.txt`](SECURITY.txt). Code scanning runs
+through the "CodeQL Advanced" GitHub Actions workflow
+(`.github/workflows/codeql.yml`, config in `.github/codeql/codeql-config.yml`).
 
 ## Release Process
 

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.1",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",
@@ -28,16 +28,16 @@
     "homepage": "https://imapflow.com/",
     "devDependencies": {
         "@eslint/js": "10.0.1",
-        "@types/node": "25.9.1",
+        "@types/node": "25.9.3",
         "c8": "11.0.0",
-        "eslint": "10.4.1",
+        "eslint": "10.5.0",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "10.1.8",
         "grunt": "1.6.2",
         "grunt-cli": "1.5.0",
         "grunt-contrib-nodeunit": "5.0.0",
         "grunt-eslint": "26.0.0",
-        "prettier": "3.8.3",
+        "prettier": "3.8.4",
         "proxyquire": "^2.1.3",
         "typescript": "6.0.3"
     },
@@ -48,7 +48,7 @@
         "libbase64": "1.3.0",
         "libmime": "5.3.8",
         "libqp": "2.1.1",
-        "nodemailer": "8.0.10",
+        "nodemailer": "9.0.0",
         "pino": "10.3.1",
         "socks": "2.8.9"
     }

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
 // ============================================