@bobfrankston/iflow-direct 0.1.42 → 0.1.43

package/imap-compat.d.ts

@@ -106,6 +106,42 @@ export declare class CompatImapClient {
     /** Cached CAPABILITY set parsed at connect/login. Callers gate
      *  optional features (NOTIFY, QRESYNC, MOVE, ...) on this. */
     getCapabilities(): Set<string>;
+    /** RFC 5161 ENABLE — activates an IMAP extension for the remainder of
+     *  the session. QRESYNC must be enabled before any SELECT for
+     *  `* VANISHED` responses + automatic `MODSEQ` to start flowing.
+     *  Returns the set of extensions the server confirmed are active. */
+    enable(extensions: string[]): Promise<Set<string>>;
+    /** Convenience: enable QRESYNC if the server advertises it. Returns
+     *  true if QRESYNC is active on the session afterwards. Idempotent —
+     *  safe to call once per connection at connect time. */
+    enableQresync(): Promise<boolean>;
+    /** Fast resync of a mailbox via RFC 7162 QRESYNC. Caller supplies the
+     *  `uidValidity` and last-seen `modSeq` from its prior visit; the
+     *  server replies with `* VANISHED` for UIDs expunged since then and
+     *  unsolicited `* FETCH` for state changes (flag updates etc.) since
+     *  then, plus the current `HIGHESTMODSEQ` for the caller to persist
+     *  as its new watermark.
+     *
+     *  Returns:
+     *  - `uidValidityChanged`: server's UIDVALIDITY no longer matches; the
+     *    caller's UID set is stale and MUST be full-resynced.
+     *  - `vanishedUids`: authoritative deletion list. No client-side diff.
+     *  - `changedMessages`: state-change FETCH responses since the prior
+     *    modSeq — each carries `uid`, `flags`, and `modSeq` (and possibly
+     *    other FETCH items the caller asked for).
+     *  - `newHighestModSeq`: persist this for the next resync.
+     *
+     *  Pre-requisite: `enableQresync()` returned true once on the session.
+     *  If the server doesn't support QRESYNC, fall back to the older
+     *  `fetchMessagesSinceUid` / set-diff path. */
+    resyncFolder(mailbox: string, uidValidity: number, modSeq: number): Promise<{
+        uidValidityChanged: boolean;
+        vanishedUids: number[];
+        changedMessages: FetchedMessage[];
+        newHighestModSeq: number | undefined;
+        exists: number;
+        uidNext: number;
+    }>;
     /** 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

package/imap-compat.js

@@ -279,6 +279,61 @@ export class CompatImapClient {
     getCapabilities() {
         return this.native.getCapabilities();
     }
+    /** RFC 5161 ENABLE — activates an IMAP extension for the remainder of
+     *  the session. QRESYNC must be enabled before any SELECT for
+     *  `* VANISHED` responses + automatic `MODSEQ` to start flowing.
+     *  Returns the set of extensions the server confirmed are active. */
+    async enable(extensions) {
+        await this.ensureConnected();
+        return this.native.enable(extensions);
+    }
+    /** Convenience: enable QRESYNC if the server advertises it. Returns
+     *  true if QRESYNC is active on the session afterwards. Idempotent —
+     *  safe to call once per connection at connect time. */
+    async enableQresync() {
+        const caps = this.getCapabilities();
+        if (!caps.has("QRESYNC"))
+            return false;
+        const enabled = await this.enable(["QRESYNC"]);
+        return enabled.has("QRESYNC");
+    }
+    /** Fast resync of a mailbox via RFC 7162 QRESYNC. Caller supplies the
+     *  `uidValidity` and last-seen `modSeq` from its prior visit; the
+     *  server replies with `* VANISHED` for UIDs expunged since then and
+     *  unsolicited `* FETCH` for state changes (flag updates etc.) since
+     *  then, plus the current `HIGHESTMODSEQ` for the caller to persist
+     *  as its new watermark.
+     *
+     *  Returns:
+     *  - `uidValidityChanged`: server's UIDVALIDITY no longer matches; the
+     *    caller's UID set is stale and MUST be full-resynced.
+     *  - `vanishedUids`: authoritative deletion list. No client-side diff.
+     *  - `changedMessages`: state-change FETCH responses since the prior
+     *    modSeq — each carries `uid`, `flags`, and `modSeq` (and possibly
+     *    other FETCH items the caller asked for).
+     *  - `newHighestModSeq`: persist this for the next resync.
+     *
+     *  Pre-requisite: `enableQresync()` returned true once on the session.
+     *  If the server doesn't support QRESYNC, fall back to the older
+     *  `fetchMessagesSinceUid` / set-diff path. */
+    async resyncFolder(mailbox, uidValidity, modSeq) {
+        await this.ensureConnected();
+        const result = await this.native.select(mailbox, { uidValidity, modSeq });
+        // Untagged FETCH responses emitted during a QRESYNC SELECT are
+        // pre-parsed by the native layer into NativeFetchedMessage objects;
+        // expose them as FetchedMessage to compat callers. (The native
+        // select() doesn't currently surface these — that wiring is in
+        // imap-native.ts:select via the FETCH-during-select case.)
+        const changedMessages = result.changedMessages?.map((m) => new FetchedMessage(m)) || [];
+        return {
+            uidValidityChanged: result.uidValidityChanged,
+            vanishedUids: result.vanishedUids,
+            changedMessages,
+            newHighestModSeq: result.highestModSeq,
+            exists: result.exists,
+            uidNext: result.uidNext,
+        };
+    }
     /** 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

package/imap-native.d.ts

@@ -30,6 +30,11 @@ export interface NativeFetchedMessage {
     flagged: boolean;
     answered: boolean;
     draft: boolean;
+    /** Per-message modification sequence (RFC 7162). Present when the
+     *  server is CONDSTORE/QRESYNC-capable and the client either has
+     *  ENABLE QRESYNC active or asked for MODSEQ explicitly. Used by the
+     *  caller to track its own `last_modseq` watermark per folder. */
+    modSeq?: number;
 }
 export interface NativeFolder {
     path: string;

package/imap-native.js

@@ -1336,6 +1336,14 @@ export class NativeImapClient {
             const sizeMatch = r.text.match(/RFC822\.SIZE\s+(\d+)/);
             if (sizeMatch)
                 msg.size = parseInt(sizeMatch[1]);
+            // Extract MODSEQ (RFC 7162). Format: `MODSEQ (12345)`. Server
+            // emits this when the session has ENABLE QRESYNC/CONDSTORE
+            // active OR when the client explicitly asks for MODSEQ in the
+            // FETCH command. Track on every FETCH so the caller can update
+            // its `last_modseq` watermark.
+            const modSeqMatch = r.text.match(/MODSEQ\s+\((\d+)\)/);
+            if (modSeqMatch)
+                msg.modSeq = parseInt(modSeqMatch[1]);
             // Extract INTERNALDATE
             const dateMatch = r.text.match(/INTERNALDATE\s+"([^"]+)"/);
             if (dateMatch)

package/package.json

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