@bobfrankston/iflow-direct 0.1.39 → 0.1.40

package/imap-compat.d.ts

@@ -7,6 +7,7 @@ import { type NativeFolder } from "./imap-native.js";
 import { FetchedMessage } from "./fetched-message.js";
 import type { ImapClientConfig } from "./types.js";
 import type { TransportFactory } from "./transport.js";
+import type * as proto from "./imap-protocol.js";
 /** Special folder detection result */
 export interface SpecialFolders {
     inbox?: string;
@@ -102,8 +103,18 @@ export declare class CompatImapClient {
     createmailbox(name: string): Promise<void>;
     /** Append a message to a mailbox */
     appendMessage(mailbox: string, message: string | Uint8Array, flags?: string[]): Promise<number | null>;
-    /** Watch a mailbox for new messages (IDLE) */
-    watchMailbox(mailbox: string, onNew: (count: number) => void): Promise<() => Promise<void>>;
+    /** Cached CAPABILITY set parsed at connect/login. Callers gate
+     *  optional features (NOTIFY, QRESYNC, MOVE, ...) on this. */
+    getCapabilities(): Set<string>;
+    /** 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
+     *  for each. Capability check is the caller's responsibility; pass
+     *  notifySpec only when `getCapabilities().has("NOTIFY")`. */
+    watchMailbox(mailbox: string, onNew: (count: number) => void, opts?: {
+        notifySpec?: string;
+        onMailboxStatus?: (mailbox: string, data: proto.StatusData) => void;
+    }): Promise<() => Promise<void>>;
     /** Copy a message to another server (cross-account) */
     moveMessageToServer(msg: any, fromMailbox: string, targetClient: CompatImapClient, toMailbox: string): Promise<void>;
     /** Rename a mailbox (via native access) */

package/imap-compat.js

@@ -274,10 +274,23 @@ export class CompatImapClient {
         const data = typeof message === "string" ? message : new TextDecoder().decode(message);
         return this.native.appendMessage(mailbox, data, flags);
     }
-    /** Watch a mailbox for new messages (IDLE) */
-    async watchMailbox(mailbox, onNew) {
+    /** Cached CAPABILITY set parsed at connect/login. Callers gate
+     *  optional features (NOTIFY, QRESYNC, MOVE, ...) on this. */
+    getCapabilities() {
+        return this.native.getCapabilities();
+    }
+    /** 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
+     *  for each. Capability check is the caller's responsibility; pass
+     *  notifySpec only when `getCapabilities().has("NOTIFY")`. */
+    async watchMailbox(mailbox, onNew, opts) {
         await this.ensureConnected();
         await this.native.select(mailbox);
+        if (opts?.onMailboxStatus)
+            this.native.onMailboxStatus = opts.onMailboxStatus;
+        if (opts?.notifySpec)
+            await this.native.notify(opts.notifySpec);
         return this.native.startIdle(onNew);
     }
     /** Copy a message to another server (cross-account) */

package/imap-native.d.ts

@@ -77,6 +77,11 @@ export declare class NativeImapClient {
     private idleTag;
     private idleCallback;
     private idleRefreshTimer;
+    /** RFC 5465 NOTIFY: fires on unsolicited STATUS responses for non-selected
+     *  mailboxes (the server pushes these when the client has issued NOTIFY
+     *  SET with a PERSONAL group). Distinct from `idleCallback` which only
+     *  fires for EXISTS on the currently-selected mailbox. */
+    onMailboxStatus: ((mailbox: string, data: proto.StatusData) => void) | null;
     /** Set by startIdle's stop closure so auto-suspend knows not to resume after a command finishes. */
     private idleStopped;
     private verbose;
@@ -104,6 +109,11 @@ export declare class NativeImapClient {
     private authenticate;
     private starttls;
     capability(): Promise<Set<string>>;
+    /** Return the cached CAPABILITY set parsed at connect/login time. Callers
+     *  use this to gate optional code paths (NOTIFY, QRESYNC, MOVE, etc.)
+     *  without re-issuing CAPABILITY. Returns a defensive copy so callers
+     *  can't mutate internal state. */
+    getCapabilities(): Set<string>;
     private parseCapabilities;
     logout(): Promise<void>;
     select(mailbox: string): Promise<MailboxInfo>;
@@ -179,6 +189,14 @@ export declare class NativeImapClient {
     expunge(): Promise<void>;
     /** Append a message to a mailbox */
     appendMessage(mailbox: string, message: string | Uint8Array, flags?: string[]): Promise<number | null>;
+    /** Issue NOTIFY SET so the server starts pushing unsolicited STATUS
+     *  responses for the mailboxes named in `spec` (beyond the currently
+     *  selected one). Capability gated — callers must check
+     *  `getCapabilities().has("NOTIFY")` before calling. Set
+     *  `onMailboxStatus` before issuing if you want to react. Issue AFTER
+     *  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): Promise<() => Promise<void>>;
     /**
      * If IDLE is currently active, send DONE and wait for its tagged OK so the

package/imap-native.js

@@ -40,6 +40,11 @@ export class NativeImapClient {
     idleTag = null;
     idleCallback = 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
+     *  SET with a PERSONAL group). Distinct from `idleCallback` which only
+     *  fires for EXISTS on the currently-selected mailbox. */
+    onMailboxStatus = null;
     /** Set by startIdle's stop closure so auto-suspend knows not to resume after a command finishes. */
     idleStopped = true;
     verbose;
@@ -224,6 +229,13 @@ export class NativeImapClient {
         }
         return this.capabilities;
     }
+    /** Return the cached CAPABILITY set parsed at connect/login time. Callers
+     *  use this to gate optional code paths (NOTIFY, QRESYNC, MOVE, etc.)
+     *  without re-issuing CAPABILITY. Returns a defensive copy so callers
+     *  can't mutate internal state. */
+    getCapabilities() {
+        return new Set(this.capabilities);
+    }
     parseCapabilities(text) {
         const caps = text.replace(/^CAPABILITY\s*/i, "").split(/\s+/);
         this.capabilities.clear();
@@ -623,6 +635,22 @@ export class NativeImapClient {
         const uidMatch = tagged.text.match(/APPENDUID\s+\d+\s+(\d+)/i);
         return uidMatch ? parseInt(uidMatch[1]) : null;
     }
+    // ── NOTIFY (RFC 5465) ──
+    /** Issue NOTIFY SET so the server starts pushing unsolicited STATUS
+     *  responses for the mailboxes named in `spec` (beyond the currently
+     *  selected one). Capability gated — callers must check
+     *  `getCapabilities().has("NOTIFY")` before calling. Set
+     *  `onMailboxStatus` before issuing if you want to react. Issue AFTER
+     *  SELECT and BEFORE startIdle — the server holds the spec for the
+     *  lifetime of the connection. */
+    async notify(spec) {
+        const tag = proto.nextTag();
+        const responses = await this.sendCommand(tag, proto.notifyCommand(tag, spec));
+        const tagged = responses.find(r => r.tag === tag);
+        if (!tagged || tagged.type !== "OK") {
+            throw new Error(`NOTIFY SET failed: ${tagged?.text || "unknown"}`);
+        }
+    }
     // ── IDLE ──
     async startIdle(onNewMail) {
         this.idleCallback = onNewMail;
@@ -1156,6 +1184,26 @@ export class NativeImapClient {
                 }
                 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
+            // callback when IDLE is active — a STATUS response outside IDLE
+            // is the result of a direct STATUS command and belongs to the
+            // pending command's response set (the fall-through below).
+            if (this.idleTag && resp.tag === "*" && resp.type === "STATUS" && this.onMailboxStatus) {
+                const parsed = proto.parseStatusResponseFull(resp.text);
+                if (parsed) {
+                    try {
+                        this.onMailboxStatus(parsed.mailbox, parsed.data);
+                    }
+                    catch (err) {
+                        if (this.verbose)
+                            console.error(`  [imap] onMailboxStatus threw: ${err.message}`);
+                    }
+                    continue;
+                }
+                // Parse failed — fall through so the response isn't silently dropped.
+            }
             // Collect untagged responses for the pending command
             if (resp.tag === "*" && this.pendingCommand) {
                 this.pendingCommand.responses.push(resp);

package/imap-protocol.d.ts

@@ -95,6 +95,13 @@ export declare function moveCommand(tag: string, uid: number, destination: strin
 export declare function appendCommand(tag: string, mailbox: string, flags: string[], size: number): string;
 /** Build IDLE command */
 export declare function idleCommand(tag: string): string;
+/** Build NOTIFY SET command (RFC 5465). `spec` is the full event group list,
+ *  e.g. "(SELECTED (MessageNew MessageExpunge FlagChange)) (PERSONAL
+ *  (MessageNew MessageExpunge FlagChange MailboxName))" — the server then
+ *  pushes unsolicited STATUS responses for non-selected mailboxes in the
+ *  spec while the connection is idle. Capability gated: only issue when
+ *  CAPABILITY response contains NOTIFY. */
+export declare function notifyCommand(tag: string, spec: string): string;
 /** Build DONE command (ends IDLE) */
 export declare function doneCommand(): string;
 /** Build STARTTLS command */
@@ -117,6 +124,14 @@ export declare function parseResponseLine(line: string): ImapResponse;
 export declare function parseListResponse(text: string): ListData | null;
 /** Parse STATUS response: * STATUS "mailbox" (MESSAGES n UIDNEXT n ...) */
 export declare function parseStatusResponse(text: string): StatusData | null;
+/** Parse a STATUS response keeping the mailbox name. Used by NOTIFY's
+ *  unsolicited STATUS pushes where the mailbox identifies which folder
+ *  changed — `parseStatusResponse` discards that. Mailbox may be quoted
+ *  ("Sent") or atom-shaped (Sent); the regex handles both. */
+export declare function parseStatusResponseFull(text: string): {
+    mailbox: string;
+    data: StatusData;
+} | null;
 /** Parse UID SEARCH response: * SEARCH 1 2 3 4 5 */
 export declare function parseSearchResponse(text: string): number[];
 /** Parse FLAGS from a FETCH or SELECT response */

package/imap-protocol.js

@@ -79,6 +79,15 @@ export function appendCommand(tag, mailbox, flags, size) {
 export function idleCommand(tag) {
     return buildCommand(tag, "IDLE");
 }
+/** Build NOTIFY SET command (RFC 5465). `spec` is the full event group list,
+ *  e.g. "(SELECTED (MessageNew MessageExpunge FlagChange)) (PERSONAL
+ *  (MessageNew MessageExpunge FlagChange MailboxName))" — the server then
+ *  pushes unsolicited STATUS responses for non-selected mailboxes in the
+ *  spec while the connection is idle. Capability gated: only issue when
+ *  CAPABILITY response contains NOTIFY. */
+export function notifyCommand(tag, spec) {
+    return buildCommand(tag, `NOTIFY SET ${spec}`);
+}
 /** Build DONE command (ends IDLE) */
 export function doneCommand() {
     return "DONE\r\n";
@@ -182,6 +191,34 @@ export function parseStatusResponse(text) {
     }
     return data;
 }
+/** Parse a STATUS response keeping the mailbox name. Used by NOTIFY's
+ *  unsolicited STATUS pushes where the mailbox identifies which folder
+ *  changed — `parseStatusResponse` discards that. Mailbox may be quoted
+ *  ("Sent") or atom-shaped (Sent); the regex handles both. */
+export function parseStatusResponseFull(text) {
+    // Match: "quoted name" (data)   OR   atomname (data)
+    const m = text.match(/^"((?:[^"\\]|\\.)*)"\s*\((.*)\)\s*$/) || text.match(/^(\S+)\s*\((.*)\)\s*$/);
+    if (!m)
+        return null;
+    const mailbox = m[1].replace(/\\(.)/g, "$1");
+    const data = {};
+    const pairs = m[2].split(/\s+/);
+    for (let i = 0; i < pairs.length - 1; i += 2) {
+        const key = pairs[i].toUpperCase();
+        const val = parseInt(pairs[i + 1]);
+        if (key === "MESSAGES")
+            data.messages = val;
+        else if (key === "RECENT")
+            data.recent = val;
+        else if (key === "UIDNEXT")
+            data.uidNext = val;
+        else if (key === "UIDVALIDITY")
+            data.uidValidity = val;
+        else if (key === "UNSEEN")
+            data.unseen = val;
+    }
+    return { mailbox, data };
+}
 /** Parse UID SEARCH response: * SEARCH 1 2 3 4 5 */
 export function parseSearchResponse(text) {
     if (!text.trim())

package/package.json

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