@lazyneoaz/metachat 5.1.0 → 5.1.2

package/dist/index.d.mts

@@ -1154,7 +1154,7 @@ interface RealtimeHealthState {
  */
 declare class RealtimeHealth {
     private now;
-    private frames;
+    private frameCount;
     private lastFrameAt;
     private connectedAt;
     private probes;
@@ -1175,15 +1175,19 @@ declare class RealtimeHealth {
     /** Record an active ping being sent. */
     notePing(): void;
     sinceLastFrame(): number;
+    /** Total inbound packets observed on this connection generation. */
+    get frames(): number;
     /**
      * Decide what to do about the current socket.
      *
      * - `disconnected` — the transport already knows it is down; reconnect.
-     * - `dead` — connected on paper, silent well past the window, and repeated
-     *   pings raised no traffic at all; reconnect.
-     * - `suspect` — silent past the window but a ping was only just sent; wait.
+     * - `dead` — connected on paper and silent past the window; the supervisor
+     *   runs a round-trip probe and recycles it only if the probe fails.
      * - `quiet` — silent but inside the window; normal.
      * - `healthy` — recent traffic.
+     *
+     * Silence alone is never proof of death: an idle-but-healthy socket is
+     * frame-silent for hours. The probe is what distinguishes the two.
      */
     verdict(connected: boolean): RealtimeHealthState["verdict"];
     /** A snapshot for diagnostics. */
@@ -1196,8 +1200,12 @@ interface RealtimeSupervisorOptions {
     intervalMs?: number;
     /** Ask the transport to reconnect (fresh socket) — must be idempotent. */
     reconnect: (reason: string) => void;
-    /** Send an MQTT ping. Return false if it could not be sent. */
-    ping?: () => boolean;
+    /**
+     * Active liveness probe. Resolve true only when the broker's reply was
+     * observed (e.g. a PINGRESP or app-level round-trip). Returning true marks
+     * the socket alive; false allows it to be recycled.
+     */
+    ping?: () => boolean | Promise<boolean>;
     /** Whether the transport currently reports connected. */
     isConnected: () => boolean;
     /** Observe verdict changes (logging). */
@@ -1216,7 +1224,7 @@ interface RealtimeSupervisorOptions {
 declare function startRealtimeSupervisor(options: RealtimeSupervisorOptions): {
     health: RealtimeHealth;
     stop: () => void;
-    checkNow: () => RealtimeHealthState;
+    checkNow: () => Promise<RealtimeHealthState>;
 };
 
 /** Extract the `CurrentUserInitialData` object from a profile HTML document. */
@@ -1241,13 +1249,7 @@ interface AcquireResult {
     /** Number of cookies written into the jar. */
     loaded: number;
 }
-/**
- * Acquire session cookies into `jar`.
- *
- * Accepts an appState array, a `;`-joined cookie string, or email+password
- * credentials. Throws only when *no* usable source was provided — an individual
- * bad cookie never fails the whole load.
- */
+
 declare function acquireCookies(jar: any, credentials: LoginCredentials$1, globalOptions: LoginOptions$1): Promise<AcquireResult>;
 
 interface UploadedAttachment {
@@ -1276,6 +1278,11 @@ declare function normalizeReaction(value: unknown, options?: {
 /**
  * Facebook "non-critical" errors (e.g. 1357004) are retryable and must not be
  * treated as auth failures or checkpoints.
+ *
+ * `1357001` ("Facebook blocked the login") and `1357031` (document token
+ * invalid) are deliberately excluded: they mean the session is dead or the
+ * tokens are stale, so retrying the same call hides a real problem instead of
+ * repairing it.
  */
 declare function isNonCriticalError(value: any): boolean;
 declare function retryOnNonCritical<T = any>(operation: () => Promise<T>, refresh: () => void | Promise<void>): Promise<T>;

package/dist/index.d.ts

@@ -1154,7 +1154,7 @@ interface RealtimeHealthState {
  */
 declare class RealtimeHealth {
     private now;
-    private frames;
+    private frameCount;
     private lastFrameAt;
     private connectedAt;
     private probes;
@@ -1175,15 +1175,19 @@ declare class RealtimeHealth {
     /** Record an active ping being sent. */
     notePing(): void;
     sinceLastFrame(): number;
+    /** Total inbound packets observed on this connection generation. */
+    get frames(): number;
     /**
      * Decide what to do about the current socket.
      *
      * - `disconnected` — the transport already knows it is down; reconnect.
-     * - `dead` — connected on paper, silent well past the window, and repeated
-     *   pings raised no traffic at all; reconnect.
-     * - `suspect` — silent past the window but a ping was only just sent; wait.
+     * - `dead` — connected on paper and silent past the window; the supervisor
+     *   runs a round-trip probe and recycles it only if the probe fails.
      * - `quiet` — silent but inside the window; normal.
      * - `healthy` — recent traffic.
+     *
+     * Silence alone is never proof of death: an idle-but-healthy socket is
+     * frame-silent for hours. The probe is what distinguishes the two.
      */
     verdict(connected: boolean): RealtimeHealthState["verdict"];
     /** A snapshot for diagnostics. */
@@ -1196,8 +1200,12 @@ interface RealtimeSupervisorOptions {
     intervalMs?: number;
     /** Ask the transport to reconnect (fresh socket) — must be idempotent. */
     reconnect: (reason: string) => void;
-    /** Send an MQTT ping. Return false if it could not be sent. */
-    ping?: () => boolean;
+    /**
+     * Active liveness probe. Resolve true only when the broker's reply was
+     * observed (e.g. a PINGRESP or app-level round-trip). Returning true marks
+     * the socket alive; false allows it to be recycled.
+     */
+    ping?: () => boolean | Promise<boolean>;
     /** Whether the transport currently reports connected. */
     isConnected: () => boolean;
     /** Observe verdict changes (logging). */
@@ -1216,7 +1224,7 @@ interface RealtimeSupervisorOptions {
 declare function startRealtimeSupervisor(options: RealtimeSupervisorOptions): {
     health: RealtimeHealth;
     stop: () => void;
-    checkNow: () => RealtimeHealthState;
+    checkNow: () => Promise<RealtimeHealthState>;
 };
 
 /** Extract the `CurrentUserInitialData` object from a profile HTML document. */
@@ -1241,13 +1249,7 @@ interface AcquireResult {
     /** Number of cookies written into the jar. */
     loaded: number;
 }
-/**
- * Acquire session cookies into `jar`.
- *
- * Accepts an appState array, a `;`-joined cookie string, or email+password
- * credentials. Throws only when *no* usable source was provided — an individual
- * bad cookie never fails the whole load.
- */
+
 declare function acquireCookies(jar: any, credentials: LoginCredentials$1, globalOptions: LoginOptions$1): Promise<AcquireResult>;
 
 interface UploadedAttachment {
@@ -1276,6 +1278,11 @@ declare function normalizeReaction(value: unknown, options?: {
 /**
  * Facebook "non-critical" errors (e.g. 1357004) are retryable and must not be
  * treated as auth failures or checkpoints.
+ *
+ * `1357001` ("Facebook blocked the login") and `1357031` (document token
+ * invalid) are deliberately excluded: they mean the session is dead or the
+ * tokens are stale, so retrying the same call hides a real problem instead of
+ * repairing it.
  */
 declare function isNonCriticalError(value: any): boolean;
 declare function retryOnNonCritical<T = any>(operation: () => Promise<T>, refresh: () => void | Promise<void>): Promise<T>;