baileys-antiban 1.3.1 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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).
 
+## [1.5.0] - 2026-04-18
+
+### Added
+- **RetryReasonTracker** module: Track message retry reasons and detect retry spirals
+  - Classifies 10 retry reason types (no_session, invalid_key, bad_mac, decryption_failure, server_error_463, server_error_429, timeout, no_route, node_malformed, unknown)
+  - Detects retry spirals when same message retries exceed threshold (default: 3)
+  - Provides stats on total retries, retries by reason, spirals detected, and active retries
+  - Auto-integrates with messages.update events in wrapper
+  - Inspired by whatsapp-rust's protocol/retry.rs module
+- **PostReconnectThrottle** module: Throttle outbound messages after reconnection
+  - Prevents burst-floods on reconnect that trigger WhatsApp rate limits
+  - Configurable ramp-up from initial rate multiplier (default: 10%) to full rate over ramp duration (default: 60s)
+  - Linear ramp with configurable steps (default: 6 steps)
+  - Auto-integrates with connection.update events
+  - Inspired by whatsapp-rust's client/sessions.rs semaphore swap pattern
+- Both modules are opt-in (enabled: false by default) for backward compatibility
+
+### Changed
+- `AntiBan.beforeSend()` now also consults reconnect throttle
+- `AntiBan.onReconnect()` triggers reconnect throttle window
+- `AntiBan.getStats()` includes retry tracker and reconnect throttle stats when enabled
+- Wrapper now tracks message updates for retry classification and clears on successful send
+
+## [1.4.0] - 2026-04-18
+
+### Added
+- **Transport-agnostic support** — works with both `baileys` and `@oxidezap/baileyrs` (Rust/WASM WhatsApp library)
+- Both transports now listed as optional peer dependencies
+- GitHub Actions CI workflow with dual-transport matrix testing (Node 18.x + 20.x × baileys + baileyrs)
+- New test suite: `tests/transport-agnostic.test.ts` for duck-typed socket validation
+- Updated JSDoc examples showing usage with both transports
+
+### Changed
+- `peerDependencies` now includes both `baileys` and `@oxidezap/baileyrs` as optional
+- Package description updated to mention transport-agnostic support
+- Wrapper comments clarify baileyrs timelock behavior (no `reachoutTimeLock` events in v0.0.8 — operates in detection-only mode)
+
+### Why
+Positions baileys-antiban as "Switzerland" of WhatsApp anti-ban — works with any Baileys-compatible transport layer. No breaking changes for existing baileys users.
+
 ## [1.3.1] - 2026-04-16
 
 ### Changed

package/README.md

