baileys-antiban 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+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.2.0] - 2026-04-13
+
+### Added
+- **`destroy()` method** in `AntiBan` class to clean up all timers and resources
+- **`destroy()` method** in `MessageQueue` class to clean up interval timer
+- **Explicit stat interfaces** exported from library:
+  - `WarmUpStatus` interface (replaces opaque `ReturnType<WarmUp['getStatus']>`)
+  - `RateLimiterStats` interface (replaces opaque `ReturnType<RateLimiter['getStats']>`)
+- Automatic cleanup on socket close in wrapper
+
+### Fixed
+- **Timer leak**: `AntiBan` now properly cleans up `TimelockGuard.resumeTimer` on connection close
+- **Type visibility**: Consumers can now see stat object shapes without inspecting implementation
+
+### Changed
+- `wrapSocket()` now automatically calls `antiban.destroy()` when `connection.close` event fires
+- `AntiBanStats` interface now uses explicit `WarmUpStatus` and `RateLimiterStats` types
+
+## [1.1.0] - 2026-03-27
+
+### Added
+- **StateAdapter interface** for persistent state management
+- `FileStateAdapter` class for JSON file-based state persistence
+- Comprehensive TypeScript type exports for all configuration interfaces
+- `SendDecision` type export from main index
+- `HealthMonitorConfig` type export
+- Full JSDoc documentation across all modules
+- Named constants for time values (MS_PER_MINUTE, MS_PER_HOUR, etc.)
+- `identicalMessageWindowMs` config option for time-windowed duplicate tracking
+- `resumeBufferMs` config for TimelockGuard safety margin
+- Comprehensive test suite for TimelockGuard
+
+### Changed
+- **README.md** completely rewritten with practical examples and better structure
+- Simplified package.json exports (ESM-only, removed CJS)
+- Added `sideEffects: false` to package.json for better tree-shaking
+- Updated tsconfig.json with strict mode enabled
+
+### Fixed
+- **Burst reset bug** in RateLimiter: `timeSinceLast` check now happens BEFORE `lastMessageTime` update
+- **Identical message tracking** now properly expires after time window (1 hour default) instead of persisting indefinitely
+- **Cleanup logic** in RateLimiter now removes expired identical message trackers based on `lastSeen` timestamp
+- **Hourly/daily limit delays** now properly sort messages by timestamp to find the oldest message
+- **Timer race condition** in TimelockGuard: generation counter prevents stale timer callbacks from firing
+
+### Improved
+- More accurate ban risk scoring in HealthMonitor
+- Better handling of 463 reachout timelock errors
+- Clearer error messages and logging
+- More robust state management across all components
+- Better TypeScript strict mode compliance
+
+## [1.0.0] - 2026-03-24
+
+### Added
+- Initial npm release
+- Core anti-ban features:
+  - Rate limiting with human-like timing patterns
+  - Warm-up system for new numbers (7-day gradual ramp)
+  - Health monitoring with auto-pause
+  - Socket wrapper for drop-in protection
+  - TimelockGuard for 463 reachout error handling
+- Advanced features:
+  - Message queue with auto-retry
+  - Content variator to avoid identical messages
+  - Smart scheduler for time-of-day optimization
+  - Webhook alerts (Telegram, Discord, custom)
+- Comprehensive test suite
+- Live test bot for real WhatsApp testing
+- Stress test bot for performance validation
+
+### Technical
+- TypeScript codebase with full type definitions
+- Peer dependency: Baileys >=6.0.0
+- Gaussian jitter for realistic delays
+- Typing simulation based on message length
+- Burst allowance for natural conversation flow
+- Persistent warm-up state support
+
+## [Pre-1.0.0] - Development
+
+### 2026-03-23
+- Added comprehensive smoke test suite
+- Implemented live test bot for real-world validation
+
+### 2026-03-22
+- Version 2.0 feature set: MessageQueue, ContentVariator, Scheduler, WebhookAlerts
+- Added .gitignore and cleaned up repository
+
+### 2026-03-20
+- Initial implementation: RateLimiter, WarmUp, HealthMonitor
+- Socket wrapper with automatic protection
+- Core anti-ban logic and safety mechanisms
+
+---
+
+## Upgrade Notes
+
+### 1.0.0
+This is the first stable release. API is considered stable and follows semantic versioning from this point forward.
+
+## Links
+- [GitHub Repository](https://github.com/kobie3717/baileys-antiban)
+- [npm Package](https://www.npmjs.com/package/baileys-antiban)
+- [Issues](https://github.com/kobie3717/baileys-antiban/issues)

package/README.md

@@ -1,4 +1,8 @@
-# baileys-antiban 🛡️
+# baileys-antiban
+
+[![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)
 
 Anti-ban middleware for [Baileys](https://github.com/WhiskeySockets/Baileys) — protect your WhatsApp number with human-like messaging patterns.
 
@@ -6,21 +10,24 @@ Anti-ban middleware for [Baileys](https://github.com/WhiskeySockets/Baileys) —
 
 WhatsApp bans numbers that behave like bots. This library makes your Baileys bot behave like a human:
 
-- **Rate limiting** with human-like timing (gaussian jitter, typing simulation)
+- **Rate limiting** with human-like timing (Gaussian jitter, typing simulation)
 - **Warm-up** for new numbers (gradual activity increase over 7 days)
 - **Health monitoring** that detects ban warning signs before it's too late
+- **Timelock handling** for 463 reachout errors
 - **Auto-pause** when risk gets too high
 - **Drop-in wrapper** — one line to protect your existing bot
 
-## Install
+## Installation
 
 ```bash
 npm install baileys-antiban
 ```
 
+Requires Node.js ≥16 and Baileys ≥6.0.0.
+
 ## Quick Start
 
-### Option 1: Wrap your socket (easiest)
+### Option 1: Wrap Your Socket (Easiest)
 
 ```typescript
 import makeWASocket from 'baileys';
@@ -36,20 +43,20 @@ await safeSock.sendMessage(jid, { text: 'Hello!' });
 console.log(safeSock.antiban.getStats());
 ```
 
-### Option 2: Manual control
+### Option 2: Manual Control
 
 ```typescript
 import { AntiBan } from 'baileys-antiban';
 
 const antiban = new AntiBan();
 
-// Before every message:
+// Before every message
 const decision = await antiban.beforeSend(recipient, content);
 
 if (decision.allowed) {
   // Wait the recommended delay
   await new Promise(r => setTimeout(r, decision.delayMs));
-  
+
   try {
     await sock.sendMessage(recipient, { text: content });
     antiban.afterSend(recipient, content);
@@ -60,7 +67,7 @@ if (decision.allowed) {
   console.log('Blocked:', decision.reason);
 }
 
-// In your connection.update handler:
+// In your connection.update handler
 sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
   if (connection === 'close') {
     antiban.onDisconnect(lastDisconnect?.error?.output?.statusCode);
@@ -73,34 +80,50 @@ sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
 
 ## Configuration
 
+All options are optional — defaults are conservative and safe.
+
 ```typescript
+import { AntiBan } from 'baileys-antiban';
+
 const antiban = new AntiBan({
   rateLimiter: {
-    maxPerMinute: 8,        // Max messages per minute (default: 8)
-    maxPerHour: 200,         // Max messages per hour (default: 200)
-    maxPerDay: 1500,         // Max messages per day (default: 1500)
-    minDelayMs: 1500,        // Min delay between messages (default: 1500ms)
-    maxDelayMs: 5000,        // Max delay between messages (default: 5000ms)
-    newChatDelayMs: 3000,    // Extra delay for first message to new chat
-    maxIdenticalMessages: 3, // Block after 3 identical messages
-    burstAllowance: 3,       // Fast messages before rate limiting kicks in
+    maxPerMinute: 8,              // Max messages per minute (default: 8)
+    maxPerHour: 200,               // Max messages per hour (default: 200)
+    maxPerDay: 1500,               // Max messages per day (default: 1500)
+    minDelayMs: 1500,              // Min delay between messages (default: 1500ms)
+    maxDelayMs: 5000,              // Max delay between messages (default: 5000ms)
+    newChatDelayMs: 3000,          // Extra delay for first message to new chat
+    maxIdenticalMessages: 3,       // Block after 3 identical messages
+    burstAllowance: 3,             // Fast messages before rate limiting kicks in
+    identicalMessageWindowMs: 3600000, // 1 hour window for identical tracking
   },
   warmUp: {
-    warmUpDays: 7,           // Days to full capacity (default: 7)
-    day1Limit: 20,           // Messages allowed on day 1 (default: 20)
-    growthFactor: 1.8,       // Daily limit multiplier (~doubles each day)
-    inactivityThresholdHours: 72, // Re-enter warm-up after 3 days inactive
+    warmUpDays: 7,                 // Days to full capacity (default: 7)
+    day1Limit: 20,                 // Messages allowed on day 1 (default: 20)
+    growthFactor: 1.8,             // Daily limit multiplier (~doubles each day)
+    inactivityThresholdHours: 72,  // Re-enter warm-up after 3 days inactive
   },
   health: {
-    disconnectWarningThreshold: 3,  // Disconnects/hour before warning
-    disconnectCriticalThreshold: 5, // Disconnects/hour before critical
-    failedMessageThreshold: 5,      // Failed messages/hour before warning
-    autoPauseAt: 'high',            // Auto-pause at this risk level
+    disconnectWarningThreshold: 3,   // Disconnects/hour before warning
+    disconnectCriticalThreshold: 5,  // Disconnects/hour before critical
+    failedMessageThreshold: 5,       // Failed messages/hour before warning
+    autoPauseAt: 'high',             // Auto-pause at this risk level
     onRiskChange: (status) => {
       // Custom handler — send alert, log, etc.
       console.log(`Risk: ${status.risk}`, status.recommendation);
     },
   },
+  timelock: {
+    resumeBufferMs: 10000,           // Extra 10s safety buffer after expiry
+    onTimelockDetected: (state) => {
+      // Called when 463 reachout timelock is detected
+      console.log(`TIMELOCKED until ${state.expiresAt}`);
+    },
+    onTimelockLifted: (state) => {
+      // Called when timelock expires or is manually lifted
+      console.log('Timelock lifted — resuming normal operation');
+    },
+  },
   logging: true, // Console logging (default: true)
 });
 ```
@@ -114,6 +137,7 @@ The health monitor tracks ban warning signs:
 | Frequent disconnects | +15 to +30 | WhatsApp dropping your connection |
 | 403 Forbidden | +40 per event | WhatsApp actively blocking you |
 | 401 Logged Out | +60 | Possible temporary ban |
+| 463 Reachout Timelock | +25 | Messaging new contacts temporarily blocked |
 | Failed messages | +20 | Messages not going through |
 
 Risk levels:
@@ -131,31 +155,84 @@ console.log(status.recommendation); // Human-readable advice
 
 ## Warm-Up Schedule
 
-New numbers ramp up gradually:
+New numbers ramp up gradually over 7 days:
 
 | Day | Message Limit |
 |-----|--------------|
-| 1 | 20 |
-| 2 | 36 |
-| 3 | 65 |
-| 4 | 117 |
-| 5 | 210 |
-| 6 | 378 |
-| 7 | 680 |
-| 8+ | Unlimited |
+| 1   | 20           |
+| 2   | 36           |
+| 3   | 65           |
+| 4   | 117          |
+| 5   | 210          |
+| 6   | 378          |
+| 7   | 680          |
+| 8+  | Unlimited    |
+
+### Persisting Warm-Up State
 
-Persist warm-up state between restarts:
+Warm-up progress is lost on restart unless you persist it:
 
 ```typescript
-// Save state
+import fs from 'fs/promises';
+
+// On shutdown (or periodically)
 const state = antiban.exportWarmUpState();
-fs.writeFileSync('warmup.json', JSON.stringify(state));
+await fs.writeFile('warmup.json', JSON.stringify(state));
 
-// Restore state
-const saved = JSON.parse(fs.readFileSync('warmup.json', 'utf-8'));
+// On startup
+const saved = JSON.parse(await fs.readFile('warmup.json', 'utf-8'));
 const antiban = new AntiBan(config, saved);
 ```
 
+**Better: Use StateAdapter**
+
+```typescript
+import { AntiBan, FileStateAdapter } from 'baileys-antiban';
+
+const adapter = new FileStateAdapter('./bot-state');
+const antiban = new AntiBan({ /* config */ });
+
+// Load state on startup
+const warmupState = await adapter.load('warmup');
+if (warmupState) {
+  antiban = new AntiBan({ /* config */ }, warmupState);
+}
+
+// Save state periodically (every 5 minutes)
+setInterval(async () => {
+  await adapter.save('warmup', antiban.exportWarmUpState());
+}, 300000);
+
+// Save on clean shutdown
+process.on('SIGTERM', async () => {
+  await adapter.save('warmup', antiban.exportWarmUpState());
+  process.exit(0);
+});
+```
+
+## Timelock Handling (463 Errors)
+
+WhatsApp sometimes blocks messaging **new contacts** temporarily (reachout timelock). This library automatically:
+
+- Detects 463 errors
+- Blocks new contact messages during the timelock
+- Allows existing contacts and groups to continue
+- Auto-resumes when the timelock expires
+
+```typescript
+// Timelock state is automatically managed
+const decision = await antiban.beforeSend('new-contact@s.whatsapp.net', 'Hello');
+
+if (!decision.allowed && decision.reason?.includes('timelock')) {
+  console.log('Timelocked — cannot message new contacts right now');
+  console.log('Existing chats still work');
+}
+
+// Manual control if needed
+antiban.timelock.lift();  // Manually lift
+antiban.timelock.reset(); // Clear all state
+```
+
 ## Rate Limiter Details
 
 The rate limiter mimics human behavior:
@@ -164,10 +241,12 @@ The rate limiter mimics human behavior:
 - **Typing simulation**: Longer messages get longer delays (~30ms per character)
 - **New chat penalty**: First message to an unknown recipient gets extra delay
 - **Burst allowance**: First 3 messages are faster (humans do this too)
-- **Identical message detection**: Blocks sending the same text more than 3 times
-- **Time-of-day awareness**: Built-in support for custom schedules
+- **Identical message detection**: Blocks sending the same text repeatedly within 1 hour
+- **Per-minute/hour/day limits**: Multiple layers of protection
 
-## Message Queue
+## Optional Features
+
+### Message Queue
 
 Queue messages for safe, paced delivery with auto-retry:
 
@@ -190,10 +269,9 @@ queue.start();
 // Events
 queue.on('sent', (msg) => console.log('Sent:', msg.id));
 queue.on('failed', (msg, err) => console.log('Failed:', msg.id, err));
-queue.on('retry', (msg, attempt, delay) => console.log(`Retry #${attempt} in ${delay}ms`));
 ```
 
-## Content Variator
+### Content Variator
 
 Auto-vary messages to avoid identical message detection:
 
@@ -201,21 +279,18 @@ Auto-vary messages to avoid identical message detection:
 import { ContentVariator } from 'baileys-antiban';
 
 const variator = new ContentVariator({
-  zeroWidthChars: true,    // Invisible character variations
+  zeroWidthChars: true,      // Invisible character variations
   punctuationVariation: true, // Subtle punctuation changes
-  synonyms: true,           // Replace common words with synonyms
+  synonyms: true,             // Replace common words with synonyms
 });
 
 // Each call returns a unique variation
 const msg1 = variator.vary('Check out our auction today!');
 const msg2 = variator.vary('Check out our auction today!');
 // msg1 !== msg2 (technically different, looks the same to humans)
-
-// Generate bulk variations for broadcast
-const variations = variator.varyBulk('Hello everyone!', 50);
 ```
 
-## Smart Scheduler
+### Smart Scheduler
 
 Send during safe hours with realistic daily patterns:
 
@@ -224,10 +299,10 @@ import { Scheduler } from 'baileys-antiban';
 
 const scheduler = new Scheduler({
   timezone: 'Africa/Johannesburg',
-  activeHours: [8, 21],     // 8 AM to 9 PM
-  weekendFactor: 0.5,       // Half speed on weekends
-  peakHours: [10, 14],      // Faster during business hours
-  lunchBreak: [12, 13],     // Slow down at lunch
+  activeHours: [8, 21],       // 8 AM to 9 PM
+  weekendFactor: 0.5,         // Half speed on weekends
+  peakHours: [10, 14],        // Faster during business hours
+  lunchBreak: [12, 13],       // Slow down at lunch
 });
 
 if (scheduler.isActiveTime()) {
@@ -238,7 +313,7 @@ if (scheduler.isActiveTime()) {
 }
 ```
 
-## Webhook Alerts
+### Webhook Alerts
 
 Get notified when risk level changes:
 
@@ -246,16 +321,12 @@ Get notified when risk level changes:
 import { WebhookAlerts } from 'baileys-antiban';
 
 const alerts = new WebhookAlerts({
-  // Telegram alerts
   telegram: { botToken: 'BOT_TOKEN', chatId: 'CHAT_ID' },
-  // Discord alerts
   discord: { webhookUrl: 'https://discord.com/api/webhooks/...' },
-  // Generic webhooks
   urls: ['https://your-server.com/webhook'],
   minRiskLevel: 'medium',
 });
 
-// Wire into health monitor
 const antiban = new AntiBan({
   health: {
     onRiskChange: (status) => alerts.alert(status),
@@ -276,6 +347,19 @@ antiban.resume();
 antiban.reset();
 ```
 
+## Disclaimer
+
+**⚠️ This library reduces the risk of WhatsApp bans through rate limiting and human-like behavior patterns, but cannot guarantee prevention of bans.**
+
+WhatsApp's anti-bot detection systems are constantly evolving. This library implements best practices based on observed behaviors, but:
+
+- No anti-ban solution is 100% effective
+- WhatsApp may update their detection algorithms at any time
+- Violating WhatsApp's Terms of Service may result in permanent bans
+- **Always comply with WhatsApp's official policies and usage limits**
+
+Use responsibly and at your own risk.
+
 ## Best Practices
 
 1. **Always warm up new numbers** — Don't send 1000 messages on day 1
@@ -285,7 +369,210 @@ antiban.reset();
 5. **Persist warm-up state** — Don't lose progress on restart
 6. **Monitor your stats** — Check `getStats()` regularly
 7. **Have a backup number** — Bans happen despite best efforts
+8. **Stay within WhatsApp's ToS** — Don't spam, don't violate privacy
+
+## Troubleshooting
+
+### Messages being blocked unexpectedly
+
+Check the health monitor status:
+```typescript
+const stats = antiban.getStats();
+console.log(stats.health.risk);    // Check risk level
+console.log(stats.health.reasons); // See what triggered it
+```
+
+### "Reachout timelocked" messages
+
+This is a 463 error from WhatsApp. The library automatically handles it:
+
+- Existing chats continue to work
+- New contacts are blocked temporarily
+- Auto-resumes when the timelock expires
+
+### Warm-up limits too restrictive
+
+Adjust the warm-up configuration:
+```typescript
+const antiban = new AntiBan({
+  warmUp: {
+    warmUpDays: 5,    // Faster warm-up
+    day1Limit: 30,    // Higher initial limit
+    growthFactor: 2.0, // Faster growth
+  },
+});
+```
+
+### Rate limiter too aggressive
+
+Increase the limits:
+```typescript
+const antiban = new AntiBan({
+  rateLimiter: {
+    maxPerMinute: 10,  // More messages per minute
+    maxPerHour: 300,
+    minDelayMs: 1000,  // Shorter delays
+  },
+});
+```
+
+### State not persisting across restarts
+
+Use the FileStateAdapter:
+```typescript
+import { FileStateAdapter } from 'baileys-antiban';
+
+const adapter = new FileStateAdapter('./state');
+
+// Save periodically
+setInterval(async () => {
+  await adapter.save('warmup', antiban.exportWarmUpState());
+}, 300000);
+```
+
+## API Reference
+
+### AntiBan
+
+```typescript
+class AntiBan {
+  constructor(config?: AntiBanConfig, warmUpState?: WarmUpState);
+
+  // Message control
+  beforeSend(recipient: string, content: string): Promise<SendDecision>;
+  afterSend(recipient: string, content: string): void;
+  afterSendFailed(error?: string): void;
+
+  // Connection events
+  onDisconnect(reason: string | number): void;
+  onReconnect(): void;
+
+  // State
+  getStats(): AntiBanStats;
+  exportWarmUpState(): WarmUpState;
+
+  // Control
+  pause(): void;
+  resume(): void;
+  reset(): void;
+
+  // Access to components
+  timelock: TimelockGuard;
+}
+```
+
+### RateLimiter
+
+```typescript
+class RateLimiter {
+  constructor(config?: Partial<RateLimiterConfig>);
+
+  getDelay(recipient: string, content: string): Promise<number>;
+  record(recipient: string, content: string): void;
+  getStats(): { lastMinute, lastHour, lastDay, limits, knownChats };
+}
+```
+
+### WarmUp
+
+```typescript
+class WarmUp {
+  constructor(config?: Partial<WarmUpConfig>, state?: WarmUpState);
+
+  canSend(): boolean;
+  getDailyLimit(): number;
+  record(): void;
+  getStatus(): { phase, day, totalDays, todayLimit, todaySent, progress };
+  exportState(): WarmUpState;
+  reset(): void;
+}
+```
+
+### HealthMonitor
+
+```typescript
+class HealthMonitor {
+  constructor(config?: Partial<HealthMonitorConfig>);
+
+  recordDisconnect(reason: string | number): void;
+  recordReconnect(): void;
+  recordMessageFailed(error?: string): void;
+  recordReachoutTimelock(detail?: string): void;
+
+  getStatus(): HealthStatus;
+  isPaused(): boolean;
+  setPaused(paused: boolean): void;
+  reset(): void;
+}
+```
+
+### TimelockGuard
+
+```typescript
+class TimelockGuard {
+  constructor(config?: Partial<TimelockGuardConfig>);
+
+  record463Error(): void;
+  onTimelockUpdate(data: { isActive?, timeEnforcementEnds?, enforcementType? }): void;
+
+  canSend(jid: string): { allowed: boolean; reason?: string };
+  isTimelocked(): boolean;
+
+  registerKnownChat(jid: string): void;
+  registerKnownChats(jids: string[]): void;
+  getKnownChats(): Set<string>;
+
+  getState(): TimelockState;
+  lift(): void;
+  reset(): void;
+}
+```
+
+### StateAdapter
+
+```typescript
+interface StateAdapter {
+  save(key: string, state: any): Promise<void>;
+  load(key: string): Promise<any | null>;
+  delete(key: string): Promise<void>;
+  list(): Promise<string[]>;
+}
+
+class FileStateAdapter implements StateAdapter {
+  constructor(basePath: string);
+  // Implements all StateAdapter methods
+}
+```
+
+## TypeScript Support
+
+This package is written in TypeScript and includes full type definitions.
+
+```typescript
+import type {
+  AntiBanConfig,
+  AntiBanStats,
+  SendDecision,
+  RateLimiterConfig,
+  WarmUpConfig,
+  WarmUpState,
+  HealthMonitorConfig,
+  HealthStatus,
+  BanRiskLevel,
+  TimelockGuardConfig,
+  TimelockState,
+  StateAdapter,
+} from 'baileys-antiban';
+```
+
+## Contributing
+
+Contributions are welcome! Please open an issue before submitting a PR.
+
+## Related Projects
+
+- **[WaSP (WhatsApp Session Protocol)](https://github.com/kobie3717/wasp)** — Full-featured WhatsApp session management with built-in anti-ban (includes this library)
 
 ## License
 
-MIT — Built by [WhatsAuction](https://whatsauction.co.za) 🇿🇦
+MIT — Built for [WhatsAuction](https://whatsauction.co.za) 🇿🇦