baileys-antiban 1.2.1 → 1.3.1

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.3.1] - 2026-04-16
+
+### Changed
+- Refactor wrapper to use Baileys' `ev.process()` API — single batched event handler reduces listener leaks and cleans up the integration surface
+- Graceful fallback to `ev.on()` for older Baileys versions
+
+### Why
+Scattered `ev.on()` registrations are a known leak vector. Consolidating into `process()` shrinks the attack surface for listener-lifecycle bugs and future-proofs for backend-agnostic support.
+
+## [1.3.0] - 2026-04-16
+
+### Added
+- **ReplyRatioGuard** — tracks outbound:inbound ratio per contact, blocks sends to non-responsive contacts, suggests auto-replies to incoming messages
+- **ContactGraphWarmer** — requires 1:1 handshake before bulk/group send, enforces group lurk period, daily stranger quota
+- **PresenceChoreographer** — circadian rhythm enforcement, distraction pauses, realistic read-receipt timing
+- All three features are **opt-in** via config and backward compatible
+- New wrapSocket option: `autoRespondToIncoming` for hands-off reply-ratio maintenance
+- New config fields: `replyRatio`, `contactGraph`, `presence` in `AntiBanConfig`
+- New public methods: `onIncomingMessage()`, getters for new modules
+- Enhanced `AntiBanStats` with optional `replyRatio`, `contactGraph`, `presence` stats
+
+### Why
+Based on 2025-2026 ban detection research: WhatsApp's ML models weight reply-ratio, contact-graph distance, and temporal patterns more heavily than raw volume. These modules address the three largest gaps in existing anti-ban libraries.
+
 ## [1.2.0] - 2026-04-13
 
 ### Added

package/README.md

