baileys-antiban 1.5.0 → 2.0.0

package/CHANGELOG.md

@@ -5,6 +5,61 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-04-19
+
+### Added
+- **Session Stability Module** — New middleware layer for Baileys socket stability (opt-in, backward compatible)
+  - `wrapWithSessionStability()` — Proxy wrapper for Baileys socket with stability features
+  - `SessionHealthMonitor` — Track decrypt success/fail ratio, emit degradation alerts when Bad MAC rate exceeds threshold
+  - `classifyDisconnect()` — Typed disconnect reason classification with recovery recommendations
+  - Canonical JID normalization before `sendMessage()` — Auto-resolves PN↔LID using `LidResolver` to reduce mutex race triggers
+  - Comprehensive disconnect code coverage: 401, 408, 428, 429, 440, 500, 503, 515, 1000, unknown
+  - Degradation detection: triggers `onDegraded` callback when Bad MAC count exceeds threshold in time window (default: 3 in 60s)
+  - Recovery detection: triggers `onRecovered` callback when Bad MAC rate drops below threshold
+  - 19 new tests with 100% coverage of disconnect classification and health monitoring
+
+### Changed
+- `AntiBan` class extended with optional `sessionStability` config (default: disabled)
+- `AntiBanConfig` interface includes `sessionStability` options (enabled, canonicalJidNormalization, healthMonitoring, badMacThreshold, badMacWindowMs)
+- `AntiBanStats` includes `sessionStability` stats when enabled
+- `destroy()` now cleans up session stability monitor
+- Exposed `sessionStability` getter for direct access to health monitor
+
+### Technical Details
+- Pure middleware layer — no Baileys internals modification required
+- Works alongside existing v1.x LID resolver and canonicalizer modules
+- Default configuration: disabled for backward compatibility, opt-in via `sessionStability: { enabled: true }`
+- Health monitor uses sliding window for Bad MAC detection (default: 3 errors in 60 seconds)
+- Socket wrapper uses ES6 Proxy for transparent method interception
+- TypeScript strict mode compliant, no `any` types except socket wrapper generic
+
+### Breaking Changes
+None — all v2.0 features are opt-in and backward compatible with v1.x
+
+## [1.6.0] - 2026-04-18
+
+### Added
+- **LID/PN Race Condition Mitigation** — New modules to address the #1 reported Baileys bug: "Bad MAC / No Session / Invalid PreKey" errors caused by WhatsApp's Linked Identity (LID) migration
+  - `LidResolver` — Standalone utility for maintaining bidirectional LID↔PN mappings learned from message events
+  - `JidCanonicalizer` — Opt-in middleware that auto-learns from incoming events and canonicalizes outbound send targets to a single form (phone number by default)
+  - Both modules default to **disabled** — backward compatible, zero behavior change for existing users
+  - Middleware-layer mitigation only — root fix still requires [PR #2372](https://github.com/WhiskeySockets/Baileys/pull/2372) merged upstream
+  - Comprehensive test coverage: 56 new tests (29 LidResolver + 18 JidCanonicalizer + 9 integration)
+
+### Changed
+- `AntiBan` class now exposes `lidResolver` and `jidCanonicalizer` getters for direct access
+- `AntiBanConfig` extended with `lidResolver` and `jidCanonicalizer` config options
+- `AntiBanStats` includes `lidResolver` and `jidCanonicalizer` stats when enabled
+- Wrapper's `sendMessage` now canonicalizes JID before all rate-limit/timelock/graph checks
+- `messages.upsert` and `messages.update` handlers now auto-learn LID mappings when canonicalizer enabled
+
+### Technical Details
+- LRU eviction at configurable `maxEntries` (default 10,000)
+- Optional persistence hooks for cross-restart state survival
+- Device suffix stripping (`:N` in JIDs) for robust matching
+- Supports both `canonical: 'pn'` (phone number) and `canonical: 'lid'` modes
+- Shared resolver mode allows multiple canonicalizers to reference same mapping state
+
 ## [1.5.0] - 2026-04-18
 
 ### Added

package/README.md

@@ -6,7 +6,144 @@
 
 **Transport-agnostic** anti-ban middleware — protect your WhatsApp number with human-like messaging patterns. Works with both [Baileys](https://github.com/WhiskeySockets/Baileys) and [@oxidezap/baileyrs](https://github.com/oxidezap/baileyrs) (Rust/WASM).
 
-## v1.5 New Features
+## v2.0 New Features — Session Stability Module
+
+### What's New in v2.0
+
+Three powerful new features to improve session stability and reduce "Bad MAC" errors:
+
+1. **Typed Disconnect Reason Classification** — Know exactly why you disconnected and how to recover
+2. **Session Health Monitor** — Detect session degradation before it causes bans
+3. **Socket Wrapper with JID Canonicalization** — Middleware-layer fix for LID/PN race conditions
+
+All v2.0 features are **opt-in** and **100% backward compatible** with v1.x.
+
+### 1. Typed Disconnect Reason Classification
+
+```typescript
+import { classifyDisconnect } from 'baileys-antiban';
+
+sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+  if (connection === 'close' && lastDisconnect?.error) {
+    const statusCode = lastDisconnect.error.output?.statusCode;
+    const classification = classifyDisconnect(statusCode);
+
+    console.log(`Disconnected: ${classification.message}`);
+    console.log(`Category: ${classification.category}`);  // fatal | recoverable | rate-limited | unknown
+    console.log(`Should reconnect: ${classification.shouldReconnect}`);
+    
+    if (classification.shouldReconnect && classification.backoffMs) {
+      console.log(`Recommended backoff: ${classification.backoffMs}ms`);
+      setTimeout(() => connectToWhatsApp(), classification.backoffMs);
+    }
+  }
+});
+```
+
+**Supported disconnect codes**: 401 (logged out), 408 (timeout), 428 (connection replaced), 429 (rate limited), 440 (logged out), 500 (internal error), 503 (unavailable), 515 (restart required), 1000 (graceful close), and unknown codes.
+
+### 2. Session Health Monitor
+
+Track decrypt success/failure ratio to detect session degradation **before** it causes a ban:
+
+```typescript
+import { SessionHealthMonitor } from 'baileys-antiban';
+
+const healthMonitor = new SessionHealthMonitor({
+  badMacThreshold: 3,          // Alert after 3 Bad MACs
+  badMacWindowMs: 60_000,      // ...in 60 seconds
+  onDegraded: (stats) => {
+    console.error(`🔴 SESSION DEGRADED: ${stats.badMacCount} Bad MACs in last minute`);
+    console.error('Action required: Restart session or switch to LID-based canonical form');
+  },
+  onRecovered: (stats) => {
+    console.log('🟢 Session recovered — decrypt success rate improved');
+  },
+});
+
+// Wire to Baileys events
+sock.ev.on('messages.update', (updates) => {
+  for (const { key, update } of updates) {
+    if (update.messageStubType === Types.WAMessageStubType.CIPHERTEXT) {
+      healthMonitor.recordDecryptFail(true); // Bad MAC detected
+    }
+  }
+});
+
+// Check status anytime
+const stats = healthMonitor.getStats();
+console.log(`Decrypt success: ${stats.decryptSuccess}`);
+console.log(`Bad MAC count: ${stats.badMacCount}`);
+console.log(`Is degraded: ${stats.isDegraded}`);
+```
+
+### 3. Socket Wrapper with JID Canonicalization
+
+The easiest way to use v2.0: wrap your socket for automatic JID canonicalization and health monitoring:
+
+```typescript
+import { wrapWithSessionStability, LidResolver } from 'baileys-antiban';
+
+const resolver = new LidResolver({ canonical: 'pn' });
+const sock = makeWASocket({ ... });
+
+const safeSock = wrapWithSessionStability(sock, {
+  canonicalJidNormalization: true,  // Auto-canonicalize JIDs before sendMessage
+  healthMonitoring: true,           // Auto-track decrypt health
+  lidResolver: resolver,
+  health: {
+    badMacThreshold: 3,
+    badMacWindowMs: 60_000,
+    onDegraded: (stats) => console.error('Session degraded!'),
+  },
+});
+
+// Use safeSock exactly like normal sock
+await safeSock.sendMessage('123456@lid', { text: 'hello' });
+// ^ Automatically canonicalized to '27825651069@s.whatsapp.net' if mapping exists
+
+// Access health stats
+const healthStats = safeSock.sessionHealthStats;
+console.log(`Bad MAC count: ${healthStats.badMacCount}`);
+```
+
+### Integration with AntiBan Class
+
+You can also enable session stability via the main `AntiBan` config:
+
+```typescript
+import { AntiBan } from 'baileys-antiban';
+
+const antiban = new AntiBan({
+  sessionStability: {
+    enabled: true,
+    canonicalJidNormalization: true,  // Auto-canonicalize JIDs
+    healthMonitoring: true,           // Track Bad MAC rate
+    badMacThreshold: 3,
+    badMacWindowMs: 60_000,
+  },
+  jidCanonicalizer: {
+    enabled: true,
+    canonical: 'pn',
+  },
+});
+
+// Access health monitor directly
+const healthMonitor = antiban.sessionStability;
+if (healthMonitor) {
+  console.log(healthMonitor.getStats());
+}
+
+// Stats include session stability
+const stats = antiban.getStats();
+console.log(stats.sessionStability);  // Health stats when enabled
+```
+
+**Why v2.0?** Bad MAC errors are the #1 reported Baileys issue. Session stability features give you early warning and automated mitigation, reducing bans caused by session degradation.
+
+---
+
+## v1.5 Features
 
 ### RetryReasonTracker
 Tracks message retry reasons and detects retry spirals (when the same message keeps failing). Inspired by whatsapp-rust's protocol/retry.rs module.
@@ -61,6 +198,58 @@ console.log(stats.throttledSendCount);   // Sends gated since reconnect
 
 **Why?** When WhatsApp reconnects after a disconnection, sending messages at full rate immediately can trigger rate limit alarms. The reconnect throttle gradually ramps up sending rate over 60 seconds, mimicking how a human would resume messaging after their internet came back.
 
+## LID / Phone Number Canonicalization
+
+WhatsApp migrated to **Linked Identity (LID)** in 2024. A contact now has two JID forms:
+- Phone number: `27825651069@s.whatsapp.net`
+- LID: `123456789@lid`
+
+Messages can arrive under either form. If an encryption session was established under one form and a message arrives under the other, decryption fails → **"Bad MAC / No Session / Invalid PreKey"** errors (the #1 reported Baileys bug).
+
+baileys-antiban v1.6+ provides **middleware-layer mitigation** via two new modules:
+
+```typescript
+import { wrapSocket } from 'baileys-antiban';
+
+const sock = makeWASocket({ ... });
+const safeSock = wrapSocket(sock, {
+  jidCanonicalizer: {
+    enabled: true,  // Enable LID/PN canonicalization
+    canonical: 'pn', // Normalize to phone-number form (default)
+  },
+});
+
+// That's it! Incoming events auto-learn LID↔PN mappings.
+// Outbound sends are auto-canonicalized to phone-number form.
+```
+
+**Advanced: Standalone Resolver**
+
+```typescript
+import { LidResolver } from 'baileys-antiban';
+
+const resolver = new LidResolver({
+  canonical: 'pn',
+  maxEntries: 10_000, // LRU cache size
+  persistence: {
+    load: async () => JSON.parse(await fs.readFile('lid-map.json', 'utf8')),
+    save: async (map) => fs.writeFile('lid-map.json', JSON.stringify(map)),
+  },
+});
+
+// Learn from message events
+resolver.learn({
+  lid: '123456789@lid',
+  pn: '27825651069@s.whatsapp.net',
+});
+
+// Resolve canonical form
+const canonical = resolver.resolveCanonical('123456789@lid');
+// → '27825651069@s.whatsapp.net'
+```
+
+**Note:** This is a middleware-layer workaround. The root fix lives inside Baileys' crypto pipeline ([PR #2372](https://github.com/WhiskeySockets/Baileys/pull/2372)).
+
 ## v1.3 Features
 
 ### ReplyRatioGuard

package/dist/antiban.d.ts

@@ -22,6 +22,9 @@ import { ContactGraphWarmer, type ContactGraphConfig, type ContactGraphStats } f
 import { PresenceChoreographer, type PresenceChoreographerConfig, type PresenceChoreographerStats } from './presenceChoreographer.js';
 import { RetryReasonTracker, type RetryTrackerConfig, type RetryStats } from './retryTracker.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';
+import { SessionHealthMonitor, type SessionHealthStats } from './sessionStability.js';
 export interface AntiBanConfig {
     rateLimiter?: Partial<RateLimiterConfig>;
     warmUp?: Partial<WarmUpConfig>;
@@ -32,6 +35,20 @@ export interface AntiBanConfig {
     presence?: Partial<PresenceChoreographerConfig>;
     retryTracker?: Partial<RetryTrackerConfig>;
     reconnectThrottle?: Partial<ReconnectThrottleConfig>;
+    lidResolver?: LidResolverConfig;
+    jidCanonicalizer?: JidCanonicalizerConfig;
+    /** Session stability features (v2.0) — default disabled for backward compatibility */
+    sessionStability?: {
+        enabled: boolean;
+        /** Enable canonical JID normalization before sendMessage (default: true if enabled) */
+        canonicalJidNormalization?: boolean;
+        /** Enable session health monitoring (default: true if enabled) */
+        healthMonitoring?: boolean;
+        /** Bad MAC threshold before declaring session degraded (default: 3) */
+        badMacThreshold?: number;
+        /** Time window for Bad MAC threshold in ms (default: 60000) */
+        badMacWindowMs?: number;
+    };
     /** Log warnings and blocks to console (default: true) */
     logging?: boolean;
 }
@@ -54,6 +71,9 @@ export interface AntiBanStats {
     presence?: PresenceChoreographerStats;
     retryTracker?: RetryStats | null;
     reconnectThrottle?: ReconnectThrottleStats | null;
+    lidResolver?: LidResolverStats | null;
+    jidCanonicalizer?: JidCanonicalizerStats | null;
+    sessionStability?: SessionHealthStats | null;
 }
 export declare class AntiBan {
     private rateLimiter;
@@ -65,6 +85,9 @@ export declare class AntiBan {
     private presenceChoreographer;
     private retryTrackerModule;
     private reconnectThrottleModule;
+    private lidResolverModule;
+    private jidCanonicalizerModule;
+    private sessionStabilityMonitor;
     private logging;
     private stats;
     constructor(config?: AntiBanConfig, warmUpState?: WarmUpState);
@@ -114,6 +137,12 @@ export declare class AntiBan {
     get retryTracker(): RetryReasonTracker;
     /** Get the reconnect throttle for direct access */
     get reconnectThrottle(): PostReconnectThrottle;
+    /** Get the LID resolver for direct access */
+    get lidResolver(): LidResolver | null;
+    /** Get the JID canonicalizer for direct access */
+    get jidCanonicalizer(): JidCanonicalizer | null;
+    /** Get the session stability monitor for direct access */
+    get sessionStability(): SessionHealthMonitor | null;
     /**
      * Export warm-up state for persistence between restarts
      */

package/dist/antiban.js

@@ -22,6 +22,9 @@ import { ContactGraphWarmer } from './contactGraph.js';
 import { PresenceChoreographer } from './presenceChoreographer.js';
 import { RetryReasonTracker } from './retryTracker.js';
 import { PostReconnectThrottle } from './reconnectThrottle.js';
+import { LidResolver } from './lidResolver.js';
+import { JidCanonicalizer } from './jidCanonicalizer.js';
+import { SessionHealthMonitor } from './sessionStability.js';
 export class AntiBan {
     rateLimiter;
     warmUp;
@@ -32,6 +35,9 @@ export class AntiBan {
     presenceChoreographer;
     retryTrackerModule;
     reconnectThrottleModule;
+    lidResolverModule = null;
+    jidCanonicalizerModule = null;
+    sessionStabilityMonitor = null;
     logging;
     stats = {
         messagesAllowed: 0,
@@ -86,6 +92,49 @@ export class AntiBan {
             ...config.reconnectThrottle,
             baselineRatePerMinute: () => this.rateLimiter.getStats().limits.perMinute,
         });
+        // Initialize LID resolver and canonicalizer if configured
+        // If jidCanonicalizer is enabled but no resolver provided, create standalone resolver
+        if (config.jidCanonicalizer?.enabled) {
+            // Create or use provided resolver
+            if (config.jidCanonicalizer.resolver) {
+                // User provided their own resolver
+                this.jidCanonicalizerModule = new JidCanonicalizer(config.jidCanonicalizer);
+                this.lidResolverModule = config.jidCanonicalizer.resolver;
+            }
+            else {
+                // Create new resolver using lidResolver config if provided
+                const resolverConfig = config.lidResolver || config.jidCanonicalizer.resolverConfig;
+                const resolver = new LidResolver(resolverConfig);
+                this.lidResolverModule = resolver;
+                this.jidCanonicalizerModule = new JidCanonicalizer({
+                    ...config.jidCanonicalizer,
+                    resolver,
+                });
+            }
+        }
+        else if (config.lidResolver) {
+            // Standalone resolver without canonicalizer
+            this.lidResolverModule = new LidResolver(config.lidResolver);
+        }
+        // Initialize session stability monitor if enabled
+        if (config.sessionStability?.enabled) {
+            const healthConfig = {
+                badMacThreshold: config.sessionStability.badMacThreshold,
+                badMacWindowMs: config.sessionStability.badMacWindowMs,
+                onDegraded: (stats) => {
+                    if (this.logging) {
+                        console.log(`[baileys-antiban] 🔴 SESSION DEGRADED — Bad MAC rate: ${stats.badMacCount} in last ${config.sessionStability?.badMacWindowMs || 60000}ms`);
+                        console.log(`[baileys-antiban] Consider restarting session or switching to LID-based canonical form`);
+                    }
+                },
+                onRecovered: () => {
+                    if (this.logging) {
+                        console.log(`[baileys-antiban] 🟢 SESSION RECOVERED — decrypt success rate improved`);
+                    }
+                },
+            };
+            this.sessionStabilityMonitor = new SessionHealthMonitor(healthConfig);
+        }
     }
     /**
      * Check if a message can be sent and get required delay.
@@ -286,6 +335,15 @@ export class AntiBan {
         if (this.reconnectThrottleModule['config']?.enabled) {
             stats.reconnectThrottle = this.reconnectThrottleModule.getStats();
         }
+        if (this.lidResolverModule) {
+            stats.lidResolver = this.lidResolverModule.getStats();
+        }
+        if (this.jidCanonicalizerModule) {
+            stats.jidCanonicalizer = this.jidCanonicalizerModule.getStats();
+        }
+        if (this.sessionStabilityMonitor) {
+            stats.sessionStability = this.sessionStabilityMonitor.getStats();
+        }
         return stats;
     }
     /** Get the timelock guard for direct access */
@@ -312,6 +370,18 @@ export class AntiBan {
     get reconnectThrottle() {
         return this.reconnectThrottleModule;
     }
+    /** Get the LID resolver for direct access */
+    get lidResolver() {
+        return this.lidResolverModule;
+    }
+    /** Get the JID canonicalizer for direct access */
+    get jidCanonicalizer() {
+        return this.jidCanonicalizerModule;
+    }
+    /** Get the session stability monitor for direct access */
+    get sessionStability() {
+        return this.sessionStabilityMonitor;
+    }
     /**
      * Export warm-up state for persistence between restarts
      */
@@ -364,6 +434,9 @@ export class AntiBan {
         this.presenceChoreographer.reset();
         this.retryTrackerModule.destroy();
         this.reconnectThrottleModule.destroy();
+        this.jidCanonicalizerModule?.destroy();
+        this.lidResolverModule?.destroy();
+        this.sessionStabilityMonitor?.reset();
         if (this.logging) {
             console.log('[baileys-antiban] 🧹 Destroyed — all timers cleared');
         }

package/dist/index.d.ts

@@ -17,6 +17,9 @@ export { ContactGraphWarmer, type ContactGraphConfig, type ContactGraphStats, ty
 export { PresenceChoreographer, type PresenceChoreographerConfig, type PresenceChoreographerStats } from './presenceChoreographer.js';
 export { RetryReasonTracker, type RetryTrackerConfig, type RetryStats, type RetryReason } from './retryTracker.js';
 export { PostReconnectThrottle, type ReconnectThrottleConfig, type ReconnectThrottleStats } from './reconnectThrottle.js';
+export { LidResolver, type LidResolverConfig, type LidResolverStats, type LidMapping } from './lidResolver.js';
+export { JidCanonicalizer, type JidCanonicalizerConfig, type JidCanonicalizerStats } from './jidCanonicalizer.js';
+export { SessionHealthMonitor, type SessionHealthStats, type SessionHealthConfig, wrapWithSessionStability, type SessionStabilityConfig, classifyDisconnect, type DisconnectClassification, type DisconnectCategory, } from './sessionStability.js';
 export { wrapSocket, type WrappedSocket, type WrapSocketOptions } from './wrapper.js';
 export { MessageQueue, type QueuedMessage, type MessageQueueConfig } from './messageQueue.js';
 export { ContentVariator, type VariatorConfig } from './contentVariator.js';

package/dist/index.js

@@ -20,6 +20,11 @@ export { PresenceChoreographer } from './presenceChoreographer.js';
 // v1.5 new modules
 export { RetryReasonTracker } from './retryTracker.js';
 export { PostReconnectThrottle } from './reconnectThrottle.js';
+// v1.6 new modules
+export { LidResolver } from './lidResolver.js';
+export { JidCanonicalizer } from './jidCanonicalizer.js';
+// v2.0 new modules
+export { SessionHealthMonitor, wrapWithSessionStability, classifyDisconnect, } from './sessionStability.js';
 // Socket wrapper
 export { wrapSocket } from './wrapper.js';
 // Optional features

package/dist/jidCanonicalizer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * JID Canonicalizer — Opt-in middleware for LID/PN normalization
+ *
+ * Wraps LidResolver to provide automatic:
+ * 1. Learning from incoming message events
+ * 2. Canonicalization of outbound send targets
+ *
+ * This mitigates the LID/PN race condition that causes "Bad MAC / No Session /
+ * Invalid PreKey" errors (Baileys issue #1769, our PR #2372).
+ *
+ * Usage:
+ *   const canonicalizer = new JidCanonicalizer({ enabled: true });
+ *
+ *   // On incoming event
+ *   canonicalizer.onIncomingEvent({ messages: [...] });
+ *
+ *   // On outbound send
+ *   const canonicalJid = canonicalizer.canonicalizeTarget(jid);
+ *   await sock.sendMessage(canonicalJid, content);
+ *
+ * Note: This is a middleware-layer mitigation. The root fix requires merging
+ * PR #2372 into Baileys' crypto pipeline.
+ */
+import { LidResolver, type LidResolverConfig, type LidResolverStats } from './lidResolver.js';
+export interface JidCanonicalizerConfig {
+    /** Enable canonicalization (default: false — opt-in) */
+    enabled?: boolean;
+    /** Provide your own resolver to share across modules. Otherwise one is created. */
+    resolver?: LidResolver;
+    /** Config for creating a new resolver (ignored if resolver provided) */
+    resolverConfig?: LidResolverConfig;
+    /** Canonicalize outbound sendMessage targets. Default true. */
+    canonicalizeOutbound?: boolean;
+    /** Learn from inbound events. Default true. */
+    learnFromEvents?: boolean;
+}
+export interface JidCanonicalizerStats {
+    resolver: LidResolverStats;
+    outboundCanonicalized: number;
+    outboundPassthrough: number;
+    inboundLearned: number;
+}
+export declare class JidCanonicalizer {
+    private config;
+    private lidResolver;
+    private ownsResolver;
+    private stats;
+    constructor(config?: JidCanonicalizerConfig);
+    /**
+     * Access the underlying resolver (for cross-module sharing)
+     */
+    get resolver(): LidResolver;
+    /**
+     * Called by wrapper on every outbound send. Returns canonical JID.
+     */
+    canonicalizeTarget(jid: string): string;
+    /**
+     * Called by wrapper on messages.upsert event. Learns mappings.
+     */
+    onIncomingEvent(upsert: {
+        messages: Array<any>;
+        type?: string;
+    }): void;
+    /**
+     * Called by wrapper on messages.update event. Learns from sent-message refs.
+     */
+    onMessageUpdate(updates: Array<any>): void;
+    getStats(): JidCanonicalizerStats;
+    destroy(): void;
+    /**
+     * Extract LID↔PN mappings from a message object
+     */
+    private learnFromMessage;
+    /**
+     * Extract mappings from message.key
+     */
+    private learnFromMessageKey;
+}