@vanzxy/baileys 1.6.7 → 1.7.0

package/NOTICE.md

@@ -0,0 +1,111 @@
+# NOTICE
+
+`@vanzxy/baileys` is MIT-licensed (see the root `LICENSE`/`license` field in
+`package.json`). It's a fork built on top of, and incorporating ported code
+from, several other MIT-licensed WhatsApp libraries. This file lists each
+third-party component, its original author/source, and where it lives in
+this package — so credit stays attached to the actual code, not just a
+generic "thanks" in the README.
+
+MIT only requires the original copyright notice to travel with the code; it
+does not require original authors to endorse this fork. Every component
+below was MIT-licensed at its source at the time it was ported.
+
+---
+
+## Upstream base
+
+- **WhiskeySockets/Baileys** — original library this entire tree descends from.
+- **@itsliaaa/baileys** — intermediate fork this package was branched from.
+
+## Ported components
+
+### MessageBuilder / AIRich / Button / Carousel / Toolkit — base implementation
+- **Source:** Nixel, "NIXCODE — Advanced WhatsApp Interactive Message Builder", with contributions from Ahmad tumbuh kembang.
+- **Location in this package:** `lib/Utils/MessageBuilder.js` and the `AIRich`/`AIVanzxy`/`LeafRich` exports.
+- **⚠ Needs your confirmation:** the in-file header as of 1.7.0 now says this
+  was "ported into @vanzxy/baileys 1.3.9 from the `@blurose/baileys` 1.1.13
+  fork (base, feature-complete), with perf defaults and message-authenticity
+  fields backported from `arslan-baileys` 1.1.0." That doesn't name Nixel/
+  NIXCODE or Ahmad tumbuh kembang at all. I didn't overwrite the existing
+  line since I can't tell from the code alone whether blurose/arslan are
+  themselves downstream of NIXCODE (in which case both chains should be
+  listed) or whether this is a separate lineage that should replace the old
+  entry. Let me know which and I'll finalize it.
+
+### MessageBuilder v4.7 additions (setResponseId/setBotResponseId/hasId/getIds/peek/delete)
+- **Source:** credited in-code only as "temen's MessageBuilderV4.7" (`temen` = Indonesian for "friend/buddy") — not a resolvable handle or repo.
+- **Location in this package:** `lib/Utils/MessageBuilder.js` (`~line 2120, 2885, 2916`).
+- **⚠ Needs your input:** I can't attribute this properly without the actual author/repo name. Let me know who this refers to.
+
+### Button/list addon-kind resolution logic
+- **Source:** vinikjkkj, [zapo](https://github.com/vinikjkkj/zapo) (MIT).
+- **Location in this package:** `lib/Utils/message-kind.js` (`resolveButtonAddonKind`, ported from `zapo-js` `src/message/encode/content.ts`).
+- *(Corrected from the previous NOTICE, which pointed this entry at
+  `button-helper-utils.js`/`button-sender.js` — those two files are actually
+  sourced from `@queenanya/baileys`, see below. The zapo attribution belongs
+  here instead.)*
+- Also referenced "in spirit" (not a direct port) for migration-tracking
+  design in `lib/Utils/use-sqlite-auth-state.js`.
+
+### Button helper / button-sender runtime layer
+- **Source:** QueenAnya, [`@queenanya/baileys`](https://github.com/QueenAnya/Bail) (MIT) `src/addons/message-utils.ts` and `src/addons/button-sender.ts` — both of which that fork's own header credits onward to **`@ryuu-reinzz/button-helper` v2.2.5** as the original implementation.
+- **Location in this package:** `lib/Utils/button-helper-utils.js`, `lib/Utils/button-sender.js`.
+
+### Interactive/native-flow button send layer
+- **Source:** QueenAnya, [`@queenanya/baileys`](https://github.com/QueenAnya/Bail) (MIT, Copyright (c) 2025 Rajeh Taher/WhiskeySockets).
+- **Location in this package:** `lib/Utils/button-sender.js` (send-layer portions).
+
+### Username management (check/set/pin/recommend/find)
+- **Source:** QueenAnya, [`@queenanya/baileys`](https://github.com/QueenAnya/Bail) `lib/Socket/username.js` (MIT), itself ported from `@innovatorssoft/baileys`.
+- **Location in this package:** `lib/Socket/username.js`.
+
+### Chat Control utilities (TypingIndicator + related presence helpers)
+- **Source:** `@innovatorssoft/baileys` `chat-control.js` (direct, per this file's own header — not routed through @queenanya/baileys).
+- **Location in this package:** `lib/Utils/chat-control.js` (and its `.d.ts`).
+
+### Bail-master Utils addons batch
+- **Source:** QueenAnya's `Bail` repository, master branch ("Bail-master"), `src/addons/*.ts` — same upstream as the `@queenanya/baileys` package above.
+- **Location in this package** (TS → ESM JS conversions, type-only annotations dropped, behavior unchanged unless noted):
+  - `lib/Utils/vcard.js` ← `addons/vcard.ts`
+  - `lib/Utils/scheduling.js` ← `addons/scheduling.ts` + `addons/message-scheduler.ts` (merged into one class-based scheduler)
+  - `lib/Utils/message-search.js` ← `addons/message-search.ts`
+  - `lib/Utils/auto-reply.js` ← `addons/auto-reply.ts`
+  - `lib/Utils/stickerpack.js` ← `addons/stickerpack.ts`
+  - `lib/Utils/anti-delete.js` ← `addons/anti-delete.ts`
+  - `lib/Utils/chat-history-helpers.js` ← `addons/chat-history-helpers.ts` (adapted to this fork's own `makeInMemoryStore`)
+  - `lib/Utils/media-messages.js` ← `addons/media-messages.ts`
+  - `lib/Utils/media-set.js` ← `addons/media-set.ts`
+  - `lib/Utils/status.js` ← `addons/status-helpers.ts`
+  - `lib/Utils/templates.js` ← `addons/templates.ts`
+  - `lib/Utils/baileys-event-stream.js` ← `addons/baileys-event-stream.ts`
+  - `lib/Utils/past-participants.js` ← `addons/past-participants.ts`
+  - `lib/Utils/use-cache-manager-auth-state.js` ← `addons/use-cache-manager-auth-state.ts` (that file itself credits `@innovatorssoft/baileys` `make-cache-manager-store.js`)
+
+### Bot Framework (Bot / Context / SessionManager / StatsManager / MediaManager / SQLiteStore)
+- **Source:** Originally submitted as WhiskeySockets/Baileys PR #2710 by **LuferOS**; the P0–P3 bugfix pass and TypeScript rewrite referenced in this package's code comments were done by QueenAnya in `@queenanya/baileys` `lib/Framework/` (MIT). Adapted further for this fork (async `better-sqlite3`/`fluent-ffmpeg` lazy-loading, no `ffmpeg-static` dependency) — see the `Vanz@Port`/`Vanz@Fix` comments at the top of each file for exactly what changed.
+- **Location in this package:** `lib/Framework/`.
+
+### ourin-baileys ports
+- **Source:** ourin-baileys (version 9.0.11 for the VoIP stack, per this package's `lib/index.js`).
+- **Location in this package:**
+  - `lib/VoIP/`, `lib/assets/wasm/` — audio call WASM stack + WebRTC relay.
+  - `lib/Socket/newsletter.js` — AutoFollow feature.
+  - `lib/Utils/MessageBuilder.js` — the `ORich` no-op subclass of `AIRich`, kept only for drop-in compatibility with code originally written against ourin-baileys.
+
+---
+
+## Referenced for verification only (no code incorporated)
+
+A few bug-fix comments in `lib/Utils/MessageBuilder.js` cite other
+implementations to confirm expected wire behavior, without copying code from
+them: `zqdevelopers/zq_baileys_helper`, `@chatunity/baileys`, `@neoxr/wb`,
+and `WhiskeySockets/Baileys` issue/PR `#2626`. Listed here for transparency
+only — not attribution-bearing ports, so no third-party notice entry is
+needed for them.
+
+---
+
+If a source or attribution above is inaccurate or a component was missed,
+please open an issue at the repository linked in `package.json` so it can be
+corrected — misattribution here is a mistake to fix, not a dispute to argue.

package/README.md

@@ -2,8 +2,6 @@
 
 <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>
@@ -41,11 +39,11 @@
 <summary>📖 Full table of contents</summary>
 <br/>
 
-- [🍃 Why @vanzxy/baileys](#-why-vanzxybaileys)
+- [✨ Why @vanzxy/baileys](#-why-vanzxybaileys)
 - [🆚 Comparison](#-comparison)
 - [🧰 Built With](#-built-with)
 - [🔥 Features](#-features)
-- [✨ Exclusive Vanzxy Enhancements](#-exclusive-vanzxy-enhancements)
+- [🌟 Exclusive Vanzxy Enhancements](#-exclusive-vanzxy-enhancements)
 - [📦 Installation](#-installation)
 - [🚀 Quick Start](#-quick-start)
 - [🔐 Authentication](#-authentication)
@@ -57,6 +55,8 @@
   - [AIRich — rich response cards](#airich--rich-response-cards)
 - [📞 Voice & Video Calls](#-voice--video-calls)
 - [🔎 User Sync Queries](#-user-sync-queries)
+- [👤 Username Management](#-username-management)
+- [🤖 Bot Framework](#-bot-framework)
 - [🧩 Utility Modules](#-utility-modules)
 - [🛎️ System Notification Filter](#-system-notification-filter)
 - [🛠 Recommended Environment](#-recommended-environment)
@@ -65,10 +65,11 @@
 - [❓ FAQ & Troubleshooting](#-faq--troubleshooting)
 - [🤝 Contributing](#-contributing)
 - [🙏 Credits](#-credits)
+- [📈 Repo Activity](#-repo-activity)
 - [💖 Support](#-support)
 - [👑 Maintainer](#-maintainer)
 - [⚠️ Disclaimer](#-disclaimer)
-- [📝 Patch Notes](#-v4-patch-notes)
+- [📝 Patch Notes](#-v5-patch-notes)
 
 </details>
 
@@ -76,7 +77,7 @@
 
 ---
 
-## 🍃 Why @vanzxy/baileys?
+## ✨ Why @vanzxy/baileys?
 
 This fork focuses on:
 
@@ -107,6 +108,8 @@ How `@vanzxy/baileys` stacks up against its own lineage and the wider Baileys fo
 | Multi-backend store (SQL/Mongo/Redis) | ✅ | ⚠️ file/SQLite only | ⚠️ in-memory only |
 | Full `.d.ts` TypeScript definitions | ✅ | ⚠️ partial | ⚠️ partial |
 | User sync queries (WAUSync) | ✅ | ✅ | ✅ |
+| Username management (check/set/pin/recommend) | ✅ | ❌ | ❌ |
+| Bot framework (middleware, session, stats) | ✅ | ❌ | ❌ |
 
 > Tabel ini menggambarkan fitur di level package, bukan benchmark performa. PR untuk memperbarui/mengoreksi tabel ini dipersilakan lewat [Contributing](#-contributing).
 
@@ -218,7 +221,7 @@ How `@vanzxy/baileys` stacks up against its own lineage and the wider Baileys fo
 
 ---
 
-## ✨ 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.
@@ -315,7 +318,8 @@ Everything below is **optional** — the socket works without any of them. Insta
 | `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 |
+| `better-sqlite3` | SQLite auth state, SQLite store adapter, **and** the [Bot Framework](#-bot-framework)'s `SQLiteStore`/`StatsManager` |
+| `node-webpmux` | Packname/author EXIF metadata on stickers made via `MediaManager.convertToSticker()` — not needed for plain sticker conversion |
 | `mongodb` | MongoDB store adapter |
 | `mysql2` | MySQL store adapter |
 | `pg` | PostgreSQL store adapter |
@@ -535,6 +539,84 @@ Available protocols: `USyncContactProtocol`, `USyncDeviceProtocol`, `USyncStatus
 
 ---
 
+## 👤 Username Management
+
+High-level wrappers around WhatsApp's username feature (the `@username` handle you can set instead of exposing your phone number), sitting on top of `USyncUsernameProtocol`. Query IDs are captured from live WA Web sessions — if a call starts throwing `unexpected response structure`, WA has rotated them and they need re-capturing.
+
+```js
+// Check availability + get suggestions if taken
+const check = await sock.checkUsername('vanzxy')
+// { available: true, username: 'vanzxy' }
+// or: { available: false, suggestions: [...], rejectionReasons: [...] }
+
+// Claim a username
+await sock.setUsername('vanzxy', { source: sock.USERNAME_SOURCE.USER_INPUT })
+
+// Lock it behind a PIN so it can't be changed without one
+await sock.setUsernamePin('123456')
+
+// Read your own username / drop it
+const mine = await sock.getMyUsername()
+await sock.deleteUsername()
+
+// Resolve a username to a JID (USync-based, like onWhatsApp() but by username)
+const user = await sock.findUserByUsername('someone')
+// { jid: '628...@s.whatsapp.net', contact: false }
+
+// Batch-resolve usernames for a list of known contacts
+const usernames = await sock.fetchContactUsernames(jid1, jid2, jid3)
+
+// Get WA's own suggestions (e.g. for onboarding flows)
+const recs = await sock.getUsernameRecommendations()
+```
+
+> Requires a Community/Contact-tier account in good standing — accounts under WA's usual restrictions for new/unverified numbers may see `INVALID` or empty suggestions regardless of the username's actual availability.
+
+---
+
+## 🤖 Bot Framework
+
+An optional, higher-level layer on top of the raw socket: middleware routing, a `!command` dispatcher, a message queue that survives disconnects, exponential-backoff auto-reconnect, per-JID session storage, group activity stats, and media (sticker/voice-note) conversion helpers — so a new bot project doesn't have to hand-roll session/context management every time.
+
+Needs the `better-sqlite3` peer dependency (session + stats storage) and `fluent-ffmpeg` (sticker/voice-note conversion, already listed above) — both fail with an install hint rather than crashing if you use a Framework feature that needs them without installing them first.
+
+```js
+import { Bot } from '@vanzxy/baileys'
+
+const bot = new Bot({
+    socketConfig: { printQRInTerminal: true },
+    dbPath: './bot.db',   // sessions + stats, defaults to 'baileys_store.db'
+    enableStats: true     // group message/sticker leaderboards + ghost detection
+})
+
+bot.command('!ping', async (ctx) => {
+    await ctx.reply({ text: 'pong' })
+})
+
+bot.command('!sticker', async (ctx) => {
+    if (!ctx.quoted?.imageMessage) return ctx.reply({ text: 'Reply to an image with !sticker' })
+    // ctx.replySticker() handles the WebP conversion for you
+    await ctx.replySticker(imageBuffer, { packname: 'Vanzxy Pack', author: 'you' })
+})
+
+bot.onText(async (ctx) => {
+    // ctx.session() / ctx.setSession() / ctx.updateSession() / ctx.clearSession()
+    // persist small per-chat state (e.g. multi-step flows) to SQLite automatically
+    const state = ctx.session()
+    if (state?.awaitingReply) {
+        ctx.updateSession((s) => ({ ...s, awaitingReply: false }))
+    }
+})
+
+await bot.start()
+```
+
+`Context`, `SessionManager`, `StatsManager`, `MediaManager`, and `SQLiteStore` are also exported individually if you only need one piece rather than the full `Bot` class.
+
+> These files ship as plain `.js` for now — hand-written `.d.ts` declarations for the Framework module haven't been added yet, unlike the rest of this fork's fully-typed surface.
+
+---
+
 ## 🧩 Utility Modules
 
 A sample of the utilities exported from `lib/Utils` beyond the message builders above:
@@ -656,6 +738,41 @@ Full details and license terms per component: see [`NOTICE.md`](./NOTICE.md).
 
 ---
 
+## 📈 Repo Activity
+
+<div align="center">
+
+<a href="https://star-history.com/#vanzxysenpai/vanzxybaileys&Date">
+  <img src="https://api.star-history.com/svg?repos=vanzxysenpai/vanzxybaileys&type=Date" width="70%" alt="Star History Chart"/>
+</a>
+
+</div>
+
+> Star history di atas otomatis mengikuti data repo — tidak perlu setup tambahan.
+
+<details>
+<summary>🎮 Want a 3D contribution graph on your own profile?</summary>
+<br/>
+
+That's a separate, opt-in GitHub Action for your **profile** repo (`username/username`), not something this package ships — see [github-profile-3d-contrib](https://github.com/yoshi389111/github-profile-3d-contrib) if you want to set it up for yourself.
+
+</details>
+
+---
+
+## 💖 Support
+
+Kalau package ini kepakai buat project kamu, dukungan kecil sangat membantu perawatannya:
+
+<p>
+<a href="https://github.com/sponsors/vanzxysenpai" target="_blank"><img src="https://img.shields.io/badge/GitHub%20Sponsors-EA4AAA?style=for-the-badge&logo=githubsponsors&logoColor=white" alt="GitHub Sponsors"/></a>
+<a href="#" target="_blank"><img src="https://img.shields.io/badge/Ko--fi-FF5E5B?style=for-the-badge&logo=kofi&logoColor=white" alt="Ko-fi"/></a>
+</p>
+
+> Ganti link Ko-fi/Sponsors di atas dengan akun kamu, atau hapus baris ini kalau belum dipakai.
+
+---
+
 ## 👑 Maintainer
 
 **Vanzxy**
@@ -672,6 +789,18 @@ Use responsibly and follow WhatsApp Terms of Service.
 
 ---
 
+## 📝 V5 Patch Notes
+
+- Added [Username Management](#-username-management): `checkUsername`, `checkUsernameMulti`, `setUsername`, `deleteUsername`, `getMyUsername`, `setUsernamePin`, `findUserByUsername`, `fetchContactUsernames`, `getUsernameRecommendations` — ported from `@queenanya/baileys`, layered onto this fork's existing `USyncUsernameProtocol` support.
+- Added the [Bot Framework](#-bot-framework) (`Bot`, `Context`, `SessionManager`, `StatsManager`, `MediaManager`, `SQLiteStore`) — ported from `@queenanya/baileys` (originally WhiskeySockets PR #2710 by LuferOS). Adapted on the way in:
+  - `SQLiteStore`/`StatsManager` construction moved behind an async `.create()` factory so `better-sqlite3` stays a lazily-loaded optional peer dep instead of a hard top-level import that would crash the Framework module for anyone without it installed.
+  - `MediaManager`'s sticker/voice-note conversion now reuses this fork's existing lazy `fluent-ffmpeg` loader (see `Utils/MessageBuilder.js`) instead of adding `ffmpeg-static` + a second ffmpeg dependency; `node-webpmux` (sticker EXIF metadata) is lazy-loaded the same way and only when packname/author is actually requested.
+  - `Bot`'s default logger now falls back to this fork's own pino instance instead of a silent no-op stub.
+- No `.d.ts` files were written for the new Framework module yet — see the note in that section.
+- Bumped to `1.7.0`.
+
+---
+
 ## 📝 V4 Patch Notes
 
 - Kept the existing Vanzxy custom MessageBuilder classes and AIRich implementation intact.
@@ -679,7 +808,7 @@ Use responsibly and follow WhatsApp Terms of Service.
 - 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, angd 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, and AIRich fixes that would risk regressions if replaced.
 
 ---
 

package/lib/Framework/Bot.js

@@ -0,0 +1,209 @@
+import { Boom } from '@hapi/boom';
+import makeWASocket from '../Socket/index.js';
+import { DisconnectReason } from '../Types/index.js';
+import { isJidGroup } from '../WABinary/index.js';
+import defaultLogger from '../Utils/logger.js';
+import { SQLiteStore } from './Store/SQLiteStore.js';
+import { Context } from './Context.js';
+import { SessionManager } from './SessionManager.js';
+import { StatsManager } from './StatsManager.js';
+
+// Vanz@Port (from @queenanya/baileys Framework, originally Baileys PR #2710
+// by LuferOS) --- high-level Bot class: middleware routing (Express/Koa-style
+// `use()`/`next()`), a `!command` dispatcher, an outgoing message queue that
+// survives disconnects, and exponential-backoff auto-reconnect.
+//
+// Kept from upstream's fix pass:
+//  - command boundary check: `!sticker` no longer matches `!stickerSpam`
+//  - queue is rejected (not left hanging) on DisconnectReason.loggedOut
+//  - stats.observeMessage runs inside the per-message try block, so a
+//    SQLite error can't silently skip middleware for that message
+//  - reconnect timer handle is stored so stop()/restart() can cancel it
+//
+// Vanz@Fix vs upstream: SQLiteStore/StatsManager are now created through an
+// async factory (see Store/SQLiteStore.js) instead of a synchronous
+// constructor, since better-sqlite3 is lazy-loaded as an optional peer dep
+// in this fork. That means store/session/stats setup moved out of the Bot
+// constructor and into start() — the socket is only created *after* the
+// store is ready, so no message can arrive before sessions/stats exist.
+export class Bot {
+    constructor(config) {
+        this.middlewares = [];
+        this.messageQueue = [];
+        this.isConnected = false;
+        this.reconnectAttempts = 0;
+        this.reconnectTimer = null;
+        this.BASE_RECONNECT_DELAY = 1000;
+        this.MAX_RECONNECT_DELAY = 30000;
+        this.socket = null;
+        this.sessions = null;
+        this.stats = null;
+        this.store = null;
+        this.config = config;
+        this.logger = config.logger ?? defaultLogger.child({ module: 'Framework.Bot' });
+    }
+
+    /** Register a middleware function */
+    use(middleware) {
+        this.middlewares.push(middleware);
+        return this;
+    }
+
+    /**
+     * Register a command handler.
+     * Uses exact match OR prefix + whitespace so '!sticker' does NOT
+     * match '!stickerSpam' or '!stickerset'.
+     */
+    command(cmd, handler) {
+        this.use(async (ctx, next) => {
+            const text = ctx.text;
+            if (text === cmd || text?.startsWith(cmd + ' ')) {
+                await handler(ctx);
+            }
+            await next();
+        });
+        return this;
+    }
+
+    /** Register a handler that fires on any non-empty text */
+    onText(handler) {
+        this.use(async (ctx, next) => {
+            if (ctx.text) {
+                await handler(ctx);
+            }
+            await next();
+        });
+        return this;
+    }
+
+    /** Send a message — queues automatically when socket is disconnected */
+    async sendMessage(jid, content, options = {}) {
+        if (this.isConnected && this.socket) {
+            return this.socket.sendMessage(jid, content, options);
+        }
+        return new Promise((resolve, reject) => {
+            this.messageQueue.push({ jid, content, options, resolve, reject });
+            this.logger.info({ queueLength: this.messageQueue.length }, 'socket not connected — message queued');
+        });
+    }
+
+    /** Drain queued messages after reconnect. */
+    drainQueue() {
+        if (!this.isConnected || !this.socket || this.messageQueue.length === 0)
+            return;
+        this.logger.info({ pending: this.messageQueue.length }, 'draining message queue');
+        const queue = [...this.messageQueue];
+        this.messageQueue = [];
+        for (const msg of queue) {
+            this.socket.sendMessage(msg.jid, msg.content, msg.options).then(msg.resolve).catch(msg.reject);
+        }
+    }
+
+    /** Reject and clear the message queue. Called on loggedOut so callers don't hang forever. */
+    rejectQueue(reason) {
+        const queue = [...this.messageQueue];
+        this.messageQueue = [];
+        for (const msg of queue) {
+            msg.reject(new Boom(reason, { statusCode: 401 }));
+        }
+        if (queue.length > 0) {
+            this.logger.warn({ rejected: queue.length }, 'message queue rejected — session terminated');
+        }
+    }
+
+    /** Start the socket and wire all event handlers */
+    async start() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        // Vanz@Fix: store/sessions must exist before the socket can receive
+        // any message, so this now awaits creation instead of doing it
+        // synchronously in the constructor.
+        if (!this.store) {
+            const dbPath = this.config.dbPath ?? 'baileys_store.db';
+            this.store = await SQLiteStore.create(dbPath);
+            this.sessions = new SessionManager(this.store);
+        }
+        this.socket = makeWASocket(this.config.socketConfig);
+        if (this.config.enableStats && !this.stats) {
+            this.stats = await StatsManager.create(this.config.dbPath ?? 'baileys_store.db', jid => this.socket.groupMetadata(jid));
+        }
+        this.socket.ev.on('messages.upsert', async ({ messages, type }) => {
+            if (type !== 'notify')
+                return;
+            for (const msg of messages) {
+                const ctx = new Context(this, msg);
+                try {
+                    if (this.stats && ctx.remoteJid && isJidGroup(ctx.remoteJid)) {
+                        const participant = msg.key.participant || msg.participant;
+                        if (participant) {
+                            const isSticker = !!msg.message?.stickerMessage;
+                            this.stats.observeMessage(ctx.remoteJid, participant, isSticker);
+                        }
+                    }
+                    await this.executeMiddlewares(ctx);
+                }
+                catch (err) {
+                    this.logger.error({ err }, 'error executing middleware');
+                }
+            }
+        });
+        this.socket.ev.on('connection.update', update => {
+            const { connection, lastDisconnect } = update;
+            if (connection === 'open') {
+                this.logger.info('bot connected');
+                this.isConnected = true;
+                this.reconnectAttempts = 0;
+                this.drainQueue();
+            }
+            if (connection === 'close') {
+                this.isConnected = false;
+                const error = lastDisconnect?.error;
+                const statusCode = error?.output?.statusCode;
+                const isLoggedOut = statusCode === DisconnectReason.loggedOut;
+                this.logger.warn({ statusCode }, 'connection closed');
+                if (isLoggedOut) {
+                    this.rejectQueue('session terminated (logged out)');
+                    this.logger.info('session logged out — not reconnecting');
+                }
+                else {
+                    this.reconnectAttempts++;
+                    const delay = Math.min(this.MAX_RECONNECT_DELAY, this.BASE_RECONNECT_DELAY * Math.pow(2, this.reconnectAttempts - 1));
+                    this.logger.info({ delay, attempt: this.reconnectAttempts }, 'scheduling reconnect');
+                    this.reconnectTimer = setTimeout(() => {
+                        this.reconnectTimer = null;
+                        this.start().catch(err => {
+                            this.logger.error({ err }, 'reconnect failed');
+                        });
+                    }, delay);
+                }
+            }
+        });
+    }
+
+    async executeMiddlewares(ctx) {
+        let index = -1;
+        const dispatch = async (i) => {
+            if (i <= index)
+                throw new Error('next() called multiple times');
+            index = i;
+            const middleware = this.middlewares[i];
+            if (middleware) {
+                await middleware(ctx, () => dispatch(i + 1));
+            }
+        };
+        await dispatch(0);
+    }
+
+    /** Gracefully stop the bot */
+    stop() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.rejectQueue('bot stopped');
+        this.store?.close();
+        this.stats?.close();
+    }
+}

package/lib/Framework/Context.js

@@ -0,0 +1,90 @@
+import { MediaManager } from './MediaManager.js';
+
+// Vanz@Port (from @queenanya/baileys Framework, originally Baileys PR #2710
+// by LuferOS) --- message context helper: wraps a WAMessage with reply,
+// react, session, and media helpers so command handlers don't have to touch
+// the raw socket API.
+//
+// Kept from upstream's fix pass:
+//  - text getter also reads imageMessage/videoMessage/documentMessage
+//    captions, so a command sent as an image caption still matches
+//  - reply()/react()/replySticker()/replyVoiceNote() throw when remoteJid is
+//    missing instead of silently no-op'ing, so a handler can't believe a
+//    reply went out when it never did
+export class Context {
+    constructor(bot, message) {
+        this.bot = bot;
+        this.message = message;
+    }
+
+    get remoteJid() {
+        return this.message.key.remoteJid;
+    }
+
+    /** Text content, including image/video/document captions so caption-only commands still match. */
+    get text() {
+        return (this.message.message?.conversation ||
+            this.message.message?.extendedTextMessage?.text ||
+            this.message.message?.imageMessage?.caption ||
+            this.message.message?.videoMessage?.caption ||
+            this.message.message?.documentMessage?.caption ||
+            undefined);
+    }
+
+    get quoted() {
+        return this.message.message?.extendedTextMessage?.contextInfo?.quotedMessage;
+    }
+
+    session() {
+        return this.bot.sessions?.get(this.remoteJid || '');
+    }
+
+    setSession(data) {
+        this.bot.sessions?.set(this.remoteJid || '', data);
+    }
+
+    updateSession(updater) {
+        this.bot.sessions?.update(this.remoteJid || '', updater);
+    }
+
+    clearSession() {
+        this.bot.sessions?.delete(this.remoteJid || '');
+    }
+
+    async reply(content, options) {
+        if (!this.remoteJid)
+            throw new Error('Cannot reply: remoteJid is undefined');
+        await this.bot.sendMessage(this.remoteJid, {
+            ...content
+        }, {
+            quoted: this.message,
+            ...options
+        });
+    }
+
+    async react(emoji) {
+        if (!this.remoteJid)
+            throw new Error('Cannot react: remoteJid is undefined');
+        await this.bot.sendMessage(this.remoteJid, {
+            react: { text: emoji, key: this.message.key }
+        });
+    }
+
+    async replySticker(inputPathOrBuffer, metadata) {
+        if (!this.remoteJid)
+            throw new Error('Cannot reply: remoteJid is undefined');
+        const buffer = await MediaManager.convertToSticker(inputPathOrBuffer, metadata);
+        await this.reply({ sticker: buffer });
+    }
+
+    async replyVoiceNote(inputPathOrBuffer) {
+        if (!this.remoteJid)
+            throw new Error('Cannot reply: remoteJid is undefined');
+        const buffer = await MediaManager.convertToVoiceNote(inputPathOrBuffer);
+        await this.reply({
+            audio: buffer,
+            mimetype: 'audio/ogg; codecs=opus',
+            ptt: true
+        });
+    }
+}