miaw-core 1.1.0 → 1.2.0

package/dist/client/MiawClient.js

@@ -1,9 +1,14 @@
-import makeWASocket, { DisconnectReason, fetchLatestBaileysVersion, makeCacheableSignalKeyStore, downloadMediaMessage, } from "@whiskeysockets/baileys";
+import makeWASocket, { DisconnectReason, fetchLatestBaileysVersion, makeCacheableSignalKeyStore, Browsers, downloadMediaMessage, } from "@whiskeysockets/baileys";
 import { EventEmitter } from "node:events";
-import pino from "pino";
+import { createFilteredLogger } from "../utils/filtered-logger.js";
+import { enableConsoleFilter, disableConsoleFilter, } from "../utils/console-filter.js";
 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 { CACHE_CONFIG } from "../constants/cache.js";
+import { validatePhoneNumber, validateJID, validateMessageText, validateGroupName, validatePhoneNumbers, } from "../utils/validation.js";
 /**
  * LRU Cache for LID to JID mappings
  * Prevents unbounded memory growth while maintaining frequently used mappings
@@ -11,7 +16,7 @@ import { MessageHandler } from "../handlers/MessageHandler.js";
 class LruCache {
     cache;
     maxSize;
-    constructor(maxSize = 1000) {
+    constructor(maxSize = CACHE_CONFIG.LID_MAP_MAX_SIZE) {
         this.cache = new Map();
         this.maxSize = maxSize;
     }
@@ -48,6 +53,34 @@ class LruCache {
     get size() {
         return this.cache.size;
     }
+    /**
+     * Get an iterator for all entries in the cache
+     * @returns Iterator of [key, value] tuples
+     */
+    entries() {
+        return this.cache.entries();
+    }
+    /**
+     * Get an iterator for all keys in the cache
+     * @returns Iterator of keys
+     */
+    keys() {
+        return this.cache.keys();
+    }
+    /**
+     * Get an iterator for all values in the cache
+     * @returns Iterator of values
+     */
+    values() {
+        return this.cache.values();
+    }
+    /**
+     * Execute a callback for each entry in the cache
+     * @param callback - Function to call for each entry
+     */
+    forEach(callback) {
+        this.cache.forEach(callback);
+    }
 }
 /**
  * Main client class for interacting with WhatsApp
@@ -57,33 +90,54 @@ export class MiawClient extends EventEmitter {
     socket = null;
     authHandler;
     connectionState = "disconnected";
+    connectionStateTimestamp = 0;
+    connectionWatchdogTimer = null;
     reconnectAttempts = 0;
     reconnectTimer = null;
+    loggingOut = false;
     logger;
-    lidToJidMap = new LruCache(1000);
-    // In-memory stores for v0.9.0
+    lidToJidMap = new LruCache();
+    // Custom stores for contacts, chats, messages (Baileys v7 removed makeInMemoryStore)
     contactsStore = new Map();
+    chatsStore = new Map();
+    messagesStore = new Map();
     labelsStore = new Map();
-    messagesStore = new Map(); // JID -> messages
-    chatsStore = new Map(); // JID -> chat info
+    // Store label-chat associations (labelId -> Set of chatJids)
+    labelChatsStore = new Map();
+    // Track pending history fetch requests for loadMoreMessages
+    pendingHistoryRequests = new Map();
+    labelEventCount = 0;
+    lastLabelSyncTime;
+    // Track initial label sync to ensure fetchAllLabels waits for it
+    initialLabelSyncPromise = null;
+    initialLabelSyncComplete = false;
+    // Store auth state for logout access (needed when disconnected)
+    authState = null;
     constructor(options) {
         super();
+        // Initialize logger first (needed for options)
+        const logger = options.logger || createFilteredLogger(options.debug || false);
         // Set default options
         this.options = {
             instanceId: options.instanceId,
             sessionPath: options.sessionPath || "./sessions",
             debug: options.debug || false,
-            logger: options.logger,
+            logger: logger,
             autoReconnect: options.autoReconnect !== false,
             maxReconnectAttempts: options.maxReconnectAttempts || Infinity,
-            reconnectDelay: options.reconnectDelay || 3000,
+            reconnectDelay: options.reconnectDelay || TIMEOUTS.RECONNECT_DELAY,
+            stuckStateTimeout: options.stuckStateTimeout || TIMEOUTS.STUCK_STATE,
+            qrGracePeriod: options.qrGracePeriod || TIMEOUTS.QR_GRACE_PERIOD,
+            qrScanTimeout: options.qrScanTimeout || TIMEOUTS.QR_SCAN_TIMEOUT,
+            connectionTimeout: options.connectionTimeout || TIMEOUTS.CONNECTION_TIMEOUT,
         };
-        // Initialize logger
-        this.logger =
-            this.options.logger ||
-                pino({
-                    level: this.options.debug ? "debug" : "silent",
-                });
+        // Use the initialized logger
+        this.logger = logger;
+        // Enable console filter to suppress libsignal logs when debug is off
+        // libsignal logs directly to console.info/warn, bypassing our logger
+        if (!this.options.debug) {
+            enableConsoleFilter();
+        }
         // Initialize handlers
         this.authHandler = new AuthHandler(this.options.sessionPath, this.options.instanceId);
     }
@@ -91,13 +145,42 @@ export class MiawClient extends EventEmitter {
      * Connect to WhatsApp
      */
     async connect() {
+        // Check for stale "connecting" state (stuck for more than configured timeout)
+        if (this.connectionState === "connecting") {
+            const elapsed = Date.now() - this.connectionStateTimestamp;
+            if (elapsed < this.options.stuckStateTimeout) {
+                this.logger.info(`Already connecting (${elapsed}ms), skipping connect() call`);
+                return;
+            }
+            else {
+                this.logger.warn(`Stuck in "connecting" state for ${elapsed}ms, forcing reconnect`);
+                this.updateConnectionState("disconnected");
+            }
+        }
+        // Don't reconnect if already connected
+        if (this.connectionState === "connected") {
+            this.logger.info("Already connected, skipping connect() call");
+            return;
+        }
         try {
             this.updateConnectionState("connecting");
+            // Load persisted stores from disk before connecting
+            // This ensures data is available even if Baileys history sync doesn't fire
+            // (Known Baileys v7 issue: history sync notification may be received but never processed)
+            this.loadLabelsFromFile();
+            this.loadContactsFromFile();
+            this.loadLidMappingsFromFile(); // Load LID mappings BEFORE chats for resolution
+            this.loadChatsFromFile();
+            this.loadMessagesFromFile();
             // Load auth state
             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();
             // Create socket
+            const debugMode = this.options.debug;
+            const logger = this.logger;
             this.socket = makeWASocket({
                 version,
                 logger: this.logger,
@@ -106,11 +189,18 @@ export class MiawClient extends EventEmitter {
                     creds: state.creds,
                     keys: makeCacheableSignalKeyStore(state.keys, this.logger),
                 },
-                browser: ["Miaw", "Chrome", "1.0.0"],
+                browser: Browsers.macOS("Desktop"), // Desktop for more history
                 generateHighQualityLinkPreview: true,
-                // Enable app state sync for labels and other features
-                syncFullHistory: false,
+                // Enable full history sync to populate stores
+                syncFullHistory: true,
                 fireInitQueries: true,
+                // Debug callback to see if history sync notifications are received
+                shouldSyncHistoryMessage: (msg) => {
+                    if (debugMode) {
+                        logger.debug(`[shouldSyncHistoryMessage] syncType: ${msg.syncType}`);
+                    }
+                    return true; // Always sync
+                },
             });
             // Register event handlers
             this.registerSocketEvents(saveCreds);
@@ -150,10 +240,25 @@ export class MiawClient extends EventEmitter {
                 this.updateConnectionState("connected");
                 this.emit("ready");
                 this.logger.info("Connected to WhatsApp");
-                // Sync app state to populate labels (WhatsApp Business)
-                // Labels are stored in the 'regular' app state collection
-                this.syncLabelsFromAppState().catch((error) => {
+                // Log store sizes after connection
+                if (this.options.debug) {
+                    this.logger.debug(`[ready] Stores: contacts=${this.contactsStore.size}, chats=${this.chatsStore.size}, messages=${this.messagesStore.size}`);
+                    // Also log after a delay to catch async updates
+                    setTimeout(() => {
+                        this.logger.debug(`[ready+5s] Stores: contacts=${this.contactsStore.size}, chats=${this.chatsStore.size}, messages=${this.messagesStore.size}`);
+                    }, 5000);
+                }
+                // Track the initial sync promise so fetchAllLabels can await it
+                // This ensures CLI commands that run immediately after connection
+                // will wait for the sync to complete before returning empty results
+                this.initialLabelSyncPromise = this.syncLabelsFromAppState()
+                    .then(() => {
+                    this.initialLabelSyncComplete = true;
+                    this.logger.debug("Initial label sync completed");
+                })
+                    .catch((error) => {
                     this.logger.warn("Failed to sync labels from app state:", error);
+                    this.initialLabelSyncComplete = true; // Mark complete even on error
                 });
             }
         });
@@ -162,24 +267,88 @@ export class MiawClient extends EventEmitter {
             await saveCreds();
             this.emit("session_saved");
         });
-        // Contact updates - build LID to JID mapping and populate contacts store
+        // LID mapping update - captures LID to PN (phone number) mappings
+        // This event is part of Baileys v7 LID privacy feature
+        // Note: This event is WIP and may not always fire
+        this.socket.ev.on("lid-mapping.update", (mapping) => {
+            this.addLidMapping(mapping.lid, mapping.pn, "BaileysEvent");
+        });
+        // Contact updates - build LID to JID mapping and update store
         this.socket.ev.on("contacts.upsert", (contacts) => {
+            if (this.options.debug) {
+                this.logger.debug(`[contacts.upsert] Received ${contacts.length} contacts`);
+                if (contacts.length > 0) {
+                    this.logger.debug(`[contacts.upsert] Sample: ${JSON.stringify(contacts[0])}`);
+                }
+            }
             this.updateLidToJidMapping(contacts);
             this.updateContactsStore(contacts);
         });
         this.socket.ev.on("contacts.update", (contacts) => {
+            if (this.options.debug) {
+                this.logger.debug(`[contacts.update] Received ${contacts.length} contact updates`);
+                if (contacts.length > 0) {
+                    this.logger.debug(`[contacts.update] Sample: ${JSON.stringify(contacts[0])}`);
+                }
+            }
             this.updateLidToJidMapping(contacts);
             this.updateContactsStore(contacts);
         });
-        // Chat updates - extract LID mappings from chat data and populate chats store
+        // Chat updates - extract LID mappings and update store
         this.socket.ev.on("chats.upsert", (chats) => {
+            if (this.options.debug) {
+                this.logger.debug(`[chats.upsert] Received ${chats.length} chats`);
+                if (chats.length > 0) {
+                    this.logger.debug(`[chats.upsert] Sample: ${JSON.stringify(chats[0])}`);
+                }
+            }
             this.updateLidFromChats(chats);
             this.updateChatsStore(chats);
         });
         this.socket.ev.on("chats.update", (chats) => {
+            if (this.options.debug) {
+                this.logger.debug(`[chats.update] Received ${chats.length} chat updates`);
+            }
             this.updateLidFromChats(chats);
             this.updateChatsStore(chats);
         });
+        // History sync - populates contacts, chats, and messages from history
+        this.socket.ev.on("messaging-history.set", ({ chats, contacts, messages, 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(`Is Latest: ${isLatest}, SessionId: ${peerDataRequestSessionId || 'none'}`);
+                this.logger.debug("============================================\n");
+            }
+            // Build LID mappings FIRST (before store population)
+            this.updateLidToJidMapping(contacts);
+            this.updateLidFromChats(chats);
+            // Update contacts from history
+            this.updateContactsStore(contacts);
+            // Update chats from history
+            this.updateChatsStore(chats);
+            // Update messages from history
+            // Baileys v7: messages is a flat WAMessage[] array (not nested)
+            for (const msg of messages) {
+                this.addMessageToStore(msg);
+            }
+            // Check for pending loadMoreMessages requests
+            if (peerDataRequestSessionId && this.pendingHistoryRequests.has(peerDataRequestSessionId)) {
+                const request = this.pendingHistoryRequests.get(peerDataRequestSessionId);
+                const newCount = (this.messagesStore.get(request.jid) || []).length;
+                const messagesLoaded = newCount - request.initialCount;
+                this.pendingHistoryRequests.delete(peerDataRequestSessionId);
+                request.resolve({
+                    success: true,
+                    messagesLoaded,
+                    hasMore: !isLatest,
+                });
+                this.logger.debug(`History request ${peerDataRequestSessionId} completed: ${messagesLoaded} messages loaded`);
+            }
+            if (this.options.debug && isLatest) {
+                this.logger.debug(`✅ History sync complete. Stores: ${this.contactsStore.size} contacts, ${this.chatsStore.size} chats`);
+            }
+        });
         // Messages
         this.socket.ev.on("messages.upsert", async (m) => {
             if (m.type !== "notify")
@@ -187,9 +356,9 @@ export class MiawClient extends EventEmitter {
             for (const msg of m.messages) {
                 // Debug: Log raw Baileys message structure
                 if (this.options.debug) {
-                    console.log("\n========== RAW BAILEYS MESSAGE ==========");
-                    console.log(JSON.stringify(msg, null, 2));
-                    console.log("=========================================\n");
+                    this.logger.debug("\n========== RAW BAILEYS MESSAGE ==========");
+                    this.logger.debug(JSON.stringify(msg, null, 2));
+                    this.logger.debug("=========================================\n");
                 }
                 // Check for protocol messages (edits and deletes)
                 const protocolMessage = msg.message?.protocolMessage;
@@ -202,22 +371,17 @@ export class MiawClient extends EventEmitter {
                 // Note: senderLid may exist at runtime but isn't in Baileys v7 types
                 const msgKey = msg.key;
                 if (!msgKey.fromMe && msgKey.senderLid && msgKey.remoteJid) {
-                    const lid = msgKey.senderLid.endsWith("@lid")
-                        ? msgKey.senderLid
-                        : `${msgKey.senderLid}@lid`;
-                    this.lidToJidMap.set(lid, msgKey.remoteJid);
-                    if (this.options.debug) {
-                        console.log(`[LID Mapping] ${lid} -> ${msg.key.remoteJid}`);
-                    }
+                    this.addLidMapping(msgKey.senderLid, msgKey.remoteJid, "Message");
                 }
-                const normalized = MessageHandler.normalize({ messages: [msg] });
+                const normalized = MessageHandler.normalize({ messages: [msg], type: "notify" }, this.logger);
                 if (normalized) {
-                    // Store message in messagesStore (v0.9.0)
+                    // Store message in messagesStore
                     const chatJid = normalized.from;
                     if (!this.messagesStore.has(chatJid)) {
                         this.messagesStore.set(chatJid, []);
                     }
                     this.messagesStore.get(chatJid).push(normalized);
+                    this.saveMessagesToFile();
                     this.emit("message", normalized);
                 }
             }
@@ -234,9 +398,9 @@ export class MiawClient extends EventEmitter {
                     raw: { key, reaction },
                 };
                 if (this.options.debug) {
-                    console.log("\n========== REACTION ==========");
-                    console.log(JSON.stringify(reactionData, null, 2));
-                    console.log("==============================\n");
+                    this.logger.debug("\n========== REACTION ==========");
+                    this.logger.debug(JSON.stringify(reactionData, null, 2));
+                    this.logger.debug("==============================\n");
                 }
                 this.emit("message_reaction", reactionData);
             }
@@ -252,19 +416,20 @@ export class MiawClient extends EventEmitter {
                     lastSeen: presenceData.lastSeen,
                 };
                 if (this.options.debug) {
-                    console.log("\n========== PRESENCE UPDATE ==========");
-                    console.log(JSON.stringify(update, null, 2));
-                    console.log("=====================================\n");
+                    this.logger.debug("\n========== PRESENCE UPDATE ==========");
+                    this.logger.debug(JSON.stringify(update, null, 2));
+                    this.logger.debug("=====================================\n");
                 }
                 this.emit("presence", update);
             }
         });
         // Label updates (WhatsApp Business)
         this.socket.ev.on("labels.edit", (label) => {
+            this.labelEventCount++;
             if (this.options.debug) {
-                console.log("\n========== LABEL UPDATE ==========");
-                console.log(JSON.stringify(label, null, 2));
-                console.log("==================================\n");
+                this.logger.debug("\n========== LABEL UPDATE ==========");
+                this.logger.debug(JSON.stringify(label, null, 2));
+                this.logger.debug("==================================\n");
             }
             // Update label in store
             if (label.id) {
@@ -281,9 +446,54 @@ export class MiawClient extends EventEmitter {
                     };
                     this.labelsStore.set(label.id, labelData);
                 }
+                // Persist labels to disk after every update
+                // This ensures labels survive reconnections where resyncAppState returns only patches
+                this.saveLabelsToFile();
+            }
+        });
+        // Handle label-chat associations
+        this.socket.ev.on("labels.association", ({ association, type }) => {
+            // Only handle chat-level associations (not message-level)
+            if (association.type === "label_jid") {
+                const { labelId, chatId } = association;
+                if (type === "add") {
+                    if (!this.labelChatsStore.has(labelId)) {
+                        this.labelChatsStore.set(labelId, new Set());
+                    }
+                    this.labelChatsStore.get(labelId).add(chatId);
+                }
+                else if (type === "remove") {
+                    this.labelChatsStore.get(labelId)?.delete(chatId);
+                }
+                if (this.options.debug) {
+                    this.logger.debug(`Label association: ${type} chat ${chatId} ${type === "add" ? "to" : "from"} label ${labelId}`);
+                }
             }
         });
     }
