baileys-antiban 3.8.3 → 3.8.4

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.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';

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';

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.4",
   "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",