@manybot/manybot 5.6.0 → 5.7.0

package/dist/drivers/baileys/api/index.js

@@ -9,6 +9,7 @@
  * The ctx surface area is preserved so existing plugins stay compatible.
  */
 import { toBotMessage } from "#drivers/baileys/index.js";
+import { decodeContent } from "#drivers/baileys/adapter.js";
 import { logger } from "#logger";
 import { t, createPluginT, reloadTranslations, getCurrentLang } from "#i18n";
 import { CONFIG, CONFIG_DIR } from "#config";
@@ -27,7 +28,7 @@ import { waitForSendSlot, simulateState, typingDuration, mediaDuration, waitForE
 import { sendWithFallback } from "#kernel/sendFallbackGuard.js";
 import { buildSettingsApi } from "#settingsdb";
 import WebP from "node-webpmux";
-import { getAggregateVotesInPollMessage, decryptPollVote, jidNormalizedUser, } from "@whiskeysockets/baileys";
+import { jidNormalizedUser, } from "@whiskeysockets/baileys";
 // ── Raw-Baileys escape hatch ─────────────────────────────────────────────────
 //
 // This whole file is the Baileys driver's plugin-context builder, so the
@@ -222,11 +223,11 @@ function bindGroupMetaInvalidation(contract) {
     if (groupMetaInvalidationBound)
         return;
     groupMetaInvalidationBound = true;
-    const sock = rawSocketOf(contract);
-    const ev = sock.ev;
-    ev.on("group-participants.update", (u) => groupMetaCache.delete(u.id));
-    ev.on("groups.update", (updates) => {
-        for (const u of updates)
+    contract.on("group-participants.update", (u) => {
+        groupMetaCache.delete(u.id);
+    });
+    contract.on("groups.update", (p) => {
+        for (const u of p.updates)
             if (u.id)
                 groupMetaCache.delete(u.id);
     });
@@ -731,22 +732,53 @@ export function buildMessageContext(msg, contract, store, guardOptions = {}) {
     const jitter = guardOptions.jitter ?? true;
     const contextInfo = getContextInfo(msg);
     // Build a synthetic quoted BotMessage when the original envelope carries
-    // a quotedMessage (the adapter pre-decoded it into msg.quotedKey).
-    const quotedRaw = msg.quotedKey
-        ? {
-            id: msg.quotedKey.id ?? "",
-            chatId: msg.chatId,
-            fromMe: false,
-            type: "other",
-            contentHash: "",
-            timestamp: 0,
-            _raw: msg._raw ? {
-                quotedMessage: msg._raw.quotedMessage,
-                stanzaId: msg._raw.stanzaId,
-                participant: msg._raw.participant,
-            } : undefined,
-        }
-        : null;
+    // a quotedMessage (the adapter pre-decodes the full IContextInfo into
+    // msg._raw.contextInfo). The synthetic uses the same decodeContent
+    // helper as toBotMessage so type/body/mimetype reflect what's actually
+    // in the quoted payload — without this, msgHasMedia()/downloadMedia()
+    // on the result of getReply() always reported type=other / no media,
+    // even when the quoted message was an image/video/document/etc.
+    //
+    // We carry the same _raw.contextInfo on the synthetic so a recursive
+    // getReply().getReply() keeps working (the inner call re-reads
+    // getContextInfo off _raw.contextInfo).
+    const quotedRaw = contextInfo?.quotedMessage
+        ? (() => {
+            const decoded = decodeContent(contextInfo.quotedMessage);
+            return {
+                id: contextInfo.stanzaId ?? "",
+                chatId: msg.chatId,
+                fromMe: false,
+                type: decoded.type,
+                contentHash: "",
+                timestamp: 0,
+                body: decoded.body,
+                mimetype: decoded.mimetype,
+                _raw: {
+                    contextInfo: {
+                        stanzaId: contextInfo.stanzaId,
+                        participant: contextInfo.participant,
+                        mentionedJid: contextInfo.mentionedJid,
+                        quotedMessage: contextInfo.quotedMessage,
+                    },
+                },
+            };
+        })()
+        : msg.quotedKey
+            // No embedded quotedMessage (older envelopes, evicted from store, or
+            // the quoted message pre-dates contextInfo-quoting). Fall back to a
+            // key-only synthetic so hasReply()/getReply() still work, but
+            // hasMedia/downloadMedia on the result will degrade gracefully
+            // (type=other, mimetype=undefined).
+            ? {
+                id: msg.quotedKey.id ?? "",
+                chatId: msg.chatId,
+                fromMe: false,
+                type: "other",
+                contentHash: "",
+                timestamp: 0,
+            }
+            : null;
     return {
         id: msg.id,
         timestamp: msg.timestamp || 0,
@@ -1289,20 +1321,58 @@ function buildSetupSendApi(contract, store) {
         },
     };
 }
-// ── Events API ────────────────────────────────────────────────────────────────
+const WA_EVENT_NAMES = new Set([
+    "messages.upsert",
+    "messages.update",
+    "messages.delete",
+    "messaging-history.set",
+    "chats.upsert",
+    "chats.update",
+    "chats.delete",
+    "contacts.upsert",
+    "contacts.update",
+    "group-participants.update",
+    "groups.upsert",
+    "groups.update",
+    "group.join-request",
+    "blocklist.set",
+    "blocklist.update",
+    "connection.update",
+]);
+function assertSupportedEvent(event) {
+    if (!WA_EVENT_NAMES.has(event)) {
+        throw new Error(`[events] unsupported event "${event}". Supported: ${[...WA_EVENT_NAMES].join(", ")}. ` +
+            `If you need this event, file an issue — adding events to WaEventName is a contract change.`);
+    }
+}
 const listenerRegistry = new Map();
-export function cleanupPluginEvents(pluginName, contract) {
-    const sock = rawSocketOf(contract);
+export function cleanupPluginEvents(pluginName, _contract) {
     const list = listenerRegistry.get(pluginName);
     if (list) {
-        for (const { event, handler } of list) {
+        for (const ref of list) {
             try {
-                sock.ev.off(event, handler);
+                ref.detach();
             }
             catch { }
         }
         listenerRegistry.delete(pluginName);
     }
+    // The poll-vote subscription is created in `buildPollApi` by calling
+    // `contract.on(...)` directly, so it lives outside `listenerRegistry`.
+    // Detach it here so the listener doesn't outlive the plugin (and a
+    // reloaded plugin can re-subscribe — `buildPollApi` gates on the
+    // `boundPollPlugins` map).
+    const pollDetach = boundPollPlugins.get(pluginName);
+    if (pollDetach) {
+        try {
+            pollDetach();
+        }
+        catch { }
+        boundPollPlugins.delete(pluginName);
+    }
+    // Drop the per-plugin poll registry so reloading a plugin doesn't see
+    // stale PollHandles from a prior instance.
+    pollRegistry.delete(pluginName);
     cancelPlugin(pluginName);
 }
 /**
@@ -1310,21 +1380,26 @@ export function cleanupPluginEvents(pluginName, contract) {
  * @param {string}     pluginName
  */
 function buildEventsApi(contract, pluginName) {
-    const sock = rawSocketOf(contract);
     return {
         on(event, handler) {
-            sock.ev.on(event, handler);
+            assertSupportedEvent(event);
+            const wrapped = (payload) => handler(payload);
+            const detach = contract.on(event, wrapped);
             if (!listenerRegistry.has(pluginName))
                 listenerRegistry.set(pluginName, new Set());
-            const ref = { event, handler };
+            const ref = { event, handler: wrapped, detach };
             listenerRegistry.get(pluginName).add(ref);
             return () => {
-                sock.ev.off(event, handler);
+                try {
+                    detach();
+                }
+                catch { }
                 listenerRegistry.get(pluginName)?.delete(ref);
             };
         },
         once(event) {
-            return new Promise(resolve => {
+            assertSupportedEvent(event);
+            return new Promise((resolve) => {
                 const off = this.on(event, (data) => { off(); resolve(data); });
             });
         },
@@ -1332,8 +1407,12 @@ function buildEventsApi(contract, pluginName) {
             const list = listenerRegistry.get(pluginName);
             if (!list)
                 return;
-            for (const { event, handler } of list)
-                sock.ev.off(event, handler);
+            for (const ref of list) {
+                try {
+                    ref.detach();
+                }
+                catch { }
+            }
             listenerRegistry.delete(pluginName);
         },
     };
@@ -1531,11 +1610,15 @@ function buildMeApi(contract) {
 }
 // ── Poll API ──────────────────────────────────────────────────────────────────
 const pollRegistry = new Map();
-// Rebinding must happen per socket instance — a plugin name alone doesn't
-// tell us whether the listener is bound to the CURRENT (post-reconnect)
-// sock.ev or a dead one from before. WeakMap keyed by sock lets old
-// entries fall off automatically once that socket is garbage collected.
-const pollListenersBySocket = new WeakMap();
+// Per-process map of plugin names whose poll-vote subscription is bound,
+// to its unsubscribe handle. The contract handles rebinding to a fresh
+// socket on reconnect (its `on()` returns an unsubscribe that drops
+// cleanly on the dead socket's fan-out once it's torn down), so a simple
+// per-process map is enough — no per-sock WeakMap needed anymore.
+// `cleanupPluginEvents` MUST call the stored detach handle on unload so
+// the listener doesn't outlive the plugin and so a reloaded plugin can
+// re-subscribe.
+const boundPollPlugins = new Map();
 /**
  * Tracks votes for an active poll.
  * Obtained via ctx.poll.create().
@@ -1606,59 +1689,29 @@ function buildPollApi(contract, store, rawJid, guardOptions, pluginName) {
         pollRegistry.set(pluginName, new Map());
     const registry = pollRegistry.get(pluginName);
     // Keyed by creationId -> (voterKey -> latest vote entry). WhatsApp resends
-    // the *entire current selection* on every tap (not a diff), and Baileys'
-    // getAggregateVotesInPollMessage() replays whatever pollUpdates you give it
-    // with no dedup — so we must keep only the latest entry per voter ourselves,
-    // or retracted/changed votes keep counting alongside the new one.
+    // the *entire current selection* on every tap (not a diff), and the
+    // aggregatePollVotes() contract method replays whatever pollUpdates you
+    // give it with no dedup — so we must keep only the latest entry per
+    // voter ourselves, or retracted/changed votes keep counting alongside
+    // the new one.
     const pollVotesByCreationId = new Map();
-    // Poll decryption needs the raw Baileys socket (sock.ev for
-    // messages.upsert, sock.user for self-JID shape), so we lift it off the
-    // contract here. The WeakMap key is the socket itself so old listeners
-    // fall off automatically when the socket is replaced (reconnect).
-    const sock = rawSocketOf(contract);
-    let boundPlugins = pollListenersBySocket.get(sock);
-    if (!boundPlugins) {
-        boundPlugins = new Set();
-        pollListenersBySocket.set(sock, boundPlugins);
-    }
-    if (!boundPlugins.has(pluginName)) {
-        boundPlugins.add(pluginName);
-        const meId = sock.user?.id ? jidNormalizedUser(sock.user.id) : "me";
-        // WhatsApp doesn't consistently use the same JID shape (LID vs PN) for
-        // pollCreatorJid/voterJid when deriving the poll-vote decryption key —
-        // it depends on addressingMode, 1:1 vs group, and which side sent last.
-        // Trying to compute "the" correct JID up front (as the old resolveAuthor
-        // did, always preferring participantPn) causes AES-GCM auth failures
-        // whenever WhatsApp actually used the LID for that message. Instead,
-        // gather every plausible JID for each side and brute-force combinations
-        // until one decrypts successfully — see
-        // https://github.com/WhiskeySockets/Baileys/issues/2342 and #1678.
-        function jidCandidates(key) {
-            const cands = [];
-            if (key.fromMe) {
-                const selfLid = sock.user?.lid;
-                if (selfLid)
-                    cands.push(jidNormalizedUser(selfLid));
-                if (sock.user?.id)
-                    cands.push(jidNormalizedUser(sock.user.id));
-            }
-            else {
-                const rawParticipant = key.participant ?? key.remoteJid;
-                if (rawParticipant)
-                    cands.push(jidNormalizedUser(rawParticipant));
-                if (key.participantPn)
-                    cands.push(jidNormalizedUser(key.participantPn));
-                if (rawParticipant?.endsWith("@lid")) {
-                    const resolved = store.resolveJid(rawParticipant);
-                    if (resolved && resolved !== rawParticipant)
-                        cands.push(jidNormalizedUser(resolved));
-                }
-            }
-            return Array.from(new Set(cands.filter(Boolean)));
-        }
-        sock.ev.on("messages.upsert", async ({ messages: msgs }) => {
+    // Poll decryption is Baileys-specific. Both the subscription
+    // (`messages.upsert`) and the decryption/aggregation go through the
+    // contract — `buildPollApi` doesn't touch the raw socket anymore. The
+    // contract's optional methods are only implemented by the Baileys
+    // adapter; drivers that don't have poll decryption leave them off the
+    // contract and we silently no-op here (a bot on a non-Baileys driver
+    // simply can't track poll votes).
+    if (!boundPollPlugins.has(pluginName) &&
+        typeof contract.decryptPollVote === "function" &&
+        typeof contract.aggregatePollVotes === "function") {
+        const detach = contract.on("messages.upsert", async ({ messages: msgs }) => {
             for (const msg of msgs) {
-                const pum = msg.message?.pollUpdateMessage;
+                // Filter poll-update messages by reading the raw envelope from
+                // the store (the neutral `BotMessage` doesn't carry the
+                // `pollUpdateMessage` field — it's a Baileys-proto detail).
+                const raw = store.messages.get(msg.chatId)?.get(msg.id);
+                const pum = raw?.message?.pollUpdateMessage;
                 if (!pum)
                     continue;
                 const creationKey = pum.pollCreationMessageKey;
@@ -1671,44 +1724,44 @@ function buildPollApi(contract, store, rawJid, guardOptions, pluginName) {
                 if (!storeMsg || !pollEncKeyRaw || !pum.vote)
                     continue;
                 try {
-                    const pollEncKey = Buffer.isBuffer(pollEncKeyRaw)
-                        ? pollEncKeyRaw
-                        : Buffer.from(pollEncKeyRaw, "base64");
-                    const creatorCandidates = jidCandidates((creationKey ?? {}));
-                    const voterCandidates = jidCandidates(msg.key);
-                    let decryptedVote;
-                    for (const pollCreatorJid of creatorCandidates) {
-                        for (const voterJid of voterCandidates) {
-                            try {
-                                decryptedVote = decryptPollVote(pum.vote, {
-                                    pollEncKey,
-                                    pollCreatorJid,
-                                    pollMsgId: creationId,
-                                    voterJid,
-                                });
-                                break;
-                            }
-                            catch {
-                                // try next JID combination
-                            }
-                        }
-                        if (decryptedVote)
-                            break;
-                    }
-                    if (!decryptedVote) {
-                        throw new Error(`all JID combinations failed (creator=${JSON.stringify(creatorCandidates)}, voter=${JSON.stringify(voterCandidates)})`);
+                    const decrypted = await contract.decryptPollVote({
+                        voteKey: {
+                            id: msg.id,
+                            remoteJid: msg.chatId,
+                            fromMe: msg.fromMe,
+                            participant: msg.participantAlt ?? msg.fromLid ?? msg.fromPn ?? null,
+                        },
+                        pollKey: {
+                            id: creationId,
+                            remoteJid: creationKey?.remoteJid ?? null,
+                            fromMe: null,
+                            participant: creationKey?.participant ?? null,
+                        },
+                        pollEncKey: pollEncKeyRaw,
+                    });
+                    if (!decrypted) {
+                        throw new Error("decryptPollVote returned null — JID candidate exhaustion or stale enc key");
                     }
-                    const voterKey = msg.key.fromMe
-                        ? meId
-                        : jidNormalizedUser(msg.key.participant ?? msg.key.remoteJid ?? "");
+                    const voterKey = msg.fromMe
+                        ? (contract.me().id ?? "me")
+                        : jidNormalizedUser(msg.participantAlt ?? msg.fromLid ?? msg.chatId);
                     const votesByVoter = pollVotesByCreationId.get(creationId) ?? new Map();
                     votesByVoter.set(voterKey, {
-                        pollUpdateMessageKey: msg.key,
-                        vote: decryptedVote,
+                        pollUpdateMessageKey: { id: msg.id, remoteJid: msg.chatId, fromMe: msg.fromMe },
+                        vote: decrypted,
                         senderTimestampMs: pum.senderTimestampMs,
                     });
                     pollVotesByCreationId.set(creationId, votesByVoter);
-                    const aggregated = getAggregateVotesInPollMessage({ message: storeMsg.message, pollUpdates: Array.from(votesByVoter.values()) }, meId);
+                    const pollAggregateOpts = contract.aggregatePollVotes;
+                    const aggregated = pollAggregateOpts({
+                        pollKey: {
+                            id: creationId,
+                            remoteJid: creationKey?.remoteJid ?? null,
+                            fromMe: null,
+                        },
+                        votes: Array.from(votesByVoter.values()).map((v) => v.vote),
+                        selfJid: contract.me().id ?? undefined,
+                    });
                     handle._updateFromAggregated(aggregated);
                 }
                 catch (err) {
@@ -1716,6 +1769,7 @@ function buildPollApi(contract, store, rawJid, guardOptions, pluginName) {
                 }
             }
         });
+        boundPollPlugins.set(pluginName, detach);
     }
     const cooldown = (guardOptions.cooldown ?? true);
     const jitter = (guardOptions.jitter ?? true);
@@ -1831,25 +1885,6 @@ export function buildApi({ msg, chat, contract, store, pluginRegistry, pluginNam
     const cooldown = (guardOptions.cooldown ?? true);
     const jitter = (guardOptions.jitter ?? true);
     bindGroupMetaInvalidation(contract);
-    // Sender for quoted messages — synthesize a neutral BotQuotedRef off
-    // the adapter's pre-extracted contextInfo fields. No raw Baileys
-    // envelope access needed here.
-    const contextInfo = getContextInfo(msg);
-    const quotedRaw = contextInfo?.quotedMessage
-        ? {
-            id: contextInfo.stanzaId ?? "",
-            chatId: msg.chatId,
-            fromMe: false,
-            type: "other",
-            contentHash: "",
-            timestamp: 0,
-            _raw: {
-                quotedMessage: contextInfo.quotedMessage,
-                stanzaId: contextInfo.stanzaId,
-                participant: contextInfo.participant,
-            },
-        }
-        : null;
     // Group participant JIDs come back in whatever addressing mode the group
     // uses (@lid or @s.whatsapp.net/@c.us) — same issue as poll vote decryption.
     // "sender" and the bot's own JID are usually PN-normalized, so a straight

package/dist/drivers/baileys/index.js

@@ -27,6 +27,7 @@ import { normalizeJid } from "#drivers/jid.js";
 import { loadPlugins, setupPlugins } from "#kernel/pluginLoader.js";
 import { runContactRefreshSweep } from "#kernel/contactAutoSave.js";
 import { registerAlertSockProvider, sendAlert } from "#kernel/alerts.js";
+import { getDriverManager } from "#kernel/driverManager.js";
 import { startUpdateCheckSchedule, stopUpdateCheckSchedule } from "#kernel/updateCheck.js";
 import { setStatus } from "#kernel/statusServer.js";
 import { logger } from "#logger";
@@ -93,6 +94,12 @@ const RECONNECT_MAX_MS = 60000;
 // silently retrying past this point can make a restriction last longer.
 const MAX_RECONNECT_ATTEMPTS = 6;
 const CACHE_SAVE_INTERVAL_MS = 5 * 60 * 1000; // 5min
+// Track consecutive restartRequired (515) — same counter space as
+// reconnectAttempts but with a lower threshold for degradation since
+// repeated 515 signals a protocol drift the current session can't
+// recover from on its own.
+const MAX_RESTART_REQUIRED = 3;
+let restartRequiredCount = 0;
 /**
  * Loads the on-disk cache and merges it into `store` (union, never
  * overwrite — see client/cache.ts). Runs once per process: the shared
@@ -193,6 +200,7 @@ async function startBot() {
         if (connection === "open") {
             state = "READY_INIT";
             reconnectAttempts = 0;
+            restartRequiredCount = 0;
             setStatus(true);
             logger.success(t("system.connected"));
             logger.info(t("system.clientId", { id: CLIENT_ID }));
@@ -211,11 +219,19 @@ async function startBot() {
         if (connection === "close") {
             const code = lastDisconnect?.error?.output?.statusCode;
             const loggedOut = code === DisconnectReason.loggedOut;
+            const badSession = code === DisconnectReason.badSession;
+            const restartReq = code === DisconnectReason.restartRequired;
             state = "BOOT";
             setStatus(false, String(code));
             logger.warn(t("system.disconnected", { reason: String(code) }));
-            if (loggedOut) {
-                logger.warn(t("system.sessionExpired"));
+            if (loggedOut || badSession) {
+                if (badSession) {
+                    logger.warn("Session data corrupted (badSession=500). Clearing session dir.");
+                    getDriverManager().markDegraded("baileys", 300_000);
+                }
+                else {
+                    logger.warn(t("system.sessionExpired"));
+                }
                 try {
                     await fs.rm(AUTH_DIR, { recursive: true, force: true });
                 }
@@ -224,9 +240,27 @@ async function startBot() {
                 }
                 scheduleReconnect(1000);
             }
+            else if (restartReq) {
+                restartRequiredCount++;
+                if (restartRequiredCount >= MAX_RESTART_REQUIRED) {
+                    halted = true;
+                    logger.error(`restartRequired (515) recurring — protocol drift suspected. Halting.`);
+                    getDriverManager().markDegraded("baileys", 600_000);
+                    sendAlert({
+                        level: "critical",
+                        title: "manybot — restartRequired recurring",
+                        message: `Protocol drift suspected after ${restartRequiredCount}x restartRequired. Bot halted on Baileys. Run connect() manually.`,
+                    }).catch(() => { });
+                    return;
+                }
+                const delay = Math.min(500, RECONNECT_BASE_MS);
+                logger.info(t("system.reconnecting", { secs: Math.round(delay / 1000) }));
+                scheduleReconnect(delay);
+            }
             else if (!shuttingDown) {
                 if (reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
                     halted = true;
+                    getDriverManager().markDegraded("baileys", 600_000);
                     logger.error(t("system.reconnectHalted", { attempts: reconnectAttempts }));
                     sendAlert({
                         level: "critical",

package/dist/drivers/baileys/sdk/baileysSock.js

@@ -19,7 +19,7 @@ import pino from "pino";
 // setMaxListeners (see the comment in createSocket() below) — raised
 // globally instead, before makeWASocket() ever constructs one.
 EventEmitter.defaultMaxListeners = 50;
-export const AUTH_DIR = path.join(CONFIG_DIR, "sessions", CLIENT_ID);
+export const AUTH_DIR = path.join(CONFIG_DIR, "sessions", CLIENT_ID, "baileys");
 // ── Shared store (survives socket reconnects) ─────────────────────────────────
 export const store = createStore();
 /**

package/dist/drivers/whatsmeow/client.js

@@ -1,9 +1,11 @@
 import { logger } from "#logger";
 import { CONFIG } from "#config";
+import { t } from "#i18n";
 import * as grpc from "@grpc/grpc-js";
 import * as protoLoader from "@grpc/proto-loader";
 import path from "path";
 import { fileURLToPath } from "node:url";
+import qrcode from "qrcode-terminal";
 /**
  * Whatsmeow gRPC client implementing the WaContract interface.
  *
@@ -50,7 +52,7 @@ class WhatsmeowClient {
         const address = CONFIG.drivers.whatsmeow.grpcAddress ?? "localhost:50051";
         const Service = this.loadProto();
         this.client = new Service(address, grpc.credentials.createInsecure());
-        // Perform a health check to confirm service is ready
+        // 1. Health check — confirm the gRPC server is up
         await new Promise((resolve, reject) => {
             this.client.HealthCheck({}, (err, resp) => {
                 if (err)
@@ -62,12 +64,43 @@ class WhatsmeowClient {
                     reject(new Error("Whatsmeow service not ready"));
             });
         });
-        logger.info("[whatsmeow] connected via gRPC");
-        // Open the server-streaming event subscription. Each WaEvent that
-        // arrives is fanned out to the local on() subscribers in the
-        // neutral envelope shape.
+        logger.info("[whatsmeow] gRPC service ready");
+        // 2. Call Connect RPC — initiates WhatsApp auth (QR or reuse existing session)
+        const connectResp = await new Promise((resolve, reject) => {
+            this.client.Connect({}, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve(resp);
+            });
+        });
+        const needsAuth = !connectResp.ok;
+        if (needsAuth && connectResp.qrCode) {
+            logger.info(t("system.qrScan"));
+            qrcode.generate(connectResp.qrCode, { small: true });
+        }
+        // 3. Set up auth deferred BEFORE SubscribeEvents to avoid race
+        let authDeferred = null;
+        let authDone = false;
+        const authPromise = needsAuth
+            ? new Promise((resolve, reject) => {
+                authDeferred = { resolve, reject };
+                setTimeout(() => {
+                    if (!authDone) {
+                        authDone = true;
+                        reject(new Error("Whatsmeow auth timeout (2 min)"));
+                    }
+                }, 120_000);
+            })
+            : Promise.resolve();
+        // 4. Open the server-streaming event subscription
         const stream = this.client.SubscribeEvents({});
         stream.on("data", (raw) => {
+            // Resolve auth promise when connection opens (QR scanned / session reused)
+            if (!authDone && authDeferred && raw.connState?.state === "open") {
+                authDone = true;
+                authDeferred.resolve();
+                authDeferred = null;
+            }
             try {
                 if (raw.connState) {
                     const state = raw.connState.state ?? "connecting";
@@ -87,13 +120,29 @@ class WhatsmeowClient {
             }
         });
         stream.on("error", (err) => {
+            if (!authDone) {
+                authDone = true;
+                authDeferred?.reject(err);
+                authDeferred = null;
+            }
             logger.warn(`[whatsmeow] event stream error: ${err.message}`);
             this.ready = false;
         });
         stream.on("end", () => {
+            if (!authDone) {
+                authDone = true;
+                authDeferred?.reject(new Error("Event stream ended before auth completed"));
+                authDeferred = null;
+            }
             logger.warn(`[whatsmeow] event stream ended`);
             this.ready = false;
         });
+        // 5. If not authenticated, wait for connState === "open" from the event stream
+        await authPromise;
+        if (needsAuth) {
+            logger.info("[whatsmeow] authenticated");
+        }
+        this.ready = true;
     }
     async disconnect() {
         if (this.client) {