miaw-core 1.2.6 → 1.6.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, 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";
@@ -9,6 +9,7 @@ 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";
+import { createProxyAgents, validateProxyConfig, } from "../utils/proxy-agent.js";
 /**
  * LRU Cache for LID to JID mappings
  * Prevents unbounded memory growth while maintaining frequently used mappings
@@ -131,6 +132,11 @@ 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,
         };
         // Use the initialized logger
         this.logger = logger;
@@ -179,6 +185,8 @@ export class MiawClient extends EventEmitter {
             this.authState = { creds: state.creds };
             // Get latest Baileys version
             const { version } = await fetchLatestBaileysVersion();
+            // Resolve proxy agents if configured
+            const proxyAgents = await this.resolveProxyAgents();
             // Create socket
             const debugMode = this.options.debug;
             const logger = this.logger;
@@ -192,6 +200,9 @@ export class MiawClient extends EventEmitter {
                 },
                 browser: Browsers.macOS("Desktop"), // Desktop for more history
                 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 +213,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 +232,77 @@ export class MiawClient extends EventEmitter {
             }
         }
     }
+    /**
+     * 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 +312,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 +402,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 +458,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 +493,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 +542,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 +641,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 +699,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 +735,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 +817,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 +849,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 +917,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 +1107,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;
@@ -964,7 +1285,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 +1324,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 +1419,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 +1484,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)