@bobfrankston/iflow-direct 0.1.41 → 0.1.42

package/imap-native.d.ts

@@ -43,6 +43,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 +143,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();

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.42",
   "description": "Direct IMAP client — transport-agnostic, no Node.js dependencies, browser-ready",
   "main": "index.js",
   "types": "index.ts",