baileys-antiban 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kobus Wentzel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,291 @@
+# baileys-antiban 🛡️
+
+Anti-ban middleware for [Baileys](https://github.com/WhiskeySockets/Baileys) — protect your WhatsApp number with human-like messaging patterns.
+
+## Why?
+
+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)
+- **Warm-up** for new numbers (gradual activity increase over 7 days)
+- **Health monitoring** that detects ban warning signs before it's too late
+- **Auto-pause** when risk gets too high
+- **Drop-in wrapper** — one line to protect your existing bot
+
+## Install
+
+```bash
+npm install baileys-antiban
+```
+
+## Quick Start
+
+### Option 1: Wrap your socket (easiest)
+
+```typescript
+import makeWASocket from 'baileys';
+import { wrapSocket } from 'baileys-antiban';
+
+const sock = makeWASocket({ /* your config */ });
+const safeSock = wrapSocket(sock);
+
+// Use safeSock instead of sock — sendMessage is now protected
+await safeSock.sendMessage(jid, { text: 'Hello!' });
+
+// Check health anytime
+console.log(safeSock.antiban.getStats());
+```
+
+### Option 2: Manual control
+
+```typescript
+import { AntiBan } from 'baileys-antiban';
+
+const antiban = new AntiBan();
+
+// 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);
+  } catch (err) {
+    antiban.afterSendFailed(err.message);
+  }
+} else {
+  console.log('Blocked:', decision.reason);
+}
+
+// In your connection.update handler:
+sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+  if (connection === 'close') {
+    antiban.onDisconnect(lastDisconnect?.error?.output?.statusCode);
+  }
+  if (connection === 'open') {
+    antiban.onReconnect();
+  }
+});
+```
+
+## Configuration
+
+```typescript
+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
+  },
+  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
+  },
+  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
+    onRiskChange: (status) => {
+      // Custom handler — send alert, log, etc.
+      console.log(`Risk: ${status.risk}`, status.recommendation);
+    },
+  },
+  logging: true, // Console logging (default: true)
+});
+```
+
+## Health Monitor
+
+The health monitor tracks ban warning signs:
+
+| Signal | Risk Score | What It Means |
+|--------|-----------|---------------|
+| 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 |
+| Failed messages | +20 | Messages not going through |
+
+Risk levels:
+- 🟢 **Low** (0-29): Operating normally
+- 🟡 **Medium** (30-59): Reduce messaging rate by 50%
+- 🟠 **High** (60-84): Reduce by 80%, consider pausing
+- 🔴 **Critical** (85-100): **STOP IMMEDIATELY**
+
+```typescript
+const status = antiban.getStats().health;
+console.log(status.risk);           // 'low' | 'medium' | 'high' | 'critical'
+console.log(status.score);          // 0-100
+console.log(status.recommendation); // Human-readable advice
+```
+
+## Warm-Up Schedule
+
+New numbers ramp up gradually:
+
+| Day | Message Limit |
+|-----|--------------|
+| 1 | 20 |
+| 2 | 36 |
+| 3 | 65 |
+| 4 | 117 |
+| 5 | 210 |
+| 6 | 378 |
+| 7 | 680 |
+| 8+ | Unlimited |
+
+Persist warm-up state between restarts:
+
+```typescript
+// Save state
+const state = antiban.exportWarmUpState();
+fs.writeFileSync('warmup.json', JSON.stringify(state));
+
+// Restore state
+const saved = JSON.parse(fs.readFileSync('warmup.json', 'utf-8'));
+const antiban = new AntiBan(config, saved);
+```
+
+## Rate Limiter Details
+
+The rate limiter mimics human behavior:
+
+- **Gaussian jitter**: Delays clustered around the middle of the range, not uniform random
+- **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
+
+## Message Queue
+
+Queue messages for safe, paced delivery with auto-retry:
+
+```typescript
+import { MessageQueue } from 'baileys-antiban';
+
+const queue = new MessageQueue({ maxAttempts: 3 });
+queue.setSendFunction(async (jid, content) => {
+  await safeSock.sendMessage(jid, content);
+});
+
+// Queue messages
+queue.add('group@g.us', { text: 'Hello!' });
+queue.add('group@g.us', { text: 'Important!' }, { priority: 'high' });
+queue.addBulk(['user1@s.whatsapp.net', 'user2@s.whatsapp.net'], { text: 'Broadcast' });
+
+// Start processing
+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
+
+Auto-vary messages to avoid identical message detection:
+
+```typescript
+import { ContentVariator } from 'baileys-antiban';
+
+const variator = new ContentVariator({
+  zeroWidthChars: true,    // Invisible character variations
+  punctuationVariation: true, // Subtle punctuation changes
+  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
+
+Send during safe hours with realistic daily patterns:
+
+```typescript
+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
+});
+
+if (scheduler.isActiveTime()) {
+  const adjustedDelay = scheduler.adjustDelay(baseDelay);
+  // Send with adjusted timing
+} else {
+  console.log(`Next active in ${scheduler.msUntilActive()}ms`);
+}
+```
+
+## Webhook Alerts
+
+Get notified when risk level changes:
+
+```typescript
+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),
+  },
+});
+```
+
+## Emergency Controls
+
+```typescript
+// Manually pause all sending
+antiban.pause();
+
+// Resume
+antiban.resume();
+
+// Nuclear reset (use after serving a ban period)
+antiban.reset();
+```
+
+## Best Practices
+
+1. **Always warm up new numbers** — Don't send 1000 messages on day 1
+2. **Use a real phone number** — Virtual/VOIP numbers get banned faster
+3. **Don't send identical messages** — Vary your content even slightly
+4. **Respect the health monitor** — When it says stop, STOP
+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
+
+## License
+
+MIT — Built by [WhatsAuction](https://whatsauction.co.za) 🇿🇦

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "baileys-antiban",
+  "version": "1.0.0",
+  "description": "Anti-ban middleware for Baileys — human-like messaging patterns to protect your WhatsApp number",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest"
+  },
+  "keywords": [
+    "baileys",
+    "whatsapp",
+    "anti-ban",
+    "rate-limit",
+    "middleware"
+  ],
+  "author": "Kobus Wentzel <kobie@pop.co.za>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kobie3717/baileys-antiban"
+  },
+  "peerDependencies": {
+    "baileys": ">=6.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/stress-test.ts

@@ -0,0 +1,199 @@
+/**
+ * Stress Test — Send 1000 messages as fast as safely possible
+ * 
+ * This pushes the anti-ban to its limits while keeping your number alive.
+ * Run: AUTH_DIR=<path> npx tsx stress-test.ts <group-jid>
+ */
+
+import makeWASocket, { useMultiFileAuthState, DisconnectReason } from 'baileys';
+import pino from 'pino';
+import { AntiBan } from './src/antiban.js';
+import { ContentVariator } from './src/contentVariator.js';
+
+const AUTH_DIR = process.env.AUTH_DIR || './test-auth';
+const GROUP_JID = process.argv[2];
+const TARGET = parseInt(process.argv[3] || '1000');
+
+if (!GROUP_JID) {
+  console.log('Usage: AUTH_DIR=<path> npx tsx stress-test.ts <group-jid> [count]');
+  process.exit(1);
+}
+
+// Aggressive but safe config
+const antiban = new AntiBan({
+  rateLimiter: {
+    maxPerMinute: 12,        // Push it — 12/min
+    maxPerHour: 500,          // 500/hr
+    maxPerDay: 2000,          // 2000/day
+    minDelayMs: 800,          // Fast but not instant
+    maxDelayMs: 3000,         // Cap delay at 3s
+    burstAllowance: 5,        // Allow 5 fast messages
+    maxIdenticalMessages: 50, // High — we use variator
+    newChatDelayMs: 500,      // Low — same group every time
+  },
+  warmUp: { warmUpDays: 0 },  // Skip warm-up for stress test
+  health: {
+    autoPauseAt: 'high',
+    onRiskChange: (status) => {
+      console.log(`\n⚠️  RISK: ${status.risk.toUpperCase()} (score: ${status.score}) — ${status.recommendation}\n`);
+    },
+  },
+  logging: false,
+});
+
+const variator = new ContentVariator({
+  zeroWidthChars: true,
+  punctuationVariation: true,
+  emojiPadding: false,
+  synonyms: false,
+});
+
+// Message templates
+const templates = [
+  '🛡️ Stress test #{n}/1000 — anti-ban holding strong',
+  '⚡ Message #{n} — speed run in progress',
+  '🧪 #{n} — pushing the limits safely',
+  '📊 #{n}/1000 — rate limiter active',
+  '🔥 #{n} — no ban, no problem',
+  '✅ #{n} sent — number still alive',
+  '🏎️ Fast message #{n} — jitter applied',
+  '💪 #{n}/1000 — endurance test',
+  '🎯 #{n} — precision timing',
+  '🌊 Wave #{n} — steady flow',
+  '⏱️ #{n} — clock is ticking',
+  '🚀 #{n}/1000 — full throttle safe mode',
+  '📈 #{n} — stats looking good',
+  '🔒 #{n} — protected by baileys-antiban',
+  '🏁 #{n} — race to 1000',
+];
+
+console.log('🏎️  baileys-antiban STRESS TEST');
+console.log('='.repeat(60));
+console.log(`Target: ${GROUP_JID}`);
+console.log(`Messages: ${TARGET}`);
+console.log(`Config: 12/min, 500/hr, 800-3000ms delay`);
+console.log(`Estimated time: ${Math.round(TARGET * 2 / 60)} - ${Math.round(TARGET * 4 / 60)} minutes`);
+console.log('='.repeat(60));
+
+async function main() {
+  const { state, saveCreds } = await useMultiFileAuthState(AUTH_DIR);
+  
+  const sock = makeWASocket({
+    auth: state,
+    printQRInTerminal: false,
+    logger: pino({ level: 'silent' }),
+  });
+  
+  sock.ev.on('creds.update', saveCreds);
+
+  // Monitor disconnects
+  sock.ev.on('connection.update', async (update) => {
+    if (update.connection === 'close') {
+      const reason = (update.lastDisconnect?.error as any)?.output?.statusCode;
+      antiban.onDisconnect(reason || 'unknown');
+      console.log(`\n❌ DISCONNECTED: ${DisconnectReason[reason] || reason}`);
+      
+      if (reason === 403) {
+        console.log('🔴 FORBIDDEN — WhatsApp is blocking us. Test stopped.');
+        process.exit(1);
+      }
+      if (reason === 401) {
+        console.log('🔴 LOGGED OUT — Possible ban. Test stopped.');
+        process.exit(1);
+      }
+    }
+  });
+
+  return new Promise<void>((resolve) => {
+    sock.ev.on('connection.update', async (update) => {
+      if (update.connection !== 'open') return;
+      
+      console.log('\n✅ Connected! Starting stress test...\n');
+      antiban.onReconnect();
+
+      let sent = 0;
+      let blocked = 0;
+      let errors = 0;
+      const startTime = Date.now();
+      const milestones = new Set([10, 50, 100, 250, 500, 750, 1000]);
+
+      for (let i = 1; i <= TARGET; i++) {
+        const template = templates[(i - 1) % templates.length];
+        const baseMsg = template.replace(/#{n}/g, String(i));
+        const message = variator.vary(baseMsg);
+
+        const decision = await antiban.beforeSend(GROUP_JID, message);
+
+        if (!decision.allowed) {
+          blocked++;
+          // Wait a bit and retry once
+          await new Promise(r => setTimeout(r, 5000));
+          const retry = await antiban.beforeSend(GROUP_JID, message);
+          if (!retry.allowed) {
+            if (i % 50 === 0) console.log(`⛔ ${i}: Still blocked — ${retry.reason}`);
+            continue;
+          }
+          await new Promise(r => setTimeout(r, retry.delayMs));
+        } else {
+          await new Promise(r => setTimeout(r, decision.delayMs));
+        }
+
+        try {
+          await sock.sendMessage(GROUP_JID, { text: message });
+          antiban.afterSend(GROUP_JID, message);
+          sent++;
+
+          // Progress indicator
+          if (sent % 10 === 0) {
+            const elapsed = ((Date.now() - startTime) / 1000).toFixed(0);
+            const rate = (sent / (parseInt(elapsed) || 1) * 60).toFixed(1);
+            const eta = Math.round((TARGET - sent) / (parseFloat(rate) / 60));
+            process.stdout.write(`\r📊 ${sent}/${TARGET} sent | ${blocked} blocked | ${rate}/min | ${elapsed}s elapsed | ETA: ${eta}s   `);
+          }
+
+          if (milestones.has(sent)) {
+            const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+            const stats = antiban.getStats();
+            console.log(`\n\n🏆 MILESTONE: ${sent} messages sent!`);
+            console.log(`   Time: ${elapsed}s | Health: ${stats.health.risk} (score: ${stats.health.score})`);
+            console.log(`   Rate: ${stats.rateLimiter.lastMinute}/min, ${stats.rateLimiter.lastHour}/hr`);
+            console.log(`   Avg delay: ${(stats.totalDelayMs / sent / 1000).toFixed(1)}s per message\n`);
+          }
+        } catch (err: any) {
+          errors++;
+          antiban.afterSendFailed(err.message);
+          if (errors > 10) {
+            console.log(`\n\n🔴 Too many errors (${errors}). Stopping.`);
+            break;
+          }
+        }
+      }
+
+      const totalTime = ((Date.now() - startTime) / 1000).toFixed(1);
+      const finalStats = antiban.getStats();
+
+      console.log(`\n\n${'='.repeat(60)}`);
+      console.log(`🏁 STRESS TEST COMPLETE`);
+      console.log(`${'='.repeat(60)}`);
+      console.log(`✅ Sent: ${sent}/${TARGET}`);
+      console.log(`⛔ Blocked: ${blocked}`);
+      console.log(`❌ Errors: ${errors}`);
+      console.log(`⏱️  Total time: ${totalTime}s (${(parseFloat(totalTime) / 60).toFixed(1)} min)`);
+      console.log(`📈 Average rate: ${(sent / parseFloat(totalTime) * 60).toFixed(1)} msgs/min`);
+      console.log(`⏳ Average delay: ${(finalStats.totalDelayMs / sent / 1000).toFixed(1)}s per message`);
+      console.log(`🏥 Final health: ${finalStats.health.risk} (score: ${finalStats.health.score})`);
+      console.log(`${sent === TARGET ? '🎉 ALL MESSAGES DELIVERED — NUMBER IS SAFE!' : '⚠️ Did not complete all messages'}`);
+      console.log(`${'='.repeat(60)}\n`);
+
+      setTimeout(() => {
+        sock.end(undefined);
+        resolve();
+      }, 2000);
+    });
+  });
+}
+
+main().then(() => process.exit(0)).catch(err => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});