miaw-core 1.2.5 → 1.6.0

package/docs/BAILEYS_VS_MIAW_COMPARISON.md

@@ -1,8 +1,8 @@
 # Baileys vs Miaw Core - Comprehensive Feature Comparison
 
-**Last Updated:** January 2, 2026  
-**Baileys Version:** 7.0.0-rc.9  
-**Miaw Core Version:** 1.1.0
+**Last Updated:** June 26, 2026  
+**Baileys Version:** 7.0.0-rc13  
+**Miaw Core Version:** 1.6.0
 
 ## Overview
 
@@ -42,7 +42,7 @@ This document provides a comprehensive comparison between [Baileys](https://gith
 | Feature                                  | Baileys | Miaw Core | Notes                                 |
 | ---------------------------------------- | ------- | --------- | ------------------------------------- |
 | **QR Code Authentication**               | ✅      | ✅        | Miaw emits `qr` event                 |
-| **Pairing Code (Phone Number)**          | ✅      | ❌        | Request pairing code via phone number |
+| **Pairing Code (Phone Number)**          | ✅      | ✅        | `usePairingCode` + `phoneNumber` (v1.6.0) |
 | **Session Persistence (Multi-file)**     | ✅      | ✅        | `AuthHandler` manages automatically   |
 | **Session Persistence (Single-file)**    | ✅      | ❌        | Multi-file only in Miaw               |
 | **Session Persistence (External Store)** | ✅      | ❌        | Redis, MongoDB, etc.                  |
@@ -53,7 +53,7 @@ This document provides a comprehensive comparison between [Baileys](https://gith
 | **Multiple Instances**                   | ✅      | ✅        | Full support in both                  |
 | **Browser Config**                       | ✅      | 🔶        | Fixed browser config in Miaw          |
 | **Custom Logger**                        | ✅      | ✅        | Pino-based in both                    |
-| **Proxy Support**                        | ✅      | ❌        | HTTP/SOCKS proxy                      |
+| **Proxy Support**                        | ✅      | ✅        | HTTP/SOCKS via `proxyUrl` config (v1.3.0) |
 | **WebSocket Options**                    | ✅      | ❌        | Custom WS configuration               |
 
 ---
@@ -66,7 +66,7 @@ This document provides a comprehensive comparison between [Baileys](https://gith
 | -------------------------- | ------- | --------- | -------------------------------------- |
 | **Send Text**              | ✅      | ✅        | `sendText()`                           |
 | **Send with Quote/Reply**  | ✅      | ✅        | `options.quoted`                       |
-| **Send with Mentions**     | ✅      | ❌        | `@mentions` in text                    |
+| **Send with Mentions**     | ✅      | ✅        | `mentions` option (v1.6.0)             |
 | **Send with Link Preview** | ✅      | 🔶        | Auto-generated in Baileys              |
 | **Send Extended Text**     | ✅      | ❌        | Bold, italic, strikethrough, monospace |
 
@@ -80,7 +80,7 @@ This document provides a comprehensive comparison between [Baileys](https://gith
 | **Send Voice Note (PTT)**   | ✅      | ✅        | `options.ptt: true`         |
 | **Send Video Note (PTV)**   | ✅      | ✅        | `options.ptv: true`         |
 | **Send Document**           | ✅      | ✅        | `sendDocument()`            |
-| **Send Sticker**            | ✅      | ❌        | WebP sticker messages       |
+| **Send Sticker**            | ✅      | ✅        | `sendSticker()` (v1.6.0)    |
 | **Send GIF**                | ✅      | ✅        | `options.gifPlayback: true` |
 | **View Once (Image/Video)** | ✅      | ✅        | `options.viewOnce: true`    |
 | **Media from URL**          | ✅      | ✅        | Pass URL string             |
@@ -92,11 +92,11 @@ This document provides a comprehensive comparison between [Baileys](https://gith
 
 | Feature                    | Baileys | Miaw Core | Notes                                  |
 | -------------------------- | ------- | --------- | -------------------------------------- |
-| **Send Location**          | ✅      | ❌        | Latitude/longitude                     |
+| **Send Location**          | ✅      | ✅        | `sendLocation()` (v1.6.0)              |
 | **Send Live Location**     | ✅      | ❌        | Live location sharing                  |
-| **Send Contact (vCard)**   | ✅      | ❌        | Contact cards                          |
-| **Send Multiple Contacts** | ✅      | ❌        | Multiple vCards                        |
-| **Send Poll**              | ✅      | ❌        | Poll messages                          |
+| **Send Contact (vCard)**   | ✅      | ✅        | `sendContact()` (v1.6.0)               |
+| **Send Multiple Contacts** | ✅      | ✅        | `sendContact()` array (v1.6.0)         |
+| **Send Poll**              | ✅      | ✅        | `sendPoll()` (v1.6.0)                  |
 | **Send Product**           | ✅      | ❌        | Product message                        |
 | **Send Event**             | ✅      | ❌        | Event/calendar messages                |
 | **Send Group Invite**      | ✅      | ❌        | Group invite message                   |
@@ -130,7 +130,7 @@ This document provides a comprehensive comparison between [Baileys](https://gith
 | **Message Delete Event**     | ✅      | ✅        | `message_delete` event             |
 | **Message Reaction Event**   | ✅      | ✅        | `message_reaction` event           |
 | **History Sync**             | ✅      | 🔶        | Chats/contacts synced to stores    |
-| **Poll Updates**             | ✅      | ❌        | Poll vote events                   |
+| **Poll Updates**             | ✅      | ✅        | `poll_vote` event (v1.6.0)         |
 | **Receipt Events**           | ✅      | ❌        | Delivery/read receipts             |
 | **Call Events**              | ✅      | ❌        | Incoming/outgoing calls            |
 | **Label Association Events** | ✅      | ❌        | Label add/remove events            |
@@ -183,7 +183,7 @@ This document provides a comprehensive comparison between [Baileys](https://gith
 | **Delete Chat**           | ✅      | ❌        | Delete entire chat        |
 | **Clear Chat**            | ✅      | ❌        | Clear all messages        |
 | **Disappearing Messages** | ✅      | ❌        | Set ephemeral timer       |
-| **Fetch Message History** | ✅      | ❌        | Load older messages       |
+| **Fetch Message History** | ✅      | ✅        | `loadMoreMessages()`      |
 | **Chat Modify**           | ✅      | 🔶        | Used internally           |
 
 ---
@@ -393,7 +393,7 @@ This document provides a comprehensive comparison between [Baileys](https://gith
 | --------------------------------- | ------- | --------- | ----------------------------------- |
 | **JID Encoding/Decoding**         | ✅      | 🔶        | `MessageHandler.formatPhoneToJid()` |
 | **Check JID Type**                | ✅      | 🔶        | Group/user/newsletter/etc.          |
-| **LID to JID Resolution**         | ✅      | ✅        | `resolveLidToJid()`                 |
+| **LID to JID Resolution**         | ✅      | ✅        | `resolveLidToJid()` + async/bulk/reverse via native store (v1.5.0) |
 | **Get Phone from JID**            | ✅      | ✅        | `getPhoneFromJid()`                 |
 | **Generate Message ID**           | ✅      | ❌        | Custom message IDs                  |
 | **Download Content from Message** | ✅      | ✅        | `downloadMedia()`                   |
@@ -421,11 +421,11 @@ This document provides a comprehensive comparison between [Baileys](https://gith
 
 | Category                  | Baileys Features | Miaw Core Implemented | Coverage |
 | ------------------------- | ---------------- | --------------------- | -------- |
-| **Connection & Auth**     | 14               | 10                    | 71%      |
-| **Sending Messages**      | 33               | 19                    | 58%      |
-| **Receiving & Events**    | 17               | 12                    | 71%      |
+| **Connection & Auth**     | 14               | 12                    | 86%      |
+| **Sending Messages**      | 33               | 25                    | 76%      |
+| **Receiving & Events**    | 17               | 13                    | 76%      |
 | **Media**                 | 4                | 2                     | 50%      |
-| **Chat Management**       | 11               | 5                     | 45%      |
+| **Chat Management**       | 11               | 6                     | 55%      |
 | **User & Contacts**       | 10               | 8                     | 80%      |
 | **Profile Management**    | 5                | 5                     | 100%     |
 | **Group Management**      | 18               | 14                    | 78%      |
@@ -439,7 +439,7 @@ This document provides a comprehensive comparison between [Baileys](https://gith
 | **Calls**                 | 5                | 0                     | 0%       |
 | **Utilities**             | 7                | 4                     | 57%      |
 | **Low-Level**             | 6                | 0                     | 0%       |
-| **TOTAL**                 | ~175             | ~110                  | ~63%     |
+| **TOTAL**                 | ~175             | ~120                  | ~69%     |
 
 ### What Miaw Core Focuses On
 
@@ -455,16 +455,17 @@ Miaw Core prioritizes the features that **90% of WhatsApp bots actually need**:
 
 ### What Miaw Core Doesn't Implement (Yet)
 
-These are deliberately excluded or planned for future:
+These are all backed by methods that exist in Baileys 7.0.0-rc13 and can be wrapped. Ordered by the prioritized backlog (see **[ROADMAP.md → Not-Yet-Implemented Baileys Features](./ROADMAP.md)**):
 
-1. ❌ **Privacy Settings** - Rarely needed by bots
-2. ❌ **Status/Stories** - Not common for automation
-3. ❌ **Communities** - Newer feature, less used
-4. ❌ **Calls** - WhatsApp calls via bots are rare
-5. ❌ **Polls** - Can be added if demand exists
-6. ❌ **Location Messages** - Can be added
-7. ❌ **Stickers** - Can be added
-8. ❌ **Interactive Messages** - Buttons/lists deprecated by WhatsApp
+1. ❌ **Chat Management** _(priority)_ - archive, pin, mute, clear, delete chat, star/unstar messages (`chatModify`)
+2. ❌ **Rich Messages** _(priority)_ - location, contact/vCard, poll (+ vote decoding), sticker, group-invite, pin-in-chat, `@mentions`
+3. ❌ **Privacy & Blocklist** - block/unblock, get blocklist, 10 privacy setters (`fetchBlocklist`, `updateBlockStatus`, `update*Privacy`)
+4. ❌ **Group Admin & Disappearing** - announce/restrict, join-approval, member-add mode, ephemeral (`groupSettingUpdate`, `groupRequest*`, `groupToggleEphemeral`)
+5. ❌ **Calls** - reject call, call events, call links (`rejectCall`, `createCallLink`)
+6. ❌ **Business Extras** - update business profile, cover photo, order details, quick replies
+7. ❌ **Status/Stories** - post to `status@broadcast`
+8. ❌ **Communities** - full `community*` layer (largest surface)
+9. 🔶 **Interactive Messages** - buttons/lists/templates deprecated by WhatsApp (low value)
 
 ---
 
@@ -519,4 +520,4 @@ These are deliberately excluded or planned for future:
 
 ---
 
-_This analysis was generated on January 2, 2026, based on Baileys v7.0.0-rc.9 and Miaw Core v1.1.0_
+_This analysis was last updated on June 27, 2026, based on Baileys v7.0.0-rc13 and Miaw Core v1.6.0._

package/docs/CLI.md

@@ -91,6 +91,7 @@ These flags work with any command:
 |------|-------------|---------|
 | `--instance-id <id>` | Specify instance ID | `default` |
 | `--session-path <path>` | Session directory path | `./sessions-cli` |
+| `--proxy <url>` | Proxy URL (http, https, socks4, socks5) | - |
 | `--json` | Output as JSON instead of tables | - |
 | `--debug` | Enable verbose logging | - |
 | `--help` | Show help message | - |
@@ -104,6 +105,12 @@ npx miaw-cli --instance-id my-bot get profile
 # Custom session path
 npx miaw-cli --session-path ./my-sessions get contacts
 
+# Connect through a SOCKS5 proxy
+npx miaw-cli --proxy socks5://proxy.example.com:1080 get groups
+
+# Connect through an HTTP proxy with auth
+npx miaw-cli --proxy http://user:pass@proxy.example.com:8080 send text 6281234567890 "Hello"
+
 # JSON output
 npx miaw-cli get groups --json
 

package/docs/LID_RESOLUTION.md

@@ -39,6 +39,34 @@ const phone = client.getPhoneFromJid("42877077966917@lid");
 client.registerLidMapping("42877077966917@lid", "6281234567890@s.whatsapp.net");
 ```
 
+#### Native-store resolution (Baileys rc13, v1.5.0+)
+
+The synchronous methods above are **cache-only**. For misses, these async
+methods additionally consult Baileys' native LID store
+(`signalRepository.lidMapping`), which can perform a server/USync-backed lookup
+and **back-fills** our cache on success. They require an active connection.
+
+```typescript
+// Async resolve — cache first, then the native store on a miss
+const jid = await client.resolveLidToJidAsync("42877077966917@lid");
+const phone = await client.getPhoneFromJidAsync("42877077966917@lid");
+
+// Bulk: cache hits served locally; misses sent in ONE native query
+const map = await client.resolveLidsToPhones([
+  "42877077966917@lid",
+  "11111111111111@lid",
+]);
+// => { "42877077966917@lid": "6281234567890", "11111111111111@lid": null }
+
+// Reverse: phone number -> LID (also seeds the local cache)
+const lid = await client.getLidForPhone("6281234567890");
+// => "42877077966917@lid" or null
+```
+
+> Inbound messages already use this fallback automatically: if a sender's
+> `@lid` is not yet cached, the native store is consulted while resolving
+> `senderPhone`.
+
 ## Sources of LID Mappings
 
 The LID cache is populated from multiple sources:
@@ -52,7 +80,25 @@ The LID cache is populated from multiple sources:
 | `contacts.update` | Contact updates with LID changes |
 | `chats.upsert` | New chats with LID information |
 | `chats.update` | Chat updates with LID changes |
-| `messages.upsert` | Message sender LID mappings |
+| `messages.upsert` | Message sender LID mappings (from the rc13 key alt fields — see below) |
+
+#### Baileys rc13 key/field changes
+
+Baileys v7 (rc10+) reworked how the phone (PN) and LID identifiers are carried.
+miaw-core reads the modern fields and falls back to the legacy ones for older
+session data:
+
+| Source object | Phone (PN) field | LID field |
+|---------------|------------------|-----------|
+| `Contact` | `phoneNumber` (replaces the removed `jid`) | `lid` |
+| `Chat` (`proto.IConversation`) | `pnJid` | `lidJid` |
+| Message `key` | `remoteJidAlt` (DMs) / `participantAlt` (groups), with `addressingMode` = `lid`\|`pn` | `remoteJid` / `participant` when those are `@lid` |
+
+For each inbound message, whichever side of the (`remoteJid`, `remoteJidAlt`) and
+(`participant`, `participantAlt`) pairs is a `@lid` is mapped to the `@s.whatsapp.net`
+side, so `senderPhone` resolves even for privacy-masked senders. The legacy
+`senderPn` / `participantPn` / `senderLid` key fields are no longer set by Baileys
+and are kept only as a fallback.
 
 ### 2. Persisted Storage
 
@@ -203,12 +249,18 @@ client.on("message", (message) => {
 
 ## Future Improvements
 
-Potential enhancements to LID resolution:
+**Implemented in v1.5.0** — miaw-core now adopts Baileys 7.0.0-rc13's native LID infrastructure:
+
+- ✅ **Native LID store** — `resolveLidToJidAsync()` / `getPhoneFromJidAsync()` fall back to `signalRepository.lidMapping.getPNForLID()` (server/USync-backed) on cache misses, back-filling the local cache. The inbound message path uses this automatically for `senderPhone`.
+- ✅ **`lidPnMappings` ingestion** — the dedicated LID↔PN array on `messaging-history.set` is consumed during history sync.
+- ✅ **Bulk + reverse resolution** — `resolveLidsToPhones([...])` (via `getPNsForLIDs`) and `getLidForPhone()` (via `getLIDForPN`).
+
+> `signalRepository.migrateSession(pn → lid)` is **not** wrapped: Baileys already calls it internally (`enableAutoSessionRecreation` defaults to `true`), so a manual wrapper would be redundant.
+
+Potential further enhancements:
 
-1. **Baileys PR**: Submit a pull request to Baileys to extract `phoneNumberToLidMappings` from HistorySync
-2. **Fallback lookup**: Implement a contact lookup API that resolves LIDs server-side
-3. **User notification**: Alert users when important contacts have unresolved LIDs
-4. **Bulk resolution**: API to resolve multiple LIDs in a single call
+1. **User notification**: Alert users when important contacts have unresolved LIDs
+2. **Proactive seeding**: Resolve all unresolved store LIDs via the native store on connect
 
 ## Related Files
 
@@ -224,3 +276,5 @@ Potential enhancements to LID resolution:
 | v1.1.0 | Added LID persistence to file |
 | v1.1.1 | Fixed CLI group participants LID display |
 | v1.1.2 | Fixed `getContactProfile()` LID resolution |
+| v1.4.1 | Baileys 7.0.0-rc13: read `Contact.phoneNumber` / `Chat.pnJid` and message-key `remoteJidAlt` / `participantAlt` (rc10 removed `Contact.jid`; rc13 no longer sets `senderPn` / `senderLid`) |
+| v1.5.0 | Adopt the rc13 native LID store: async/bulk/reverse resolvers (`resolveLidToJidAsync`, `getPhoneFromJidAsync`, `resolveLidsToPhones`, `getLidForPhone`) + `lidPnMappings` history ingestion |

package/docs/MIGRATION.md

@@ -4,6 +4,7 @@ This guide helps you migrate between versions of Miaw Core.
 
 ## Table of Contents
 
+- [v1.4.0 to v1.4.1](#v140-to-v141)
 - [v1.1.x to v1.2.0](#v11x-to-v120)
 - [v1.0.x to v1.1.0](#v10x-to-v110)
 - [v0.9.x to v1.0.0](#v09x-to-v100)
@@ -13,6 +14,40 @@ This guide helps you migrate between versions of Miaw Core.
 
 ---
 
+## v1.4.0 to v1.4.1
+
+**Status:** Released — 2026-06-26
+**Breaking Changes:** None ✅
+
+v1.4.1 upgrades the Baileys dependency from `7.0.0-rc.9` to `7.0.0-rc13` (the latest
+release). It is a drop-in upgrade — no application code changes are required.
+
+### What changed
+
+- **Baileys `7.0.0-rc.9` → `7.0.0-rc13`** (pinned exactly). Brings security fixes
+  (GHSA-qvv5-jq5g-4cgg, a protocolMessage parse-regression fix), performance and
+  stability work, and libsignal published to the npm registry.
+- **LID → phone resolution updated for the rc10+ field changes.** Baileys rc10
+  removed `Contact.jid` (now `Contact.phoneNumber`) and rc13 stopped setting
+  `senderPn` / `participantPn` / `senderLid` on message keys (now `remoteJidAlt` /
+  `participantAlt` + `addressingMode`). miaw-core reads the modern fields, so
+  `senderPhone` keeps resolving for privacy-masked (`@lid`) senders. See
+  [LID_RESOLUTION.md](./LID_RESOLUTION.md).
+
+### Do I need to change anything?
+
+No. The public API is unchanged, and persisted `lid-mappings.json` files remain
+compatible.
+
+### Known issue
+
+- Newsletter **creation** may return `success` with an empty `newsletterId` on rc13:
+  Baileys currently fails to parse the create response (`invalid mex newsletter
+  notification content`) even though the newsletter is created server-side. Tracked
+  upstream.
+
+---
+
 ## v1.1.x to v1.2.0
 
 **Status:** Code Quality Release (TBD)
@@ -466,9 +501,10 @@ If you encounter issues during migration:
 
 ## Version Compatibility
 
-| Miaw Core | Node.js  | Baileys | Status               |
-| --------- | -------- | ------- | -------------------- |
-| 1.0.0     | >=18.0.0 | 6.7.21+ | Stable (Coming Soon) |
+| Miaw Core | Node.js  | Baileys    | Status               |
+| --------- | -------- | ---------- | -------------------- |
+| 1.4.1     | >=18.0.0 | 7.0.0-rc13 | Stable               |
+| 1.0.0     | >=18.0.0 | 6.7.21+    | Stable (Coming Soon) |
 | 0.9.x     | >=18.0.0 | 6.7.21+ | Stable               |
 | 0.8.x     | >=18.0.0 | 6.7.21+ | Stable               |
 | 0.7.x     | >=18.0.0 | 6.7.21+ | Stable               |

package/docs/TEST_COVERAGE_ANALYSIS.md

@@ -1,11 +1,13 @@
 # MiawClient Test Coverage Analysis
 
-**Generated:** January 2, 2026  
+**Generated:** January 2, 2026 · **Last reviewed:** June 26, 2026 (Baileys 7.0.0-rc13, miaw-core v1.4.1)  
 **Source Files Analyzed:**
 
 - `src/client/MiawClient.ts` - Main client implementation
 - `tests/interactive-test.ts` - Interactive manual test suite
 
+> **Note:** The figures below reflect the 92-method API surface as of v1.4.1. The not-yet-implemented Baileys features tracked in [ROADMAP.md → Not-Yet-Implemented Baileys Features](./ROADMAP.md#not-yet-implemented-baileys-features-prioritized) (chat management, rich messages, privacy/blocklist, etc.) are **not** counted here and will need coverage as they land. A full regeneration of this table is out of scope for the rc13 docs refresh.
+
 ## Summary
 
 | Category           | Total Methods | Covered | Coverage |

package/docs/USAGE.md

@@ -26,6 +26,7 @@ This document covers all current capabilities of Miaw Core. It will be updated a
 - [Receiving Messages](#receiving-messages)
 - [Connection Management](#connection-management)
 - [Multiple Instances](#multiple-instances)
+- [Proxy Support](#proxy-support)
 - [Session Management](#session-management)
 - [Event Reference](#event-reference)
 - [Error Handling](#error-handling)
@@ -93,6 +94,10 @@ const client = new MiawClient({
   maxReconnectAttempts: 10, // Default: Infinity
   reconnectDelay: 5000, // Default: 3000 (ms)
 
+  // Proxy configuration (v1.3.0+)
+  proxy: "socks5://proxy.example.com:1080", // Proxy URL string
+  // or: proxy: { url: "http://proxy:8080", username: "user", password: "pass" }
+
   // Advanced timeout configurations
   stuckStateTimeout: 30000, // Default: 30000 (ms)
   qrGracePeriod: 30000, // Default: 30000 (ms)
@@ -115,6 +120,9 @@ const client = new MiawClient({
 | `qrGracePeriod`        | `number`  | `30000`        | QR code grace period                                |
 | `qrScanTimeout`        | `number`  | `60000`        | QR code scan timeout                                |
 | `connectionTimeout`    | `number`  | `120000`       | Connection establishment timeout                    |
+| `proxy`                | `string \| ProxyConfig` | _none_ | Proxy URL or config object (see [Proxy Support](#proxy-support)) |
+| `agent`                | `Agent`   | _none_         | Custom WebSocket agent (advanced, overrides proxy)  |
+| `fetchAgent`           | `unknown` | _none_         | Custom fetch dispatcher (advanced, overrides proxy) |
 
 ## Authentication
 
@@ -133,6 +141,26 @@ client.on("qr", (qr) => {
 });
 ```
 
+### Pairing Code Authentication (v1.6.0)
+
+Connect by entering an 8-character code in WhatsApp (Linked Devices → Link with
+phone number) instead of scanning a QR — ideal for headless/server deploys. QR
+emission is suppressed in this mode.
+
+```typescript
+const client = new MiawClient({
+  instanceId: "bot1",
+  usePairingCode: true,
+  phoneNumber: "6281234567890", // international format, no '+'
+});
+
+client.on("pairing_code", (code) => {
+  console.log("Enter this code in WhatsApp:", code); // e.g. "ABCD1234"
+});
+
+await client.connect();
+```
+
 ### Session Persistence
 
 After first authentication, the session is automatically saved and reused:
@@ -226,6 +254,46 @@ client.on("message", async (msg) => {
 });
 ```
 
+### Mentions (groups)
+
+```typescript
+// @mention members in a group (also reference them as @<number> in the text)
+await client.sendText(groupJid, "Hi @6281234567890!", {
+  mentions: ["6281234567890"],
+});
+```
+
+### Rich Message Types (v1.6.0)
+
+```typescript
+// Location
+await client.sendLocation("6281234567890", -6.2, 106.8, {
+  name: "Jakarta",
+  address: "Indonesia",
+});
+
+// Contact card(s) — pass one object or an array
+await client.sendContact("6281234567890", {
+  fullName: "John Doe",
+  phone: "6285555555555",
+  organization: "Acme Inc",
+});
+
+// Sticker (WebP — file path, URL, or Buffer)
+await client.sendSticker("6281234567890", "./sticker.webp");
+
+// Poll (>= 2 options; selectableCount defaults to 1)
+await client.sendPoll("6281234567890", "Lunch?", ["Pizza", "Sushi"], {
+  selectableCount: 1,
+});
+
+// Read poll votes (aggregated tally)
+client.on("poll_vote", (vote) => {
+  console.log(vote.pollMessageId, vote.results);
+  // results: [{ option: "Pizza", voters: ["...@s.whatsapp.net"] }, ...]
+});
+```
+
 ## Media Messages
 
 ### Send Image
@@ -1232,6 +1300,98 @@ bot1.on("message", (msg) => console.log("Bot 1:", msg.text));
 bot2.on("message", (msg) => console.log("Bot 2:", msg.text));
 ```
 
+## Proxy Support
+
+_Added in v1.3.0_
+
+Each MiawClient instance can connect through a proxy for IP rotation, geographic distribution, or privacy. Supports HTTP, HTTPS, SOCKS4, and SOCKS5 proxies.
+
+### Basic Proxy Usage
+
+```typescript
+import { MiawClient } from "miaw-core";
+
+// Using a proxy URL string
+const client = new MiawClient({
+  instanceId: "bot-1",
+  proxy: "socks5://proxy.example.com:1080",
+});
+
+// Using a ProxyConfig object (with separate auth)
+const client2 = new MiawClient({
+  instanceId: "bot-2",
+  proxy: {
+    url: "http://proxy.example.com:8080",
+    username: "user",
+    password: "pass",
+  },
+});
+
+await client.connect(); // Connects through the proxy
+```
+
+### Proxy Info
+
+```typescript
+// Get current proxy info (credentials masked)
+const info = client.getProxyInfo();
+// { url: "socks5://proxy.example.com:1080/", protocol: "socks5" }
+```
+
+### Multiple Instances with Different Proxies
+
+```typescript
+const instances = [
+  { id: "us-bot", proxy: "socks5://us-proxy.example.com:1080" },
+  { id: "eu-bot", proxy: "socks5://eu-proxy.example.com:1080" },
+  { id: "asia-bot", proxy: "http://asia-proxy.example.com:8080" },
+];
+
+for (const { id, proxy } of instances) {
+  const client = new MiawClient({
+    instanceId: id,
+    sessionPath: "./sessions",
+    proxy,
+  });
+  await client.connect();
+}
+```
+
+### Custom Agent (Advanced)
+
+For advanced use cases, you can pass your own agents directly instead of a proxy URL:
+
+```typescript
+import { HttpsProxyAgent } from "https-proxy-agent";
+
+const client = new MiawClient({
+  instanceId: "advanced-bot",
+  agent: new HttpsProxyAgent("http://proxy:8080"),    // WebSocket agent
+  fetchAgent: myCustomDispatcher,                      // undici Dispatcher for media
+});
+```
+
+### Proxy Validation
+
+```typescript
+import { validateProxyConfig } from "miaw-core";
+
+validateProxyConfig("socks5://proxy:1080");  // true
+validateProxyConfig("http://proxy:8080");    // true
+validateProxyConfig("ftp://invalid:21");     // false
+```
+
+### Supported Protocols
+
+| Protocol | WebSocket | Media Upload/Download |
+|----------|-----------|----------------------|
+| `http://`  | Yes | Yes |
+| `https://` | Yes | Yes |
+| `socks4://` | Yes | No (direct connection) |
+| `socks5://` | Yes | No (direct connection) |
+
+> **Note**: SOCKS proxies fully tunnel the WebSocket connection to WhatsApp. However, media uploads/downloads (which use Node.js `fetch()`) fall back to a direct connection when using SOCKS, because Node.js `fetch()` requires an undici-compatible dispatcher which doesn't support SOCKS natively. HTTP/HTTPS proxies work for both.
+
 ## Session Management
 
 ### Session Storage Location
@@ -1359,10 +1519,22 @@ client.on("message", (msg) => {
   console.log("Sender phone:", msg.senderPhone);
 });
 
-// Manual LID resolution
+// Manual LID resolution (synchronous, cache-only)
 const phoneJid = client.resolveLidToJid("123456@lid");
 const phone = client.getPhoneFromJid("123456@lid");
 
+// Async resolution — falls back to Baileys' native LID store on a cache miss
+// (server-backed, back-fills the cache). Requires an active connection.
+const jid = await client.resolveLidToJidAsync("123456@lid");
+const phone2 = await client.getPhoneFromJidAsync("123456@lid");
+
+// Bulk: resolve many LIDs in one native query (cache hits served locally)
+const map = await client.resolveLidsToPhones(["123456@lid", "789012@lid"]);
+// => { "123456@lid": "6281234567890", "789012@lid": null }
+
+// Reverse: phone number -> LID
+const lid = await client.getLidForPhone("6281234567890"); // "123456@lid" | null
+
 // Register LID mapping (useful for persistence)
 client.registerLidMapping("123456@lid", "6281234567890@s.whatsapp.net");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaw-core",
-  "version": "1.2.5",
+  "version": "1.6.0",
   "description": "Simplified WhatsApp API wrapper for Baileys - Multiple Instance of Awesome WhatsApp",
   "type": "module",
   "main": "dist/index.js",
@@ -14,20 +14,6 @@
   "bin": {
     "miaw-cli": "./bin/miaw-cli.ts"
   },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "lint": "eslint src tests examples bin",
-    "lint:fix": "eslint src tests examples bin --fix",
-    "prepublishOnly": "npm run build",
-    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
-    "test:watch": "NODE_OPTIONS='--experimental-vm-modules' jest --watch",
-    "test:coverage": "NODE_OPTIONS='--experimental-vm-modules' jest --coverage",
-    "test:cli": "NODE_OPTIONS='--experimental-vm-modules' jest --testPathPattern='tests/integration/cli' --runInBand --forceExit",
-    "test:manual": "tsx tests/interactive-test.ts",
-    "test:manual:build": "npm run build && node dist/tests/interactive-test.js",
-    "cli": "tsx bin/miaw-cli.ts"
-  },
   "keywords": [
     "whatsapp",
     "baileys",
@@ -43,10 +29,13 @@
   },
   "dependencies": {
     "@hapi/boom": "^10.0.1",
-    "@whiskeysockets/baileys": "^7.0.0-rc.9",
+    "@whiskeysockets/baileys": "7.0.0-rc13",
     "cli-table3": "^0.6.5",
+    "https-proxy-agent": "^8.0.0",
     "pino": "^8.19.0",
-    "qrcode-terminal": "^0.12.0"
+    "qrcode-terminal": "^0.12.0",
+    "socks-proxy-agent": "^9.0.0",
+    "undici": "^7.24.0"
   },
   "devDependencies": {
     "@babel/preset-env": "^7.28.5",
@@ -67,5 +56,18 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint src tests examples bin",
+    "lint:fix": "eslint src tests examples bin --fix",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "test:watch": "NODE_OPTIONS='--experimental-vm-modules' jest --watch",
+    "test:coverage": "NODE_OPTIONS='--experimental-vm-modules' jest --coverage",
+    "test:cli": "NODE_OPTIONS='--experimental-vm-modules' jest --testPathPattern='tests/integration/cli' --runInBand --forceExit",
+    "test:manual": "tsx tests/interactive-test.ts",
+    "test:manual:build": "npm run build && node dist/tests/interactive-test.js",
+    "cli": "tsx bin/miaw-cli.ts"
   }
-}
+}

package/sessions-cli/.cli_history

@@ -1,3 +1,8 @@
+instances
+ls
+instance ls
+instances
+devices
 get contacts --filter 22341
 get profile
 group participants 120363039902323086@g.us
@@ -272,3 +277,8 @@ group get profile
 group participants 120363039902323086@g.us
 get profile
 get contacts --filter 22341
+devices
+instances
+instance ls
+ls
+instances