miaw-core 1.2.6 → 1.7.0

package/dist/client/MiawClient.js

@@ -1,4 +1,4 @@
-import makeWASocket, { DisconnectReason, fetchLatestBaileysVersion, makeCacheableSignalKeyStore, Browsers, downloadMediaMessage, jidNormalizedUser, } from "@whiskeysockets/baileys";
+import makeWASocket, { DisconnectReason, fetchLatestBaileysVersion, fetchLatestWaWebVersion, DEFAULT_CONNECTION_CONFIG, makeCacheableSignalKeyStore, Browsers, downloadMediaMessage, jidNormalizedUser, getAggregateVotesInPollMessage, } from "@whiskeysockets/baileys";
 import { EventEmitter } from "node:events";
 import { createFilteredLogger } from "../utils/filtered-logger.js";
 import { enableConsoleFilter, disableConsoleFilter, } from "../utils/console-filter.js";
@@ -6,9 +6,10 @@ import * as path from "node:path";
 import * as fs from "node:fs";
 import { AuthHandler } from "../handlers/AuthHandler.js";
 import { MessageHandler } from "../handlers/MessageHandler.js";
-import { TIMEOUTS } from "../constants/timeouts.js";
+import { TIMEOUTS, THRESHOLDS } from "../constants/timeouts.js";
 import { CACHE_CONFIG } from "../constants/cache.js";
 import { validatePhoneNumber, validateJID, validateMessageText, validateGroupName, validatePhoneNumbers, } from "../utils/validation.js";
+import { createProxyAgents, validateProxyConfig, } from "../utils/proxy-agent.js";
 /**
  * LRU Cache for LID to JID mappings
  * Prevents unbounded memory growth while maintaining frequently used mappings
@@ -94,6 +95,8 @@ export class MiawClient extends EventEmitter {
     connectionWatchdogTimer = null;
     reconnectAttempts = 0;
     reconnectTimer = null;
+    // Cached WA Web version (resolved once, reused across reconnects)
+    cachedVersion = null;
     loggingOut = false;
     logger;
     lidToJidMap = new LruCache();
@@ -131,6 +134,12 @@ export class MiawClient extends EventEmitter {
             qrScanTimeout: options.qrScanTimeout || TIMEOUTS.QR_SCAN_TIMEOUT,
             connectionTimeout: options.connectionTimeout || TIMEOUTS.CONNECTION_TIMEOUT,
             syncFullHistory: options.syncFullHistory !== false,
+            proxy: options.proxy,
+            agent: options.agent,
+            fetchAgent: options.fetchAgent,
+            usePairingCode: options.usePairingCode,
+            phoneNumber: options.phoneNumber,
+            browser: options.browser,
         };
         // Use the initialized logger
         this.logger = logger;
@@ -177,8 +186,10 @@ export class MiawClient extends EventEmitter {
             const { state, saveCreds } = await this.authHandler.initialize();
             // Store auth state for logout access (needed when disconnected)
             this.authState = { creds: state.creds };
-            // Get latest Baileys version
-            const { version } = await fetchLatestBaileysVersion();
+            // Resolve the WA Web version (prefers the real current version to avoid 428)
+            const version = await this.resolveWAVersion();
+            // Resolve proxy agents if configured
+            const proxyAgents = await this.resolveProxyAgents();
             // Create socket
             const debugMode = this.options.debug;
             const logger = this.logger;
@@ -190,8 +201,15 @@ export class MiawClient extends EventEmitter {
                     creds: state.creds,
                     keys: makeCacheableSignalKeyStore(state.keys, this.logger),
                 },
-                browser: Browsers.macOS("Desktop"), // Desktop for more history
+                // "Desktop" identities (webSubPlatform DARWIN/WIN32) are rejected by
+                // WhatsApp with a 428 before any QR since ~2026-06-29; browser
+                // identities ("Chrome", etc.) still pair. Configurable via options.
+                // See https://github.com/WhiskeySockets/Baileys/issues/2671 and /issues/2677
+                browser: this.options.browser ?? Browsers.macOS("Chrome"),
                 generateHighQualityLinkPreview: true,
+                // Auto-recreate signal sessions on retry and migrate PN<->LID sessions
+                // (Baileys rc13 default; set explicitly to document the LID reliance).
+                enableAutoSessionRecreation: true,
                 // Enable full history sync to populate stores (controlled by syncFullHistory option)
                 syncFullHistory: this.options.syncFullHistory,
                 fireInitQueries: true,
@@ -202,9 +220,15 @@ export class MiawClient extends EventEmitter {
                     }
                     return this.options.syncFullHistory;
                 },
+                // Proxy support: agent for WebSocket, fetchAgent for media HTTP requests
+                ...(proxyAgents?.wsAgent ? { agent: proxyAgents.wsAgent } : {}),
+                ...(proxyAgents?.fetchAgent ? { fetchAgent: proxyAgents.fetchAgent } : {}),
             });
             // Register event handlers
             this.registerSocketEvents(saveCreds);
+            // Pairing-code auth (alternative to QR): on a fresh session, request an
+            // 8-char code for the configured phone number and emit it.
+            this.maybeRequestPairingCode(Boolean(state.creds.registered));
             this.logger.info("Connection initiated");
         }
         catch (error) {
@@ -215,6 +239,118 @@ export class MiawClient extends EventEmitter {
             }
         }
     }
+    /**
+     * Resolve the WhatsApp Web version to connect with.
+     *
+     * Prefers the REAL current WA Web version (queried from web.whatsapp.com/sw.js
+     * via fetchLatestWaWebVersion). Baileys' bundled/GitHub-master version is often
+     * stale, and a stale client version is a known trigger for WhatsApp rejecting
+     * the fresh-registration handshake with statusCode 428 before any QR is issued.
+     * Falls back to fetchLatestBaileysVersion, then to the version bundled with
+     * Baileys. Every network call is guarded by a short timeout so connect() can
+     * never hang on version resolution, and the result is cached so reconnects
+     * don't refetch.
+     */
+    async resolveWAVersion() {
+        if (this.cachedVersion) {
+            return this.cachedVersion;
+        }
+        const withTimeout = (p) => Promise.race([
+            p.catch(() => null),
+            new Promise((resolve) => setTimeout(() => resolve(null), TIMEOUTS.VERSION_FETCH_TIMEOUT)),
+        ]);
+        // 1) Real current WA Web version — the actual fix for the 428 bug.
+        const waWeb = await withTimeout(fetchLatestWaWebVersion());
+        if (waWeb && !waWeb.error) {
+            this.logger.info(`Using WA Web version ${waWeb.version.join(".")}`);
+            this.cachedVersion = waWeb.version;
+            return waWeb.version;
+        }
+        // 2) Baileys' published version (or its bundled default on internal error).
+        const baileys = await withTimeout(fetchLatestBaileysVersion());
+        if (baileys) {
+            this.logger.info(`Using Baileys version ${baileys.version.join(".")}` +
+                (waWeb?.error ? " (WA Web version fetch failed)" : ""));
+            this.cachedVersion = baileys.version;
+            return baileys.version;
+        }
+        // 3) Both fetches timed out/threw — use the version bundled with Baileys.
+        const fallback = DEFAULT_CONNECTION_CONFIG.version;
+        this.logger.warn(`WA version fetch failed; using bundled version ${fallback.join(".")}`);
+        this.cachedVersion = fallback;
+        return fallback;
+    }
+    /**
+     * Request a pairing code when pairing-code auth is configured and the session
+     * is not yet registered. Non-blocking; emits `pairing_code` on success.
+     * @param registered - Whether the current session creds are already registered
+     */
+    maybeRequestPairingCode(registered) {
+        if (!this.options.usePairingCode ||
+            !this.options.phoneNumber ||
+            registered ||
+            !this.socket) {
+            return;
+        }
+        this.socket
+            .requestPairingCode(this.options.phoneNumber)
+            .then((code) => {
+            if (this.options.debug) {
+                this.logger.debug(`Pairing code: ${code}`);
+            }
+            this.emit("pairing_code", code);
+        })
+            .catch((err) => {
+            this.logger.error("Failed to request pairing code:", err);
+        });
+    }
+    /**
+     * Resolves proxy agents from configuration.
+     * Direct agent/fetchAgent options take priority over proxy config.
+     */
+    async resolveProxyAgents() {
+        // Direct agent options take priority
+        if (this.options.agent || this.options.fetchAgent) {
+            return {
+                wsAgent: this.options.agent,
+                fetchAgent: this.options.fetchAgent,
+            };
+        }
+        // Create agents from proxy config
+        if (this.options.proxy) {
+            if (!validateProxyConfig(this.options.proxy)) {
+                throw new Error(`Invalid proxy configuration: ${typeof this.options.proxy === "string" ? this.options.proxy : this.options.proxy.url}`);
+            }
+            const agents = await createProxyAgents(this.options.proxy);
+            this.logger.info("Proxy agent initialized");
+            return agents;
+        }
+        return undefined;
+    }
+    /**
+     * Get current proxy configuration info (URL with credentials masked).
+     * Returns null if no proxy is configured.
+     */
+    getProxyInfo() {
+        const proxyUrl = typeof this.options.proxy === "string"
+            ? this.options.proxy
+            : this.options.proxy?.url;
+        if (!proxyUrl)
+            return null;
+        try {
+            const parsed = new URL(proxyUrl);
+            if (parsed.password) {
+                parsed.password = "****";
+            }
+            return {
+                url: parsed.toString(),
+                protocol: parsed.protocol.replace(":", ""),
+            };
+        }
+        catch {
+            return { url: proxyUrl, protocol: "unknown" };
+        }
+    }
     /**
      * Register socket event handlers
      */
