@bobfrankston/iflow-direct 0.1.64 → 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/imap-protocol.js

@@ -384,7 +384,16 @@ function decodeImapString(s) {
         return "";
     // RFC 2047 §6.2: whitespace between adjacent encoded-words must be ignored
     const unfolded = s.replace(/\?=\s+=\?/g, "?==?");
-    return unfolded.replace(/=\?([^?]+)\?([BQ])\?([^?]+)\?=/gi, (_match, charset, encoding, text) => {
+    // Some mailers FOLD INSIDE an encoded-word, stranding the closing `?=` on
+    // the next line ("=?utf-8?Q?…_has_Shipped\r\n\t?="). RFC 2047 forbids it,
+    // but a JavaMail/hybris sender does it on every order mail in Bob's
+    // archive; the unterminated word then matched nothing at all and the raw
+    // `=?utf-8?Q?=EF=BB=BFYour_Order_has_Shipped` became the subject line.
+    // `[^?]*?` can't cross a `?`, so this only rejoins words whose terminator
+    // was separated by folding whitespace — a properly closed encoded-word
+    // never has whitespace before its `?=`.
+    const rejoined = unfolded.replace(/(=\?[^?]+\?[BQ]\?[^?]*?)\s+\?=/gi, "$1?=");
+    const decodedWords = rejoined.replace(/=\?([^?]+)\?([BQ])\?([^?]+)\?=/gi, (_match, charset, encoding, text) => {
         try {
             const decoder = decoderFor(charset);
             if (encoding.toUpperCase() === "B") {
@@ -419,6 +428,10 @@ function decodeImapString(s) {
             return encoding.toUpperCase() === "Q" ? text.replace(/_/g, " ") : text;
         }
     });
+    // A BOM inside the encoded-word (`=EF=BB=BF…`) is an encoding marker the
+    // sender leaked into the text, not content — invisible, but it still sorts,
+    // searches and truncates as a character. Drop it.
+    return decodedWords.replace(/\uFEFF/g, ""); // U+FEFF
 }
 /** Tokenize a parenthesized IMAP list (top-level only) */
 function tokenizeParenList(s) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/iflow-direct",
-  "version": "0.1.64",
+  "version": "0.1.67",
   "description": "Direct IMAP client — transport-agnostic, no Node.js dependencies, browser-ready",
   "main": "index.js",
   "types": "index.ts",
@@ -8,7 +8,8 @@
   "scripts": {
     "build": "tsc",
     "watch": "tsc -watch",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "test": "node test/encoded-word.test.mjs"
   },
   "keywords": [
     "imap",

package/test/encoded-word.test.mjs

@@ -0,0 +1,51 @@
+// RFC 2047 encoded-word decoding, exercised through parseEnvelope — an
+// ENVELOPE response is what a client actually stores subjects from.
+//
+// Regression origin (Bob 2026-08-02): a mailman sender labelled its charset
+// `en_US.UTF-8` — a POSIX locale, not a charset. TextDecoder rejected the
+// label, the catch returned the RAW encoded text, and the subject line read
+// `A London_Startup_Is_Selling_Permanent=2C_Painless=2C_=22Stick-On=22…`.
+//
+// Run: node test/encoded-word.test.mjs
+import { parseEnvelope } from "../imap-protocol.js";
+
+// IMAP quoting: only " and \ are escaped. JSON.stringify would ALSO escape the
+// tab a folded header carries, and unquote() would then hand the decoder a
+// literal "t" — the fixture has to look like what the wire really delivers.
+const imapQuote = (s) => `"${s.replace(/([\\"])/g, "\\$1")}"`;
+const env = (subject) =>
+    `("Sat, 1 Aug 2026 22:32:00 -0400" ${imapQuote(subject)} ` +
+    `(("Lauren Weinstein" NIL "lauren" "vortex.com")) NIL NIL ` +
+    `(("NNSquad" NIL "nnsquad" "vortex.com")) NIL NIL NIL "<x@y>")`;
+
+const cases = [
+    // The reported one: POSIX locale as charset, three adjacent encoded-words.
+    ["en_US.UTF-8 locale, adjacent words",
+     "[ NNSquad ] What could go wrong? - A =?en_US.UTF-8?Q?L?= =?en_US.UTF-8?Q?ondon_Startup_Is_Selling_Permanent=2C_Painless=2C_=22Stic?= =?en_US.UTF-8?Q?k-On=22_Tattoos=E2=80=94and?= It Wants to Do Mail Order",
+     "[ NNSquad ] What could go wrong? - A London Startup Is Selling Permanent, Painless, \"Stick-On\" Tattoos—and It Wants to Do Mail Order"],
+    ["plain utf-8 Q", "=?utf-8?Q?caf=C3=A9_r=C3=A9sum=C3=A9?=", "café résumé"],
+    ["utf8 (no hyphen)", "=?utf8?Q?na=C3=AFve?=", "naïve"],
+    ["RFC 2231 language suffix", "=?utf-8*en?Q?hello_world?=", "hello world"],
+    ["iso-8859-1 B", "=?iso-8859-1?B?SmVhbi1S6Q==?=", "Jean-Ré"],
+    ["windows-1252 Q", "=?windows-1252?Q?=93quoted=94?=", "“quoted”"],
+    // Dotted label that is a REAL charset — the locale rule must not mangle it.
+    ["dotted real charset (ansi_x3.4-1968)", "=?ansi_x3.4-1968?Q?plain_ascii?=", "plain ascii"],
+    ["koi8-r B", "=?koi8-r?B?89DBzQ==?=", "Спам"],
+    // Fold INSIDE an encoded-word: the closing ?= sits on the next line, and
+    // the transport's literal handler drops the newline but keeps the leading
+    // whitespace — so the decoder sees "…Shipped\t?=". Also checks the BOM the
+    // sender encoded into the text is not left in the subject.
+    ["terminator folded onto next line", "=?utf-8?Q?=EF=BB=BFYour_Order_has_Shipped\t?=", "Your Order has Shipped"],
+    ["second word terminator folded", "=?UTF-8?Q?=EF=BB=BFThanks!_We_got_your_order_16536?=\t=?UTF-8?Q?3791 ?=", "Thanks! We got your order 165363791"],
+    ["no encoded words", "just a plain subject", "just a plain subject"],
+];
+
+let fail = 0;
+for (const [name, raw, want] of cases) {
+    const got = parseEnvelope(env(raw)).subject;
+    const ok = got === want;
+    if (!ok) fail++;
+    console.log(`${ok ? "✓" : "✗"} ${name}${ok ? "" : `\n    got  ${JSON.stringify(got)}\n    want ${JSON.stringify(want)}`}`);
+}
+console.log(fail ? `\n${fail} FAILED` : `\nall ${cases.length} passed`);
+process.exit(fail ? 1 : 0);