+    /**
+     * Remove all socket event listeners
+     * Call this before closing socket to prevent stale event handlers
+     */
+    removeSocketEvents() {
+        if (!this.socket)
+            return;
+        this.logger.debug("Removing socket event listeners");
+        // Remove all event listeners
+        this.socket.ev.removeAllListeners("connection.update");
+        this.socket.ev.removeAllListeners("creds.update");
+        this.socket.ev.removeAllListeners("lid-mapping.update");
+        this.socket.ev.removeAllListeners("contacts.upsert");
+        this.socket.ev.removeAllListeners("contacts.update");
+        this.socket.ev.removeAllListeners("chats.upsert");
+        this.socket.ev.removeAllListeners("chats.update");
+        this.socket.ev.removeAllListeners("messaging-history.set");
+        this.socket.ev.removeAllListeners("messages.upsert");
+        this.socket.ev.removeAllListeners("messages.reaction");
+        this.socket.ev.removeAllListeners("presence.update");
+        this.socket.ev.removeAllListeners("labels.edit");
+        this.socket.ev.removeAllListeners("labels.association");
+    }
     /**
      * Handle protocol messages (edits, deletes)
      */
@@ -300,9 +510,9 @@ export class MiawClient extends EventEmitter {
                 raw: msg,
             };
             if (this.options.debug) {
-                console.log("\n========== MESSAGE DELETED ==========");
-                console.log(JSON.stringify(deletion, null, 2));
-                console.log("=====================================\n");
+                this.logger.debug("\n========== MESSAGE DELETED ==========");
+                this.logger.debug(JSON.stringify(deletion, null, 2));
+                this.logger.debug("=====================================\n");
             }
             this.emit("message_delete", deletion);
         }
