baileys-antiban 4.8.0 → 4.9.0

package/dist/antiban.d.ts

@@ -21,6 +21,7 @@ import { ReplyRatioGuard, type ReplyRatioConfig, type ReplyRatioStats } from './
 import { ContactGraphWarmer, type ContactGraphConfig, type ContactGraphStats } from './contactGraph.js';
 import { PresenceChoreographer, type PresenceChoreographerConfig, type PresenceChoreographerStats } from './presenceChoreographer.js';
 import { RetryReasonTracker, type RetryTrackerConfig, type RetryStats } from './retryTracker.js';
+import { TopologyThrottler, type TopologyThrottlerConfig } from './topologyThrottler.js';
 import { PostReconnectThrottle, type ReconnectThrottleConfig, type ReconnectThrottleStats } from './reconnectThrottle.js';
 import { LidResolver, type LidResolverConfig, type LidResolverStats } from './lidResolver.js';
 import { JidCanonicalizer, type JidCanonicalizerConfig, type JidCanonicalizerStats } from './jidCanonicalizer.js';
@@ -41,6 +42,7 @@ export interface AntiBanConfigLegacy {
     presence?: Partial<PresenceChoreographerConfig>;
     retryTracker?: Partial<RetryTrackerConfig>;
     reconnectThrottle?: Partial<ReconnectThrottleConfig>;
+    topologyThrottler?: Partial<TopologyThrottlerConfig>;
     lidResolver?: LidResolverConfig;
     jidCanonicalizer?: JidCanonicalizerConfig;
     sessionStability?: {
@@ -72,6 +74,16 @@ export interface AntiBanStats {
     presence?: PresenceChoreographerStats;
     retryTracker?: RetryStats | null;
     reconnectThrottle?: ReconnectThrottleStats | null;
+    topologyThrottler?: {
+        newContactsThisHour: number;
+        newContactsToday: number;
+        replyRatio: number | null;
+        blockedRatio: number | null;
+        hotspots: Array<{
+            sourceGroup: string;
+            count: number;
+        }>;
+    } | null;
     lidResolver?: LidResolverStats | null;
     jidCanonicalizer?: JidCanonicalizerStats | null;
     sessionStability?: SessionHealthStats | null;
@@ -93,6 +105,7 @@ export declare class AntiBan {
     private presenceChoreographer;
     private retryTrackerModule;
     private reconnectThrottleModule;
+    private topologyThrottlerModule;
     private lidResolverModule;
     private jidCanonicalizerModule;
     private sessionStabilityMonitor;
@@ -160,6 +173,10 @@ export declare class AntiBan {
     get retryTracker(): RetryReasonTracker;
     /** Get the reconnect throttle for direct access */
     get reconnectThrottle(): PostReconnectThrottle;
+    /** Get the topology throttler for direct access */
+    get topologyThrottler(): TopologyThrottler | null;
+    /** Get the topology throttler for direct access (alias) */
+    get topology(): TopologyThrottler | null;
     /** Get the LID resolver for direct access */
     get lidResolver(): LidResolver | null;
     /** Get the JID canonicalizer for direct access */
@@ -186,6 +203,7 @@ export declare class AntiBan {
      * Reset everything (use after a ban period)
      */
     reset(): void;
+    private isGroupJid;
     private runAdaptiveCheck;
     private persistStateDebounced;
     private persistStateImmediate;

package/dist/antiban.js

@@ -21,6 +21,7 @@ import { ReplyRatioGuard } from './replyRatio.js';
 import { ContactGraphWarmer } from './contactGraph.js';
 import { PresenceChoreographer } from './presenceChoreographer.js';
 import { RetryReasonTracker } from './retryTracker.js';
+import { TopologyThrottler } from './topologyThrottler.js';
 import { PostReconnectThrottle } from './reconnectThrottle.js';
 import { LidResolver } from './lidResolver.js';
 import { JidCanonicalizer } from './jidCanonicalizer.js';
@@ -105,6 +106,7 @@ export class AntiBan {
     presenceChoreographer;
     retryTrackerModule;
     reconnectThrottleModule;
+    topologyThrottlerModule = null;
     lidResolverModule = null;
     jidCanonicalizerModule = null;
     sessionStabilityMonitor = null;
@@ -246,6 +248,13 @@ export class AntiBan {
             ...(legacyPassthrough?.reconnectThrottle || {}),
             baselineRatePerMinute: () => this.rateLimiter.getStats().limits.perMinute,
         });
+        // Initialize topology throttler if configured
+        if (legacyPassthrough?.topologyThrottler) {
+            this.topologyThrottlerModule = new TopologyThrottler(legacyPassthrough.topologyThrottler);
+            if (this.logging) {
+                console.log(`[baileys-antiban] 🌐 Topology throttler enabled — max ${legacyPassthrough.topologyThrottler.maxNewContactsPerHour || 5}/hr, ${legacyPassthrough.topologyThrottler.maxNewContactsPerDay || 20}/day new contacts`);
+            }
+        }
         // Initialize LID resolver and canonicalizer if configured
         // If jidCanonicalizer is enabled but no resolver provided, create standalone resolver
         if (legacyPassthrough?.jidCanonicalizer?.enabled) {
@@ -381,6 +390,46 @@ export class AntiBan {
                 health: healthStatus,
             };
         }
+        // Topology throttler check — only applies to DMs to new/unknown contacts
+        if (this.topologyThrottlerModule && !this.isGroupJid(recipient)) {
+            const knownChats = this.rateLimiter.getKnownChats();
+            const isNewContact = !knownChats.has(recipient);
+            if (isNewContact) {
+                // Check if we can send to new contact based on topology limits
+                const topologyDecision = this.topologyThrottlerModule.canSendToNewContact();
+                if (!topologyDecision.allowed) {
+                    this.stats.messagesBlocked++;
+                    if (this.logging) {
+                        console.log(`[baileys-antiban] 🌐 BLOCKED — topology: ${topologyDecision.reason}`);
+                    }
+                    return {
+                        allowed: false,
+                        delayMs: topologyDecision.retryAfterMs || 0,
+                        reason: `Topology: ${topologyDecision.reason}`,
+                        health: healthStatus,
+                    };
+                }
+                // Assess contact risk
+                const riskAssessment = this.topologyThrottlerModule.assessContact(recipient, {
+                    messageType: 'dm',
+                    hasReplied: false,
+                    knownGroups: [],
+                });
+                if (riskAssessment.recommendation === 'abort') {
+                    this.stats.messagesBlocked++;
+                    if (this.logging) {
+                        console.log(`[baileys-antiban] ⛔ BLOCKED — contact risk ${riskAssessment.risk} (score ${riskAssessment.score}): ${riskAssessment.reasons.join(', ')}`);
+                    }
+                    return {
+                        allowed: false,
+                        delayMs: 0,
+                        reason: `Contact risk too high: ${riskAssessment.reasons.join(', ')}`,
+                        health: healthStatus,
+                    };
+                }
+                // If delay recommended, we'll add it to the total delay later
+            }
+        }
         // Reply ratio check
         const replyRatioDecision = this.replyRatioGuard.beforeSend(recipient);
         if (!replyRatioDecision.allowed) {
@@ -482,6 +531,24 @@ export class AntiBan {
                 }
             }
         }
+        // Topology throttler recommended delay
+        if (this.topologyThrottlerModule && !this.isGroupJid(recipient)) {
+            const knownChats = this.rateLimiter.getKnownChats();
+            const isNewContact = !knownChats.has(recipient);
+            if (isNewContact) {
+                const riskAssessment = this.topologyThrottlerModule.assessContact(recipient, {
+                    messageType: 'dm',
+                    hasReplied: false,
+                    knownGroups: [],
+                });
+                if (riskAssessment.recommendation === 'delay' && riskAssessment.suggestedDelayMs) {
+                    delay += riskAssessment.suggestedDelayMs;
+                    if (this.logging) {
+                        console.log(`[baileys-antiban] ⚠️  Topology risk ${riskAssessment.risk} — adding ${Math.floor(riskAssessment.suggestedDelayMs / 60000)}min delay`);
+                    }
+                }
+            }
+        }
         // Roll for distraction pause
         const distractionCheck = this.presenceChoreographer.shouldPauseForDistraction();
         if (distractionCheck.pause) {
@@ -513,6 +580,7 @@ export class AntiBan {
         this.rateLimiter.record(recipient, content);
         this.warmUp.record();
         this.replyRatioGuard.recordSent(recipient);
+        this.topologyThrottlerModule?.recordSent(recipient);
         this.stats.messagesAllowed++;
         if (msgId) {
             this.deliveryTracker.onMessageSent(msgId);
@@ -552,6 +620,7 @@ export class AntiBan {
     onIncomingMessage(jid, msgText) {
         this.replyRatioGuard.recordReceived(jid);
         this.contactGraphWarmer.onIncomingMessage(jid);
+        this.topologyThrottlerModule?.recordReplied(jid);
         return this.replyRatioGuard.suggestReply(jid, msgText);
     }
     /**
@@ -595,6 +664,9 @@ export class AntiBan {
         if (this.reconnectThrottleModule['config']?.enabled) {
             stats.reconnectThrottle = this.reconnectThrottleModule.getStats();
         }
+        if (this.topologyThrottlerModule) {
+            stats.topologyThrottler = this.topologyThrottlerModule.getTopologyStats();
+        }
         if (this.lidResolverModule) {
             stats.lidResolver = this.lidResolverModule.getStats();
         }
@@ -640,6 +712,14 @@ export class AntiBan {
     get reconnectThrottle() {
         return this.reconnectThrottleModule;
     }
+    /** Get the topology throttler for direct access */
+    get topologyThrottler() {
+        return this.topologyThrottlerModule;
+    }
+    /** Get the topology throttler for direct access (alias) */
+    get topology() {
+        return this.topologyThrottlerModule;
+    }
     /** Get the LID resolver for direct access */
     get lidResolver() {
         return this.lidResolverModule;
@@ -701,6 +781,9 @@ export class AntiBan {
             console.log('[baileys-antiban] 🔄 Reset — starting fresh warm-up');
         }
     }
+    isGroupJid(jid) {
+        return jid.endsWith('@g.us') || jid.endsWith('@newsletter');
+    }
     runAdaptiveCheck() {
         const delivery = this.deliveryTracker.getStats();
         // Need min sample to be meaningful
@@ -763,6 +846,7 @@ export class AntiBan {
             rateLimiter: this.rateLimiter,
             timelockGuard: this.timelockGuard,
             messageRegistry: this.messageTypeRegistry || undefined,
+            topologyThrottler: this.topologyThrottlerModule || undefined,
             instanceId: this.resolvedConfig.instanceId,
         });
     }
@@ -777,6 +861,7 @@ export class AntiBan {
             rateLimiter: this.rateLimiter,
             timelockGuard: this.timelockGuard,
             messageRegistry: this.messageTypeRegistry || undefined,
+            topologyThrottler: this.topologyThrottlerModule || undefined,
         });
     }
     /**

package/dist/cjs/antiban.js

@@ -24,6 +24,7 @@ const replyRatio_js_1 = require("./replyRatio.js");
 const contactGraph_js_1 = require("./contactGraph.js");
 const presenceChoreographer_js_1 = require("./presenceChoreographer.js");
 const retryTracker_js_1 = require("./retryTracker.js");
+const topologyThrottler_js_1 = require("./topologyThrottler.js");
 const reconnectThrottle_js_1 = require("./reconnectThrottle.js");
 const lidResolver_js_1 = require("./lidResolver.js");
 const jidCanonicalizer_js_1 = require("./jidCanonicalizer.js");
@@ -108,6 +109,7 @@ class AntiBan {
     presenceChoreographer;
     retryTrackerModule;
     reconnectThrottleModule;
+    topologyThrottlerModule = null;
     lidResolverModule = null;
     jidCanonicalizerModule = null;
     sessionStabilityMonitor = null;
@@ -249,6 +251,13 @@ class AntiBan {
             ...(legacyPassthrough?.reconnectThrottle || {}),
             baselineRatePerMinute: () => this.rateLimiter.getStats().limits.perMinute,
         });
+        // Initialize topology throttler if configured
+        if (legacyPassthrough?.topologyThrottler) {
+            this.topologyThrottlerModule = new topologyThrottler_js_1.TopologyThrottler(legacyPassthrough.topologyThrottler);
+            if (this.logging) {
+                console.log(`[baileys-antiban] 🌐 Topology throttler enabled — max ${legacyPassthrough.topologyThrottler.maxNewContactsPerHour || 5}/hr, ${legacyPassthrough.topologyThrottler.maxNewContactsPerDay || 20}/day new contacts`);
+            }
+        }
         // Initialize LID resolver and canonicalizer if configured
         // If jidCanonicalizer is enabled but no resolver provided, create standalone resolver
         if (legacyPassthrough?.jidCanonicalizer?.enabled) {
@@ -384,6 +393,46 @@ class AntiBan {
                 health: healthStatus,
             };
         }
+        // Topology throttler check — only applies to DMs to new/unknown contacts
+        if (this.topologyThrottlerModule && !this.isGroupJid(recipient)) {
+            const knownChats = this.rateLimiter.getKnownChats();
+            const isNewContact = !knownChats.has(recipient);
+            if (isNewContact) {
+                // Check if we can send to new contact based on topology limits
+                const topologyDecision = this.topologyThrottlerModule.canSendToNewContact();
+                if (!topologyDecision.allowed) {
+                    this.stats.messagesBlocked++;
+                    if (this.logging) {
+                        console.log(`[baileys-antiban] 🌐 BLOCKED — topology: ${topologyDecision.reason}`);
+                    }
+                    return {
+                        allowed: false,
+                        delayMs: topologyDecision.retryAfterMs || 0,
+                        reason: `Topology: ${topologyDecision.reason}`,
+                        health: healthStatus,
+                    };
+                }
+                // Assess contact risk
+                const riskAssessment = this.topologyThrottlerModule.assessContact(recipient, {
+                    messageType: 'dm',
+                    hasReplied: false,
+                    knownGroups: [],
+                });
+                if (riskAssessment.recommendation === 'abort') {
+                    this.stats.messagesBlocked++;
+                    if (this.logging) {
+                        console.log(`[baileys-antiban] ⛔ BLOCKED — contact risk ${riskAssessment.risk} (score ${riskAssessment.score}): ${riskAssessment.reasons.join(', ')}`);
+                    }
+                    return {
+                        allowed: false,
+                        delayMs: 0,
+                        reason: `Contact risk too high: ${riskAssessment.reasons.join(', ')}`,
+                        health: healthStatus,
+                    };
+                }
+                // If delay recommended, we'll add it to the total delay later
+            }
+        }
         // Reply ratio check
         const replyRatioDecision = this.replyRatioGuard.beforeSend(recipient);
         if (!replyRatioDecision.allowed) {
@@ -485,6 +534,24 @@ class AntiBan {
                 }
             }
         }
+        // Topology throttler recommended delay
+        if (this.topologyThrottlerModule && !this.isGroupJid(recipient)) {
+            const knownChats = this.rateLimiter.getKnownChats();
+            const isNewContact = !knownChats.has(recipient);
+            if (isNewContact) {
+                const riskAssessment = this.topologyThrottlerModule.assessContact(recipient, {
+                    messageType: 'dm',
+                    hasReplied: false,
+                    knownGroups: [],
+                });
+                if (riskAssessment.recommendation === 'delay' && riskAssessment.suggestedDelayMs) {
+                    delay += riskAssessment.suggestedDelayMs;
+                    if (this.logging) {
+                        console.log(`[baileys-antiban] ⚠️  Topology risk ${riskAssessment.risk} — adding ${Math.floor(riskAssessment.suggestedDelayMs / 60000)}min delay`);
+                    }
+                }
+            }
+        }
         // Roll for distraction pause
         const distractionCheck = this.presenceChoreographer.shouldPauseForDistraction();
         if (distractionCheck.pause) {
@@ -516,6 +583,7 @@ class AntiBan {
         this.rateLimiter.record(recipient, content);
         this.warmUp.record();
         this.replyRatioGuard.recordSent(recipient);
+        this.topologyThrottlerModule?.recordSent(recipient);
         this.stats.messagesAllowed++;
         if (msgId) {
             this.deliveryTracker.onMessageSent(msgId);
@@ -555,6 +623,7 @@ class AntiBan {
     onIncomingMessage(jid, msgText) {
         this.replyRatioGuard.recordReceived(jid);
         this.contactGraphWarmer.onIncomingMessage(jid);
+        this.topologyThrottlerModule?.recordReplied(jid);
         return this.replyRatioGuard.suggestReply(jid, msgText);
     }
     /**
@@ -598,6 +667,9 @@ class AntiBan {
         if (this.reconnectThrottleModule['config']?.enabled) {
             stats.reconnectThrottle = this.reconnectThrottleModule.getStats();
         }
+        if (this.topologyThrottlerModule) {
+            stats.topologyThrottler = this.topologyThrottlerModule.getTopologyStats();
+        }
         if (this.lidResolverModule) {
             stats.lidResolver = this.lidResolverModule.getStats();
         }
@@ -643,6 +715,14 @@ class AntiBan {
     get reconnectThrottle() {
         return this.reconnectThrottleModule;
     }
+    /** Get the topology throttler for direct access */
+    get topologyThrottler() {
+        return this.topologyThrottlerModule;
+    }
+    /** Get the topology throttler for direct access (alias) */
+    get topology() {
+        return this.topologyThrottlerModule;
+    }
     /** Get the LID resolver for direct access */
     get lidResolver() {
         return this.lidResolverModule;
@@ -704,6 +784,9 @@ class AntiBan {
             console.log('[baileys-antiban] 🔄 Reset — starting fresh warm-up');
         }
     }
+    isGroupJid(jid) {
+        return jid.endsWith('@g.us') || jid.endsWith('@newsletter');
+    }
     runAdaptiveCheck() {
         const delivery = this.deliveryTracker.getStats();
         // Need min sample to be meaningful
@@ -766,6 +849,7 @@ class AntiBan {
             rateLimiter: this.rateLimiter,
             timelockGuard: this.timelockGuard,
             messageRegistry: this.messageTypeRegistry || undefined,
+            topologyThrottler: this.topologyThrottlerModule || undefined,
             instanceId: this.resolvedConfig.instanceId,
         });
     }
@@ -780,6 +864,7 @@ class AntiBan {
             rateLimiter: this.rateLimiter,
             timelockGuard: this.timelockGuard,
             messageRegistry: this.messageTypeRegistry || undefined,
+            topologyThrottler: this.topologyThrottlerModule || undefined,
         });
     }
     /**

package/dist/cjs/index.js

@@ -10,7 +10,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getRetryJitter = exports.getTypingJitter = exports.getMessageSendJitter = exports.applySessionFingerprint = exports.generateSessionFingerprint = exports.proxyRotator = exports.readReceiptVariance = exports.credsSnapshot = exports.applyFingerprint = exports.generateFingerprint = exports.messageRecovery = exports.applyGroupMultiplier = exports.shouldUseGroupProfile = exports.isBroadcast = exports.isNewsletter = exports.isGroup = exports.StateManager = exports.PRESETS = exports.resolveConfig = exports.FileStateAdapter = exports.Scheduler = exports.WebhookAlerts = exports.ContentVariator = exports.MessageQueue = exports.wrapSocketWithFingerprint = exports.wrapSocket = exports.getRetryReasonDescription = exports.isMacError = exports.parseRetryReason = exports.MAC_ERROR_CODES = exports.MessageRetryReason = exports.createLidFirstResolver = exports.LidFirstResolver = exports.DeafSessionDetector = exports.classifyDisconnect = exports.wrapWithSessionStability = exports.SessionHealthMonitor = exports.JidCanonicalizer = exports.LidResolver = exports.PostReconnectThrottle = exports.RetryReasonTracker = exports.getCircadianMultiplier = exports.PresenceChoreographer = exports.ContactGraphWarmer = exports.ReplyRatioGuard = exports.TimelockGuard = exports.HealthMonitor = exports.WarmUp = exports.RateLimiter = exports.AntiBan = void 0;
-exports.createPeriodicExporter = exports.createMetricsHandler = exports.exportPrometheusMetrics = exports.createConsoleLogger = exports.importAntibanState = exports.exportAntibanState = exports.MessageTypeRegistry = exports.createHumanEntropyService = exports.HumanEntropyService = exports.createInMemoryEventStoreBackend = exports.createMySQLEventStoreBackend = exports.createFleetEventStore = exports.createJidCircuitBreaker = exports.JidCircuitBreaker = exports.InstanceCoordinator = exports.DeliveryTracker = exports.BanRecoveryOrchestrator = exports.LegitimacySignalInjector = exports.GROUP_OP_ERRORS = exports.extractPrivacyBlock = exports.classifyGroupOpError = exports.GroupOperationGuard = exports.AbortError = exports.STEALTH_BROWSER_POOL = exports.rampPresenceAfterConnect = exports.getStealthSocketConfig = exports.createStealthFingerprint = exports.getBatteryState = exports.getVoiceNoteMetadata = void 0;
+exports.createPeriodicExporter = exports.createMetricsHandler = exports.exportPrometheusMetrics = exports.createConsoleLogger = exports.TopologyThrottler = exports.importAntibanState = exports.exportAntibanState = exports.MessageTypeRegistry = exports.createHumanEntropyService = exports.HumanEntropyService = exports.createInMemoryEventStoreBackend = exports.createMySQLEventStoreBackend = exports.createFleetEventStore = exports.createJidCircuitBreaker = exports.JidCircuitBreaker = exports.InstanceCoordinator = exports.DeliveryTracker = exports.BanRecoveryOrchestrator = exports.LegitimacySignalInjector = exports.GROUP_OP_ERRORS = exports.extractPrivacyBlock = exports.classifyGroupOpError = exports.GroupOperationGuard = exports.AbortError = exports.STEALTH_BROWSER_POOL = exports.rampPresenceAfterConnect = exports.getStealthSocketConfig = exports.createStealthFingerprint = exports.getBatteryState = exports.getVoiceNoteMetadata = void 0;
 // Core
 var antiban_js_1 = require("./antiban.js");
 Object.defineProperty(exports, "AntiBan", { enumerable: true, get: function () { return antiban_js_1.AntiBan; } });
@@ -149,6 +149,8 @@ Object.defineProperty(exports, "MessageTypeRegistry", { enumerable: true, get: f
 var stateExport_js_1 = require("./stateExport.js");
 Object.defineProperty(exports, "exportAntibanState", { enumerable: true, get: function () { return stateExport_js_1.exportAntibanState; } });
 Object.defineProperty(exports, "importAntibanState", { enumerable: true, get: function () { return stateExport_js_1.importAntibanState; } });
+var topologyThrottler_js_1 = require("./topologyThrottler.js");
+Object.defineProperty(exports, "TopologyThrottler", { enumerable: true, get: function () { return topologyThrottler_js_1.TopologyThrottler; } });
 // Observability
 var observability_js_1 = require("./observability.js");
 Object.defineProperty(exports, "createConsoleLogger", { enumerable: true, get: function () { return observability_js_1.createConsoleLogger; } });

package/dist/cjs/stateExport.js

@@ -71,6 +71,10 @@ function exportAntibanState(modules) {
     if (modules.messageRegistry) {
         snapshot.messageRegistry = modules.messageRegistry.exportState();
     }
+    // Export topology throttler state
+    if (modules.topologyThrottler) {
+        snapshot.topologyThrottler = modules.topologyThrottler.exportState();
+    }
     // Export engagement scores
     if (modules.engagementScores) {
         snapshot.engagementScores = Object.fromEntries(modules.engagementScores.entries());
@@ -144,6 +148,10 @@ function importAntibanState(snapshot, modules) {
     if (snapshot.messageRegistry && modules.messageRegistry) {
         modules.messageRegistry.importState(snapshot.messageRegistry);
     }
+    // Import topology throttler state
+    if (snapshot.topologyThrottler && modules.topologyThrottler) {
+        modules.topologyThrottler.importState(snapshot.topologyThrottler);
+    }
     // Import engagement scores
     if (snapshot.engagementScores && modules.engagementScores) {
         for (const [jid, score] of Object.entries(snapshot.engagementScores)) {

package/dist/cjs/topologyThrottler.js

@@ -0,0 +1,343 @@
+"use strict";
+/**
+ * Topology Throttler — Network topology-based anti-ban enforcement
+ *
+ * WhatsApp bans based on NETWORK TOPOLOGY, not just message timing:
+ * - How fast you expand your contact graph
+ * - Cold-contact ratio (strangers vs known contacts)
+ * - Reply reciprocity
+ * - Group-source clustering (mass-DMing group members)
+ *
+ * This module enforces graph expansion limits and scores contact risk
+ * before each send, acting as the primary enforcement layer for high-risk
+ * cold outreach.
+ *
+ * Key insight: A 30% reply rate is the minimum to unlock more cold sends.
+ * Below that, WhatsApp's ML models flag you as a spammer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TopologyThrottler = void 0;
+const TIME_CONSTANTS = {
+    MS_PER_HOUR: 3600000,
+    MS_PER_DAY: 86400000,
+    MS_PER_24H: 86400000,
+    REPLY_WINDOW_DAYS: 7,
+};
+const DEFAULT_CONFIG = {
+    maxNewContactsPerHour: 5,
+    maxNewContactsPerDay: 20,
+    minReplyRatioForNewContacts: 0.3,
+    maxSameGroupContacts: 10,
+    maxContactsFromSameSource: 8,
+    blockOnLimitReached: true,
+    cooldownMs: TIME_CONSTANTS.MS_PER_HOUR,
+    riskConfig: {
+        firstContactPenalty: 40,
+        noReplyPenalty: 20,
+        noMutualGroupsPenalty: 15,
+        recentContactBonus: -20,
+        repliedBeforeBonus: -30,
+        delayThreshold: 40,
+        abortThreshold: 75,
+    },
+};
+const DEFAULT_RISK_CONFIG = {
+    firstContactPenalty: 40,
+    noReplyPenalty: 20,
+    noMutualGroupsPenalty: 15,
+    recentContactBonus: -20,
+    repliedBeforeBonus: -30,
+    delayThreshold: 40,
+    abortThreshold: 75,
+};
+class TopologyThrottler {
+    config;
+    riskConfig;
+    contacts = new Map();
+    limits;
+    sourceGroupCounts = new Map();
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.riskConfig = { ...DEFAULT_RISK_CONFIG, ...this.config.riskConfig };
+        this.limits = {
+            newContactsThisHour: 0,
+            newContactsToday: 0,
+            lastHourResetAt: Date.now(),
+            lastDayResetAt: Date.now(),
+        };
+    }
+    /**
+     * Assess contact risk before sending.
+     * This is the main check — call before every send to a new/unknown contact.
+     */
+    assessContact(jid, context) {
+        this.resetLimitsIfNeeded();
+        const record = this.contacts.get(jid);
+        const now = Date.now();
+        let score = 0;
+        const reasons = [];
+        // First contact penalty
+        if (!record) {
+            score += this.riskConfig.firstContactPenalty;
+            reasons.push('first_contact');
+        }
+        else {
+            // Has record — check reply history
+            if (record.replyTimestamps.length === 0 && record.sendTimestamps.length > 0) {
+                score += this.riskConfig.noReplyPenalty;
+                reasons.push('no_reply_history');
+            }
+        }
+        // No mutual groups penalty
+        if (!context.knownGroups || context.knownGroups.length === 0) {
+            score += this.riskConfig.noMutualGroupsPenalty;
+            reasons.push('no_mutual_groups');
+        }
+        // Recent contact bonus
+        if (context.lastContactAt && (now - context.lastContactAt) < TIME_CONSTANTS.MS_PER_24H) {
+            score += this.riskConfig.recentContactBonus;
+            reasons.push('recent_contact');
+        }
+        // Replied before bonus
+        if (context.hasReplied || (record && record.replyTimestamps.length > 0)) {
+            score += this.riskConfig.repliedBeforeBonus;
+            reasons.push('has_replied');
+        }
+        // Clamp score to 0-100
+        score = Math.max(0, Math.min(100, score));
+        // Determine risk level
+        let risk;
+        let recommendation;
+        let suggestedDelayMs;
+        if (score >= this.riskConfig.abortThreshold) {
+            risk = 'CRITICAL';
+            recommendation = 'abort';
+            reasons.push('risk_too_high');
+        }
+        else if (score >= this.riskConfig.delayThreshold) {
+            risk = score >= 60 ? 'HIGH' : 'MEDIUM';
+            recommendation = 'delay';
+            // Exponential delay based on score
+            const delayMinutes = Math.floor((score - this.riskConfig.delayThreshold) / 10);
+            suggestedDelayMs = delayMinutes * 60000;
+            reasons.push('recommend_delay');
+        }
+        else {
+            risk = score >= 30 ? 'MEDIUM' : 'LOW';
+            recommendation = 'send';
+        }
+        return {
+            jid,
+            risk,
+            score,
+            reasons,
+            recommendation,
+            suggestedDelayMs,
+        };
+    }
+    /**
+     * Record a sent message to this contact.
+     */
+    recordSent(jid, sourceGroup) {
+        this.resetLimitsIfNeeded();
+        const now = Date.now();
+        let record = this.contacts.get(jid);
+        if (!record) {
+            // New contact — increment limits
+            record = {
+                firstContactAt: now,
+                sendTimestamps: [],
+                replyTimestamps: [],
+                blocked: false,
+                sourceGroup,
+            };
+            this.contacts.set(jid, record);
+            this.limits.newContactsThisHour++;
+            this.limits.newContactsToday++;
+            // Track source group
+            if (sourceGroup) {
+                const count = this.sourceGroupCounts.get(sourceGroup) || 0;
+                this.sourceGroupCounts.set(sourceGroup, count + 1);
+            }
+        }
+        // Add send timestamp (keep sliding window)
+        record.sendTimestamps.push(now);
+        this.cleanupTimestamps(record.sendTimestamps, TIME_CONSTANTS.REPLY_WINDOW_DAYS * TIME_CONSTANTS.MS_PER_DAY);
+    }
+    /**
+     * Record a reply from this contact.
+     */
+    recordReplied(jid) {
+        const record = this.contacts.get(jid);
+        if (!record)
+            return;
+        const now = Date.now();
+        record.replyTimestamps.push(now);
+        this.cleanupTimestamps(record.replyTimestamps, TIME_CONSTANTS.REPLY_WINDOW_DAYS * TIME_CONSTANTS.MS_PER_DAY);
+    }
+    /**
+     * Record that this contact blocked you.
+     */
+    recordBlocked(jid) {
+        const record = this.contacts.get(jid);
+        if (!record)
+            return;
+        record.blocked = true;
+    }
+    /**
+     * Check if topology limits allow sending to a new contact.
+     * Returns whether allowed and reason/retry time if blocked.
+     */
+    canSendToNewContact() {
+        this.resetLimitsIfNeeded();
+        const now = Date.now();
+        // Check cooldown
+        if (this.limits.limitHitAt) {
+            const cooldownEndsAt = this.limits.limitHitAt + this.config.cooldownMs;
+            if (now < cooldownEndsAt) {
+                const retryAfterMs = cooldownEndsAt - now;
+                return {
+                    allowed: false,
+                    reason: `Cooldown active — limit hit recently`,
+                    retryAfterMs,
+                };
+            }
+            else {
+                // Cooldown expired
+                delete this.limits.limitHitAt;
+            }
+        }
+        // Check hourly limit
+        if (this.limits.newContactsThisHour >= this.config.maxNewContactsPerHour) {
+            this.limits.limitHitAt = now;
+            const retryAfterMs = (this.limits.lastHourResetAt + TIME_CONSTANTS.MS_PER_HOUR) - now;
+            return {
+                allowed: false,
+                reason: `Hourly new contact limit reached (${this.config.maxNewContactsPerHour})`,
+                retryAfterMs: Math.max(0, retryAfterMs),
+            };
+        }
+        // Check daily limit
+        if (this.limits.newContactsToday >= this.config.maxNewContactsPerDay) {
+            this.limits.limitHitAt = now;
+            const retryAfterMs = (this.limits.lastDayResetAt + TIME_CONSTANTS.MS_PER_DAY) - now;
+            return {
+                allowed: false,
+                reason: `Daily new contact limit reached (${this.config.maxNewContactsPerDay})`,
+                retryAfterMs: Math.max(0, retryAfterMs),
+            };
+        }
+        // Check reply ratio requirement
+        const replyRatio = this.calculateReplyRatio();
+        if (replyRatio !== null && replyRatio < this.config.minReplyRatioForNewContacts) {
+            // Poor reply ratio — need to improve engagement before more cold sends
+            return {
+                allowed: false,
+                reason: `Reply ratio too low (${Math.round(replyRatio * 100)}% < ${Math.round(this.config.minReplyRatioForNewContacts * 100)}%)`,
+                retryAfterMs: TIME_CONSTANTS.MS_PER_HOUR, // arbitrary — user needs to improve engagement
+            };
+        }
+        return { allowed: true };
+    }
+    /**
+     * Get topology statistics.
+     */
+    getTopologyStats() {
+        this.resetLimitsIfNeeded();
+        const replyRatio = this.calculateReplyRatio();
+        const blockedRatio = this.calculateBlockedRatio();
+        // Get top 5 source group hotspots
+        const hotspots = Array.from(this.sourceGroupCounts.entries())
+            .map(([sourceGroup, count]) => ({ sourceGroup, count }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, 5);
+        return {
+            newContactsThisHour: this.limits.newContactsThisHour,
+            newContactsToday: this.limits.newContactsToday,
+            replyRatio,
+            blockedRatio,
+            hotspots,
+        };
+    }
+    /**
+     * Export state for persistence.
+     */
+    exportState() {
+        return {
+            contacts: Array.from(this.contacts.entries()),
+            limits: { ...this.limits },
+            sourceGroupCounts: Array.from(this.sourceGroupCounts.entries()),
+        };
+    }
+    /**
+     * Import state from persistence.
+     */
+    importState(state) {
+        if (state.contacts) {
+            this.contacts = new Map(state.contacts);
+        }
+        if (state.limits) {
+            this.limits = { ...state.limits };
+        }
+        if (state.sourceGroupCounts) {
+            this.sourceGroupCounts = new Map(state.sourceGroupCounts);
+        }
+    }
+    // Private helpers
+    resetLimitsIfNeeded() {
+        const now = Date.now();
+        // Reset hourly counter
+        if (now - this.limits.lastHourResetAt >= TIME_CONSTANTS.MS_PER_HOUR) {
+            this.limits.newContactsThisHour = 0;
+            this.limits.lastHourResetAt = now;
+        }
+        // Reset daily counter
+        if (now - this.limits.lastDayResetAt >= TIME_CONSTANTS.MS_PER_DAY) {
+            this.limits.newContactsToday = 0;
+            this.limits.lastDayResetAt = now;
+            // Clear source group counts daily
+            this.sourceGroupCounts.clear();
+        }
+    }
+    calculateReplyRatio() {
+        const now = Date.now();
+        const windowMs = TIME_CONSTANTS.REPLY_WINDOW_DAYS * TIME_CONSTANTS.MS_PER_DAY;
+        let totalSent = 0;
+        let totalReplies = 0;
+        for (const record of this.contacts.values()) {
+            // Count sends in window
+            const recentSends = record.sendTimestamps.filter(t => now - t < windowMs);
+            totalSent += recentSends.length;
+            // Count replies in window
+            const recentReplies = record.replyTimestamps.filter(t => now - t < windowMs);
+            totalReplies += recentReplies.length;
+        }
+        if (totalSent === 0)
+            return null; // No data yet
+        return totalReplies / totalSent;
+    }
+    calculateBlockedRatio() {
+        const totalContacts = this.contacts.size;
+        if (totalContacts === 0)
+            return null;
+        let blockedCount = 0;
+        for (const record of this.contacts.values()) {
+            if (record.blocked)
+                blockedCount++;
+        }
+        return blockedCount / totalContacts;
+    }
+    cleanupTimestamps(timestamps, maxAgeMs) {
+        const now = Date.now();
+        const cutoff = now - maxAgeMs;
+        // Remove old timestamps (in-place filter)
+        let writeIdx = 0;
+        for (let readIdx = 0; readIdx < timestamps.length; readIdx++) {
+            if (timestamps[readIdx] >= cutoff) {
+                timestamps[writeIdx++] = timestamps[readIdx];
+            }
+        }
+        timestamps.length = writeIdx;
+    }
+}
+exports.TopologyThrottler = TopologyThrottler;

package/dist/index.d.ts

@@ -48,4 +48,5 @@ export { createFleetEventStore, createMySQLEventStoreBackend, createInMemoryEven
 export { HumanEntropyService, createHumanEntropyService, type HumanEntropyConfig, type HumanEntropyStats } from './humanEntropy.js';
 export { MessageTypeRegistry, type MessageTypeDefinition, type MessageProvenance, type MessageTypeStats, type MessageTypeWarning, type MessageTypeRegistryState } from './messageTypeRegistry.js';
 export { exportAntibanState, importAntibanState, type AntibanSnapshot, type RateLimiterState, type TimelockGuardState, type CircuitState as CircuitStateExport, type DisconnectEvent } from './stateExport.js';
+export { TopologyThrottler, type TopologyThrottlerConfig, type ContactRisk, type ContactRiskAssessment, type ContactRiskConfig, type TopologyThrottlerState } from './topologyThrottler.js';
 export { createConsoleLogger, exportPrometheusMetrics, createMetricsHandler, createPeriodicExporter, type AntiBanLogger, type PeriodicExporterConfig, type PeriodicExporterHandle, } from './observability.js';

package/dist/index.js

@@ -70,5 +70,6 @@ export { HumanEntropyService, createHumanEntropyService } from './humanEntropy.j
 // v4.8 new modules
 export { MessageTypeRegistry } from './messageTypeRegistry.js';
 export { exportAntibanState, importAntibanState } from './stateExport.js';
+export { TopologyThrottler } from './topologyThrottler.js';
 // Observability
 export { createConsoleLogger, exportPrometheusMetrics, createMetricsHandler, createPeriodicExporter, } from './observability.js';

package/dist/stateExport.d.ts

@@ -12,6 +12,7 @@
  */
 import type { WarmUpState } from './warmup.js';
 import type { MessageTypeRegistryState } from './messageTypeRegistry.js';
+import type { TopologyThrottlerState } from './topologyThrottler.js';
 export interface DisconnectEvent {
     type: 'disconnect' | 'forbidden' | 'loggedOut' | 'messageFailed' | 'reconnect' | 'reachoutTimelocked';
     timestamp: number;
@@ -75,6 +76,8 @@ export interface AntibanSnapshot {
     timelockGuard?: TimelockGuardState;
     /** Message type registry state */
     messageRegistry?: MessageTypeRegistryState;
+    /** Topology throttler state */
+    topologyThrottler?: TopologyThrottlerState;
     /** Per-JID engagement scores */
     engagementScores?: Record<string, number>;
 }
@@ -113,6 +116,9 @@ export declare function exportAntibanState(modules: {
     messageRegistry?: {
         exportState: () => MessageTypeRegistryState;
     };
+    topologyThrottler?: {
+        exportState: () => TopologyThrottlerState;
+    };
     engagementScores?: Map<string, number>;
     instanceId?: string;
 }): AntibanSnapshot;
@@ -141,5 +147,8 @@ export declare function importAntibanState(snapshot: AntibanSnapshot, modules: {
     messageRegistry?: {
         importState: (state: MessageTypeRegistryState) => void;
     };
+    topologyThrottler?: {
+        importState: (state: TopologyThrottlerState) => void;
+    };
     engagementScores?: Map<string, number>;
 }): void;

package/dist/stateExport.js

@@ -67,6 +67,10 @@ export function exportAntibanState(modules) {
     if (modules.messageRegistry) {
         snapshot.messageRegistry = modules.messageRegistry.exportState();
     }
+    // Export topology throttler state
+    if (modules.topologyThrottler) {
+        snapshot.topologyThrottler = modules.topologyThrottler.exportState();
+    }
     // Export engagement scores
     if (modules.engagementScores) {
         snapshot.engagementScores = Object.fromEntries(modules.engagementScores.entries());
@@ -140,6 +144,10 @@ export function importAntibanState(snapshot, modules) {
     if (snapshot.messageRegistry && modules.messageRegistry) {
         modules.messageRegistry.importState(snapshot.messageRegistry);
     }
+    // Import topology throttler state
+    if (snapshot.topologyThrottler && modules.topologyThrottler) {
+        modules.topologyThrottler.importState(snapshot.topologyThrottler);
+    }
     // Import engagement scores
     if (snapshot.engagementScores && modules.engagementScores) {
         for (const [jid, score] of Object.entries(snapshot.engagementScores)) {

package/dist/topologyThrottler.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Topology Throttler — Network topology-based anti-ban enforcement
+ *
+ * WhatsApp bans based on NETWORK TOPOLOGY, not just message timing:
+ * - How fast you expand your contact graph
+ * - Cold-contact ratio (strangers vs known contacts)
+ * - Reply reciprocity
+ * - Group-source clustering (mass-DMing group members)
+ *
+ * This module enforces graph expansion limits and scores contact risk
+ * before each send, acting as the primary enforcement layer for high-risk
+ * cold outreach.
+ *
+ * Key insight: A 30% reply rate is the minimum to unlock more cold sends.
+ * Below that, WhatsApp's ML models flag you as a spammer.
+ */
+export type ContactRisk = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+export interface ContactRiskAssessment {
+    jid: string;
+    risk: ContactRisk;
+    score: number;
+    reasons: string[];
+    recommendation: 'send' | 'delay' | 'abort';
+    suggestedDelayMs?: number;
+}
+export interface ContactRiskConfig {
+    firstContactPenalty?: number;
+    noReplyPenalty?: number;
+    noMutualGroupsPenalty?: number;
+    recentContactBonus?: number;
+    repliedBeforeBonus?: number;
+    delayThreshold?: number;
+    abortThreshold?: number;
+}
+export interface TopologyThrottlerConfig {
+    maxNewContactsPerHour?: number;
+    maxNewContactsPerDay?: number;
+    minReplyRatioForNewContacts?: number;
+    maxSameGroupContacts?: number;
+    maxContactsFromSameSource?: number;
+    blockOnLimitReached?: boolean;
+    cooldownMs?: number;
+    riskConfig?: ContactRiskConfig;
+}
+interface ContactRecord {
+    firstContactAt: number;
+    sendTimestamps: number[];
+    replyTimestamps: number[];
+    blocked: boolean;
+    sourceGroup?: string;
+}
+interface TopologyLimits {
+    newContactsThisHour: number;
+    newContactsToday: number;
+    lastHourResetAt: number;
+    lastDayResetAt: number;
+    limitHitAt?: number;
+}
+export interface TopologyThrottlerState {
+    contacts: Array<[string, ContactRecord]>;
+    limits: TopologyLimits;
+    sourceGroupCounts: Array<[string, number]>;
+}
+export declare class TopologyThrottler {
+    private config;
+    private riskConfig;
+    private contacts;
+    private limits;
+    private sourceGroupCounts;
+    constructor(config?: TopologyThrottlerConfig);
+    /**
+     * Assess contact risk before sending.
+     * This is the main check — call before every send to a new/unknown contact.
+     */
+    assessContact(jid: string, context: {
+        messageType?: 'dm' | 'group' | 'broadcast';
+        sourceGroup?: string;
+        knownGroups?: string[];
+        hasReplied?: boolean;
+        lastContactAt?: number;
+        lastReplyAt?: number;
+    }): ContactRiskAssessment;
+    /**
+     * Record a sent message to this contact.
+     */
+    recordSent(jid: string, sourceGroup?: string): void;
+    /**
+     * Record a reply from this contact.
+     */
+    recordReplied(jid: string): void;
+    /**
+     * Record that this contact blocked you.
+     */
+    recordBlocked(jid: string): void;
+    /**
+     * Check if topology limits allow sending to a new contact.
+     * Returns whether allowed and reason/retry time if blocked.
+     */
+    canSendToNewContact(): {
+        allowed: boolean;
+        reason?: string;
+        retryAfterMs?: number;
+    };
+    /**
+     * Get topology statistics.
+     */
+    getTopologyStats(): {
+        newContactsThisHour: number;
+        newContactsToday: number;
+        replyRatio: number | null;
+        blockedRatio: number | null;
+        hotspots: Array<{
+            sourceGroup: string;
+            count: number;
+        }>;
+    };
+    /**
+     * Export state for persistence.
+     */
+    exportState(): TopologyThrottlerState;
+    /**
+     * Import state from persistence.
+     */
+    importState(state: TopologyThrottlerState): void;
+    private resetLimitsIfNeeded;
+    private calculateReplyRatio;
+    private calculateBlockedRatio;
+    private cleanupTimestamps;
+}
+export {};

package/dist/topologyThrottler.js

@@ -0,0 +1,339 @@
+/**
+ * Topology Throttler — Network topology-based anti-ban enforcement
+ *
+ * WhatsApp bans based on NETWORK TOPOLOGY, not just message timing:
+ * - How fast you expand your contact graph
+ * - Cold-contact ratio (strangers vs known contacts)
+ * - Reply reciprocity
+ * - Group-source clustering (mass-DMing group members)
+ *
+ * This module enforces graph expansion limits and scores contact risk
+ * before each send, acting as the primary enforcement layer for high-risk
+ * cold outreach.
+ *
+ * Key insight: A 30% reply rate is the minimum to unlock more cold sends.
+ * Below that, WhatsApp's ML models flag you as a spammer.
+ */
+const TIME_CONSTANTS = {
+    MS_PER_HOUR: 3600000,
+    MS_PER_DAY: 86400000,
+    MS_PER_24H: 86400000,
+    REPLY_WINDOW_DAYS: 7,
+};
+const DEFAULT_CONFIG = {
+    maxNewContactsPerHour: 5,
+    maxNewContactsPerDay: 20,
+    minReplyRatioForNewContacts: 0.3,
+    maxSameGroupContacts: 10,
+    maxContactsFromSameSource: 8,
+    blockOnLimitReached: true,
+    cooldownMs: TIME_CONSTANTS.MS_PER_HOUR,
+    riskConfig: {
+        firstContactPenalty: 40,
+        noReplyPenalty: 20,
+        noMutualGroupsPenalty: 15,
+        recentContactBonus: -20,
+        repliedBeforeBonus: -30,
+        delayThreshold: 40,
+        abortThreshold: 75,
+    },
+};
+const DEFAULT_RISK_CONFIG = {
+    firstContactPenalty: 40,
+    noReplyPenalty: 20,
+    noMutualGroupsPenalty: 15,
+    recentContactBonus: -20,
+    repliedBeforeBonus: -30,
+    delayThreshold: 40,
+    abortThreshold: 75,
+};
+export class TopologyThrottler {
+    config;
+    riskConfig;
+    contacts = new Map();
+    limits;
+    sourceGroupCounts = new Map();
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.riskConfig = { ...DEFAULT_RISK_CONFIG, ...this.config.riskConfig };
+        this.limits = {
+            newContactsThisHour: 0,
+            newContactsToday: 0,
+            lastHourResetAt: Date.now(),
+            lastDayResetAt: Date.now(),
+        };
+    }
+    /**
+     * Assess contact risk before sending.
+     * This is the main check — call before every send to a new/unknown contact.
+     */
+    assessContact(jid, context) {
+        this.resetLimitsIfNeeded();
+        const record = this.contacts.get(jid);
+        const now = Date.now();
+        let score = 0;
+        const reasons = [];
+        // First contact penalty
+        if (!record) {
+            score += this.riskConfig.firstContactPenalty;
+            reasons.push('first_contact');
+        }
+        else {
+            // Has record — check reply history
+            if (record.replyTimestamps.length === 0 && record.sendTimestamps.length > 0) {
+                score += this.riskConfig.noReplyPenalty;
+                reasons.push('no_reply_history');
+            }
+        }
+        // No mutual groups penalty
+        if (!context.knownGroups || context.knownGroups.length === 0) {
+            score += this.riskConfig.noMutualGroupsPenalty;
+            reasons.push('no_mutual_groups');
+        }
+        // Recent contact bonus
+        if (context.lastContactAt && (now - context.lastContactAt) < TIME_CONSTANTS.MS_PER_24H) {
+            score += this.riskConfig.recentContactBonus;
+            reasons.push('recent_contact');
+        }
+        // Replied before bonus
+        if (context.hasReplied || (record && record.replyTimestamps.length > 0)) {
+            score += this.riskConfig.repliedBeforeBonus;
+            reasons.push('has_replied');
+        }
+        // Clamp score to 0-100
+        score = Math.max(0, Math.min(100, score));
+        // Determine risk level
+        let risk;
+        let recommendation;
+        let suggestedDelayMs;
+        if (score >= this.riskConfig.abortThreshold) {
+            risk = 'CRITICAL';
+            recommendation = 'abort';
+            reasons.push('risk_too_high');
+        }
+        else if (score >= this.riskConfig.delayThreshold) {
+            risk = score >= 60 ? 'HIGH' : 'MEDIUM';
+            recommendation = 'delay';
+            // Exponential delay based on score
+            const delayMinutes = Math.floor((score - this.riskConfig.delayThreshold) / 10);
+            suggestedDelayMs = delayMinutes * 60000;
+            reasons.push('recommend_delay');
+        }
+        else {
+            risk = score >= 30 ? 'MEDIUM' : 'LOW';
+            recommendation = 'send';
+        }
+        return {
+            jid,
+            risk,
+            score,
+            reasons,
+            recommendation,
+            suggestedDelayMs,
+        };
+    }
+    /**
+     * Record a sent message to this contact.
+     */
+    recordSent(jid, sourceGroup) {
+        this.resetLimitsIfNeeded();
+        const now = Date.now();
+        let record = this.contacts.get(jid);
+        if (!record) {
+            // New contact — increment limits
+            record = {
+                firstContactAt: now,
+                sendTimestamps: [],
+                replyTimestamps: [],
+                blocked: false,
+                sourceGroup,
+            };
+            this.contacts.set(jid, record);
+            this.limits.newContactsThisHour++;
+            this.limits.newContactsToday++;
+            // Track source group
+            if (sourceGroup) {
+                const count = this.sourceGroupCounts.get(sourceGroup) || 0;
+                this.sourceGroupCounts.set(sourceGroup, count + 1);
+            }
+        }
+        // Add send timestamp (keep sliding window)
+        record.sendTimestamps.push(now);
+        this.cleanupTimestamps(record.sendTimestamps, TIME_CONSTANTS.REPLY_WINDOW_DAYS * TIME_CONSTANTS.MS_PER_DAY);
+    }
+    /**
+     * Record a reply from this contact.
+     */
+    recordReplied(jid) {
+        const record = this.contacts.get(jid);
+        if (!record)
+            return;
+        const now = Date.now();
+        record.replyTimestamps.push(now);
+        this.cleanupTimestamps(record.replyTimestamps, TIME_CONSTANTS.REPLY_WINDOW_DAYS * TIME_CONSTANTS.MS_PER_DAY);
+    }
+    /**
+     * Record that this contact blocked you.
+     */
+    recordBlocked(jid) {
+        const record = this.contacts.get(jid);
+        if (!record)
+            return;
+        record.blocked = true;
+    }
+    /**
+     * Check if topology limits allow sending to a new contact.
+     * Returns whether allowed and reason/retry time if blocked.
+     */
+    canSendToNewContact() {
+        this.resetLimitsIfNeeded();
+        const now = Date.now();
+        // Check cooldown
+        if (this.limits.limitHitAt) {
+            const cooldownEndsAt = this.limits.limitHitAt + this.config.cooldownMs;
+            if (now < cooldownEndsAt) {
+                const retryAfterMs = cooldownEndsAt - now;
+                return {
+                    allowed: false,
+                    reason: `Cooldown active — limit hit recently`,
+                    retryAfterMs,
+                };
+            }
+            else {
+                // Cooldown expired
+                delete this.limits.limitHitAt;
+            }
+        }
+        // Check hourly limit
+        if (this.limits.newContactsThisHour >= this.config.maxNewContactsPerHour) {
+            this.limits.limitHitAt = now;
+            const retryAfterMs = (this.limits.lastHourResetAt + TIME_CONSTANTS.MS_PER_HOUR) - now;
+            return {
+                allowed: false,
+                reason: `Hourly new contact limit reached (${this.config.maxNewContactsPerHour})`,
+                retryAfterMs: Math.max(0, retryAfterMs),
+            };
+        }
+        // Check daily limit
+        if (this.limits.newContactsToday >= this.config.maxNewContactsPerDay) {
+            this.limits.limitHitAt = now;
+            const retryAfterMs = (this.limits.lastDayResetAt + TIME_CONSTANTS.MS_PER_DAY) - now;
+            return {
+                allowed: false,
+                reason: `Daily new contact limit reached (${this.config.maxNewContactsPerDay})`,
+                retryAfterMs: Math.max(0, retryAfterMs),
+            };
+        }
+        // Check reply ratio requirement
+        const replyRatio = this.calculateReplyRatio();
+        if (replyRatio !== null && replyRatio < this.config.minReplyRatioForNewContacts) {
+            // Poor reply ratio — need to improve engagement before more cold sends
+            return {
+                allowed: false,
+                reason: `Reply ratio too low (${Math.round(replyRatio * 100)}% < ${Math.round(this.config.minReplyRatioForNewContacts * 100)}%)`,
+                retryAfterMs: TIME_CONSTANTS.MS_PER_HOUR, // arbitrary — user needs to improve engagement
+            };
+        }
+        return { allowed: true };
+    }
+    /**
+     * Get topology statistics.
+     */
+    getTopologyStats() {
+        this.resetLimitsIfNeeded();
+        const replyRatio = this.calculateReplyRatio();
+        const blockedRatio = this.calculateBlockedRatio();
+        // Get top 5 source group hotspots
+        const hotspots = Array.from(this.sourceGroupCounts.entries())
+            .map(([sourceGroup, count]) => ({ sourceGroup, count }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, 5);
+        return {
+            newContactsThisHour: this.limits.newContactsThisHour,
+            newContactsToday: this.limits.newContactsToday,
+            replyRatio,
+            blockedRatio,
+            hotspots,
+        };
+    }
+    /**
+     * Export state for persistence.
+     */
+    exportState() {
+        return {
+            contacts: Array.from(this.contacts.entries()),
+            limits: { ...this.limits },
+            sourceGroupCounts: Array.from(this.sourceGroupCounts.entries()),
+        };
+    }
+    /**
+     * Import state from persistence.
+     */
+    importState(state) {
+        if (state.contacts) {
+            this.contacts = new Map(state.contacts);
+        }
+        if (state.limits) {
+            this.limits = { ...state.limits };
+        }
+        if (state.sourceGroupCounts) {
+            this.sourceGroupCounts = new Map(state.sourceGroupCounts);
+        }
+    }
+    // Private helpers
+    resetLimitsIfNeeded() {
+        const now = Date.now();
+        // Reset hourly counter
+        if (now - this.limits.lastHourResetAt >= TIME_CONSTANTS.MS_PER_HOUR) {
+            this.limits.newContactsThisHour = 0;
+            this.limits.lastHourResetAt = now;
+        }
+        // Reset daily counter
+        if (now - this.limits.lastDayResetAt >= TIME_CONSTANTS.MS_PER_DAY) {
+            this.limits.newContactsToday = 0;
+            this.limits.lastDayResetAt = now;
+            // Clear source group counts daily
+            this.sourceGroupCounts.clear();
+        }
+    }
+    calculateReplyRatio() {
+        const now = Date.now();
+        const windowMs = TIME_CONSTANTS.REPLY_WINDOW_DAYS * TIME_CONSTANTS.MS_PER_DAY;
+        let totalSent = 0;
+        let totalReplies = 0;
+        for (const record of this.contacts.values()) {
+            // Count sends in window
+            const recentSends = record.sendTimestamps.filter(t => now - t < windowMs);
+            totalSent += recentSends.length;
+            // Count replies in window
+            const recentReplies = record.replyTimestamps.filter(t => now - t < windowMs);
+            totalReplies += recentReplies.length;
+        }
+        if (totalSent === 0)
+            return null; // No data yet
+        return totalReplies / totalSent;
+    }
+    calculateBlockedRatio() {
+        const totalContacts = this.contacts.size;
+        if (totalContacts === 0)
+            return null;
+        let blockedCount = 0;
+        for (const record of this.contacts.values()) {
+            if (record.blocked)
+                blockedCount++;
+        }
+        return blockedCount / totalContacts;
+    }
+    cleanupTimestamps(timestamps, maxAgeMs) {
+        const now = Date.now();
+        const cutoff = now - maxAgeMs;
+        // Remove old timestamps (in-place filter)
+        let writeIdx = 0;
+        for (let readIdx = 0; readIdx < timestamps.length; readIdx++) {
+            if (timestamps[readIdx] >= cutoff) {
+                timestamps[writeIdx++] = timestamps[readIdx];
+            }
+        }
+        timestamps.length = writeIdx;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baileys-antiban",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Anti-ban middleware for Baileys WhatsApp bots. Rate limiting, warmup, health monitor, LID resolver, disconnect classifier. Free Whapi.Cloud alternative.",
   "main": "dist/cjs/index.js",
   "types": "dist/index.d.ts",