@bobfrankston/iflow-direct 0.1.65 → 0.1.67

package/imap-compat.d.ts

@@ -166,6 +166,9 @@ export declare class CompatImapClient {
         notifySpec?: string;
         onMailboxStatus?: (mailbox: string, data: proto.StatusData) => void;
         onExpunge?: () => void;
+        /** A flag changed on a message in the watched mailbox — another
+         *  client starred, read or unread something. */
+        onFlagChange?: (seq: number, flags: string[]) => void;
     }): Promise<() => Promise<void>>;
     /** Copy a message to another server (cross-account) */
     moveMessageToServer(msg: any, fromMailbox: string, targetClient: CompatImapClient, toMailbox: string): Promise<void>;

package/imap-compat.js

@@ -340,7 +340,7 @@ export class CompatImapClient {
             this.native.onMailboxStatus = opts.onMailboxStatus;
         if (opts?.notifySpec)
             await this.native.notify(opts.notifySpec);
-        return this.native.startIdle(onNew, opts?.onExpunge);
+        return this.native.startIdle(onNew, opts?.onExpunge, opts?.onFlagChange);
     }
     /** Copy a message to another server (cross-account) */
     async moveMessageToServer(msg, fromMailbox, targetClient, toMailbox) {

package/imap-native.d.ts

@@ -120,6 +120,10 @@ export declare class NativeImapClient {
      *  a server-side deletion in real time instead of waiting for the next
      *  periodic poll. Distinct from `idleCallback` (new mail only). */
     private idleExpungeCallback;
+    /** Fired for an unsolicited FETCH carrying FLAGS while parked in IDLE —
+     *  another client (a phone, Thunderbird, webmail) changed a flag on a
+     *  message in the selected mailbox. */
+    private idleFlagCallback;
     private idleRefreshTimer;
     /** RFC 5465 NOTIFY: fires on unsolicited STATUS responses for non-selected
      *  mailboxes (the server pushes these when the client has issued NOTIFY
@@ -264,7 +268,7 @@ export declare class NativeImapClient {
      *  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, onExpunge?: () => void): Promise<() => Promise<void>>;
+    startIdle(onNewMail: (count: number) => void, onExpunge?: () => void, onFlagChange?: (seq: number, flags: string[]) => void): Promise<() => Promise<void>>;
     /**
      * If IDLE is currently active, send DONE and wait for its tagged OK so the
      * connection is free to accept a new command. Saves the active callback so

package/imap-native.js

@@ -52,6 +52,10 @@ export class NativeImapClient {
      *  a server-side deletion in real time instead of waiting for the next
      *  periodic poll. Distinct from `idleCallback` (new mail only). */
     idleExpungeCallback = null;
+    /** Fired for an unsolicited FETCH carrying FLAGS while parked in IDLE —
+     *  another client (a phone, Thunderbird, webmail) changed a flag on a
+     *  message in the selected mailbox. */
+    idleFlagCallback = 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
@@ -579,7 +583,8 @@ export class NativeImapClient {
         if (uids.length === 0)
             return [];
         uids.reverse(); // Newest first
-        console.log(`  [fetch] ${uids.length} UIDs since ${sinceUid} (newest first)`);
+        if (this.verbose)
+            console.log(`  [fetch] ${uids.length} UIDs since ${sinceUid} (newest first)`);
         if (uids.length <= this.fetchChunkSize) {
             const msgs = await this.fetchMessages(uids.join(","), options);
             if (onChunk)
@@ -613,14 +618,19 @@ export class NativeImapClient {
             before: before || undefined,
         });
         // SEARCH SINCE on Dovecot can take minutes on a cold mailbox while it
-        // (re)builds its date index. Without a "search starting" log, mailx
-        // shows nothing for the entire SEARCH window — the user thinks
-        // nothing is happening. Bracket the SEARCH with logs so the silence
-        // is at least labeled.
+        // (re)builds its date index, and unlabelled silence reads as a hang.
+        // That is what the sendCommand heartbeat is for — "still waiting for
+        // tag N after 30.0s — SEARCH …", unconditional and generic — so this
+        // bracket does not have to fire on every call. It used to: one sync
+        // pass over ~90 folders wrote two lines per folder per cycle, and on
+        // Android every line is an HTTP request to the log server (Bob
+        // 2026-08-29: "are we overlogging"). Verbose keeps it for debugging.
         const t0 = Date.now();
-        console.log(`  [search] SINCE ${since.toISOString().slice(0, 10)}${before ? ` BEFORE ${before.toISOString().slice(0, 10)}` : ""} — running...`);
+        if (this.verbose)
+            console.log(`  [search] SINCE ${since.toISOString().slice(0, 10)}${before ? ` BEFORE ${before.toISOString().slice(0, 10)}` : ""} — running...`);
         const uids = await this.search(criteria);
-        console.log(`  [search] returned ${uids.length} UIDs in ${Date.now() - t0}ms`);
+        if (this.verbose)
+            console.log(`  [search] returned ${uids.length} UIDs in ${Date.now() - t0}ms`);
         if (uids.length === 0)
             return [];
         // Reverse so newest messages (highest UIDs) come first
@@ -639,7 +649,8 @@ export class NativeImapClient {
             // without spamming. The first-chunk log proves the fetch is alive
             // even when subsequent chunks are slow.
             if (chunkIndex === 1 || chunkIndex % 5 === 0) {
-                console.log(`  [fetch] ${allMessages.length}/${uids.length} messages (chunk ${chunkIndex})`);
+                if (this.verbose)
+                    console.log(`  [fetch] ${allMessages.length}/${uids.length} messages (chunk ${chunkIndex})`);
             }
             if (onChunk)
                 onChunk(msgs);
@@ -647,7 +658,8 @@ export class NativeImapClient {
             if (chunkSize < this.fetchChunkSizeMax)
                 chunkSize = Math.min(chunkSize * 4, this.fetchChunkSizeMax);
         }
-        console.log(`  [fetch] done — ${allMessages.length} messages in ${Date.now() - t0}ms`);
+        if (this.verbose)
+            console.log(`  [fetch] done — ${allMessages.length} messages in ${Date.now() - t0}ms`);
         return allMessages;
     }
     /** Fetch the most recent N messages by sequence number — avoids
@@ -663,7 +675,8 @@ export class NativeImapClient {
         const start = Math.max(1, exists - n + 1);
         const range = `${start}:${exists}`;
         const t0 = Date.now();
-        console.log(`  [fetch-latest] ${this.selectedMailbox || "?"}: sequence ${range} (${Math.min(n, exists)} most recent of ${exists})`);
+        if (this.verbose)
+            console.log(`  [fetch-latest] ${this.selectedMailbox || "?"}: sequence ${range} (${Math.min(n, exists)} most recent of ${exists})`);
         const items = ["UID", "FLAGS", "ENVELOPE", "RFC822.SIZE", "INTERNALDATE", "BODY.PEEK[HEADER]"];
         if (options.source)
             items.push("BODY.PEEK[]");
@@ -694,7 +707,8 @@ export class NativeImapClient {
         // Reverse so newest-first matches fetchByDate ordering — caller code
         // (mailx) expects that ordering when computing highestUid windows.
         streamed.reverse();
-        console.log(`  [fetch-latest] done — ${streamed.length} messages in ${Date.now() - t0}ms`);
+        if (this.verbose)
+            console.log(`  [fetch-latest] done — ${streamed.length} messages in ${Date.now() - t0}ms`);
         return streamed;
     }
     /** Fetch a single message by UID */
@@ -817,9 +831,10 @@ export class NativeImapClient {
         }
     }
     // ── IDLE ──
-    async startIdle(onNewMail, onExpunge) {
+    async startIdle(onNewMail, onExpunge, onFlagChange) {
         this.idleCallback = onNewMail;
         this.idleExpungeCallback = onExpunge ?? null;
+        this.idleFlagCallback = onFlagChange ?? null;
         this.idleStopped = false;
         const beginIdleCycle = async () => {
             const tag = proto.nextTag();
@@ -1416,6 +1431,27 @@ export class NativeImapClient {
                     this.idleExpungeCallback();
                 continue;
             }
+            // A flag changed in the SELECTED mailbox: the server sends an
+            // unsolicited "* 1234 FETCH (FLAGS (\Seen \Flagged))" — this is
+            // how starring a message on a phone reaches another client. It fell
+            // through here and was dropped, so the desktop only learned about
+            // it on its next periodic sync of that folder: measured on Bob's
+            // own log, a median of 5 minutes and up to 20 (2026-08-29).
+            if (this.idleTag && resp.tag === "*" && resp.type === "FETCH" && /FLAGS\s*\(/i.test(resp.text)) {
+                if (this.idleFlagCallback) {
+                    const seq = parseInt(resp.text, 10);
+                    const inner = resp.text.match(/FLAGS\s*\(([^)]*)\)/i)?.[1] || "";
+                    const flags = inner.split(/\s+/).filter(Boolean);
+                    try {
+                        this.idleFlagCallback(Number.isFinite(seq) ? seq : 0, flags);
+                    }
+                    catch (err) {
+                        if (this.verbose)
+                            console.error(`  [imap] onFlagChange threw: ${err.message}`);
+                    }
+                }
+                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

package/package.json

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