@lazyneoaz/metachat 4.0.6 → 4.0.8

package/dist/index.d.mts

@@ -99,6 +99,19 @@ interface LoginOptions$1 {
     warmUp?: boolean;
     /** Alternate foreground/background on a human rhythm to avoid detection. */
     liveness?: boolean;
+    /**
+     * Auto-recovery supervisor. `true` (default) keeps a dead session alive by
+     * refreshing cookies and, when credentials are available, re-logging in.
+     * Pass an options object to tune it, or `false` to disable it.
+     */
+    recovery?: boolean | {
+        intervalMs?: number;
+        failureThreshold?: number;
+        maxRecoveries?: number;
+        noRelogin?: boolean;
+    };
+    /** Write a refreshed appState here on successful recovery (best-effort). */
+    appStatePath?: string;
     logging?: boolean;
     pageID?: string;
     [key: string]: any;
@@ -132,6 +145,8 @@ interface ApiContext$1 {
     fb_dtsg?: string;
     jazoest?: string;
     lsd?: string;
+    /** App-scoped abuse id (`x-asbd-id`) scraped from the current document. */
+    asbdId?: string;
     ttstamp?: string;
     threadTypeCache?: Record<string, boolean>;
     lastMessageTime?: number;
@@ -720,6 +735,16 @@ declare function refreshSessionCookies(ctx: any, defaultFuncs: any, options?: {
 }>;
 /** Detect an auth/document-token failure in a thrown or returned payload. */
 declare function isAuthFailure(value: any): boolean;
+/**
+ * Detect a logged-out document.
+ *
+ * When Facebook invalidates a session it does not always answer with an auth
+ * error code: it serves the login page, or (when the browser/device is still
+ * trusted) the one-tap "Continue as <name>" interstitial. Both look like a
+ * normal `200 text/html`, so a session can silently become useless. Recognising
+ * the document lets the caller re-authenticate instead of limping along.
+ */
+declare function isLoggedOutDocument(html: any): boolean;
 /**
  * Wrap a network operation with one repair-and-retry pass.
  *
@@ -935,9 +960,281 @@ declare function canActProactively(ctx: any): boolean;
 /** Wait until the session is foregrounded and the breaker is closed. */
 declare function awaitProactiveSlot(ctx: any, maxWaitMs?: number): Promise<boolean>;
 
+/**
+ * Long-run auto-recovery ("set and forget").
+ *
+ * The pieces that keep a session alive already exist and are individually
+ * correct: cookie refresh, Comet-token invalidation, the account-safety
+ * breaker, MQTT reconnect backoff, human pacing. What was missing was the
+ * *supervisor* that ties them together — something that notices when the
+ * session has quietly died and does the one useful thing that remains.
+ *
+ * This module adds that supervisor and is deliberately conservative:
+ *
+ *   - It samples health on a slow, jittered cadence (never a hot loop).
+ *   - It first tries the cheap fix: refresh cookies + tokens.
+ *   - Only if the session is still unauthenticated *and* credentials were
+ *     supplied does it attempt a real credential re-login.
+ *   - Every recovery attempt is gated by the safety breaker and a per-session
+ *     attempt budget with exponential backoff, so a genuinely dead account
+ *     cannot turn into a login storm that gets it checkpointed.
+ *   - It reports every state change through a callback, so a bot can log or
+ *     alert instead of failing silently.
+ *
+ * Everything here is pure logic over an injected "runtime" — the network work
+ * is delegated to callbacks the caller supplies. That keeps the module
+ * unit-testable without any network, and means a bug here can only ever
+ * *skip* a recovery, never corrupt a live request.
+ */
+
+type RecoveryPhase = "healthy" | "refreshing" | "recovering" | "relogin" | "cooling" | "stopped";
+interface RecoveryState {
+    phase: RecoveryPhase;
+    /** Total health samples taken. */
+    checks: number;
+    /** Consecutive unhealthy samples. */
+    consecutiveFailures: number;
+    /** Successful auto-heals (cookie refresh or repair) that restored auth. */
+    healCount: number;
+    /** Total recovery attempts made (successful or not), for the budget. */
+    attempts: number;
+    /** Successful full re-logins. */
+    reloginCount: number;
+    /** Recoveries abandoned because the budget/breaker said stop. */
+    givenUp: number;
+    /** ms timestamp of the last successful health confirmation. */
+    lastHealthyAt: number;
+    /** ms until the next scheduled check. */
+    nextCheckMs: number;
+    /** Whether a credential re-login is possible for this session. */
+    canRelogin: boolean;
+    /** Last human-readable detail. */
+    lastDetail?: string;
+}
+/**
+ * The dependency surface the supervisor needs. All network work is behind
+ * these callbacks so the supervisor itself stays pure and testable.
+ */
+interface RecoveryRuntime {
+    ctx: any;
+    /** True when the jar still holds a usable session. Cheap, synchronous. */
+    isAuthenticated: () => boolean;
+    /**
+     * Active server-side liveness check. Distinct from {@link isAuthenticated}:
+     * the jar can still look authenticated locally while Facebook has already
+     * invalidated the session server-side (the "Continue as <name>" page). When
+     * provided, the supervisor trusts this over the cheap local check.
+     */
+    probeLiveness?: () => Promise<boolean>;
+    /** Refresh cookies/tokens in place; resolves to whether auth survived. */
+    refresh: () => Promise<boolean>;
+    /**
+     * Full credential re-login. Must resolve to a fresh appState (array) on
+     * success, or null/throw on failure. Optional: when absent, no re-login is
+     * attempted and the supervisor only reports the dead session.
+     */
+    relogin?: () => Promise<any[] | null>;
+    /**
+     * Whether a credential re-login is actually possible for this session (e.g.
+     * email+password were supplied). Defaults to whether `relogin` is set. This
+     * exists because `relogin` is always provided by the login plumbing, but it
+     * is only *useful* when the caller had credentials.
+     */
+    canRelogin?: boolean;
+    /** Persist a refreshed appState (e.g. write the account file). Optional. */
+    persistAppState?: (appState: any[]) => void;
+    /** Restart the MQTT listener after a recovery. Optional. */
+    restartMqtt?: () => void;
+    /** Observe state transitions (logging/alerting). Optional. */
+    onEvent?: (event: RecoveryEvent) => void;
+}
+interface RecoveryEvent {
+    type: "check" | "unhealthy" | "healed" | "relogin" | "gave-up" | "cooling" | "stopped";
+    detail: string;
+    state: RecoveryState;
+}
+interface RecoveryOptions {
+    /** Base interval between health samples. Jittered ±30% each tick. */
+    intervalMs?: number;
+    /** Consecutive failed checks before the supervisor intervenes. */
+    failureThreshold?: number;
+    /** Max automatic recoveries (heal+relogin) before the supervisor gives up. */
+    maxRecoveries?: number;
+    /** Disable credential re-login even when credentials exist. */
+    noRelogin?: boolean;
+}
+/**
+ * The supervisor. Create with {@link startRecovery} rather than directly.
+ */
+declare class RecoverySupervisor {
+    private runtime;
+    private opts;
+    private timer;
+    private stopped;
+    private running;
+    private state;
+    private backoffMs;
+    constructor(runtime: RecoveryRuntime, options?: RecoveryOptions);
+    /** A point-in-time copy of the supervisor state. */
+    snapshot(): RecoveryState;
+    isRunning(): boolean;
+    /** Start the supervisor. Idempotent. */
+    start(): void;
+    /** Stop the supervisor and clear any pending timer. */
+    stop(): void;
+    /**
+     * Run one health check immediately (used by tests and by `checkNow()`).
+     * Returns the resulting state. Never throws.
+     */
+    checkNow(): Promise<RecoveryState>;
+    private nextCheckAt;
+    private startTimer;
+    private runOnce;
+    private markHealthy;
+    private afterRecovery;
+    private emit;
+}
+/**
+ * Wire a supervisor to a live session.
+ *
+ * @param ctx        session context (mutated with `__recovery`)
+ * @param runtime    the injected dependency surface
+ * @param options    tuning knobs
+ */
+declare function startRecovery(ctx: any, runtime: RecoveryRuntime, options?: RecoveryOptions): RecoverySupervisor;
+
+/**
+ * MQTT connection health.
+ *
+ * A Messenger realtime socket fails in two ways:
+ *
+ *  1. **Loudly** — TCP drop, broker close, auth error. mqtt.js raises `close`
+ *     and the listener reconnects. Easy.
+ *  2. **Silently** — the socket stays "connected" but Facebook has stopped
+ *     routing events to it (a half-open connection, a broker-side idle reap, a
+ *     revoked session). No error is emitted, `client.connected` stays `true`,
+ *     and from the bot's point of view it is online while receiving nothing.
+ *
+ * Case 2 is why bots are traditionally torn down and restarted on a timer:
+ * there was no way to tell a healthy quiet socket from a dead one. This module
+ * provides that signal, so the socket can stay up indefinitely and only ever be
+ * recycled when it is *actually* broken.
+ *
+ * The detector is deliberately conservative — real accounts genuinely go quiet
+ * for long stretches, so it only acts when the socket has been silent for a
+ * long window AND an active ping fails to elicit any traffic.
+ */
+/** No traffic and no pong for this long => the socket is suspect. */
+declare const SILENT_WINDOW_MS: number;
+/** How long to wait for traffic after an active ping before declaring death. */
+declare const PING_GRACE_MS: number;
+interface RealtimeHealthState {
+    /** Whether the transport currently reports itself connected. */
+    connected: boolean;
+    /** ms since the last inbound frame (or since connect when none seen yet). */
+    sinceLastFrameMs: number;
+    /** Total inbound frames observed. */
+    frames: number;
+    /** Completed health probes. */
+    probes: number;
+    /** Times the health check forced a reconnect. */
+    forcedReconnects: number;
+    /** The last determined verdict. */
+    verdict: "healthy" | "quiet" | "suspect" | "dead" | "disconnected";
+}
+/**
+ * Tracks liveness of one realtime connection. Instances are cheap and are
+ * recreated per connection generation by the listener.
+ */
+declare class RealtimeHealth {
+    private now;
+    private frames;
+    private lastFrameAt;
+    private connectedAt;
+    private probes;
+    private forcedReconnects;
+    private lastPingAt;
+    private startedAt;
+    constructor(now?: () => number);
+    /** Record any inbound frame (message, pong, anything from the broker). */
+    noteFrame(): void;
+    /** Record a successful connect. */
+    noteConnected(): void;
+    /** Record that the transport reports itself disconnected. */
+    noteDisconnected(): void;
+    /** Record an active ping being sent. */
+    notePing(): void;
+    sinceLastFrame(): number;
+    /**
+     * Decide what to do about the current socket.
+     *
+     * - `disconnected` — the transport already knows it is down; reconnect.
+     * - `dead` — connected on paper, silent past the window, and a ping raised no
+     *   traffic within the grace period; reconnect.
+     * - `suspect` — silent past the window but a ping was only just sent; wait.
+     * - `quiet` — silent but inside the window; normal.
+     * - `healthy` — recent traffic.
+     */
+    verdict(connected: boolean): RealtimeHealthState["verdict"];
+    /** A snapshot for diagnostics. */
+    state(connected: boolean): RealtimeHealthState;
+    noteProbe(): void;
+    noteForcedReconnect(): void;
+}
+interface RealtimeSupervisorOptions {
+    /** How often to evaluate the socket. Jittered. Default 3 min. */
+    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;
+    /** Whether the transport currently reports connected. */
+    isConnected: () => boolean;
+    /** Observe verdict changes (logging). */
+    onVerdict?: (state: RealtimeHealthState) => void;
+}
+/**
+ * A lightweight supervisor that keeps ONE realtime socket honest: it pings a
+ * long-quiet socket and recycles only a genuinely dead one. It never restarts a
+ * socket that is simply idle, which is what lets the connection live for days.
+ */
+declare function startRealtimeSupervisor(options: RealtimeSupervisorOptions): {
+    health: RealtimeHealth;
+    stop: () => void;
+    checkNow: () => RealtimeHealthState;
+};
+
 /** Extract the `CurrentUserInitialData` object from a profile HTML document. */
 declare function extractCurrentUser(html: any): Record<string, any> | null;
 
+/**
+ * Reusable cookie acquisition.
+ *
+ * `loginHelper` needs this to build the initial jar, and the recovery
+ * supervisor needs the exact same logic to *re-login* a dead session from
+ * stored credentials. Keeping a single implementation means a fix to cookie
+ * handling (domain normalization, Set-Cookie parsing, appState formats) can
+ * never apply to login but not to recovery.
+ *
+ * The function is deliberately narrow: it mutates a cookie jar and reports
+ * what it loaded. It performs no session validation and starts nothing.
+ */
+
+interface AcquireResult {
+    /** How cookies were obtained. */
+    source: "appState" | "credentials" | "appStateString";
+    /** 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>;
+
 type ApiContext = ApiContext$1;
 type ApiInternal = Api;
 type DefaultFuncs = DefaultFuncs$1;
@@ -948,4 +1245,4 @@ declare const _default: typeof login$1 & {
     default: typeof login$1;
 };
 
-export { type API, type AddedStickerPackInfo, type AiTheme, type AnyAttachment, type ApiContext, type ApiInternal, type Attachment, type AudioAttachment, type BrowserProfile, type Callback, type CommentMessage, type CommentResult, type Coordinates, type DefaultFuncs, type EmojiEvent, type Event, type FileAttachment, type GroupNameEvent, type ListenEvent, type LivenessHandle, type LivenessState, type LoginCredentials, type LoginOptions, type Mention, type Message, type MessageID, type MessageObject, type MessageReply, type MusicTag, type MusicTrack, type NicknameEvent, type PhotoAttachment, type Reaction, type SearchMusicOptions, type SearchMusicResult, type ShareAttachment, type ShareResult, type StickerAttachment, type StickerInfo, type StickerPackInfo, type ThreadID, type ThreadInfo, type ThreadThemeEvent, type TypingIndicator, type UnsendMessageEvent, type UserID, type UserInfo, type VideoAttachment, type WarmUpResult, applySetCookie, awaitProactiveSlot, canActProactively, collectSessionCookies, _default as default, defaultBrowserProfile, ensureCometTokens, extractCookies, extractCookiesFromBody, extractCookiesFromJar, extractCookiesFromSetCookie, extractCurrentUser, getFingerprintParams, getHeaders, getWebSocketHeaders, hasAuthenticatedSession, humanDelay, invalidateCometTokens, isAuthFailure, isBreakerOpen, isStaleTokenError, login$1 as login, missingSessionCookies, normalizeBrowserProfile, noteAction, noteAuthFailure, noteCheckpoint, noteRateLimit, paceRequest, publicTypes, randomUserAgent, refreshSessionCookies, repairSession, reserveRequest, resetBreaker, resolveProfile, retryDelay, safetySnapshot, sleep, startLiveness, tripBreaker, warmUpSession, withCometTokens, withSessionRetry };
+export { type API, type AddedStickerPackInfo, type AiTheme, type AnyAttachment, type ApiContext, type ApiInternal, type Attachment, type AudioAttachment, type BrowserProfile, type Callback, type CommentMessage, type CommentResult, type Coordinates, type DefaultFuncs, type EmojiEvent, type Event, type FileAttachment, type GroupNameEvent, type ListenEvent, type LivenessHandle, type LivenessState, type LoginCredentials, type LoginOptions, type Mention, type Message, type MessageID, type MessageObject, type MessageReply, type MusicTag, type MusicTrack, type NicknameEvent, PING_GRACE_MS, type PhotoAttachment, type Reaction, RealtimeHealth, type RealtimeHealthState, type RecoveryEvent, type RecoveryOptions, type RecoveryRuntime, type RecoveryState, RecoverySupervisor, SILENT_WINDOW_MS, type SearchMusicOptions, type SearchMusicResult, type ShareAttachment, type ShareResult, type StickerAttachment, type StickerInfo, type StickerPackInfo, type ThreadID, type ThreadInfo, type ThreadThemeEvent, type TypingIndicator, type UnsendMessageEvent, type UserID, type UserInfo, type VideoAttachment, type WarmUpResult, acquireCookies, applySetCookie, awaitProactiveSlot, canActProactively, collectSessionCookies, _default as default, defaultBrowserProfile, ensureCometTokens, extractCookies, extractCookiesFromBody, extractCookiesFromJar, extractCookiesFromSetCookie, extractCurrentUser, getFingerprintParams, getHeaders, getWebSocketHeaders, hasAuthenticatedSession, humanDelay, invalidateCometTokens, isAuthFailure, isBreakerOpen, isLoggedOutDocument, isStaleTokenError, login$1 as login, missingSessionCookies, normalizeBrowserProfile, noteAction, noteAuthFailure, noteCheckpoint, noteRateLimit, paceRequest, publicTypes, randomUserAgent, refreshSessionCookies, repairSession, reserveRequest, resetBreaker, resolveProfile, retryDelay, safetySnapshot, sleep, startLiveness, startRealtimeSupervisor, startRecovery, tripBreaker, warmUpSession, withCometTokens, withSessionRetry };

package/dist/index.d.ts

@@ -99,6 +99,19 @@ interface LoginOptions$1 {
     warmUp?: boolean;
     /** Alternate foreground/background on a human rhythm to avoid detection. */
     liveness?: boolean;
+    /**
+     * Auto-recovery supervisor. `true` (default) keeps a dead session alive by
+     * refreshing cookies and, when credentials are available, re-logging in.
+     * Pass an options object to tune it, or `false` to disable it.
+     */
+    recovery?: boolean | {
+        intervalMs?: number;
+        failureThreshold?: number;
+        maxRecoveries?: number;
+        noRelogin?: boolean;
+    };
+    /** Write a refreshed appState here on successful recovery (best-effort). */
+    appStatePath?: string;
     logging?: boolean;
     pageID?: string;
     [key: string]: any;
@@ -132,6 +145,8 @@ interface ApiContext$1 {
     fb_dtsg?: string;
     jazoest?: string;
     lsd?: string;
+    /** App-scoped abuse id (`x-asbd-id`) scraped from the current document. */
+    asbdId?: string;
     ttstamp?: string;
     threadTypeCache?: Record<string, boolean>;
     lastMessageTime?: number;
@@ -720,6 +735,16 @@ declare function refreshSessionCookies(ctx: any, defaultFuncs: any, options?: {
 }>;
 /** Detect an auth/document-token failure in a thrown or returned payload. */
 declare function isAuthFailure(value: any): boolean;
+/**
+ * Detect a logged-out document.
+ *
+ * When Facebook invalidates a session it does not always answer with an auth
+ * error code: it serves the login page, or (when the browser/device is still
+ * trusted) the one-tap "Continue as <name>" interstitial. Both look like a
+ * normal `200 text/html`, so a session can silently become useless. Recognising
+ * the document lets the caller re-authenticate instead of limping along.
+ */
+declare function isLoggedOutDocument(html: any): boolean;
 /**
  * Wrap a network operation with one repair-and-retry pass.
  *
@@ -935,9 +960,281 @@ declare function canActProactively(ctx: any): boolean;
 /** Wait until the session is foregrounded and the breaker is closed. */
 declare function awaitProactiveSlot(ctx: any, maxWaitMs?: number): Promise<boolean>;
 
+/**
+ * Long-run auto-recovery ("set and forget").
+ *
+ * The pieces that keep a session alive already exist and are individually
+ * correct: cookie refresh, Comet-token invalidation, the account-safety
+ * breaker, MQTT reconnect backoff, human pacing. What was missing was the
+ * *supervisor* that ties them together — something that notices when the
+ * session has quietly died and does the one useful thing that remains.
+ *
+ * This module adds that supervisor and is deliberately conservative:
+ *
+ *   - It samples health on a slow, jittered cadence (never a hot loop).
+ *   - It first tries the cheap fix: refresh cookies + tokens.
+ *   - Only if the session is still unauthenticated *and* credentials were
+ *     supplied does it attempt a real credential re-login.
+ *   - Every recovery attempt is gated by the safety breaker and a per-session
+ *     attempt budget with exponential backoff, so a genuinely dead account
+ *     cannot turn into a login storm that gets it checkpointed.
+ *   - It reports every state change through a callback, so a bot can log or
+ *     alert instead of failing silently.
+ *
+ * Everything here is pure logic over an injected "runtime" — the network work
+ * is delegated to callbacks the caller supplies. That keeps the module
+ * unit-testable without any network, and means a bug here can only ever
+ * *skip* a recovery, never corrupt a live request.
+ */
+
+type RecoveryPhase = "healthy" | "refreshing" | "recovering" | "relogin" | "cooling" | "stopped";
+interface RecoveryState {
+    phase: RecoveryPhase;
+    /** Total health samples taken. */
+    checks: number;
+    /** Consecutive unhealthy samples. */
+    consecutiveFailures: number;
+    /** Successful auto-heals (cookie refresh or repair) that restored auth. */
+    healCount: number;
+    /** Total recovery attempts made (successful or not), for the budget. */
+    attempts: number;
+    /** Successful full re-logins. */
+    reloginCount: number;
+    /** Recoveries abandoned because the budget/breaker said stop. */
+    givenUp: number;
+    /** ms timestamp of the last successful health confirmation. */
+    lastHealthyAt: number;
+    /** ms until the next scheduled check. */
+    nextCheckMs: number;
+    /** Whether a credential re-login is possible for this session. */
+    canRelogin: boolean;
+    /** Last human-readable detail. */
+    lastDetail?: string;
+}
+/**
+ * The dependency surface the supervisor needs. All network work is behind
+ * these callbacks so the supervisor itself stays pure and testable.
+ */
+interface RecoveryRuntime {
+    ctx: any;
+    /** True when the jar still holds a usable session. Cheap, synchronous. */
+    isAuthenticated: () => boolean;
+    /**
+     * Active server-side liveness check. Distinct from {@link isAuthenticated}:
+     * the jar can still look authenticated locally while Facebook has already
+     * invalidated the session server-side (the "Continue as <name>" page). When
+     * provided, the supervisor trusts this over the cheap local check.
+     */
+    probeLiveness?: () => Promise<boolean>;
+    /** Refresh cookies/tokens in place; resolves to whether auth survived. */
+    refresh: () => Promise<boolean>;
+    /**
+     * Full credential re-login. Must resolve to a fresh appState (array) on
+     * success, or null/throw on failure. Optional: when absent, no re-login is
+     * attempted and the supervisor only reports the dead session.
+     */
+    relogin?: () => Promise<any[] | null>;
+    /**
+     * Whether a credential re-login is actually possible for this session (e.g.
+     * email+password were supplied). Defaults to whether `relogin` is set. This
+     * exists because `relogin` is always provided by the login plumbing, but it
+     * is only *useful* when the caller had credentials.
+     */
+    canRelogin?: boolean;
+    /** Persist a refreshed appState (e.g. write the account file). Optional. */
+    persistAppState?: (appState: any[]) => void;
+    /** Restart the MQTT listener after a recovery. Optional. */
+    restartMqtt?: () => void;
+    /** Observe state transitions (logging/alerting). Optional. */
+    onEvent?: (event: RecoveryEvent) => void;
+}
+interface RecoveryEvent {
+    type: "check" | "unhealthy" | "healed" | "relogin" | "gave-up" | "cooling" | "stopped";
+    detail: string;
+    state: RecoveryState;
+}
+interface RecoveryOptions {
+    /** Base interval between health samples. Jittered ±30% each tick. */
+    intervalMs?: number;
+    /** Consecutive failed checks before the supervisor intervenes. */
+    failureThreshold?: number;
+    /** Max automatic recoveries (heal+relogin) before the supervisor gives up. */
+    maxRecoveries?: number;
+    /** Disable credential re-login even when credentials exist. */
+    noRelogin?: boolean;
+}
+/**
+ * The supervisor. Create with {@link startRecovery} rather than directly.
+ */
+declare class RecoverySupervisor {
+    private runtime;
+    private opts;
+    private timer;
+    private stopped;
+    private running;
+    private state;
+    private backoffMs;
+    constructor(runtime: RecoveryRuntime, options?: RecoveryOptions);
+    /** A point-in-time copy of the supervisor state. */
+    snapshot(): RecoveryState;
+    isRunning(): boolean;
+    /** Start the supervisor. Idempotent. */
+    start(): void;
+    /** Stop the supervisor and clear any pending timer. */
+    stop(): void;
+    /**
+     * Run one health check immediately (used by tests and by `checkNow()`).
+     * Returns the resulting state. Never throws.
+     */
+    checkNow(): Promise<RecoveryState>;
+    private nextCheckAt;
+    private startTimer;
+    private runOnce;
+    private markHealthy;
+    private afterRecovery;
+    private emit;
+}
+/**
+ * Wire a supervisor to a live session.
+ *
+ * @param ctx        session context (mutated with `__recovery`)
+ * @param runtime    the injected dependency surface
+ * @param options    tuning knobs
+ */
+declare function startRecovery(ctx: any, runtime: RecoveryRuntime, options?: RecoveryOptions): RecoverySupervisor;
+
+/**
+ * MQTT connection health.
+ *
+ * A Messenger realtime socket fails in two ways:
+ *
+ *  1. **Loudly** — TCP drop, broker close, auth error. mqtt.js raises `close`
+ *     and the listener reconnects. Easy.
+ *  2. **Silently** — the socket stays "connected" but Facebook has stopped
+ *     routing events to it (a half-open connection, a broker-side idle reap, a
+ *     revoked session). No error is emitted, `client.connected` stays `true`,
+ *     and from the bot's point of view it is online while receiving nothing.
+ *
+ * Case 2 is why bots are traditionally torn down and restarted on a timer:
+ * there was no way to tell a healthy quiet socket from a dead one. This module
+ * provides that signal, so the socket can stay up indefinitely and only ever be
+ * recycled when it is *actually* broken.
+ *
+ * The detector is deliberately conservative — real accounts genuinely go quiet
+ * for long stretches, so it only acts when the socket has been silent for a
+ * long window AND an active ping fails to elicit any traffic.
+ */
+/** No traffic and no pong for this long => the socket is suspect. */
+declare const SILENT_WINDOW_MS: number;
+/** How long to wait for traffic after an active ping before declaring death. */
+declare const PING_GRACE_MS: number;
+interface RealtimeHealthState {
+    /** Whether the transport currently reports itself connected. */
+    connected: boolean;
+    /** ms since the last inbound frame (or since connect when none seen yet). */
+    sinceLastFrameMs: number;
+    /** Total inbound frames observed. */
+    frames: number;
+    /** Completed health probes. */
+    probes: number;
+    /** Times the health check forced a reconnect. */
+    forcedReconnects: number;
+    /** The last determined verdict. */
+    verdict: "healthy" | "quiet" | "suspect" | "dead" | "disconnected";
+}
+/**
+ * Tracks liveness of one realtime connection. Instances are cheap and are
+ * recreated per connection generation by the listener.
+ */
+declare class RealtimeHealth {
+    private now;
+    private frames;
+    private lastFrameAt;
+    private connectedAt;
+    private probes;
+    private forcedReconnects;
+    private lastPingAt;
+    private startedAt;
+    constructor(now?: () => number);
+    /** Record any inbound frame (message, pong, anything from the broker). */
+    noteFrame(): void;
+    /** Record a successful connect. */
+    noteConnected(): void;
+    /** Record that the transport reports itself disconnected. */
+    noteDisconnected(): void;
+    /** Record an active ping being sent. */
+    notePing(): void;
+    sinceLastFrame(): number;
+    /**
+     * Decide what to do about the current socket.
+     *
+     * - `disconnected` — the transport already knows it is down; reconnect.
+     * - `dead` — connected on paper, silent past the window, and a ping raised no
+     *   traffic within the grace period; reconnect.
+     * - `suspect` — silent past the window but a ping was only just sent; wait.
+     * - `quiet` — silent but inside the window; normal.
+     * - `healthy` — recent traffic.
+     */
+    verdict(connected: boolean): RealtimeHealthState["verdict"];
+    /** A snapshot for diagnostics. */
+    state(connected: boolean): RealtimeHealthState;
+    noteProbe(): void;
+    noteForcedReconnect(): void;
+}
+interface RealtimeSupervisorOptions {
+    /** How often to evaluate the socket. Jittered. Default 3 min. */
+    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;
+    /** Whether the transport currently reports connected. */
+    isConnected: () => boolean;
+    /** Observe verdict changes (logging). */
+    onVerdict?: (state: RealtimeHealthState) => void;
+}
+/**
+ * A lightweight supervisor that keeps ONE realtime socket honest: it pings a
+ * long-quiet socket and recycles only a genuinely dead one. It never restarts a
+ * socket that is simply idle, which is what lets the connection live for days.
+ */
+declare function startRealtimeSupervisor(options: RealtimeSupervisorOptions): {
+    health: RealtimeHealth;
+    stop: () => void;
+    checkNow: () => RealtimeHealthState;
+};
+
 /** Extract the `CurrentUserInitialData` object from a profile HTML document. */
 declare function extractCurrentUser(html: any): Record<string, any> | null;
 
+/**
+ * Reusable cookie acquisition.
+ *
+ * `loginHelper` needs this to build the initial jar, and the recovery
+ * supervisor needs the exact same logic to *re-login* a dead session from
+ * stored credentials. Keeping a single implementation means a fix to cookie
+ * handling (domain normalization, Set-Cookie parsing, appState formats) can
+ * never apply to login but not to recovery.
+ *
+ * The function is deliberately narrow: it mutates a cookie jar and reports
+ * what it loaded. It performs no session validation and starts nothing.
+ */
+
+interface AcquireResult {
+    /** How cookies were obtained. */
+    source: "appState" | "credentials" | "appStateString";
+    /** 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>;
+
 type ApiContext = ApiContext$1;
 type ApiInternal = Api;
 type DefaultFuncs = DefaultFuncs$1;
@@ -948,4 +1245,4 @@ declare const _default: typeof login$1 & {
     default: typeof login$1;
 };
 
-export { type API, type AddedStickerPackInfo, type AiTheme, type AnyAttachment, type ApiContext, type ApiInternal, type Attachment, type AudioAttachment, type BrowserProfile, type Callback, type CommentMessage, type CommentResult, type Coordinates, type DefaultFuncs, type EmojiEvent, type Event, type FileAttachment, type GroupNameEvent, type ListenEvent, type LivenessHandle, type LivenessState, type LoginCredentials, type LoginOptions, type Mention, type Message, type MessageID, type MessageObject, type MessageReply, type MusicTag, type MusicTrack, type NicknameEvent, type PhotoAttachment, type Reaction, type SearchMusicOptions, type SearchMusicResult, type ShareAttachment, type ShareResult, type StickerAttachment, type StickerInfo, type StickerPackInfo, type ThreadID, type ThreadInfo, type ThreadThemeEvent, type TypingIndicator, type UnsendMessageEvent, type UserID, type UserInfo, type VideoAttachment, type WarmUpResult, applySetCookie, awaitProactiveSlot, canActProactively, collectSessionCookies, _default as default, defaultBrowserProfile, ensureCometTokens, extractCookies, extractCookiesFromBody, extractCookiesFromJar, extractCookiesFromSetCookie, extractCurrentUser, getFingerprintParams, getHeaders, getWebSocketHeaders, hasAuthenticatedSession, humanDelay, invalidateCometTokens, isAuthFailure, isBreakerOpen, isStaleTokenError, login$1 as login, missingSessionCookies, normalizeBrowserProfile, noteAction, noteAuthFailure, noteCheckpoint, noteRateLimit, paceRequest, publicTypes, randomUserAgent, refreshSessionCookies, repairSession, reserveRequest, resetBreaker, resolveProfile, retryDelay, safetySnapshot, sleep, startLiveness, tripBreaker, warmUpSession, withCometTokens, withSessionRetry };
+export { type API, type AddedStickerPackInfo, type AiTheme, type AnyAttachment, type ApiContext, type ApiInternal, type Attachment, type AudioAttachment, type BrowserProfile, type Callback, type CommentMessage, type CommentResult, type Coordinates, type DefaultFuncs, type EmojiEvent, type Event, type FileAttachment, type GroupNameEvent, type ListenEvent, type LivenessHandle, type LivenessState, type LoginCredentials, type LoginOptions, type Mention, type Message, type MessageID, type MessageObject, type MessageReply, type MusicTag, type MusicTrack, type NicknameEvent, PING_GRACE_MS, type PhotoAttachment, type Reaction, RealtimeHealth, type RealtimeHealthState, type RecoveryEvent, type RecoveryOptions, type RecoveryRuntime, type RecoveryState, RecoverySupervisor, SILENT_WINDOW_MS, type SearchMusicOptions, type SearchMusicResult, type ShareAttachment, type ShareResult, type StickerAttachment, type StickerInfo, type StickerPackInfo, type ThreadID, type ThreadInfo, type ThreadThemeEvent, type TypingIndicator, type UnsendMessageEvent, type UserID, type UserInfo, type VideoAttachment, type WarmUpResult, acquireCookies, applySetCookie, awaitProactiveSlot, canActProactively, collectSessionCookies, _default as default, defaultBrowserProfile, ensureCometTokens, extractCookies, extractCookiesFromBody, extractCookiesFromJar, extractCookiesFromSetCookie, extractCurrentUser, getFingerprintParams, getHeaders, getWebSocketHeaders, hasAuthenticatedSession, humanDelay, invalidateCometTokens, isAuthFailure, isBreakerOpen, isLoggedOutDocument, isStaleTokenError, login$1 as login, missingSessionCookies, normalizeBrowserProfile, noteAction, noteAuthFailure, noteCheckpoint, noteRateLimit, paceRequest, publicTypes, randomUserAgent, refreshSessionCookies, repairSession, reserveRequest, resetBreaker, resolveProfile, retryDelay, safetySnapshot, sleep, startLiveness, startRealtimeSupervisor, startRecovery, tripBreaker, warmUpSession, withCometTokens, withSessionRetry };