@bobfrankston/iflow-direct 0.1.41 → 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;
@@ -43,6 +48,33 @@ export interface MailboxInfo {
     uidValidity: number;
     flags: string[];
     permanentFlags: string[];
+    /** Per RFC 7162. Present when the server is CONDSTORE/QRESYNC-capable
+     *  and includes [HIGHESTMODSEQ N] in the SELECT-OK response (or after
+     *  ENABLE QRESYNC). Use as the `since-modseq` argument to subsequent
+     *  resyncs to ask the server "what changed since this point?" */
+    highestModSeq?: number;
+}
+/** Parameters for `SELECT mailbox (QRESYNC (uidvalidity modseq))` per RFC 7162.
+ *  Caller persists `(uidValidity, modSeq)` per folder; after ENABLE QRESYNC
+ *  has been issued once on the session, the next SELECT replies with
+ *  `* VANISHED (EARLIER) <uids>` for every message the server expunged since
+ *  `modSeq`, plus `* FETCH` for every message whose state changed since then.
+ *  No client-side UID diffing, no tombstones — the server tells you the
+ *  authoritative deletions. */
+export interface QresyncParams {
+    uidValidity: number;
+    modSeq: number;
+    knownUids?: string;
+}
+/** Result of a QRESYNC-enabled SELECT. The caller drains `vanishedUids`
+ *  (delete from local store), processes any FETCH responses (upsert state
+ *  changes), and saves the new `highestModSeq` for the next resync. */
+export interface SelectResult extends MailboxInfo {
+    vanishedUids: number[];
+    /** 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. */
+    uidValidityChanged: boolean;
 }
 export declare class NativeImapClient {
     private transport;
@@ -116,7 +148,21 @@ export declare class NativeImapClient {
     getCapabilities(): Set<string>;
     private parseCapabilities;
     logout(): Promise<void>;
-    select(mailbox: string): Promise<MailboxInfo>;
+    /** SELECT a mailbox. Optional QRESYNC params trigger RFC 7162 fast resync —
+     *  on a re-visit the server replies with `* VANISHED (EARLIER) <uids>` for
+     *  every UID expunged since the caller's last `modSeq`, plus `* FETCH`
+     *  for every state change since then. The caller must have called
+     *  `enable(["QRESYNC"])` once on the session for this to take effect.
+     *  Returns a `SelectResult` rather than a bare `MailboxInfo` so VANISHED
+     *  is delivered to the caller. The result is upcast-compatible with
+     *  `MailboxInfo` for code paths that don't care about VANISHED. */
+    select(mailbox: string, qresync?: QresyncParams): Promise<SelectResult>;
+    /** RFC 5161 ENABLE. Activates an extension for the rest of the session.
+     *  QRESYNC requires this once before any SELECT for VANISHED responses
+     *  to be emitted. Capability-gate at the caller — emitting ENABLE for
+     *  an unadvertised extension is a no-op on compliant servers but spams
+     *  the response stream. */
+    enable(extensions: string[]): Promise<Set<string>>;
     examine(mailbox: string): Promise<MailboxInfo>;
     /** Close the currently selected mailbox */
     closeMailbox(): Promise<void>;

package/imap-native.js

@@ -251,14 +251,26 @@ export class NativeImapClient {
         this._connected = false;
     }
     // ── Mailbox Operations ──
-    async select(mailbox) {
+    /** SELECT a mailbox. Optional QRESYNC params trigger RFC 7162 fast resync —
+     *  on a re-visit the server replies with `* VANISHED (EARLIER) <uids>` for
+     *  every UID expunged since the caller's last `modSeq`, plus `* FETCH`
+     *  for every state change since then. The caller must have called
+     *  `enable(["QRESYNC"])` once on the session for this to take effect.
+     *  Returns a `SelectResult` rather than a bare `MailboxInfo` so VANISHED
+     *  is delivered to the caller. The result is upcast-compatible with
+     *  `MailboxInfo` for code paths that don't care about VANISHED. */
+    async select(mailbox, qresync) {
         const tag = proto.nextTag();
-        const responses = await this.sendCommand(tag, proto.selectCommand(tag, mailbox));
+        const responses = await this.sendCommand(tag, proto.selectCommand(tag, mailbox, qresync));
         const tagged = responses.find(r => r.tag === tag);
         if (!tagged || tagged.type !== "OK") {
             throw new Error(`SELECT ${mailbox} failed: ${tagged?.text || "unknown"}`);
         }
-        // Parse mailbox info from untagged responses
+        // Reset transient fields each SELECT so a stale value from a previous
+        // mailbox doesn't leak into the new one.
+        this.mailboxInfo.highestModSeq = undefined;
+        const vanishedUids = [];
+        const priorUidValidity = qresync?.uidValidity;
         for (const r of responses) {
             if (r.tag !== "*")
                 continue;
@@ -281,10 +293,50 @@ export class NativeImapClient {
                 const permMatch = r.text.match(/PERMANENTFLAGS\s+\(([^)]*)\)/i);
                 if (permMatch)
                     this.mailboxInfo.permanentFlags = permMatch[1].split(/\s+/).filter(Boolean);
+                const modSeqMatch = r.text.match(/HIGHESTMODSEQ\s+(\d+)/i);
+                if (modSeqMatch)
+                    this.mailboxInfo.highestModSeq = parseInt(modSeqMatch[1]);
+            }
+            else if (r.type === "VANISHED") {
+                // `* VANISHED (EARLIER) 1:5,8,12` or `* VANISHED 1:5,8,12` —
+                // strip the optional `(EARLIER)` modifier and expand the UID
+                // set. EARLIER means "deleted before your last sync", which
+                // is the QRESYNC case; without it, the message just vanished
+                // mid-session (post-EXPUNGE on another client).
+                const text = r.text.replace(/^\(EARLIER\)\s*/i, "").trim();
+                for (const uid of proto.parseUidSet(text))
+                    vanishedUids.push(uid);
             }
         }
         this.selectedMailbox = mailbox;
-        return { ...this.mailboxInfo };
+        const uidValidityChanged = priorUidValidity !== undefined
+            && this.mailboxInfo.uidValidity !== priorUidValidity;
+        return {
+            ...this.mailboxInfo,
+            vanishedUids,
+            uidValidityChanged,
+        };
+    }
+    /** RFC 5161 ENABLE. Activates an extension for the rest of the session.
+     *  QRESYNC requires this once before any SELECT for VANISHED responses
+     *  to be emitted. Capability-gate at the caller — emitting ENABLE for
+     *  an unadvertised extension is a no-op on compliant servers but spams
+     *  the response stream. */
+    async enable(extensions) {
+        const tag = proto.nextTag();
+        const responses = await this.sendCommand(tag, proto.enableCommand(tag, extensions));
+        const tagged = responses.find(r => r.tag === tag);
+        if (!tagged || tagged.type !== "OK") {
+            throw new Error(`ENABLE ${extensions.join(" ")} failed: ${tagged?.text || "unknown"}`);
+        }
+        const enabled = new Set();
+        for (const r of responses) {
+            if (r.tag === "*" && r.type === "ENABLED") {
+                for (const ext of r.text.split(/\s+/).filter(Boolean))
+                    enabled.add(ext.toUpperCase());
+            }
+        }
+        return enabled;
     }
     async examine(mailbox) {
         const tag = proto.nextTag();
@@ -1284,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/imap-protocol.d.ts

@@ -71,8 +71,26 @@ export declare function loginCommand(tag: string, user: string, pass: string): s
 export declare function xoauth2Command(tag: string, user: string, token: string): string;
 /** Build LIST command */
 export declare function listCommand(tag: string, ref?: string, pattern?: string): string;
-/** Build SELECT command */
-export declare function selectCommand(tag: string, mailbox: string): string;
+/** Build SELECT command. Optional `qresync` triggers RFC 7162 fast resync:
+ *  the server emits `* VANISHED (EARLIER) <uid-set>` for every UID expunged
+ *  since `modSeq` and `* FETCH` for every state change since then, in lieu
+ *  of the caller having to diff UID sets. Capability-gated by caller;
+ *  requires `ENABLE QRESYNC` already issued on the session. */
+export declare function selectCommand(tag: string, mailbox: string, qresync?: {
+    uidValidity: number;
+    modSeq: number;
+    knownUids?: string;
+}): string;
+/** Build ENABLE command per RFC 5161. Common extensions to enable: QRESYNC,
+ *  CONDSTORE, UTF8=ACCEPT. Must be issued before any SELECT for the
+ *  extension to take effect on the session. */
+export declare function enableCommand(tag: string, extensions: string[]): string;
+/** Expand an RFC 3501 UID set (e.g. `"1:5,8,12,20:*"`) into a flat number
+ *  list. Does NOT resolve `*` — caller passes a known upper bound only
+ *  when it has one; here `*` is treated as a sentinel and skipped so the
+ *  call site can decide what to do (typically: ignore — VANISHED never
+ *  emits `*` because that would be open-ended). */
+export declare function parseUidSet(set: string): number[];
 /** Build EXAMINE command (read-only SELECT) */
 export declare function examineCommand(tag: string, mailbox: string): string;
 /** Build STATUS command */

package/imap-protocol.js

@@ -32,9 +32,52 @@ export function xoauth2Command(tag, user, token) {
 export function listCommand(tag, ref = '""', pattern = '"*"') {
     return buildCommand(tag, `LIST ${ref} ${pattern}`);
 }
-/** Build SELECT command */
-export function selectCommand(tag, mailbox) {
-    return buildCommand(tag, `SELECT ${quoteMailbox(mailbox)}`);
+/** Build SELECT command. Optional `qresync` triggers RFC 7162 fast resync:
+ *  the server emits `* VANISHED (EARLIER) <uid-set>` for every UID expunged
+ *  since `modSeq` and `* FETCH` for every state change since then, in lieu
+ *  of the caller having to diff UID sets. Capability-gated by caller;
+ *  requires `ENABLE QRESYNC` already issued on the session. */
+export function selectCommand(tag, mailbox, qresync) {
+    if (!qresync)
+        return buildCommand(tag, `SELECT ${quoteMailbox(mailbox)}`);
+    let params = `${qresync.uidValidity} ${qresync.modSeq}`;
+    if (qresync.knownUids)
+        params += ` ${qresync.knownUids}`;
+    return buildCommand(tag, `SELECT ${quoteMailbox(mailbox)} (QRESYNC (${params}))`);
+}
+/** Build ENABLE command per RFC 5161. Common extensions to enable: QRESYNC,
+ *  CONDSTORE, UTF8=ACCEPT. Must be issued before any SELECT for the
+ *  extension to take effect on the session. */
+export function enableCommand(tag, extensions) {
+    return buildCommand(tag, `ENABLE ${extensions.join(" ")}`);
+}
+/** Expand an RFC 3501 UID set (e.g. `"1:5,8,12,20:*"`) into a flat number
+ *  list. Does NOT resolve `*` — caller passes a known upper bound only
+ *  when it has one; here `*` is treated as a sentinel and skipped so the
+ *  call site can decide what to do (typically: ignore — VANISHED never
+ *  emits `*` because that would be open-ended). */
+export function parseUidSet(set) {
+    const out = [];
+    for (const part of set.split(",")) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const range = trimmed.split(":");
+        if (range.length === 1) {
+            const n = parseInt(range[0], 10);
+            if (Number.isFinite(n))
+                out.push(n);
+        }
+        else if (range.length === 2) {
+            const lo = parseInt(range[0], 10);
+            const hi = range[1] === "*" ? lo : parseInt(range[1], 10);
+            if (!Number.isFinite(lo) || !Number.isFinite(hi) || hi < lo)
+                continue;
+            for (let u = lo; u <= hi; u++)
+                out.push(u);
+        }
+    }
+    return out;
 }
 /** Build EXAMINE command (read-only SELECT) */
 export function examineCommand(tag, mailbox) {

package/package.json

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