baileys-antiban 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -5,6 +5,126 @@ 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.5.0] — 2026-04-26
+
+### Added
+- **proxyRotator** — Native proxy injection with multi-strategy rotation and health tracking
+  - Closes the datacenter IP ban vector — WhatsApp's ML flags VPS IPs, residential/4G proxies stay alive
+  - Supports SOCKS5, SOCKS5H, HTTP, HTTPS proxies with auth
+  - 4 rotation strategies: round-robin, random, least-recently-used, weighted (by health)
+  - Auto-failover on endpoint failure with configurable dead thresholds (default: 3 failures)
+  - Health tracking: failure counters, dead-marking, auto-resurrection after cooldown (default: 10min)
+  - Per-endpoint cooldown periods to avoid hammering proxy providers
+  - Scheduled rotation for proactive IP rotation (configurable interval)
+  - Rotation triggers: manual, disconnect, ban-warning, scheduled (user-wired)
+  - Lazy-loaded proxy agent dependencies (optional peerDeps: socks-proxy-agent, http-proxy-agent, https-proxy-agent)
+  - Agent caching for performance (avoids re-creating agents on every request)
+  - Comprehensive stats: total rotations, per-trigger breakdowns, endpoint health dashboard
+  - Production-ready error handling: graceful fallback when peer deps missing
+
+### Fixed
+- **proxyRotator**: Fixed ESM `require()` regression by using `createRequire()` from `node:module` for ESM-compatible synchronous module loading (caught by live SOCKS5 smoke test before publish)
+
+### Why v3.5
+Per GapHunter analysis, WhatsApp's ban detection includes IP reputation scoring. Datacenter IPs (VPS) are flagged. Residential/4G proxies stay alive. Every Baileys implementation uses DIY proxy hacks — no library handles native proxy injection. `proxyRotator` closes that gap with production-grade rotation strategies, health tracking, and auto-failover.
+
+### Usage
+```ts
+import { proxyRotator } from 'baileys-antiban';
+import { makeWASocket } from 'baileys';
+
+const rotator = proxyRotator({
+  pool: [
+    { type: 'socks5', host: 'proxy1.example.com', port: 1080, username: 'user', password: 'pass', label: 'Proxy1' },
+    { type: 'socks5', host: 'proxy2.example.com', port: 1080, username: 'user', password: 'pass', label: 'Proxy2', cooldownMs: 300_000 },
+  ],
+  strategy: 'weighted', // Prefer healthier endpoints
+  rotateOn: ['disconnect', 'ban-warning'],
+  maxFailures: 3,
+  deadCooldownMs: 600_000, // 10 minutes
+});
+
+const sock = makeWASocket({
+  auth: state,
+  fetchAgent: rotator.currentAgent(), // Inject proxy into Baileys fetch
+});
+
+// Wire disconnect rotation
+sock.ev.on('connection.update', ({ connection }) => {
+  if (connection === 'close') {
+    rotator.rotate('disconnect');
+  }
+});
+
+// Wire ban-warning rotation (from sessionStability)
+monitor.onDegraded = () => {
+  rotator.rotate('ban-warning');
+};
+
+// Check stats
+console.log(rotator.getStats());
+```
+
+### Technical Details
+- Agent caching: agents are created once per endpoint and reused until rotation
+- Cooldown logic: endpoints are skipped if `Date.now() - lastUsedAt < cooldownMs`
+- Dead resurrection: auto-checks on rotation if `Date.now() - lastUsedAt >= deadCooldownMs`
+- Weighted strategy: `weight = 1 / (failures + 1)` for probabilistic health-biased selection
+- LRU strategy: prioritizes never-used endpoints, then oldest `lastUsedAt`
+- Peer dep handling: uses `require()` with try/catch, logs clear error on missing deps
+- Pool size 1: logs warning once, rotation becomes no-op
+- All endpoints dead: `currentAgent()` returns `null`, user code must handle
+
+## [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

package/README.md