@@ -323,13 +533,40 @@ export class MiawClient extends EventEmitter {
                 raw: msg,
             };
             if (this.options.debug) {
-                console.log("\n========== MESSAGE EDITED ==========");
-                console.log(JSON.stringify(edit, null, 2));
-                console.log("====================================\n");
+                this.logger.debug("\n========== MESSAGE EDITED ==========");
+                this.logger.debug(JSON.stringify(edit, null, 2));
+                this.logger.debug("====================================\n");
             }
             this.emit("message_edit", edit);
         }
     }
+    /**
+     * Add LID to JID mapping with normalized format and debug logging
+     * Centralized helper for all LID mapping operations
+     * @param lid - The LID (with or without @lid suffix)
+     * @param jid - The JID to map to (phone number)
+     * @param source - Source of the mapping for debug logs
+     */
+    addLidMapping(lid, jid, source) {
+        if (!lid || !jid) {
+            return;
+        }
+        // Normalize LID format (ensure it ends with @lid)
+        const normalizedLid = lid.endsWith("@lid") ? lid : `${lid}@lid`;
+        // Check if this is a new mapping
+        const existingJid = this.lidToJidMap.get(normalizedLid);
+        const isNew = existingJid !== jid;
+        // Store in our LRU cache
+        this.lidToJidMap.set(normalizedLid, jid);
+        if (this.options.debug) {
+            this.logger.debug(`[LID Mapping: ${source}] ${normalizedLid} -> ${jid}`);
+            this.logger.debug(`Total LID mappings: ${this.lidToJidMap.size}`);
+        }
+        // Persist to disk if this is a new mapping
+        if (isNew) {
+            this.saveLidMappingsToFile();
+        }
+    }
     /**
      * Update LID to JID mapping from contacts
      */
@@ -337,74 +574,14 @@ export class MiawClient extends EventEmitter {
         for (const contact of contacts) {
             // Contact has both lid and jid - create mapping
             if (contact.lid && contact.id && !contact.id.endsWith("@lid")) {
-                this.lidToJidMap.set(contact.lid, contact.id);
-                if (this.options.debug) {
-                    console.log(`[Contact LID Mapping] ${contact.lid} -> ${contact.id}`);
-                }
+                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.lidToJidMap.set(contact.id, contact.jid);
-                if (this.options.debug) {
-                    console.log(`[Contact LID Mapping] ${contact.id} -> ${contact.jid}`);
-                }
+                this.addLidMapping(contact.id, contact.jid, "Contact");
             }
         }
     }
-    /**
-     * Update in-memory contacts store (v0.9.0)
-     * @param contacts - Array of contact objects from Baileys
-     */
-    updateContactsStore(contacts) {
-        for (const contact of contacts) {
-            // Extract the JID (prefer non-lid IDs)
-            const jid = contact.id?.endsWith("@lid")
-                ? contact.jid || contact.id
-                : contact.id;
-            if (!jid)
-                continue;
-            // Extract phone number from JID
-            const phone = jid.endsWith("@s.whatsapp.net")
-                ? jid.replace("@s.whatsapp.net", "")
-                : undefined;
-            // Build contact info
-            const contactInfo = {
-                jid,
-                phone,
-                name: contact.name || contact.notify || undefined,
-            };
-            // Update store
-            this.contactsStore.set(jid, contactInfo);
-        }
-    }
-    /**
-     * Update in-memory chats store (v0.9.0)
-     * @param chats - Array of chat objects from Baileys
-     */
-    updateChatsStore(chats) {
-        for (const chat of chats) {
-            const jid = chat.id;
-            if (!jid)
-                continue;
-            // Extract phone number from JID
-            const phone = jid.endsWith("@s.whatsapp.net")
-                ? jid.replace("@s.whatsapp.net", "")
-                : undefined;
-            // Build chat info
-            const chatInfo = {
-                jid,
-                phone,
-                name: chat.name || undefined,
-                isGroup: jid.endsWith("@g.us"),
-                lastMessageTimestamp: chat.timestamp || undefined,
-                unreadCount: chat.unreadCount || undefined,
-                isArchived: chat.archived || false,
-                isPinned: chat.pinned || false,
-            };
-            // Update store
-            this.chatsStore.set(jid, chatInfo);
-        }
-    }
     /**
      * Update LID to JID mapping from chat data
      */
@@ -412,20 +589,11 @@ export class MiawClient extends EventEmitter {
         for (const chat of chats) {
             // Chat may have both id (could be phone or LID) and lidJid
             if (chat.lidJid && chat.id && !chat.id.endsWith("@lid")) {
-                const lid = chat.lidJid.endsWith("@lid")
-                    ? chat.lidJid
-                    : `${chat.lidJid}@lid`;
-                this.lidToJidMap.set(lid, chat.id);
-                if (this.options.debug) {
-                    console.log(`[Chat LID Mapping] ${lid} -> ${chat.id}`);
-                }
+                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.lidToJidMap.set(chat.id, chat.jid);
-                if (this.options.debug) {
-                    console.log(`[Chat LID Mapping] ${chat.id} -> ${chat.jid}`);
-                }
+                this.addLidMapping(chat.id, chat.jid, "Chat");
             }
         }
     }
