imapflow 1.4.0 → 1.4.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -57,7 +57,7 @@ jobs:
|
|
|
57
57
|
# 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
|
|
58
58
|
steps:
|
|
59
59
|
- name: Checkout repository
|
|
60
|
-
uses: actions/checkout@
|
|
60
|
+
uses: actions/checkout@v6
|
|
61
61
|
|
|
62
62
|
# Add any setup steps before running the `github/codeql-action/init` action.
|
|
63
63
|
# This includes steps like installing compilers or runtimes (`actions/setup-node`
|
|
@@ -12,7 +12,7 @@ jobs:
|
|
|
12
12
|
stale:
|
|
13
13
|
runs-on: ubuntu-latest
|
|
14
14
|
steps:
|
|
15
|
-
- uses: actions/stale@
|
|
15
|
+
- uses: actions/stale@v10
|
|
16
16
|
with:
|
|
17
17
|
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.'
|
|
18
18
|
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.'
|
|
@@ -7,18 +7,25 @@ on:
|
|
|
7
7
|
permissions:
|
|
8
8
|
contents: read
|
|
9
9
|
|
|
10
|
+
concurrency:
|
|
11
|
+
group: ${{ github.workflow }}-${{ github.ref }}
|
|
12
|
+
cancel-in-progress: true
|
|
13
|
+
|
|
10
14
|
jobs:
|
|
11
15
|
test:
|
|
16
|
+
name: Test (Node ${{ matrix.node }})
|
|
17
|
+
timeout-minutes: 10
|
|
12
18
|
strategy:
|
|
13
19
|
matrix:
|
|
14
|
-
node: [
|
|
20
|
+
node: [22.x, 24.x]
|
|
15
21
|
os: [ubuntu-latest]
|
|
16
22
|
runs-on: ${{ matrix.os }}
|
|
17
23
|
steps:
|
|
18
|
-
- uses: actions/checkout@
|
|
24
|
+
- uses: actions/checkout@v6
|
|
19
25
|
- name: Use Node.js ${{ matrix.node }}
|
|
20
|
-
uses: actions/setup-node@
|
|
26
|
+
uses: actions/setup-node@v6
|
|
21
27
|
with:
|
|
22
28
|
node-version: ${{ matrix.node }}
|
|
29
|
+
cache: npm
|
|
23
30
|
- run: npm install
|
|
24
31
|
- run: npm test
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [1.4.2](https://github.com/postalsys/imapflow/compare/v1.4.1...v1.4.2) (2026-06-19)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Bug Fixes
|
|
7
|
+
|
|
8
|
+
* bump nodemailer to 9.0.1 ([9c46aa9](https://github.com/postalsys/imapflow/commit/9c46aa9a6156184ee298d003331b8af607f9a8ff))
|
|
9
|
+
|
|
10
|
+
## [1.4.1](https://github.com/postalsys/imapflow/compare/v1.4.0...v1.4.1) (2026-06-15)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
### Bug Fixes
|
|
14
|
+
|
|
15
|
+
* ship refreshed dependencies (nodemailer 9, updated toolchain) ([e1d36e6](https://github.com/postalsys/imapflow/commit/e1d36e68c7a5dd4dd3bc9a7816dc96a01f063af3))
|
|
16
|
+
|
|
3
17
|
## [1.4.0](https://github.com/postalsys/imapflow/compare/v1.3.7...v1.4.0) (2026-06-09)
|
|
4
18
|
|
|
5
19
|
|
package/CLAUDE.md
CHANGED
|
@@ -1,4 +1,96 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Claude Development Guidelines
|
|
2
|
+
|
|
3
|
+
## Project Overview
|
|
4
|
+
|
|
5
|
+
ImapFlow is a modern, promise-based IMAP client library for Node.js. It opens
|
|
6
|
+
TLS/cleartext connections to IMAP servers, authenticates, and parses untrusted
|
|
7
|
+
protocol responses from those servers into a friendly API. It is published to
|
|
8
|
+
npm as `imapflow` and ships TypeScript type definitions.
|
|
9
|
+
|
|
10
|
+
## Project Structure
|
|
11
|
+
|
|
12
|
+
- `lib/imap-flow.js` - Main `ImapFlow` client class (connection lifecycle, command dispatch, public API)
|
|
13
|
+
- `lib/imap-flow.d.ts` - TypeScript type definitions (published as `types`)
|
|
14
|
+
- `lib/imap-commands.js` - Registry wiring individual command implementations
|
|
15
|
+
- `lib/commands/` - Per-command implementations (login, fetch, search, append, etc.)
|
|
16
|
+
- `lib/handler/` - IMAP response stream parser and command compiler (tokenizer, literals, line handling)
|
|
17
|
+
- `lib/search-compiler.js` - Translates the search query object into IMAP SEARCH terms
|
|
18
|
+
- `lib/charsets.js`, `lib/jp-decoder.js` - Charset/encoding helpers
|
|
19
|
+
- `lib/special-use.js` - SPECIAL-USE mailbox detection
|
|
20
|
+
- `lib/proxy-connection.js` - SOCKS/HTTP proxy connection support
|
|
21
|
+
- `lib/limited-passthrough.js`, `lib/tools.js`, `lib/logger.js` - Internal utilities
|
|
22
|
+
- `test/` - Unit tests (`*-test.js`), run with nodeunit via Grunt
|
|
23
|
+
- `examples/` - Standalone usage examples (not production code)
|
|
24
|
+
|
|
25
|
+
## Technology Stack
|
|
26
|
+
|
|
27
|
+
- **Runtime**: Node.js (CI tests on 22.x and 24.x)
|
|
28
|
+
- **Module system**: CommonJS (see Packaging Constraints below)
|
|
29
|
+
- **Testing**: Grunt + grunt-contrib-nodeunit, ESLint via grunt-eslint
|
|
30
|
+
- **Lint/format**: ESLint (`eslint.config.js`, flat config) + Prettier
|
|
31
|
+
- **Key dependencies**: `@zone-eu/mailsplit`, `libmime`, `libqp`, `libbase64`, `iconv-lite`, `encoding-japanese`, `nodemailer`, `pino`, `socks`
|
|
32
|
+
|
|
33
|
+
## Development Commands
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
npm test # Run full suite via Grunt (ESLint + nodeunit tests)
|
|
37
|
+
npm run coverage # Run tests under c8 coverage (text + html reports)
|
|
38
|
+
npm run lint # Lint with ESLint
|
|
39
|
+
npm run format # Format with Prettier (js, json, md, yml, yaml)
|
|
40
|
+
npm run update # Refresh deps: remove node_modules + lockfile, ncu -u, npm install
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Testing
|
|
44
|
+
|
|
45
|
+
- 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.
|
|
46
|
+
- `npm test` runs `grunt`, which runs ESLint first, then the nodeunit suite. Keep the suite green and lint-clean before committing.
|
|
47
|
+
- 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.
|
|
48
|
+
|
|
49
|
+
## Packaging Constraints (IMPORTANT)
|
|
50
|
+
|
|
51
|
+
EmailEngine (see "Relationship to EmailEngine" below) bundles ImapFlow and all
|
|
52
|
+
of its transitive dependencies into a single self-contained executable using
|
|
53
|
+
[`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg). `pkg` works by snapshotting a
|
|
54
|
+
CommonJS `require()` graph, so it **cannot bundle pure-ESM packages**.
|
|
55
|
+
|
|
56
|
+
Therefore ImapFlow itself and every dependency it pulls in must stay
|
|
57
|
+
CommonJS-compatible:
|
|
58
|
+
|
|
59
|
+
- ImapFlow source stays CommonJS (`require`/`module.exports`). Do not convert the library to ESM.
|
|
60
|
+
- 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.
|
|
61
|
+
- 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.
|
|
62
|
+
- Keep dynamic `require()` paths static enough for `pkg` to detect; avoid building module paths at runtime in ways the bundler can't trace.
|
|
63
|
+
|
|
64
|
+
## Code Style Rules
|
|
65
|
+
|
|
66
|
+
- Never use emojis in code or documentation, only printable ASCII characters.
|
|
67
|
+
- Use a single hyphen-minus (`-`) as a dash in user-facing strings and docs. Never use double hyphens (`--`), em dashes, or en dashes.
|
|
68
|
+
- When composing git commit messages, do not include Claude as a co-contributor.
|
|
69
|
+
- Use Conventional Commit prefixes (`feat:`, `fix:`, `chore:`, `docs:`, `test:`, `ci:`, ...). Versioning and the changelog are driven by these prefixes via release-please.
|
|
70
|
+
- 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.
|
|
71
|
+
- After making code changes:
|
|
72
|
+
1. Run `npm run format` and `npm run lint`
|
|
73
|
+
2. Run `npm test` and keep it green
|
|
74
|
+
3. For non-trivial changes, run `/simplify` to review changed code and `/security-review` to check for security issues before committing
|
|
75
|
+
- 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.
|
|
76
|
+
|
|
77
|
+
## Relationship to EmailEngine
|
|
78
|
+
|
|
79
|
+
ImapFlow is developed and maintained primarily as the IMAP client used by
|
|
80
|
+
[EmailEngine](https://github.com/postalsys/emailengine). The local development
|
|
81
|
+
copy of EmailEngine lives at `../emailengine` relative to this project root. When
|
|
82
|
+
EmailEngine hits a bug or unhandled promise rejection that originates in
|
|
83
|
+
ImapFlow, the fix belongs here in the ImapFlow source rather than as a
|
|
84
|
+
workaround in EmailEngine. Because EmailEngine packages this library with
|
|
85
|
+
`@yao-pkg/pkg`, never make a change here that breaks CommonJS packaging (see
|
|
86
|
+
Packaging Constraints).
|
|
87
|
+
|
|
88
|
+
## Security
|
|
89
|
+
|
|
90
|
+
Security policy and private reporting channels are documented in
|
|
91
|
+
[`SECURITY.md`](SECURITY.md) / [`SECURITY.txt`](SECURITY.txt). Code scanning runs
|
|
92
|
+
through the "CodeQL Advanced" GitHub Actions workflow
|
|
93
|
+
(`.github/workflows/codeql.yml`, config in `.github/codeql/codeql-config.yml`).
|
|
2
94
|
|
|
3
95
|
## Release Process
|
|
4
96
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "imapflow",
|
|
3
|
-
"version": "1.4.
|
|
3
|
+
"version": "1.4.2",
|
|
4
4
|
"description": "IMAP Client for Node",
|
|
5
5
|
"main": "lib/imap-flow.js",
|
|
6
6
|
"types": "lib/imap-flow.d.ts",
|
|
@@ -28,16 +28,16 @@
|
|
|
28
28
|
"homepage": "https://imapflow.com/",
|
|
29
29
|
"devDependencies": {
|
|
30
30
|
"@eslint/js": "10.0.1",
|
|
31
|
-
"@types/node": "
|
|
31
|
+
"@types/node": "26.0.0",
|
|
32
32
|
"c8": "11.0.0",
|
|
33
|
-
"eslint": "10.
|
|
33
|
+
"eslint": "10.5.0",
|
|
34
34
|
"eslint-config-nodemailer": "1.2.0",
|
|
35
35
|
"eslint-config-prettier": "10.1.8",
|
|
36
36
|
"grunt": "1.6.2",
|
|
37
37
|
"grunt-cli": "1.5.0",
|
|
38
38
|
"grunt-contrib-nodeunit": "5.0.0",
|
|
39
39
|
"grunt-eslint": "26.0.0",
|
|
40
|
-
"prettier": "3.8.
|
|
40
|
+
"prettier": "3.8.4",
|
|
41
41
|
"proxyquire": "^2.1.3",
|
|
42
42
|
"typescript": "6.0.3"
|
|
43
43
|
},
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
"libbase64": "1.3.0",
|
|
49
49
|
"libmime": "5.3.8",
|
|
50
50
|
"libqp": "2.1.1",
|
|
51
|
-
"nodemailer": "
|
|
51
|
+
"nodemailer": "9.0.1",
|
|
52
52
|
"pino": "10.3.1",
|
|
53
53
|
"socks": "2.8.9"
|
|
54
54
|
}
|