@bobfrankston/iflow-direct 0.1.42 → 0.1.44

package/fetched-message.d.ts

@@ -35,6 +35,7 @@ export declare class FetchedMessage implements NativeFetchedMessage {
     flagged: boolean;
     answered: boolean;
     draft: boolean;
+    modSeq?: number;
     parsedHeader: string[][];
     headerSet: HeaderMap;
     constructor(init: NativeFetchedMessage);

package/fetched-message.js

@@ -40,6 +40,7 @@ export class FetchedMessage {
     flagged;
     answered;
     draft;
+    modSeq;
     // Parsed-header state
     parsedHeader;
     headerSet;

package/imap-compat.d.ts

@@ -106,6 +106,52 @@ export declare class CompatImapClient {
     /** Cached CAPABILITY set parsed at connect/login. Callers gate
      *  optional features (NOTIFY, QRESYNC, MOVE, ...) on this. */
     getCapabilities(): Set<string>;
+    /** Snapshot of the most recently SELECTed mailbox's info. Callers use this
+     *  to read `highestModSeq` after any operation that did a SELECT — useful
+     *  for seeding the QRESYNC modSeq watermark on the very first sync of a
+     *  folder (before the QRESYNC path is eligible). */
+    getCurrentMailboxInfo(): {
+        uidValidity: number;
+        uidNext: number;
+        exists: number;
+        highestModSeq?: number;
+    };
+    /** 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,64 @@ export class CompatImapClient {
     getCapabilities() {
         return this.native.getCapabilities();
     }
+    /** Snapshot of the most recently SELECTed mailbox's info. Callers use this
+     *  to read `highestModSeq` after any operation that did a SELECT — useful
+     *  for seeding the QRESYNC modSeq watermark on the very first sync of a
+     *  folder (before the QRESYNC path is eligible). */
+    getCurrentMailboxInfo() {
+        const info = this.native.getMailboxInfo?.();
+        return info || { uidValidity: 0, uidNext: 0, exists: 0 };
+    }
+    /** 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 });
+        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;
@@ -62,10 +67,15 @@ export interface QresyncParams {
     knownUids?: string;
 }
 /** Result of a QRESYNC-enabled SELECT. The caller drains `vanishedUids`
- *  (delete from local store), processes any FETCH responses (upsert state
+ *  (delete from local store), processes `changedMessages` (upsert state
  *  changes), and saves the new `highestModSeq` for the next resync. */
 export interface SelectResult extends MailboxInfo {
     vanishedUids: number[];
+    /** Untagged `* FETCH` responses the server emitted during the QRESYNC
+     *  SELECT — typically flag/MODSEQ changes for messages whose state
+     *  shifted between the caller's previous modSeq and now. Empty for
+     *  non-QRESYNC SELECTs. */
+    changedMessages: NativeFetchedMessage[];
     /** True if the server's UIDVALIDITY changed since the caller's last
      *  visit — in that case knownUids/modSeq are invalid and the caller
      *  must full-resync from scratch. */
@@ -141,6 +151,15 @@ export declare class NativeImapClient {
      *  without re-issuing CAPABILITY. Returns a defensive copy so callers
      *  can't mutate internal state. */
     getCapabilities(): Set<string>;
+    /** Snapshot of the currently-SELECTed mailbox's info. Lets the compat
+     *  client read `highestModSeq` etc. after any select-implying operation
+     *  (fetchMessagesSinceUid, etc.) without re-issuing SELECT. */
+    getMailboxInfo(): {
+        uidValidity: number;
+        uidNext: number;
+        exists: number;
+        highestModSeq?: number;
+    };
     private parseCapabilities;
     logout(): Promise<void>;
     /** SELECT a mailbox. Optional QRESYNC params trigger RFC 7162 fast resync —

package/imap-native.js

@@ -236,6 +236,17 @@ export class NativeImapClient {
     getCapabilities() {
         return new Set(this.capabilities);
     }
+    /** Snapshot of the currently-SELECTed mailbox's info. Lets the compat
+     *  client read `highestModSeq` etc. after any select-implying operation
+     *  (fetchMessagesSinceUid, etc.) without re-issuing SELECT. */
+    getMailboxInfo() {
+        return {
+            uidValidity: this.mailboxInfo.uidValidity,
+            uidNext: this.mailboxInfo.uidNext,
+            exists: this.mailboxInfo.exists,
+            highestModSeq: this.mailboxInfo.highestModSeq,
+        };
+    }
     parseCapabilities(text) {
         const caps = text.replace(/^CAPABILITY\s*/i, "").split(/\s+/);
         this.capabilities.clear();
@@ -271,6 +282,10 @@ export class NativeImapClient {
         this.mailboxInfo.highestModSeq = undefined;
         const vanishedUids = [];
         const priorUidValidity = qresync?.uidValidity;
+        // Untagged FETCH responses emitted during a QRESYNC SELECT carry
+        // state-change deltas the server is volunteering up-front; parse
+        // them through the same path as normal FETCH so the shape matches.
+        const fetchResponses = responses.filter(r => r.tag === "*" && r.type === "FETCH");
         for (const r of responses) {
             if (r.tag !== "*")
                 continue;
@@ -311,9 +326,13 @@ export class NativeImapClient {
         this.selectedMailbox = mailbox;
         const uidValidityChanged = priorUidValidity !== undefined
             && this.mailboxInfo.uidValidity !== priorUidValidity;
+        const changedMessages = fetchResponses.length > 0
+            ? this.parseFetchResponses(fetchResponses)
+            : [];
         return {
             ...this.mailboxInfo,
             vanishedUids,
+            changedMessages,
             uidValidityChanged,
         };
     }
@@ -1336,6 +1355,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.44",
   "description": "Direct IMAP client — transport-agnostic, no Node.js dependencies, browser-ready",
   "main": "index.js",
   "types": "index.ts",