@lazyneoaz/metachat 4.0.4 → 4.0.6

package/dist/index.d.mts

@@ -1,6 +1,80 @@
 import { ReadStream } from 'fs';
 import { EventEmitter } from 'events';
 
+/**
+ * Single source of truth for browser and device identity.
+ *
+ * Facebook cross-checks the User-Agent against the Client Hints it receives
+ * (`sec-ch-ua*`), the `navigator`-derived values it can infer from request
+ * shape (platform, viewport, timezone, locale), and the `a` field on the MQTT
+ * username. Every one of those must describe the *same* device, so they are all
+ * derived from one profile here instead of being hardcoded across files.
+ */
+interface BrowserProfile {
+    /** Full navigator.userAgent string. */
+    userAgent: string;
+    /** Value for the `sec-ch-ua` header. */
+    secChUa: string;
+    /** Value for the `sec-ch-ua-full-version-list` header. */
+    secChUaFullVersionList: string;
+    /** Value for the `sec-ch-ua-platform` header (quoted). */
+    secChUaPlatform: string;
+    /** Value for the `sec-ch-ua-platform-version` header (quoted). */
+    secChUaPlatformVersion: string;
+    /** Value for `sec-ch-ua-arch` (quoted, only meaningful on desktop). */
+    secChUaArch: string;
+    /** Value for `sec-ch-ua-bitness` (quoted). */
+    secChUaBitness: string;
+    /** Value for `sec-ch-ua-model` (`""` on desktop). */
+    secChUaModel: string;
+    /** Value for `sec-ch-ua-wow64` (`?1` only on Windows x64 emulation). */
+    secChUaWow64: string;
+    /** Value for `sec-ch-ua-form-factors` (quoted brand list). */
+    secChUaFormFactors: string;
+    /** Value for `sec-ch-ua-mobile`. */
+    secChUaMobile: string;
+    /** Value for `Accept-Language`. */
+    acceptLanguage: string;
+    /** Primary language tag, e.g. `en-US`. */
+    language: string;
+    /** IANA timezone the session claims, e.g. `Europe/London`. */
+    timezone: string;
+    /** Device screen geometry, used to keep a stable `dpr`/viewport identity. */
+    screen: {
+        width: number;
+        height: number;
+        availWidth: number;
+        availHeight: number;
+        colorDepth: number;
+        pixelDepth: number;
+    };
+    /** Device DPR for the `dpr` request parameter. */
+    devicePixelRatio: number;
+    /** navigator.hardwareConcurrency. */
+    hardwareConcurrency: number;
+    /** navigator.deviceMemory (GB). */
+    deviceMemory: number;
+    /** Stable, per-profile name surfaced in logs/debug. */
+    label: string;
+}
+/**
+ * Deterministic default profile. Using a fixed identity avoids the "every
+ * request a different browser" smell while still being configurable through
+ * `login({ userAgent })` / `login({ randomUserAgent: true })`.
+ */
+declare const defaultBrowserProfile: BrowserProfile;
+/**
+ * Produce a coherent random browser profile. The UA and every Client Hint are
+ * generated from the same (major, platform) pair, so they can never disagree.
+ */
+declare function randomUserAgent(): BrowserProfile;
+/**
+ * Fold a caller-supplied partial identity into a complete, coherent profile.
+ * Used when `login({ userAgent })` is given a bare string: the UA is honored
+ * but every dependent hint is recomputed from it so the pair cannot disagree.
+ */
+declare function normalizeBrowserProfile(input?: Partial<BrowserProfile> & Record<string, any>): BrowserProfile;
+
 interface LoginOptions$1 {
     online?: boolean;
     selfListen?: boolean;
@@ -14,11 +88,17 @@ interface LoginOptions$1 {
     proxy?: string;
     autoReconnect?: boolean;
     userAgent?: string;
+    /** Full browser identity (UA + Client Hints). Resolved once at login. */
+    browser?: BrowserProfile;
     emitReady?: boolean;
     randomUserAgent?: boolean;
     bypassRegion?: string;
     advancedProtection?: boolean;
     autoRotateSession?: boolean;
+    /** Visit the natural browser surfaces (home, inbox) before first use. */
+    warmUp?: boolean;
+    /** Alternate foreground/background on a human rhythm to avoid detection. */
+    liveness?: boolean;
     logging?: boolean;
     pageID?: string;
     [key: string]: any;
@@ -542,6 +622,322 @@ declare namespace publicTypes {
   export { type publicTypes_API as API, type publicTypes_AddedStickerPackInfo as AddedStickerPackInfo, type publicTypes_AiTheme as AiTheme, type publicTypes_AnyAttachment as AnyAttachment, type publicTypes_Attachment as Attachment, type publicTypes_AudioAttachment as AudioAttachment, type publicTypes_Callback as Callback, type publicTypes_CommentMessage as CommentMessage, type publicTypes_CommentResult as CommentResult, type publicTypes_Coordinates as Coordinates, type publicTypes_EmojiEvent as EmojiEvent, type publicTypes_Event as Event, type publicTypes_FileAttachment as FileAttachment, type publicTypes_GroupNameEvent as GroupNameEvent, type publicTypes_ListenEvent as ListenEvent, type publicTypes_LoginCredentials as LoginCredentials, type publicTypes_LoginOptions as LoginOptions, type publicTypes_Mention as Mention, type publicTypes_Message as Message, type publicTypes_MessageID as MessageID, type publicTypes_MessageObject as MessageObject, type publicTypes_MessageReply as MessageReply, type publicTypes_MusicTag as MusicTag, type publicTypes_MusicTrack as MusicTrack, type publicTypes_NicknameEvent as NicknameEvent, type publicTypes_PhotoAttachment as PhotoAttachment, type publicTypes_Reaction as Reaction, type publicTypes_SearchMusicOptions as SearchMusicOptions, type publicTypes_SearchMusicResult as SearchMusicResult, type publicTypes_ShareAttachment as ShareAttachment, type publicTypes_ShareResult as ShareResult, type publicTypes_StickerAttachment as StickerAttachment, type publicTypes_StickerInfo as StickerInfo, type publicTypes_StickerPackInfo as StickerPackInfo, type publicTypes_ThreadID as ThreadID, type publicTypes_ThreadInfo as ThreadInfo, type publicTypes_ThreadThemeEvent as ThreadThemeEvent, type publicTypes_TypingIndicator as TypingIndicator, type publicTypes_UnsendMessageEvent as UnsendMessageEvent, type publicTypes_UserID as UserID, type publicTypes_UserInfo as UserInfo, type publicTypes_VideoAttachment as VideoAttachment, publicTypes_login as login };
 }
 
+/**
+ * Resolve the browser profile for a request. Precedence:
+ *   1. an explicitly supplied profile on the options object
+ *   2. the session profile resolved once at login (`globalOptions.browser`)
+ *   3. the library default
+ *
+ * Individual `sec-ch-ua*` overrides on `options` are honored so a caller can
+ * pin a specific browser without breaking the UA/CH parity contract.
+ */
+declare function resolveProfile(options?: Record<string, any>): BrowserProfile;
+declare function getHeaders(url: string, options?: Record<string, any>, ctx?: Record<string, any>, customHeader?: Record<string, any>): Record<string, string>;
+/**
+ * Build the headers used on a WebSocket / MQTT upgrade. These are the browser
+ * headers minus the hop-by-hop ones the transport owns, and with the same
+ * Client Hints so the socket matches the HTTP traffic from the same session.
+ */
+declare function getWebSocketHeaders(url: string, options?: Record<string, any>, ctx?: Record<string, any>): Record<string, string>;
+/**
+ * Query parameters the real web client appends to every GraphQL/form POST.
+ * Sending the same `dpr` and viewport as the browser identity keeps the
+ * request fingerprint coherent with the Client Hints.
+ */
+declare function getFingerprintParams(options?: Record<string, any>): Record<string, string>;
+
+interface CookieExtractionResult {
+    /** Human-readable name -> value for every cookie found. */
+    cookies: Record<string, string>;
+    /** Total distinct cookie names harvested. */
+    count: number;
+    /** Sources that contributed at least one cookie. */
+    sources: string[];
+}
+/**
+ * Collect cookies from a live cookie jar for every Facebook/Messenger origin.
+ * `getCookiesSync(url)` returns Cookie objects; `cookieString()` yields the
+ * exact `name=value` pair that must be sent on the wire.
+ */
+declare function extractCookiesFromJar(jar: any): Record<string, string>;
+/**
+ * Parse a raw `Set-Cookie` header (or an array of them) into name/value pairs.
+ * Multiple `Set-Cookie` headers arrive as an array; a single one may also be
+ * comma-joined by some transports, so handle both.
+ */
+declare function extractCookiesFromSetCookie(header: any): Record<string, string>;
+/**
+ * Some Facebook responses embed cookie assignments inside JSON (`jsmods`) or
+ * inline scripts rather than in a `Set-Cookie` header. Harvest those too so a
+ * rotated cookie cannot hide from the jar.
+ */
+declare function extractCookiesFromBody(body: any): Record<string, string>;
+/**
+ * Run every extractor and merge the results. Later sources win so a cookie
+ * freshly set by Facebook overrides the stale jar copy.
+ */
+declare function extractCookies(sources: {
+    jar?: any;
+    setCookie?: any;
+    body?: any;
+}): CookieExtractionResult;
+/**
+ * Fold a `Set-Cookie` header into the jar for both facebook and messenger.
+ * Preserves the attributes Facebook sent instead of rebuilding the cookie, so
+ * `Secure` / `SameSite` / `HttpOnly` / expiry survive.
+ */
+declare function applySetCookie(jar: any, header: any): number;
+/** True when the jar still holds an authenticated session (`c_user` + `xs`). */
+declare function hasAuthenticatedSession(jar: any): boolean;
+/**
+ * Build the `Cookie:` header value for a socket/HTTP target.
+ *
+ * Cookies are scoped to `.facebook.com`/`.messenger.com`, so a jar lookup for
+ * an `edge-chat.messenger.com` or `gateway.facebook.com` host returns only the
+ * handful of host-less cookies (typically just `fr`). Sending that partial set
+ * is what makes Facebook refuse an authenticated handshake. This unions the
+ * jar across every origin the session legitimately holds cookies for, dedupes
+ * by name, and preserves `cookieString()` (the exact wire form).
+ */
+declare function collectSessionCookies(ctx: any, host?: string): string;
+/** Names of the session cookies that are currently missing. */
+declare function missingSessionCookies(jar: any): string[];
+/**
+ * Re-fetch the Facebook/Messenger surfaces and fold every `Set-Cookie` back
+ * into the jar. This is the cookie extractor's refresh step: it is how a
+ * long-running session obtains rotated `datr`/`fr`/`xs` values instead of
+ * slowly dying as they expire.
+ *
+ * Returns the merged cookie map so callers can persist it (e.g. as a new
+ * appState), plus whether the session still looks authenticated.
+ */
+declare function refreshSessionCookies(ctx: any, defaultFuncs: any, options?: {
+    surfaces?: string[];
+}): Promise<CookieExtractionResult & {
+    applied: number;
+    authenticated: boolean;
+    errors: string[];
+}>;
+/** Detect an auth/document-token failure in a thrown or returned payload. */
+declare function isAuthFailure(value: any): boolean;
+/**
+ * Wrap a network operation with one repair-and-retry pass.
+ *
+ * On an auth failure it refreshes the session cookies, invalidates the Comet
+ * tokens, and runs the operation once more. This is what converts "works after
+ * startup, then stops" into "works, and recovers on its own".
+ */
+declare function withSessionRetry<T>(ctx: any, defaultFuncs: any, operation: () => Promise<T>, options?: {
+    attempts?: number;
+    onRecover?: (info: any) => void;
+}): Promise<T>;
+/** Repair a session: refresh cookies, drop stale tokens, reset MQTT backoff. */
+declare function repairSession(ctx: any, defaultFuncs: any): Promise<boolean>;
+
+/**
+ * Populate `ctx.lsd` / `ctx.fb_dtsg` (and `ctx.__spin` / `ctx.jazoest`) from
+ * Facebook's own Comet markup.
+ *
+ * Safe to call from every GraphQL module: it is a no-op while the cached pair
+ * is fresh, and it maintains exponential backoff when the scrape keeps failing
+ * so a broken session cannot turn into a request storm.
+ */
+declare function ensureCometTokens(ctx: any, defaultFuncs: any, force?: boolean): Promise<void>;
+/**
+ * Drop the cached document tokens so the next {@link ensureCometTokens} call is
+ * forced to re-scrape. Call this from any error path that observes a
+ * document-token rejection.
+ */
+declare function invalidateCometTokens(ctx: any): void;
+/** True when an error/response payload signals a stale document token. */
+declare function isStaleTokenError(value: any): boolean;
+/**
+ * Run a GraphQL request with document-token resilience.
+ *
+ * `run(host)` must perform the request using the tokens currently on `ctx`
+ * (read `ctx.lsd` / `ctx.fb_dtsg`), and resolve to the parsed payload. This
+ * helper makes sure the tokens exist first, detects a stale-token rejection in
+ * the result, re-scrapes, and retries once. It is the shared implementation
+ * behind searchMusic and every other token-sensitive query.
+ */
+declare function withCometTokens<T>(ctx: any, defaultFuncs: any, run: () => Promise<T>, options?: {
+    retries?: number;
+}): Promise<T>;
+
+/**
+ * Human-like pacing and request sequencing.
+ *
+ * Facebook does not rate-limit on volume alone; it also looks at *shape*. A
+ * bot that issues ten GraphQL calls in the same millisecond, or that always
+ * waits exactly the same amount between retries, is trivially separable from a
+ * person. Real clients:
+ *
+ *   - space requests out by a few tens to a few hundreds of milliseconds,
+ *   - take longer after a heavy call and shorter after a trivial one,
+ *   - jitter their retry delays instead of using a fixed ramp,
+ *   - pause noticeably between distinct "actions" (open thread, then send).
+ *
+ * This module centralizes that behavior. It is deliberately cheap: a single
+ * shared queue guarantees requests never leave simultaneously, while still
+ * letting independent callers await their own turn.
+ */
+/**
+ * A jittered wait. Uses a log-normal-ish shape (mostly short, occasionally
+ * longer) so the distribution does not look uniform to a classifier.
+ */
+declare function humanDelay(baseMs?: number, spreadMs?: number): number;
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Await this session's turn before sending a request, then record the send
+ * time. Concurrent callers are serialized in call order so two modules cannot
+ * fire in the same tick.
+ *
+ * `weight` lets a caller request a longer pause for an action that would be a
+ * "big" step for a human (opening a thread, sending a message) versus a small
+ * poll.
+ */
+declare function paceRequest(ctx: any, weight?: "light" | "normal" | "heavy"): Promise<void>;
+/**
+ * An exponentially backed-off, fully jittered retry delay. Replaces the fixed
+ * `base * 2 ** i` ramps used across the library, which are a pattern tell and
+ * synchronized across every process started at the same time.
+ */
+declare function retryDelay(attempt: number, baseMs?: number, capMs?: number): number;
+/** Mark a heavy action so the next request gets a longer pause. */
+declare function noteAction(ctx: any, weight?: "light" | "normal" | "heavy"): void;
+
+/**
+ * Account safety: a per-session request budget and circuit breaker.
+ *
+ * The single most common way a bot gets its session invalidated is not a bad
+ * header — it is a *storm*. A loop that retries a failing call, a reconnect
+ * ramp that re-arms a limiter, or several modules firing at once can push a
+ * healthy account into Facebook's risk system, which then logs the session out
+ * or asks for a password. Once that happens, no amount of header tuning helps.
+ *
+ * This module caps how fast a session can emit requests and trips a breaker
+ * when Facebook starts signalling that it is unhappy (429s, repeated auth
+ * failures, checkpoint/consent redirects). A tripped breaker parks all traffic
+ * for a cooling-off window, which is exactly what a person would do after
+ * being warned.
+ */
+type BreakerReason = "rate-limit" | "auth-failure" | "checkpoint" | "manual";
+interface SafetySnapshot {
+    closed: boolean;
+    reason?: BreakerReason;
+    cooldownRemainingMs: number;
+    requestsInWindow: number;
+    authFailures: number;
+    cappedCount: number;
+}
+/** True while the breaker is open (traffic should be parked). */
+declare function isBreakerOpen(ctx: any): boolean;
+/** Trip the breaker for a cooling-off period. */
+declare function tripBreaker(ctx: any, reason?: BreakerReason): void;
+/** Close the breaker immediately (e.g. after a confirmed-good request). */
+declare function resetBreaker(ctx: any): void;
+/** Record an auth-looking failure; trips the breaker at the threshold. */
+declare function noteAuthFailure(ctx: any): void;
+/** Record a Facebook rate-limit response. */
+declare function noteRateLimit(ctx: any): void;
+/** Record a checkpoint/consent redirect that means the session is at risk. */
+declare function noteCheckpoint(ctx: any): void;
+/**
+ * Reserve a request slot. Returns the number of ms the caller must wait before
+ * emitting (0 when it may proceed immediately). Throws nothing: a caller that
+ * cannot wait is still bounded by the sliding window.
+ */
+declare function reserveRequest(ctx: any): number;
+/** A diagnostic snapshot for logs / health checks. */
+declare function safetySnapshot(ctx: any): SafetySnapshot;
+
+/**
+ * Session warm-up.
+ *
+ * A freshly-authenticated session that immediately fires GraphQL queries is
+ * distinguishable from a real client, which first loads the home document, then
+ * the Messenger inbox, and only afterwards starts issuing API calls. Those
+ * document loads also hand out the `datr`/`fr` rotation and the Comet document
+ * tokens that later calls depend on.
+ *
+ * {@link warmUpSession} performs that short, realistic sequence with human
+ * pacing. It is best-effort: a failure never aborts login, because the tokens
+ * can always be re-scraped lazily.
+ */
+
+interface WarmUpResult {
+    visited: string[];
+    cookiesApplied: number;
+    authenticated: boolean;
+    tokensSeeded: boolean;
+    errors: string[];
+}
+/**
+ * Visit the surfaces a real browser would on a normal session start.
+ *
+ * @param ctx    session context (needs `jar`)
+ * @param getter a `defaultFuncs.get`-compatible function
+ * @param options.includeMessenger visit messenger.com as well (default true)
+ */
+declare function warmUpSession(ctx: any, getter: (url: string, jar: any, qs?: any, options?: any, ctx?: any, customHeader?: any) => Promise<any>, options?: {
+    includeMessenger?: boolean;
+}): Promise<WarmUpResult>;
+
+/**
+ * Human-like liveness engine.
+ *
+ * This is the piece that makes a long-running bot account behave like a person
+ * instead of a script. Facebook's risk system does not just look at one request
+ * — it looks at the *shape of the session over time*:
+ *
+ *   - requests spread out, never a burst,
+ *   - activity in bursts followed by quiet periods (people leave the app),
+ *   - a stable presence heartbeat instead of a permanent "always typing" state,
+ *   - no reconnect storms when the socket drops,
+ *   - a deliberate pause after being told to slow down.
+ *
+ * {@link startLiveness} installs a single worker that owns that rhythm. Every
+ * outbound request funnels through it (via `paceRequest`), and it maintains a
+ * natural foreground/background rhythm so the session never looks pinned open.
+ */
+
+interface LivenessHandle {
+    stop: () => void;
+    /** Current activity state, for diagnostics. */
+    state: () => LivenessState;
+}
+interface LivenessState {
+    active: boolean;
+    /** ms until the next background/foreground transition. */
+    nextTransitionMs: number;
+    /** Total requests observed through pacing. */
+    requests: number;
+    breakerOpen: boolean;
+}
+/**
+ * Start the liveness worker for a session.
+ *
+ * @param ctx        session context (mutated with `__foreground`)
+ * @param options.foregroundPing optional callback invoked when becoming active
+ * @param options.backgroundPing optional callback invoked when going idle
+ */
+declare function startLiveness(ctx: any, options?: {
+    foregroundPing?: () => void;
+    backgroundPing?: () => void;
+}): LivenessHandle;
+/**
+ * A guard for *proactive* activity (anything not triggered by an incoming
+ * event). Returns false while the session is idle or the safety breaker is
+ * open, so a scheduled loop can quietly skip instead of firing off-schedule
+ * and looking automated.
+ */
+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>;
+
+/** Extract the `CurrentUserInitialData` object from a profile HTML document. */
+declare function extractCurrentUser(html: any): Record<string, any> | null;
+
 type ApiContext = ApiContext$1;
 type ApiInternal = Api;
 type DefaultFuncs = DefaultFuncs$1;
@@ -552,4 +948,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 Callback, type CommentMessage, type CommentResult, type Coordinates, type DefaultFuncs, type EmojiEvent, type Event, type FileAttachment, type GroupNameEvent, type ListenEvent, 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, _default as default, login$1 as login, publicTypes };
+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 };