@lazyneoaz/metachat 5.1.1 → 6.0.0

package/dist/index.d.mts

@@ -831,6 +831,63 @@ declare function retryDelay(attempt: number, baseMs?: number, capMs?: number): n
 /** Mark a heavy action so the next request gets a longer pause. */
 declare function noteAction(ctx: any, weight?: "light" | "normal" | "heavy"): void;
 
+/**
+ * Realtime event middleware system (reference `api.useMiddleware` etc.).
+ *
+ * A middleware is `(event, next) => void | Promise<void>`. Middleware run in
+ * registration order; call `next()` to continue, `next(err)` to abort with an
+ * error, or `next(false)` to drop the event. Returning false/null from a
+ * middleware drops the event.
+ */
+type MiddlewareCallback = (err: any, event: any) => void;
+type NextFunction = (arg?: any) => void;
+type MiddlewareFunction = (event: any, next: NextFunction) => any;
+interface RealtimeMiddlewareSystem {
+    use: (middleware: string | MiddlewareFunction, fn?: MiddlewareFunction) => () => void;
+    remove: (identifier: string | MiddlewareFunction) => boolean;
+    clear: () => void;
+    list: () => string[];
+    setEnabled: (name: string, enabled: boolean) => boolean;
+    process: (event: any, finalCallback: MiddlewareCallback) => void;
+    wrapCallback: (callback: MiddlewareCallback) => MiddlewareCallback;
+    readonly count: number;
+}
+declare function createRealtimeMiddlewareSystem(logger?: (text: string, type?: string) => void): RealtimeMiddlewareSystem;
+
+declare function createScheduler(sendMessage: (...args: any[]) => any, logger?: (m: string, l?: string) => void): {
+    scheduleMessage: (message: any, threadID: any, when: Date | number | string, options?: any) => string;
+    cancelScheduledMessage: (id: string) => boolean;
+    getScheduledMessage: (id: string) => {
+        id: string;
+        message: any;
+        threadID: any;
+        timestamp: number;
+        createdAt: number;
+        options: {
+            replyMessageID?: string;
+            isGroup?: boolean;
+            callback?: any;
+        };
+        timeUntilSend: number;
+    };
+    listScheduledMessages: () => {
+        id: string;
+        message: any;
+        threadID: any;
+        timestamp: number;
+        createdAt: number;
+        options: {
+            replyMessageID?: string;
+            isGroup?: boolean;
+            callback?: any;
+        };
+        timeUntilSend: number;
+    }[];
+    cancelAllScheduledMessages: () => number;
+    getScheduledCount: () => number;
+    destroy: () => number;
+};
+
 /**
  * Account safety: a per-session request budget and circuit breaker.
  *
@@ -1154,7 +1211,7 @@ interface RealtimeHealthState {
  */
 declare class RealtimeHealth {
     private now;
-    private frames;
+    private frameCount;
     private lastFrameAt;
     private connectedAt;
     private probes;
@@ -1175,15 +1232,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 +1257,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 +1281,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 +1306,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 +1335,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>;
@@ -1290,4 +1354,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, CORE_REACTIONS, 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, REACTION_ALIASES, 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, cleanJsonResponse, collectSessionCookies, _default as default, defaultBrowserProfile, ensureCometTokens, extractCookies, extractCookiesFromBody, extractCookiesFromJar, extractCookiesFromSetCookie, extractCurrentUser, getFingerprintParams, getHeaders, getWebSocketHeaders, hasAuthenticatedSession, humanDelay, invalidateCometTokens, isAuthFailure, isBreakerOpen, isLoggedOutDocument, isNonCriticalError, isReactionEmoji, isStaleTokenError, login$1 as login, missingSessionCookies, normalizeBrowserProfile, normalizeReaction, noteAction, noteAuthFailure, noteCheckpoint, noteRateLimit, paceRequest, publicTypes, randomUserAgent, refreshSessionCookies, repairSession, reserveRequest, resetBreaker, resolveProfile, retryDelay, retryOnNonCritical, safetySnapshot, sleep, startLiveness, startRealtimeSupervisor, startRecovery, tripBreaker, uploadGroupImage, uploadMercuryAttachment, warmUpSession, withCometTokens, withSessionRetry };
+export { type API, type AddedStickerPackInfo, type AiTheme, type AnyAttachment, type ApiContext, type ApiInternal, type Attachment, type AudioAttachment, type BrowserProfile, CORE_REACTIONS, 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, REACTION_ALIASES, 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, cleanJsonResponse, collectSessionCookies, createRealtimeMiddlewareSystem, createScheduler, _default as default, defaultBrowserProfile, ensureCometTokens, extractCookies, extractCookiesFromBody, extractCookiesFromJar, extractCookiesFromSetCookie, extractCurrentUser, getFingerprintParams, getHeaders, getWebSocketHeaders, hasAuthenticatedSession, humanDelay, invalidateCometTokens, isAuthFailure, isBreakerOpen, isLoggedOutDocument, isNonCriticalError, isReactionEmoji, isStaleTokenError, login$1 as login, missingSessionCookies, normalizeBrowserProfile, normalizeReaction, noteAction, noteAuthFailure, noteCheckpoint, noteRateLimit, paceRequest, publicTypes, randomUserAgent, refreshSessionCookies, repairSession, reserveRequest, resetBreaker, resolveProfile, retryDelay, retryOnNonCritical, safetySnapshot, sleep, startLiveness, startRealtimeSupervisor, startRecovery, tripBreaker, uploadGroupImage, uploadMercuryAttachment, warmUpSession, withCometTokens, withSessionRetry };