@@ -469,12 +637,16 @@ export class MiawClient extends EventEmitter {
      * Get all registered LID mappings
      * Useful for persisting mappings to storage
      */
+    /**
+     * Get all LID to JID mappings (for debugging/monitoring)
+     * @returns Record of LID to JID mappings
+     */
     getLidMappings() {
         const result = {};
-        // Iterate through the cache
-        for (const [key, value] of this.lidToJidMap.cache) {
+        // Use proper encapsulated iteration method
+        this.lidToJidMap.forEach((value, key) => {
             result[key] = value;
-        }
+        });
         return result;
     }
     /**
@@ -489,6 +661,124 @@ export class MiawClient extends EventEmitter {
     clearLidCache() {
         this.lidToJidMap.clear();
     }
+    /**
+     * Update in-memory contacts store
+     * @param contacts - Array of contact objects from Baileys
+     *
+     * Baileys v7 Contact structure:
+     * - id: primary identifier (could be @lid or @s.whatsapp.net)
+     * - phoneNumber: phone JID (@s.whatsapp.net) when available
+     * - lid: LID JID (@lid) when available
+     * - name: contact name saved by user
+     * - notify: contact's own display name (push name)
+     * - verifiedName: verified business name
+     */
+    updateContactsStore(contacts) {
+        for (const contact of contacts) {
+            let jid = contact.id;
+            // Baileys v7: Use phoneNumber when id is LID
+            if (jid?.endsWith("@lid") && contact.phoneNumber) {
+                // Register LID mapping for future resolution
+                this.addLidMapping(contact.id, contact.phoneNumber, "Contact");
+                jid = contact.phoneNumber;
+            }
+            if (!jid)
+                continue;
+            // Extract phone number from JID
+            const phone = jid.endsWith("@s.whatsapp.net")
+                ? jid.replace("@s.whatsapp.net", "")
+                : undefined;
+            // Build contact info
+            const contactInfo = {
+                jid,
+                phone,
+                name: contact.name || contact.notify || contact.verifiedName || undefined,
+            };
+            // Update store with phone JID as primary key
+            this.contactsStore.set(jid, contactInfo);
+            // Also store by LID for lookup if available
+            if (contact.lid && contact.lid !== jid) {
+                this.contactsStore.set(contact.lid, contactInfo);
+            }
+            // Also store by original id if different (for LID contacts)
+            if (contact.id && contact.id !== jid) {
+                this.contactsStore.set(contact.id, contactInfo);
+            }
+        }
+        // Persist contacts to disk after every update
+        // This ensures contacts survive reconnections where history sync may not fire
+        if (contacts.length > 0) {
+            this.saveContactsToFile();
+        }
+    }
+    /**
+     * Update in-memory chats store
+     * @param chats - Array of chat objects from Baileys
+     *
+     * Baileys v7 Chat structure (proto.IConversation):
+     * - id: chat JID (can be @lid or @s.whatsapp.net or @g.us)
+     * - pnJid: phone number JID when id is LID
+     * - lidJid: LID JID when id is phone
+     * - name/displayName: chat display name
+     * - conversationTimestamp: last message timestamp
+     * - unreadCount, archived, pinned: chat state
+     */
+    updateChatsStore(chats) {
+        for (const chat of chats) {
+            let jid = chat.id;
+            if (!jid)
+                continue;
+            const originalId = jid;
+            // Handle LID chats - use pnJid (phone JID) when available
+            if (jid.endsWith("@lid") && chat.pnJid) {
+                this.addLidMapping(jid, chat.pnJid, "Chat");
+                jid = chat.pnJid;
+            }
+            // Extract phone number from JID
+            const phone = jid.endsWith("@s.whatsapp.net")
+                ? jid.replace("@s.whatsapp.net", "")
+                : undefined;
+            // Build chat info with proper field mapping for proto.IConversation
+            const chatInfo = {
+                jid,
+                phone,
+                name: chat.name || chat.displayName || undefined,
+                isGroup: jid.endsWith("@g.us"),
+                lastMessageTimestamp: chat.conversationTimestamp
+                    ? Number(chat.conversationTimestamp)
+                    : (chat.timestamp ? Number(chat.timestamp) : undefined),
+                unreadCount: chat.unreadCount || undefined,
+                isArchived: chat.archived || false,
+                isPinned: !!chat.pinned,
+            };
+            // Update store with resolved JID as primary key
+            this.chatsStore.set(jid, chatInfo);
+            // Also store by original LID if different (for lookup)
+            if (originalId !== jid) {
+                this.chatsStore.set(originalId, chatInfo);
+            }
+        }
+        // Persist chats to disk after every update
+        // This ensures chats survive reconnections where history sync may not fire
+        if (chats.length > 0) {
+            this.saveChatsToFile();
+        }
+    }
+    /**
+     * Add a message to the store
+     * @param msg - Baileys message object
+     */
+    addMessageToStore(msg) {
+        const normalized = MessageHandler.normalize({ messages: [msg], type: "notify" }, this.logger);
+        if (!normalized)
+            return;
+        const chatJid = normalized.from;
+        if (!this.messagesStore.has(chatJid)) {
+            this.messagesStore.set(chatJid, []);
+        }
+        this.messagesStore.get(chatJid).push(normalized);
+        this.saveMessagesToFile();
+    }
     /**
      * Clear session data for this instance.
      * This will delete all stored authentication credentials.
@@ -507,12 +797,15 @@ export class MiawClient extends EventEmitter {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
+        // Reset logout flag
+        this.loggingOut = false;
         // Clear LID cache
         this.lidToJidMap.clear();
         // Remove all event listeners
         this.removeAllListeners();
         // Close socket if connected
         if (this.socket) {
+            this.removeSocketEvents();
             this.socket.end(undefined);
             this.socket = null;
         }
@@ -528,6 +821,15 @@ export class MiawClient extends EventEmitter {
         this.logger.info("Disconnected:", reason, "Code:", statusCode);
         this.updateConnectionState("disconnected");
         this.emit("disconnected", reason);
+        // Reset label sync state so next connection will trigger fresh sync
+        this.initialLabelSyncPromise = null;
+        this.initialLabelSyncComplete = false;
+        // Don't reconnect if logging out
+        if (this.loggingOut) {
+            this.logger.info("Logout in progress, skipping auto-reconnect");
+            this.loggingOut = false; // Reset flag
+            return false;
+        }
         // Don't reconnect if logged out - clear session for fresh QR code on next connect
         if (statusCode === DisconnectReason.loggedOut) {
             this.logger.info("Logged out, clearing session for fresh authentication");
@@ -549,11 +851,11 @@ export class MiawClient extends EventEmitter {
             clearTimeout(this.reconnectTimer);
         }
         this.reconnectAttempts++;
-        this.updateConnectionState("reconnecting");
+        // 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.connect();
+            this.connect(); // This will set state to "connecting"
         }, this.options.reconnectDelay);
     }
     /**
@@ -561,7 +863,38 @@ export class MiawClient extends EventEmitter {
      */
     updateConnectionState(state) {
         this.connectionState = state;
+        this.connectionStateTimestamp = Date.now();
         this.emit("connection", state);
+        // Start watchdog for potentially stuck states
+        if (state === "connecting" || state === "reconnecting") {
+            this.startConnectionWatchdog();
+        }
+        else {
+            // Clear watchdog if we're no longer in a potentially stuck state
+            if (this.connectionWatchdogTimer) {
+                clearTimeout(this.connectionWatchdogTimer);
+                this.connectionWatchdogTimer = null;
+            }
+        }
+    }
+    /**
+     * Start watchdog timer to detect stuck connection states
+     */
+    startConnectionWatchdog() {
+        // Clear any existing watchdog
+        if (this.connectionWatchdogTimer) {
+            clearTimeout(this.connectionWatchdogTimer);
+        }
+        this.connectionWatchdogTimer = setTimeout(() => {
+            const currentState = this.connectionState;
+            const elapsed = Date.now() - this.connectionStateTimestamp;
+            // If stuck in connecting/reconnecting for too long, reset to disconnected
+            if ((currentState === "connecting" || currentState === "reconnecting") &&
+                elapsed >= this.options.stuckStateTimeout) {
+                this.logger.warn(`Connection stuck in "${currentState}" state for ${elapsed}ms, resetting`);
+                this.updateConnectionState("disconnected");
+            }
+        }, this.options.stuckStateTimeout);
     }
     /**
      * Send a text message
@@ -577,6 +910,25 @@ export class MiawClient extends EventEmitter {
             if (this.connectionState !== "connected") {
                 throw new Error(`Cannot send message. Connection state: ${this.connectionState}`);
             }
+            // Validate recipient (phone or JID)
+            const isJID = to.includes("@");
+            if (isJID) {
+                const jidValidation = validateJID(to);
+                if (!jidValidation.valid) {
+                    return { success: false, error: jidValidation.error };
+                }
+            }
+            else {
+                const phoneValidation = validatePhoneNumber(to);
+                if (!phoneValidation.valid) {
+                    return { success: false, error: phoneValidation.error };
+                }
+            }
+            // Validate message text
+            const textValidation = validateMessageText(text);
+            if (!textValidation.valid) {
+                return { success: false, error: textValidation.error };
+            }
             const jid = MessageHandler.formatPhoneToJid(to);
             // Build send options (for quoting/replying)
             const sendOptions = options?.quoted?.raw
@@ -914,6 +1266,86 @@ export class MiawClient extends EventEmitter {
             return null;
         }
     }
+    /**
+     * Get full contact profile including name, status, picture, and business info
+     * @param jidOrPhone - Contact's JID or phone number
+     * @returns ContactProfile or null if not found
+     */
+    async getContactProfile(jidOrPhone) {
+        try {
+            if (!this.socket) {
+                throw new Error("Not connected. Call connect() first.");
+            }
+            if (this.connectionState !== "connected") {
+                throw new Error(`Cannot get contact profile. Connection state: ${this.connectionState}`);
+            }
+            const jid = MessageHandler.formatPhoneToJid(jidOrPhone);
+            // Try to resolve LID JID to phone JID
+            const resolvedJid = this.resolveLidToJid(jid);
+            // Extract phone from resolved JID (or use getPhoneFromJid which handles LID resolution)
+            const phone = this.getPhoneFromJid(jid);
+            // Get name from contactsStore - try both original and resolved JID
+            let name;
+            const storedContact = this.contactsStore.get(jid) || this.contactsStore.get(resolvedJid);
+            if (storedContact?.name) {
+                name = storedContact.name;
+            }
+            // Fetch status
+            let status;
+            try {
+                const statusResult = await this.socket.fetchStatus(jid);
+                const firstResult = Array.isArray(statusResult)
+                    ? statusResult[0]
+                    : statusResult;
+                status = firstResult?.status?.status || undefined;
+            }
+            catch {
+                // Status might not be available
+            }
+            // Fetch profile picture URL
+            let pictureUrl;
+            try {
+                pictureUrl = (await this.socket.profilePictureUrl(jid)) || undefined;
+            }
+            catch {
+                // Profile picture might not be available (privacy settings)
+            }
+            // Check if business account and get business profile
+            let isBusiness = false;
+            let business;
+            try {
+                const businessProfile = await this.socket.getBusinessProfile(jid);
+                if (businessProfile) {
+                    isBusiness = true;
+                    business = {
+                        description: businessProfile.description || undefined,
+                        category: businessProfile.category || undefined,
+                        website: Array.isArray(businessProfile.website)
+                            ? businessProfile.website[0]
+                            : businessProfile.website,
+                        email: businessProfile.email || undefined,
+                        address: businessProfile.address || undefined,
+                    };
+                }
+            }
+            catch {
+                // Not a business account or not available
+            }
+            return {
+                jid,
+                phone,
+                name,
+                status,
+                pictureUrl,
+                isBusiness,
+                business,
+            };
+        }
+        catch (error) {
+            this.logger.error("Failed to get contact profile:", error);
+            return null;
+        }
+    }
     /**
      * Get business profile information
      * @param jidOrPhone - Contact's JID or phone number
@@ -976,12 +1408,26 @@ export class MiawClient extends EventEmitter {
     // ============================================
     /**
      * Fetch all contacts from the in-memory store
-     * Note: Contacts are populated via history sync and contact events
+     * Note: Contacts are populated via Baileys store history sync
      * @returns FetchAllContactsResult with list of contacts
      */
     async fetchAllContacts() {
         try {
-            const contacts = Array.from(this.contactsStore.values());
+            // Map contacts and resolve any @lid JIDs that weren't resolved earlier
+            const contacts = Array.from(this.contactsStore.values()).map(contact => {
+                // If jid is @lid and phone is missing, try to resolve using LID cache
+                if (contact.jid.endsWith("@lid") && !contact.phone) {
+                    const resolved = this.resolveLidToJid(contact.jid);
+                    if (resolved !== contact.jid && resolved.endsWith("@s.whatsapp.net")) {
+                        return {
+                            ...contact,
+                            jid: resolved,
+                            phone: resolved.replace("@s.whatsapp.net", ""),
+                        };
+                    }
+                }
+                return contact;
+            });
             return {
                 success: true,
                 contacts,
@@ -1059,6 +1505,8 @@ export class MiawClient extends EventEmitter {
             const phone = jid.endsWith("@s.whatsapp.net")
                 ? jid.replace("@s.whatsapp.net", "")
                 : undefined;
+            // Get display name from socket user
+            const name = this.socket.user?.name;
             // Fetch status
             let status;
             try {
@@ -1091,6 +1539,7 @@ export class MiawClient extends EventEmitter {
             return {
                 jid,
                 phone,
+                name,
                 status,
                 pictureUrl,
                 isBusiness,
@@ -1103,7 +1552,7 @@ export class MiawClient extends EventEmitter {
     }
     /**
      * Sync labels from WhatsApp app state
-     * This triggers a resync of the 'regular' collection which contains labels
+     * This triggers a resync of ALL app state collections to ensure labels are synced
      * Labels will be emitted via labels.edit events and stored in labelsStore
      */
     async syncLabelsFromAppState() {
@@ -1112,9 +1561,11 @@ export class MiawClient extends EventEmitter {
         }
         try {
             // resyncAppState is provided by Baileys to sync app state collections
-            // The 'regular' collection contains labels
+            // Sync ALL collections like Baileys does during initial sync
+            // Labels could be in any of: critical_block, critical_unblock_low, regular_high, regular_low, regular
             // The second parameter (false) means this is not an initial sync
-            await this.socket.resyncAppState(["regular"], false);
+            await this.socket.resyncAppState(["critical_block", "critical_unblock_low", "regular_high", "regular_low", "regular"], false);
+            this.lastLabelSyncTime = new Date();
             this.logger.info("App state sync completed, labels should be populated via labels.edit events");
         }
         catch (error) {
@@ -1128,13 +1579,36 @@ export class MiawClient extends EventEmitter {
      * @param forceSync - If true, force a resync from WhatsApp before returning labels
      * @returns FetchAllLabelsResult with list of labels
      */
-    async fetchAllLabels(forceSync = false) {
+    async fetchAllLabels(forceSync = false, syncTimeout = 2000) {
         try {
-            // Force resync if requested or if store is empty (first call)
+            // If initial sync is still in progress, wait for it first
+            // This handles the case where fetchAllLabels is called immediately after connection
+            // (e.g., CLI "get labels" right after connect)
+            if (this.initialLabelSyncPromise && !this.initialLabelSyncComplete) {
+                this.logger.debug("Waiting for initial label sync to complete...");
+                try {
+                    await Promise.race([
+                        this.initialLabelSyncPromise,
+                        new Promise((_, reject) => setTimeout(() => reject(new Error("Initial sync timeout")), 10000)),
+                    ]);
+                }
+                catch (error) {
+                    this.logger.debug("Initial sync wait timed out or failed:", error);
+                }
+            }
+            // Force resync if explicitly requested OR if store is empty (first call)
+            // This ensures labels are always available even if automatic sync hasn't completed
             if (forceSync || this.labelsStore.size === 0) {
                 await this.syncLabelsFromAppState();
-                // Give a brief moment for labels.edit events to be processed
-                await new Promise((resolve) => setTimeout(resolve, 500));
+                // Wait for buffered events to process
+                // Baileys uses ev.createBufferedFunction which processes events async
+                await new Promise((resolve) => setTimeout(resolve, syncTimeout));
+            }
+            // If store is still empty after sync, try loading from disk as fallback
+            // This handles reconnection scenarios where resyncAppState returns only patches
+            if (this.labelsStore.size === 0) {
+                this.logger.debug("Labels store still empty after sync, attempting to load from disk");
+                this.loadLabelsFromFile();
             }
             const labels = Array.from(this.labelsStore.values());
             return {
@@ -1150,9 +1624,366 @@ export class MiawClient extends EventEmitter {
             };
         }
     }
+    /**
+     * Get chats that have a specific label
+     * @param labelId - Label ID to query
+     * @returns Array of ChatInfo for chats with this label
+     */
+    getChatsByLabel(labelId) {
+        const chatJids = this.labelChatsStore.get(labelId);
+        if (!chatJids || chatJids.size === 0) {
+            return [];
+        }
+        const chats = [];
+        for (const jid of chatJids) {
+            const chat = this.chatsStore.get(jid);
+            if (chat) {
+                chats.push(chat);
+            }
+            else {
+                // Chat not in store, create minimal info
+                chats.push({
+                    jid,
+                    phone: jid.replace(/@s\.whatsapp\.net$/, ""),
+                    isGroup: jid.endsWith("@g.us"),
+                });
+            }
+        }
+        return chats;
+    }
+    /**
+     * Get the count of label events received
+     * Useful for debugging label sync issues
+     * @returns Number of labels.edit events received since connection
+     */
+    getLabelEventCount() {
+        return this.labelEventCount;
+    }
+    /**
+     * Get detailed information about the labels store
+     * Useful for debugging label sync issues
+     * @returns Object with store size, event count, and last sync time
+     */
+    getLabelsStoreInfo() {
+        return {
+            size: this.labelsStore.size,
+            eventCount: this.labelEventCount,
+            lastSyncTime: this.lastLabelSyncTime,
+        };
+    }
+    // =============================================================================
+    // Persistent Label Storage
+    // =============================================================================
+    /**
+     * Get the path to the labels storage file
+     */
+    getLabelsFilePath() {
+        return path.join(this.options.sessionPath, this.options.instanceId, "labels.json");
+    }
+    /**
+     * Save labels to disk for persistence across reconnections
+     * WhatsApp's resyncAppState only returns patches (not full snapshot) when version > 0,
+     * so we need to persist labels locally to survive reconnections
+     */
+    saveLabelsToFile() {
+        try {
+            const labelsPath = this.getLabelsFilePath();
+            const labelsDir = path.dirname(labelsPath);
+            // Ensure directory exists
+            if (!fs.existsSync(labelsDir)) {
+                fs.mkdirSync(labelsDir, { recursive: true });
+            }
+            // Convert Map to array for JSON serialization
+            const labelsData = Array.from(this.labelsStore.values());
+            fs.writeFileSync(labelsPath, JSON.stringify(labelsData, null, 2), "utf8");
+            this.logger.debug(`Saved ${labelsData.length} labels to ${labelsPath}`);
+        }
+        catch (error) {
+            this.logger.warn("Failed to save labels to file:", error);
+        }
+    }
+    /**
+     * Load labels from disk
+     * Called on connection to restore labels from previous session
+     */
+    loadLabelsFromFile() {
+        try {
+            const labelsPath = this.getLabelsFilePath();
+            if (!fs.existsSync(labelsPath)) {
+                this.logger.debug("No labels file found, starting with empty store");
+                return;
+            }
+            const labelsData = JSON.parse(fs.readFileSync(labelsPath, "utf8"));
+            if (Array.isArray(labelsData)) {
+                // Clear existing store and populate from file
+                this.labelsStore.clear();
+                for (const label of labelsData) {
+                    if (label.id) {
+                        this.labelsStore.set(label.id, label);
+                    }
+                }
+                this.logger.info(`Loaded ${this.labelsStore.size} labels from disk`);
+            }
+        }
+        catch (error) {
+            this.logger.warn("Failed to load labels from file:", error);
+        }
+    }
+    // ============================================
+    // CONTACTS PERSISTENCE
+    // ============================================
+    getContactsFilePath() {
+        return path.join(this.options.sessionPath, this.options.instanceId, "contacts.json");
+    }
+    /**
+     * Save contacts to disk for persistence across reconnections
+     * Baileys v7 history sync doesn't always fire, so we persist contacts locally
+     */
+    saveContactsToFile() {
+        try {
+            const contactsPath = this.getContactsFilePath();
+            const contactsDir = path.dirname(contactsPath);
+            // Ensure directory exists
+            if (!fs.existsSync(contactsDir)) {
+                fs.mkdirSync(contactsDir, { recursive: true });
+            }
+            // Convert Map to array for JSON serialization
+            // Deduplicate by jid (Map may have same contact under multiple keys)
+            const uniqueContacts = new Map();
+            for (const contact of this.contactsStore.values()) {
+                if (contact.jid && !uniqueContacts.has(contact.jid)) {
+                    uniqueContacts.set(contact.jid, contact);
+                }
+            }
+            const contactsData = Array.from(uniqueContacts.values());
+            fs.writeFileSync(contactsPath, JSON.stringify(contactsData, null, 2), "utf8");
+            this.logger.debug(`Saved ${contactsData.length} contacts to ${contactsPath}`);
+        }
+        catch (error) {
+            this.logger.warn("Failed to save contacts to file:", error);
+        }
+    }
+    /**
+     * Load contacts from disk
+     * Called on connection to restore contacts from previous session
+     */
+    loadContactsFromFile() {
+        try {
+            const contactsPath = this.getContactsFilePath();
+            if (!fs.existsSync(contactsPath)) {
+                this.logger.debug("No contacts file found, starting with empty store");
+                return;
+            }
+            const contactsData = JSON.parse(fs.readFileSync(contactsPath, "utf8"));
+            if (Array.isArray(contactsData)) {
+                // Clear existing store and populate from file
+                this.contactsStore.clear();
+                for (const contact of contactsData) {
+                    if (contact.jid) {
+                        this.contactsStore.set(contact.jid, contact);
+                    }
+                }
+                this.logger.info(`Loaded ${this.contactsStore.size} contacts from disk`);
+            }
+        }
+        catch (error) {
+            this.logger.warn("Failed to load contacts from file:", error);
+        }
+    }
+    // ============================================
+    // LID MAPPINGS PERSISTENCE
+    // ============================================
+    getLidMappingsFilePath() {
+        return path.join(this.options.sessionPath, this.options.instanceId, "lid-mappings.json");
+    }
+    /**
+     * Save LID-to-JID mappings to disk for persistence across reconnections
+     * This ensures @lid JIDs can be resolved to phone numbers even after restart
+     */
+    saveLidMappingsToFile() {
+        try {
+            const mappingsPath = this.getLidMappingsFilePath();
+            const mappingsDir = path.dirname(mappingsPath);
+            // Ensure directory exists
+            if (!fs.existsSync(mappingsDir)) {
+                fs.mkdirSync(mappingsDir, { recursive: true });
+            }
+            // Get all mappings from the LRU cache
+            const mappings = this.getLidMappings();
+            const count = Object.keys(mappings).length;
+            if (count > 0) {
+                fs.writeFileSync(mappingsPath, JSON.stringify(mappings, null, 2), "utf8");
+                this.logger.debug(`Saved ${count} LID mappings to ${mappingsPath}`);
+            }
+        }
+        catch (error) {
+            this.logger.warn("Failed to save LID mappings to file:", error);
+        }
+    }
+    /**
+     * Load LID-to-JID mappings from disk
+     * Called on connection BEFORE loading chats to ensure resolution works
+     */
+    loadLidMappingsFromFile() {
+        try {
+            const mappingsPath = this.getLidMappingsFilePath();
+            if (!fs.existsSync(mappingsPath)) {
+                this.logger.debug("No LID mappings file found, starting with empty cache");
+                return;
+            }
+            const mappingsData = JSON.parse(fs.readFileSync(mappingsPath, "utf8"));
+            if (typeof mappingsData === "object" && mappingsData !== null) {
+                let count = 0;
+                for (const [lid, jid] of Object.entries(mappingsData)) {
+                    if (typeof lid === "string" && typeof jid === "string") {
+                        this.lidToJidMap.set(lid, jid);
+                        count++;
+                    }
+                }
+                this.logger.info(`Loaded ${count} LID mappings from disk`);
+            }
+        }
+        catch (error) {
+            this.logger.warn("Failed to load LID mappings from file:", error);
+        }
+    }
+    // ============================================
+    // CHATS PERSISTENCE
+    // ============================================
+    getChatsFilePath() {
+        return path.join(this.options.sessionPath, this.options.instanceId, "chats.json");
+    }
+    /**
+     * Save chats to disk for persistence across reconnections
+     * Baileys v7 history sync doesn't always fire, so we persist chats locally
+     */
+    saveChatsToFile() {
+        try {
+            const chatsPath = this.getChatsFilePath();
+            const chatsDir = path.dirname(chatsPath);
+            // Ensure directory exists
+            if (!fs.existsSync(chatsDir)) {
+                fs.mkdirSync(chatsDir, { recursive: true });
+            }
+            // Convert Map to array for JSON serialization
+            // Deduplicate by jid (Map may have same chat under multiple keys)
+            const uniqueChats = new Map();
+            for (const chat of this.chatsStore.values()) {
+                if (chat.jid && !uniqueChats.has(chat.jid)) {
+                    uniqueChats.set(chat.jid, chat);
+                }
+            }
+            const chatsData = Array.from(uniqueChats.values());
+            fs.writeFileSync(chatsPath, JSON.stringify(chatsData, null, 2), "utf8");
+            this.logger.debug(`Saved ${chatsData.length} chats to ${chatsPath}`);
+        }
+        catch (error) {
+            this.logger.warn("Failed to save chats to file:", error);
+        }
+    }
+    /**
+     * Load chats from disk
+     * Called on connection to restore chats from previous session
+     */
+    loadChatsFromFile() {
+        try {
+            const chatsPath = this.getChatsFilePath();
+            if (!fs.existsSync(chatsPath)) {
+                this.logger.debug("No chats file found, starting with empty store");
+                return;
+            }
+            const chatsData = JSON.parse(fs.readFileSync(chatsPath, "utf8"));
+            if (Array.isArray(chatsData)) {
+                // Clear existing store and populate from file
+                this.chatsStore.clear();
+                for (const chat of chatsData) {
+                    if (chat.jid) {
+                        this.chatsStore.set(chat.jid, chat);
+                    }
+                }
+                this.logger.info(`Loaded ${this.chatsStore.size} chats from disk`);
+            }
+        }
+        catch (error) {
+            this.logger.warn("Failed to load chats from file:", error);
+        }
+    }
+    // ============================================
+    // MESSAGES PERSISTENCE
+    // ============================================
+    getMessagesFilePath() {
+        return path.join(this.options.sessionPath, this.options.instanceId, "messages.json");
+    }
+    /**
+     * Save messages to disk for persistence across reconnections
+     * Baileys v7 history sync doesn't always fire, so we persist messages locally
+     */
+    saveMessagesToFile() {
+        try {
+            const messagesPath = this.getMessagesFilePath();
+            const messagesDir = path.dirname(messagesPath);
+            // Ensure directory exists
+            if (!fs.existsSync(messagesDir)) {
+                fs.mkdirSync(messagesDir, { recursive: true });
+            }
+            // Convert Map to object for JSON serialization
+            // Structure: { "jid1": [msg1, msg2], "jid2": [msg3] }
+            const messagesData = {};
+            for (const [jid, messages] of this.messagesStore.entries()) {
+                messagesData[jid] = messages;
+            }
+            // Count total messages
+            const totalMessages = Array.from(this.messagesStore.values()).reduce((sum, msgs) => sum + msgs.length, 0);
+            fs.writeFileSync(messagesPath, JSON.stringify(messagesData, null, 2), "utf8");
+            this.logger.debug(`Saved ${totalMessages} messages across ${this.messagesStore.size} chats to ${messagesPath}`);
+        }
+        catch (error) {
+            this.logger.warn("Failed to save messages to file:", error);
+        }
+    }
+    /**
+     * Load messages from disk
+     * Called on connection to restore messages from previous session
+     */
+    loadMessagesFromFile() {
+        try {
+            const messagesPath = this.getMessagesFilePath();
+            if (!fs.existsSync(messagesPath)) {
+                this.logger.debug("No messages file found, starting with empty store");
+                return;
+            }
+            const messagesData = JSON.parse(fs.readFileSync(messagesPath, "utf8"));
+            if (messagesData && typeof messagesData === "object") {
+                // Clear existing store and populate from file
+                this.messagesStore.clear();
+                let totalMessages = 0;
+                for (const [jid, messages] of Object.entries(messagesData)) {
+                    if (Array.isArray(messages)) {
+                        this.messagesStore.set(jid, messages);
+                        totalMessages += messages.length;
+                    }
+                }
+                this.logger.info(`Loaded ${totalMessages} messages across ${this.messagesStore.size} chats from disk`);
+            }
+        }
+        catch (error) {
+            this.logger.warn("Failed to load messages from file:", error);
+        }
+    }
+    /**
+     * Get message counts for all chats
+     * @returns Map of JID to message count
+     */
+    getMessageCounts() {
+        const counts = new Map();
+        for (const [jid, messages] of this.messagesStore.entries()) {
+            counts.set(jid, messages.length);
+        }
+        return counts;
+    }
     /**
      * Get chat messages from the in-memory store
-     * Note: Messages are populated via messages.upsert events
+     * Note: Messages are populated via Baileys store history sync
      * @param jidOrPhone - Chat JID or phone number
      * @returns FetchChatMessagesResult with list of messages
      */
@@ -1173,14 +2004,104 @@ export class MiawClient extends EventEmitter {
             };
         }
     }
+    /**
+     * Load more (older) messages for a specific chat
+     * Uses Baileys fetchMessageHistory to fetch earlier messages
+     * @param jidOrPhone - Chat JID or phone number
+     * @param count - Number of messages to fetch (max 50)
+     * @param timeoutMs - Timeout in milliseconds (default 30000)
+     * @returns Result with number of messages loaded and whether more are available
+     */
+    async loadMoreMessages(jidOrPhone, count = 50, timeoutMs = 30000) {
+        try {
+            if (!this.socket) {
+                return { success: false, error: "Not connected. Call connect() first." };
+            }
+            if (this.connectionState !== "connected") {
+                return { success: false, error: `Cannot load messages. Connection state: ${this.connectionState}` };
+            }
+            const jid = MessageHandler.formatPhoneToJid(jidOrPhone);
+            const messages = this.messagesStore.get(jid) || [];
+            if (messages.length === 0) {
+                return { success: false, error: "No messages in store to paginate from. Send or receive a message first." };
+            }
+            // Find the oldest message (messages are stored newest first after history sync)
+            // We need the raw Baileys message for the key and timestamp
+            let oldestMessage = null;
+            let oldestTimestamp = Infinity;
+            for (const msg of messages) {
+                if (msg.timestamp < oldestTimestamp) {
+                    oldestTimestamp = msg.timestamp;
+                    oldestMessage = msg;
+                }
+            }
+            if (!oldestMessage || !oldestMessage.raw) {
+                return { success: false, error: "Cannot find message with raw data for pagination cursor." };
+            }
+            const rawMsg = oldestMessage.raw;
+            const msgKey = rawMsg.key;
+            const msgTimestamp = rawMsg.messageTimestamp;
+            if (!msgKey || !msgTimestamp) {
+                return { success: false, error: "Message missing key or timestamp for pagination." };
+            }
+            // Clamp count to max 50
+            const fetchCount = Math.min(count, 50);
+            const initialCount = messages.length;
+            this.logger.debug(`Fetching ${fetchCount} older messages for ${jid} (current: ${initialCount})`);
+            // Call Baileys fetchMessageHistory
+            const sessionId = await this.socket.fetchMessageHistory(fetchCount, msgKey, typeof msgTimestamp === 'number' ? msgTimestamp * 1000 : Number(msgTimestamp) * 1000);
+            this.logger.debug(`History fetch initiated with sessionId: ${sessionId}`);
+            // Create a Promise that will be resolved when the history arrives
+            return new Promise((resolve) => {
+                // Set up timeout
+                const timeout = setTimeout(() => {
+                    this.pendingHistoryRequests.delete(sessionId);
+                    resolve({
+                        success: false,
+                        error: `Timeout waiting for history (${timeoutMs}ms)`,
+                    });
+                }, timeoutMs);
+                // Store the pending request
+                this.pendingHistoryRequests.set(sessionId, {
+                    jid,
+                    initialCount,
+                    resolve: (result) => {
+                        clearTimeout(timeout);
+                        resolve(result);
+                    },
+                });
+            });
+        }
+        catch (error) {
+            this.logger.error("Failed to load more messages:", error);
+            return {
+                success: false,
+                error: error.message,
+            };
+        }
+    }
     /**
      * Fetch all chats from the in-memory store
-     * Note: Chats are populated via history sync and chat events
+     * Note: Chats are populated via Baileys store history sync
      * @returns FetchAllChatsResult with list of chats
      */
     async fetchAllChats() {
         try {
-            const chats = Array.from(this.chatsStore.values());
+            // Map chats and resolve any @lid JIDs that weren't resolved earlier
+            const chats = Array.from(this.chatsStore.values()).map(chat => {
+                // If jid is @lid and phone is missing, try to resolve using LID cache
+                if (chat.jid.endsWith("@lid") && !chat.phone) {
+                    const resolved = this.resolveLidToJid(chat.jid);
+                    if (resolved !== chat.jid && resolved.endsWith("@s.whatsapp.net")) {
+                        return {
+                            ...chat,
+                            jid: resolved,
+                            phone: resolved.replace("@s.whatsapp.net", ""),
+                        };
+                    }
+                }
+                return chat;
+            });
             return {
                 success: true,
                 chats,
@@ -1607,6 +2528,16 @@ export class MiawClient extends EventEmitter {
             if (this.connectionState !== "connected") {
                 throw new Error(`Cannot create group. Connection state: ${this.connectionState}`);
             }
+            // Validate group name
+            const nameValidation = validateGroupName(name);
+            if (!nameValidation.valid) {
+                return { success: false, error: nameValidation.error };
+            }
+            // Validate participant phone numbers
+            const phonesValidation = validatePhoneNumbers(participants);
+            if (!phonesValidation.valid) {
+                return { success: false, error: phonesValidation.error };
+            }
             // Format participant JIDs
             const formattedParticipants = participants.map((p) => MessageHandler.formatPhoneToJid(p));
             const metadata = await this.socket.groupCreate(name, formattedParticipants);
@@ -3184,7 +4115,9 @@ export class MiawClient extends EventEmitter {
         return mimeTypes[ext] || "application/octet-stream";
     }
     /**
-     * Disconnect from WhatsApp
+     * Disconnect from WhatsApp without logging out.
+     * The session is preserved and can be used to reconnect later without scanning QR again.
+     * Use logout() if you want to fully log out and require a new QR code.
      */
     async disconnect() {
         if (this.reconnectTimer) {
@@ -3192,11 +4125,127 @@ export class MiawClient extends EventEmitter {
             this.reconnectTimer = null;
         }
         if (this.socket) {
-            await this.socket.logout();
+            // Use end() instead of logout() to preserve session
+            // logout() would clear credentials and require new QR scan
+            this.socket.end(undefined);
             this.socket = null;
         }
+        // Cleanup console filter if it was enabled (reference counted)
+        if (!this.options.debug) {
+            disableConsoleFilter();
+        }
         this.updateConnectionState("disconnected");
-        this.logger.info("Disconnected");
+        this.logger.info("Disconnected (session preserved)");
+    }
+    /**
+     * Logout from WhatsApp and clear session.
+     * After calling this, the next connect() will require scanning a new QR code.
+     *
+     * This method:
+     * 1. Attempts to reconnect if disconnected (max 10 seconds)
+     * 2. Sends a logout request to WhatsApp servers using socket.query() to wait for acknowledgment
+     * 3. Clears local session files
+     * 4. Closes the connection
+     *
+     * Note: The socket.query() method waits for WhatsApp's acknowledgment before proceeding.
+     * This is more reliable than Baileys' native socket.logout() which uses sendNode() (fire-and-forget).
+     */
+    async logout() {
+        // Set flag to prevent auto-reconnect during logout
+        this.loggingOut = true;
+        // Clear any pending reconnection
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        // Get JID from auth state (if connected) or load from session file
+        let jid = this.authState?.creds?.me?.id;
+        // If not in memory, try loading from session file
+        if (!jid && this.authState) {
+            jid = this.authState.creds.me?.id;
+            this.logger.info(`Retrieved JID from auth state: ${jid ? 'JID found' : 'no JID'}`);
+        }
+        // If still not found, try initializing auth handler
+        if (!jid) {
+            try {
+                const { state } = await this.authHandler.initialize();
+                jid = state.creds.me?.id;
+                this.logger.info(`Loaded credentials from session file: ${jid ? 'JID found' : 'no JID'}`);
+            }
+            catch (error) {
+                this.logger.warn(`Failed to load credentials from session file: ${error}`);
+            }
+        }
+        if (!jid) {
+            this.logger.warn("No credentials found - cannot send logout request to server");
+            this.updateConnectionState("disconnected");
+            return;
+        }
+        // If disconnected, try to reconnect temporarily (only if we have credentials)
+        if ((!this.socket || this.connectionState !== "connected") && jid) {
+            this.logger.info("Not connected - attempting quick reconnect for logout");
+            try {
+                // Race between connect+wait and timeout to prevent hanging
+                await Promise.race([
+                    (async () => {
+                        await this.connect();
+                        await this.waitForState("connected", 5000);
+                    })(),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("Reconnect timeout")), 5000))
+                ]);
+                this.logger.info("Reconnected successfully for logout");
+            }
+            catch (error) {
+                this.logger.warn(`Quick reconnect failed: ${error instanceof Error ? error.message : error}`);
+                // Continue with local cleanup even if reconnect fails
+            }
+        }
+        // Send logout request using query() to wait for response
+        if (this.socket && this.connectionState === "connected") {
+            try {
+                this.logger.info("Sending logout request to WhatsApp server...");
+                // Use query() instead of sendNode() to wait for response
+                // This works around Baileys' socket.logout() using sendNode() which
+                // closes the connection before WhatsApp can process the request
+                // Note: socket.query() auto-generates the 'id' attribute if not provided
+                await this.socket.query({
+                    tag: 'iq',
+                    attrs: {
+                        to: "s.whatsapp.net",
+                        type: 'set',
+                        xmlns: 'md'
+                    },
+                    content: [{
+                            tag: 'remove-companion-device',
+                            attrs: {
+                                jid,
+                                reason: 'user_initiated'
+                            }
+                        }]
+                });
+                this.logger.info("Logout request acknowledged by WhatsApp server");
+            }
+            catch (error) {
+                this.logger.warn(`Logout request failed: ${error}`);
+                // Continue with cleanup even if logout request fails
+            }
+        }
+        // Clean up socket
+        if (this.socket) {
+            this.removeSocketEvents();
+            this.socket.end(undefined);
+            this.socket = null;
+        }
+        // Clear session files
+        this.authHandler.clearSession();
+        // Reset logout flag
+        this.loggingOut = false;
+        // Cleanup console filter if it was enabled (reference counted)
+        if (!this.options.debug) {
+            disableConsoleFilter();
+        }
+        this.updateConnectionState("disconnected");
+        this.logger.info("Logged out (session cleared)");
     }
     /**
      * Get current connection state
@@ -3204,6 +4253,32 @@ export class MiawClient extends EventEmitter {
     getConnectionState() {
         return this.connectionState;
     }
+    /**
+     * Wait for connection state to change to desired state
+     * @param desiredState - The state to wait for
+     * @param timeoutMs - Maximum time to wait in milliseconds
+     */
+    async waitForState(desiredState, timeoutMs = 10000) {
+        return new Promise((resolve, reject) => {
+            // Check if already in desired state
+            if (this.connectionState === desiredState) {
+                resolve();
+                return;
+            }
+            const timer = setTimeout(() => {
+                this.off("connection", handler);
+                reject(new Error(`Timeout waiting for connection state: ${desiredState}`));
+            }, timeoutMs);
+            const handler = (state) => {
+                if (state === desiredState) {
+                    clearTimeout(timer);
+                    this.off("connection", handler);
+                    resolve();
+                }
+            };
+            this.on("connection", handler);
+        });
+    }
     /**
      * Get instance ID
      */
@@ -3216,6 +4291,58 @@ export class MiawClient extends EventEmitter {
     isConnected() {
         return this.connectionState === "connected";
     }
+    /**
+     * Enable debug mode at runtime
+     * Enables verbose logging for debugging (includes libsignal session logs)
+     */
+    enableDebug() {
+        this.options.debug = true;
+        // Recreate logger with debug enabled
+        this.logger = createFilteredLogger(true);
+        this.options.logger = this.logger;
+        // Update socket logger if connected
+        if (this.socket) {
+            this.socket.logger = this.logger;
+        }
+        // Disable console filter to show libsignal logs in debug mode
+        disableConsoleFilter();
+        this.logger.info("Debug mode enabled");
+    }
+    /**
+     * Disable debug mode at runtime
+     * Disables verbose logging and suppresses libsignal session logs
+     */
+    disableDebug() {
+        this.logger.info("Debug mode disabled");
+        this.options.debug = false;
+        // Recreate logger with debug disabled
+        this.logger = createFilteredLogger(false);
+        this.options.logger = this.logger;
+        // Update socket logger if connected
+        if (this.socket) {
+            this.socket.logger = this.logger;
+        }
+        // Enable console filter to suppress libsignal session logs
+        enableConsoleFilter();
+    }
+    /**
+     * Check if debug mode is enabled
+     */
+    isDebugEnabled() {
+        return this.options.debug;
+    }
+    /**
+     * Set debug mode
+     * @param enabled - Whether to enable debug mode
+     */
+    setDebug(enabled) {
+        if (enabled) {
+            this.enableDebug();
+        }
+        else {
+            this.disableDebug();
+        }
+    }
     // TypeScript event emitter type safety
     on(event, listener) {
         return super.on(event, listener);