baileys-antiban 2.1.0 → 3.0.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.0.0] — 2026-04-25
+
+### Breaking Changes
+- Constructor now accepts `string | FlatConfig | undefined` — nested v2 config still works but logs deprecation warning
+- `WarmUpConfig.statePath` removed (use `persist` in AntiBanConfig instead)
+
+### New Features
+- **Zero-config:** `new AntiBan()` works with conservative defaults
+- **Presets:** `conservative` / `moderate` / `aggressive`
+- **State persistence:** `persist: './state.json'` — warmup + knownChats survive restarts
+- **Group profiles:** `groupProfiles: true` — stricter rate limits for @g.us and @newsletter JIDs
+- **Health decay:** Score recovers automatically (2pts/min severe, 5pts/min normal)
+- **CLI:** `npx baileys-antiban status|reset|warmup`
+
+### Bug Fixes
+- `statePath` in WarmUpConfig was declared but never implemented — replaced with working `persist` option
+- Health score never recovered after ban signals — fixed with time-based decay
+
+---
+
 ## [2.1.0] - 2026-04-19
 
 ### Added

package/README.md

@@ -1,10 +1,12 @@
-# baileys-antiban
+# baileys-antiban — Anti-Ban Middleware for Baileys & WhatsApp Bots
 
 [![npm version](https://img.shields.io/npm/v/baileys-antiban.svg)](https://www.npmjs.com/package/baileys-antiban)
 [![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)
 
-**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).
+**Drop-in anti-ban middleware for Baileys WhatsApp bots. Free, self-hosted, TypeScript-first. Whapi.Cloud alternative — zero monthly fees.**
+
+> Rate limiting with Gaussian jitter, 7-day warmup, session health monitoring, LID resolver, disconnect classification, contact graph enforcement — all in one `npm install`. Works with [Baileys](https://github.com/WhiskeySockets/Baileys) and [@oxidezap/baileyrs](https://github.com/oxidezap/baileyrs) (Rust/WASM).
 
 ## v2.0 New Features — Session Stability Module
 
@@ -323,6 +325,25 @@ const antiban = new AntiBan({
 
 **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
+
+| Feature | baileys-antiban | Whapi.Cloud | DIY snippets |
+|---|---|---|---|
+| Price | **Free, MIT** | $49–$99/mo | Free |
+| WhatsApp API | Unofficial (Baileys) | Unofficial underneath | Unofficial (Baileys) |
+| Rate limiting | ✅ Gaussian jitter | ✅ Black box | ⚠️ Basic only |
+| Warmup schedule | ✅ 7-day ramp | ✅ Managed | ❌ None |
+| Session health monitor | ✅ Built-in | ✅ Managed | ❌ None |
+| LID/PN resolver | ✅ v2.0 | ❌ Unknown | ❌ None |
+| Disconnect classifier | ✅ Typed reasons | ❌ None | ❌ None |
+| Contact graph enforcement | ✅ v1.3 | ❌ None | ❌ None |
+| Self-hosted | ✅ Yes | ❌ No | ✅ Yes |
+| TypeScript | ✅ Full types | N/A | ❌ Rarely |
+| Customisable | ✅ Full control | ❌ None | ⚠️ Copy-paste |
+| Drop-in (existing bot) | ✅ One-line wrapper | ❌ Full migration | ❌ Rewrite |
+
+**Bottom line:** Whapi.Cloud charges $99/mo for managed Baileys under the hood — same unofficial API, same ban risk, zero customisation. baileys-antiban gives you more protection, free, with full source access.
+
 ## Why?
 
 WhatsApp bans numbers that behave like bots. This library makes your Baileys bot behave like a human:
@@ -364,7 +385,47 @@ npm install @oxidezap/baileyrs baileys-antiban
 
 Requires Node.js ≥16.
 
-## Quick Start
+## Quick Start (v3)
+
+```bash
+npm install baileys-antiban
+```
+
+```typescript
+import { AntiBan } from 'baileys-antiban';
+
+// Zero config — works immediately
+const ab = new AntiBan();
+
+// Or pick a preset
+const ab = new AntiBan('moderate');
+
+// Full control
+const ab = new AntiBan({
+  preset: 'moderate',
+  persist: './antiban-state.json',  // survives restarts
+  groupProfiles: true,               // stricter limits for groups
+  maxPerMinute: 15,                  // override any value
+});
+
+// Usage unchanged
+const result = await ab.beforeSend(jid, text);
+if (result.allowed) {
+  await new Promise(r => setTimeout(r, result.delayMs));
+  await sock.sendMessage(jid, { text });
+  ab.afterSend(jid, text);
+}
+```
+
+### CLI
+
+```bash
+npx baileys-antiban status --state ./antiban-state.json
+npx baileys-antiban warmup --simulate 7 --preset moderate
+npx baileys-antiban reset --state ./antiban-state.json
+```
+
+## Quick Start (Legacy)
 
 ### Option 1: Wrap Your Socket (Easiest)
 

package/dist/antiban.d.ts

@@ -25,7 +25,8 @@ import { PostReconnectThrottle, type ReconnectThrottleConfig, type ReconnectThro
 import { LidResolver, type LidResolverConfig, type LidResolverStats } from './lidResolver.js';
 import { JidCanonicalizer, type JidCanonicalizerConfig, type JidCanonicalizerStats } from './jidCanonicalizer.js';
 import { SessionHealthMonitor, type SessionHealthStats } from './sessionStability.js';
-export interface AntiBanConfig {
+import { type AntiBanInput } from './presets.js';
+export interface AntiBanConfigLegacy {
     rateLimiter?: Partial<RateLimiterConfig>;
     warmUp?: Partial<WarmUpConfig>;
     health?: Partial<HealthMonitorConfig>;
@@ -37,21 +38,16 @@ export interface AntiBanConfig {
     reconnectThrottle?: Partial<ReconnectThrottleConfig>;
     lidResolver?: LidResolverConfig;
     jidCanonicalizer?: JidCanonicalizerConfig;
-    /** Session stability features (v2.0) — default disabled for backward compatibility */
     sessionStability?: {
         enabled: boolean;
-        /** Enable canonical JID normalization before sendMessage (default: true if enabled) */
         canonicalJidNormalization?: boolean;
-        /** Enable session health monitoring (default: true if enabled) */
         healthMonitoring?: boolean;
-        /** Bad MAC threshold before declaring session degraded (default: 3) */
         badMacThreshold?: number;
-        /** Time window for Bad MAC threshold in ms (default: 60000) */
         badMacWindowMs?: number;
     };
-    /** Log warnings and blocks to console (default: true) */
     logging?: boolean;
 }
+export type AntiBanConfig = AntiBanInput | AntiBanConfigLegacy;
 export interface SendDecision {
     allowed: boolean;
     delayMs: number;
@@ -88,9 +84,11 @@ export declare class AntiBan {
     private lidResolverModule;
     private jidCanonicalizerModule;
     private sessionStabilityMonitor;
+    private stateManager;
+    private resolvedConfig;
     private logging;
     private stats;
-    constructor(config?: AntiBanConfig, warmUpState?: WarmUpState);
+    constructor(input?: AntiBanInput | AntiBanConfigLegacy, warmUpStateArg?: WarmUpState);
     /**
      * Check if a message can be sent and get required delay.
      * Call this BEFORE every sendMessage().
@@ -159,6 +157,8 @@ export declare class AntiBan {
      * Reset everything (use after a ban period)
      */
     reset(): void;
+    private persistStateDebounced;
+    private persistStateImmediate;
     /**
      * Clean up all timers and resources.
      * Call this when disposing of the AntiBan instance or when the socket closes.

package/dist/antiban.js

@@ -25,6 +25,44 @@ import { PostReconnectThrottle } from './reconnectThrottle.js';
 import { LidResolver } from './lidResolver.js';
 import { JidCanonicalizer } from './jidCanonicalizer.js';
 import { SessionHealthMonitor } from './sessionStability.js';
+import { resolveConfig } from './presets.js';
+import { StateManager } from './persist.js';
+import { shouldUseGroupProfile, applyGroupMultiplier } from './profiles.js';
+function isLegacyConfig(cfg) {
+    if (typeof cfg !== 'object' || cfg === null)
+        return false;
+    return 'rateLimiter' in cfg || 'warmUp' in cfg || 'health' in cfg || 'timelock' in cfg ||
+        'replyRatio' in cfg || 'contactGraph' in cfg || 'presence' in cfg || 'retryTracker' in cfg ||
+        'reconnectThrottle' in cfg || 'lidResolver' in cfg || 'jidCanonicalizer' in cfg ||
+        'sessionStability' in cfg;
+}
+function mapLegacyToFlat(legacy) {
+    console.warn('[baileys-antiban] DEPRECATED: Nested config (v2 style) detected. ' +
+        'Migrate to flat config: new AntiBan({ maxPerMinute: 8 }). ' +
+        'See: https://github.com/kobie3717/baileys-antiban#migration');
+    const flat = {};
+    if (legacy.rateLimiter?.maxPerMinute !== undefined)
+        flat.maxPerMinute = legacy.rateLimiter.maxPerMinute;
+    if (legacy.rateLimiter?.maxPerHour !== undefined)
+        flat.maxPerHour = legacy.rateLimiter.maxPerHour;
+    if (legacy.rateLimiter?.maxPerDay !== undefined)
+        flat.maxPerDay = legacy.rateLimiter.maxPerDay;
+    if (legacy.rateLimiter?.minDelayMs !== undefined)
+        flat.minDelayMs = legacy.rateLimiter.minDelayMs;
+    if (legacy.rateLimiter?.maxDelayMs !== undefined)
+        flat.maxDelayMs = legacy.rateLimiter.maxDelayMs;
+    if (legacy.rateLimiter?.newChatDelayMs !== undefined)
+        flat.newChatDelayMs = legacy.rateLimiter.newChatDelayMs;
+    if (legacy.warmUp?.warmUpDays !== undefined)
+        flat.warmupDays = legacy.warmUp.warmUpDays;
+    if (legacy.warmUp?.day1Limit !== undefined)
+        flat.day1Limit = legacy.warmUp.day1Limit;
+    if (legacy.warmUp?.growthFactor !== undefined)
+        flat.growthFactor = legacy.warmUp.growthFactor;
+    if (legacy.logging !== undefined)
+        flat.logging = legacy.logging;
+    return flat;
+}
 export class AntiBan {
     rateLimiter;
     warmUp;
@@ -38,17 +76,63 @@ export class AntiBan {
     lidResolverModule = null;
     jidCanonicalizerModule = null;
     sessionStabilityMonitor = null;
+    stateManager = null;
+    resolvedConfig;
     logging;
     stats = {
         messagesAllowed: 0,
         messagesBlocked: 0,
         totalDelayMs: 0,
     };
-    constructor(config = {}, warmUpState) {
-        this.rateLimiter = new RateLimiter(config.rateLimiter);
-        this.warmUp = new WarmUp(config.warmUp, warmUpState);
+    constructor(input, warmUpStateArg) {
+        let flatConfig;
+        let legacyPassthrough = null;
+        let warmUpState = warmUpStateArg;
+        if (isLegacyConfig(input)) {
+            legacyPassthrough = input;
+            flatConfig = mapLegacyToFlat(legacyPassthrough);
+        }
+        else {
+            flatConfig = {};
+            legacyPassthrough = null;
+        }
+        const cfg = isLegacyConfig(input)
+            ? resolveConfig(flatConfig)
+            : resolveConfig(input);
+        this.resolvedConfig = cfg;
+        // Initialize persistence — load state before constructing modules
+        let savedState = null;
+        if (cfg.persist) {
+            this.stateManager = new StateManager(cfg.persist);
+            savedState = this.stateManager.load();
+            if (savedState) {
+                warmUpState = savedState.warmup;
+            }
+        }
+        this.logging = cfg.logging ?? true;
+        this.rateLimiter = new RateLimiter({
+            maxPerMinute: cfg.maxPerMinute,
+            maxPerHour: cfg.maxPerHour,
+            maxPerDay: cfg.maxPerDay,
+            minDelayMs: cfg.minDelayMs,
+            maxDelayMs: cfg.maxDelayMs,
+            newChatDelayMs: cfg.newChatDelayMs,
+            ...(legacyPassthrough?.rateLimiter || {}),
+        });
+        // Restore knownChats from persisted state after rateLimiter is constructed
+        if (savedState?.knownChats) {
+            this.rateLimiter.restoreKnownChats(savedState.knownChats);
+        }
+        this.warmUp = new WarmUp({
+            warmUpDays: cfg.warmupDays,
+            day1Limit: cfg.day1Limit,
+            growthFactor: cfg.growthFactor,
+            inactivityThresholdHours: cfg.inactivityThresholdHours,
+            ...(legacyPassthrough?.warmUp || {}),
+        }, warmUpState);
         this.health = new HealthMonitor({
-            ...config.health,
+            autoPauseAt: cfg.autoPauseAt,
+            ...(legacyPassthrough?.health || {}),
             onRiskChange: (status) => {
                 if (this.logging) {
                     const emoji = { low: '🟢', medium: '🟡', high: '🟠', critical: '🔴' };
@@ -56,74 +140,74 @@ export class AntiBan {
                     console.log(`[baileys-antiban] ${status.recommendation}`);
                     status.reasons.forEach(r => console.log(`[baileys-antiban]   → ${r}`));
                 }
-                config.health?.onRiskChange?.(status);
+                // Call original callback if present
+                legacyPassthrough?.health?.onRiskChange?.(status);
             },
         });
-        this.logging = config.logging ?? true;
         this.timelockGuard = new TimelockGuard({
-            ...config.timelock,
+            ...(legacyPassthrough?.timelock || {}),
             onTimelockDetected: (state) => {
                 this.health.recordReachoutTimelock(state.enforcementType);
                 if (this.logging) {
                     console.log(`[baileys-antiban] REACHOUT TIMELOCKED — ${state.enforcementType || 'unknown'}, expires ${state.expiresAt?.toISOString() || 'unknown'}`);
                 }
-                config.timelock?.onTimelockDetected?.(state);
+                legacyPassthrough?.timelock?.onTimelockDetected?.(state);
             },
             onTimelockLifted: (state) => {
                 if (this.logging) {
                     console.log(`[baileys-antiban] Timelock lifted — resuming new contact messages`);
                 }
-                config.timelock?.onTimelockLifted?.(state);
+                legacyPassthrough?.timelock?.onTimelockLifted?.(state);
             },
         });
-        this.replyRatioGuard = new ReplyRatioGuard(config.replyRatio);
-        this.contactGraphWarmer = new ContactGraphWarmer(config.contactGraph);
-        this.presenceChoreographer = new PresenceChoreographer(config.presence);
+        this.replyRatioGuard = new ReplyRatioGuard(legacyPassthrough?.replyRatio);
+        this.contactGraphWarmer = new ContactGraphWarmer(legacyPassthrough?.contactGraph);
+        this.presenceChoreographer = new PresenceChoreographer(legacyPassthrough?.presence);
         this.retryTrackerModule = new RetryReasonTracker({
-            ...config.retryTracker,
+            ...(legacyPassthrough?.retryTracker || {}),
             onSpiral: (msgId, reason) => {
                 if (this.logging) {
                     console.log(`[baileys-antiban] ⚠️  Message ${msgId} stuck in retry spiral (${reason})`);
                 }
-                config.retryTracker?.onSpiral?.(msgId, reason);
+                legacyPassthrough?.retryTracker?.onSpiral?.(msgId, reason);
             },
         });
         this.reconnectThrottleModule = new PostReconnectThrottle({
-            ...config.reconnectThrottle,
+            ...(legacyPassthrough?.reconnectThrottle || {}),
             baselineRatePerMinute: () => this.rateLimiter.getStats().limits.perMinute,
         });
         // Initialize LID resolver and canonicalizer if configured
         // If jidCanonicalizer is enabled but no resolver provided, create standalone resolver
-        if (config.jidCanonicalizer?.enabled) {
+        if (legacyPassthrough?.jidCanonicalizer?.enabled) {
             // Create or use provided resolver
-            if (config.jidCanonicalizer.resolver) {
+            if (legacyPassthrough.jidCanonicalizer.resolver) {
                 // User provided their own resolver
-                this.jidCanonicalizerModule = new JidCanonicalizer(config.jidCanonicalizer);
-                this.lidResolverModule = config.jidCanonicalizer.resolver;
+                this.jidCanonicalizerModule = new JidCanonicalizer(legacyPassthrough.jidCanonicalizer);
+                this.lidResolverModule = legacyPassthrough.jidCanonicalizer.resolver;
             }
             else {
                 // Create new resolver using lidResolver config if provided
-                const resolverConfig = config.lidResolver || config.jidCanonicalizer.resolverConfig;
+                const resolverConfig = legacyPassthrough.lidResolver || legacyPassthrough.jidCanonicalizer.resolverConfig;
                 const resolver = new LidResolver(resolverConfig);
                 this.lidResolverModule = resolver;
                 this.jidCanonicalizerModule = new JidCanonicalizer({
-                    ...config.jidCanonicalizer,
+                    ...legacyPassthrough.jidCanonicalizer,
                     resolver,
                 });
             }
         }
-        else if (config.lidResolver) {
+        else if (legacyPassthrough?.lidResolver) {
             // Standalone resolver without canonicalizer
-            this.lidResolverModule = new LidResolver(config.lidResolver);
+            this.lidResolverModule = new LidResolver(legacyPassthrough.lidResolver);
         }
         // Initialize session stability monitor if enabled
-        if (config.sessionStability?.enabled) {
+        if (legacyPassthrough?.sessionStability?.enabled) {
             const healthConfig = {
-                badMacThreshold: config.sessionStability.badMacThreshold,
-                badMacWindowMs: config.sessionStability.badMacWindowMs,
+                badMacThreshold: legacyPassthrough.sessionStability.badMacThreshold,
+                badMacWindowMs: legacyPassthrough.sessionStability.badMacWindowMs,
                 onDegraded: (stats) => {
                     if (this.logging) {
-                        console.log(`[baileys-antiban] 🔴 SESSION DEGRADED — Bad MAC rate: ${stats.badMacCount} in last ${config.sessionStability?.badMacWindowMs || 60000}ms`);
+                        console.log(`[baileys-antiban] 🔴 SESSION DEGRADED — Bad MAC rate: ${stats.badMacCount} in last ${legacyPassthrough?.sessionStability?.badMacWindowMs || 60000}ms`);
                         console.log(`[baileys-antiban] Consider restarting session or switching to LID-based canonical form`);
                     }
                 },
@@ -226,6 +310,24 @@ export class AntiBan {
                 health: healthStatus,
             };
         }
+        // Group profile rate check (runs before rateLimiter.getDelay for timing)
+        if (this.resolvedConfig.groupProfiles && shouldUseGroupProfile(recipient)) {
+            const groupLimits = applyGroupMultiplier({
+                maxPerMinute: this.resolvedConfig.maxPerMinute,
+                maxPerHour: this.resolvedConfig.maxPerHour,
+                maxPerDay: this.resolvedConfig.maxPerDay,
+            }, this.resolvedConfig.groupMultiplier);
+            const stats = this.rateLimiter.getStats();
+            if (stats.lastMinute >= groupLimits.maxPerMinute ||
+                stats.lastHour >= groupLimits.maxPerHour ||
+                stats.lastDay >= groupLimits.maxPerDay) {
+                this.stats.messagesBlocked++;
+                if (this.logging) {
+                    console.log(`[baileys-antiban] 🚫 BLOCKED — group rate limit exceeded for ${recipient}`);
+                }
+                return { allowed: false, delayMs: 0, reason: 'Group rate limit exceeded', health: healthStatus };
+            }
+        }
         // Rate limiter delay
         let delay = await this.rateLimiter.getDelay(recipient, content);
         if (delay === -1) {
@@ -279,6 +381,7 @@ export class AntiBan {
         this.warmUp.record();
         this.replyRatioGuard.recordSent(recipient);
         this.stats.messagesAllowed++;
+        this.persistStateDebounced();
     }
     /**
      * Record a failed message send
@@ -292,6 +395,10 @@ export class AntiBan {
     onDisconnect(reason) {
         this.health.recordDisconnect(reason);
         this.reconnectThrottleModule.onDisconnect();
+        const reasonStr = String(reason);
+        if (reasonStr === '403' || reasonStr === '401' || reasonStr === 'forbidden' || reasonStr === 'loggedOut') {
+            this.persistStateImmediate();
+        }
     }
     /**
      * Record a successful reconnection
@@ -423,11 +530,34 @@ export class AntiBan {
             console.log('[baileys-antiban] 🔄 Reset — starting fresh warm-up');
         }
     }
+    persistStateDebounced() {
+        if (!this.stateManager)
+            return;
+        const state = {
+            warmup: this.warmUp.exportState(),
+            knownChats: Array.from(this.rateLimiter.getKnownChats()),
+            savedAt: Date.now(),
+            version: 3,
+        };
+        this.stateManager.saveDebounced(state);
+    }
+    persistStateImmediate() {
+        if (!this.stateManager)
+            return;
+        const state = {
+            warmup: this.warmUp.exportState(),
+            knownChats: Array.from(this.rateLimiter.getKnownChats()),
+            savedAt: Date.now(),
+            version: 3,
+        };
+        this.stateManager.saveImmediate(state);
+    }
     /**
      * Clean up all timers and resources.
      * Call this when disposing of the AntiBan instance or when the socket closes.
      */
     destroy() {
+        this.stateManager?.destroy();
         this.timelockGuard.reset(); // Clears the resumeTimer
         this.replyRatioGuard.reset();
         this.contactGraphWarmer.reset();

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * baileys-antiban CLI
+ * Usage: npx baileys-antiban <command> [options]
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * baileys-antiban CLI
+ * Usage: npx baileys-antiban <command> [options]
+ */
+import * as fs from 'fs';
+import { StateManager } from './persist.js';
+import { resolveConfig } from './presets.js';
+const args = process.argv.slice(2);
+const command = args[0];
+function parseArgs(argv) {
+    const result = {};
+    for (let i = 1; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next && !next.startsWith('--')) {
+                result[key] = next;
+                i++;
+            }
+            else {
+                result[key] = true;
+            }
+        }
+    }
+    return result;
+}
+function cmdStatus(opts) {
+    const statePath = opts['state'];
+    let warmupInfo = 'No state file (in-memory mode)';
+    let savedAt = 'N/A';
+    if (statePath) {
+        const mgr = new StateManager(statePath);
+        const state = mgr.load();
+        if (state) {
+            const now = Date.now();
+            const dayMs = 86400000;
+            const currentDay = Math.floor((now - state.warmup.startedAt) / dayMs);
+            warmupInfo = state.warmup.graduated
+                ? 'Graduated (warmup complete)'
+                : `Day ${currentDay + 1}, sent today: ${state.warmup.dailyCounts[currentDay] || 0}`;
+            savedAt = new Date(state.savedAt).toISOString();
+        }
+        else {
+            warmupInfo = 'State file missing or corrupt';
+        }
+    }
+    const output = {
+        warmup: warmupInfo,
+        savedAt,
+        statePath: statePath || null,
+    };
+    if (opts['json']) {
+        console.log(JSON.stringify(output, null, 2));
+    }
+    else {
+        console.log('═══ baileys-antiban status ═══');
+        console.log(`Warmup:   ${output.warmup}`);
+        console.log(`Saved:    ${output.savedAt}`);
+        console.log(`State:    ${output.statePath || 'none'}`);
+    }
+}
+function cmdReset(opts) {
+    const statePath = opts['state'];
+    if (!statePath) {
+        console.error('Error: --state <path> required for reset');
+        process.exit(1);
+    }
+    if (!fs.existsSync(statePath)) {
+        console.log('State file does not exist — nothing to reset');
+        return;
+    }
+    fs.unlinkSync(statePath);
+    console.log(`✅ State file deleted: ${statePath}`);
+}
+function cmdWarmupSimulate(opts) {
+    const days = parseInt(opts['simulate'] || '7', 10);
+    const presetName = opts['preset'] || 'conservative';
+    const cfg = resolveConfig(presetName);
+    console.log(`\nWarmup simulation — preset: ${presetName}, days: ${days}`);
+    console.log('─'.repeat(50));
+    const startDate = new Date();
+    for (let day = 0; day < days; day++) {
+        const date = new Date(startDate);
+        date.setDate(date.getDate() + day);
+        const dayName = date.toLocaleDateString('en-US', { weekday: 'short', month: 'short', day: 'numeric' });
+        const limit = Math.round(cfg.day1Limit * Math.pow(cfg.growthFactor, day));
+        const bar = '█'.repeat(Math.min(30, Math.round(limit / 10)));
+        console.log(`Day ${String(day + 1).padStart(2)} ${dayName.padEnd(15)} ${String(limit).padStart(5)} msgs/day  ${bar}`);
+    }
+    console.log('─'.repeat(50));
+    console.log(`Day ${days + 1}+: graduated (unlimited by warmup)\n`);
+}
+// Main
+const opts = parseArgs(args);
+switch (command) {
+    case 'status':
+        cmdStatus(opts);
+        break;
+    case 'reset':
+        cmdReset(opts);
+        break;
+    case 'warmup':
+        if (opts['simulate']) {
+            cmdWarmupSimulate(opts);
+        }
+        else {
+            console.error('Usage: npx baileys-antiban warmup --simulate <days> [--preset conservative|moderate|aggressive]');
+            process.exit(1);
+        }
+        break;
+    default:
+        console.log('baileys-antiban v3.0');
+        console.log('');
+        console.log('Commands:');
+        console.log('  status [--state <path>] [--json]     Show warmup and health status');
+        console.log('  reset --state <path>                  Delete state file');
+        console.log('  warmup --simulate <days> [--preset]  Show warmup schedule');
+        console.log('');
+        console.log('Examples:');
+        console.log('  npx baileys-antiban status --state ./antiban-state.json');
+        console.log('  npx baileys-antiban warmup --simulate 7 --preset moderate');
+        console.log('  npx baileys-antiban reset --state ./antiban-state.json');
+}

package/dist/health.d.ts

@@ -45,6 +45,8 @@ export declare class HealthMonitor {
     private startTime;
     private paused;
     private lastRisk;
+    private lastBadEventTime;
+    private lastEventWasSevere;
     constructor(config?: Partial<HealthMonitorConfig>);
     /**
      * Record a disconnection event

package/dist/health.js

@@ -24,6 +24,8 @@ export class HealthMonitor {
     startTime = Date.now();
     paused = false;
     lastRisk = 'low';
+    lastBadEventTime = Date.now();
+    lastEventWasSevere = false;
     constructor(config = {}) {
         this.config = { ...DEFAULT_CONFIG, ...config };
     }
@@ -32,16 +34,20 @@ export class HealthMonitor {
      */
     recordDisconnect(reason) {
         const reasonStr = String(reason);
-        // 403 = Forbidden (WhatsApp blocking)
         if (reasonStr === '403' || reasonStr === 'forbidden') {
             this.events.push({ type: 'forbidden', timestamp: Date.now(), detail: reasonStr });
+            this.lastBadEventTime = Date.now();
+            this.lastEventWasSevere = true;
         }
-        // 401 = Logged out (possible temp ban)
         else if (reasonStr === '401' || reasonStr === 'loggedOut') {
             this.events.push({ type: 'loggedOut', timestamp: Date.now(), detail: reasonStr });
+            this.lastBadEventTime = Date.now();
+            this.lastEventWasSevere = true;
         }
         else {
             this.events.push({ type: 'disconnect', timestamp: Date.now(), detail: reasonStr });
+            this.lastBadEventTime = Date.now();
+            this.lastEventWasSevere = false;
         }
         this.checkAndNotify();
     }
@@ -56,6 +62,8 @@ export class HealthMonitor {
      */
     recordMessageFailed(error) {
         this.events.push({ type: 'messageFailed', timestamp: Date.now(), detail: error });
+        this.lastBadEventTime = Date.now();
+        this.lastEventWasSevere = false;
         this.checkAndNotify();
     }
     /**
@@ -63,6 +71,8 @@ export class HealthMonitor {
      */
     recordReachoutTimelock(detail) {
         this.events.push({ type: 'reachoutTimelocked', timestamp: Date.now(), detail });
+        this.lastBadEventTime = Date.now();
+        this.lastEventWasSevere = false;
         this.checkAndNotify();
     }
     /**
@@ -110,6 +120,12 @@ export class HealthMonitor {
         }
         // Determine risk level
         score = Math.min(100, score);
+        // Tiered decay: recover based on time since last bad event
+        // Severe (403/401): 2pts/min — ~50min to clear 100pts
+        // Normal: 5pts/min — ~20min to clear 100pts
+        const minutesSinceLastBad = (now - this.lastBadEventTime) / 60000;
+        const decayRate = this.lastEventWasSevere ? 2 : 5;
+        score = Math.max(0, score - Math.floor(minutesSinceLastBad * decayRate));
         let risk;
         if (score >= 85)
             risk = 'critical';
@@ -174,6 +190,8 @@ export class HealthMonitor {
         this.startTime = Date.now();
         this.paused = false;
         this.lastRisk = 'low';
+        this.lastBadEventTime = Date.now();
+        this.lastEventWasSevere = false;
     }
     cleanup(now) {
         // Keep last 6 hours of events

package/dist/index.d.ts

@@ -28,3 +28,6 @@ export { ContentVariator, type VariatorConfig } from './contentVariator.js';
 export { WebhookAlerts, type WebhookConfig } from './webhooks.js';
 export { Scheduler, type SchedulerConfig } from './scheduler.js';
 export { type StateAdapter, FileStateAdapter } from './stateAdapter.js';
+export { resolveConfig, PRESETS, type AntiBanInput, type ResolvedConfig, type PresetName } from './presets.js';
+export { StateManager, type PersistedState } from './persist.js';
+export { isGroup, isNewsletter, isBroadcast, shouldUseGroupProfile, applyGroupMultiplier, type RateLimits } from './profiles.js';

package/dist/index.js

@@ -37,3 +37,7 @@ export { WebhookAlerts } from './webhooks.js';
 export { Scheduler } from './scheduler.js';
 // State persistence
 export { FileStateAdapter } from './stateAdapter.js';
+// v3.0 new modules
+export { resolveConfig, PRESETS } from './presets.js';
+export { StateManager } from './persist.js';
+export { isGroup, isNewsletter, isBroadcast, shouldUseGroupProfile, applyGroupMultiplier } from './profiles.js';

package/dist/persist.d.ts

@@ -0,0 +1,28 @@
+import type { WarmUpState } from './warmup.js';
+export interface PersistedState {
+    warmup: WarmUpState;
+    knownChats: string[];
+    savedAt: number;
+    version: 3;
+}
+/**
+ * Manages persisted state for a single baileys-antiban instance.
+ *
+ * **Single-writer assumption:** No file lock is used. Two processes sharing
+ * the same state file will race on concurrent writes. Use separate state
+ * files per process to avoid data corruption.
+ */
+export declare class StateManager {
+    private path;
+    private debounceTimer;
+    constructor(filePath: string);
+    load(): PersistedState | null;
+    /** Debounced save — called after every send (5s delay) */
+    saveDebounced(state: PersistedState): void;
+    /** Immediate save — called after health events (ban/restriction) */
+    saveImmediate(state: PersistedState): void;
+    /** Flush/cancel pending debounced write (for tests and process exit) */
+    flush(): void;
+    destroy(): void;
+    private writeFile;
+}

package/dist/persist.js

@@ -0,0 +1,79 @@
+import * as fs from 'fs';
+const KNOWN_CHATS_MAX = 1000;
+const DEBOUNCE_MS = 5000;
+/**
+ * Manages persisted state for a single baileys-antiban instance.
+ *
+ * **Single-writer assumption:** No file lock is used. Two processes sharing
+ * the same state file will race on concurrent writes. Use separate state
+ * files per process to avoid data corruption.
+ */
+export class StateManager {
+    path;
+    debounceTimer = null;
+    constructor(filePath) {
+        this.path = filePath;
+    }
+    load() {
+        try {
+            const raw = fs.readFileSync(this.path, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed.version !== 3) {
+                console.warn('[baileys-antiban] WARN: corrupt state file or version mismatch, starting fresh');
+                return null;
+            }
+            return parsed;
+        }
+        catch {
+            // Missing file = silent null. Corrupt JSON = warn.
+            if (fs.existsSync(this.path)) {
+                console.warn('[baileys-antiban] WARN: corrupt state file, starting fresh');
+            }
+            return null;
+        }
+    }
+    /** Debounced save — called after every send (5s delay) */
+    saveDebounced(state) {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.writeFile(state);
+            this.debounceTimer = null;
+        }, DEBOUNCE_MS);
+    }
+    /** Immediate save — called after health events (ban/restriction) */
+    saveImmediate(state) {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        this.writeFile(state);
+    }
+    /** Flush/cancel pending debounced write (for tests and process exit) */
+    flush() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+    }
+    destroy() {
+        this.flush();
+    }
+    writeFile(state) {
+        const toSave = {
+            ...state,
+            savedAt: Date.now(),
+            // LRU eviction: keep last KNOWN_CHATS_MAX entries
+            knownChats: state.knownChats.length > KNOWN_CHATS_MAX
+                ? state.knownChats.slice(-KNOWN_CHATS_MAX)
+                : state.knownChats,
+        };
+        try {
+            fs.writeFileSync(this.path, JSON.stringify(toSave, null, 2), 'utf-8');
+        }
+        catch (err) {
+            console.warn(`[baileys-antiban] WARN: failed to write state to ${this.path}:`, err);
+        }
+    }
+}

package/dist/presets.d.ts

@@ -0,0 +1,24 @@
+import type { BanRiskLevel } from './health.js';
+export interface ResolvedConfig {
+    maxPerMinute: number;
+    maxPerHour: number;
+    maxPerDay: number;
+    minDelayMs: number;
+    maxDelayMs: number;
+    newChatDelayMs: number;
+    warmupDays: number;
+    day1Limit: number;
+    growthFactor: number;
+    inactivityThresholdHours: number;
+    autoPauseAt: BanRiskLevel;
+    groupMultiplier: number;
+    groupProfiles: boolean;
+    persist?: string;
+    logging: boolean;
+}
+export type PresetName = 'conservative' | 'moderate' | 'aggressive';
+export type AntiBanInput = PresetName | Partial<ResolvedConfig & {
+    preset?: PresetName;
+}> | undefined;
+export declare const PRESETS: Record<PresetName, ResolvedConfig>;
+export declare function resolveConfig(input: AntiBanInput): ResolvedConfig;

package/dist/presets.js

@@ -0,0 +1,67 @@
+export const PRESETS = {
+    conservative: {
+        maxPerMinute: 5,
+        maxPerHour: 100,
+        maxPerDay: 800,
+        minDelayMs: 2500,
+        maxDelayMs: 7000,
+        newChatDelayMs: 4000,
+        warmupDays: 10,
+        day1Limit: 15,
+        growthFactor: 1.8,
+        inactivityThresholdHours: 72,
+        autoPauseAt: 'medium',
+        groupMultiplier: 0.5,
+        groupProfiles: false,
+        logging: true,
+    },
+    moderate: {
+        maxPerMinute: 10,
+        maxPerHour: 300,
+        maxPerDay: 1500,
+        minDelayMs: 1500,
+        maxDelayMs: 5000,
+        newChatDelayMs: 3000,
+        warmupDays: 7,
+        day1Limit: 20,
+        growthFactor: 1.8,
+        inactivityThresholdHours: 72,
+        autoPauseAt: 'high',
+        groupMultiplier: 0.7,
+        groupProfiles: false,
+        logging: true,
+    },
+    aggressive: {
+        maxPerMinute: 20,
+        maxPerHour: 800,
+        maxPerDay: 4000,
+        minDelayMs: 800,
+        maxDelayMs: 3000,
+        newChatDelayMs: 2000,
+        warmupDays: 4,
+        day1Limit: 35,
+        growthFactor: 2.0,
+        inactivityThresholdHours: 48,
+        autoPauseAt: 'critical',
+        groupMultiplier: 0.9,
+        groupProfiles: false,
+        logging: true,
+    },
+};
+export function resolveConfig(input) {
+    if (input === undefined) {
+        return { ...PRESETS.conservative };
+    }
+    if (typeof input === 'string') {
+        if (!(input in PRESETS)) {
+            throw new Error(`Unknown preset "${input}". Valid: ${Object.keys(PRESETS).join(', ')}`);
+        }
+        return { ...PRESETS[input] };
+    }
+    // Object form — extract preset base, merge overrides
+    const { preset = 'conservative', ...overrides } = input;
+    if (!(preset in PRESETS)) {
+        throw new Error(`Unknown preset "${preset}". Valid: ${Object.keys(PRESETS).join(', ')}`);
+    }
+    return { ...PRESETS[preset], ...overrides };
+}

package/dist/profiles.d.ts

@@ -0,0 +1,22 @@
+export interface RateLimits {
+    maxPerMinute: number;
+    maxPerHour: number;
+    maxPerDay: number;
+}
+/** @g.us = WhatsApp group */
+export declare function isGroup(jid: string): boolean;
+/** @newsletter = WhatsApp newsletter/channel */
+export declare function isNewsletter(jid: string): boolean;
+/** status@broadcast = broadcast list */
+export declare function isBroadcast(jid: string): boolean;
+/**
+ * Returns true if the JID should use stricter (group) rate limits.
+ * Groups and newsletters both get the group multiplier in v3.
+ * v4: separate newsletter profile.
+ */
+export declare function shouldUseGroupProfile(jid: string): boolean;
+/**
+ * Scale rate limits by multiplier for group/newsletter JIDs.
+ * Floors to integer, minimum 1 per limit.
+ */
+export declare function applyGroupMultiplier(limits: RateLimits, multiplier: number): RateLimits;

package/dist/profiles.js

@@ -0,0 +1,31 @@
+/** @g.us = WhatsApp group */
+export function isGroup(jid) {
+    return jid.endsWith('@g.us');
+}
+/** @newsletter = WhatsApp newsletter/channel */
+export function isNewsletter(jid) {
+    return jid.endsWith('@newsletter');
+}
+/** status@broadcast = broadcast list */
+export function isBroadcast(jid) {
+    return jid === 'status@broadcast' || jid.endsWith('@broadcast');
+}
+/**
+ * Returns true if the JID should use stricter (group) rate limits.
+ * Groups and newsletters both get the group multiplier in v3.
+ * v4: separate newsletter profile.
+ */
+export function shouldUseGroupProfile(jid) {
+    return isGroup(jid) || isNewsletter(jid);
+}
+/**
+ * Scale rate limits by multiplier for group/newsletter JIDs.
+ * Floors to integer, minimum 1 per limit.
+ */
+export function applyGroupMultiplier(limits, multiplier) {
+    return {
+        maxPerMinute: Math.max(1, Math.floor(limits.maxPerMinute * multiplier)),
+        maxPerHour: Math.max(1, Math.floor(limits.maxPerHour * multiplier)),
+        maxPerDay: Math.max(1, Math.floor(limits.maxPerDay * multiplier)),
+    };
+}

package/dist/rateLimiter.d.ts

@@ -61,6 +61,10 @@ export declare class RateLimiter {
      * Get current usage stats
      */
     getStats(): RateLimiterStats;
+    /** Get the set of known chat JIDs (for state persistence) */
+    getKnownChats(): Set<string>;
+    /** Restore known chats from persisted state */
+    restoreKnownChats(chats: string[]): void;
     private cleanup;
     /** Random delay between min and max (gaussian-ish distribution) */
     private jitter;

package/dist/rateLimiter.js

@@ -154,6 +154,16 @@ export class RateLimiter {
             knownChats: this.knownChats.size,
         };
     }
+    /** Get the set of known chat JIDs (for state persistence) */
+    getKnownChats() {
+        return this.knownChats;
+    }
+    /** Restore known chats from persisted state */
+    restoreKnownChats(chats) {
+        for (const jid of chats) {
+            this.knownChats.add(jid);
+        }
+    }
     cleanup(now) {
         // Remove messages older than 24 hours
         this.messages = this.messages.filter(m => now - m.timestamp < TIME_CONSTANTS.MS_PER_DAY);

package/dist/warmup.d.ts

@@ -18,8 +18,6 @@ export interface WarmUpConfig {
     growthFactor: number;
     /** Hours of inactivity before re-entering warm-up (default: 72) */
     inactivityThresholdHours: number;
-    /** Persist state to this file path (optional) */
-    statePath?: string;
 }
 export interface WarmUpState {
     /** When warm-up started */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "baileys-antiban",
-  "version": "2.1.0",
-  "description": "Transport-agnostic anti-ban middleware for Baileys and baileyrs — human-like messaging patterns to protect your WhatsApp number",
+  "version": "3.0.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",
   "type": "module",
@@ -27,6 +27,9 @@
     "test:check": "tsc --noEmit && npm test",
     "prepublishOnly": "npm run build"
   },
+  "bin": {
+    "baileys-antiban": "./dist/cli.js"
+  },
   "keywords": [
     "baileys",
     "baileyrs",
@@ -38,7 +41,20 @@
     "bot-protection",
     "whatsapp-api",
     "nodejs",
-    "transport-agnostic"
+    "transport-agnostic",
+    "whapi-alternative",
+    "whatsapp-ban",
+    "baileys-middleware",
+    "warmup",
+    "session-health",
+    "lid-resolver",
+    "disconnect-classifier",
+    "gaussian-jitter",
+    "whatsapp-automation",
+    "typescript",
+    "self-hosted",
+    "free",
+    "open-source"
   ],
   "author": "Kobus Wentzel <kobie@pop.co.za>",
   "license": "MIT",