@bobfrankston/iflow-direct 0.1.16 → 0.1.17

package/README.md

@@ -0,0 +1,117 @@
+# @bobfrankston/iflow-direct
+
+Transport-agnostic IMAP client. Zero Node.js deps — works in Node, Electron, and
+the browser (via a bridge transport). Caller supplies a `TransportFactory`, OAuth
+token provider (if needed), and drives the client.
+
+See [MIGRATION.md](./MIGRATION.md) for the split from legacy `@bobfrankston/iflow`
+and the desktop/browser architecture diagram.
+
+## Install
+
+```bash
+npm install @bobfrankston/iflow-direct
+# desktop TCP transport:
+npm install @bobfrankston/tcp-transport
+```
+
+## Quick start (desktop)
+
+```typescript
+import { NativeImapClient } from "@bobfrankston/iflow-direct";
+import { TcpTransport } from "@bobfrankston/tcp-transport";
+
+const client = new NativeImapClient(
+    { server: "imap.example.com", port: 993, username: "me", password: "..." },
+    () => new TcpTransport(),
+);
+await client.connect();
+await client.select("INBOX");
+const msgs = await client.fetchMessages("1:50", { source: false });
+await client.logout();
+```
+
+For the legacy API shape (`getFolderList`, etc.) use `CompatImapClient` from the
+same package.
+
+## Batch body retrieval
+
+Two APIs for pulling bodies across many UIDs in a single `UID FETCH` round trip,
+with per-message streaming as responses arrive (not buffered until the tagged OK).
+
+### `fetchMessagesStream(range, options, onMessage?)`
+
+Streaming variant of `fetchMessages`. `range` accepts any IMAP sequence set —
+single UID (`"42"`), range (`"100:200"`), comma list (`"1,5,10,42"`), or mixed
+(`"1:10,42,50:55"`). The server handles all forms.
+
+```typescript
+await client.select("INBOX");
+await client.fetchMessagesStream(
+    "1,5,10,42,100:150",
+    { source: true, headers: false },
+    (msg) => {
+        // Called once per message as soon as its FETCH response
+        // (literals included) is fully received. Tagged OK has not arrived yet.
+        console.log(msg.uid, msg.source.length);
+    },
+);
+```
+
+Returns the parsed messages at the tagged OK; if `onMessage` is omitted, behaves
+like `fetchMessages` (collect-all).
+
+### `fetchBodiesBatch(folderPath, uids, onBody)`
+
+Folder-scoped convenience. Selects the folder (skips if already selected), issues
+one `UID FETCH <comma-list> (UID FLAGS ENVELOPE RFC822.SIZE INTERNALDATE BODY.PEEK[])`,
+streams each `(uid, source)` through `onBody`, returns on tagged OK.
+
+```typescript
+await client.fetchBodiesBatch("INBOX", [1, 5, 10, 42], (uid, source) => {
+    store.saveBody(uid, source);
+});
+```
+
+Intended for prefetch pipelines — e.g. mailx-imap's body-prefetch path — that
+would otherwise issue one SELECT+FETCH per message.
+
+### Streaming guarantees
+
+- `onMessage` / `onBody` fires on the same event-loop turn that the server's
+  FETCH response (with any literal bodies) is fully parsed.
+- Ordering matches server response order. For a comma list, servers typically
+  return in the order requested, but RFC 3501 does not require it — treat order
+  as server-defined.
+- Callback exceptions are caught and logged (verbose mode) so one bad message
+  doesn't abort the batch. Throw only if you want that behavior and wrap your
+  own try/catch.
+- The tagged-OK promise still resolves with the full response list; callers
+  needing both streaming and a terminal "all done" signal should `await` the
+  returned promise.
+
+## Other APIs
+
+`NativeImapClient` exposes the usual IMAP surface: `select`, `examine`,
+`listFolders`, `getStatus`, `search`, `fetchMessage`, `fetchSinceUid`,
+`fetchByDate` (both with optional `onChunk` chunked callbacks), `addFlags`,
+`removeFlags`, `copyMessage`, `moveMessage`, `deleteMessage`, `expunge`,
+`appendMessage`, `startIdle`, `logout`. See `imap-native.ts` for signatures.
+
+IDLE auto-suspends when any other command is issued on the same connection and
+re-enters afterwards — safe to interleave commands with a long-running IDLE.
+
+## Configuration
+
+`ImapClientConfig` fields relevant to throughput/resilience:
+
+| Field | Default | Notes |
+|---|---|---|
+| `inactivityTimeout` | 60000 | ms with no data before connection is declared dead. Timer resets on every byte. Slow Dovecot often needs 180000+. |
+| `fetchChunkSize` | 25 | Initial chunk size for `fetchSinceUid`/`fetchByDate`. |
+| `fetchChunkSizeMax` | 500 | Ramps up 4× per chunk. Batch APIs above bypass chunking — caller decides. |
+| `verbose` | false | Log every command/response line + literal bookkeeping. |
+
+## Files
+
+See [MIGRATION.md § Files in iflow-direct](./MIGRATION.md#files-in-iflow-direct).

package/imap-compat.d.ts

@@ -38,6 +38,11 @@ export declare class CompatImapClient {
     fetchMessagesSinceUid(mailbox: string, sinceUid: number, options?: {
         source?: boolean;
     }): Promise<FetchedMessage[]>;
+    /** Batch-fetch bodies for many UIDs in one folder on one connection. Streams
+     *  each body through `onBody` as it arrives. No per-message round trips —
+     *  one SELECT, one UID FETCH, streaming response. Required by mailx-imap's
+     *  batch prefetch path. */
+    fetchBodiesBatch(mailbox: string, uids: number[], onBody: (uid: number, source: string) => void): Promise<void>;
     /** Fetch messages by date range. Optional onChunk callback for incremental processing. */
     fetchMessageByDate(mailbox: string, start: Date, end?: Date, options?: {
         source?: boolean;

package/imap-compat.js

@@ -93,6 +93,16 @@ export class CompatImapClient {
         await this.native.closeMailbox();
         return msgs.map(m => new FetchedMessage(m));
     }
+    /** Batch-fetch bodies for many UIDs in one folder on one connection. Streams
+     *  each body through `onBody` as it arrives. No per-message round trips —
+     *  one SELECT, one UID FETCH, streaming response. Required by mailx-imap's
+     *  batch prefetch path. */
+    async fetchBodiesBatch(mailbox, uids, onBody) {
+        if (uids.length === 0)
+            return;
+        await this.ensureConnected();
+        await this.native.fetchBodiesBatch(mailbox, uids, onBody);
+    }
     /** Fetch messages by date range. Optional onChunk callback for incremental processing. */
     async fetchMessageByDate(mailbox, start, end, options, onChunk) {
         await this.ensureConnected();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/iflow-direct",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Direct IMAP client — transport-agnostic, no Node.js dependencies, browser-ready",
   "main": "index.js",
   "types": "index.ts",