@@ -4,9 +4,64 @@
 [![Node.js Version](https://img.shields.io/node/v/baileys-antiban.svg)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Anti-ban middleware for [Baileys](https://github.com/WhiskeySockets/Baileys) — protect your WhatsApp number with human-like messaging patterns.
+**Transport-agnostic** anti-ban middleware — protect your WhatsApp number with human-like messaging patterns. Works with both [Baileys](https://github.com/WhiskeySockets/Baileys) and [@oxidezap/baileyrs](https://github.com/oxidezap/baileyrs) (Rust/WASM).
 
-## v1.3 New Features
+## v1.5 New Features
+
+### RetryReasonTracker
+Tracks message retry reasons and detects retry spirals (when the same message keeps failing). Inspired by whatsapp-rust's protocol/retry.rs module.
+
+```typescript
+import { AntiBan } from 'baileys-antiban';
+
+const antiban = new AntiBan({
+  retryTracker: {
+    enabled: true,
+    maxRetries: 5,           // Max retries before considering a message failed
+    spiralThreshold: 3,      // Retries before warning about retry spiral
+    onSpiral: (msgId, reason) => {
+      console.warn(`Message ${msgId} stuck in retry spiral: ${reason}`);
+    },
+  },
+});
+
+// Stats show retry patterns
+const stats = antiban.getStats().retryTracker;
+console.log(stats.totalRetries);         // Total retries across all messages
+console.log(stats.byReason.timeout);     // Retries due to timeout
+console.log(stats.spiralsDetected);      // Messages stuck in retry loops
+console.log(stats.activeRetries);        // Messages currently retrying
+```
+
+**Retry reasons tracked**: no_session, invalid_key, bad_mac, decryption_failure, server_error_463, server_error_429, timeout, no_route, node_malformed, unknown
+
+### PostReconnectThrottle
+Throttles outbound messages after reconnection to prevent burst-floods that trigger rate limits. Inspired by whatsapp-rust's client/sessions.rs semaphore swap pattern.
+
+```typescript
+const antiban = new AntiBan({
+  reconnectThrottle: {
+    enabled: true,
+    rampDurationMs: 60_000,       // 60s ramp-up to full rate
+    initialRateMultiplier: 0.1,   // Start at 10% of normal rate
+    rampSteps: 6,                 // 10% → 25% → 50% → 75% → 90% → 100%
+  },
+});
+
+// After reconnect, sends are automatically throttled for 60 seconds
+// Ramps from 10% rate to 100% rate linearly over 6 steps
+
+// Stats show throttle state
+const stats = antiban.getStats().reconnectThrottle;
+console.log(stats.isThrottled);          // Currently throttled?
+console.log(stats.currentMultiplier);    // 0.1 to 1.0
+console.log(stats.remainingMs);          // Time until full rate
+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.
+
+## v1.3 Features
 
 ### ReplyRatioGuard
 Tracks outbound:inbound message ratio per contact. Blocks sends to non-responsive contacts to avoid "spray-and-pray" ban patterns. Optionally suggests auto-replies to maintain healthy engagement.
@@ -92,21 +147,46 @@ WhatsApp bans numbers that behave like bots. This library makes your Baileys bot
 - **Reply ratio tracking** (v1.3) — blocks sends to non-responsive contacts
 - **Contact graph enforcement** (v1.3) — requires handshakes before bulk/group sends
 - **Circadian rhythm** (v1.3) — realistic time-of-day activity patterns
+- **Retry tracking** (v1.5) — detect retry spirals and classify retry reasons
+- **Reconnect throttle** (v1.5) — prevent burst-floods after reconnection
+
+## Supported Transports
+
+**v1.4+** is transport-agnostic and works with any Baileys-compatible WhatsApp library:
+
+- **[Baileys](https://github.com/WhiskeySockets/Baileys)** (Node.js, JavaScript/TypeScript)
+- **[@oxidezap/baileyrs](https://github.com/oxidezap/baileyrs)** (Rust/WASM, Baileys-compatible API)
+
+Both use the same `wrapSocket()` integration. Zero code changes needed.
 
 ## Installation
 
+### With Baileys (Node.js)
+
+```bash
+npm install baileys baileys-antiban
+```
+
+### With baileyrs (Rust/WASM)
+
 ```bash
-npm install baileys-antiban
+npm install @oxidezap/baileyrs baileys-antiban
 ```
 
-Requires Node.js ≥16 and Baileys ≥6.0.0.
+Requires Node.js ≥16.
 
 ## Quick Start
 
 ### Option 1: Wrap Your Socket (Easiest)
 
+Works with both baileys and baileyrs — same code:
+
 ```typescript
+// With baileys:
 import makeWASocket from 'baileys';
+// OR with baileyrs:
+// import { makeWASocket } from '@oxidezap/baileyrs';
+
 import { wrapSocket } from 'baileys-antiban';
 
 const sock = makeWASocket({ /* your config */ });
@@ -200,6 +280,17 @@ const antiban = new AntiBan({
       console.log('Timelock lifted — resuming normal operation');
     },
   },
+  retryTracker: {
+    enabled: false,                  // Opt-in (default: false)
+    maxRetries: 5,
+    spiralThreshold: 3,
+  },
+  reconnectThrottle: {
+    enabled: false,                  // Opt-in (default: false)
+    rampDurationMs: 60_000,
+    initialRateMultiplier: 0.1,
+    rampSteps: 6,
+  },
   logging: true, // Console logging (default: true)
 });
 ```

package/dist/antiban.d.ts

@@ -20,6 +20,8 @@ import { TimelockGuard, type TimelockGuardConfig } from './timelockGuard.js';
 import { ReplyRatioGuard, type ReplyRatioConfig, type ReplyRatioStats } from './replyRatio.js';
 import { ContactGraphWarmer, type ContactGraphConfig, type ContactGraphStats } from './contactGraph.js';
 import { PresenceChoreographer, type PresenceChoreographerConfig, type PresenceChoreographerStats } from './presenceChoreographer.js';
+import { RetryReasonTracker, type RetryTrackerConfig, type RetryStats } from './retryTracker.js';
+import { PostReconnectThrottle, type ReconnectThrottleConfig, type ReconnectThrottleStats } from './reconnectThrottle.js';
 export interface AntiBanConfig {
     rateLimiter?: Partial<RateLimiterConfig>;
     warmUp?: Partial<WarmUpConfig>;
@@ -28,6 +30,8 @@ export interface AntiBanConfig {
     replyRatio?: Partial<ReplyRatioConfig>;
     contactGraph?: Partial<ContactGraphConfig>;
     presence?: Partial<PresenceChoreographerConfig>;
+    retryTracker?: Partial<RetryTrackerConfig>;
+    reconnectThrottle?: Partial<ReconnectThrottleConfig>;
     /** Log warnings and blocks to console (default: true) */
     logging?: boolean;
 }
@@ -48,6 +52,8 @@ export interface AntiBanStats {
     replyRatio?: ReplyRatioStats;
     contactGraph?: ContactGraphStats;
     presence?: PresenceChoreographerStats;
+    retryTracker?: RetryStats | null;
+    reconnectThrottle?: ReconnectThrottleStats | null;
 }
 export declare class AntiBan {
     private rateLimiter;
@@ -57,6 +63,8 @@ export declare class AntiBan {
     private replyRatioGuard;
     private contactGraphWarmer;
     private presenceChoreographer;
+    private retryTrackerModule;
+    private reconnectThrottleModule;
     private logging;
     private stats;
     constructor(config?: AntiBanConfig, warmUpState?: WarmUpState);
@@ -102,6 +110,10 @@ export declare class AntiBan {
     get contactGraph(): ContactGraphWarmer;
     /** Get the presence choreographer for direct access */
     get presence(): PresenceChoreographer;
+    /** Get the retry tracker for direct access */
+    get retryTracker(): RetryReasonTracker;
+    /** Get the reconnect throttle for direct access */
+    get reconnectThrottle(): PostReconnectThrottle;
     /**
      * Export warm-up state for persistence between restarts
      */

package/dist/antiban.js

@@ -20,6 +20,8 @@ import { TimelockGuard } from './timelockGuard.js';
 import { ReplyRatioGuard } from './replyRatio.js';
 import { ContactGraphWarmer } from './contactGraph.js';
 import { PresenceChoreographer } from './presenceChoreographer.js';
+import { RetryReasonTracker } from './retryTracker.js';
+import { PostReconnectThrottle } from './reconnectThrottle.js';
 export class AntiBan {
     rateLimiter;
     warmUp;
@@ -28,6 +30,8 @@ export class AntiBan {
     replyRatioGuard;
     contactGraphWarmer;
     presenceChoreographer;
+    retryTrackerModule;
+    reconnectThrottleModule;
     logging;
     stats = {
         messagesAllowed: 0,
@@ -69,6 +73,19 @@ export class AntiBan {
         this.replyRatioGuard = new ReplyRatioGuard(config.replyRatio);
         this.contactGraphWarmer = new ContactGraphWarmer(config.contactGraph);
         this.presenceChoreographer = new PresenceChoreographer(config.presence);
+        this.retryTrackerModule = new RetryReasonTracker({
+            ...config.retryTracker,
+            onSpiral: (msgId, reason) => {
+                if (this.logging) {
+                    console.log(`[baileys-antiban] ⚠️  Message ${msgId} stuck in retry spiral (${reason})`);
+                }
+                config.retryTracker?.onSpiral?.(msgId, reason);
+            },
+        });
+        this.reconnectThrottleModule = new PostReconnectThrottle({
+            ...config.reconnectThrottle,
+            baselineRatePerMinute: () => this.rateLimiter.getStats().limits.perMinute,
+        });
     }
     /**
      * Check if a message can be sent and get required delay.
@@ -146,6 +163,20 @@ export class AntiBan {
                 health: healthStatus,
             };
         }
+        // Reconnect throttle check
+        const reconnectThrottleDecision = this.reconnectThrottleModule.beforeSend();
+        if (!reconnectThrottleDecision.allowed) {
+            this.stats.messagesBlocked++;
+            if (this.logging) {
+                console.log(`[baileys-antiban] 🔄 BLOCKED — reconnect throttle: ${reconnectThrottleDecision.reason}`);
+            }
+            return {
+                allowed: false,
+                delayMs: reconnectThrottleDecision.retryAfterMs || 0,
+                reason: reconnectThrottleDecision.reason || 'Post-reconnect throttle',
+                health: healthStatus,
+            };
+        }
         // Rate limiter delay
         let delay = await this.rateLimiter.getDelay(recipient, content);
         if (delay === -1) {
@@ -211,12 +242,14 @@ export class AntiBan {
      */
     onDisconnect(reason) {
         this.health.recordDisconnect(reason);
+        this.reconnectThrottleModule.onDisconnect();
     }
     /**
      * Record a successful reconnection
      */
     onReconnect() {
         this.health.recordReconnect();
+        this.reconnectThrottleModule.onReconnect();
     }
     /**
      * Handle incoming message — record in reply ratio + contact graph.
@@ -247,6 +280,12 @@ export class AntiBan {
         if (this.presenceChoreographer['config']?.enabled) {
             stats.presence = this.presenceChoreographer.getStats();
         }
+        if (this.retryTrackerModule['config']?.enabled) {
+            stats.retryTracker = this.retryTrackerModule.getStats();
+        }
+        if (this.reconnectThrottleModule['config']?.enabled) {
+            stats.reconnectThrottle = this.reconnectThrottleModule.getStats();
+        }
         return stats;
     }
     /** Get the timelock guard for direct access */
@@ -265,6 +304,14 @@ export class AntiBan {
     get presence() {
         return this.presenceChoreographer;
     }
+    /** Get the retry tracker for direct access */
+    get retryTracker() {
+        return this.retryTrackerModule;
+    }
+    /** Get the reconnect throttle for direct access */
+    get reconnectThrottle() {
+        return this.reconnectThrottleModule;
+    }
     /**
      * Export warm-up state for persistence between restarts
      */
@@ -299,6 +346,8 @@ export class AntiBan {
         this.replyRatioGuard.reset();
         this.contactGraphWarmer.reset();
         this.presenceChoreographer.reset();
+        this.retryTrackerModule.destroy();
+        this.reconnectThrottleModule.destroy();
         this.stats = { messagesAllowed: 0, messagesBlocked: 0, totalDelayMs: 0 };
         if (this.logging) {
             console.log('[baileys-antiban] 🔄 Reset — starting fresh warm-up');
@@ -313,6 +362,8 @@ export class AntiBan {
         this.replyRatioGuard.reset();
         this.contactGraphWarmer.reset();
         this.presenceChoreographer.reset();
+        this.retryTrackerModule.destroy();
+        this.reconnectThrottleModule.destroy();
         if (this.logging) {
             console.log('[baileys-antiban] 🧹 Destroyed — all timers cleared');
         }

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export { TimelockGuard, type TimelockGuardConfig, type TimelockState } from './t
 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 { RetryReasonTracker, type RetryTrackerConfig, type RetryStats, type RetryReason } from './retryTracker.js';
+export { PostReconnectThrottle, type ReconnectThrottleConfig, type ReconnectThrottleStats } from './reconnectThrottle.js';
 export { wrapSocket, type WrappedSocket, type WrapSocketOptions } from './wrapper.js';
 export { MessageQueue, type QueuedMessage, type MessageQueueConfig } from './messageQueue.js';
 export { ContentVariator, type VariatorConfig } from './contentVariator.js';

package/dist/index.js

@@ -17,6 +17,9 @@ export { TimelockGuard } from './timelockGuard.js';
 export { ReplyRatioGuard } from './replyRatio.js';
 export { ContactGraphWarmer } from './contactGraph.js';
 export { PresenceChoreographer } from './presenceChoreographer.js';
+// v1.5 new modules
+export { RetryReasonTracker } from './retryTracker.js';
+export { PostReconnectThrottle } from './reconnectThrottle.js';
 // Socket wrapper
 export { wrapSocket } from './wrapper.js';
 // Optional features

package/dist/reconnectThrottle.d.ts

@@ -0,0 +1,89 @@
+/**
+ * PostReconnectThrottle — Throttle outbound messages after reconnection
+ *
+ * Inspired by whatsapp-rust's client/sessions.rs which uses semaphore=1 during
+ * offline sync (serializes all processing), then swaps to semaphore=64 when sync
+ * completes. This prevents burst-floods on reconnect that trigger WA rate limits.
+ *
+ * In middleware layer: on reconnect, enter a throttled window where beforeSend()
+ * gates outbound messages to an artificially low rate, then ramps back to normal
+ * over a configurable period.
+ *
+ * Usage:
+ *   const throttle = new PostReconnectThrottle({
+ *     enabled: true,
+ *     rampDurationMs: 60_000,
+ *     initialRateMultiplier: 0.1,
+ *   });
+ *
+ *   // On connection.update with connection === 'open':
+ *   throttle.onReconnect();
+ *
+ *   // Before sending:
+ *   const decision = throttle.beforeSend();
+ *   if (!decision.allowed) {
+ *     // Wait decision.retryAfterMs
+ *   }
+ *
+ *   // Get current throttle multiplier (1.0 = no throttle):
+ *   const multiplier = throttle.getCurrentMultiplier();
+ */
+export interface ReconnectThrottleConfig {
+    enabled?: boolean;
+    rampDurationMs?: number;
+    initialRateMultiplier?: number;
+    rampSteps?: number;
+    baselineRatePerMinute?: () => number;
+}
+export interface ReconnectThrottleStats {
+    isThrottled: boolean;
+    currentMultiplier: number;
+    throttledSinceMs: number | null;
+    remainingMs: number;
+    throttledSendCount: number;
+    lifetimeReconnects: number;
+}
+export declare class PostReconnectThrottle {
+    private config;
+    private throttledSince;
+    private throttledSendCount;
+    private lifetimeReconnects;
+    private rampTimer;
+    private currentStep;
+    private sendsInCurrentWindow;
+    private currentWindowStart;
+    private readonly WINDOW_DURATION_MS;
+    constructor(config?: ReconnectThrottleConfig);
+    /**
+     * Call when connection is re-established. Starts throttle window.
+     */
+    onReconnect(): void;
+    /**
+     * Call when connection drops (optional — reset state).
+     */
+    onDisconnect(): void;
+    /**
+     * Schedule the next ramp step
+     */
+    private scheduleNextRampStep;
+    /**
+     * Returns current rate multiplier (1.0 = no throttle)
+     */
+    getCurrentMultiplier(): number;
+    /**
+     * Checks if a send should be gated. Returns {allowed, reason, retryAfterMs?}
+     */
+    beforeSend(): {
+        allowed: boolean;
+        reason?: string;
+        retryAfterMs?: number;
+    };
+    /**
+     * Get current stats
+     */
+    getStats(): ReconnectThrottleStats;
+    /**
+     * Destroy and clean up timers
+     */
+    destroy(): void;
+}

package/dist/reconnectThrottle.js

@@ -0,0 +1,180 @@
+/**
+ * PostReconnectThrottle — Throttle outbound messages after reconnection
+ *
+ * Inspired by whatsapp-rust's client/sessions.rs which uses semaphore=1 during
+ * offline sync (serializes all processing), then swaps to semaphore=64 when sync
+ * completes. This prevents burst-floods on reconnect that trigger WA rate limits.
+ *
+ * In middleware layer: on reconnect, enter a throttled window where beforeSend()
+ * gates outbound messages to an artificially low rate, then ramps back to normal
+ * over a configurable period.
+ *
+ * Usage:
+ *   const throttle = new PostReconnectThrottle({
+ *     enabled: true,
+ *     rampDurationMs: 60_000,
+ *     initialRateMultiplier: 0.1,
+ *   });
+ *
+ *   // On connection.update with connection === 'open':
+ *   throttle.onReconnect();
+ *
+ *   // Before sending:
+ *   const decision = throttle.beforeSend();
+ *   if (!decision.allowed) {
+ *     // Wait decision.retryAfterMs
+ *   }
+ *
+ *   // Get current throttle multiplier (1.0 = no throttle):
+ *   const multiplier = throttle.getCurrentMultiplier();
+ */
+const DEFAULT_CONFIG = {
+    enabled: false,
+    rampDurationMs: 60_000,
+    initialRateMultiplier: 0.1,
+    rampSteps: 6,
+    baselineRatePerMinute: null,
+};
+export class PostReconnectThrottle {
+    config;
+    throttledSince = null;
+    throttledSendCount = 0;
+    lifetimeReconnects = 0;
+    rampTimer = null;
+    currentStep = 0;
+    // Tracking sends in current window
+    sendsInCurrentWindow = 0;
+    currentWindowStart = 0;
+    WINDOW_DURATION_MS = 60_000; // 1 minute window
+    constructor(config) {
+        this.config = {
+            ...DEFAULT_CONFIG,
+            ...config,
+            baselineRatePerMinute: config?.baselineRatePerMinute || null,
+        };
+    }
+    /**
+     * Call when connection is re-established. Starts throttle window.
+     */
+    onReconnect() {
+        if (!this.config.enabled)
+            return;
+        this.throttledSince = Date.now();
+        this.currentStep = 0;
+        this.throttledSendCount = 0;
+        this.lifetimeReconnects++;
+        this.sendsInCurrentWindow = 0;
+        this.currentWindowStart = Date.now();
+        // Clear any existing ramp timer
+        if (this.rampTimer) {
+            clearTimeout(this.rampTimer);
+        }
+        // Set up ramp schedule
+        this.scheduleNextRampStep();
+    }
+    /**
+     * Call when connection drops (optional — reset state).
+     */
+    onDisconnect() {
+        // Keep throttle state for now — it will expire naturally
+        // This prevents rapid reconnect/disconnect cycles from resetting throttle too early
+    }
+    /**
+     * Schedule the next ramp step
+     */
+    scheduleNextRampStep() {
+        if (this.currentStep >= this.config.rampSteps) {
+            // Ramp complete — no longer throttled
+            this.throttledSince = null;
+            this.rampTimer = null;
+            return;
+        }
+        const stepDuration = this.config.rampDurationMs / this.config.rampSteps;
+        this.rampTimer = setTimeout(() => {
+            this.currentStep++;
+            this.scheduleNextRampStep();
+        }, stepDuration);
+    }
+    /**
+     * Returns current rate multiplier (1.0 = no throttle)
+     */
+    getCurrentMultiplier() {
+        if (!this.config.enabled || !this.throttledSince) {
+            return 1.0;
+        }
+        const elapsed = Date.now() - this.throttledSince;
+        if (elapsed >= this.config.rampDurationMs) {
+            // Ramp complete
+            return 1.0;
+        }
+        // Linear ramp from initialRateMultiplier to 1.0 across rampSteps
+        const progress = this.currentStep / this.config.rampSteps;
+        const multiplier = this.config.initialRateMultiplier +
+            (1.0 - this.config.initialRateMultiplier) * progress;
+        return Math.min(1.0, multiplier);
+    }
+    /**
+     * Checks if a send should be gated. Returns {allowed, reason, retryAfterMs?}
+     */
+    beforeSend() {
+        if (!this.config.enabled || !this.throttledSince) {
+            return { allowed: true };
+        }
+        const now = Date.now();
+        const multiplier = this.getCurrentMultiplier();
+        // If fully ramped up, allow all sends
+        if (multiplier >= 1.0) {
+            this.throttledSince = null;
+            return { allowed: true };
+        }
+        // Reset window if needed
+        if (now - this.currentWindowStart >= this.WINDOW_DURATION_MS) {
+            this.sendsInCurrentWindow = 0;
+            this.currentWindowStart = now;
+        }
+        // Calculate budget for current window
+        const baselineRate = this.config.baselineRatePerMinute ? this.config.baselineRatePerMinute() : 8;
+        const allowedInWindow = Math.floor(baselineRate * multiplier);
+        // Check if we're over budget
+        if (this.sendsInCurrentWindow >= allowedInWindow) {
+            const windowRemaining = this.WINDOW_DURATION_MS - (now - this.currentWindowStart);
+            return {
+                allowed: false,
+                reason: `Post-reconnect throttle: ${Math.floor(multiplier * 100)}% rate (${this.sendsInCurrentWindow}/${allowedInWindow} sends in window)`,
+                retryAfterMs: windowRemaining,
+            };
+        }
+        // Allow send and increment counter
+        this.sendsInCurrentWindow++;
+        this.throttledSendCount++;
+        return { allowed: true };
+    }
+    /**
+     * Get current stats
+     */
+    getStats() {
+        const multiplier = this.getCurrentMultiplier();
+        const isThrottled = this.throttledSince !== null && multiplier < 1.0;
+        const remainingMs = isThrottled && this.throttledSince
+            ? Math.max(0, this.config.rampDurationMs - (Date.now() - this.throttledSince))
+            : 0;
+        return {
+            isThrottled,
+            currentMultiplier: multiplier,
+            throttledSinceMs: this.throttledSince,
+            remainingMs,
+            throttledSendCount: this.throttledSendCount,
+            lifetimeReconnects: this.lifetimeReconnects,
+        };
+    }
+    /**
+     * Destroy and clean up timers
+     */
+    destroy() {
+        if (this.rampTimer) {
+            clearTimeout(this.rampTimer);
+            this.rampTimer = null;
+        }
+        this.throttledSince = null;
+    }
+}

package/dist/retryTracker.d.ts

@@ -0,0 +1,87 @@
+/**
+ * RetryReasonTracker — Track message retry reasons and detect retry spirals
+ *
+ * Inspired by whatsapp-rust's protocol/retry.rs module which defines 13 typed
+ * RetryReason codes with MAX_RETRY=5 and optimized key-include behavior.
+ *
+ * In the middleware layer, we can't control key inclusion (that's transport-level),
+ * but we CAN observe retry patterns from messages.update events and classify them.
+ * High retry rates per reason = ban signal precursor.
+ *
+ * Usage:
+ *   const tracker = new RetryReasonTracker({ enabled: true, maxRetries: 5 });
+ *
+ *   // In messages.update handler:
+ *   tracker.onMessageUpdate(update);
+ *
+ *   // Check for spirals:
+ *   if (tracker.isSpiraling(msgId)) {
+ *     console.warn('Message stuck in retry spiral, dropping');
+ *   }
+ *
+ *   // On successful send:
+ *   tracker.clear(msgId);
+ *
+ *   // Get stats:
+ *   const stats = tracker.getStats();
+ */
+export type RetryReason = 'no_session' | 'invalid_key' | 'bad_mac' | 'decryption_failure' | 'server_error_463' | 'server_error_429' | 'timeout' | 'no_route' | 'node_malformed' | 'unknown';
+export interface RetryTrackerConfig {
+    enabled?: boolean;
+    maxRetries?: number;
+    spiralThreshold?: number;
+    onSpiral?: (msgId: string, reason: RetryReason) => void;
+}
+export interface RetryStats {
+    totalRetries: number;
+    byReason: Record<RetryReason, number>;
+    spiralsDetected: number;
+    activeRetries: number;
+}
+export declare class RetryReasonTracker {
+    private config;
+    private retries;
+    private totalRetries;
+    private reasonCounts;
+    private spiralsDetected;
+    constructor(config?: RetryTrackerConfig);
+    /**
+     * Call when a messages.update event arrives with a status/error.
+     * Classifies and records the retry.
+     */
+    onMessageUpdate(update: {
+        key: {
+            id?: string;
+        };
+        status?: number;
+        error?: any;
+    }): void;
+    /**
+     * Classify an arbitrary error object into a RetryReason
+     */
+    classify(err: any): RetryReason;
+    /**
+     * Record a retry for a message
+     */
+    private recordRetry;
+    /**
+     * Should we warn the user this message is spiraling?
+     */
+    isSpiraling(msgId: string): boolean;
+    /**
+     * Reset counters for a specific message (call on successful delivery)
+     */
+    clear(msgId: string): void;
+    /**
+     * Get current stats
+     */
+    getStats(): RetryStats;
+    /**
+     * Clean up old retry records (>5 minutes old)
+     */
+    private cleanup;
+    /**
+     * Destroy and clean up
+     */
+    destroy(): void;
+}

package/dist/retryTracker.js

@@ -0,0 +1,171 @@
+/**
+ * RetryReasonTracker — Track message retry reasons and detect retry spirals
+ *
+ * Inspired by whatsapp-rust's protocol/retry.rs module which defines 13 typed
+ * RetryReason codes with MAX_RETRY=5 and optimized key-include behavior.
+ *
+ * In the middleware layer, we can't control key inclusion (that's transport-level),
+ * but we CAN observe retry patterns from messages.update events and classify them.
+ * High retry rates per reason = ban signal precursor.
+ *
+ * Usage:
+ *   const tracker = new RetryReasonTracker({ enabled: true, maxRetries: 5 });
+ *
+ *   // In messages.update handler:
+ *   tracker.onMessageUpdate(update);
+ *
+ *   // Check for spirals:
+ *   if (tracker.isSpiraling(msgId)) {
+ *     console.warn('Message stuck in retry spiral, dropping');
+ *   }
+ *
+ *   // On successful send:
+ *   tracker.clear(msgId);
+ *
+ *   // Get stats:
+ *   const stats = tracker.getStats();
+ */
+const DEFAULT_CONFIG = {
+    enabled: false,
+    maxRetries: 5,
+    spiralThreshold: 3,
+    onSpiral: () => { },
+};
+export class RetryReasonTracker {
+    config;
+    retries = new Map();
+    totalRetries = 0;
+    reasonCounts = {
+        no_session: 0,
+        invalid_key: 0,
+        bad_mac: 0,
+        decryption_failure: 0,
+        server_error_463: 0,
+        server_error_429: 0,
+        timeout: 0,
+        no_route: 0,
+        node_malformed: 0,
+        unknown: 0,
+    };
+    spiralsDetected = 0;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Call when a messages.update event arrives with a status/error.
+     * Classifies and records the retry.
+     */
+    onMessageUpdate(update) {
+        if (!this.config.enabled)
+            return;
+        const msgId = update.key?.id;
+        if (!msgId)
+            return;
+        // Only track error statuses
+        if (update.status !== 0 && !update.error)
+            return;
+        const reason = this.classify(update.error || update);
+        this.recordRetry(msgId, reason);
+    }
+    /**
+     * Classify an arbitrary error object into a RetryReason
+     */
+    classify(err) {
+        if (!err)
+            return 'unknown';
+        // Check for HTTP status codes
+        const statusCode = err.output?.statusCode || err.statusCode || err.status;
+        if (statusCode === 463)
+            return 'server_error_463';
+        if (statusCode === 429)
+            return 'server_error_429';
+        // Extract error message/text for pattern matching
+        const errorMsg = (err.message || err.text || String(err)).toLowerCase();
+        // Pattern matching for known errors
+        if (errorMsg.includes('bad mac'))
+            return 'bad_mac';
+        if (errorMsg.includes('no session') || errorMsg.includes('session not found'))
+            return 'no_session';
+        if (errorMsg.includes('invalid key') || errorMsg.includes('key error'))
+            return 'invalid_key';
+        if (errorMsg.includes('decryption') || errorMsg.includes('decrypt'))
+            return 'decryption_failure';
+        if (errorMsg.includes('timeout') || errorMsg.includes('timed out'))
+            return 'timeout';
+        if (errorMsg.includes('no route') || errorMsg.includes('unreachable') || errorMsg.includes('offline'))
+            return 'no_route';
+        if (errorMsg.includes('malformed') || errorMsg.includes('invalid node'))
+            return 'node_malformed';
+        return 'unknown';
+    }
+    /**
+     * Record a retry for a message
+     */
+    recordRetry(msgId, reason) {
+        const now = Date.now();
+        let record = this.retries.get(msgId);
+        if (!record) {
+            record = {
+                msgId,
+                count: 0,
+                reasons: [],
+                firstRetry: now,
+                lastRetry: now,
+            };
+            this.retries.set(msgId, record);
+        }
+        record.count++;
+        record.reasons.push(reason);
+        record.lastRetry = now;
+        this.totalRetries++;
+        this.reasonCounts[reason]++;
+        // Check for spiral
+        if (record.count >= this.config.spiralThreshold) {
+            this.spiralsDetected++;
+            this.config.onSpiral(msgId, reason);
+        }
+    }
+    /**
+     * Should we warn the user this message is spiraling?
+     */
+    isSpiraling(msgId) {
+        const record = this.retries.get(msgId);
+        return record ? record.count >= this.config.spiralThreshold : false;
+    }
+    /**
+     * Reset counters for a specific message (call on successful delivery)
+     */
+    clear(msgId) {
+        this.retries.delete(msgId);
+    }
+    /**
+     * Get current stats
+     */
+    getStats() {
+        return {
+            totalRetries: this.totalRetries,
+            byReason: { ...this.reasonCounts },
+            spiralsDetected: this.spiralsDetected,
+            activeRetries: this.retries.size,
+        };
+    }
+    /**
+     * Clean up old retry records (>5 minutes old)
+     */
+    cleanup() {
+        const now = Date.now();
+        const maxAge = 5 * 60 * 1000; // 5 minutes
+        for (const [msgId, record] of this.retries.entries()) {
+            if (now - record.lastRetry > maxAge) {
+                this.retries.delete(msgId);
+            }
+        }
+    }
+    /**
+     * Destroy and clean up
+     */
+    destroy() {
+        this.retries.clear();
+        this.cleanup();
+    }
+}

package/dist/wrapper.d.ts

@@ -1,18 +1,31 @@
 /**
  * Socket Wrapper — Drop-in replacement that wraps sendMessage with anti-ban protection
  *
- * Usage:
+ * Works with both baileys and @oxidezap/baileyrs transports.
+ *
+ * Usage with baileys:
  *   import makeWASocket from 'baileys';
  *   import { wrapSocket } from 'baileys-antiban';
  *
  *   const sock = makeWASocket({ ... });
  *   const safeSock = wrapSocket(sock);
  *
+ * Usage with baileyrs:
+ *   import { makeWASocket } from '@oxidezap/baileyrs';
+ *   import { wrapSocket } from 'baileys-antiban';
+ *
+ *   const sock = makeWASocket({ ... });
+ *   const safeSock = wrapSocket(sock);
+ *
  *   // Use safeSock.sendMessage() — automatically rate-limited and monitored
  *   await safeSock.sendMessage(jid, { text: 'Hello!' });
  *
  *   // Check health anytime
  *   console.log(safeSock.antiban.getStats());
+ *
+ * Note: reachoutTimeLock timelock module silently noops on baileyrs until upstream
+ * emits reachoutTimeLock events — confirmed NOT present in baileyrs v0.0.8.
+ * Timelock guard will operate in detection-only mode (relies on 463 errors only).
  */
 import { AntiBan, type AntiBanConfig } from './antiban.js';
 import type { WarmUpState } from './warmup.js';

package/dist/wrapper.js

@@ -1,18 +1,31 @@
 /**
  * Socket Wrapper — Drop-in replacement that wraps sendMessage with anti-ban protection
  *
- * Usage:
+ * Works with both baileys and @oxidezap/baileyrs transports.
+ *
+ * Usage with baileys:
  *   import makeWASocket from 'baileys';
  *   import { wrapSocket } from 'baileys-antiban';
  *
  *   const sock = makeWASocket({ ... });
  *   const safeSock = wrapSocket(sock);
  *
+ * Usage with baileyrs:
+ *   import { makeWASocket } from '@oxidezap/baileyrs';
+ *   import { wrapSocket } from 'baileys-antiban';
+ *
+ *   const sock = makeWASocket({ ... });
+ *   const safeSock = wrapSocket(sock);
+ *
  *   // Use safeSock.sendMessage() — automatically rate-limited and monitored
  *   await safeSock.sendMessage(jid, { text: 'Hello!' });
  *
  *   // Check health anytime
  *   console.log(safeSock.antiban.getStats());
+ *
+ * Note: reachoutTimeLock timelock module silently noops on baileyrs until upstream
+ * emits reachoutTimeLock events — confirmed NOT present in baileyrs v0.0.8.
+ * Timelock guard will operate in detection-only mode (relies on 463 errors only).
  */
 import { AntiBan } from './antiban.js';
 /**
@@ -50,16 +63,19 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
                     });
                 }
             }
-            // Catch 463 errors from message updates
+            // Catch 463 errors from message updates + track retries
             if (events['messages.update']) {
                 const updates = events['messages.update'];
                 for (const update of updates) {
+                    // 463 error detection
                     if (update?.update?.messageStubParameters) {
                         const params = update.update.messageStubParameters;
                         if (params.includes(463) || params.includes('463')) {
                             antiban.timelock.record463Error();
                         }
                     }
+                    // Retry tracking
+                    antiban.retryTracker.onMessageUpdate(update);
                 }
             }
             // Register known chats from incoming messages + handle reply suggestions
@@ -120,15 +136,18 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
                 });
             }
         });
-        // Catch 463 errors from message updates
+        // Catch 463 errors from message updates + track retries
         sock.ev.on('messages.update', (updates) => {
             for (const update of updates) {
+                // 463 error detection
                 if (update?.update?.messageStubParameters) {
                     const params = update.update.messageStubParameters;
                     if (params.includes(463) || params.includes('463')) {
                         antiban.timelock.record463Error();
                     }
                 }
+                // Retry tracking
+                antiban.retryTracker.onMessageUpdate(update);
             }
         });
         // Register known chats from incoming messages + handle reply suggestions
@@ -185,6 +204,10 @@ export function wrapSocket(sock, config, warmUpState, wrapOptions) {
             const result = await originalSendMessage(jid, content, options);
             antiban.afterSend(jid, text);
             antiban.timelock.registerKnownChat(jid);
+            // Clear retry tracking on successful send
+            if (result?.key?.id) {
+                antiban.retryTracker.clear(result.key.id);
+            }
             return result;
         }
         catch (error) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "baileys-antiban",
-  "version": "1.3.1",
-  "description": "Anti-ban middleware for Baileys — human-like messaging patterns to protect your WhatsApp number",
+  "version": "1.5.0",
+  "description": "Transport-agnostic anti-ban middleware for Baileys and baileyrs — human-like messaging patterns to protect your WhatsApp number",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -29,6 +29,7 @@
   },
   "keywords": [
     "baileys",
+    "baileyrs",
     "whatsapp",
     "anti-ban",
     "rate-limit",
@@ -36,7 +37,8 @@
     "whatsapp-bot",
     "bot-protection",
     "whatsapp-api",
-    "nodejs"
+    "nodejs",
+    "transport-agnostic"
   ],
   "author": "Kobus Wentzel <kobie@pop.co.za>",
   "license": "MIT",
@@ -49,13 +51,22 @@
   },
   "homepage": "https://github.com/kobie3717/baileys-antiban#readme",
   "peerDependencies": {
+    "@oxidezap/baileyrs": ">=0.0.8",
     "baileys": ">=6.0.0"
   },
+  "peerDependenciesMeta": {
+    "baileys": {
+      "optional": true
+    },
+    "@oxidezap/baileyrs": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/jest": "^29.5.14",
     "@types/node": "^20.0.0",
     "jest": "^29.7.0",
-    "ts-jest": "^29.4.6",
+    "ts-jest": "^29.4.9",
     "tsx": "^4.21.0",
     "typescript": "^5.0.0"
   }