package/dist/index.d.ts

@@ -831,6 +831,63 @@ declare function retryDelay(attempt: number, baseMs?: number, capMs?: number): n
 /** Mark a heavy action so the next request gets a longer pause. */
 declare function noteAction(ctx: any, weight?: "light" | "normal" | "heavy"): void;
 
+/**
+ * Realtime event middleware system (reference `api.useMiddleware` etc.).
+ *
+ * A middleware is `(event, next) => void | Promise<void>`. Middleware run in
+ * registration order; call `next()` to continue, `next(err)` to abort with an
+ * error, or `next(false)` to drop the event. Returning false/null from a
+ * middleware drops the event.
+ */
+type MiddlewareCallback = (err: any, event: any) => void;
+type NextFunction = (arg?: any) => void;
+type MiddlewareFunction = (event: any, next: NextFunction) => any;
+interface RealtimeMiddlewareSystem {
+    use: (middleware: string | MiddlewareFunction, fn?: MiddlewareFunction) => () => void;
+    remove: (identifier: string | MiddlewareFunction) => boolean;
+    clear: () => void;
+    list: () => string[];
+    setEnabled: (name: string, enabled: boolean) => boolean;
+    process: (event: any, finalCallback: MiddlewareCallback) => void;
+    wrapCallback: (callback: MiddlewareCallback) => MiddlewareCallback;
+    readonly count: number;
+}
+declare function createRealtimeMiddlewareSystem(logger?: (text: string, type?: string) => void): RealtimeMiddlewareSystem;
+
+declare function createScheduler(sendMessage: (...args: any[]) => any, logger?: (m: string, l?: string) => void): {
+    scheduleMessage: (message: any, threadID: any, when: Date | number | string, options?: any) => string;
+    cancelScheduledMessage: (id: string) => boolean;
+    getScheduledMessage: (id: string) => {
+        id: string;
+        message: any;
+        threadID: any;
+        timestamp: number;
+        createdAt: number;
+        options: {
+            replyMessageID?: string;
+            isGroup?: boolean;
+            callback?: any;
+        };
+        timeUntilSend: number;
+    };
+    listScheduledMessages: () => {
+        id: string;
+        message: any;
+        threadID: any;
+        timestamp: number;
+        createdAt: number;
+        options: {
+            replyMessageID?: string;
+            isGroup?: boolean;
+            callback?: any;
+        };
+        timeUntilSend: number;
+    }[];
+    cancelAllScheduledMessages: () => number;
+    getScheduledCount: () => number;
+    destroy: () => number;
+};
+
 /**
  * Account safety: a per-session request budget and circuit breaker.
  *
@@ -1154,7 +1211,7 @@ interface RealtimeHealthState {
  */
 declare class RealtimeHealth {
     private now;
-    private frames;
+    private frameCount;
     private lastFrameAt;
     private connectedAt;
     private probes;
@@ -1175,15 +1232,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 +1257,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 +1281,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 +1306,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 +1335,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>;
@@ -1290,4 +1354,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, CORE_REACTIONS, 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, REACTION_ALIASES, 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, cleanJsonResponse, collectSessionCookies, _default as default, defaultBrowserProfile, ensureCometTokens, extractCookies, extractCookiesFromBody, extractCookiesFromJar, extractCookiesFromSetCookie, extractCurrentUser, getFingerprintParams, getHeaders, getWebSocketHeaders, hasAuthenticatedSession, humanDelay, invalidateCometTokens, isAuthFailure, isBreakerOpen, isLoggedOutDocument, isNonCriticalError, isReactionEmoji, isStaleTokenError, login$1 as login, missingSessionCookies, normalizeBrowserProfile, normalizeReaction, noteAction, noteAuthFailure, noteCheckpoint, noteRateLimit, paceRequest, publicTypes, randomUserAgent, refreshSessionCookies, repairSession, reserveRequest, resetBreaker, resolveProfile, retryDelay, retryOnNonCritical, safetySnapshot, sleep, startLiveness, startRealtimeSupervisor, startRecovery, tripBreaker, uploadGroupImage, uploadMercuryAttachment, warmUpSession, withCometTokens, withSessionRetry };
+export { type API, type AddedStickerPackInfo, type AiTheme, type AnyAttachment, type ApiContext, type ApiInternal, type Attachment, type AudioAttachment, type BrowserProfile, CORE_REACTIONS, 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, REACTION_ALIASES, 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, cleanJsonResponse, collectSessionCookies, createRealtimeMiddlewareSystem, createScheduler, _default as default, defaultBrowserProfile, ensureCometTokens, extractCookies, extractCookiesFromBody, extractCookiesFromJar, extractCookiesFromSetCookie, extractCurrentUser, getFingerprintParams, getHeaders, getWebSocketHeaders, hasAuthenticatedSession, humanDelay, invalidateCometTokens, isAuthFailure, isBreakerOpen, isLoggedOutDocument, isNonCriticalError, isReactionEmoji, isStaleTokenError, login$1 as login, missingSessionCookies, normalizeBrowserProfile, normalizeReaction, noteAction, noteAuthFailure, noteCheckpoint, noteRateLimit, paceRequest, publicTypes, randomUserAgent, refreshSessionCookies, repairSession, reserveRequest, resetBreaker, resolveProfile, retryDelay, retryOnNonCritical, safetySnapshot, sleep, startLiveness, startRealtimeSupervisor, startRecovery, tripBreaker, uploadGroupImage, uploadMercuryAttachment, warmUpSession, withCometTokens, withSessionRetry };