@@ -6,6 +6,79 @@
 
 Anti-ban middleware for [Baileys](https://github.com/WhiskeySockets/Baileys) — protect your WhatsApp number with human-like messaging patterns.
 
+## v1.3 New 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.
+
+```typescript
+import { AntiBan } from 'baileys-antiban';
+
+const antiban = new AntiBan({
+  replyRatio: {
+    enabled: true,
+    minRatio: 0.10,              // Block sends to contacts with <10% reply rate
+    minMessagesBeforeEnforce: 5,  // Enforce after 5 outbound messages
+    cooldownHoursOnViolation: 24, // 24h cooldown on ratio violation
+  },
+});
+
+// Handle incoming messages to track replies
+sock.ev.on('messages.upsert', ({ messages }) => {
+  for (const msg of messages) {
+    if (!msg.key.fromMe) {
+      const suggestion = antiban.onIncomingMessage(msg.key.remoteJid);
+      if (suggestion.shouldReply) {
+        // Optionally auto-reply with suggestion.suggestedText
+      }
+    }
+  }
+});
+```
+
+### ContactGraphWarmer
+Requires 1:1 handshake before bulk/group sends. Enforces group lurk period (don't spam immediately after joining). Caps daily new-contact messaging.
+
+```typescript
+const antiban = new AntiBan({
+  contactGraph: {
+    enabled: true,
+    requireHandshakeBeforeGroupSend: true,
+    handshakeMinDelayMs: 3600000,  // 1h between handshake and first real message
+    groupLurkPeriodMs: 43200000,   // 12h lurk before first group send
+    maxStrangerMessagesPerDay: 5,  // Max 5 new contacts per day
+  },
+});
+
+// Mark handshake sent/complete manually
+antiban.contactGraph.markHandshakeSent(jid);
+antiban.contactGraph.markHandshakeComplete(jid);
+
+// Or auto-register known contacts on incoming messages
+// (enabled by default with autoRegisterOnIncoming: true)
+```
+
+### PresenceChoreographer
+Adds circadian rhythm to sending patterns (slower at night, faster during business hours). Injects realistic distraction pauses, offline gaps, and read-receipt timing variations.
+
+```typescript
+const antiban = new AntiBan({
+  presence: {
+    enabled: true,
+    enableCircadianRhythm: true,
+    timezone: 'Africa/Johannesburg',
+    activityCurve: 'office',        // 'office' | 'social' | 'global'
+    distractionPauseProbability: 0.05, // 5% chance per send to pause 5-20min
+    offlineGapProbability: 0.03,    // 3% chance to go offline 5-15min
+  },
+});
+
+// Delays are automatically adjusted based on local time-of-day
+// No manual intervention needed
+```
+
+**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.
+
 ## Why?
 
 WhatsApp bans numbers that behave like bots. This library makes your Baileys bot behave like a human:
@@ -16,6 +89,9 @@ WhatsApp bans numbers that behave like bots. This library makes your Baileys bot
 - **Timelock handling** for 463 reachout errors
 - **Auto-pause** when risk gets too high
 - **Drop-in wrapper** — one line to protect your existing 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
 
 ## Installation
 

package/dist/antiban.d.ts

@@ -17,11 +17,17 @@ import { type RateLimiterConfig, type RateLimiterStats } from './rateLimiter.js'
 import { type WarmUpConfig, type WarmUpState, type WarmUpStatus } from './warmup.js';
 import { type HealthMonitorConfig, type HealthStatus } from './health.js';
 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';
 export interface AntiBanConfig {
     rateLimiter?: Partial<RateLimiterConfig>;
     warmUp?: Partial<WarmUpConfig>;
     health?: Partial<HealthMonitorConfig>;
     timelock?: Partial<TimelockGuardConfig>;
+    replyRatio?: Partial<ReplyRatioConfig>;
+    contactGraph?: Partial<ContactGraphConfig>;
+    presence?: Partial<PresenceChoreographerConfig>;
     /** Log warnings and blocks to console (default: true) */
     logging?: boolean;
 }
@@ -39,12 +45,18 @@ export interface AntiBanStats {
     health: HealthStatus;
     warmUp: WarmUpStatus;
     rateLimiter: RateLimiterStats;
+    replyRatio?: ReplyRatioStats;
+    contactGraph?: ContactGraphStats;
+    presence?: PresenceChoreographerStats;
 }
 export declare class AntiBan {
     private rateLimiter;
     private warmUp;
     private health;
     private timelockGuard;
+    private replyRatioGuard;
+    private contactGraphWarmer;
+    private presenceChoreographer;
     private logging;
     private stats;
     constructor(config?: AntiBanConfig, warmUpState?: WarmUpState);
@@ -70,12 +82,26 @@ export declare class AntiBan {
      * Record a successful reconnection
      */
     onReconnect(): void;
+    /**
+     * Handle incoming message — record in reply ratio + contact graph.
+     * Returns suggested reply if reply ratio suggests auto-reply.
+     */
+    onIncomingMessage(jid: string, msgText?: string): {
+        shouldReply: boolean;
+        suggestedText?: string;
+    };
     /**
      * Get comprehensive stats
      */
     getStats(): AntiBanStats;
     /** Get the timelock guard for direct access */
     get timelock(): TimelockGuard;
+    /** Get the reply ratio guard for direct access */
+    get replyRatio(): ReplyRatioGuard;
+    /** Get the contact graph warmer for direct access */
+    get contactGraph(): ContactGraphWarmer;
+    /** Get the presence choreographer for direct access */
+    get presence(): PresenceChoreographer;
     /**
      * Export warm-up state for persistence between restarts
      */

package/dist/antiban.js

@@ -17,11 +17,17 @@ import { RateLimiter } from './rateLimiter.js';
 import { WarmUp } from './warmup.js';
 import { HealthMonitor } from './health.js';
 import { TimelockGuard } from './timelockGuard.js';
+import { ReplyRatioGuard } from './replyRatio.js';
+import { ContactGraphWarmer } from './contactGraph.js';
+import { PresenceChoreographer } from './presenceChoreographer.js';
 export class AntiBan {
     rateLimiter;
     warmUp;
     health;
     timelockGuard;
+    replyRatioGuard;
+    contactGraphWarmer;
+    presenceChoreographer;
     logging;
     stats = {
         messagesAllowed: 0,
@@ -60,6 +66,9 @@ export class AntiBan {
                 config.timelock?.onTimelockLifted?.(state);
             },
         });
+        this.replyRatioGuard = new ReplyRatioGuard(config.replyRatio);
+        this.contactGraphWarmer = new ContactGraphWarmer(config.contactGraph);
+        this.presenceChoreographer = new PresenceChoreographer(config.presence);
     }
     /**
      * Check if a message can be sent and get required delay.
@@ -109,8 +118,36 @@ export class AntiBan {
                 warmUpDay: warmUpStatus.day,
             };
         }
+        // Contact graph check
+        const contactGraphDecision = this.contactGraphWarmer.canMessage(recipient);
+        if (!contactGraphDecision.allowed) {
+            this.stats.messagesBlocked++;
+            if (this.logging) {
+                console.log(`[baileys-antiban] 📊 BLOCKED — contact graph: ${contactGraphDecision.reason}`);
+            }
+            return {
+                allowed: false,
+                delayMs: 0,
+                reason: `Contact graph: ${contactGraphDecision.reason}`,
+                health: healthStatus,
+            };
+        }
+        // Reply ratio check
+        const replyRatioDecision = this.replyRatioGuard.beforeSend(recipient);
+        if (!replyRatioDecision.allowed) {
+            this.stats.messagesBlocked++;
+            if (this.logging) {
+                console.log(`[baileys-antiban] 💬 BLOCKED — reply ratio: ${replyRatioDecision.reason}`);
+            }
+            return {
+                allowed: false,
+                delayMs: 0,
+                reason: `Reply ratio: ${replyRatioDecision.reason}`,
+                health: healthStatus,
+            };
+        }
         // Rate limiter delay
-        const delay = await this.rateLimiter.getDelay(recipient, content);
+        let delay = await this.rateLimiter.getDelay(recipient, content);
         if (delay === -1) {
             this.stats.messagesBlocked++;
             if (this.logging) {
@@ -123,6 +160,29 @@ export class AntiBan {
                 health: healthStatus,
             };
         }
+        // Apply circadian rhythm multiplier to delay
+        const activityFactor = this.presenceChoreographer.getCurrentActivityFactor();
+        if (activityFactor < 1.0) {
+            // Lower activity = longer delays (cap at 5x)
+            const multiplier = Math.min(5, 1 / activityFactor);
+            delay = Math.floor(delay * multiplier);
+        }
+        // Roll for distraction pause
+        const distractionCheck = this.presenceChoreographer.shouldPauseForDistraction();
+        if (distractionCheck.pause) {
+            delay += distractionCheck.durationMs;
+            if (this.logging) {
+                console.log(`[baileys-antiban] ⏸️  Distraction pause: +${Math.floor(distractionCheck.durationMs / 60000)}min`);
+            }
+        }
+        // Roll for offline gap
+        const offlineCheck = this.presenceChoreographer.shouldTakeOfflineGap();
+        if (offlineCheck.offline) {
+            delay += offlineCheck.durationMs;
+            if (this.logging) {
+                console.log(`[baileys-antiban] 📴 Offline gap: +${Math.floor(offlineCheck.durationMs / 60000)}min`);
+            }
+        }
         this.stats.totalDelayMs += delay;
         return {
             allowed: true,
@@ -137,6 +197,7 @@ export class AntiBan {
     afterSend(recipient, content) {
         this.rateLimiter.record(recipient, content);
         this.warmUp.record();
+        this.replyRatioGuard.recordSent(recipient);
         this.stats.messagesAllowed++;
     }
     /**
@@ -157,21 +218,53 @@ export class AntiBan {
     onReconnect() {
         this.health.recordReconnect();
     }
+    /**
+     * Handle incoming message — record in reply ratio + contact graph.
+     * Returns suggested reply if reply ratio suggests auto-reply.
+     */
+    onIncomingMessage(jid, msgText) {
+        this.replyRatioGuard.recordReceived(jid);
+        this.contactGraphWarmer.onIncomingMessage(jid);
+        return this.replyRatioGuard.suggestReply(jid, msgText);
+    }
     /**
      * Get comprehensive stats
      */
     getStats() {
-        return {
+        const stats = {
             ...this.stats,
             health: this.health.getStatus(),
             warmUp: this.warmUp.getStatus(),
             rateLimiter: this.rateLimiter.getStats(),
         };
+        // Only include new stats if enabled
+        if (this.replyRatioGuard['config']?.enabled) {
+            stats.replyRatio = this.replyRatioGuard.getStats();
+        }
+        if (this.contactGraphWarmer['config']?.enabled) {
+            stats.contactGraph = this.contactGraphWarmer.getStats();
+        }
+        if (this.presenceChoreographer['config']?.enabled) {
+            stats.presence = this.presenceChoreographer.getStats();
+        }
+        return stats;
     }
     /** Get the timelock guard for direct access */
     get timelock() {
         return this.timelockGuard;
     }
+    /** Get the reply ratio guard for direct access */
+    get replyRatio() {
+        return this.replyRatioGuard;
+    }
+    /** Get the contact graph warmer for direct access */
+    get contactGraph() {
+        return this.contactGraphWarmer;
+    }
+    /** Get the presence choreographer for direct access */
+    get presence() {
+        return this.presenceChoreographer;
+    }
     /**
      * Export warm-up state for persistence between restarts
      */
@@ -203,6 +296,9 @@ export class AntiBan {
         this.timelockGuard.reset();
         this.health.reset();
         this.warmUp.reset();
+        this.replyRatioGuard.reset();
+        this.contactGraphWarmer.reset();
+        this.presenceChoreographer.reset();
         this.stats = { messagesAllowed: 0, messagesBlocked: 0, totalDelayMs: 0 };
         if (this.logging) {
             console.log('[baileys-antiban] 🔄 Reset — starting fresh warm-up');
@@ -214,6 +310,9 @@ export class AntiBan {
      */
     destroy() {
         this.timelockGuard.reset(); // Clears the resumeTimer
+        this.replyRatioGuard.reset();
+        this.contactGraphWarmer.reset();
+        this.presenceChoreographer.reset();
         if (this.logging) {
             console.log('[baileys-antiban] 🧹 Destroyed — all timers cleared');
         }

package/dist/contactGraph.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Contact Graph Warmer — Requires 1:1 handshake before group/bulk sends
+ *
+ * WhatsApp's ML models weight "social graph distance" heavily. Accounts that
+ * message strangers (contacts who never replied) have higher ban risk.
+ *
+ * This module:
+ * - Tracks contact state: stranger → handshake_sent → handshake_complete → known
+ * - Blocks sends to strangers unless handshake completed
+ * - Enforces group lurk period (don't send immediately after joining)
+ * - Caps daily new-contact messaging (prevent spray-and-pray patterns)
+ * - Auto-registers inbound senders as "known contacts"
+ *
+ * Research: 2025 ban waves correlated with accounts joining groups + spamming
+ * instantly. 12-24h lurk period significantly reduced bans.
+ */
+export interface ContactGraphConfig {
+    /** Enable contact graph enforcement (default: false — opt-in) */
+    enabled?: boolean;
+    /** Require handshake completion before group/bulk sends (default: true) */
+    requireHandshakeBeforeGroupSend?: boolean;
+    /** Min wait time (ms) between handshake and first real message (default: 3600000 = 1h) */
+    handshakeMinDelayMs?: number;
+    /** Group lurk period (ms) before first send (default: 43200000 = 12h) */
+    groupLurkPeriodMs?: number;
+    /** Max new-contact messages per day (default: 5) */
+    maxStrangerMessagesPerDay?: number;
+    /** Auto-register inbound senders as known contacts (default: true) */
+    autoRegisterOnIncoming?: boolean;
+}
+export type ContactState = 'stranger' | 'handshake_sent' | 'handshake_complete' | 'known';
+export interface ContactGraphStats {
+    knownContacts: number;
+    pendingHandshakes: number;
+    strangersToday: number;
+    groupsJoined: Array<{
+        groupJid: string;
+        joinedAt: number;
+        firstSendUnlocksAt: number;
+    }>;
+}
+export declare class ContactGraphWarmer {
+    private config;
+    private contacts;
+    private groups;
+    private strangerMessagesToday;
+    private lastStrangerResetDay;
+    constructor(config?: ContactGraphConfig);
+    /**
+     * Check if message can be sent to this contact/group.
+     * Returns { allowed: false, needsHandshake: true } if handshake required.
+     */
+    canMessage(jid: string): {
+        allowed: boolean;
+        reason?: string;
+        needsHandshake?: boolean;
+    };
+    /**
+     * Mark handshake as sent to this contact.
+     */
+    markHandshakeSent(jid: string): void;
+    /**
+     * Mark handshake as complete with this contact.
+     */
+    markHandshakeComplete(jid: string): void;
+    /**
+     * Register a contact as known (skip handshake requirement).
+     */
+    registerKnownContact(jid: string): void;
+    /**
+     * Register a group join event.
+     */
+    registerGroupJoin(groupJid: string): void;
+    /**
+     * Get contact state.
+     */
+    getContactState(jid: string): ContactState;
+    /**
+     * Handle incoming message — auto-register if enabled.
+     */
+    onIncomingMessage(jid: string): void;
+    /**
+     * Get statistics.
+     */
+    getStats(): ContactGraphStats;
+    /**
+     * Reset all state.
+     */
+    reset(): void;
+    /**
+     * Export state for persistence.
+     */
+    exportState(): object;
+    /**
+     * Restore state from persistence.
+     */
+    restoreState(state: any): void;
+    private isGroup;
+    private getCurrentDay;
+    private checkGroupMessage;
+    private checkIndividualMessage;
+}