@vanzxy/baileys 1.6.5 → 1.6.7

package/README.md

@@ -1,43 +1,156 @@
-# 🍃 @vanzxy/baileys
+<div align="center" id="top">
+
+<img src="https://capsule-render.vercel.app/api?type=waving&color=0:1d6a23,100:2ecc71&height=180&section=header&text=%40vanzxy%2Fbaileys&fontSize=42&fontColor=ffffff&animation=fadeIn&fontAlignY=38&desc=Next-generation%20Baileys%20fork%20—%20built%20different,%20built%20by%20Vanzxy&descAlignY=58&descSize=16" width="100%"/>
+
+<img src="https://files.catbox.moe/l72xji.svg" width="100%" alt="Sakura night banner"/>
+
+<p>
+  <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=18&pause=1200&color=2ECC71&center=true&vCenter=true&width=650&lines=Extended+interactive+messages+%26+native+flow;Status+tools+%2B+quality-of-life+fixes;Built+on+top+of+WhiskeySockets%2FBaileys" alt="Typing SVG" />
+</p>
+
+<p>
+<a href="https://www.npmjs.com/package/@vanzxy/baileys" target="_blank"><img src="https://img.shields.io/npm/v/@vanzxy/baileys?color=2ecc71&label=npm&style=for-the-badge" alt="npm version"/></a>
+<a href="https://www.npmjs.com/package/@vanzxy/baileys" target="_blank"><img src="https://img.shields.io/npm/dt/@vanzxy/baileys?color=3498db&style=for-the-badge" alt="npm downloads"/></a>
+<a href="https://github.com/vanzxysenpai/vanzxybaileys/stargazers" target="_blank"><img src="https://img.shields.io/github/stars/vanzxysenpai/vanzxybaileys?color=f1c40f&style=for-the-badge" alt="GitHub stars"/></a>
+<a href="https://github.com/vanzxysenpai/vanzxybaileys/issues" target="_blank"><img src="https://img.shields.io/github/issues/vanzxysenpai/vanzxybaileys?color=e74c3c&style=for-the-badge" alt="GitHub issues"/></a>
+</p>
+<p>
+<img src="https://img.shields.io/github/last-commit/vanzxysenpai/vanzxybaileys?color=9b59b6&style=flat-square" alt="Last commit"/>
+<img src="https://img.shields.io/github/commit-activity/m/vanzxysenpai/vanzxybaileys?color=1abc9c&style=flat-square" alt="Commit activity"/>
+<img src="https://img.shields.io/github/languages/code-size/vanzxysenpai/vanzxybaileys?color=e67e22&style=flat-square" alt="Code size"/>
+<img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square" alt="Node >=20"/>
+<img src="https://img.shields.io/badge/module-ESM-blue?style=flat-square" alt="ESM"/>
+<img src="https://img.shields.io/badge/types-included-blue?style=flat-square" alt="TypeScript types included"/>
+<img src="https://img.shields.io/badge/license-see%20NOTICE-lightgrey?style=flat-square" alt="License"/>
+</p>
+
+<p>
+<a href="#-why-vanzxybaileys">About</a> &#xa0;|&#xa0;
+<a href="#-comparison">Comparison</a> &#xa0;|&#xa0;
+<a href="#-features">Features</a> &#xa0;|&#xa0;
+<a href="#-installation">Installation</a> &#xa0;|&#xa0;
+<a href="#-quick-start">Quick Start</a> &#xa0;|&#xa0;
+<a href="#-usage-examples">Examples</a> &#xa0;|&#xa0;
+<a href="#-faq--troubleshooting">FAQ</a> &#xa0;|&#xa0;
+<a href="#-contributing">Contributing</a> &#xa0;|&#xa0;
+<a href="#-credits">Credits</a> &#xa0;|&#xa0;
+<a href="#-maintainer">Maintainer</a>
+</p>
+
+<details>
+<summary>📖 Full table of contents</summary>
+<br/>
+
+- [🍃 Why @vanzxy/baileys](#-why-vanzxybaileys)
+- [🆚 Comparison](#-comparison)
+- [🧰 Built With](#-built-with)
+- [🔥 Features](#-features)
+- [✨ Exclusive Vanzxy Enhancements](#-exclusive-vanzxy-enhancements)
+- [📦 Installation](#-installation)
+- [🚀 Quick Start](#-quick-start)
+- [🔐 Authentication](#-authentication)
+- [🗄️ Store Backends](#-store-backends)
+- [💡 Usage Examples](#-usage-examples)
+  - [Buttons & Native Flow](#buttons--native-flow)
+  - [Poll](#poll)
+  - [Carousel](#carousel)
+  - [AIRich — rich response cards](#airich--rich-response-cards)
+- [📞 Voice & Video Calls](#-voice--video-calls)
+- [🔎 User Sync Queries](#-user-sync-queries)
+- [🧩 Utility Modules](#-utility-modules)
+- [🛎️ System Notification Filter](#-system-notification-filter)
+- [🛠 Recommended Environment](#-recommended-environment)
+- [📘 TypeScript Support](#-typescript-support)
+- [📚 Fork Lineage](#-fork-lineage)
+- [❓ FAQ & Troubleshooting](#-faq--troubleshooting)
+- [🤝 Contributing](#-contributing)
+- [🙏 Credits](#-credits)
+- [💖 Support](#-support)
+- [👑 Maintainer](#-maintainer)
+- [⚠️ Disclaimer](#-disclaimer)
+- [📝 Patch Notes](#-v4-patch-notes)
+
+</details>
+
+</div>
 
-> Next-generation Baileys fork by **Vanzxy**.
-> Built for modern WhatsApp bot development with extended interactive messages, native flow enhancements, status tools, and quality-of-life improvements.
+---
+
+## 🍃 Why @vanzxy/baileys?
+
+This fork focuses on:
 
-![Version](https://img.shields.io/npm/v/@vanzxy/baileys)
-![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)
-![ESM](https://img.shields.io/badge/module-ESM-blue)
+| | |
+|---|---|
+| 🚀 | Better developer experience |
+| 🎯 | Extended native flow support |
+| 📢 | Advanced status & broadcast features |
+| 🧩 | More interactive message types |
+| ⚡ | Cleaner implementation for bot developers |
+| 🔧 | Extra utilities not available in standard Baileys forks |
+| 🗄️ | Multiple auth & store backends out of the box (file, SQLite, MongoDB, MySQL, PostgreSQL, Redis) |
+| 📞 | Experimental voice-call (VoIP) support |
 
 ---
 
-# ✨ Why @vanzxy/baileys?
+## 🆚 Comparison
 
-This fork focuses on:
+How `@vanzxy/baileys` stacks up against its own lineage and the wider Baileys fork ecosystem:
+
+| Capability | `@vanzxy/baileys` | `@itsliaaa/baileys` | `WhiskeySockets/Baileys` |
+|---|:---:|:---:|:---:|
+| Native Flow buttons (V1/V2/V3) | ✅ | ✅ | ⚠️ basic only |
+| Carousel messages | ✅ | ❌ | ❌ |
+| Rich response cards (AIRich) | ✅ | ❌ | ❌ |
+| Commerce flow (catalog/order/payment) | ✅ | ⚠️ partial | ❌ |
+| Voice calling (VoIP) | ✅ experimental | ❌ | ❌ |
+| Multi-backend store (SQL/Mongo/Redis) | ✅ | ⚠️ file/SQLite only | ⚠️ in-memory only |
+| Full `.d.ts` TypeScript definitions | ✅ | ⚠️ partial | ⚠️ partial |
+| User sync queries (WAUSync) | ✅ | ✅ | ✅ |
 
-- 🚀 Better developer experience
-- 🎯 Extended native flow support
-- 📢 Advanced status & broadcast features
-- 🧩 More interactive message types
-- ⚡ Cleaner implementation for bot developers
-- 🔧 Extra utilities not available in standard Baileys forks
+> Tabel ini menggambarkan fitur di level package, bukan benchmark performa. PR untuk memperbarui/mengoreksi tabel ini dipersilakan lewat [Contributing](#-contributing).
 
 ---
 
-# 🔥 Features
+## 🧰 Built With
+
+<p>
+<img src="https://img.shields.io/badge/node.js-%2343853D.svg?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js"/>
+<img src="https://img.shields.io/badge/javascript-%23323330.svg?style=for-the-badge&logo=javascript&logoColor=%23F7DF1E" alt="JavaScript"/>
+<img src="https://img.shields.io/badge/esm-%23F7DF1E.svg?style=for-the-badge&logo=javascript&logoColor=black" alt="ESM"/>
+<img src="https://img.shields.io/badge/websocket-%23000000.svg?style=for-the-badge&logo=socket.io&logoColor=white" alt="WebSocket"/>
+<img src="https://img.shields.io/badge/signal%20protocol-%233A76F0.svg?style=for-the-badge&logo=signal&logoColor=white" alt="Signal Protocol"/>
+<img src="https://img.shields.io/badge/protobuf-%23345?style=for-the-badge&logo=google&logoColor=white" alt="Protobuf"/>
+<img src="https://img.shields.io/badge/npm-%23CB3837.svg?style=for-the-badge&logo=npm&logoColor=white" alt="npm"/>
+</p>
+
+---
+
+## 🔥 Features
+
+<table>
+<tr>
+<th align="center">💬 Interactive Messages</th>
+<th align="center">🛒 Commerce & Business</th>
+<th align="center">🧩 Utility Features</th>
+</tr>
+<tr>
+<td valign="top">
 
-## Interactive Messages
 - Native Flow
-- Buttons
+- Buttons (V1 / V2 / V3)
 - Lists
 - Carousel Messages
-- Rich Response Messages
-- CTA Buttons
-- Reply Buttons
-- URL Buttons
+- Poll & Quiz Messages
+- Rich Response Messages (AIRich)
+- CTA / Reply / URL Buttons
 - Call Buttons
 - OTP Buttons
 - Authentication Buttons
 
-## Commerce & Business
+</td>
+<td valign="top">
+
 - Catalog Message
 - Order Details
 - Order Status
@@ -48,7 +161,9 @@ This fork focuses on:
 - Reorder
 - Cancel Order
 
-## Utility Features
+</td>
+<td valign="top">
+
 - Group Status Support
 - Mention All
 - Lottie Sticker Support
@@ -58,43 +173,108 @@ This fork focuses on:
 - Rich Formatting
 - Code Highlighting
 
+</td>
+</tr>
+</table>
+
+<table>
+<tr>
+<th align="center">🔐 Auth & Storage</th>
+<th align="center">📞 Realtime</th>
+<th align="center">🛠 Developer Tooling</th>
+</tr>
+<tr>
+<td valign="top">
+
+- Multi-file auth state
+- Single-file auth state
+- SQLite auth state
+- Cache-manager auth state
+- In-memory store
+- SQLite / MongoDB / MySQL /
+  PostgreSQL / Redis store adapters
+
+</td>
+<td valign="top">
+
+- Voice calling (VoIP, WASM engine)
+- User sync queries (WAUSync)
+- Presence / status / device lookup
+- Event buffer for high-volume bots
+
+</td>
+<td valign="top">
+
+- Full TypeScript definitions (`.d.ts`)
+- Anti-delete detection
+- Message search helpers
+- Auto-reply engine
+- Scheduling helpers
+- Message retry manager
+
+</td>
+</tr>
+</table>
+
 ---
 
-# 🌟 Exclusive Vanzxy Enhancements
+## ✨ Exclusive Vanzxy Enhancements
 
 ### Audio Group Status Fix
 Audio status uses a more compatible implementation to avoid unsupported-version errors on older WhatsApp clients.
 
+### AIRich — the rich-response message builder
+A chainable builder (`AIRich`, also exported as `AIVanzxy` / `LeafRich` / `VanzxyAI` / `VanzxyRich`) with 40+ `add*()`/`set*()` methods covering headings, formatted text (hyperlinks/citations/LaTeX), code blocks, tables, image/video/product/post cards, task & progress cards, tip banners, and quick-reply suggestions — the kind of rich card layout you'd normally only see from an official AI/assistant-style bot. See [Usage Examples](#airich--rich-response-cards) below.
+
 ### Native Flow Expansion
-Additional supported button types:
 
+<table>
+<tr>
+<td valign="top" width="33%">
+
+**Buttons & Actions**
 - cta_reminder
 - cta_cancel_reminder
-- address_message
-- send_location
-- catalog_message
-- mpm
 - otp_button
 - authentication_button
 - call_button
 - url_button
 - reply_button
+- voice_call
+- video_call_button
+
+</td>
+<td valign="top" width="33%">
+
+**Commerce Flow**
+- catalog_message
+- mpm
 - card_message
 - order_details
 - order_status
 - review_and_pay
 - payment_status
 - payment_method
+
+</td>
+<td valign="top" width="33%">
+
+**Navigation & Misc**
+- address_message
+- send_location
 - track_order
 - reorder
 - cancel_order
 - clear_chat
 - navigateToScreen
 - flow_action
-- voice_call
-- video_call_button
+
+</td>
+</tr>
+</table>
 
 ### System Notification Filter
+
 Messages include:
 
 ```js
@@ -109,77 +289,408 @@ Useful for filtering:
 
 ---
 
-# 📦 Installation
+## 📦 Installation
 
 ```bash
 npm install @vanzxy/baileys
 ```
 
-GitHub:
+Directly from GitHub:
 
 ```bash
-npm install github:vanzxy/baileys
+npm install github:vanzxysenpai/vanzxybaileys
 ```
 
+> Requires **Node.js 20+** — install will refuse to run below that (checked by `engine-requirements.js` on `preinstall`).
+
+### Optional peer dependencies
+
+Everything below is **optional** — the socket works without any of them. Install only what the features you use need; missing ones fail with a clear install hint instead of a silent crash.
+
+| Package | Unlocks |
+|---|---|
+| `sharp` | Fast image resizing/processing (used by the message builders' `Toolkit.resize`) |
+| `@napi-rs/image` | Lighter native alternative to `sharp` for image ops |
+| `jimp` | Pure-JS image fallback when neither of the above is installed |
+| `fluent-ffmpeg` | Audio/video conversion for media messages |
+| `audio-decode` | Audio waveform/duration extraction (voice notes, VoIP capture) |
+| `link-preview-js` | Rich link previews for URLs in outgoing text messages |
+| `better-sqlite3` | SQLite auth state **and** SQLite store adapter |
+| `mongodb` | MongoDB store adapter |
+| `mysql2` | MySQL store adapter |
+| `pg` | PostgreSQL store adapter |
+| `ioredis` | Redis store adapter |
+| `@roamhq/wrtc` | Native WebRTC bindings for [voice calling](#-voice--video-calls) |
+
 ---
 
-# 🚀 Quick Start
+## 🚀 Quick Start
 
 ```js
-import { makeWASocket } from '@vanzxy/baileys'
+import { makeWASocket, useMultiFileAuthState } from '@vanzxy/baileys'
+
+const { state, saveCreds } = await useMultiFileAuthState('auth_info')
 
 const sock = makeWASocket({
-    printQRInTerminal: true
+    auth: state
+})
+
+// persist credentials whenever Baileys updates them
+sock.ev.on('creds.update', saveCreds)
+
+sock.ev.on('connection.update', (update) => {
+    const { connection, qr } = update
+
+    // `printQRInTerminal` is deprecated upstream — render the QR yourself,
+    // e.g. with the `qrcode-terminal` package:
+    //   import qrcode from 'qrcode-terminal'
+    //   if (qr) qrcode.generate(qr, { small: true })
+    if (qr) console.log('Scan this QR:', qr)
+
+    if (connection === 'open') console.log('🍃 Connected!')
+})
+
+sock.ev.on('messages.upsert', ({ messages }) => {
+    const msg = messages[0]
+    if (!msg.message || msg.key.fromMe) return
+    console.log('New message from', msg.key.remoteJid)
 })
 ```
 
 ---
 
-# 🛠 Recommended Environment
+## 🔐 Authentication
+
+Four auth-state backends ship out of the box. All return the same `{ state, saveCreds }` shape expected by `makeWASocket({ auth })`, so they're drop-in interchangeable.
+
+| Function | Storage | Best for |
+|---|---|---|
+| `useMultiFileAuthState(folder)` | One JSON file per key, on disk | Default choice — simple, debuggable, works everywhere |
+| `useSingleFileAuthState(fileName)` | One JSON file, on disk | Small bots where a single file is easier to manage/back up |
+| `useSqliteAuthState(opts)` | SQLite (`better-sqlite3`) | Bots that already use SQLite, or want auth in one embedded DB file |
+| `useCacheManagerAuthState(store, sessionKey)` | Any [`cacheable`](https://www.npmjs.com/package/@cacheable/node-cache)-compatible store | Multi-session hosting panels, Redis-backed setups |
 
-- Node.js 18+
-- ESM Project
-- Latest WhatsApp Multi Device
+```js
+import { makeWASocket, useMultiFileAuthState } from '@vanzxy/baileys'
+
+const { state, saveCreds } = await useMultiFileAuthState('auth_info')
+const sock = makeWASocket({ auth: state })
+sock.ev.on('creds.update', saveCreds)
+```
+
+```js
+// SQLite variant
+import { makeWASocket, useSqliteAuthState } from '@vanzxy/baileys'
+
+const { state, saveCreds } = await useSqliteAuthState({ database: './auth.db' })
+const sock = makeWASocket({ auth: state })
+sock.ev.on('creds.update', saveCreds)
+```
+
+`useMultiFileAuthState` also exports `pruneStaleAuthFiles(folder, options)` to clean up old sender-key files on a schedule — useful for long-running bots that accumulate thousands of stale key files.
 
 ---
 
-# 📚 Fork Lineage
+## 🗄️ Store Backends
+
+`makeInMemoryStore()` from `lib/Store` gives you the classic in-memory chat/contact/message cache. For anything that needs to survive a restart, `makePersistentStore()` (from `PersistentStore.js`) wraps one of five backends behind the same interface:
+
+| Backend | Function |
+|---|---|
+| SQLite | `createSqliteStoreAdapter(opts)` |
+| MongoDB | `createMongoStoreAdapter(opts)` |
+| MySQL | `createMysqlStoreAdapter(opts)` |
+| PostgreSQL | `createPostgresStoreAdapter(opts)` |
+| Redis | `createRedisStoreAdapter(opts)` |
+
+```js
+import { makeWASocket, makeInMemoryStore } from '@vanzxy/baileys'
+
+const store = makeInMemoryStore({})
+store.readFromFile('./baileys_store.json')
+setInterval(() => store.writeToFile('./baileys_store.json'), 10_000)
+
+const sock = makeWASocket({ /* ...auth etc */ })
+store.bind(sock.ev)
+```
 
+---
+
+## 💡 Usage Examples
+
+### Buttons & Native Flow
+
+```js
+import { Button } from '@vanzxy/baileys'
+
+await new Button(sock)
+    .setTitle('Promo Spesial')
+    .setBody('Diskon 20% cuma hari ini')
+    .setFooter('@vanzxy/baileys')
+    .addReply('Klaim Sekarang', 'claim_promo')
+    .addUrl('Lihat Katalog', 'https://example.com/catalog')
+    .addCall('Hubungi Kami', '628123456789')
+    .send(jid)
+```
+
+### Poll
+
+```js
+import { Poll } from '@vanzxy/baileys'
+
+await new Poll(sock)
+    .setName('Mau makan apa hari ini?')
+    .addOptions(['Nasi Goreng', 'Mie Ayam', 'Bakso'])
+    .setSelectable(1)
+    .send(jid)
+```
+
+### Carousel
+
+> Each card must be built with `Button(...).toCard()` first — a carousel card is really just a button card with an image/video header.
+
+```js
+import { Button, Carousel } from '@vanzxy/baileys'
+
+const cardA = await new Button(sock)
+    .setImage('https://example.com/a.jpg')
+    .setTitle('Produk A')
+    .addUrl('Lihat', 'https://example.com/a')
+    .toCard()
+
+const cardB = await new Button(sock)
+    .setImage('https://example.com/b.jpg')
+    .setTitle('Produk B')
+    .addUrl('Lihat', 'https://example.com/b')
+    .toCard()
+
+await new Carousel(sock)
+    .setBody('Pilih salah satu produk di bawah ini')
+    .addCard([cardA, cardB])
+    .send(jid)
+```
+
+### AIRich — rich response cards
+
+```js
+import { AIRich } from '@vanzxy/baileys'
+
+await new AIRich(sock)
+    .addHeading('Ringkasan Order')
+    .addText('Pesananmu sedang diproses.')
+    .addTable([
+        ['Item', 'Qty'],
+        ['Kopi Susu', '2']
+    ])
+    .addTip('Pesanan biasanya siap dalam 15 menit')
+    .addSuggest('Lacak Order')
+    .send(jid)
+```
+
+`AIRich` supports `{ id, insertAt }` on every `add*()`/`set*()` call, so you can insert a block relative to one you added earlier instead of always appending to the end — handy for streaming/edit-in-place style responses combined with `sendEdit(jid, id)`.
+
+Other builders worth knowing about: **`ButtonV2`** (simpler quick-reply-only buttons), **`ButtonV3`** (`loadFrom(msg)` to edit an existing template message in place), and **`Toolkit`** (static helpers: `Toolkit.resize()`, `Toolkit.fetchBuffer()`, `Toolkit.waitAllPromises()`, `Toolkit.extractIE()` for parsing `[label](url)` links/citations/LaTeX out of plain text).
+
+---
+
+## 📞 Voice & Video Calls
+
+Experimental audio-call support (ported from ourin-baileys) via a WASM call stack + WebRTC relay. Requires the optional `@roamhq/wrtc` peer dependency.
+
+```js
+import { VoipClient } from '@vanzxy/baileys'
+
+const voip = new VoipClient({ resourcesPath: './voip-resources' })
+await voip.connectWithSocket(sock)
+
+const call = await voip.call('628123456789')
+
+call.on('ringing', () => console.log('Ringing...'))
+call.on('connected', () => console.log('Call connected'))
+call.on('ended', (reason) => console.log('Call ended:', reason))
+```
+
+`ActiveCall` (returned by `.call()`) and `CallState` are also exported directly if you need finer-grained control over call state.
+
+---
+
+## 🔎 User Sync Queries
+
+`WAUSync` (`USyncQuery` / `USyncUser` + protocols) lets you check things like WhatsApp registration, device lists, status, and username info for a JID before you message it — the same mechanism behind `sock.onWhatsApp()`.
+
+```js
+import { USyncQuery, USyncUser, USyncContactProtocol } from '@vanzxy/baileys'
+
+const query = new USyncQuery()
+    .withContext('interactive')
+    .withMode('query')
+    .withUser(new USyncUser().withPhone('628123456789'))
+
+query.protocols.push(new USyncContactProtocol())
+
+const result = await sock.executeUSyncQuery(query)
+```
+
+Available protocols: `USyncContactProtocol`, `USyncDeviceProtocol`, `USyncStatusProtocol`, `USyncUsernameProtocol`, `USyncDisappearingModeProtocol`, `UsyncBotProfileProtocol`, `UsyncLIDProtocol`.
+
+---
+
+## 🧩 Utility Modules
+
+A sample of the utilities exported from `lib/Utils` beyond the message builders above:
+
+| Module | What it does |
+|---|---|
+| `anti-delete` | Detect and recover messages the sender deleted for everyone |
+| `auto-reply` | Simple keyword/pattern-based auto-responder engine |
+| `message-search` | Search cached/stored messages, peeling off ephemeral/view-once wrappers first |
+| `message-retry-manager` | Handles WhatsApp's retry-receipt protocol for undecryptable messages |
+| `scheduling` | Schedule messages/actions for later delivery |
+| `business` | Business-profile & catalog helpers |
+| `chat-control` | Pin, mute, archive, and mark-read/unread helpers |
+| `chat-history-helpers` | Work with synced chat history payloads |
+| `link-preview` | Generate link preview metadata for outgoing messages |
+| `stickerpack` | Build and send sticker packs (including animated/Lottie) |
+| `templates` | Legacy WhatsApp Business template message helpers |
+| `vcard` | Build vCard (contact card) payloads |
+| `status` | Post and manage WhatsApp Status updates |
+| `event-buffer` | Buffers/coalesces high-volume socket events for heavier bots |
+
+Every module above ships a matching `.d.ts`, so your editor will show full hover-docs regardless of which ones you import.
+
+---
+
+## 🛠 Recommended Environment
+
+| Requirement | Version |
+|---|---|
+| Node.js | 20+ |
+| Module system | ESM |
+| WhatsApp | Latest Multi Device |
+
+---
+
+## 📘 TypeScript Support
+
+Every file in `lib/` ships a matching `.d.ts`, including the message builders (`MessageBuilder_d.ts`) and all `Types/*` definitions (Auth, Chat, Contact, Events, GroupMetadata, Message, Product, Signal, USync, and more). No `@types/` package needed — plain `import { ... } from '@vanzxy/baileys'` gets full autocomplete in TS or JS-with-checkJS projects.
+
+---
+
+## 📚 Fork Lineage
+
+```
 @vanzxy/baileys
 └── @itsliaaa/baileys
     └── WhiskeySockets/Baileys
+```
 
 Respect to all original maintainers and contributors.
 
 ---
 
-# 👑 Maintainer
+## ❓ FAQ & Troubleshooting
 
-**Vanzxy**
+<details>
+<summary><b>Koneksi terus putus / reconnect loop</b></summary>
+<br/>
 
-GitHub:
-https://github.com/vanzxy
+Cek `connection.update` untuk field `lastDisconnect.error`. Kalau status code-nya `401` (loggedOut), sesi memang sudah invalid dan perlu scan ulang QR — jangan auto-reconnect di kondisi ini. Untuk status lain (`428`, `440`, dsb.), reconnect dengan backoff biasanya cukup.
 
-Package:
-@vanzxy/baileys
+</details>
+
+<details>
+<summary><b>QR tidak muncul / tidak ke-scan</b></summary>
+<br/>
+
+`printQRInTerminal` sudah deprecated di upstream Baileys — pastikan kamu render QR sendiri dari event `qr` (lihat contoh di [Quick Start](#-quick-start)). Kalau QR muncul tapi gagal linking, biasanya karena versi WA Web (`version` di `makeWASocket`) sudah kedaluwarsa; fetch versi terbaru lewat `fetchLatestBaileysVersion()`.
+
+</details>
+
+<details>
+<summary><b>Error "Bad MAC" / pesan gagal didekripsi</b></summary>
+<br/>
+
+Umumnya terjadi kalau folder auth state korup atau sesi dipakai di lebih dari satu proses secara bersamaan. Pastikan hanya satu instance yang menulis ke folder auth state yang sama, dan pertimbangkan `pruneStaleAuthFiles()` untuk membersihkan sender-key lama secara berkala.
+
+</details>
+
+<details>
+<summary><b>Memory terus naik di bot yang jalan lama</b></summary>
+<br/>
+
+Kalau pakai `makeInMemoryStore()`, cache chat/message/contact akan terus tumbuh tanpa batas. Untuk bot yang jalan lama, pertimbangkan pindah ke salah satu backend `makePersistentStore()` (SQLite/Redis/dst) dan pakai `event-buffer` untuk meredam lonjakan event di trafik tinggi.
+
+</details>
+
+<details>
+<summary><b>Voice call gagal connect</b></summary>
+<br/>
+
+Fitur ini masih experimental dan butuh peer dependency `@roamhq/wrtc` — pastikan sudah terinstall dan platform kamu didukung native binding-nya. Cek event `call.on('ended', reason => ...)` untuk detail penyebab gagalnya.
+
+</details>
 
 ---
 
-# ⚠️ Disclaimer
+## 🤝 Contributing
 
-This project is an independent fork.
-Use responsibly and follow WhatsApp Terms of Service.
+Kontribusi dipersilakan, terutama untuk perbaikan bug, dokumentasi, dan enhancement pada `MessageBuilder` / `AIRich`.
+
+1. Fork repo ini, buat branch dari `main` (`feat/nama-fitur` atau `fix/nama-bug`)
+2. Pastikan perubahan tetap ESM-only dan menyertakan/menyesuaikan `.d.ts` terkait
+3. Uji perubahan pada minimal satu jalur auth state + satu store backend sebelum PR
+4. Buka Pull Request dengan deskripsi singkat: apa yang berubah dan kenapa
+
+Untuk laporan bug, sertakan versi Node.js, cara reproduksi, dan potongan log `lastDisconnect.error` bila relevan.
 
 ---
 
-Made with 🍃 by Vanzxy
+## 🙏 Credits
+
+- **Nixel** (with contributions from **Ahmad tumbuh kembang**) — base implementation of the `MessageBuilder` (AIRich / Button / Carousel / Toolkit), originally "NIXCODE — Advanced WhatsApp Interactive Message Builder"
+- **vinikjkkj** ([zapo](https://github.com/vinikjkkj/zapo)) — button/list addon-kind resolution logic
+- **QueenAnya** (`@queenanya/baileys`) — interactive/native-flow button send layer
+- **WhiskeySockets/Baileys** & **@itsliaaa/baileys** — upstream base
 
+Full details and license terms per component: see [`NOTICE.md`](./NOTICE.md).
+
+---
 
-## V4 Patch Notes
+## 👑 Maintainer
+
+**Vanzxy**
+
+- GitHub: [github.com/vanzxysenpai](https://github.com/vanzxysenpai)
+- Package: [`@vanzxy/baileys`](https://www.npmjs.com/package/@vanzxy/baileys)
+
+---
+
+## ⚠️ Disclaimer
+
+This project is an independent fork.
+Use responsibly and follow WhatsApp Terms of Service.
+
+---
+
+## 📝 V4 Patch Notes
 
 - Kept the existing Vanzxy custom MessageBuilder classes and AIRich implementation intact.
 - Added `whatsapp-rust-bridge@0.5.5` as a runtime dependency. The library already dynamically imports this module for LT Hash/app-state and crypto helpers; declaring it prevents accidental missing-module fallbacks in normal installations.
 - Existing guarded fallbacks for platforms where the native bridge cannot load remain in place.
 - ESM-only package metadata is preserved; no CommonJS build is included.
 
-Reference audit: the supplied Ourin, Elaina, ItsLiaaa, and Noxleyss packages were compared before this patch. Their broader core changes were not copied wholesale because the current Vanzxy tree already contains additional LID, retry, media, interactive, and AIRich fixes that would risk regressions if replaced.
+Reference audit: the supplied Ourin, Elaina, ItsLiaaa, and Noxleyss packages were compared before this patch. Their broader core changes were not copied wholesale because the current Vanzxy tree already contains additional LID, retry, media, interactive, angd AIRich fixes that would risk regressions if replaced.
+
+---
+
+<div align="center">
+
+<img src="https://capsule-render.vercel.app/api?type=waving&color=0:2ecc71,100:1d6a23&height=100&section=footer" width="100%"/>
+
+Made with 🍃 by **Vanzxy**
+
+Thanks for stopping by! ✌️
+
+<a href="#top">⬆️ Back to top</a>
+
+</div>