baileys-antiban 3.8.3 → 3.8.5

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.8.5] - 2026-05-09
+
+### Added
+- **Observability module** (`src/observability.ts`) — Prometheus metrics export and pluggable structured logging.
+  - `exportPrometheusMetrics(stats, labels?)` — exports 27 metrics (3 counters, 24 gauges) in Prometheus text exposition format v0.0.4. Covers health score/risk, warmup progress, rate limiter windows, known chats, reply ratio, contact graph, retry spirals, reconnect throttle. Accepts custom labels (`instance`, `region`, etc.).
+  - `createMetricsHandler(getStats, labels?)` — returns Express/Fastify-compatible `handle(req, res)` + `text()` helpers for a `/metrics` endpoint.
+  - `createPeriodicExporter(getStats, config)` — push-based exporter that calls `onMetrics(text)` on a configurable interval (default 30s). Returns `stop()` handle.
+  - `createConsoleLogger(prefix?)` — structured console logger compatible with winston/pino interface (`debug`, `info`, `warn`, `error` with ISO timestamps and JSON meta).
+  - `AntiBanLogger` interface — plug in any logger: `winston`, `pino`, or the built-in console logger.
+- New exports: `createConsoleLogger`, `exportPrometheusMetrics`, `createMetricsHandler`, `createPeriodicExporter`, `AntiBanLogger`, `PeriodicExporterConfig`, `PeriodicExporterHandle`.
+
+## [3.8.4] - 2026-05-09
+
+### Added
+- **`DeafSessionDetector`** — detects WebSocket sessions that stay open but stop delivering `messages.upsert` / `messages.update` events (Baileys issue #2491). Root cause: `messageMutex` holding ACKs under Redis latency spikes triggers WhatsApp server-side flow control, silently stopping message delivery while keepAlive pings still succeed. The detector runs a 30-second interval, fires `onDeafSession` callback with silence duration info, and optionally calls `sock.end(new Error('deaf-session'))` for auto-reconnect. Configurable `timeoutMs` (default 5 min), `minUptimeMs` warmup guard (default 2 min), `autoReconnect` flag.
+- **`wrapSocket` `deafSession` option** — pass `deafSession: DeafSessionConfig` to `wrapOptions` to enable automatic deaf-session detection on the wrapped socket. Activity signals are wired to all `messages.upsert` and `messages.update` events; cleanup is tied to `connection.update` close events.
+- New exports: `DeafSessionDetector`, `DeafSessionConfig`, `DeafSessionInfo`.
+
 ## [3.8.3] - 2026-05-09
 
 ### Fixed

package/dist/index.d.ts

@@ -19,7 +19,7 @@ export { RetryReasonTracker, type RetryTrackerConfig, type RetryStats, type Retr
 export { PostReconnectThrottle, type ReconnectThrottleConfig, type ReconnectThrottleStats } from './reconnectThrottle.js';
 export { LidResolver, type LidResolverConfig, type LidResolverStats, type LidMapping } from './lidResolver.js';
 export { JidCanonicalizer, type JidCanonicalizerConfig, type JidCanonicalizerStats } from './jidCanonicalizer.js';
-export { SessionHealthMonitor, type SessionHealthStats, type SessionHealthConfig, wrapWithSessionStability, type SessionStabilityConfig, classifyDisconnect, type DisconnectClassification, type DisconnectCategory, } from './sessionStability.js';
+export { SessionHealthMonitor, type SessionHealthStats, type SessionHealthConfig, wrapWithSessionStability, type SessionStabilityConfig, classifyDisconnect, type DisconnectClassification, type DisconnectCategory, DeafSessionDetector, type DeafSessionConfig, type DeafSessionInfo, } from './sessionStability.js';
 export { LidFirstResolver, createLidFirstResolver, type LidPhoneMapping, } from './lidFirstResolver.js';
 export { MessageRetryReason, MAC_ERROR_CODES, parseRetryReason, isMacError, getRetryReasonDescription, } from './retryReason.js';
 export { wrapSocket, type WrappedSocket, type WrapSocketOptions } from './wrapper.js';
@@ -38,3 +38,4 @@ export { readReceiptVariance, type ReadReceiptVariance, type ReadReceiptVariance
 export { proxyRotator, type ProxyEndpoint, type ProxyRotatorConfig, type ProxyRotatorStats, type ProxyRotatorHandle, } from './proxyRotator.js';
 export { generateSessionFingerprint, applySessionFingerprint, getMessageSendJitter, getTypingJitter, getRetryJitter, getVoiceNoteMetadata, getBatteryState, createStealthFingerprint, type SessionFingerprint, type SessionFingerprintConfig, } from './sessionFingerprint.js';
 export { getStealthSocketConfig, rampPresenceAfterConnect, STEALTH_BROWSER_POOL, AbortError, type BrowserTuple, type StealthSocketConfig, type GetStealthSocketConfigOptions, type RampPresenceOptions, type PresenceCapableSocket, } from './stealthConnect.js';
+export { createConsoleLogger, exportPrometheusMetrics, createMetricsHandler, createPeriodicExporter, type AntiBanLogger, type PeriodicExporterConfig, type PeriodicExporterHandle, } from './observability.js';

package/dist/index.js

@@ -24,7 +24,7 @@ export { PostReconnectThrottle } from './reconnectThrottle.js';
 export { LidResolver } from './lidResolver.js';
 export { JidCanonicalizer } from './jidCanonicalizer.js';
 // v2.0 new modules
-export { SessionHealthMonitor, wrapWithSessionStability, classifyDisconnect, } from './sessionStability.js';
+export { SessionHealthMonitor, wrapWithSessionStability, classifyDisconnect, DeafSessionDetector, } from './sessionStability.js';
 // v2.1 new modules
 export { LidFirstResolver, createLidFirstResolver, } from './lidFirstResolver.js';
 export { MessageRetryReason, MAC_ERROR_CODES, parseRetryReason, isMacError, getRetryReasonDescription, } from './retryReason.js';
@@ -53,3 +53,5 @@ export { proxyRotator, } from './proxyRotator.js';
 export { generateSessionFingerprint, applySessionFingerprint, getMessageSendJitter, getTypingJitter, getRetryJitter, getVoiceNoteMetadata, getBatteryState, createStealthFingerprint, } from './sessionFingerprint.js';
 // v3.8 new modules
 export { getStealthSocketConfig, rampPresenceAfterConnect, STEALTH_BROWSER_POOL, AbortError, } from './stealthConnect.js';
+// Observability
+export { createConsoleLogger, exportPrometheusMetrics, createMetricsHandler, createPeriodicExporter, } from './observability.js';

package/dist/observability.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Observability — Prometheus metrics export + pluggable structured logging
+ *
+ * Usage:
+ *   // Logging
+ *   import { createConsoleLogger } from 'baileys-antiban';
+ *   const logger = createConsoleLogger('[my-bot]');
+ *   logger.info('Message sent', { recipient: jid });
+ *
+ *   // Metrics export for Express
+ *   import { createMetricsHandler } from 'baileys-antiban';
+ *   const metricsHandler = createMetricsHandler(() => antiban.getStats());
+ *   app.get('/metrics', metricsHandler.handle);
+ *
+ *   // Periodic push to external system
+ *   import { createPeriodicExporter } from 'baileys-antiban';
+ *   const exporter = createPeriodicExporter(() => antiban.getStats(), {
+ *     intervalMs: 30_000,
+ *     onMetrics: (text) => pushToVictoriaMetrics(text),
+ *   });
+ */
+import type { AntiBanStats } from './antiban.js';
+/**
+ * Pluggable logger interface compatible with winston, pino, console
+ */
+export interface AntiBanLogger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Create a simple console logger with timestamps and prefix
+ */
+export declare function createConsoleLogger(prefix?: string): AntiBanLogger;
+/**
+ * Export AntiBan stats as Prometheus text format (exposition format v0.0.4)
+ */
+export declare function exportPrometheusMetrics(stats: AntiBanStats, labels?: Record<string, string>): string;
+/**
+ * Create an HTTP handler for Prometheus metrics (Express/Fastify compatible)
+ */
+export declare function createMetricsHandler(getStats: () => AntiBanStats, labels?: Record<string, string>): {
+    /**
+     * HTTP request handler (Express/Fastify compatible)
+     */
+    handle: (_req: unknown, res: {
+        setHeader: (name: string, value: string) => void;
+        end: (data: string) => void;
+    }) => void;
+    /**
+     * Get metrics as plain text (for non-HTTP usage)
+     */
+    text: () => string;
+};
+/**
+ * Configuration for periodic metrics export
+ */
+export interface PeriodicExporterConfig {
+    /**
+     * Export interval in milliseconds (default: 30000)
+     */
+    intervalMs?: number;
+    /**
+     * Callback invoked with Prometheus text on each interval
+     */
+    onMetrics: (text: string) => void;
+    /**
+     * Additional labels to attach to all metrics
+     */
+    labels?: Record<string, string>;
+}
+/**
+ * Handle for controlling periodic export
+ */
+export interface PeriodicExporterHandle {
+    /**
+     * Stop the periodic exporter
+     */
+    stop(): void;
+}
+/**
+ * Create a periodic metrics exporter that calls onMetrics on an interval
+ */
+export declare function createPeriodicExporter(getStats: () => AntiBanStats, config: PeriodicExporterConfig): PeriodicExporterHandle;

package/dist/observability.js

@@ -0,0 +1,145 @@
+/**
+ * Observability — Prometheus metrics export + pluggable structured logging
+ *
+ * Usage:
+ *   // Logging
+ *   import { createConsoleLogger } from 'baileys-antiban';
+ *   const logger = createConsoleLogger('[my-bot]');
+ *   logger.info('Message sent', { recipient: jid });
+ *
+ *   // Metrics export for Express
+ *   import { createMetricsHandler } from 'baileys-antiban';
+ *   const metricsHandler = createMetricsHandler(() => antiban.getStats());
+ *   app.get('/metrics', metricsHandler.handle);
+ *
+ *   // Periodic push to external system
+ *   import { createPeriodicExporter } from 'baileys-antiban';
+ *   const exporter = createPeriodicExporter(() => antiban.getStats(), {
+ *     intervalMs: 30_000,
+ *     onMetrics: (text) => pushToVictoriaMetrics(text),
+ *   });
+ */
+/**
+ * Create a simple console logger with timestamps and prefix
+ */
+export function createConsoleLogger(prefix = '[baileys-antiban]') {
+    const format = (level, msg, meta) => {
+        const timestamp = new Date().toISOString();
+        const metaStr = meta ? ' ' + JSON.stringify(meta) : '';
+        return `${timestamp} ${level} ${prefix} ${msg}${metaStr}`;
+    };
+    return {
+        debug: (msg, meta) => console.log(format('DEBUG', msg, meta)),
+        info: (msg, meta) => console.log(format('INFO', msg, meta)),
+        warn: (msg, meta) => console.warn(format('WARN', msg, meta)),
+        error: (msg, meta) => console.error(format('ERROR', msg, meta)),
+    };
+}
+/**
+ * Export AntiBan stats as Prometheus text format (exposition format v0.0.4)
+ */
+export function exportPrometheusMetrics(stats, labels) {
+    const labelMap = { instance: 'default', ...labels };
+    const labelStr = Object.entries(labelMap)
+        .map(([k, v]) => `${k}="${v}"`)
+        .join(',');
+    const lines = [];
+    const addMetric = (name, type, help, value) => {
+        lines.push(`# HELP ${name} ${help}`);
+        lines.push(`# TYPE ${name} ${type}`);
+        lines.push(`${name}{${labelStr}} ${value}`);
+    };
+    // Counters
+    addMetric('antiban_messages_allowed_total', 'counter', 'Total messages allowed by AntiBan', stats.messagesAllowed);
+    addMetric('antiban_messages_blocked_total', 'counter', 'Total messages blocked by AntiBan', stats.messagesBlocked);
+    addMetric('antiban_total_delay_ms_total', 'counter', 'Total delay imposed (milliseconds)', stats.totalDelayMs);
+    // Health gauges
+    const riskMap = { low: 0, medium: 1, high: 2, critical: 3 };
+    addMetric('antiban_health_score', 'gauge', 'Current health score (0=best, 100=worst)', stats.health.score);
+    addMetric('antiban_health_risk', 'gauge', 'Risk level encoded as number (0=low, 1=medium, 2=high, 3=critical)', riskMap[stats.health.risk] ?? 0);
+    addMetric('antiban_disconnects_last_hour', 'gauge', 'Disconnects in last hour', stats.health.stats.disconnectsLastHour);
+    addMetric('antiban_failed_messages_last_hour', 'gauge', 'Failed messages in last hour', stats.health.stats.failedMessagesLastHour);
+    addMetric('antiban_uptime_ms', 'gauge', 'Session uptime in milliseconds', stats.health.stats.uptimeMs);
+    // Warm-up gauges
+    addMetric('antiban_warmup_progress', 'gauge', 'Warm-up progress (0.0 to 1.0)', stats.warmUp.progress);
+    addMetric('antiban_warmup_day', 'gauge', 'Current warm-up day', stats.warmUp.day);
+    addMetric('antiban_warmup_today_sent', 'gauge', 'Messages sent today during warm-up', stats.warmUp.todaySent);
+    addMetric('antiban_warmup_today_limit', 'gauge', 'Message limit for today during warm-up', stats.warmUp.todayLimit);
+    // Rate limiter gauges
+    addMetric('antiban_rate_last_minute', 'gauge', 'Messages sent in last minute', stats.rateLimiter.lastMinute);
+    addMetric('antiban_rate_last_hour', 'gauge', 'Messages sent in last hour', stats.rateLimiter.lastHour);
+    addMetric('antiban_rate_last_day', 'gauge', 'Messages sent in last day', stats.rateLimiter.lastDay);
+    addMetric('antiban_rate_limit_per_minute', 'gauge', 'Rate limit per minute', stats.rateLimiter.limits.perMinute);
+    addMetric('antiban_rate_limit_per_hour', 'gauge', 'Rate limit per hour', stats.rateLimiter.limits.perHour);
+    addMetric('antiban_rate_limit_per_day', 'gauge', 'Rate limit per day', stats.rateLimiter.limits.perDay);
+    addMetric('antiban_known_chats', 'gauge', 'Number of known chats', stats.rateLimiter.knownChats);
+    // Reply ratio gauges (optional)
+    if (stats.replyRatio) {
+        addMetric('antiban_contacts_on_cooldown', 'gauge', 'Contacts currently on reply cooldown', stats.replyRatio.contactsOnCooldown);
+    }
+    else {
+        addMetric('antiban_contacts_on_cooldown', 'gauge', 'Contacts currently on reply cooldown', 0);
+    }
+    // Contact graph gauges (optional)
+    if (stats.contactGraph) {
+        addMetric('antiban_known_contacts', 'gauge', 'Number of known contacts', stats.contactGraph.knownContacts);
+        addMetric('antiban_pending_handshakes', 'gauge', 'Pending handshakes', stats.contactGraph.pendingHandshakes);
+    }
+    else {
+        addMetric('antiban_known_contacts', 'gauge', 'Number of known contacts', 0);
+        addMetric('antiban_pending_handshakes', 'gauge', 'Pending handshakes', 0);
+    }
+    // Retry tracker gauges (optional)
+    if (stats.retryTracker) {
+        addMetric('antiban_retry_spirals', 'gauge', 'Number of retry spirals detected', stats.retryTracker.spiralsDetected);
+        addMetric('antiban_active_retries', 'gauge', 'Currently active retries', stats.retryTracker.activeRetries);
+    }
+    else {
+        addMetric('antiban_retry_spirals', 'gauge', 'Number of retry spirals detected', 0);
+        addMetric('antiban_active_retries', 'gauge', 'Currently active retries', 0);
+    }
+    // Reconnect throttle gauges (optional)
+    if (stats.reconnectThrottle) {
+        addMetric('antiban_reconnect_throttled', 'gauge', 'Whether reconnect is currently throttled (0=no, 1=yes)', stats.reconnectThrottle.isThrottled ? 1 : 0);
+        addMetric('antiban_lifetime_reconnects', 'gauge', 'Total reconnects in session lifetime', stats.reconnectThrottle.lifetimeReconnects);
+    }
+    else {
+        addMetric('antiban_reconnect_throttled', 'gauge', 'Whether reconnect is currently throttled (0=no, 1=yes)', 0);
+        addMetric('antiban_lifetime_reconnects', 'gauge', 'Total reconnects in session lifetime', 0);
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * Create an HTTP handler for Prometheus metrics (Express/Fastify compatible)
+ */
+export function createMetricsHandler(getStats, labels) {
+    return {
+        /**
+         * HTTP request handler (Express/Fastify compatible)
+         */
+        handle: (_req, res) => {
+            const metrics = exportPrometheusMetrics(getStats(), labels);
+            res.setHeader('Content-Type', 'text/plain; version=0.0.4; charset=utf-8');
+            res.end(metrics);
+        },
+        /**
+         * Get metrics as plain text (for non-HTTP usage)
+         */
+        text: () => {
+            return exportPrometheusMetrics(getStats(), labels);
+        },
+    };
+}
+/**
+ * Create a periodic metrics exporter that calls onMetrics on an interval
+ */
+export function createPeriodicExporter(getStats, config) {
+    const intervalMs = config.intervalMs ?? 30_000;
+    const intervalId = setInterval(() => {
+        const metrics = exportPrometheusMetrics(getStats(), config.labels);
+        config.onMetrics(metrics);
+    }, intervalMs);
+    return {
+        stop: () => clearInterval(intervalId),
+    };
+}

package/dist/sessionStability.d.ts

@@ -76,6 +76,77 @@ export declare class SessionHealthMonitor {
      */
     reset(): void;
 }
+export interface DeafSessionConfig {
+    /**
+     * How long the session must be silent (no messages.upsert or messages.update)
+     * while the WS connection is open before it is declared "deaf".
+     * Default: 5 minutes.
+     */
+    timeoutMs?: number;
+    /**
+     * Minimum uptime before the detector starts checking.
+     * Avoids false positives immediately after a fresh connect.
+     * Default: 2 minutes.
+     */
+    minUptimeMs?: number;
+    /**
+     * Called when a deaf session is detected, before any auto-reconnect.
+     * Use this to log, alert, or run custom recovery logic.
+     */
+    onDeafSession?: (info: DeafSessionInfo) => void;
+    /**
+     * If true, call sock.end(new Error('deaf-session')) automatically.
+     * Set false if you want to handle reconnection yourself in onDeafSession.
+     * Default: true.
+     */
+    autoReconnect?: boolean;
+}
+export interface DeafSessionInfo {
+    /** Timestamp of last observed message activity, or null if none since connect. */
+    lastMessageAt: Date | null;
+    /** How long the session has been silent in ms. */
+    silenceDurationMs: number;
+    /** How long the WS has been open in ms. */
+    connectedSinceMs: number;
+}
+/**
+ * Detects "deaf sessions" — WebSocket connections that stay open but stop
+ * delivering messages.upsert / messages.update events.
+ *
+ * Root cause (Baileys issue #2491): messageMutex holding ACKs hostage under
+ * Redis latency spikes causes WhatsApp's server-side flow control to stop
+ * delivering messages to that client, while keepAlive pings still succeed.
+ *
+ * Usage: call onConnect() / onDisconnect() from connection.update events,
+ * onMessageActivity() from messages.upsert and messages.update events.
+ * Pass a sock reference via attach() so auto-reconnect can call sock.end().
+ */
+export declare class DeafSessionDetector {
+    private readonly timeoutMs;
+    private readonly minUptimeMs;
+    private readonly autoReconnect;
+    private readonly onDeafSessionCb?;
+    private lastMessageAt;
+    private connectedAt;
+    private timer;
+    private sockRef;
+    constructor(config?: DeafSessionConfig);
+    /** Attach a socket so auto-reconnect can call sock.end() */
+    attach(sock: {
+        end: (err?: Error) => void;
+    }): void;
+    /** Call when connection.update → connection === 'open' */
+    onConnect(): void;
+    /** Call when connection.update → connection === 'close' */
+    onDisconnect(): void;
+    /** Call on every messages.upsert and messages.update event */
+    onMessageActivity(): void;
+    /** Release the interval — call when discarding the socket */
+    destroy(): void;
+    private startTimer;
+    private stopTimer;
+    private check;
+}
 export interface SessionStabilityConfig {
     /** Enable canonical JID normalization before sendMessage (default: true) */
     canonicalJidNormalization?: boolean;

package/dist/sessionStability.js

@@ -207,6 +207,95 @@ export class SessionHealthMonitor {
         this.badMacTimestamps = [];
     }
 }
+/**
+ * Detects "deaf sessions" — WebSocket connections that stay open but stop
+ * delivering messages.upsert / messages.update events.
+ *
+ * Root cause (Baileys issue #2491): messageMutex holding ACKs hostage under
+ * Redis latency spikes causes WhatsApp's server-side flow control to stop
+ * delivering messages to that client, while keepAlive pings still succeed.
+ *
+ * Usage: call onConnect() / onDisconnect() from connection.update events,
+ * onMessageActivity() from messages.upsert and messages.update events.
+ * Pass a sock reference via attach() so auto-reconnect can call sock.end().
+ */
+export class DeafSessionDetector {
+    timeoutMs;
+    minUptimeMs;
+    autoReconnect;
+    onDeafSessionCb;
+    lastMessageAt = null;
+    connectedAt = null;
+    timer = null;
+    sockRef = null;
+    constructor(config = {}) {
+        this.timeoutMs = config.timeoutMs ?? 5 * 60_000;
+        this.minUptimeMs = config.minUptimeMs ?? 2 * 60_000;
+        this.autoReconnect = config.autoReconnect ?? true;
+        this.onDeafSessionCb = config.onDeafSession;
+    }
+    /** Attach a socket so auto-reconnect can call sock.end() */
+    attach(sock) {
+        this.sockRef = sock;
+    }
+    /** Call when connection.update → connection === 'open' */
+    onConnect() {
+        this.connectedAt = Date.now();
+        this.lastMessageAt = Date.now(); // reset — fresh connect is not silence
+        this.startTimer();
+    }
+    /** Call when connection.update → connection === 'close' */
+    onDisconnect() {
+        this.connectedAt = null;
+        this.stopTimer();
+    }
+    /** Call on every messages.upsert and messages.update event */
+    onMessageActivity() {
+        this.lastMessageAt = Date.now();
+    }
+    /** Release the interval — call when discarding the socket */
+    destroy() {
+        this.stopTimer();
+        this.sockRef = null;
+    }
+    startTimer() {
+        this.stopTimer();
+        this.timer = setInterval(() => this.check(), 30_000);
+    }
+    stopTimer() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    check() {
+        if (this.connectedAt === null)
+            return;
+        const now = Date.now();
+        const connectedSinceMs = now - this.connectedAt;
+        if (connectedSinceMs < this.minUptimeMs)
+            return;
+        const silenceDurationMs = now - (this.lastMessageAt ?? this.connectedAt);
+        if (silenceDurationMs < this.timeoutMs)
+            return;
+        const info = {
+            lastMessageAt: this.lastMessageAt !== null ? new Date(this.lastMessageAt) : null,
+            silenceDurationMs,
+            connectedSinceMs,
+        };
+        this.onDeafSessionCb?.(info);
+        if (this.autoReconnect && this.sockRef) {
+            try {
+                this.sockRef.end(new Error('deaf-session'));
+            }
+            catch {
+                // socket may already be closing
+            }
+        }
+        // Stop checking after triggering — let onConnect reset on next reconnect
+        this.stopTimer();
+    }
+}
 /**
  * Wrap a Baileys socket with session stability features.
  * Returns a Proxy that intercepts sendMessage to canonicalize JIDs.

package/dist/wrapper.d.ts

@@ -28,6 +28,7 @@
  * Timelock guard will operate in detection-only mode (relies on 463 errors only).
  */
 import { AntiBan, type AntiBanConfig } from './antiban.js';
+import { type DeafSessionConfig } from './sessionStability.js';
 import type { WarmUpState } from './warmup.js';
 export type WASocket = {
     sendMessage: (jid: string, content: any, options?: any) => Promise<any>;
@@ -44,6 +45,12 @@ export type WASocket = {
 export interface WrapSocketOptions {
     /** Auto-respond to incoming messages when reply ratio suggests it (default: false) */
     autoRespondToIncoming?: boolean;
+    /**
+     * Deaf session detection — monitors for WS connections that stop delivering
+     * messages while keepAlive pings still succeed (Baileys issue #2491).
+     * Pass a config object to enable; omit to disable.
+     */
+    deafSession?: DeafSessionConfig;
 }
 export type WrappedSocket<T extends WASocket = WASocket> = T & {
     antiban: AntiBan;

package/dist/wrapper.js

@@ -28,6 +28,7 @@
  * Timelock guard will operate in detection-only mode (relies on 463 errors only).
  */
 import { AntiBan } from './antiban.js';
+import { DeafSessionDetector } from './sessionStability.js';
 /**
  * Wrap a Baileys socket with anti-ban protection.
  * The returned socket has the same API but sendMessage() is protected.
@@ -38,6 +39,12 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
         autoRespondToIncoming: false,
         ...wrapOptions,
     };
+    // Deaf session detector — optional, enabled via wrapOptions.deafSession
+    const deafDetector = options.deafSession
+        ? new DeafSessionDetector(options.deafSession)
+        : null;
+    if (deafDetector)
+        deafDetector.attach(sock);
     // Hook into Baileys events for health monitoring
     // Prefer ev.process() (Baileys ≥ late 2022) for batched event handling
     // Fall back to ev.on() for older versions
@@ -50,9 +57,12 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
                     const reason = update.lastDisconnect?.error?.output?.statusCode || 'unknown';
                     antiban.onDisconnect(reason);
                     antiban.destroy(); // Clean up all timers
+                    deafDetector?.onDisconnect();
+                    deafDetector?.destroy();
                 }
                 if (update.connection === 'open') {
                     antiban.onReconnect();
+                    deafDetector?.onConnect();
                 }
                 // Reachout timelock detection
                 if (update.reachoutTimeLock) {
@@ -66,6 +76,7 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
             // Catch 463 errors from message updates + track retries + learn LID mappings
             if (events['messages.update']) {
                 const updates = events['messages.update'];
+                deafDetector?.onMessageActivity();
                 for (const update of updates) {
                     // 463 error detection
                     if (update?.update?.messageStubParameters) {
@@ -85,6 +96,7 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
             // Register known chats from incoming messages + handle reply suggestions + learn LID mappings
             if (events['messages.upsert']) {
                 const { messages } = events['messages.upsert'];
+                deafDetector?.onMessageActivity();
                 // Learn LID mappings FIRST (before any other processing)
                 antiban.jidCanonicalizer?.onIncomingEvent(events['messages.upsert']);
                 for (const msg of messages || []) {
@@ -129,9 +141,12 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
                 const reason = update.lastDisconnect?.error?.output?.statusCode || 'unknown';
                 antiban.onDisconnect(reason);
                 antiban.destroy(); // Clean up all timers
+                deafDetector?.onDisconnect();
+                deafDetector?.destroy();
             }
             if (update.connection === 'open') {
                 antiban.onReconnect();
+                deafDetector?.onConnect();
             }
             // Reachout timelock detection
             if (update.reachoutTimeLock) {
@@ -144,6 +159,7 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
         });
         // Catch 463 errors from message updates + track retries + learn LID mappings
         sock.ev.on('messages.update', (updates) => {
+            deafDetector?.onMessageActivity();
             for (const update of updates) {
                 // 463 error detection
                 if (update?.update?.messageStubParameters) {
@@ -161,6 +177,7 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
         // Register known chats from incoming messages + handle reply suggestions + learn LID mappings
         sock.ev.on('messages.upsert', (upsert) => {
             const { messages } = upsert;
+            deafDetector?.onMessageActivity();
             // Learn LID mappings FIRST (before any other processing)
             antiban.jidCanonicalizer?.onIncomingEvent(upsert);
             for (const msg of messages || []) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baileys-antiban",
-  "version": "3.8.3",
+  "version": "3.8.5",
   "description": "Anti-ban middleware for Baileys WhatsApp bots. Rate limiting, warmup, health monitor, LID resolver, disconnect classifier. Free Whapi.Cloud alternative.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",