baileys-antiban 3.2.0 → 3.4.0

package/CHANGELOG.md

@@ -5,6 +5,75 @@ 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.4.0] — 2026-04-26
+
+### Added
+- **WPM-based typing duration model** — Realistic typing indicator patterns based on human typing speed
+  - `PresenceChoreographer.computeTypingPlan(messageLength)` — Generates realistic typing plan with Gaussian WPM variance
+  - `PresenceChoreographer.executeTypingPlan(sock, jid, plan)` — Executes multi-step typing/pause cycle
+  - Gaussian sampling (Box-Muller) for WPM variance (default: 45 WPM ± 15 stdDev, clamped 10-120)
+  - Think-pause injection: 8% probability per 10 chars, 0.8-3.5s pauses (humans pause mid-thought)
+  - Intermittent `paused` state (40% probability) before send for realism
+  - Configurable min/max typing duration caps (default: 0.6s - 90s)
+  - AbortSignal support for mid-plan cancellation
+  - New stats: `typingPlansComputed`, `typingPlansExecuted`, `totalTypingTimeMs`
+  - Zero new dependencies — pure TypeScript with Box-Muller transform
+
+### Why v3.4
+WhatsApp's ML models flag accounts that fire `composing` then immediately send, or never fire typing indicators at all. Real humans typing a 200-character message take 30-60 seconds with multiple typing/paused cycles. This is the missing signal layer that completes PresenceChoreographer's anti-detection coverage. The WPM model is the final piece of the presence choreography puzzle — realistic read receipts (v1.3), distraction pauses (v1.3), circadian rhythm (v1.3), and now typing duration.
+
+### Usage
+```ts
+import { PresenceChoreographer } from 'baileys-antiban';
+
+const choreo = new PresenceChoreographer({
+  enabled: true,
+  enableTypingModel: true,
+  typingWPM: 45,             // Average human typing speed
+  typingWPMStdDev: 15,       // Variance (slow/fast days)
+  thinkPauseProbability: 0.08,
+  thinkPauseMinMs: 800,
+  thinkPauseMaxMs: 3500,
+});
+
+// Before sending a message
+const messageText = "Hello, how are you doing today?";
+const plan = choreo.computeTypingPlan(messageText.length);
+
+// Execute typing plan
+await choreo.executeTypingPlan(sock, jid, plan);
+
+// Send actual message
+await sock.sendMessage(jid, { text: messageText });
+```
+
+### Technical Details
+- Plan structure: `Array<{ state: 'composing' | 'paused', durationMs: number }>`
+- WPM → chars/sec conversion: `(WPM × 5) / 60` (industry standard: 5 chars/word)
+- Think pauses are extras, not subtracted from base typing time (20% budget slack)
+- Composing chunks coalesced when no pause injected between them
+- AbortSignal cleanup: sets presence to `paused` before throwing
+- All existing PresenceChoreographer features remain unchanged and backward compatible
+
+## [3.3.0] — 2026-04-26
+
+### Added
+- **`JidCanonicalizer.canonicalKey(jid)`** — Returns stable thread key for DB storage/indexing
+  - Solves the split-thread bug from Baileys v7 LID migration ([#1832](https://github.com/WhiskeySockets/Baileys/issues/1832))
+  - Always returns same key regardless of whether message arrives as `@lid` or `@s.whatsapp.net`
+  - Format: `thread:<digits>` for known contacts, `thread:lid:<digits>` for unknown, `thread:group:<id>` for groups
+  - Uses learned LID↔PN mappings when available, falls back to LID form when not
+  - Handles edge cases: groups, broadcasts, newsletters, empty/null inputs
+  - Tracks stats: `canonicalKeyHits` (PN known) vs `canonicalKeyMisses` (LID only)
+- **`docs/lid-migration.md`** — Comprehensive guide for surviving Baileys v7's LID migration
+  - Explains the three major bugs LID causes (#1832 split-thread, #1718 phone lookup, #2030 call routing)
+  - Full integration examples: learning from events, canonicalizing sends, stable DB keys
+  - Production setup with persistence, stats logging, cleanup
+  - Limitations and best practices
+
+### Why v3.3
+Baileys v7 made `@lid` the default JID format, but many apps still use `remoteJid` as their database thread key. This causes the same conversation to appear as two separate threads when messages arrive under different forms. `canonicalKey()` provides a stable, form-independent identifier that prevents this split-thread bug. The LID migration doc owns the narrative for the v7 transition.
+
 ## [3.2.0] — 2026-04-26
 
 ### New Features

package/README.md

@@ -9,6 +9,8 @@
 
 > Rate limiting with Gaussian jitter, 7-day warmup, session health monitoring, LID resolver, disconnect classification, contact graph enforcement — all in one `npm install`. Works with [Baileys](https://github.com/WhiskeySockets/Baileys) and [@oxidezap/baileyrs](https://github.com/oxidezap/baileyrs) (Rust/WASM).
 
+> **New in v3.3:** [LID Migration Guide](./docs/lid-migration.md) — survive Baileys v7's @lid default with stable thread keys.
+
 ## v2.0 New Features — Session Stability Module
 
 ### What's New in v2.0
@@ -324,6 +326,42 @@ const antiban = new AntiBan({
 // No manual intervention needed
 ```
 
+#### WPM Typing Model (v3.4+)
+
+Real humans typing a 200-character message take 30-60 seconds with multiple `composing`/`paused` cycles. Bots that fire `composing` then immediately send (or never fire it) are detectable.
+
+```typescript
+import { PresenceChoreographer } from 'baileys-antiban';
+
+const choreo = new PresenceChoreographer({
+  enabled: true,
+  enableTypingModel: true,
+  typingWPM: 45,             // Average human typing speed
+  typingWPMStdDev: 15,       // Variance (slow/fast days)
+  thinkPauseProbability: 0.08, // 8% chance of mid-typing pause per 10 chars
+  thinkPauseMinMs: 800,
+  thinkPauseMaxMs: 3500,
+});
+
+// Before sending
+const messageText = "Hello, how are you doing today?";
+const plan = choreo.computeTypingPlan(messageText.length);
+
+// Execute typing plan (sends composing/paused updates)
+await choreo.executeTypingPlan(sock, jid, plan);
+
+// Send message
+await sock.sendMessage(jid, { text: messageText });
+```
+
+**How it works:**
+1. Samples WPM from Gaussian distribution (default: 45 WPM ± 15 stdDev)
+2. Converts to realistic typing duration: `(messageLength / charsPerSec) * 1000`
+3. Injects "think pauses" (0.8-3.5s) mid-typing at 8% probability per 10 chars
+4. Returns plan: `[{ state: 'composing', durationMs: 4200 }, { state: 'paused', durationMs: 950 }, ...]`
+5. Executes plan: fires `sendPresenceUpdate('composing'/'paused')` + sleeps for each step
+6. Supports AbortSignal for mid-plan cancellation
+
 **Why these features?** 2025-2026 ban research showed WhatsApp's ML models heavily weight reply-ratio (<10% = high risk), contact-graph distance (strangers = high risk), and temporal patterns (robotic timing = high risk). These modules address the three largest gaps in existing anti-ban libraries.
 
 ## baileys-antiban vs Whapi.Cloud vs DIY rate limiting

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { HealthMonitor, type HealthStatus, type HealthMonitorConfig, type BanRis
 export { TimelockGuard, type TimelockGuardConfig, type TimelockState } from './timelockGuard.js';
 export { ReplyRatioGuard, type ReplyRatioConfig, type ReplyRatioStats } from './replyRatio.js';
 export { ContactGraphWarmer, type ContactGraphConfig, type ContactGraphStats, type ContactState } from './contactGraph.js';
-export { PresenceChoreographer, type PresenceChoreographerConfig, type PresenceChoreographerStats } from './presenceChoreographer.js';
+export { PresenceChoreographer, type PresenceChoreographerConfig, type PresenceChoreographerStats, type TypingPlanStep } from './presenceChoreographer.js';
 export { RetryReasonTracker, type RetryTrackerConfig, type RetryStats, type RetryReason } from './retryTracker.js';
 export { PostReconnectThrottle, type ReconnectThrottleConfig, type ReconnectThrottleStats } from './reconnectThrottle.js';
 export { LidResolver, type LidResolverConfig, type LidResolverStats, type LidMapping } from './lidResolver.js';

package/dist/jidCanonicalizer.d.ts

@@ -39,6 +39,8 @@ export interface JidCanonicalizerStats {
     outboundCanonicalized: number;
     outboundPassthrough: number;
     inboundLearned: number;
+    canonicalKeyHits: number;
+    canonicalKeyMisses: number;
 }
 export declare class JidCanonicalizer {
     private config;
@@ -54,6 +56,23 @@ export declare class JidCanonicalizer {
      * Called by wrapper on every outbound send. Returns canonical JID.
      */
     canonicalizeTarget(jid: string): string;
+    /**
+     * Returns a stable, canonical thread key for storage / DB indexing.
+     *
+     * Different from `canonicalizeTarget()` (which picks the right send target):
+     * - canonicalizeTarget('1234@lid') → '+27...@s.whatsapp.net' (best send target)
+     * - canonicalKey('1234@lid')      → 'thread:27...'  (stable thread identifier)
+     *
+     * If LID has known PN mapping → use phone-number form
+     * If only LID known → use LID stripped of suffix
+     * Always lowercase, no @-suffix, prefixed with `thread:`
+     *
+     * Apps using this as their DB key won't double-thread on LID/PN drift.
+     *
+     * @param jid - WhatsApp JID (can be PN, LID, group, or broadcast)
+     * @returns Stable thread key for DB indexing
+     */
+    canonicalKey(jid: string): string;
     /**
      * Called by wrapper on messages.upsert event. Learns mappings.
      */

package/dist/jidCanonicalizer.js

@@ -35,6 +35,8 @@ export class JidCanonicalizer {
         outboundCanonicalized: 0,
         outboundPassthrough: 0,
         inboundLearned: 0,
+        canonicalKeyHits: 0,
+        canonicalKeyMisses: 0,
     };
     constructor(config = {}) {
         this.config = { ...DEFAULT_CONFIG, ...config };
@@ -70,6 +72,72 @@ export class JidCanonicalizer {
         }
         return canonical;
     }
+    /**
+     * Returns a stable, canonical thread key for storage / DB indexing.
+     *
+     * Different from `canonicalizeTarget()` (which picks the right send target):
+     * - canonicalizeTarget('1234@lid') → '+27...@s.whatsapp.net' (best send target)
+     * - canonicalKey('1234@lid')      → 'thread:27...'  (stable thread identifier)
+     *
+     * If LID has known PN mapping → use phone-number form
+     * If only LID known → use LID stripped of suffix
+     * Always lowercase, no @-suffix, prefixed with `thread:`
+     *
+     * Apps using this as their DB key won't double-thread on LID/PN drift.
+     *
+     * @param jid - WhatsApp JID (can be PN, LID, group, or broadcast)
+     * @returns Stable thread key for DB indexing
+     */
+    canonicalKey(jid) {
+        // Defensive: handle null/undefined/empty
+        if (!jid || typeof jid !== 'string' || jid.trim() === '') {
+            return 'thread:invalid';
+        }
+        const normalized = jid.trim().toLowerCase();
+        // Extract parts: user@domain
+        const atIndex = normalized.indexOf('@');
+        if (atIndex === -1) {
+            return 'thread:invalid';
+        }
+        const user = normalized.substring(0, atIndex);
+        const domain = normalized.substring(atIndex + 1);
+        // Handle special domains
+        if (domain === 'g.us') {
+            // Group chat
+            return `thread:group:${user}`;
+        }
+        if (domain === 'broadcast') {
+            // Broadcast list
+            return `thread:broadcast:${user}`;
+        }
+        if (domain === 'newsletter') {
+            // Newsletter (WA Channels)
+            return `thread:newsletter:${user}`;
+        }
+        // Handle @s.whatsapp.net (PN form)
+        if (domain === 's.whatsapp.net') {
+            this.stats.canonicalKeyHits++;
+            return `thread:${user}`;
+        }
+        // Handle @lid form
+        if (domain === 'lid') {
+            // Try to resolve to PN via learned mappings
+            const mapping = this.lidResolver.getMapping(normalized);
+            if (mapping?.pn) {
+                // We have a PN mapping — use it
+                const pnUser = mapping.pn.split('@')[0];
+                this.stats.canonicalKeyHits++;
+                return `thread:${pnUser}`;
+            }
+            else {
+                // No PN known yet — use LID form
+                this.stats.canonicalKeyMisses++;
+                return `thread:lid:${user}`;
+            }
+        }
+        // Unknown domain — return generic form
+        return `thread:${domain}:${user}`;
+    }
     /**
      * Called by wrapper on messages.upsert event. Learns mappings.
      */
@@ -102,6 +170,8 @@ export class JidCanonicalizer {
             outboundCanonicalized: this.stats.outboundCanonicalized,
             outboundPassthrough: this.stats.outboundPassthrough,
             inboundLearned: this.stats.inboundLearned,
+            canonicalKeyHits: this.stats.canonicalKeyHits,
+            canonicalKeyMisses: this.stats.canonicalKeyMisses,
         };
     }
     destroy() {

package/dist/presenceChoreographer.d.ts

@@ -39,6 +39,24 @@ export interface PresenceChoreographerConfig {
     offlineGapMinMs?: number;
     /** Max offline gap duration in ms (default: 900000 = 15min) */
     offlineGapMaxMs?: number;
+    /** Enable WPM-based typing duration model (default: true when enabled) */
+    enableTypingModel?: boolean;
+    /** Mean typing speed in words per minute (default: 45) */
+    typingWPM?: number;
+    /** Std dev around the mean WPM (default: 15) — humans vary a lot */
+    typingWPMStdDev?: number;
+    /** Probability of "thinking pause" mid-typing per 10 chars (default: 0.08) */
+    thinkPauseProbability?: number;
+    /** Min think pause ms (default: 800) */
+    thinkPauseMinMs?: number;
+    /** Max think pause ms (default: 3500) */
+    thinkPauseMaxMs?: number;
+    /** Probability bot ALSO fires 'paused' state mid-cycle (default: 0.4) */
+    intermittentPausedProbability?: number;
+    /** Cap on total typing duration regardless of message length (default: 90_000 = 90s) */
+    typingMaxMs?: number;
+    /** Min typing duration even for short messages (default: 600 = 0.6s) */
+    typingMinMs?: number;
 }
 export interface PresenceChoreographerStats {
     currentActivityFactor: number;
@@ -47,6 +65,13 @@ export interface PresenceChoreographerStats {
     readReceiptsDelayed: number;
     readReceiptsSkipped: number;
     currentHourLocal: number;
+    typingPlansComputed: number;
+    typingPlansExecuted: number;
+    totalTypingTimeMs: number;
+}
+export interface TypingPlanStep {
+    state: 'composing' | 'paused';
+    durationMs: number;
 }
 export declare class PresenceChoreographer {
     private config;
@@ -83,6 +108,31 @@ export declare class PresenceChoreographer {
         mark: boolean;
         delayMs: number;
     };
+    /**
+     * Compute realistic typing duration for a message of given length.
+     * Includes Gaussian WPM variance + think-pause injection.
+     * Returns a "typing plan": array of { state, durationMs } steps the caller should execute sequentially.
+     *
+     *   plan = [
+     *     { state: 'composing', durationMs: 4200 },
+     *     { state: 'paused',    durationMs: 950 },   // think pause
+     *     { state: 'composing', durationMs: 6800 },
+     *     { state: 'paused',    durationMs: 600 },   // brief stop before send
+     *   ]
+     */
+    computeTypingPlan(messageLength: number): TypingPlanStep[];
+    /**
+     * Execute a typing plan against a Baileys-shaped sock with sendPresenceUpdate(state, jid).
+     * Awaits each step's duration. Updates stats.
+     *
+     *   await choreo.executeTypingPlan(sock, jid, plan);
+     *   await sock.sendMessage(jid, content);
+     */
+    executeTypingPlan(sock: {
+        sendPresenceUpdate: (state: string, jid: string) => Promise<void> | void;
+    }, jid: string, plan: TypingPlanStep[], options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
     /**
      * Get statistics.
      */
@@ -93,4 +143,11 @@ export declare class PresenceChoreographer {
     reset(): void;
     private getLocalHour;
     private randomBetween;
+    private clamp;
+    /**
+     * Generate Gaussian sample using Box-Muller transform.
+     * Returns a sample from N(mean, stdDev).
+     */
+    private gaussianSample;
+    private sleep;
 }

package/dist/presenceChoreographer.js

@@ -26,6 +26,15 @@ const DEFAULT_CONFIG = {
     offlineGapProbability: 0.03,
     offlineGapMinMs: 300000,
     offlineGapMaxMs: 900000,
+    enableTypingModel: true,
+    typingWPM: 45,
+    typingWPMStdDev: 15,
+    thinkPauseProbability: 0.08,
+    thinkPauseMinMs: 800,
+    thinkPauseMaxMs: 3500,
+    intermittentPausedProbability: 0.4,
+    typingMaxMs: 90000,
+    typingMinMs: 600,
 };
 /**
  * Activity curves (0.1 to 1.0 multipliers by hour)
@@ -70,6 +79,9 @@ export class PresenceChoreographer {
         offlineGapsInjected: 0,
         readReceiptsDelayed: 0,
         readReceiptsSkipped: 0,
+        typingPlansComputed: 0,
+        typingPlansExecuted: 0,
+        totalTypingTimeMs: 0,
     };
     constructor(config = {}) {
         this.config = { ...DEFAULT_CONFIG, ...config };
@@ -136,6 +148,106 @@ export class PresenceChoreographer {
         this.stats.readReceiptsDelayed++;
         return { mark: true, delayMs };
     }
+    /**
+     * Compute realistic typing duration for a message of given length.
+     * Includes Gaussian WPM variance + think-pause injection.
+     * Returns a "typing plan": array of { state, durationMs } steps the caller should execute sequentially.
+     *
+     *   plan = [
+     *     { state: 'composing', durationMs: 4200 },
+     *     { state: 'paused',    durationMs: 950 },   // think pause
+     *     { state: 'composing', durationMs: 6800 },
+     *     { state: 'paused',    durationMs: 600 },   // brief stop before send
+     *   ]
+     */
+    computeTypingPlan(messageLength) {
+        if (!this.config.enabled || !this.config.enableTypingModel) {
+            return [{ state: 'composing', durationMs: this.config.typingMinMs }];
+        }
+        this.stats.typingPlansComputed++;
+        // Handle empty message
+        if (messageLength === 0) {
+            return [{ state: 'composing', durationMs: this.config.typingMinMs }];
+        }
+        // 1. Sample WPM from Gaussian distribution
+        const wpmSample = this.clamp(this.gaussianSample(this.config.typingWPM, this.config.typingWPMStdDev), 10, 120);
+        // 2. Convert to chars/sec (WPM standard: 5 chars/word)
+        const cps = (wpmSample * 5) / 60;
+        // 3. Base typing time
+        const baseMs = (messageLength / cps) * 1000;
+        // 4. Clamp to min/max
+        const targetMs = this.clamp(baseMs, this.config.typingMinMs, this.config.typingMaxMs);
+        // 5. Build plan with think pauses
+        const plan = [];
+        let remainingBudget = targetMs;
+        let position = 0;
+        // Walk through message in chunks of 10 chars
+        const chunkSize = 10;
+        const numChunks = Math.max(1, Math.ceil(messageLength / chunkSize));
+        for (let i = 0; i < numChunks && remainingBudget > 0; i++) {
+            const charsInChunk = Math.min(chunkSize, messageLength - position);
+            // Distribute remaining budget proportionally across remaining chunks
+            const remainingChunks = numChunks - i;
+            const chunkBudget = remainingBudget / remainingChunks;
+            const chunkTypingMs = Math.floor(Math.min(chunkBudget, remainingBudget));
+            if (chunkTypingMs <= 0)
+                break;
+            // Should we inject a think pause after this chunk?
+            if (i > 0 && i < numChunks - 1 && Math.random() < this.config.thinkPauseProbability) {
+                // Add composing step
+                plan.push({ state: 'composing', durationMs: chunkTypingMs });
+                remainingBudget -= chunkTypingMs;
+                // Add think pause (don't subtract from typing budget)
+                const pauseMs = this.randomBetween(this.config.thinkPauseMinMs, this.config.thinkPauseMaxMs);
+                plan.push({ state: 'paused', durationMs: pauseMs });
+            }
+            else {
+                // Accumulate typing time
+                if (plan.length === 0 || plan[plan.length - 1].state === 'paused') {
+                    plan.push({ state: 'composing', durationMs: chunkTypingMs });
+                }
+                else {
+                    plan[plan.length - 1].durationMs += chunkTypingMs;
+                }
+                remainingBudget -= chunkTypingMs;
+            }
+            position += charsInChunk;
+        }
+        // 6. Optional final pause before send
+        if (Math.random() < this.config.intermittentPausedProbability) {
+            const finalPauseMs = this.randomBetween(200, 800);
+            plan.push({ state: 'paused', durationMs: finalPauseMs });
+        }
+        // Ensure we have at least one composing step
+        if (plan.length === 0 || !plan.some(step => step.state === 'composing')) {
+            return [{ state: 'composing', durationMs: this.config.typingMinMs }];
+        }
+        return plan;
+    }
+    /**
+     * Execute a typing plan against a Baileys-shaped sock with sendPresenceUpdate(state, jid).
+     * Awaits each step's duration. Updates stats.
+     *
+     *   await choreo.executeTypingPlan(sock, jid, plan);
+     *   await sock.sendMessage(jid, content);
+     */
+    async executeTypingPlan(sock, jid, plan, options) {
+        this.stats.typingPlansExecuted++;
+        for (const step of plan) {
+            // Check abort signal
+            if (options?.signal?.aborted) {
+                // Restore presence to paused before throwing
+                await Promise.resolve(sock.sendPresenceUpdate('paused', jid));
+                throw new Error('Typing plan aborted');
+            }
+            // Update presence
+            await Promise.resolve(sock.sendPresenceUpdate(step.state, jid));
+            // Sleep for duration
+            await this.sleep(step.durationMs);
+            // Track total typing time
+            this.stats.totalTypingTimeMs += step.durationMs;
+        }
+    }
     /**
      * Get statistics.
      */
@@ -147,6 +259,9 @@ export class PresenceChoreographer {
             readReceiptsDelayed: this.stats.readReceiptsDelayed,
             readReceiptsSkipped: this.stats.readReceiptsSkipped,
             currentHourLocal: this.getLocalHour(),
+            typingPlansComputed: this.stats.typingPlansComputed,
+            typingPlansExecuted: this.stats.typingPlansExecuted,
+            totalTypingTimeMs: this.stats.totalTypingTimeMs,
         };
     }
     /**
@@ -158,6 +273,9 @@ export class PresenceChoreographer {
             offlineGapsInjected: 0,
             readReceiptsDelayed: 0,
             readReceiptsSkipped: 0,
+            typingPlansComputed: 0,
+            typingPlansExecuted: 0,
+            totalTypingTimeMs: 0,
         };
     }
     // Private helpers
@@ -184,4 +302,21 @@ export class PresenceChoreographer {
     randomBetween(min, max) {
         return Math.floor(Math.random() * (max - min + 1)) + min;
     }
+    clamp(value, min, max) {
+        return Math.max(min, Math.min(max, value));
+    }
+    /**
+     * Generate Gaussian sample using Box-Muller transform.
+     * Returns a sample from N(mean, stdDev).
+     */
+    gaussianSample(mean, stdDev) {
+        // Box-Muller transform
+        const u1 = Math.random();
+        const u2 = Math.random();
+        const z0 = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+        return mean + z0 * stdDev;
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baileys-antiban",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "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",