@kbzowski/mcp-inbox 0.1.0

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.
Files changed (47) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +396 -0
  3. package/dist/cache/db.d.ts +34 -0
  4. package/dist/cache/idle.d.ts +32 -0
  5. package/dist/cache/queries.d.ts +66 -0
  6. package/dist/cache/schema.d.ts +456 -0
  7. package/dist/cache/sync.d.ts +38 -0
  8. package/dist/config/env.d.ts +103 -0
  9. package/dist/errors/mapper.d.ts +10 -0
  10. package/dist/errors/types.d.ts +25 -0
  11. package/dist/formatters/markdown.d.ts +13 -0
  12. package/dist/imap/client.d.ts +37 -0
  13. package/dist/imap/folders.d.ts +19 -0
  14. package/dist/imap/mime-builder.d.ts +32 -0
  15. package/dist/imap/search.d.ts +28 -0
  16. package/dist/index.d.ts +1 -0
  17. package/dist/index.js +2572 -0
  18. package/dist/index.js.map +7 -0
  19. package/dist/migrations/0000_mean_the_santerians.sql +49 -0
  20. package/dist/migrations/0001_wooden_doomsday.sql +2 -0
  21. package/dist/migrations/meta/0000_snapshot.json +337 -0
  22. package/dist/migrations/meta/0001_snapshot.json +224 -0
  23. package/dist/migrations/meta/_journal.json +20 -0
  24. package/dist/server.d.ts +8 -0
  25. package/dist/smtp/client.d.ts +28 -0
  26. package/dist/tools/attachments/get-attachment.d.ts +43 -0
  27. package/dist/tools/define-tool.d.ts +61 -0
  28. package/dist/tools/drafts/create-draft.d.ts +11 -0
  29. package/dist/tools/drafts/get-draft.d.ts +10 -0
  30. package/dist/tools/drafts/list-drafts.d.ts +11 -0
  31. package/dist/tools/drafts/update-draft.d.ts +12 -0
  32. package/dist/tools/emails/delete-email.d.ts +6 -0
  33. package/dist/tools/emails/get-email.d.ts +10 -0
  34. package/dist/tools/emails/list-emails.d.ts +14 -0
  35. package/dist/tools/emails/mark-read.d.ts +9 -0
  36. package/dist/tools/emails/move-to-folder.d.ts +6 -0
  37. package/dist/tools/emails/search-emails.d.ts +17 -0
  38. package/dist/tools/emails/shared.d.ts +74 -0
  39. package/dist/tools/folders/list-folders.d.ts +7 -0
  40. package/dist/tools/registry.d.ts +21 -0
  41. package/dist/tools/send/forward.d.ts +11 -0
  42. package/dist/tools/send/reply.d.ts +12 -0
  43. package/dist/tools/send/send-draft.d.ts +5 -0
  44. package/dist/tools/send/send-email.d.ts +10 -0
  45. package/dist/tools/send/shared.d.ts +40 -0
  46. package/dist/utils/logger.d.ts +40 -0
  47. package/package.json +90 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Krzysztof Bzowski
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,396 @@
1
+ # mcp-inbox
2
+
3
+ > MCP server that gives any MCP-capable agent read/write access to your IMAP inbox, with a local SQLite cache for fast responses and IMAP IDLE for real-time updates.
4
+
5
+ Works with any IMAP/SMTP provider: Gmail, Outlook, Fastmail, iCloud, Proton Mail (via Bridge), Dovecot, hosted Exchange, self-hosted mail servers. Tools for listing and searching mail, composing and sending, managing drafts, inspecting attachment metadata. Cache stays in sync with the server via CONDSTORE + IDLE so most reads serve from local SQLite without a network round-trip.
6
+
7
+ **On attachments:** `imap_get_email` surfaces attachment metadata (filename, content type, size) by default - enough for the agent to describe what's attached without any download. When the agent genuinely needs to read content inside an attachment (search a PDF, extract a table from a CSV), `imap_get_attachment` fetches the bytes inline as base64 for one response. Nothing is cached on disk; re-requesting the same attachment refetches from the server.
8
+
9
+ **Status:** 0.1.0, early. See `CLAUDE.md` for architecture notes.
10
+
11
+ ---
12
+
13
+ ## Requirements
14
+
15
+ - **Node.js 24 LTS** or newer (`node --version` should print `v24.x` or higher).
16
+ - An IMAP/SMTP account. Gmail and Outlook users need an **app password**, not the account password - see [Provider notes](#provider-notes).
17
+
18
+ ---
19
+
20
+ ## Configure
21
+
22
+ mcp-inbox reads credentials from environment variables. At minimum you need three:
23
+
24
+ ```
25
+ IMAP_USER=you@example.com
26
+ IMAP_PASSWORD=your-app-password
27
+ IMAP_HOST=imap.example.com
28
+ ```
29
+
30
+ The full list of variables (ports, TLS flags, cache tuning, IDLE folders) lives in [.env.example](.env.example).
31
+
32
+ How those env vars reach the server process depends on which MCP client you use. Every client below lets you set env per-server.
33
+
34
+ ---
35
+
36
+ ## Connect it to your client
37
+
38
+ Pick your client and follow the snippet. Each example sets `IMAP_USER`, `IMAP_PASSWORD`, and `IMAP_HOST`; add any optional variables from `.env.example` the same way.
39
+
40
+ ### Claude Code (CLI)
41
+
42
+ Works on macOS, Linux, and Windows.
43
+
44
+ ```bash
45
+ claude mcp add mcp-inbox \
46
+ --env IMAP_USER=you@example.com \
47
+ --env IMAP_PASSWORD=your-app-password \
48
+ --env IMAP_HOST=imap.gmail.com \
49
+ -- npx -y @kbzowski/mcp-inbox
50
+ ```
51
+
52
+ Add `-s user` (user scope) to make the server available in every project instead of just the current directory. List and verify with `claude mcp list`. Remove with `claude mcp remove mcp-inbox`.
53
+
54
+ **Windows note:** works directly; Claude Code wraps `npx` correctly on Windows since mid-2025. If you hit `spawn npx ENOENT`, upgrade Claude Code first.
55
+
56
+ ### Claude Desktop
57
+
58
+ Config file location:
59
+ - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
60
+ - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
61
+ - **Linux** (unofficial): `~/.config/Claude/claude_desktop_config.json`
62
+
63
+ Edit (create the file if it doesn't exist) and merge this into the top-level object:
64
+
65
+ ```json
66
+ {
67
+ "mcpServers": {
68
+ "mcp-inbox": {
69
+ "command": "npx",
70
+ "args": ["-y", "@kbzowski/mcp-inbox"],
71
+ "env": {
72
+ "IMAP_USER": "you@example.com",
73
+ "IMAP_PASSWORD": "your-app-password",
74
+ "IMAP_HOST": "imap.gmail.com"
75
+ }
76
+ }
77
+ }
78
+ }
79
+ ```
80
+
81
+ Restart Claude Desktop after saving. The server appears in the "Search and tools" menu once the handshake completes.
82
+
83
+ **Windows quirk:** if Claude Desktop fails to spawn `npx` (older Electron versions do this), replace the `command`/`args` pair with:
84
+
85
+ ```json
86
+ "command": "cmd",
87
+ "args": ["/c", "npx", "-y", "@kbzowski/mcp-inbox"],
88
+ ```
89
+
90
+ ### Codex CLI (OpenAI)
91
+
92
+ Config lives at `~/.codex/config.toml`:
93
+
94
+ ```toml
95
+ [mcp_servers.mcp-inbox]
96
+ command = "npx"
97
+ args = ["-y", "@kbzowski/mcp-inbox"]
98
+
99
+ [mcp_servers.mcp-inbox.env]
100
+ IMAP_USER = "you@example.com"
101
+ IMAP_PASSWORD = "your-app-password"
102
+ IMAP_HOST = "imap.gmail.com"
103
+ ```
104
+
105
+ Verify with `codex mcp list`. If you're on Windows and Codex can't find `npx`, wrap it: `command = "cmd"`, `args = ["/c", "npx", "-y", "@kbzowski/mcp-inbox"]`.
106
+
107
+ ### Cursor
108
+
109
+ **Option A - Settings UI:** Settings → MCP → Add new MCP server. Fill in:
110
+ - Name: `mcp-inbox`
111
+ - Type: `command`
112
+ - Command: `npx -y @kbzowski/mcp-inbox`
113
+ - Env: add `IMAP_USER`, `IMAP_PASSWORD`, `IMAP_HOST` one per line
114
+
115
+ **Option B - edit `~/.cursor/mcp.json`:**
116
+
117
+ ```json
118
+ {
119
+ "mcpServers": {
120
+ "mcp-inbox": {
121
+ "command": "npx",
122
+ "args": ["-y", "@kbzowski/mcp-inbox"],
123
+ "env": {
124
+ "IMAP_USER": "you@example.com",
125
+ "IMAP_PASSWORD": "your-app-password",
126
+ "IMAP_HOST": "imap.gmail.com"
127
+ }
128
+ }
129
+ }
130
+ }
131
+ ```
132
+
133
+ A workspace-scoped variant goes at `.cursor/mcp.json` in the project root.
134
+
135
+ ### VS Code (native MCP)
136
+
137
+ VS Code added first-party MCP support in 2025. Enable it at the workspace level by creating `.vscode/mcp.json`:
138
+
139
+ ```json
140
+ {
141
+ "servers": {
142
+ "mcp-inbox": {
143
+ "type": "stdio",
144
+ "command": "npx",
145
+ "args": ["-y", "@kbzowski/mcp-inbox"],
146
+ "env": {
147
+ "IMAP_USER": "you@example.com",
148
+ "IMAP_PASSWORD": "your-app-password",
149
+ "IMAP_HOST": "imap.gmail.com"
150
+ }
151
+ }
152
+ }
153
+ }
154
+ ```
155
+
156
+ User-level config: the `mcp` section under your settings JSON (`Cmd/Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)").
157
+
158
+ ### Cline (VS Code extension)
159
+
160
+ Cline reads its MCP config from `cline_mcp_settings.json`. Open it from the Cline sidebar → MCP Servers → Configure MCP Servers. Add:
161
+
162
+ ```json
163
+ {
164
+ "mcpServers": {
165
+ "mcp-inbox": {
166
+ "command": "npx",
167
+ "args": ["-y", "@kbzowski/mcp-inbox"],
168
+ "env": {
169
+ "IMAP_USER": "you@example.com",
170
+ "IMAP_PASSWORD": "your-app-password",
171
+ "IMAP_HOST": "imap.gmail.com"
172
+ },
173
+ "disabled": false,
174
+ "autoApprove": []
175
+ }
176
+ }
177
+ }
178
+ ```
179
+
180
+ ### Continue.dev
181
+
182
+ Edit `~/.continue/config.yaml`:
183
+
184
+ ```yaml
185
+ mcpServers:
186
+ - name: mcp-inbox
187
+ command: npx
188
+ args:
189
+ - "-y"
190
+ - "@kbzowski/mcp-inbox"
191
+ env:
192
+ IMAP_USER: you@example.com
193
+ IMAP_PASSWORD: your-app-password
194
+ IMAP_HOST: imap.gmail.com
195
+ ```
196
+
197
+ ### Zed
198
+
199
+ Zed's editor settings (`Cmd/Ctrl+,`) - add a `context_servers` entry:
200
+
201
+ ```json
202
+ {
203
+ "context_servers": {
204
+ "mcp-inbox": {
205
+ "command": "npx",
206
+ "args": ["-y", "@kbzowski/mcp-inbox"],
207
+ "env": {
208
+ "IMAP_USER": "you@example.com",
209
+ "IMAP_PASSWORD": "your-app-password",
210
+ "IMAP_HOST": "imap.gmail.com"
211
+ }
212
+ }
213
+ }
214
+ }
215
+ ```
216
+
217
+ ### Goose (Block)
218
+
219
+ Edit `~/.config/goose/config.yaml`:
220
+
221
+ ```yaml
222
+ extensions:
223
+ mcp-inbox:
224
+ type: stdio
225
+ cmd: npx
226
+ args: ["-y", "@kbzowski/mcp-inbox"]
227
+ envs:
228
+ IMAP_USER: you@example.com
229
+ IMAP_PASSWORD: your-app-password
230
+ IMAP_HOST: imap.gmail.com
231
+ enabled: true
232
+ ```
233
+
234
+ ### Any other MCP client
235
+
236
+ The pattern every MCP client shares:
237
+
238
+ | Field | Value |
239
+ |---|---|
240
+ | Transport | stdio |
241
+ | Command | `npx` |
242
+ | Args | `["-y", "@kbzowski/mcp-inbox"]` |
243
+ | Env | `IMAP_USER`, `IMAP_PASSWORD`, `IMAP_HOST` (minimum) |
244
+
245
+ If the client expects a bundled executable instead of `npx`, install globally (`npm i -g @kbzowski/mcp-inbox`) and point it at `mcp-inbox` directly.
246
+
247
+ ---
248
+
249
+ ## Provider notes
250
+
251
+ ### Gmail / Google Workspace
252
+
253
+ Use an **[app password](https://myaccount.google.com/apppasswords)**, not your account password. Requires 2-Step Verification turned on first.
254
+
255
+ ```
256
+ IMAP_HOST=imap.gmail.com
257
+ IMAP_PORT=993
258
+ SMTP_HOST=smtp.gmail.com
259
+ SMTP_PORT=465
260
+ SMTP_SECURE=true
261
+ ```
262
+
263
+ ### Outlook / Microsoft 365
264
+
265
+ ```
266
+ IMAP_HOST=outlook.office365.com
267
+ IMAP_PORT=993
268
+ SMTP_HOST=smtp.office365.com
269
+ SMTP_PORT=587
270
+ SMTP_SECURE=false
271
+ ```
272
+
273
+ Outlook rejects the default `SMTP_PORT=465` setting - both `SMTP_PORT=587` and `SMTP_SECURE=false` are required. Personal accounts need an [app password](https://account.microsoft.com/security) if 2FA is on.
274
+
275
+ ### Fastmail
276
+
277
+ Use an [app password](https://app.fastmail.com/settings/security/devicekeys/add) (account-level passwords are rejected).
278
+
279
+ ```
280
+ IMAP_HOST=imap.fastmail.com
281
+ SMTP_HOST=smtp.fastmail.com
282
+ SMTP_PORT=465
283
+ ```
284
+
285
+ ### iCloud
286
+
287
+ Requires an [app-specific password](https://account.apple.com) from your Apple ID security settings.
288
+
289
+ ```
290
+ IMAP_HOST=imap.mail.me.com
291
+ SMTP_HOST=smtp.mail.me.com
292
+ SMTP_PORT=587
293
+ SMTP_SECURE=false
294
+ ```
295
+
296
+ ### Proton Mail
297
+
298
+ Proton Mail requires [Proton Mail Bridge](https://proton.me/mail/bridge) running locally; point mcp-inbox at the Bridge's advertised host/port (usually `127.0.0.1:1143` for IMAP).
299
+
300
+ ---
301
+
302
+ ## Troubleshooting
303
+
304
+ ### "IMAP authentication failed"
305
+
306
+ You're almost certainly using your account password instead of an app password. See the provider-specific links above.
307
+
308
+ ### The client can't find `npx` / `spawn ENOENT`
309
+
310
+ On Windows, some older clients don't resolve `.cmd` shims. Wrap the command:
311
+
312
+ ```json
313
+ "command": "cmd",
314
+ "args": ["/c", "npx", "-y", "@kbzowski/mcp-inbox"]
315
+ ```
316
+
317
+ Or install globally and use the binary directly:
318
+
319
+ ```bash
320
+ npm install -g @kbzowski/mcp-inbox
321
+ # then set command: "mcp-inbox" (no args)
322
+ ```
323
+
324
+ ### Passwords with shell-special characters
325
+
326
+ If your password contains `$`, `` ` ``, `!`, or a backslash, put it in an env file / config JSON rather than passing it on a shell command line. The config files above handle this correctly; `claude mcp add --env IMAP_PASSWORD=...` works if you **single-quote** the value in your shell.
327
+
328
+ ### First-run takes a while
329
+
330
+ The first `npx -y @kbzowski/mcp-inbox` invocation downloads the package. Subsequent runs are cached. If it looks hung on first boot, check your network.
331
+
332
+ ### Verify the connection manually
333
+
334
+ From any shell, set the env vars and run:
335
+
336
+ ```bash
337
+ IMAP_USER=you@example.com IMAP_PASSWORD=... IMAP_HOST=imap.gmail.com npx -y @kbzowski/mcp-inbox
338
+ ```
339
+
340
+ On success you'll see JSON log lines on stderr: `booting mcp-inbox` and `mcp-inbox ready`. The server then idles on stdin (waiting for MCP JSON-RPC). Hit `Ctrl+C` to stop.
341
+
342
+ ---
343
+
344
+ ## Tool catalog
345
+
346
+ All tools are prefixed `imap_` so they don't collide with other email MCPs. Every read tool accepts `response_format: "markdown" | "json"` (default markdown) and `max_staleness_seconds` (default 60 - serves from cache when fresh, syncs otherwise).
347
+
348
+ ### Discovery
349
+
350
+ - **`imap_list_folders`** - list every mailbox with its path, delimiter, and RFC 6154 special-use attribute (`\Drafts`, `\Sent`, `\Trash`, `\Junk`).
351
+ - **`imap_list_emails`** `(folder?, limit?, offset?, unseen_only?, since_date?, before_date?)` - paginated envelope list, newest first. Defaults to `INBOX`, 20 per page.
352
+ - **`imap_search_emails`** `(folder?, subject?, from?, to?, body?, unseen?, since_date?, before_date?)` - IMAP SEARCH on the server, returns matching envelopes from the cache. At least one criterion required.
353
+
354
+ ### Reading
355
+
356
+ - **`imap_get_email`** `(folder, uid)` - full message: headers, plain text, HTML, and attachment metadata (filename, content type, size).
357
+ - **`imap_list_drafts`** `(folder?, limit?, offset?)` - same as list_emails but auto-resolves the Drafts folder via SPECIAL-USE.
358
+ - **`imap_get_draft`** `(uid, folder?)` - full draft content by UID.
359
+ - **`imap_get_attachment`** `(folder, uid, filename? | part_id?, max_inline_mb?)` - download an attachment as base64 bytes, inline in the response. Memory-only, no disk cache. Default cap is 5 MB; raise via `max_inline_mb` (up to 50).
360
+
361
+ ### Flagging / filing
362
+
363
+ - **`imap_mark_read`** `(folder, uid)` - add `\Seen`. Idempotent.
364
+ - **`imap_mark_unread`** `(folder, uid)` - remove `\Seen`. Idempotent.
365
+ - **`imap_move_to_folder`** `(folder, uid, destination)` - IMAP MOVE with COPY+EXPUNGE fallback.
366
+ - **`imap_delete_email`** `(folder, uid, hard_delete?)` - defaults to move-to-Trash. `hard_delete: true` permanently expunges.
367
+
368
+ ### Composing
369
+
370
+ - **`imap_create_draft`** `(to, subject, body?, html?, cc?, bcc?, from?)` - appends a new draft to the Drafts folder with the `\Draft` flag. nodemailer handles the RFC 2822 construction, so non-ASCII subjects, long bodies, and multipart text+HTML all just work.
371
+ - **`imap_update_draft`** `(uid, to, subject, body?, html?, cc?, bcc?, from?)` - replaces an existing draft. Append-then-delete: the new draft is written first, only then is the old UID removed. A failure in the middle never loses the draft.
372
+
373
+ ### Sending
374
+
375
+ - **`imap_send_email`** `(to, subject, body?, html?, cc?, bcc?, from?)` - SMTP send + best-effort append to the Sent folder so the message shows up in the user's mail client.
376
+ - **`imap_send_draft`** `(uid, folder?)` - fetches raw source of the draft, sends it exactly as written (preserves attachments and formatting), then deletes the draft.
377
+ - **`imap_reply`** `(folder, uid, body?, html?, reply_all?, cc?, bcc?, from?)` - preserves threading via `In-Reply-To` / `References`. Subject gets a `Re: ` prefix.
378
+ - **`imap_forward`** `(folder, uid, to, body?, cc?, bcc?, from?)` - quotes the original inline, `Fwd: ` subject prefix.
379
+
380
+ ### Tool annotations
381
+
382
+ Every tool carries MCP annotations so clients can gate destructive actions:
383
+
384
+ | Tool | readOnly | destructive | idempotent |
385
+ |---|:-:|:-:|:-:|
386
+ | list_folders / list_emails / get_email / search_emails / list_drafts / get_draft / get_attachment | ✓ | | ✓ |
387
+ | mark_read / mark_unread | | | ✓ |
388
+ | move_to_folder / delete_email | | ✓ | |
389
+ | create_draft / update_draft | | | |
390
+ | send_email / send_draft / reply / forward | | ✓ | |
391
+
392
+ ---
393
+
394
+ ## License
395
+
396
+ MIT. Copyright (c) 2026 Krzysztof Bzowski. See [LICENSE](LICENSE).
@@ -0,0 +1,34 @@
1
+ import { drizzle } from 'drizzle-orm/better-sqlite3';
2
+ import * as schema from './schema';
3
+ /**
4
+ * Default migrations folder resolved relative to this module.
5
+ *
6
+ * - Dev (tsx / vitest): `src/cache/migrations/`
7
+ * - Built binary (dist/index.js): `dist/migrations/` (build script
8
+ * copies the migrations there so the shipped tarball is self-contained)
9
+ */
10
+ export declare const DEFAULT_MIGRATIONS_FOLDER: string;
11
+ export type CacheDb = ReturnType<typeof drizzle<typeof schema>>;
12
+ export interface CacheHandle {
13
+ db: CacheDb;
14
+ /** Release the underlying SQLite connection. Safe to call more than once. */
15
+ close: () => void;
16
+ }
17
+ /**
18
+ * Open (or create) the cache database, run pending migrations, and return
19
+ * a Drizzle-wrapped handle.
20
+ *
21
+ * Why better-sqlite3 and not node:sqlite: Drizzle 0.45.x does not yet
22
+ * ship a node:sqlite driver (tracking issue: drizzle-team/drizzle-orm#2648).
23
+ * better-sqlite3 is Drizzle's first-class SQLite driver, synchronous
24
+ * (matches our call-graph assumptions), and ships prebuilt binaries for
25
+ * Windows/macOS/Linux on Node 24 so end users don't need a build toolchain.
26
+ *
27
+ * @param path Absolute file path, or `:memory:` for an in-process database
28
+ * (used by unit tests).
29
+ * @param migrationsFolder Directory containing drizzle-kit output
30
+ * (e.g. src/cache/migrations). When omitted, migrations are
31
+ * skipped - typical only for :memory: unit tests that don't
32
+ * need a migration history.
33
+ */
34
+ export declare function openCache(path: string, migrationsFolder?: string): CacheHandle;
@@ -0,0 +1,32 @@
1
+ import type { AppConfig } from '../config/env';
2
+ import type { CacheDb } from './db';
3
+ /**
4
+ * One held-open IMAP connection per watched folder. IMAP's SELECT is
5
+ * single-mailbox, so watching N folders needs N connections.
6
+ *
7
+ * Server-side events drive cache updates:
8
+ * - `exists` triggers an incremental sync (CONDSTORE makes this cheap).
9
+ * - `flags` updates the cached row directly if we got a UID, otherwise
10
+ * re-syncs the folder.
11
+ * - `expunge` deletes the cached row if we got a UID, otherwise re-syncs.
12
+ *
13
+ * ImapFlow handles the auto-re-IDLE loop internally; callers only need
14
+ * to `mailboxOpen(path)` and subscribe to events.
15
+ */
16
+ export interface IdleSubscription {
17
+ folder: string;
18
+ stop: () => Promise<void>;
19
+ }
20
+ export interface IdleManagerOptions {
21
+ imap: AppConfig['imap'];
22
+ db: CacheDb;
23
+ folders: readonly string[];
24
+ }
25
+ export declare class IdleManager {
26
+ #private;
27
+ constructor(opts: IdleManagerOptions);
28
+ /** Open a watching connection per configured folder. Idempotent. */
29
+ start(): Promise<void>;
30
+ /** Release every watching connection. Idempotent. */
31
+ stop(): Promise<void>;
32
+ }
@@ -0,0 +1,66 @@
1
+ import type { CacheDb } from './db';
2
+ import { type Folder, type FolderInsert, type Email, type EmailInsert } from './schema';
3
+ /**
4
+ * Insert or update a folder row (matched on the primary-key `name`).
5
+ * Used after every SELECT to record the current UIDVALIDITY / UIDNEXT /
6
+ * HIGHESTMODSEQ + refresh `lastSyncedAt`.
7
+ */
8
+ export declare function upsertFolder(db: CacheDb, row: FolderInsert): void;
9
+ export declare function getFolder(db: CacheDb, name: string): Folder | undefined;
10
+ export declare function listFolders(db: CacheDb): Folder[];
11
+ /**
12
+ * Insert or update an email envelope. Matched on (folder, uid) - IMAP UIDs
13
+ * are folder-scoped, never global.
14
+ */
15
+ export declare function upsertEmail(db: CacheDb, row: EmailInsert): void;
16
+ export declare function getEmail(db: CacheDb, folder: string, uid: number): Email | undefined;
17
+ export interface ListEmailsOptions {
18
+ /** Max rows to return. */
19
+ limit?: number;
20
+ /** Rows to skip (for pagination). */
21
+ offset?: number;
22
+ /** If true, only messages without the \\Seen flag. */
23
+ unseenOnly?: boolean;
24
+ /** Only messages received at/after this epoch-ms timestamp. */
25
+ sinceMs?: number;
26
+ /** Only messages received strictly before this epoch-ms timestamp. */
27
+ beforeMs?: number;
28
+ }
29
+ /**
30
+ * List cached emails in a folder, newest first by IMAP INTERNALDATE.
31
+ * Messages with a null date sort last - preserves determinism when a
32
+ * provider returns envelope-only rows without dates.
33
+ */
34
+ export declare function listEmailsByFolder(db: CacheDb, folder: string, opts?: ListEmailsOptions): Email[];
35
+ export declare function countEmailsInFolder(db: CacheDb, folder: string): number;
36
+ /**
37
+ * Replace the flag set on a cached email. Used for write-through
38
+ * invalidation after mark-read/mark-unread, and when IDLE delivers
39
+ * a FLAGS update.
40
+ */
41
+ export declare function setEmailFlags(db: CacheDb, folder: string, uid: number, flags: string[]): void;
42
+ /**
43
+ * Wipe every cached message in a folder. Invoked when UIDVALIDITY changes
44
+ * on the server - all our UIDs have been invalidated at once.
45
+ */
46
+ export declare function deleteEmailsByFolder(db: CacheDb, folder: string): void;
47
+ /**
48
+ * Remove a single cached email. Invoked on EXPUNGE from IDLE, and after
49
+ * destructive tools (delete_email, move_to_folder) succeed on the server.
50
+ */
51
+ export declare function deleteEmail(db: CacheDb, folder: string, uid: number): void;
52
+ /**
53
+ * Remove a batch of UIDs from the cache in one statement. Used by the
54
+ * EXPUNGE-detection path of the UID-diff sync fallback.
55
+ */
56
+ export declare function deleteEmailsByUids(db: CacheDb, folder: string, uids: number[]): void;
57
+ export interface CachedBody {
58
+ bodyText: string | null;
59
+ bodyHtml: string | null;
60
+ bodyCachedAt: number | null;
61
+ }
62
+ export declare function getEmailBody(db: CacheDb, folder: string, uid: number): CachedBody | undefined;
63
+ export declare function setEmailBody(db: CacheDb, folder: string, uid: number, body: {
64
+ text: string | null;
65
+ html: string | null;
66
+ }, nowMs: number): void;