@bobfrankston/iflow-direct 0.1.35 → 0.1.40

package/imap-compat.d.ts

@@ -7,6 +7,7 @@ import { type NativeFolder } from "./imap-native.js";
 import { FetchedMessage } from "./fetched-message.js";
 import type { ImapClientConfig } from "./types.js";
 import type { TransportFactory } from "./transport.js";
+import type * as proto from "./imap-protocol.js";
 /** Special folder detection result */
 export interface SpecialFolders {
     inbox?: string;
@@ -66,6 +67,12 @@ export declare class CompatImapClient {
     getMessagesCount(mailbox: string): Promise<number>;
     /** Get all UIDs in a mailbox */
     getUids(mailbox: string): Promise<number[]>;
+    /** Get UIDs whose INTERNALDATE is on/after `since`. Bounded version of
+     *  getUids — returns only the date window the caller cares about
+     *  instead of the entire folder. Lets set-diff reconciliation scope
+     *  itself to "messages from the last N days" rather than enumerating
+     *  every UID in a 134k-message folder. */
+    getUidsSince(mailbox: string, since: Date): Promise<number[]>;
     /** Fetch messages — supports two calling conventions for compatibility:
      *
      *    New:  fetchMessages(mailbox, "100:200")           — UID range string
@@ -96,8 +103,18 @@ export declare class CompatImapClient {
     createmailbox(name: string): Promise<void>;
     /** Append a message to a mailbox */
     appendMessage(mailbox: string, message: string | Uint8Array, flags?: string[]): Promise<number | null>;
-    /** Watch a mailbox for new messages (IDLE) */
-    watchMailbox(mailbox: string, onNew: (count: number) => void): Promise<() => Promise<void>>;
+    /** Cached CAPABILITY set parsed at connect/login. Callers gate
+     *  optional features (NOTIFY, QRESYNC, MOVE, ...) on this. */
+    getCapabilities(): Set<string>;
+    /** Watch a mailbox for new messages (IDLE). Optionally engage RFC 5465
+     *  NOTIFY so the server also pushes STATUS responses for non-selected
+     *  mailboxes named in `opts.notifySpec` — `opts.onMailboxStatus` fires
+     *  for each. Capability check is the caller's responsibility; pass
+     *  notifySpec only when `getCapabilities().has("NOTIFY")`. */
+    watchMailbox(mailbox: string, onNew: (count: number) => void, opts?: {
+        notifySpec?: string;
+        onMailboxStatus?: (mailbox: string, data: proto.StatusData) => void;
+    }): Promise<() => Promise<void>>;
     /** Copy a message to another server (cross-account) */
     moveMessageToServer(msg: any, fromMailbox: string, targetClient: CompatImapClient, toMailbox: string): Promise<void>;
     /** Rename a mailbox (via native access) */

package/imap-compat.js

@@ -168,6 +168,20 @@ export class CompatImapClient {
         await this.native.closeMailbox();
         return uids;
     }
+    /** Get UIDs whose INTERNALDATE is on/after `since`. Bounded version of
+     *  getUids — returns only the date window the caller cares about
+     *  instead of the entire folder. Lets set-diff reconciliation scope
+     *  itself to "messages from the last N days" rather than enumerating
+     *  every UID in a 134k-message folder. */
+    async getUidsSince(mailbox, since) {
+        await this.ensureConnected();
+        await this.native.select(mailbox);
+        const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+        const d = `${since.getUTCDate()}-${months[since.getUTCMonth()]}-${since.getUTCFullYear()}`;
+        const uids = await this.native.search(`SINCE ${d}`);
+        await this.native.closeMailbox();
+        return uids;
+    }
     async fetchMessages(mailbox, rangeOrEnd, countOrOptions, maybeOptions) {
         let range;
         let options;
@@ -260,10 +274,23 @@ export class CompatImapClient {
         const data = typeof message === "string" ? message : new TextDecoder().decode(message);
         return this.native.appendMessage(mailbox, data, flags);
     }
-    /** Watch a mailbox for new messages (IDLE) */
-    async watchMailbox(mailbox, onNew) {
+    /** Cached CAPABILITY set parsed at connect/login. Callers gate
+     *  optional features (NOTIFY, QRESYNC, MOVE, ...) on this. */
+    getCapabilities() {
+        return this.native.getCapabilities();
+    }
+    /** Watch a mailbox for new messages (IDLE). Optionally engage RFC 5465
+     *  NOTIFY so the server also pushes STATUS responses for non-selected
+     *  mailboxes named in `opts.notifySpec` — `opts.onMailboxStatus` fires
+     *  for each. Capability check is the caller's responsibility; pass
+     *  notifySpec only when `getCapabilities().has("NOTIFY")`. */
+    async watchMailbox(mailbox, onNew, opts) {
         await this.ensureConnected();
         await this.native.select(mailbox);
+        if (opts?.onMailboxStatus)
+            this.native.onMailboxStatus = opts.onMailboxStatus;
+        if (opts?.notifySpec)
+            await this.native.notify(opts.notifySpec);
         return this.native.startIdle(onNew);
     }
     /** Copy a message to another server (cross-account) */

package/imap-native.d.ts

@@ -48,21 +48,40 @@ export declare class NativeImapClient {
     private transport;
     private transportFactory;
     private config;
-    /** Receive buffer + read offset. CRITICAL: never reassign with
-     *  `this.buffer = this.buffer.substring(N)` — that copies the whole
-     *  remainder per line and is O(n²) over a multi-line response (a 457KB
-     *  LIST response actually blocked the daemon's event loop for 10 minutes
-     *  in production). Use bufferOffset to advance the read cursor; only
-     *  compact the buffer string when the consumed portion is >= half its
-     *  length, keeping per-line work O(1). */
+    /** Byte-level receive buffer. IMAP literals (`{N}`) are octets — message
+     *  bodies, MIME parts with binary content, non-UTF-8 charsets — and the
+     *  parser MUST work in bytes to recover them with byte fidelity and
+     *  without paying O(n²) re-encoding cost on every chunk arrival. The
+     *  prior implementation kept `this.buffer` as a JS string, accumulated
+     *  UTF-8-decoded text from the transport, then `TextEncoder.encode`'d
+     *  the whole unread region on every TCP chunk while waiting for a
+     *  literal — pegged the event loop on multi-message FETCH responses.
+     *
+     *  Invariants:
+     *    - `buffer[0 .. bufferLength)` holds valid received bytes
+     *    - `buffer[bufferOffset .. bufferLength)` is unread
+     *    - capacity = `buffer.length` ≥ `bufferLength`; we grow on demand
+     *    - never substring — bufferOffset advances past consumed bytes;
+     *      compactBufferIfNeeded reclaims space when consumed >= half. */
     private buffer;
+    private bufferLength;
     private bufferOffset;
+    /** Cached decoder so per-line / per-literal decode doesn't re-construct
+     *  one. `fatal: false` (default) replaces invalid UTF-8 sequences with
+     *  U+FFFD — same lenient behavior as JavaScript's implicit string
+     *  decoding the parser used to rely on. */
+    private utf8Decoder;
     private pendingCommand;
     private capabilities;
     private _connected;
     private idleTag;
     private idleCallback;
     private idleRefreshTimer;
+    /** RFC 5465 NOTIFY: fires on unsolicited STATUS responses for non-selected
+     *  mailboxes (the server pushes these when the client has issued NOTIFY
+     *  SET with a PERSONAL group). Distinct from `idleCallback` which only
+     *  fires for EXISTS on the currently-selected mailbox. */
+    onMailboxStatus: ((mailbox: string, data: proto.StatusData) => void) | null;
     /** Set by startIdle's stop closure so auto-suspend knows not to resume after a command finishes. */
     private idleStopped;
     private verbose;
@@ -90,6 +109,11 @@ export declare class NativeImapClient {
     private authenticate;
     private starttls;
     capability(): Promise<Set<string>>;
+    /** Return the cached CAPABILITY set parsed at connect/login time. Callers
+     *  use this to gate optional code paths (NOTIFY, QRESYNC, MOVE, etc.)
+     *  without re-issuing CAPABILITY. Returns a defensive copy so callers
+     *  can't mutate internal state. */
+    getCapabilities(): Set<string>;
     private parseCapabilities;
     logout(): Promise<void>;
     select(mailbox: string): Promise<MailboxInfo>;
@@ -165,6 +189,14 @@ export declare class NativeImapClient {
     expunge(): Promise<void>;
     /** Append a message to a mailbox */
     appendMessage(mailbox: string, message: string | Uint8Array, flags?: string[]): Promise<number | null>;
+    /** Issue NOTIFY SET so the server starts pushing unsolicited STATUS
+     *  responses for the mailboxes named in `spec` (beyond the currently
+     *  selected one). Capability gated — callers must check
+     *  `getCapabilities().has("NOTIFY")` before calling. Set
+     *  `onMailboxStatus` before issuing if you want to react. Issue AFTER
+     *  SELECT and BEFORE startIdle — the server holds the spec for the
+     *  lifetime of the connection. */
+    notify(spec: string): Promise<void>;
     startIdle(onNewMail: (count: number) => void): Promise<() => Promise<void>>;
     /**
      * If IDLE is currently active, send DONE and wait for its tagged OK so the
@@ -213,22 +245,47 @@ export declare class NativeImapClient {
      * EXISTS callback (e.g. mailpuller's pullMail) would be ignored by the
      * server until the inactivity timer killed the socket.
      */
+    /** Per-client command serialization. IMAP allows only one command in
+     *  flight at a time on a single connection (RFC 3501 §2.2.1). The
+     *  client's `pendingCommand` field tracks that command — if a second
+     *  caller concurrently invokes sendCommand, it overwrites
+     *  pendingCommand and the first caller's await is orphaned. We saw
+     *  this in production: the outbox poller's `withConnection`-queued
+     *  task ran on the same shared ops client as syncFolder's INBOX work,
+     *  and INBOX silently hung forever (no heartbeat fire, no wall-clock,
+     *  no reject — the promise just had no command tracking it anymore).
+     *
+     *  This chain serializes ALL sendCommand callers against this client
+     *  regardless of whether the caller bothered to coordinate.
+     *  Defensive — the right thing for the upper layer to do is also use
+     *  the queue (withConnection in mailx-imap), but the IMAP client
+     *  shouldn't allow itself to be corrupted by a careless caller. */
+    private commandChain;
     private sendCommand;
     private sendCommandCore;
     private waitForContinuation;
     private waitForTagged;
     private handleData;
+    /** Append received bytes to the receive buffer, growing capacity if
+     *  needed. O(n) over the chunk size, never over the buffer total —
+     *  doubling growth amortizes to O(1) per byte across the response. */
+    private appendToBuffer;
     /** Single canonical "command finished or abandoned" cleanup. Every
      *  path that ends a command's lifecycle — resolve, reject, timeout,
      *  socket close, command-replace — calls this. Was a leak source:
      *  closure-scoped timers in sendCommandCore couldn't be cleared from
      *  handleData's inline-replacement timer or from IDLE suspend/resume. */
     private clearAllCommandTimers;
-    /** Compact the buffer when bufferOffset has advanced past half. Cheap
-     *  amortized cost; eliminates the O(n²) substring-each-line antipattern
-     *  that synchronously blocked the daemon for 10 minutes on a large LIST
-     *  response. */
+    /** Compact the buffer when bufferOffset has advanced past half the used
+     *  region. copyWithin moves the unread bytes to the front in-place
+     *  (no new allocation). Amortized O(1) per byte; never the O(n²)
+     *  substring-each-line pathology that blocked the event loop on a
+     *  large LIST response. */
     private compactBufferIfNeeded;
+    /** Find the next CRLF (0x0D 0x0A) in the unread region, returning the
+     *  byte index of the 0x0D, or -1 if not found. Manual byte loop —
+     *  Uint8Array doesn't have a native indexOf for byte sequences. */
+    private indexOfCRLF;
     private processBuffer;
     private handleUntaggedResponse;
     private parseFetchResponses;

package/imap-native.js

@@ -11,21 +11,40 @@ export class NativeImapClient {
     transport;
     transportFactory;
     config;
-    /** Receive buffer + read offset. CRITICAL: never reassign with
-     *  `this.buffer = this.buffer.substring(N)` — that copies the whole
-     *  remainder per line and is O(n²) over a multi-line response (a 457KB
-     *  LIST response actually blocked the daemon's event loop for 10 minutes
-     *  in production). Use bufferOffset to advance the read cursor; only
-     *  compact the buffer string when the consumed portion is >= half its
-     *  length, keeping per-line work O(1). */
-    buffer = "";
+    /** Byte-level receive buffer. IMAP literals (`{N}`) are octets — message
+     *  bodies, MIME parts with binary content, non-UTF-8 charsets — and the
+     *  parser MUST work in bytes to recover them with byte fidelity and
+     *  without paying O(n²) re-encoding cost on every chunk arrival. The
+     *  prior implementation kept `this.buffer` as a JS string, accumulated
+     *  UTF-8-decoded text from the transport, then `TextEncoder.encode`'d
+     *  the whole unread region on every TCP chunk while waiting for a
+     *  literal — pegged the event loop on multi-message FETCH responses.
+     *
+     *  Invariants:
+     *    - `buffer[0 .. bufferLength)` holds valid received bytes
+     *    - `buffer[bufferOffset .. bufferLength)` is unread
+     *    - capacity = `buffer.length` ≥ `bufferLength`; we grow on demand
+     *    - never substring — bufferOffset advances past consumed bytes;
+     *      compactBufferIfNeeded reclaims space when consumed >= half. */
+    buffer = new Uint8Array(8192);
+    bufferLength = 0;
     bufferOffset = 0;
+    /** Cached decoder so per-line / per-literal decode doesn't re-construct
+     *  one. `fatal: false` (default) replaces invalid UTF-8 sequences with
+     *  U+FFFD — same lenient behavior as JavaScript's implicit string
+     *  decoding the parser used to rely on. */
+    utf8Decoder = new TextDecoder("utf-8");
     pendingCommand = null;
     capabilities = new Set();
     _connected = false;
     idleTag = null;
     idleCallback = null;
     idleRefreshTimer = null;
+    /** RFC 5465 NOTIFY: fires on unsolicited STATUS responses for non-selected
+     *  mailboxes (the server pushes these when the client has issued NOTIFY
+     *  SET with a PERSONAL group). Distinct from `idleCallback` which only
+     *  fires for EXISTS on the currently-selected mailbox. */
+    onMailboxStatus = null;
     /** Set by startIdle's stop closure so auto-suspend knows not to resume after a command finishes. */
     idleStopped = true;
     verbose;
@@ -73,7 +92,7 @@ export class NativeImapClient {
         catch { /* ignore */ }
         this.transport = this.transportFactory();
         this._connected = false;
-        this.buffer = "";
+        this.bufferLength = 0;
         this.bufferOffset = 0;
         this.pendingCommand = null;
         this.selectedMailbox = null;
@@ -210,6 +229,13 @@ export class NativeImapClient {
         }
         return this.capabilities;
     }
+    /** Return the cached CAPABILITY set parsed at connect/login time. Callers
+     *  use this to gate optional code paths (NOTIFY, QRESYNC, MOVE, etc.)
+     *  without re-issuing CAPABILITY. Returns a defensive copy so callers
+     *  can't mutate internal state. */
+    getCapabilities() {
+        return new Set(this.capabilities);
+    }
     parseCapabilities(text) {
         const caps = text.replace(/^CAPABILITY\s*/i, "").split(/\s+/);
         this.capabilities.clear();
@@ -609,6 +635,22 @@ export class NativeImapClient {
         const uidMatch = tagged.text.match(/APPENDUID\s+\d+\s+(\d+)/i);
         return uidMatch ? parseInt(uidMatch[1]) : null;
     }
+    // ── NOTIFY (RFC 5465) ──
+    /** Issue NOTIFY SET so the server starts pushing unsolicited STATUS
+     *  responses for the mailboxes named in `spec` (beyond the currently
+     *  selected one). Capability gated — callers must check
+     *  `getCapabilities().has("NOTIFY")` before calling. Set
+     *  `onMailboxStatus` before issuing if you want to react. Issue AFTER
+     *  SELECT and BEFORE startIdle — the server holds the spec for the
+     *  lifetime of the connection. */
+    async notify(spec) {
+        const tag = proto.nextTag();
+        const responses = await this.sendCommand(tag, proto.notifyCommand(tag, spec));
+        const tagged = responses.find(r => r.tag === tag);
+        if (!tagged || tagged.type !== "OK") {
+            throw new Error(`NOTIFY SET failed: ${tagged?.text || "unknown"}`);
+        }
+    }
     // ── IDLE ──
     async startIdle(onNewMail) {
         this.idleCallback = onNewMail;
@@ -788,22 +830,52 @@ export class NativeImapClient {
      * EXISTS callback (e.g. mailpuller's pullMail) would be ignored by the
      * server until the inactivity timer killed the socket.
      */
+    /** Per-client command serialization. IMAP allows only one command in
+     *  flight at a time on a single connection (RFC 3501 §2.2.1). The
+     *  client's `pendingCommand` field tracks that command — if a second
+     *  caller concurrently invokes sendCommand, it overwrites
+     *  pendingCommand and the first caller's await is orphaned. We saw
+     *  this in production: the outbox poller's `withConnection`-queued
+     *  task ran on the same shared ops client as syncFolder's INBOX work,
+     *  and INBOX silently hung forever (no heartbeat fire, no wall-clock,
+     *  no reject — the promise just had no command tracking it anymore).
+     *
+     *  This chain serializes ALL sendCommand callers against this client
+     *  regardless of whether the caller bothered to coordinate.
+     *  Defensive — the right thing for the upper layer to do is also use
+     *  the queue (withConnection in mailx-imap), but the IMAP client
+     *  shouldn't allow itself to be corrupted by a careless caller. */
+    commandChain = Promise.resolve();
     async sendCommand(tag, command, onUntagged) {
-        const idleState = await this.suspendIdleForCommand();
+        const prev = this.commandChain.catch(() => { });
+        let myResolve;
+        let myReject;
+        const myPromise = new Promise((res, rej) => { myResolve = res; myReject = rej; });
+        this.commandChain = myPromise.catch(() => { });
+        await prev;
         try {
-            return await this.sendCommandCore(tag, command, onUntagged);
-        }
-        finally {
-            if (idleState) {
-                try {
-                    await this.resumeIdleAfterCommand(idleState);
-                }
-                catch (err) {
-                    if (this.verbose)
-                        console.error(`  [imap] IDLE auto-resume failed: ${err.message}`);
+            const idleState = await this.suspendIdleForCommand();
+            try {
+                const out = await this.sendCommandCore(tag, command, onUntagged);
+                myResolve(out);
+                return out;
+            }
+            finally {
+                if (idleState) {
+                    try {
+                        await this.resumeIdleAfterCommand(idleState);
+                    }
+                    catch (err) {
+                        if (this.verbose)
+                            console.error(`  [imap] IDLE auto-resume failed: ${err.message}`);
+                    }
                 }
             }
         }
+        catch (e) {
+            myReject(e);
+            throw e;
+        }
     }
     sendCommandCore(tag, command, onUntagged) {
         return new Promise((resolve, reject) => {
@@ -920,9 +992,25 @@ export class NativeImapClient {
                 }
             }, this.inactivityTimeout);
         }
-        this.buffer += data;
+        this.appendToBuffer(data);
         this.processBuffer();
     }
+    /** Append received bytes to the receive buffer, growing capacity if
+     *  needed. O(n) over the chunk size, never over the buffer total —
+     *  doubling growth amortizes to O(1) per byte across the response. */
+    appendToBuffer(data) {
+        const need = this.bufferLength + data.length;
+        if (need > this.buffer.length) {
+            let cap = Math.max(this.buffer.length * 2, 8192);
+            while (cap < need)
+                cap *= 2;
+            const grown = new Uint8Array(cap);
+            grown.set(this.buffer.subarray(0, this.bufferLength));
+            this.buffer = grown;
+        }
+        this.buffer.set(data, this.bufferLength);
+        this.bufferLength += data.length;
+    }
     /** Single canonical "command finished or abandoned" cleanup. Every
      *  path that ends a command's lifecycle — resolve, reject, timeout,
      *  socket close, command-replace — calls this. Was a leak source:
@@ -942,78 +1030,99 @@ export class NativeImapClient {
             this.wallClockTimer = null;
         }
     }
-    /** Compact the buffer when bufferOffset has advanced past half. Cheap
-     *  amortized cost; eliminates the O(n²) substring-each-line antipattern
-     *  that synchronously blocked the daemon for 10 minutes on a large LIST
-     *  response. */
+    /** Compact the buffer when bufferOffset has advanced past half the used
+     *  region. copyWithin moves the unread bytes to the front in-place
+     *  (no new allocation). Amortized O(1) per byte; never the O(n²)
+     *  substring-each-line pathology that blocked the event loop on a
+     *  large LIST response. */
     compactBufferIfNeeded() {
-        if (this.bufferOffset > 0 && this.bufferOffset >= this.buffer.length / 2) {
-            this.buffer = this.buffer.substring(this.bufferOffset);
+        if (this.bufferOffset > 0 && this.bufferOffset >= this.bufferLength / 2) {
+            this.buffer.copyWithin(0, this.bufferOffset, this.bufferLength);
+            this.bufferLength -= this.bufferOffset;
             this.bufferOffset = 0;
         }
     }
+    /** Find the next CRLF (0x0D 0x0A) in the unread region, returning the
+     *  byte index of the 0x0D, or -1 if not found. Manual byte loop —
+     *  Uint8Array doesn't have a native indexOf for byte sequences. */
+    indexOfCRLF(from) {
+        const buf = this.buffer;
+        const end = this.bufferLength - 1;
+        for (let i = from; i < end; i++) {
+            if (buf[i] === 0x0D && buf[i + 1] === 0x0A)
+                return i;
+        }
+        return -1;
+    }
     processBuffer() {
         while (true) {
-            // Check for literal {size}\r\n — reading exact BYTE count of literal data
-            // CRITICAL: literalBytes is in octets (from IMAP {N}), but this.buffer is a
-            // JavaScript string where multi-byte UTF-8 characters count as 1 character.
-            // We must use byte-accurate extraction (TextEncoder for browser, Buffer for Node).
+            // Check for literal — `{N}` announces N octets of arbitrary data
+            // (message body, MIME part, attachment chunk). The buffer is
+            // bytes; the check is a direct length compare and the slice is
+            // O(N) over the literal's own size — never O(buffer²).
             if (this.pendingCommand?.literalBytes != null) {
                 const neededBytes = this.pendingCommand.literalBytes;
-                // Encode only the unread portion — was encoding the whole
-                // buffer (including already-consumed bytes) on every literal,
-                // which on a multi-MB buffer is a non-trivial chunk of work.
-                const unread = this.bufferOffset === 0 ? this.buffer : this.buffer.substring(this.bufferOffset);
-                const encoded = new TextEncoder().encode(unread);
-                const bufferBytes = encoded.byteLength;
-                if (bufferBytes >= neededBytes) {
-                    const literal_bytes = encoded.subarray(0, neededBytes);
-                    const rest_bytes = encoded.subarray(neededBytes);
-                    let literal = new TextDecoder().decode(literal_bytes);
-                    // Reset buffer to just the rest — bufferOffset goes back
-                    // to 0 since we replaced the buffer content.
-                    this.buffer = new TextDecoder().decode(rest_bytes);
-                    this.bufferOffset = 0;
-                    // For non-BODY literals (e.g. display names in ENVELOPE), wrap in quotes
-                    // so tokenizeParenList treats them as a single token
-                    if (!this.pendingCommand.currentLiteralKey) {
-                        literal = `"${literal.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r?\n/g, "")}"`;
-                    }
-                    this.pendingCommand.literalBuffer = (this.pendingCommand.literalBuffer || "") + literal;
-                    this.pendingCommand.literalBytes = undefined;
-                    // Store the literal data by its BODY key for parseFetchResponses
-                    if (this.pendingCommand.currentLiteralKey) {
-                        if (!this.pendingCommand.literals)
-                            this.pendingCommand.literals = new Map();
-                        this.pendingCommand.literals.set(this.pendingCommand.currentLiteralKey, literal);
-                        this.pendingCommand.currentLiteralKey = undefined;
-                        this.pendingCommand.currentLiteralSize = undefined;
+                const available = this.bufferLength - this.bufferOffset;
+                if (available < neededBytes) {
+                    if (this.verbose && this.pendingCommand.literalBytes > 0) {
+                        console.log(`  [imap] waiting for literal: need ${neededBytes} bytes, have ${available}`);
                     }
-                    if (this.verbose)
-                        console.log(`  [imap] literal consumed, ${literal.length} bytes, buffer remaining: ${this.buffer.length}`);
-                    // After consuming literal, check if the NEXT part has another literal
-                    // (e.g., BODY[HEADER] {500}\r\n<data>BODY[] {2000}\r\n<data>)\r\n)
-                    // Continue to process the next line/literal from the buffer
-                    continue;
+                    break; // Wait for more data — cheap, no decode.
+                }
+                // Slice the literal bytes; advance the read cursor by N.
+                // The bytes themselves stay in the underlying buffer for the
+                // moment, but bufferOffset advances past them and the next
+                // compactBufferIfNeeded will reclaim the space.
+                const literalBytes = this.buffer.subarray(this.bufferOffset, this.bufferOffset + neededBytes);
+                this.bufferOffset += neededBytes;
+                // Decode literal once (UTF-8 with replacement). For BODY[]
+                // literals carrying non-UTF-8 charsets this is still lossy —
+                // the proper fix is to keep literals as bytes through to the
+                // body store, tracked separately. The win HERE is that the
+                // decode happens once per literal, not once per chunk that
+                // arrives during the literal's transit.
+                let literal = this.utf8Decoder.decode(literalBytes);
+                // For non-BODY literals (e.g. display names in ENVELOPE), wrap in quotes
+                // so tokenizeParenList treats them as a single token
+                if (!this.pendingCommand.currentLiteralKey) {
+                    literal = `"${literal.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r?\n/g, "")}"`;
                 }
-                if (this.verbose && this.pendingCommand.literalBytes > 0) {
-                    console.log(`  [imap] waiting for literal: need ${neededBytes} bytes, have ${bufferBytes} bytes`);
+                this.pendingCommand.literalBuffer = (this.pendingCommand.literalBuffer || "") + literal;
+                this.pendingCommand.literalBytes = undefined;
+                // Store the literal data by its BODY key for parseFetchResponses
+                if (this.pendingCommand.currentLiteralKey) {
+                    if (!this.pendingCommand.literals)
+                        this.pendingCommand.literals = new Map();
+                    this.pendingCommand.literals.set(this.pendingCommand.currentLiteralKey, literal);
+                    this.pendingCommand.currentLiteralKey = undefined;
+                    this.pendingCommand.currentLiteralSize = undefined;
                 }
-                break; // Wait for more data
+                if (this.verbose)
+                    console.log(`  [imap] literal consumed, ${neededBytes} bytes, buffer remaining: ${this.bufferLength - this.bufferOffset}`);
+                // Allow the consumed-prefix to be reclaimed when half-full —
+                // long literal-heavy responses would otherwise grow the
+                // backing buffer indefinitely between commands.
+                this.compactBufferIfNeeded();
+                continue;
             }
-            // Find next CRLF starting from the read offset (NOT from 0 —
-            // the bytes before bufferOffset are already consumed and
-            // searching them is dead work that scales with response size).
-            const lineEnd = this.buffer.indexOf("\r\n", this.bufferOffset);
+            // Find next CRLF starting from the read offset on bytes (not
+            // chars). bufferOffset advances past consumed bytes; we only
+            // search the unread region so per-line work is O(line length),
+            // never O(response size).
+            const lineEnd = this.indexOfCRLF(this.bufferOffset);
             if (lineEnd < 0) {
                 // No complete line yet. Compact the buffer if we've advanced
                 // far enough that the unconsumed-prefix is dragging.
                 this.compactBufferIfNeeded();
                 break;
             }
-            // Extract the line and advance the read cursor — no substring
-            // copy of the remainder, no buffer reallocation.
-            const line = this.buffer.substring(this.bufferOffset, lineEnd + 2);
+            // Slice the line bytes (including trailing CRLF) and decode
+            // once. IMAP control lines are 7-bit ASCII per RFC 3501; UTF-8
+            // decode is a superset and produces the same characters. The
+            // existing string-based parser (parseResponseLine, tokenizers,
+            // ENVELOPE/FLAGS handling) consumes the decoded line below.
+            const lineBytes = this.buffer.subarray(this.bufferOffset, lineEnd + 2);
+            const line = this.utf8Decoder.decode(lineBytes);
             this.bufferOffset = lineEnd + 2;
             // Periodic compaction so the consumed prefix doesn't keep
             // growing forever in long-running connections (IDLE, big sync).
@@ -1075,6 +1184,26 @@ export class NativeImapClient {
                 }
                 continue;
             }
+            // RFC 5465 NOTIFY: unsolicited STATUS responses for non-selected
+            // mailboxes arrive when the server has accepted a NOTIFY SET that
+            // included a PERSONAL (or other) event group. Only route to the
+            // callback when IDLE is active — a STATUS response outside IDLE
+            // is the result of a direct STATUS command and belongs to the
+            // pending command's response set (the fall-through below).
+            if (this.idleTag && resp.tag === "*" && resp.type === "STATUS" && this.onMailboxStatus) {
+                const parsed = proto.parseStatusResponseFull(resp.text);
+                if (parsed) {
+                    try {
+                        this.onMailboxStatus(parsed.mailbox, parsed.data);
+                    }
+                    catch (err) {
+                        if (this.verbose)
+                            console.error(`  [imap] onMailboxStatus threw: ${err.message}`);
+                    }
+                    continue;
+                }
+                // Parse failed — fall through so the response isn't silently dropped.
+            }
             // Collect untagged responses for the pending command
             if (resp.tag === "*" && this.pendingCommand) {
                 this.pendingCommand.responses.push(resp);

package/imap-protocol.d.ts

@@ -95,6 +95,13 @@ export declare function moveCommand(tag: string, uid: number, destination: strin
 export declare function appendCommand(tag: string, mailbox: string, flags: string[], size: number): string;
 /** Build IDLE command */
 export declare function idleCommand(tag: string): string;
+/** Build NOTIFY SET command (RFC 5465). `spec` is the full event group list,
+ *  e.g. "(SELECTED (MessageNew MessageExpunge FlagChange)) (PERSONAL
+ *  (MessageNew MessageExpunge FlagChange MailboxName))" — the server then
+ *  pushes unsolicited STATUS responses for non-selected mailboxes in the
+ *  spec while the connection is idle. Capability gated: only issue when
+ *  CAPABILITY response contains NOTIFY. */
+export declare function notifyCommand(tag: string, spec: string): string;
 /** Build DONE command (ends IDLE) */
 export declare function doneCommand(): string;
 /** Build STARTTLS command */
@@ -117,6 +124,14 @@ export declare function parseResponseLine(line: string): ImapResponse;
 export declare function parseListResponse(text: string): ListData | null;
 /** Parse STATUS response: * STATUS "mailbox" (MESSAGES n UIDNEXT n ...) */
 export declare function parseStatusResponse(text: string): StatusData | null;
+/** Parse a STATUS response keeping the mailbox name. Used by NOTIFY's
+ *  unsolicited STATUS pushes where the mailbox identifies which folder
+ *  changed — `parseStatusResponse` discards that. Mailbox may be quoted
+ *  ("Sent") or atom-shaped (Sent); the regex handles both. */
+export declare function parseStatusResponseFull(text: string): {
+    mailbox: string;
+    data: StatusData;
+} | null;
 /** Parse UID SEARCH response: * SEARCH 1 2 3 4 5 */
 export declare function parseSearchResponse(text: string): number[];
 /** Parse FLAGS from a FETCH or SELECT response */

package/imap-protocol.js

@@ -79,6 +79,15 @@ export function appendCommand(tag, mailbox, flags, size) {
 export function idleCommand(tag) {
     return buildCommand(tag, "IDLE");
 }
+/** Build NOTIFY SET command (RFC 5465). `spec` is the full event group list,
+ *  e.g. "(SELECTED (MessageNew MessageExpunge FlagChange)) (PERSONAL
+ *  (MessageNew MessageExpunge FlagChange MailboxName))" — the server then
+ *  pushes unsolicited STATUS responses for non-selected mailboxes in the
+ *  spec while the connection is idle. Capability gated: only issue when
+ *  CAPABILITY response contains NOTIFY. */
+export function notifyCommand(tag, spec) {
+    return buildCommand(tag, `NOTIFY SET ${spec}`);
+}
 /** Build DONE command (ends IDLE) */
 export function doneCommand() {
     return "DONE\r\n";
@@ -182,6 +191,34 @@ export function parseStatusResponse(text) {
     }
     return data;
 }
+/** Parse a STATUS response keeping the mailbox name. Used by NOTIFY's
+ *  unsolicited STATUS pushes where the mailbox identifies which folder
+ *  changed — `parseStatusResponse` discards that. Mailbox may be quoted
+ *  ("Sent") or atom-shaped (Sent); the regex handles both. */
+export function parseStatusResponseFull(text) {
+    // Match: "quoted name" (data)   OR   atomname (data)
+    const m = text.match(/^"((?:[^"\\]|\\.)*)"\s*\((.*)\)\s*$/) || text.match(/^(\S+)\s*\((.*)\)\s*$/);
+    if (!m)
+        return null;
+    const mailbox = m[1].replace(/\\(.)/g, "$1");
+    const data = {};
+    const pairs = m[2].split(/\s+/);
+    for (let i = 0; i < pairs.length - 1; i += 2) {
+        const key = pairs[i].toUpperCase();
+        const val = parseInt(pairs[i + 1]);
+        if (key === "MESSAGES")
+            data.messages = val;
+        else if (key === "RECENT")
+            data.recent = val;
+        else if (key === "UIDNEXT")
+            data.uidNext = val;
+        else if (key === "UIDVALIDITY")
+            data.uidValidity = val;
+        else if (key === "UNSEEN")
+            data.unseen = val;
+    }
+    return { mailbox, data };
+}
 /** Parse UID SEARCH response: * SEARCH 1 2 3 4 5 */
 export function parseSearchResponse(text) {
     if (!text.trim())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/iflow-direct",
-  "version": "0.1.35",
+  "version": "0.1.40",
   "description": "Direct IMAP client — transport-agnostic, no Node.js dependencies, browser-ready",
   "main": "index.js",
   "types": "index.ts",
@@ -19,7 +19,7 @@
   "author": "Bob Frankston",
   "license": "ISC",
   "dependencies": {
-    "@bobfrankston/tcp-transport": "^0.1.5"
+    "@bobfrankston/tcp-transport": "^0.1.6"
   },
   "exports": {
     ".": {
@@ -50,7 +50,7 @@
   },
   ".transformedSnapshot": {
     "dependencies": {
-      "@bobfrankston/tcp-transport": "^0.1.5"
+      "@bobfrankston/tcp-transport": "^0.1.6"
     }
   }
 }