@@ -224,8 +360,8 @@ export class MiawClient extends EventEmitter {
         // Connection updates
         this.socket.ev.on("connection.update", async (update) => {
             const { connection, lastDisconnect, qr } = update;
-            // Handle QR code
-            if (qr) {
+            // Handle QR code (suppressed when authenticating via pairing code)
+            if (qr && !this.options.usePairingCode) {
                 this.updateConnectionState("qr_required");
                 this.emit("qr", qr);
             }
@@ -314,14 +450,17 @@ export class MiawClient extends EventEmitter {
             this.updateChatsStore(chats);
         });
         // History sync - populates contacts, chats, and messages from history
-        this.socket.ev.on("messaging-history.set", ({ chats, contacts, messages, isLatest, peerDataRequestSessionId }) => {
+        this.socket.ev.on("messaging-history.set", ({ chats, contacts, messages, lidPnMappings, isLatest, peerDataRequestSessionId }) => {
             if (this.options.debug) {
                 this.logger.debug("\n========== MESSAGING HISTORY SYNC ==========");
-                this.logger.debug(`Contacts: ${contacts.length}, Chats: ${chats.length}, Messages: ${messages.length}`);
+                this.logger.debug(`Contacts: ${contacts.length}, Chats: ${chats.length}, Messages: ${messages.length}, LID maps: ${lidPnMappings?.length ?? 0}`);
                 this.logger.debug(`Is Latest: ${isLatest}, SessionId: ${peerDataRequestSessionId || 'none'}`);
                 this.logger.debug("============================================\n");
             }
-            // Build LID mappings FIRST (before store population)
+            // Build LID mappings FIRST (before store population). Baileys rc13 hands
+            // us a dedicated, high-confidence LID<->PN array on history sync; ingest
+            // it before the contact/chat-derived mappings.
+            this.ingestLidPnMappings(lidPnMappings);
             this.updateLidToJidMapping(contacts);
             this.updateLidFromChats(chats);
             // Update contacts from history
@@ -367,12 +506,14 @@ export class MiawClient extends EventEmitter {
                     this.handleProtocolMessage(msg, protocolMessage);
                     continue; // Don't process as regular message
                 }
-                // Build LID to JID mapping from incoming messages
-                // Incoming messages have remoteJid (phone) and senderLid (LID)
-                // Note: senderLid may exist at runtime but isn't in Baileys v7 types
+                // Build LID<->PN mapping from incoming message keys. Baileys rc13 keys
+                // carry the alternate JID (remoteJidAlt for DMs, participantAlt for
+                // groups): when the primary id is a privacy LID, the alt holds the phone
+                // JID (and vice versa). Capture whichever side is the @lid.
                 const msgKey = msg.key;
-                if (!msgKey.fromMe && msgKey.senderLid && msgKey.remoteJid) {
-                    this.addLidMapping(msgKey.senderLid, msgKey.remoteJid, "Message");
+                if (!msgKey.fromMe) {
+                    this.captureLidPnPair(msgKey.remoteJid, msgKey.remoteJidAlt);
+                    this.captureLidPnPair(msgKey.participant, msgKey.participantAlt);
                 }
                 const normalized = MessageHandler.normalize({ messages: [msg], type: "notify" }, this.logger);
                 if (normalized) {
@@ -400,6 +541,25 @@ export class MiawClient extends EventEmitter {
                             }
                         }
                     }
+                    // Native-store fallback (Baileys rc13): if the local cache couldn't
+                    // resolve the sender's @lid, ask the signal repository's LID store.
+                    // resolvePnFromNativeStore returns a normalized phone JID, which we
+                    // assign as the resolved sender JID (group -> participant, DM -> from).
+                    if (!normalized.senderPhone) {
+                        const lidJid = normalized.isGroup ? normalized.participant : normalized.from;
+                        if (lidJid?.endsWith("@lid")) {
+                            const pn = await this.resolvePnFromNativeStore(lidJid);
+                            if (pn) {
+                                if (normalized.isGroup) {
+                                    normalized.participant = pn;
+                                }
+                                else {
+                                    normalized.from = pn;
+                                }
+                                normalized.senderPhone = MessageHandler.formatJidToPhone(pn);
+                            }
+                        }
+                    }
                     // Store message in messagesStore
                     const chatJid = normalized.from;
                     if (!this.messagesStore.has(chatJid)) {
@@ -430,6 +590,20 @@ export class MiawClient extends EventEmitter {
                 this.emit("message_reaction", reactionData);
             }
         });
+        // Poll votes (messages.update carries pollUpdates when someone votes)
+        this.socket.ev.on("messages.update", (updates) => {
+            for (const { key, update } of updates) {
+                const pollUpdates = update.pollUpdates;
+                if (!pollUpdates?.length) {
+                    continue;
+                }
+                this.handlePollVote(key, pollUpdates).catch((err) => {
+                    if (this.options.debug) {
+                        this.logger.debug("Failed to process poll vote:", err);
+                    }
+                });
+            }
+        });
         // Presence updates
         this.socket.ev.on("presence.update", (presence) => {
             const jid = presence.id;
@@ -515,6 +689,7 @@ export class MiawClient extends EventEmitter {
         this.socket.ev.removeAllListeners("messaging-history.set");
         this.socket.ev.removeAllListeners("messages.upsert");
         this.socket.ev.removeAllListeners("messages.reaction");
+        this.socket.ev.removeAllListeners("messages.update");
         this.socket.ev.removeAllListeners("presence.update");
         this.socket.ev.removeAllListeners("labels.edit");
         this.socket.ev.removeAllListeners("labels.association");
@@ -572,6 +747,22 @@ export class MiawClient extends EventEmitter {
      * @param jid - The JID to map to (phone number)
      * @param source - Source of the mapping for debug logs
      */
+    /**
+     * Capture a LID<->PN mapping from a (primary, alternate) JID pair.
+     * Baileys rc13 message keys expose alternate addressing (remoteJidAlt /
+     * participantAlt); whichever side is a privacy LID (@lid) is mapped to the
+     * phone (@s.whatsapp.net) side.
+     */
+    captureLidPnPair(a, b) {
+        if (!a || !b)
+            return;
+        if (a.endsWith("@lid") && b.endsWith("@s.whatsapp.net")) {
+            this.addLidMapping(a, b, "Message");
+        }
+        else if (b.endsWith("@lid") && a.endsWith("@s.whatsapp.net")) {
+            this.addLidMapping(b, a, "Message");
+        }
+    }
     addLidMapping(lid, jid, source) {
         if (!lid || !jid) {
             return;
@@ -592,18 +783,80 @@ export class MiawClient extends EventEmitter {
             this.saveLidMappingsToFile();
         }
     }
+    /**
+     * Baileys rc13 native LID<->PN store, exposed on the signal repository.
+     * Provides server-grade resolution (USync-backed, with its own cache) that
+     * complements our local LRU cache. Null when the socket is not connected.
+     */
+    get lidStore() {
+        return this.socket ? this.socket.signalRepository.lidMapping : null;
+    }
+    /**
+     * Resolve a LID to its phone JID via Baileys' native LID store, used as a
+     * fallback when our local cache misses. On a hit the mapping is back-filled
+     * into the local cache (and persisted). Never throws.
+     * @param lidJid - A '@lid' JID
+     * @returns The phone JID (@s.whatsapp.net) or null if unresolved
+     */
+    async resolvePnFromNativeStore(lidJid) {
+        if (!lidJid?.endsWith("@lid")) {
+            return null;
+        }
+        const store = this.lidStore;
+        if (!store) {
+            return null;
+        }
+        try {
+            const pn = await store.getPNForLID(lidJid);
+            if (pn) {
+                // The native store returns device-specific JIDs (e.g. '123:0@s.whatsapp.net');
+                // normalize to a clean user JID so cache entries (and normalized.from /
+                // messagesStore keys) match every other resolution path.
+                const normalizedPn = jidNormalizedUser(pn);
+                this.addLidMapping(lidJid, normalizedPn, "NativeStore");
+                return normalizedPn;
+            }
+        }
+        catch (error) {
+            if (this.options.debug) {
+                this.logger.debug(`[LID NativeStore] getPNForLID failed for ${lidJid}:`, error);
+            }
+        }
+        return null;
+    }
+    /**
+     * Ingest the dedicated LID<->PN mapping array Baileys provides on history
+     * sync (rc13 `messaging-history.set.lidPnMappings`). This is the highest-
+     * confidence mapping source, so it is applied before contact/chat-derived
+     * mappings.
+     * @param mappings - Array of { lid, pn } pairs, or null/undefined
+     */
+    ingestLidPnMappings(mappings) {
+        if (!mappings?.length) {
+            return;
+        }
+        for (const entry of mappings) {
+            // Proto-decoded arrays can contain null/undefined entries; skip them.
+            if (!entry) {
+                continue;
+            }
+            this.addLidMapping(entry.lid, entry.pn, "History");
+        }
+    }
     /**
      * Update LID to JID mapping from contacts
      */
     updateLidToJidMapping(contacts) {
         for (const contact of contacts) {
-            // Contact has both lid and jid - create mapping
+            // id is a phone JID and lid is present - map lid -> phone
             if (contact.lid && contact.id && !contact.id.endsWith("@lid")) {
                 this.addLidMapping(contact.lid, contact.id, "Contact");
             }
-            // Also check if id is the LID and jid field exists
-            if (contact.id?.endsWith("@lid") && contact.jid) {
-                this.addLidMapping(contact.id, contact.jid, "Contact");
+            // id is the LID - map id -> phone. Baileys rc10 removed Contact.jid in
+            // favour of Contact.phoneNumber; keep .jid as a fallback for older data.
+            const contactPn = contact.phoneNumber || contact.jid;
+            if (contact.id?.endsWith("@lid") && contactPn) {
+                this.addLidMapping(contact.id, contactPn, "Contact");
             }
         }
     }
@@ -612,13 +865,15 @@ export class MiawClient extends EventEmitter {
      */
     updateLidFromChats(chats) {
         for (const chat of chats) {
-            // Chat may have both id (could be phone or LID) and lidJid
+            // id is a phone JID and lidJid is present - map lid -> phone
             if (chat.lidJid && chat.id && !chat.id.endsWith("@lid")) {
                 this.addLidMapping(chat.lidJid, chat.id, "Chat");
             }
-            // Reverse: if id is LID and we have a phone JID
-            if (chat.id?.endsWith("@lid") && chat.jid) {
-                this.addLidMapping(chat.id, chat.jid, "Chat");
+            // id is the LID - map id -> phone. Chats carry the phone JID on pnJid
+            // (Baileys rc10); keep the removed .jid field as a fallback for older data.
+            const chatPn = chat.pnJid || chat.jid;
+            if (chat.id?.endsWith("@lid") && chatPn) {
+                this.addLidMapping(chat.id, chatPn, "Chat");
             }
         }
     }
@@ -642,6 +897,33 @@ export class MiawClient extends EventEmitter {
         const resolved = this.resolveLidToJid(jid);
         return MessageHandler.formatJidToPhone(resolved);
     }
+    /**
+     * Resolve a LID to its phone JID, consulting Baileys' native LID store
+     * (rc13) when the local cache misses. Unlike the synchronous
+     * {@link resolveLidToJid}, this can perform a server-backed lookup.
+     * @param lid - The LID format JID (e.g., '12345@lid')
+     * @returns The resolved phone JID, or the original input if unresolved
+     */
+    async resolveLidToJidAsync(lid) {
+        const resolved = this.resolveLidToJid(lid);
+        // Already resolved from cache, or not a LID at all.
+        if (!resolved.endsWith("@lid")) {
+            return resolved;
+        }
+        const pn = await this.resolvePnFromNativeStore(resolved);
+        return pn || resolved;
+    }
+    /**
+     * Get the phone number for any JID, consulting Baileys' native LID store
+     * (rc13) when the local cache misses. Async counterpart of
+     * {@link getPhoneFromJid}.
+     * @param jid - Any JID format
+     * @returns Phone number string or undefined
+     */
+    async getPhoneFromJidAsync(jid) {
+        const resolved = await this.resolveLidToJidAsync(jid);
+        return MessageHandler.formatJidToPhone(resolved);
+    }
     /**
      * Manually register a LID to phone number mapping
      * Useful for persisting mappings across sessions
@@ -683,6 +965,87 @@ export class MiawClient extends EventEmitter {
     clearLidCache() {
         this.lidToJidMap.clear();
     }
+    /**
+     * Resolve multiple LIDs to phone numbers in one call. Cache hits are served
+     * locally; the remaining misses are resolved in a single batched query
+     * against Baileys' native LID store (rc13 `getPNsForLIDs`), and any results
+     * are back-filled into the local cache.
+     * @param lids - LID JIDs (e.g., ['12345@lid', ...])
+     * @returns A map of input LID -> phone number string, or null if unresolved
+     */
+    async resolveLidsToPhones(lids) {
+        const result = {};
+        const misses = [];
+        // Resolve from the local cache first; collect the misses.
+        for (const lid of lids) {
+            if (!lid?.endsWith("@lid")) {
+                // Not a LID — extract the phone directly when possible.
+                result[lid] = MessageHandler.formatJidToPhone(lid) || null;
+                continue;
+            }
+            const cached = this.resolveLidToJid(lid);
+            if (cached.endsWith("@lid")) {
+                result[lid] = null;
+                misses.push(lid);
+            }
+            else {
+                result[lid] = MessageHandler.formatJidToPhone(cached) || null;
+            }
+        }
+        // One batched native lookup for the misses.
+        const store = this.lidStore;
+        if (store && misses.length > 0) {
+            try {
+                const pairs = await store.getPNsForLIDs(misses);
+                if (pairs) {
+                    for (const { lid, pn } of pairs) {
+                        if (lid && pn) {
+                            const normalizedPn = jidNormalizedUser(pn);
+                            this.addLidMapping(lid, normalizedPn, "NativeStore");
+                            result[lid] = MessageHandler.formatJidToPhone(normalizedPn) || null;
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                if (this.options.debug) {
+                    this.logger.debug("[LID NativeStore] getPNsForLIDs failed:", error);
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Reverse-resolve a phone number to its LID via Baileys' native LID store
+     * (rc13 `getLIDForPN`). On a hit the mapping is also seeded into the local
+     * cache. Requires an active connection.
+     * @param phone - A phone number (e.g., '6281234567890') or phone JID
+     * @returns The LID JID (e.g., '12345@lid') or null if unresolved
+     */
+    async getLidForPhone(phone) {
+        const store = this.lidStore;
+        if (!store) {
+            return null;
+        }
+        const pnJid = phone.includes("@") ? phone : MessageHandler.formatPhoneToJid(phone);
+        try {
+            const lid = await store.getLIDForPN(pnJid);
+            if (lid) {
+                // Normalize the (possibly device-specific) LID before caching so it
+                // matches the bare LID form that arrives in message keys.
+                const normalizedLid = jidNormalizedUser(lid);
+                // Seed the reverse mapping into our cache for future LID -> PN lookups.
+                this.addLidMapping(normalizedLid, pnJid, "NativeStore");
+                return normalizedLid;
+            }
+        }
+        catch (error) {
+            if (this.options.debug) {
+                this.logger.debug(`[LID NativeStore] getLIDForPN failed for ${pnJid}:`, error);
+            }
+        }
+        return null;
+    }
     /**
      * Update in-memory contacts store
      * @param contacts - Array of contact objects from Baileys
@@ -792,6 +1155,12 @@ export class MiawClient extends EventEmitter {
      * @param msg - Baileys message object
      */
     addMessageToStore(msg) {
+        // Capture LID<->PN mapping from the history message key (rc13 alt fields)
+        // so @lid from/participant resolve consistently with the live message path.
+        if (msg?.key && !msg.key.fromMe) {
+            this.captureLidPnPair(msg.key.remoteJid, msg.key.remoteJidAlt);
+            this.captureLidPnPair(msg.key.participant, msg.key.participantAlt);
+        }
         const normalized = MessageHandler.normalize({ messages: [msg], type: "notify" }, this.logger);
         if (!normalized)
             return;
@@ -850,7 +1219,7 @@ export class MiawClient extends EventEmitter {
         const reason = DisconnectReason[statusCode] || "unknown";
         this.logger.info("Disconnected:", reason, "Code:", statusCode);
         this.updateConnectionState("disconnected");
-        this.emit("disconnected", reason);
+        this.emit("disconnected", reason, statusCode);
         // Reset label sync state so next connection will trigger fresh sync
         this.initialLabelSyncPromise = null;
         this.initialLabelSyncComplete = false;
@@ -866,27 +1235,53 @@ export class MiawClient extends EventEmitter {
             this.authHandler.clearSession();
             return false;
         }
+        // Don't auto-reconnect when replaced by another connection: reconnecting
+        // would just re-replace the other session, producing a 440 loop. The session
+        // stays valid — the app can call connect() to deliberately reclaim it.
+        if (statusCode === DisconnectReason.connectionReplaced) {
+            this.logger.warn("Connection replaced by another session; not auto-reconnecting (call connect() to reclaim)");
+            return false;
+        }
         return true;
     }
     /**
      * Schedule reconnection attempt
      */
     scheduleReconnect() {
-        if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {
-            this.logger.error("Max reconnection attempts reached");
-            this.emit("error", new Error("Max reconnection attempts reached"));
+        // Sessions that have never registered (fresh QR/pairing logins) are capped at
+        // a small number of attempts: if WhatsApp rejects the registration handshake
+        // (e.g. statusCode 428) before issuing a QR, retrying ~40 times/2min just
+        // hammers registration and can get the IP rate-limited. Established sessions
+        // keep the configured (possibly Infinite) limit but now with backoff.
+        //
+        // `creds.registered` can read false on a working rc13 session, but `creds.me`
+        // is only set once a session has successfully paired — so treat either as an
+        // established (post-login) session that should keep retrying.
+        const registered = Boolean(this.authState?.creds?.registered || this.authState?.creds?.me);
+        const maxAttempts = registered
+            ? this.options.maxReconnectAttempts
+            : Math.min(this.options.maxReconnectAttempts, THRESHOLDS.PRELOGIN_MAX_RECONNECT_ATTEMPTS);
+        if (this.reconnectAttempts >= maxAttempts) {
+            const message = registered
+                ? "Max reconnection attempts reached"
+                : `Could not register with WhatsApp after ${this.reconnectAttempts} attempts (no QR issued)`;
+            this.logger.error(message);
+            this.emit("error", new Error(message));
             return;
         }
         if (this.reconnectTimer) {
             clearTimeout(this.reconnectTimer);
         }
         this.reconnectAttempts++;
+        // Exponential backoff: reconnectDelay, 2x, 4x, ... capped at RECONNECT_MAX_DELAY.
+        // Prevents a persistent rejection from producing a tight retry storm.
+        const delay = Math.min(this.options.reconnectDelay * 2 ** (this.reconnectAttempts - 1), TIMEOUTS.RECONNECT_MAX_DELAY);
         // Emit event but don't set state - let connect() handle the state transition
         this.emit("reconnecting", this.reconnectAttempts);
         this.reconnectTimer = setTimeout(() => {
-            this.logger.info(`Reconnecting... Attempt ${this.reconnectAttempts}`);
+            this.logger.info(`Reconnecting... Attempt ${this.reconnectAttempts} (delay ${delay}ms)`);
             this.connect(); // This will set state to "connecting"
-        }, this.options.reconnectDelay);
+        }, delay);
     }
     /**
      * Update connection state and emit event
@@ -964,7 +1359,11 @@ export class MiawClient extends EventEmitter {
             const sendOptions = options?.quoted?.raw
                 ? { quoted: options.quoted.raw }
                 : undefined;
-            const result = await this.socket.sendMessage(jid, { text }, sendOptions);
+            const content = { text };
+            if (options?.mentions?.length) {
+                content.mentions = options.mentions.map((m) => MessageHandler.formatPhoneToJid(m));
+            }
+            const result = await this.socket.sendMessage(jid, content, sendOptions);
             return {
                 success: true,
                 messageId: result?.key?.id || undefined,
@@ -999,6 +1398,9 @@ export class MiawClient extends EventEmitter {
                 caption: options?.caption,
                 viewOnce: options?.viewOnce,
             };
+            if (options?.mentions?.length) {
+                imageContent.mentions = options.mentions.map((m) => MessageHandler.formatPhoneToJid(m));
+            }
             // Build send options (for quoting/replying)
             const sendOptions = options?.quoted?.raw
                 ? { quoted: options.quoted.raw }
@@ -1091,6 +1493,9 @@ export class MiawClient extends EventEmitter {
                 gifPlayback: options?.gifPlayback,
                 ptv: options?.ptv,
             };
+            if (options?.mentions?.length) {
+                videoContent.mentions = options.mentions.map((m) => MessageHandler.formatPhoneToJid(m));
+            }
             // Build send options (for quoting/replying)
             const sendOptions = options?.quoted?.raw
                 ? { quoted: options.quoted.raw }
@@ -1153,6 +1558,193 @@ export class MiawClient extends EventEmitter {
             };
         }
     }
+    /**
+     * Send a location message
+     * @param to - Recipient phone number or JID
+     * @param latitude - Latitude in decimal degrees
+     * @param longitude - Longitude in decimal degrees
+     * @param options - Optional name/address and quoted message
+     */
+    async sendLocation(to, latitude, longitude, options) {
+        try {
+            if (!this.socket) {
+                throw new Error("Not connected. Call connect() first.");
+            }
+            if (this.connectionState !== "connected") {
+                throw new Error(`Cannot send message. Connection state: ${this.connectionState}`);
+            }
+            const jid = MessageHandler.formatPhoneToJid(to);
+            const content = {
+                location: {
+                    degreesLatitude: latitude,
+                    degreesLongitude: longitude,
+                    name: options?.name,
+                    address: options?.address,
+                },
+            };
+            const sendOptions = options?.quoted?.raw
+                ? { quoted: options.quoted.raw }
+                : undefined;
+            const result = await this.socket.sendMessage(jid, content, sendOptions);
+            return { success: true, messageId: result?.key?.id || undefined };
+        }
+        catch (error) {
+            this.logger.error("Failed to send location:", error);
+            return { success: false, error: error.message };
+        }
+    }
+    /**
+     * Build a vCard (version 3.0) string from a contact card.
+     */
+    buildVCard(contact) {
+        const phoneJid = MessageHandler.formatPhoneToJid(contact.phone);
+        const waid = MessageHandler.formatJidToPhone(phoneJid) || contact.phone;
+        const lines = ["BEGIN:VCARD", "VERSION:3.0", `FN:${contact.fullName}`];
+        if (contact.organization) {
+            lines.push(`ORG:${contact.organization}`);
+        }
+        lines.push(`TEL;type=CELL;type=VOICE;waid=${waid}:+${waid}`);
+        lines.push("END:VCARD");
+        return lines.join("\n");
+    }
+    /**
+     * Send one or more contact cards (vCards)
+     * @param to - Recipient phone number or JID
+     * @param contacts - A single contact card or an array of them
+     * @param options - Optional quoted message
+     */
+    async sendContact(to, contacts, options) {
+        try {
+            if (!this.socket) {
+                throw new Error("Not connected. Call connect() first.");
+            }
+            if (this.connectionState !== "connected") {
+                throw new Error(`Cannot send message. Connection state: ${this.connectionState}`);
+            }
+            const list = Array.isArray(contacts) ? contacts : [contacts];
+            if (list.length === 0) {
+                return { success: false, error: "No contacts provided" };
+            }
+            const jid = MessageHandler.formatPhoneToJid(to);
+            const content = {
+                contacts: {
+                    displayName: list.length === 1 ? list[0].fullName : `${list.length} contacts`,
+                    contacts: list.map((c) => ({ vcard: this.buildVCard(c) })),
+                },
+            };
+            const sendOptions = options?.quoted?.raw
+                ? { quoted: options.quoted.raw }
+                : undefined;
+            const result = await this.socket.sendMessage(jid, content, sendOptions);
+            return { success: true, messageId: result?.key?.id || undefined };
+        }
+        catch (error) {
+            this.logger.error("Failed to send contact:", error);
+            return { success: false, error: error.message };
+        }
+    }
+    /**
+     * Send a sticker (WebP image)
+     * @param to - Recipient phone number or JID
+     * @param sticker - WebP sticker source (file path, URL, or Buffer)
+     * @param options - Optional quoted message
+     */
+    async sendSticker(to, sticker, options) {
+        try {
+            if (!this.socket) {
+                throw new Error("Not connected. Call connect() first.");
+            }
+            if (this.connectionState !== "connected") {
+                throw new Error(`Cannot send message. Connection state: ${this.connectionState}`);
+            }
+            const jid = MessageHandler.formatPhoneToJid(to);
+            const content = {
+                sticker: Buffer.isBuffer(sticker) ? sticker : { url: sticker },
+            };
+            const sendOptions = options?.quoted?.raw
+                ? { quoted: options.quoted.raw }
+                : undefined;
+            const result = await this.socket.sendMessage(jid, content, sendOptions);
+            return { success: true, messageId: result?.key?.id || undefined };
+        }
+        catch (error) {
+            this.logger.error("Failed to send sticker:", error);
+            return { success: false, error: error.message };
+        }
+    }
+    /**
+     * Send a poll
+     * @param to - Recipient phone number or JID
+     * @param name - Poll question/title
+     * @param pollOptions - Answer options (2-12)
+     * @param options - selectableCount (default 1) and quoted message
+     */
+    async sendPoll(to, name, pollOptions, options) {
+        try {
+            if (!this.socket) {
+                throw new Error("Not connected. Call connect() first.");
+            }
+            if (this.connectionState !== "connected") {
+                throw new Error(`Cannot send message. Connection state: ${this.connectionState}`);
+            }
+            if (!pollOptions || pollOptions.length < 2) {
+                return { success: false, error: "A poll needs at least 2 options" };
+            }
+            const jid = MessageHandler.formatPhoneToJid(to);
+            const content = {
+                poll: {
+                    name,
+                    values: pollOptions,
+                    selectableCount: options?.selectableCount ?? 1,
+                },
+            };
+            const sendOptions = options?.quoted?.raw
+                ? { quoted: options.quoted.raw }
+                : undefined;
+            const result = await this.socket.sendMessage(jid, content, sendOptions);
+            return { success: true, messageId: result?.key?.id || undefined };
+        }
+        catch (error) {
+            this.logger.error("Failed to send poll:", error);
+            return { success: false, error: error.message };
+        }
+    }
+    /**
+     * Decode a poll vote update and emit `poll_vote` with the aggregated tally.
+     * Requires the original poll-creation message to be in `messagesStore` (so its
+     * encryption secret is available). Best-effort; never throws to the caller.
+     */
+    async handlePollVote(key, pollUpdates) {
+        const chatId = key.remoteJid || "";
+        const pollMessageId = key.id || "";
+        if (!chatId || !pollMessageId) {
+            return;
+        }
+        // Find the original poll-creation message we stored.
+        const stored = (this.messagesStore.get(chatId) || []).find((m) => m.id === pollMessageId || m.raw?.key?.id === pollMessageId);
+        if (!stored?.raw?.message) {
+            return;
+        }
+        // Accumulate incoming vote updates onto the stored message (in-memory) so
+        // the aggregate reflects the running tally across multiple update events.
+        const raw = stored.raw;
+        raw.pollUpdates = [...(raw.pollUpdates || []), ...pollUpdates];
+        const aggregated = getAggregateVotesInPollMessage({ message: raw.message, pollUpdates: raw.pollUpdates }, this.socket?.user?.id);
+        const vote = {
+            pollMessageId,
+            chatId,
+            results: (aggregated || []).map((a) => ({
+                option: a.name,
+                voters: a.voters,
+            })),
+        };
+        if (this.options.debug) {
+            this.logger.debug("\n========== POLL VOTE ==========");
+            this.logger.debug(JSON.stringify(vote, null, 2));
+            this.logger.debug("===============================\n");
+        }
+        this.emit("poll_vote", vote);
+    }
     /**
      * Download media from a received message
      * @param message - The MiawMessage containing media (must have raw field with original Baileys message)
@@ -2424,6 +3016,171 @@ export class MiawClient extends EventEmitter {
         }
     }
     // ============================================
+    // Chat Management (v1.7.0) — via socket.chatModify
+    // ============================================
+    /**
+     * Last-message list for a chat, required by archive/clear/delete/markRead
+     * chatModify operations. Derived from the in-memory messagesStore; returns
+     * an empty list (with a debug note) if no message has been stored yet, in
+     * which case those operations are less reliable.
+     */
+    getLastMessages(jid) {
+        const msgs = this.messagesStore.get(jid);
+        const last = msgs && msgs.length > 0 ? msgs[msgs.length - 1] : undefined;
+        if (!last?.raw?.key) {
+            if (this.options.debug) {
+                this.logger.debug(`[chat] No stored last message for ${jid}; archive/clear/delete/markRead may be unreliable.`);
+            }
+            return [];
+        }
+        return [
+            {
+                key: last.raw.key,
+                messageTimestamp: last.raw.messageTimestamp ?? last.timestamp,
+            },
+        ];
+    }
+    /** Merge a flag patch into the cached ChatInfo (optimistic UI update). */
+    updateChatFlag(jidOrPhone, patch) {
+        const jid = MessageHandler.formatPhoneToJid(jidOrPhone);
+        const existing = this.chatsStore.get(jid);
+        if (existing) {
+            this.chatsStore.set(jid, { ...existing, ...patch });
+        }
+    }
+    /** Shared guard + chatModify runner for chat-level operations. */
+    async runChatModify(jidOrPhone, buildMod) {
+        try {
+            if (!this.socket) {
+                throw new Error("Not connected. Call connect() first.");
+            }
+            if (this.connectionState !== "connected") {
+                throw new Error(`Cannot modify chat. Connection state: ${this.connectionState}`);
+            }
+            const jid = MessageHandler.formatPhoneToJid(jidOrPhone);
+            await this.socket.chatModify(buildMod(jid), jid);
+            return { success: true };
+        }
+        catch (error) {
+            this.logger.error("Chat modify failed:", error);
+            return { success: false, error: error.message };
+        }
+    }
+    /** Archive a chat. */
+    async archiveChat(jidOrPhone) {
+        const res = await this.runChatModify(jidOrPhone, (jid) => ({
+            archive: true,
+            lastMessages: this.getLastMessages(jid),
+        }));
+        if (res.success)
+            this.updateChatFlag(jidOrPhone, { isArchived: true });
+        return res;
+    }
+    /** Unarchive a chat. */
+    async unarchiveChat(jidOrPhone) {
+        const res = await this.runChatModify(jidOrPhone, (jid) => ({
+            archive: false,
+            lastMessages: this.getLastMessages(jid),
+        }));
+        if (res.success)
+            this.updateChatFlag(jidOrPhone, { isArchived: false });
+        return res;
+    }
+    /** Pin a chat to the top. */
+    async pinChat(jidOrPhone) {
+        const res = await this.runChatModify(jidOrPhone, () => ({ pin: true }));
+        if (res.success)
+            this.updateChatFlag(jidOrPhone, { isPinned: true });
+        return res;
+    }
+    /** Unpin a chat. */
+    async unpinChat(jidOrPhone) {
+        const res = await this.runChatModify(jidOrPhone, () => ({ pin: false }));
+        if (res.success)
+            this.updateChatFlag(jidOrPhone, { isPinned: false });
+        return res;
+    }
+    /**
+     * Mute a chat.
+     * @param jidOrPhone - Chat JID or phone number
+     * @param durationMs - How long to mute for, in ms (default: 8 hours). Baileys
+     *   stores this as an absolute mute-end timestamp (`Date.now() + durationMs`).
+     */
+    async muteChat(jidOrPhone, durationMs = 8 * 60 * 60 * 1000) {
+        const res = await this.runChatModify(jidOrPhone, () => ({
+            mute: Date.now() + durationMs,
+        }));
+        if (res.success)
+            this.updateChatFlag(jidOrPhone, { isMuted: true });
+        return res;
+    }
+    /** Unmute a chat. */
+    async unmuteChat(jidOrPhone) {
+        const res = await this.runChatModify(jidOrPhone, () => ({ mute: null }));
+        if (res.success)
+            this.updateChatFlag(jidOrPhone, { isMuted: false });
+        return res;
+    }
+    /**
+     * Mark a whole chat as read (app-state level). Distinct from
+     * {@link markAsRead}, which sends a read receipt for a single message.
+     */
+    async markChatRead(jidOrPhone) {
+        return this.runChatModify(jidOrPhone, (jid) => ({
+            markRead: true,
+            lastMessages: this.getLastMessages(jid),
+        }));
+    }
+    /** Mark a whole chat as unread. */
+    async markChatUnread(jidOrPhone) {
+        return this.runChatModify(jidOrPhone, (jid) => ({
+            markRead: false,
+            lastMessages: this.getLastMessages(jid),
+        }));
+    }
+    /** Clear all messages in a chat (keeps the chat). */
+    async clearChat(jidOrPhone) {
+        return this.runChatModify(jidOrPhone, (jid) => ({
+            clear: true,
+            lastMessages: this.getLastMessages(jid),
+        }));
+    }
+    /** Delete a chat entirely. */
+    async deleteChat(jidOrPhone) {
+        return this.runChatModify(jidOrPhone, (jid) => ({
+            delete: true,
+            lastMessages: this.getLastMessages(jid),
+        }));
+    }
+    /** Star a message. */
+    async starMessage(message) {
+        return this.setMessageStar(message, true);
+    }
+    /** Remove a star from a message. */
+    async unstarMessage(message) {
+        return this.setMessageStar(message, false);
+    }
+    async setMessageStar(message, star) {
+        try {
+            if (!this.socket) {
+                throw new Error("Not connected. Call connect() first.");
+            }
+            if (this.connectionState !== "connected") {
+                throw new Error(`Cannot star message. Connection state: ${this.connectionState}`);
+            }
+            const key = message.raw?.key;
+            if (!key?.id || !key?.remoteJid) {
+                throw new Error("Message does not contain raw Baileys key data.");
+            }
+            await this.socket.chatModify({ star: { messages: [{ id: key.id, fromMe: !!key.fromMe }], star } }, key.remoteJid);
+            return { success: true };
+        }
+        catch (error) {
+            this.logger.error("Failed to star/unstar message:", error);
+            return { success: false, error: error.message };
+        }
+    }
+    // ============================================
     // UX Methods (v0.5.0)
     // ============================================
     /**