@@ -203,6 +203,91 @@ console.log(stats.throttledSendCount);   // Sends gated since reconnect
 
 **Why?** When WhatsApp reconnects after a disconnection, sending messages at full rate immediately can trigger rate limit alarms. The reconnect throttle gradually ramps up sending rate over 60 seconds, mimicking how a human would resume messaging after their internet came back.
 
+## Proxy Rotation (v3.5)
+
+WhatsApp's ban detection includes **IP reputation scoring**. Datacenter IPs (VPS) are flagged. Residential/4G proxies stay alive. No Baileys library handles native proxy injection — every implementation uses DIY hacks. `proxyRotator` closes that gap.
+
+### Features
+- Multi-strategy rotation: round-robin, random, least-recently-used, weighted (by health)
+- Auto-failover on endpoint failure
+- Health tracking with auto-resurrection after cooldown
+- Per-endpoint cooldown periods
+- Scheduled rotation for proactive IP rotation
+- Supports SOCKS5, SOCKS5H, HTTP, HTTPS proxies with auth
+
+### Basic Usage
+
+```typescript
+import { proxyRotator } from 'baileys-antiban';
+import { makeWASocket } from 'baileys';
+
+const rotator = proxyRotator({
+  pool: [
+    {
+      type: 'socks5',
+      host: 'proxy1.example.com',
+      port: 1080,
+      username: 'user',
+      password: 'pass',
+      label: 'Proxy1',
+    },
+    {
+      type: 'socks5',
+      host: 'proxy2.example.com',
+      port: 1080,
+      username: 'user',
+      password: 'pass',
+      label: 'Proxy2',
+      cooldownMs: 300_000, // 5-minute cooldown
+    },
+  ],
+  strategy: 'weighted', // Prefer healthier endpoints
+  rotateOn: ['disconnect', 'ban-warning'],
+  maxFailures: 3,
+  deadCooldownMs: 600_000, // 10 minutes
+});
+
+const sock = makeWASocket({
+  auth: state,
+  fetchAgent: rotator.currentAgent(), // Inject proxy
+});
+
+// Wire disconnect rotation
+sock.ev.on('connection.update', ({ connection }) => {
+  if (connection === 'close') {
+    rotator.rotate('disconnect');
+  }
+});
+
+// Check stats
+console.log(rotator.getStats());
+```
+
+### Advanced: Scheduled Rotation
+
+```typescript
+const rotator = proxyRotator({
+  pool: [...proxies],
+  rotateOn: ['scheduled', 'disconnect'],
+  scheduledIntervalMs: 3_600_000, // Rotate every hour
+  strategy: 'least-recently-used',
+});
+
+// Auto-rotates every hour + on disconnects
+```
+
+### Peer Dependencies
+
+Install proxy agent libraries for the protocols you use:
+
+```bash
+npm install socks-proxy-agent      # For SOCKS5/SOCKS5H
+npm install http-proxy-agent       # For HTTP
+npm install https-proxy-agent      # For HTTPS
+```
+
+All are optional peerDeps — only install what you need.
+
 ## LID / Phone Number Canonicalization
 
 WhatsApp migrated to **Linked Identity (LID)** in 2024. A contact now has two JID forms:
@@ -326,6 +411,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';
@@ -35,3 +35,4 @@ export { messageRecovery, type MessageRecoveryConfig, type MessageRecoveryStats,
 export { generateFingerprint, applyFingerprint, type DeviceFingerprint, type DeviceFingerprintConfig, } from './deviceFingerprint.js';
 export { credsSnapshot, type CredsSnapshot, type CredsSnapshotConfig, } from './credsSnapshot.js';
 export { readReceiptVariance, type ReadReceiptVariance, type ReadReceiptVarianceConfig, } from './readReceiptVariance.js';
+export { proxyRotator, type ProxyEndpoint, type ProxyRotatorConfig, type ProxyRotatorStats, type ProxyRotatorHandle, } from './proxyRotator.js';

package/dist/index.js

@@ -47,3 +47,5 @@ export { messageRecovery } from './messageRecovery.js';
 export { generateFingerprint, applyFingerprint, } from './deviceFingerprint.js';
 export { credsSnapshot, } from './credsSnapshot.js';
 export { readReceiptVariance, } from './readReceiptVariance.js';
+// v3.5 new modules
+export { proxyRotator, } from './proxyRotator.js';

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/dist/proxyRotator.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Proxy Rotation — Native proxy injection for Baileys with health tracking
+ *
+ * WhatsApp's ban detection includes IP reputation scoring. Datacenter IPs (VPS)
+ * are flagged, while residential/4G proxies stay alive. No Baileys library handles
+ * native proxy injection — every implementation is DIY hacks. We close that gap.
+ *
+ * Features:
+ * - Multi-strategy rotation (round-robin, random, LRU, weighted)
+ * - Auto-failover on endpoint failure
+ * - Scheduled rotation for proactive IP rotation
+ * - Cooldown periods between endpoint reuse
+ * - Health tracking and auto-resurrection
+ * - Lazy-loaded proxy agent dependencies (optional peerDeps)
+ *
+ * @author Kobus Wentzel <kobie@pop.co.za>
+ * @license MIT
+ */
+import type { Agent } from 'node:http';
+export interface ProxyEndpoint {
+    type: 'socks5' | 'socks5h' | 'http' | 'https';
+    host: string;
+    port: number;
+    username?: string;
+    password?: string;
+    /** Optional health label — humans use this in logs */
+    label?: string;
+    /** Cooldown after last use, in ms (default: 0) */
+    cooldownMs?: number;
+}
+export interface ProxyRotatorConfig {
+    /** Pool of proxy endpoints. Required. */
+    pool: ProxyEndpoint[];
+    /** Strategy for picking next proxy (default: 'round-robin') */
+    strategy?: 'round-robin' | 'random' | 'least-recently-used' | 'weighted';
+    /** Auto-rotate on these triggers (default: ['disconnect', 'ban-warning']) */
+    rotateOn?: Array<'disconnect' | 'ban-warning' | 'scheduled' | 'manual'>;
+    /** Scheduled rotation interval in ms (only if rotateOn includes 'scheduled') */
+    scheduledIntervalMs?: number;
+    /** Max consecutive failures before marking endpoint dead (default: 3) */
+    maxFailures?: number;
+    /** How long a "dead" endpoint stays out of rotation (default: 600_000 = 10min) */
+    deadCooldownMs?: number;
+    /** Logger */
+    logger?: {
+        info?: Function;
+        warn?: Function;
+        error?: Function;
+    };
+}
+export interface ProxyRotatorStats {
+    totalRotations: number;
+    rotationsByTrigger: Record<string, number>;
+    endpointHealth: Array<{
+        label: string;
+        inUse: boolean;
+        failures: number;
+        lastUsedAt: Date | null;
+        isDead: boolean;
+    }>;
+    currentEndpoint: string | null;
+}
+export interface ProxyRotatorHandle {
+    /** Get an Agent for the current endpoint. Use this in fetchOptions.agent or makeWASocket's options.agent */
+    currentAgent(): Agent | null;
+    /** Get the current endpoint's metadata */
+    current(): ProxyEndpoint | null;
+    /** Force rotate to next endpoint. Reason logged in stats. */
+    rotate(reason?: 'manual' | 'disconnect' | 'ban-warning' | 'scheduled'): ProxyEndpoint | null;
+    /** Mark current endpoint as failed (increments failure counter, may auto-rotate) */
+    markFailure(): void;
+    /** Clear all dead-flags (e.g. for cooldown override) */
+    resurrectAll(): void;
+    /** Stop scheduled rotation timer + dispose */
+    stop(): void;
+    /** Stats */
+    getStats(): ProxyRotatorStats;
+}
+export declare function proxyRotator(config: ProxyRotatorConfig): ProxyRotatorHandle;

package/dist/proxyRotator.js

@@ -0,0 +1,295 @@
+/**
+ * Proxy Rotation — Native proxy injection for Baileys with health tracking
+ *
+ * WhatsApp's ban detection includes IP reputation scoring. Datacenter IPs (VPS)
+ * are flagged, while residential/4G proxies stay alive. No Baileys library handles
+ * native proxy injection — every implementation is DIY hacks. We close that gap.
+ *
+ * Features:
+ * - Multi-strategy rotation (round-robin, random, LRU, weighted)
+ * - Auto-failover on endpoint failure
+ * - Scheduled rotation for proactive IP rotation
+ * - Cooldown periods between endpoint reuse
+ * - Health tracking and auto-resurrection
+ * - Lazy-loaded proxy agent dependencies (optional peerDeps)
+ *
+ * @author Kobus Wentzel <kobie@pop.co.za>
+ * @license MIT
+ */
+import { createRequire } from 'node:module';
+// Create require for optional peer dependency loading in ESM
+const require = createRequire(import.meta.url);
+const NoopLogger = {
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+export function proxyRotator(config) {
+    const { pool, strategy = 'round-robin', rotateOn = ['disconnect', 'ban-warning'], scheduledIntervalMs = 0, maxFailures = 3, deadCooldownMs = 600_000, // 10 minutes
+    logger = NoopLogger, } = config;
+    if (!pool || pool.length === 0) {
+        throw new Error('proxyRotator: pool cannot be empty');
+    }
+    // Warn once for pool size 1
+    if (pool.length === 1) {
+        logger.warn?.('proxyRotator: pool size is 1. Rotation is a no-op.');
+    }
+    // Warn for aggressive scheduled rotation
+    if (scheduledIntervalMs > 0 && scheduledIntervalMs < 60_000) {
+        logger.warn?.(`proxyRotator: scheduledIntervalMs (${scheduledIntervalMs}ms) is < 60s. May hammer proxy provider.`);
+    }
+    // Internal state
+    const states = pool.map((endpoint) => ({
+        endpoint,
+        failures: 0,
+        lastUsedAt: null,
+        isDead: false,
+    }));
+    let currentIndex = 0;
+    let totalRotations = 0;
+    const rotationsByTrigger = {};
+    let scheduledTimer = null;
+    // Agent cache: map endpoint -> Agent (cleared on rotation)
+    const agentCache = new Map();
+    // Module cache for lazy-loaded proxy agents
+    const moduleCache = {};
+    function buildProxyUrl(endpoint) {
+        const { type, host, port, username, password } = endpoint;
+        const auth = username && password ? `${username}:${password}@` : '';
+        return `${type}://${auth}${host}:${port}`;
+    }
+    function createAgentForEndpointSync(endpoint) {
+        // Check cache first
+        if (agentCache.has(endpoint)) {
+            return agentCache.get(endpoint);
+        }
+        const url = buildProxyUrl(endpoint);
+        let agent = null;
+        try {
+            if (endpoint.type === 'socks5' || endpoint.type === 'socks5h') {
+                if (!moduleCache['socks-proxy-agent']) {
+                    try {
+                        moduleCache['socks-proxy-agent'] = require('socks-proxy-agent');
+                    }
+                    catch {
+                        logger.error?.('socks-proxy-agent not installed. Run: npm install socks-proxy-agent');
+                        return null;
+                    }
+                }
+                agent = new moduleCache['socks-proxy-agent'].SocksProxyAgent(url);
+            }
+            else if (endpoint.type === 'http') {
+                if (!moduleCache['http-proxy-agent']) {
+                    try {
+                        moduleCache['http-proxy-agent'] = require('http-proxy-agent');
+                    }
+                    catch {
+                        logger.error?.('http-proxy-agent not installed. Run: npm install http-proxy-agent');
+                        return null;
+                    }
+                }
+                agent = new moduleCache['http-proxy-agent'].HttpProxyAgent(url);
+            }
+            else if (endpoint.type === 'https') {
+                if (!moduleCache['https-proxy-agent']) {
+                    try {
+                        moduleCache['https-proxy-agent'] = require('https-proxy-agent');
+                    }
+                    catch {
+                        logger.error?.('https-proxy-agent not installed. Run: npm install https-proxy-agent');
+                        return null;
+                    }
+                }
+                agent = new moduleCache['https-proxy-agent'].HttpsProxyAgent(url);
+            }
+            else {
+                logger.error?.(`Unknown proxy type: ${endpoint.type}`);
+                return null;
+            }
+            // Cache the agent
+            if (agent) {
+                agentCache.set(endpoint, agent);
+            }
+            return agent;
+        }
+        catch (err) {
+            logger.error?.(`Failed to create agent for ${endpoint.label || endpoint.host}: ${err}`);
+            return null;
+        }
+    }
+    function getAliveEndpoints() {
+        const now = Date.now();
+        return states
+            .map((s, idx) => {
+            // Dead check with auto-resurrection
+            if (s.isDead && s.lastUsedAt) {
+                if (now - s.lastUsedAt.getTime() >= deadCooldownMs) {
+                    s.isDead = false;
+                    s.failures = 0;
+                    logger.info?.(`Resurrected endpoint ${s.endpoint.label || s.endpoint.host} after cooldown`);
+                }
+            }
+            // Cooldown check
+            const cooldown = s.endpoint.cooldownMs || 0;
+            if (cooldown > 0 && s.lastUsedAt) {
+                if (now - s.lastUsedAt.getTime() < cooldown) {
+                    return -1; // Still in cooldown
+                }
+            }
+            return !s.isDead ? idx : -1;
+        })
+            .filter((idx) => idx !== -1);
+    }
+    function selectNextIndex(alive) {
+        if (alive.length === 0)
+            return currentIndex; // All dead, stay on current
+        if (strategy === 'round-robin') {
+            // Pick next after currentIndex in circular fashion
+            const afterCurrent = alive.filter((idx) => idx > currentIndex);
+            if (afterCurrent.length > 0)
+                return afterCurrent[0];
+            return alive[0]; // Wrap around
+        }
+        if (strategy === 'random') {
+            return alive[Math.floor(Math.random() * alive.length)];
+        }
+        if (strategy === 'least-recently-used') {
+            // Pick the one with oldest lastUsedAt (never-used = highest priority)
+            const neverUsed = alive.filter((idx) => states[idx].lastUsedAt === null);
+            if (neverUsed.length > 0) {
+                return neverUsed[0];
+            }
+            let oldestIdx = alive[0];
+            let oldestTime = states[oldestIdx].lastUsedAt.getTime();
+            for (const idx of alive) {
+                const time = states[idx].lastUsedAt.getTime();
+                if (time < oldestTime) {
+                    oldestTime = time;
+                    oldestIdx = idx;
+                }
+            }
+            return oldestIdx;
+        }
+        if (strategy === 'weighted') {
+            // Weighted by inverse failure count (healthier = more likely)
+            const weights = alive.map((idx) => {
+                const failures = states[idx].failures;
+                return 1 / (failures + 1); // Avoid divide-by-zero
+            });
+            const totalWeight = weights.reduce((a, b) => a + b, 0);
+            let rand = Math.random() * totalWeight;
+            for (let i = 0; i < alive.length; i++) {
+                rand -= weights[i];
+                if (rand <= 0)
+                    return alive[i];
+            }
+            return alive[alive.length - 1]; // Fallback
+        }
+        return alive[0]; // Default fallback
+    }
+    function rotateImpl(reason = 'manual') {
+        if (pool.length === 1) {
+            // No-op for single endpoint
+            return states[0].endpoint;
+        }
+        const alive = getAliveEndpoints();
+        if (alive.length === 0) {
+            logger.warn?.('All endpoints are dead. Cannot rotate.');
+            return states[currentIndex].endpoint;
+        }
+        const nextIdx = selectNextIndex(alive);
+        if (nextIdx === currentIndex && alive.length > 1) {
+            // Try to pick a different one if possible
+            const others = alive.filter((idx) => idx !== currentIndex);
+            if (others.length > 0) {
+                currentIndex = others[0];
+            }
+            else {
+                currentIndex = nextIdx;
+            }
+        }
+        else {
+            currentIndex = nextIdx;
+        }
+        states[currentIndex].lastUsedAt = new Date();
+        totalRotations++;
+        rotationsByTrigger[reason] = (rotationsByTrigger[reason] || 0) + 1;
+        const label = states[currentIndex].endpoint.label || states[currentIndex].endpoint.host;
+        logger.info?.(`Rotated to endpoint ${label} (reason: ${reason})`);
+        return states[currentIndex].endpoint;
+    }
+    function markFailureImpl() {
+        const state = states[currentIndex];
+        state.failures++;
+        const label = state.endpoint.label || state.endpoint.host;
+        logger.warn?.(`Endpoint ${label} failed (${state.failures}/${maxFailures})`);
+        if (state.failures >= maxFailures) {
+            state.isDead = true;
+            logger.error?.(`Endpoint ${label} marked DEAD after ${maxFailures} failures`);
+            // Auto-rotate to next alive endpoint
+            const alive = getAliveEndpoints();
+            if (alive.length > 0) {
+                rotateImpl('manual'); // Trigger rotation as recovery
+            }
+        }
+    }
+    function resurrectAllImpl() {
+        let count = 0;
+        for (const state of states) {
+            if (state.isDead) {
+                state.isDead = false;
+                state.failures = 0;
+                count++;
+            }
+        }
+        if (count > 0) {
+            logger.info?.(`Resurrected ${count} dead endpoint(s)`);
+        }
+    }
+    function stopImpl() {
+        if (scheduledTimer) {
+            clearInterval(scheduledTimer);
+            scheduledTimer = null;
+            logger.info?.('Stopped scheduled rotation timer');
+        }
+    }
+    function getStatsImpl() {
+        return {
+            totalRotations,
+            rotationsByTrigger: { ...rotationsByTrigger },
+            endpointHealth: states.map((s) => ({
+                label: s.endpoint.label || s.endpoint.host,
+                inUse: states[currentIndex] === s,
+                failures: s.failures,
+                lastUsedAt: s.lastUsedAt,
+                isDead: s.isDead,
+            })),
+            currentEndpoint: states[currentIndex].endpoint.label || states[currentIndex].endpoint.host,
+        };
+    }
+    function currentAgentImpl() {
+        const endpoint = states[currentIndex].endpoint;
+        return createAgentForEndpointSync(endpoint);
+    }
+    function currentImpl() {
+        return states[currentIndex].endpoint;
+    }
+    // Setup scheduled rotation if enabled
+    if (rotateOn.includes('scheduled') && scheduledIntervalMs > 0) {
+        scheduledTimer = setInterval(() => {
+            rotateImpl('scheduled');
+        }, scheduledIntervalMs);
+        logger.info?.(`Scheduled rotation enabled (every ${scheduledIntervalMs}ms)`);
+    }
+    // Initialize: select first endpoint
+    states[0].lastUsedAt = new Date();
+    return {
+        currentAgent: currentAgentImpl,
+        current: currentImpl,
+        rotate: rotateImpl,
+        markFailure: markFailureImpl,
+        resurrectAll: resurrectAllImpl,
+        stop: stopImpl,
+        getStats: getStatsImpl,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baileys-antiban",
-  "version": "3.3.0",
+  "version": "3.5.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",
@@ -76,6 +76,15 @@
     },
     "@oxidezap/baileyrs": {
       "optional": true
+    },
+    "socks-proxy-agent": {
+      "optional": true
+    },
+    "http-proxy-agent": {
+      "optional": true
+    },
+    "https-proxy-agent": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -86,5 +95,10 @@
     "tsx": "^4.21.0",
     "typescript": "^5.0.0",
     "vitest": "^4.1.5"
+  },
+  "dependencies": {
+    "http-proxy-agent": "^9.0.0",
+    "https-proxy-agent": "^9.0.0",
+    "socks-proxy-agent": "^10.0.0"
   }
 }