baileys-antiban 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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).
 
+## [3.3.0] — 2026-04-26
+
+### Added
+- **`JidCanonicalizer.canonicalKey(jid)`** — Returns stable thread key for DB storage/indexing
+  - Solves the split-thread bug from Baileys v7 LID migration ([#1832](https://github.com/WhiskeySockets/Baileys/issues/1832))
+  - Always returns same key regardless of whether message arrives as `@lid` or `@s.whatsapp.net`
+  - Format: `thread:<digits>` for known contacts, `thread:lid:<digits>` for unknown, `thread:group:<id>` for groups
+  - Uses learned LID↔PN mappings when available, falls back to LID form when not
+  - Handles edge cases: groups, broadcasts, newsletters, empty/null inputs
+  - Tracks stats: `canonicalKeyHits` (PN known) vs `canonicalKeyMisses` (LID only)
+- **`docs/lid-migration.md`** — Comprehensive guide for surviving Baileys v7's LID migration
+  - Explains the three major bugs LID causes (#1832 split-thread, #1718 phone lookup, #2030 call routing)
+  - Full integration examples: learning from events, canonicalizing sends, stable DB keys
+  - Production setup with persistence, stats logging, cleanup
+  - Limitations and best practices
+
+### Why v3.3
+Baileys v7 made `@lid` the default JID format, but many apps still use `remoteJid` as their database thread key. This causes the same conversation to appear as two separate threads when messages arrive under different forms. `canonicalKey()` provides a stable, form-independent identifier that prevents this split-thread bug. The LID migration doc owns the narrative for the v7 transition.
+
 ## [3.2.0] — 2026-04-26
 
 ### New Features

package/README.md

@@ -9,6 +9,8 @@
 
 > Rate limiting with Gaussian jitter, 7-day warmup, session health monitoring, LID resolver, disconnect classification, contact graph enforcement — all in one `npm install`. Works with [Baileys](https://github.com/WhiskeySockets/Baileys) and [@oxidezap/baileyrs](https://github.com/oxidezap/baileyrs) (Rust/WASM).
 
+> **New in v3.3:** [LID Migration Guide](./docs/lid-migration.md) — survive Baileys v7's @lid default with stable thread keys.
+
 ## v2.0 New Features — Session Stability Module
 
 ### What's New in v2.0

package/dist/jidCanonicalizer.d.ts

@@ -39,6 +39,8 @@ export interface JidCanonicalizerStats {
     outboundCanonicalized: number;
     outboundPassthrough: number;
     inboundLearned: number;
+    canonicalKeyHits: number;
+    canonicalKeyMisses: number;
 }
 export declare class JidCanonicalizer {
     private config;
@@ -54,6 +56,23 @@ export declare class JidCanonicalizer {
      * Called by wrapper on every outbound send. Returns canonical JID.
      */
     canonicalizeTarget(jid: string): string;
+    /**
+     * Returns a stable, canonical thread key for storage / DB indexing.
+     *
+     * Different from `canonicalizeTarget()` (which picks the right send target):
+     * - canonicalizeTarget('1234@lid') → '+27...@s.whatsapp.net' (best send target)
+     * - canonicalKey('1234@lid')      → 'thread:27...'  (stable thread identifier)
+     *
+     * If LID has known PN mapping → use phone-number form
+     * If only LID known → use LID stripped of suffix
+     * Always lowercase, no @-suffix, prefixed with `thread:`
+     *
+     * Apps using this as their DB key won't double-thread on LID/PN drift.
+     *
+     * @param jid - WhatsApp JID (can be PN, LID, group, or broadcast)
+     * @returns Stable thread key for DB indexing
+     */
+    canonicalKey(jid: string): string;
     /**
      * Called by wrapper on messages.upsert event. Learns mappings.
      */

package/dist/jidCanonicalizer.js

@@ -35,6 +35,8 @@ export class JidCanonicalizer {
         outboundCanonicalized: 0,
         outboundPassthrough: 0,
         inboundLearned: 0,
+        canonicalKeyHits: 0,
+        canonicalKeyMisses: 0,
     };
     constructor(config = {}) {
         this.config = { ...DEFAULT_CONFIG, ...config };
@@ -70,6 +72,72 @@ export class JidCanonicalizer {
         }
         return canonical;
     }
+    /**
+     * Returns a stable, canonical thread key for storage / DB indexing.
+     *
+     * Different from `canonicalizeTarget()` (which picks the right send target):
+     * - canonicalizeTarget('1234@lid') → '+27...@s.whatsapp.net' (best send target)
+     * - canonicalKey('1234@lid')      → 'thread:27...'  (stable thread identifier)
+     *
+     * If LID has known PN mapping → use phone-number form
+     * If only LID known → use LID stripped of suffix
+     * Always lowercase, no @-suffix, prefixed with `thread:`
+     *
+     * Apps using this as their DB key won't double-thread on LID/PN drift.
+     *
+     * @param jid - WhatsApp JID (can be PN, LID, group, or broadcast)
+     * @returns Stable thread key for DB indexing
+     */
+    canonicalKey(jid) {
+        // Defensive: handle null/undefined/empty
+        if (!jid || typeof jid !== 'string' || jid.trim() === '') {
+            return 'thread:invalid';
+        }
+        const normalized = jid.trim().toLowerCase();
+        // Extract parts: user@domain
+        const atIndex = normalized.indexOf('@');
+        if (atIndex === -1) {
+            return 'thread:invalid';
+        }
+        const user = normalized.substring(0, atIndex);
+        const domain = normalized.substring(atIndex + 1);
+        // Handle special domains
+        if (domain === 'g.us') {
+            // Group chat
+            return `thread:group:${user}`;
+        }
+        if (domain === 'broadcast') {
+            // Broadcast list
+            return `thread:broadcast:${user}`;
+        }
+        if (domain === 'newsletter') {
+            // Newsletter (WA Channels)
+            return `thread:newsletter:${user}`;
+        }
+        // Handle @s.whatsapp.net (PN form)
+        if (domain === 's.whatsapp.net') {
+            this.stats.canonicalKeyHits++;
+            return `thread:${user}`;
+        }
+        // Handle @lid form
+        if (domain === 'lid') {
+            // Try to resolve to PN via learned mappings
+            const mapping = this.lidResolver.getMapping(normalized);
+            if (mapping?.pn) {
+                // We have a PN mapping — use it
+                const pnUser = mapping.pn.split('@')[0];
+                this.stats.canonicalKeyHits++;
+                return `thread:${pnUser}`;
+            }
+            else {
+                // No PN known yet — use LID form
+                this.stats.canonicalKeyMisses++;
+                return `thread:lid:${user}`;
+            }
+        }
+        // Unknown domain — return generic form
+        return `thread:${domain}:${user}`;
+    }
     /**
      * Called by wrapper on messages.upsert event. Learns mappings.
      */
@@ -102,6 +170,8 @@ export class JidCanonicalizer {
             outboundCanonicalized: this.stats.outboundCanonicalized,
             outboundPassthrough: this.stats.outboundPassthrough,
             inboundLearned: this.stats.inboundLearned,
+            canonicalKeyHits: this.stats.canonicalKeyHits,
+            canonicalKeyMisses: this.stats.canonicalKeyMisses,
         };
     }
     destroy() {

package/package.json

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