baileys-antiban 3.9.0 → 4.6.0

package/dist/antiban.d.ts

@@ -25,7 +25,10 @@ import { PostReconnectThrottle, type ReconnectThrottleConfig, type ReconnectThro
 import { LidResolver, type LidResolverConfig, type LidResolverStats } from './lidResolver.js';
 import { JidCanonicalizer, type JidCanonicalizerConfig, type JidCanonicalizerStats } from './jidCanonicalizer.js';
 import { SessionHealthMonitor, type SessionHealthStats } from './sessionStability.js';
+import { BanRecoveryOrchestrator, type RecoveryStatus } from './banRecoveryOrchestrator.js';
 import { type AntiBanInput, type ResolvedConfig } from './presets.js';
+import { type DeliveryTrackerStats } from './deliveryTracker.js';
+import { type InstanceCoordinatorStats } from './instanceCoordinator.js';
 export interface AntiBanConfigLegacy {
     rateLimiter?: Partial<RateLimiterConfig>;
     warmUp?: Partial<WarmUpConfig>;
@@ -70,6 +73,9 @@ export interface AntiBanStats {
     lidResolver?: LidResolverStats | null;
     jidCanonicalizer?: JidCanonicalizerStats | null;
     sessionStability?: SessionHealthStats | null;
+    banRecovery?: RecoveryStatus | null;
+    deliveryTracker: DeliveryTrackerStats;
+    instanceCoordinator?: InstanceCoordinatorStats | null;
 }
 export declare class AntiBan {
     private rateLimiter;
@@ -84,6 +90,9 @@ export declare class AntiBan {
     private lidResolverModule;
     private jidCanonicalizerModule;
     private sessionStabilityMonitor;
+    private banRecovery;
+    private deliveryTracker;
+    private instanceCoordinator;
     private stateManager;
     private resolvedConfig;
     private logging;
@@ -98,7 +107,7 @@ export declare class AntiBan {
      * Record a successfully sent message.
      * Call this AFTER every successful sendMessage().
      */
-    afterSend(recipient: string, content: string): void;
+    afterSend(recipient: string, content: string, msgId?: string): void;
     /**
      * Record a failed message send
      */
@@ -119,6 +128,11 @@ export declare class AntiBan {
         shouldReply: boolean;
         suggestedText?: string;
     };
+    /**
+     * Record a delivery receipt (status 3 = DELIVERY_ACK, status 4 = READ).
+     * Call from messages.update handler when delivery status is received.
+     */
+    onDeliveryReceipt(msgId: string): void;
     /**
      * Get the resolved configuration
      */
@@ -145,6 +159,8 @@ export declare class AntiBan {
     get jidCanonicalizer(): JidCanonicalizer | null;
     /** Get the session stability monitor for direct access */
     get sessionStability(): SessionHealthMonitor | null;
+    /** Get the ban recovery orchestrator for direct access */
+    get recoveryOrchestrator(): BanRecoveryOrchestrator;
     /**
      * Export warm-up state for persistence between restarts
      */
@@ -161,6 +177,7 @@ export declare class AntiBan {
      * Reset everything (use after a ban period)
      */
     reset(): void;
+    private runAdaptiveCheck;
     private persistStateDebounced;
     private persistStateImmediate;
     /**

package/dist/antiban.js

@@ -25,9 +25,12 @@ import { PostReconnectThrottle } from './reconnectThrottle.js';
 import { LidResolver } from './lidResolver.js';
 import { JidCanonicalizer } from './jidCanonicalizer.js';
 import { SessionHealthMonitor } from './sessionStability.js';
+import { BanRecoveryOrchestrator } from './banRecoveryOrchestrator.js';
 import { resolveConfig } from './presets.js';
 import { StateManager } from './persist.js';
 import { shouldUseGroupProfile, applyGroupMultiplier } from './profiles.js';
+import { DeliveryTracker } from './deliveryTracker.js';
+import { InstanceCoordinator } from './instanceCoordinator.js';
 function isLegacyConfig(cfg) {
     if (typeof cfg !== 'object' || cfg === null)
         return false;
@@ -103,6 +106,9 @@ export class AntiBan {
     lidResolverModule = null;
     jidCanonicalizerModule = null;
     sessionStabilityMonitor = null;
+    banRecovery;
+    deliveryTracker;
+    instanceCoordinator = null;
     stateManager = null;
     resolvedConfig;
     logging;
@@ -173,14 +179,40 @@ export class AntiBan {
                 if ((status.risk === 'high' || status.risk === 'critical') && cfg.onAtRisk) {
                     cfg.onAtRisk(status);
                 }
+                // Trigger recovery orchestrator on critical risk
+                if (status.risk === 'critical') {
+                    this.banRecovery.recordBanEvent('soft_ban');
+                }
                 cfg.onRiskChange?.(status);
                 legacyPassthrough?.health?.onRiskChange?.(status);
             },
         });
+        // Initialize ban recovery orchestrator
+        this.banRecovery = new BanRecoveryOrchestrator({
+            onPhaseChange: (phase, plan) => {
+                if (this.logging) {
+                    console.log(`[baileys-antiban] 🔄 Recovery phase: ${phase} — ${plan.description}`);
+                }
+            },
+            onHardBan: () => {
+                if (this.logging) {
+                    console.log(`[baileys-antiban] 💀 HARD BAN detected — account likely dead, replace SIM`);
+                }
+            },
+        });
+        // Initialize delivery tracker
+        this.deliveryTracker = new DeliveryTracker({
+            onLowDeliveryRate: (rate) => {
+                if (this.logging) {
+                    console.log(`[baileys-antiban] ⚠️  Low delivery rate detected: ${Math.round(rate * 100)}% — possible soft ban`);
+                }
+            },
+        });
         this.timelockGuard = new TimelockGuard({
             ...(legacyPassthrough?.timelock || {}),
             onTimelockDetected: (state) => {
                 this.health.recordReachoutTimelock(state.enforcementType);
+                this.banRecovery.recordBanEvent('timelock');
                 if (this.logging) {
                     console.log(`[baileys-antiban] REACHOUT TIMELOCKED — ${state.enforcementType || 'unknown'}, expires ${state.expiresAt?.toISOString() || 'unknown'}`);
                 }
@@ -254,6 +286,17 @@ export class AntiBan {
             };
             this.sessionStabilityMonitor = new SessionHealthMonitor(healthConfig);
         }
+        // Initialize instance coordinator if configured
+        if (cfg.instanceCoordinator) {
+            this.instanceCoordinator = new InstanceCoordinator({
+                sharedFilePath: cfg.instanceCoordinator,
+                poolMaxPerMinute: cfg.instancePoolMaxPerMinute,
+                poolMaxPerHour: cfg.instancePoolMaxPerHour,
+            });
+            if (this.logging) {
+                console.log(`[baileys-antiban] 🌐 Instance coordination enabled: ${cfg.instanceCoordinator}`);
+            }
+        }
     }
     /**
      * Check if a message can be sent and get required delay.
@@ -274,6 +317,17 @@ export class AntiBan {
                 health: healthStatus,
             };
         }
+        // Recovery orchestrator rate multiplier
+        const recoveryStatus = this.banRecovery.getStatus();
+        if (recoveryStatus.phase === 'paused') {
+            this.stats.messagesBlocked++;
+            return {
+                allowed: false,
+                delayMs: recoveryStatus.pauseRemainingMs || 0,
+                reason: `Ban recovery: ${recoveryStatus.recommendation}`,
+                health: healthStatus,
+            };
+        }
         // Timelock guard (allows existing chats, blocks new contacts)
         const timelockDecision = this.timelockGuard.canSend(recipient);
         if (!timelockDecision.allowed) {
@@ -345,6 +399,22 @@ export class AntiBan {
                 health: healthStatus,
             };
         }
+        // Cross-instance coordination — check shared IP-level pool
+        if (this.instanceCoordinator) {
+            const slot = this.instanceCoordinator.tryAcquireSlot();
+            if (!slot.allowed) {
+                this.stats.messagesBlocked++;
+                if (this.logging) {
+                    console.log(`[baileys-antiban] 🌐 BLOCKED — instance pool exhausted (shared IP limit), retry in ${slot.retryAfterMs}ms`);
+                }
+                return {
+                    allowed: false,
+                    delayMs: slot.retryAfterMs || 5000,
+                    reason: 'Cross-instance rate pool exhausted',
+                    health: healthStatus,
+                };
+            }
+        }
         // Group profile rate check (runs before rateLimiter.getDelay for timing)
         if (this.resolvedConfig.groupProfiles && shouldUseGroupProfile(recipient)) {
             const groupLimits = applyGroupMultiplier({
@@ -384,6 +454,24 @@ export class AntiBan {
             const multiplier = Math.min(5, 1 / activityFactor);
             delay = Math.floor(delay * multiplier);
         }
+        // Per-contact risk multiplier — cold contacts need longer delays
+        // Only apply when contact graph is enabled, otherwise all contacts appear as 'stranger'
+        if (this.contactGraphWarmer['config']?.enabled) {
+            const contactState = this.contactGraphWarmer.getContactState(recipient);
+            const coldMultiplier = {
+                stranger: 2.5,
+                handshake_sent: 1.8,
+                handshake_complete: 1.3,
+                known: 1.0,
+            };
+            const contactRiskMult = coldMultiplier[contactState] ?? 1.0;
+            if (contactRiskMult > 1.0) {
+                delay = Math.floor(delay * contactRiskMult);
+                if (this.logging && contactRiskMult >= 2.0) {
+                    console.log(`[baileys-antiban] ⚠️  Cold contact ${recipient} — ${contactState}, delay ×${contactRiskMult}`);
+                }
+            }
+        }
         // Roll for distraction pause
         const distractionCheck = this.presenceChoreographer.shouldPauseForDistraction();
         if (distractionCheck.pause) {
@@ -411,11 +499,15 @@ export class AntiBan {
      * Record a successfully sent message.
      * Call this AFTER every successful sendMessage().
      */
-    afterSend(recipient, content) {
+    afterSend(recipient, content, msgId) {
         this.rateLimiter.record(recipient, content);
         this.warmUp.record();
         this.replyRatioGuard.recordSent(recipient);
         this.stats.messagesAllowed++;
+        if (msgId) {
+            this.deliveryTracker.onMessageSent(msgId);
+        }
+        this.runAdaptiveCheck();
         this.persistStateDebounced();
     }
     /**
@@ -441,6 +533,7 @@ export class AntiBan {
     onReconnect() {
         this.health.recordReconnect();
         this.reconnectThrottleModule.onReconnect();
+        this.rateLimiter.adaptLimits(1.0);
     }
     /**
      * Handle incoming message — record in reply ratio + contact graph.
@@ -451,6 +544,13 @@ export class AntiBan {
         this.contactGraphWarmer.onIncomingMessage(jid);
         return this.replyRatioGuard.suggestReply(jid, msgText);
     }
+    /**
+     * Record a delivery receipt (status 3 = DELIVERY_ACK, status 4 = READ).
+     * Call from messages.update handler when delivery status is received.
+     */
+    onDeliveryReceipt(msgId) {
+        this.deliveryTracker.onDeliveryReceipt(msgId);
+    }
     /**
      * Get the resolved configuration
      */
@@ -466,6 +566,8 @@ export class AntiBan {
             health: this.health.getStatus(),
             warmUp: this.warmUp.getStatus(),
             rateLimiter: this.rateLimiter.getStats(),
+            banRecovery: this.banRecovery.getStatus(),
+            deliveryTracker: this.deliveryTracker.getStats(),
         };
         // Only include new stats if enabled
         if (this.replyRatioGuard['config']?.enabled) {
@@ -492,6 +594,9 @@ export class AntiBan {
         if (this.sessionStabilityMonitor) {
             stats.sessionStability = this.sessionStabilityMonitor.getStats();
         }
+        if (this.instanceCoordinator) {
+            stats.instanceCoordinator = this.instanceCoordinator.getStats();
+        }
         return stats;
     }
     /** Get the timelock guard for direct access */
@@ -530,6 +635,10 @@ export class AntiBan {
     get sessionStability() {
         return this.sessionStabilityMonitor;
     }
+    /** Get the ban recovery orchestrator for direct access */
+    get recoveryOrchestrator() {
+        return this.banRecovery;
+    }
     /**
      * Export warm-up state for persistence between restarts
      */
@@ -571,6 +680,35 @@ export class AntiBan {
             console.log('[baileys-antiban] 🔄 Reset — starting fresh warm-up');
         }
     }
+    runAdaptiveCheck() {
+        const delivery = this.deliveryTracker.getStats();
+        // Need min sample to be meaningful
+        if (delivery.deliveryRate === null)
+            return;
+        const rate = delivery.deliveryRate;
+        let targetFactor;
+        if (rate >= 0.85) {
+            targetFactor = 1.0; // Excellent — full speed
+        }
+        else if (rate >= 0.70) {
+            targetFactor = 0.75; // Good — slight reduction
+        }
+        else if (rate >= 0.55) {
+            targetFactor = 0.50; // Poor — halve throughput
+        }
+        else {
+            targetFactor = 0.25; // Bad — severe throttle (soft ban likely)
+        }
+        const current = this.rateLimiter.getCurrentFactor();
+        // Only log + adjust when factor changes meaningfully (>5% delta)
+        if (Math.abs(targetFactor - current) > 0.05) {
+            if (this.logging) {
+                const dir = targetFactor > current ? '📈' : '📉';
+                console.log(`[baileys-antiban] ${dir} Adaptive rate: delivery=${(rate * 100).toFixed(0)}% → factor ${current.toFixed(2)}→${targetFactor.toFixed(2)}`);
+            }
+            this.rateLimiter.adaptLimits(targetFactor);
+        }
+    }
     persistStateDebounced() {
         if (!this.stateManager)
             return;

package/dist/banRecoveryOrchestrator.d.ts

@@ -0,0 +1,87 @@
+/**
+ * BanRecoveryOrchestrator — Structured recovery after ban/restriction events
+ *
+ * When WhatsApp restricts your account, the worst thing to do is immediately
+ * resume normal activity. This module provides a evidence-based recovery protocol:
+ *
+ * - Timelocked (reachout_restricted): 24h pause, resume at 10% rate, ramp 15%/week
+ * - Rate-overlimit (429): 4h pause, resume at 25% rate, ramp 25%/week
+ * - Soft-ban (repeated disconnects): 48h pause, resume at 5% rate, ramp 10%/week
+ * - Hard-ban (loggedOut): account is dead, signal for replacement
+ *
+ * Based on observed recovery times from community reports. Not guaranteed —
+ * WA's enforcement is non-deterministic. Treat as best-effort guidance.
+ */
+export type BanEventType = 'timelock' | 'rate_overlimit' | 'soft_ban' | 'hard_ban';
+export type RecoveryPhase = 'paused' | 'recovering' | 'ramping' | 'graduated' | 'dead';
+export interface RecoveryPlan {
+    eventType: BanEventType;
+    pauseDurationMs: number;
+    resumeRateMultiplier: number;
+    weeklyRampPercent: number;
+    estimatedRecoveryDays: number;
+    description: string;
+}
+export interface BanRecoveryConfig {
+    /** Custom recovery plans per event type (overrides defaults) */
+    plans?: Partial<Record<BanEventType, Partial<RecoveryPlan>>>;
+    /** Called when recovery phase changes */
+    onPhaseChange?: (phase: RecoveryPhase, plan: RecoveryPlan) => void;
+    /** Called when account appears dead (hard ban) — signal to replace SIM */
+    onHardBan?: () => void;
+    /** Max weeks before giving up on recovery and declaring dead (default: 8) */
+    maxRecoveryWeeks?: number;
+}
+export interface RecoveryState {
+    active: boolean;
+    eventType?: BanEventType;
+    phase: RecoveryPhase;
+    banDetectedAt?: number;
+    pauseUntil?: number;
+    currentRateMultiplier: number;
+    weeksSinceResume: number;
+    banCount30d: number;
+    lastBanAt?: number;
+}
+export interface RecoveryStatus {
+    phase: RecoveryPhase;
+    rateMultiplier: number;
+    pauseRemainingMs?: number;
+    estimatedFullRecoveryDate?: number;
+    recommendation: string;
+    shouldReplaceNumber: boolean;
+}
+export declare class BanRecoveryOrchestrator {
+    private config;
+    private state;
+    private plans;
+    constructor(config?: BanRecoveryConfig);
+    /**
+     * Record a ban event and start recovery protocol
+     */
+    recordBanEvent(eventType: BanEventType): RecoveryStatus;
+    /**
+     * Get current recovery status (call before sending to check rate)
+     */
+    getStatus(): RecoveryStatus;
+    /**
+     * Current rate multiplier — multiply your normal limits by this
+     */
+    getRateMultiplier(): number;
+    /**
+     * Should be called daily/weekly to advance the ramp
+     */
+    tick(): void;
+    /**
+     * Classify a raw error into a BanEventType
+     */
+    static classifyError(err: unknown): BanEventType | null;
+    /**
+     * Serializable state for persistence
+     */
+    getState(): RecoveryState;
+    /**
+     * Restore from persisted state
+     */
+    static fromState(state: RecoveryState, config?: BanRecoveryConfig): BanRecoveryOrchestrator;
+}

package/dist/banRecoveryOrchestrator.js

@@ -0,0 +1,284 @@
+/**
+ * BanRecoveryOrchestrator — Structured recovery after ban/restriction events
+ *
+ * When WhatsApp restricts your account, the worst thing to do is immediately
+ * resume normal activity. This module provides a evidence-based recovery protocol:
+ *
+ * - Timelocked (reachout_restricted): 24h pause, resume at 10% rate, ramp 15%/week
+ * - Rate-overlimit (429): 4h pause, resume at 25% rate, ramp 25%/week
+ * - Soft-ban (repeated disconnects): 48h pause, resume at 5% rate, ramp 10%/week
+ * - Hard-ban (loggedOut): account is dead, signal for replacement
+ *
+ * Based on observed recovery times from community reports. Not guaranteed —
+ * WA's enforcement is non-deterministic. Treat as best-effort guidance.
+ */
+const DEFAULT_PLANS = {
+    timelock: {
+        eventType: 'timelock',
+        pauseDurationMs: 24 * 60 * 60 * 1000, // 24 hours
+        resumeRateMultiplier: 0.10, // 10% of normal
+        weeklyRampPercent: 15, // +15% per week
+        estimatedRecoveryDays: 14,
+        description: 'WA reachout timelock — 24h pause then slow ramp',
+    },
+    rate_overlimit: {
+        eventType: 'rate_overlimit',
+        pauseDurationMs: 4 * 60 * 60 * 1000, // 4 hours
+        resumeRateMultiplier: 0.25, // 25% of normal
+        weeklyRampPercent: 25, // +25% per week
+        estimatedRecoveryDays: 7,
+        description: 'Rate limit hit — 4h pause then moderate ramp',
+    },
+    soft_ban: {
+        eventType: 'soft_ban',
+        pauseDurationMs: 48 * 60 * 60 * 1000, // 48 hours
+        resumeRateMultiplier: 0.05, // 5% of normal
+        weeklyRampPercent: 10, // +10% per week
+        estimatedRecoveryDays: 21,
+        description: 'Soft ban detected — 48h pause then very slow ramp',
+    },
+    hard_ban: {
+        eventType: 'hard_ban',
+        pauseDurationMs: Infinity,
+        resumeRateMultiplier: 0,
+        weeklyRampPercent: 0,
+        estimatedRecoveryDays: Infinity,
+        description: 'Hard ban — number is dead, replace SIM',
+    },
+};
+export class BanRecoveryOrchestrator {
+    config;
+    state;
+    plans;
+    constructor(config = {}) {
+        this.config = {
+            plans: config.plans || {},
+            onPhaseChange: config.onPhaseChange || (() => { }),
+            onHardBan: config.onHardBan || (() => { }),
+            maxRecoveryWeeks: config.maxRecoveryWeeks ?? 8,
+        };
+        // Merge custom plans with defaults
+        this.plans = { ...DEFAULT_PLANS };
+        if (config.plans) {
+            for (const eventType in config.plans) {
+                const customPlan = config.plans[eventType];
+                if (customPlan) {
+                    this.plans[eventType] = {
+                        ...this.plans[eventType],
+                        ...customPlan,
+                    };
+                }
+            }
+        }
+        this.state = {
+            active: false,
+            phase: 'graduated',
+            currentRateMultiplier: 1.0,
+            weeksSinceResume: 0,
+            banCount30d: 0,
+        };
+    }
+    /**
+     * Record a ban event and start recovery protocol
+     */
+    recordBanEvent(eventType) {
+        const now = Date.now();
+        const plan = this.plans[eventType];
+        // Update ban count (reset if >30 days since last ban)
+        if (this.state.lastBanAt) {
+            const daysSinceLastBan = (now - this.state.lastBanAt) / (86400000);
+            if (daysSinceLastBan > 30) {
+                this.state.banCount30d = 0;
+            }
+        }
+        this.state.banCount30d++;
+        this.state.lastBanAt = now;
+        // Upgrade to hard_ban if 3+ bans in 30 days (unless already hard_ban)
+        if (this.state.banCount30d >= 3 && eventType !== 'hard_ban') {
+            eventType = 'hard_ban';
+        }
+        this.state.active = true;
+        this.state.eventType = eventType;
+        this.state.banDetectedAt = now;
+        this.state.pauseUntil = plan.pauseDurationMs === Infinity ? Infinity : now + plan.pauseDurationMs;
+        this.state.currentRateMultiplier = plan.resumeRateMultiplier;
+        this.state.weeksSinceResume = 0;
+        this.state.phase = eventType === 'hard_ban' ? 'dead' : 'paused';
+        this.config.onPhaseChange(this.state.phase, plan);
+        if (eventType === 'hard_ban') {
+            this.config.onHardBan();
+        }
+        return this.getStatus();
+    }
+    /**
+     * Get current recovery status (call before sending to check rate)
+     */
+    getStatus() {
+        if (!this.state.active || !this.state.eventType) {
+            return {
+                phase: 'graduated',
+                rateMultiplier: 1.0,
+                recommendation: 'No active recovery — operating normally',
+                shouldReplaceNumber: false,
+            };
+        }
+        const now = Date.now();
+        const plan = this.plans[this.state.eventType];
+        // Check if pause period has ended
+        if (this.state.phase === 'paused' && this.state.pauseUntil !== undefined && this.state.pauseUntil !== Infinity && now >= this.state.pauseUntil) {
+            this.state.phase = 'recovering';
+            this.config.onPhaseChange(this.state.phase, plan);
+        }
+        // Check if we've exceeded max recovery weeks (give up)
+        if (this.state.phase === 'recovering' || this.state.phase === 'ramping') {
+            if (this.state.weeksSinceResume >= this.config.maxRecoveryWeeks) {
+                this.state.phase = 'dead';
+                this.config.onPhaseChange(this.state.phase, plan);
+                this.config.onHardBan();
+            }
+        }
+        const shouldReplaceNumber = this.state.phase === 'dead' || this.state.banCount30d >= 3;
+        let recommendation;
+        switch (this.state.phase) {
+            case 'dead':
+                recommendation = 'Account is permanently restricted. Replace number and start fresh.';
+                break;
+            case 'paused':
+                if (this.state.pauseUntil === Infinity) {
+                    recommendation = 'Account is dead. Do not attempt to send messages.';
+                }
+                else {
+                    const remainingMs = this.state.pauseUntil - now;
+                    const remainingHours = Math.ceil(remainingMs / 3600000);
+                    recommendation = `Pause period active. Wait ${remainingHours}h before resuming. ${plan.description}`;
+                }
+                break;
+            case 'recovering':
+                recommendation = `Recovery phase. Operating at ${Math.round(this.state.currentRateMultiplier * 100)}% capacity. Ramp: ${plan.weeklyRampPercent}%/week.`;
+                break;
+            case 'ramping':
+                recommendation = `Ramping phase. Operating at ${Math.round(this.state.currentRateMultiplier * 100)}% capacity. Ramp: ${plan.weeklyRampPercent}%/week.`;
+                break;
+            case 'graduated':
+                recommendation = 'Recovery complete. Operating at full capacity.';
+                break;
+        }
+        const pauseRemainingMs = this.state.pauseUntil !== undefined && this.state.pauseUntil !== Infinity && now < this.state.pauseUntil
+            ? this.state.pauseUntil - now
+            : undefined;
+        let estimatedFullRecoveryDate;
+        if (this.state.phase === 'recovering' || this.state.phase === 'ramping') {
+            const rateToGain = 1.0 - this.state.currentRateMultiplier;
+            const weeksNeeded = Math.ceil((rateToGain / (plan.weeklyRampPercent / 100)) * (1 / this.state.currentRateMultiplier));
+            estimatedFullRecoveryDate = now + weeksNeeded * 7 * 86400000;
+        }
+        return {
+            phase: this.state.phase,
+            rateMultiplier: this.state.currentRateMultiplier,
+            pauseRemainingMs,
+            estimatedFullRecoveryDate,
+            recommendation,
+            shouldReplaceNumber,
+        };
+    }
+    /**
+     * Current rate multiplier — multiply your normal limits by this
+     */
+    getRateMultiplier() {
+        return this.state.currentRateMultiplier;
+    }
+    /**
+     * Should be called daily/weekly to advance the ramp
+     */
+    tick() {
+        if (!this.state.active || !this.state.eventType) {
+            return;
+        }
+        const now = Date.now();
+        const plan = this.plans[this.state.eventType];
+        // Transition from paused to recovering
+        if (this.state.phase === 'paused' && this.state.pauseUntil !== undefined && this.state.pauseUntil !== Infinity && now >= this.state.pauseUntil) {
+            this.state.phase = 'recovering';
+            this.config.onPhaseChange(this.state.phase, plan);
+        }
+        // Advance the ramp if in recovering/ramping phase
+        if (this.state.phase === 'recovering' || this.state.phase === 'ramping') {
+            this.state.weeksSinceResume++;
+            // Check if exceeded max recovery weeks
+            if (this.state.weeksSinceResume >= this.config.maxRecoveryWeeks) {
+                this.state.phase = 'dead';
+                this.state.currentRateMultiplier = 0;
+                this.config.onPhaseChange(this.state.phase, plan);
+                this.config.onHardBan();
+                return;
+            }
+            // Apply weekly ramp
+            const rampMultiplier = 1 + (plan.weeklyRampPercent / 100);
+            const newMultiplier = this.state.currentRateMultiplier * rampMultiplier;
+            if (newMultiplier >= 1.0) {
+                // Graduated
+                this.state.currentRateMultiplier = 1.0;
+                this.state.phase = 'graduated';
+                this.state.active = false;
+                this.config.onPhaseChange(this.state.phase, plan);
+            }
+            else {
+                // Still ramping
+                this.state.currentRateMultiplier = newMultiplier;
+                this.state.phase = 'ramping';
+            }
+        }
+    }
+    /**
+     * Classify a raw error into a BanEventType
+     */
+    static classifyError(err) {
+        if (!err)
+            return null;
+        const errorStr = String(err).toLowerCase();
+        const errorMsg = err.message?.toLowerCase() || '';
+        const errorCode = err.code || '';
+        // Timelock patterns
+        if (errorStr.includes('reachout') ||
+            errorStr.includes('account_reachout_restricted') ||
+            errorMsg.includes('reachout') ||
+            errorCode === 463 ||
+            errorCode === '463') {
+            return 'timelock';
+        }
+        // Rate overlimit patterns
+        if (errorStr.includes('rate-overlimit') ||
+            errorStr.includes('rate_overlimit') ||
+            errorStr.includes('429') ||
+            errorCode === 429 ||
+            errorCode === '429') {
+            return 'rate_overlimit';
+        }
+        // Hard ban patterns
+        if (errorStr.includes('loggedout') ||
+            errorStr.includes('logged_out') ||
+            errorStr.includes('logged out') ||
+            errorMsg.includes('loggedout') ||
+            errorCode === 401 ||
+            errorCode === '401') {
+            return 'hard_ban';
+        }
+        // Note: soft_ban detection requires context (multiple disconnects)
+        // and should be determined by the caller using HealthMonitor
+        return null;
+    }
+    /**
+     * Serializable state for persistence
+     */
+    getState() {
+        return { ...this.state };
+    }
+    /**
+     * Restore from persisted state
+     */
+    static fromState(state, config) {
+        const orchestrator = new BanRecoveryOrchestrator(config);
+        orchestrator.state = { ...state };
+        return orchestrator;
+    }
+}