@manybot/manybot 5.5.4 → 5.6.1

package/dist/drivers/{whatsapp → baileys}/api/index.js

@@ -1,5 +1,5 @@
 /**
- * drivers/whatsapp/api/index.ts
+ * drivers/baileys/api/index.ts
  *
  * WhatsApp plugin context builder.
  * Exports buildApi() and buildSetupApi() for the WhatsApp driver.
@@ -8,23 +8,15 @@
  * All wwjs types have been replaced with Baileys equivalents.
  * 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";
 import { enqueue } from "#download";
 import { schedule, cancelPlugin } from "#kernel/scheduler.js";
 import { emptyFolder } from "#utils/file.js";
-import { normalizeJid, toPresenceCapable } from "../sdk/baileysSock.js";
-// store.contacts is keyed by whatever raw JID Baileys handed the store
-// (e.g. "...@s.whatsapp.net" for a normal DM) — never run through
-// normalizeJid. Every lookup here works in normalized ("...@c.us") form,
-// so a plain `store.contacts[normalizedId]` misses for any non-@lid
-// contact. @lid contacts don't hit this: normalizeJid doesn't touch
-// "@lid", so the raw store key already matches. Used as a fallback key
-// alongside the normalized one wherever we read store.contacts directly.
-function denormalizeJid(jid) {
-    return jid.replace(/@c\.us$/, "@s.whatsapp.net");
-}
+import { normalizeJid, denormalizeJid, toWireJid } from "#drivers/jid.js";
 import { mkdirSync } from "fs";
 import { readFile, writeFile, unlink, mkdtemp, rm } from "fs/promises";
 import { readFileSync } from "fs";
@@ -32,92 +24,175 @@ import path from "path";
 import os from "os";
 import { spawn } from "child_process";
 import { randomUUID } from "crypto";
-import { waitForSendSlot, simulateState, typingDuration, mediaDuration } from "#sendguard";
+import { waitForSendSlot, simulateState, typingDuration, mediaDuration, waitForEditSlot } from "#sendguard";
+import { sendWithFallback } from "#kernel/sendFallbackGuard.js";
 import { buildSettingsApi } from "#settingsdb";
 import WebP from "node-webpmux";
-import { downloadMediaMessage, getAggregateVotesInPollMessage, decryptPollVote, jidNormalizedUser, normalizeMessageContent } from "@whiskeysockets/baileys";
-// ── Message body / type helpers ───────────────────────────────────────────────
-// WhatsApp wraps media in ephemeralMessage/viewOnceMessage/etc when sent as
-// disappearing or view-once — the actual imageMessage/videoMessage/... sits
-// one level deeper. Reading msg.message directly misses all of that (this
-// was the cause of hasMedia silently returning false for such messages).
-function unwrap(msg) {
-    return normalizeMessageContent(msg.message) ?? undefined;
+import { getAggregateVotesInPollMessage, decryptPollVote, jidNormalizedUser, } from "@whiskeysockets/baileys";
+// ── Raw-Baileys escape hatch ─────────────────────────────────────────────────
+//
+// This whole file is the Baileys driver's plugin-context builder, so the
+// few operations that don't have a driver-neutral equivalent yet (poll
+// decryption, gif detection, message envelope decoding for the helpers
+// above) need direct access to the underlying WASocket. The WaContract
+// intentionally doesn't expose the raw socket — but the adapter that
+// builds it from a real Baileys socket hangs the socket off a private
+// symbol so we can pull it back here without leaking Baileys types
+// through the kernel/pluginApi surface.
+//
+// Defined as a separate symbol so the rest of the kernel can still
+// import the WaContract without ever knowing this exists.
+const RAW_SOCK = Symbol.for("manybot.baileys.rawSocket");
+function rawSocketOf(contract) {
+    const sock = contract[RAW_SOCK];
+    if (!sock) {
+        throw new Error("[baileys/api] WaContract has no raw socket attached — only the Baileys adapter provides one.");
+    }
+    return sock;
+}
+/**
+ * Pull a Baileys-shaped message envelope off a `BotMessage._raw` when an
+ * api-layer helper needs fields the neutral envelope intentionally
+ * doesn't model (poll enc key, gifPlayback flag, …). The store still
+ * stores the raw `WAMessage` keyed by jid+id, so the common case is
+ * to read it back from there.
+ */
+function rawMsgOf(msg, store) {
+    const raw = store.messages.get(msg.chatId)?.get(msg.id);
+    return raw;
+}
+/**
+ * Convert a `BotMessage` (driver-neutral incoming envelope) into a
+ * `BotQuotedRef` (driver-neutral outgoing reference), used as the
+ * `quoted` argument to the contract's send methods. The fields the
+ * adapter pre-extracts (id, chatId, fromMe, participantAlt/fromLid/
+ * fromPn) are enough for the protocol — no raw Baileys access needed.
+ */
+function quotedRefFromMsg(msg) {
+    return {
+        id: msg.id,
+        remoteJid: msg.chatId,
+        fromMe: msg.fromMe,
+        participant: msg.participantAlt ?? msg.fromLid ?? msg.fromPn ?? null,
+    };
 }
+/**
+ * Read the just-sent message off the store after a `contract.sendX()`
+ * call resolves with a `SentMessageRef` (id + chatId + timestamp).
+ * Mirrors the text path's polling window — the driver's own
+ * `messages.upsert` handler writes the freshly-sent WAMessage into
+ * the store keyed by chatId+id, but that write may not have landed
+ * on the very next tick.
+ */
+async function refToBotMessage(ref, store) {
+    const deadline = Date.now() + 200;
+    while (Date.now() < deadline) {
+        const stored = store.messages.get(ref.chatId)?.get(ref.id);
+        if (stored)
+            return toBotMessage(stored);
+        await new Promise(r => setTimeout(r, 20));
+    }
+    const final = store.messages.get(ref.chatId)?.get(ref.id);
+    return final ? toBotMessage(final) : undefined;
+}
+// ── Message body / type helpers ───────────────────────────────────────────────
+//
+// Helpers read the neutral `BotMessage` envelope. Fields the neutral
+// envelope intentionally doesn't model (poll enc key, gifPlayback,
+// messageSecret) are pulled out of the raw store entry when needed —
+// the adapter fills `BotMessage._raw` with the bits a Baileys-side
+// consumer might need (poll enc key) and leaves the rest on the raw
+// WAMessage in the store.
 function getMsgBody(msg) {
-    const m = unwrap(msg);
-    if (!m)
-        return "";
-    return (m.conversation ??
-        m.extendedTextMessage?.text ??
-        m.imageMessage?.caption ??
-        m.videoMessage?.caption ??
-        m.documentMessage?.caption ??
-        m.buttonsResponseMessage?.selectedDisplayText ??
-        m.listResponseMessage?.title ??
-        "");
+    // The adapter pre-extracts the body into `BotMessage.body`, so the
+    // common path is one field read. Fall back to the raw store entry only
+    // if the body wasn't populated (older code paths that built the
+    // envelope by hand).
+    if (msg.body !== undefined)
+        return msg.body;
+    return msg.body ?? "";
 }
 function getMsgType(msg) {
-    const m = unwrap(msg);
-    if (!m)
-        return "unknown";
-    if (m.conversation || m.extendedTextMessage)
-        return "chat";
-    if (m.buttonsResponseMessage || m.listResponseMessage)
-        return "chat";
-    if (m.imageMessage)
-        return "image";
-    if (m.videoMessage)
-        return "video";
-    if (m.audioMessage)
-        return "audio";
-    if (m.stickerMessage)
-        return "sticker";
-    if (m.documentMessage)
-        return "document";
-    if (m.pollCreationMessage ||
-        m.pollCreationMessageV2 ||
-        m.pollCreationMessageV3)
-        return "poll";
-    if (m.locationMessage || m.liveLocationMessage)
-        return "location";
-    if (m.contactMessage)
-        return "vcard";
-    if (m.contactsArrayMessage)
-        return "multi_vcard";
-    if (m.protocolMessage?.type === 0)
-        return "revoked"; // REVOKE
-    return "unknown";
+    // body-style text vs extendedTextMessage, buttons vs list response, etc.
+    // — these distinctions live on the raw envelope, since the neutral
+    // `type` only models the high-level kind (text/image/video/...).
+    const raw = msg._raw?.kind;
+    if (raw)
+        return raw;
+    switch (msg.type) {
+        case "text": return "chat";
+        case "image": return "image";
+        case "video": return "video";
+        case "audio": return "audio";
+        case "sticker": return "sticker";
+        case "document": return "document";
+        default: return "unknown";
+    }
 }
 function msgHasMedia(msg) {
-    const m = unwrap(msg);
-    return !!(m?.imageMessage || m?.videoMessage || m?.audioMessage || m?.documentMessage || m?.stickerMessage);
+    return msg.type === "image" || msg.type === "video" || msg.type === "audio" || msg.type === "document" || msg.type === "sticker";
 }
-function msgIsGif(msg) {
-    return !!(unwrap(msg)?.videoMessage?.gifPlayback);
+function msgIsGif(msg, store) {
+    const raw = rawMsgOf(msg, store);
+    if (!raw)
+        return false;
+    // gifPlayback is a Baileys-specific flag — read it off the raw
+    // WAMessage directly.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return !!raw.message?.videoMessage?.gifPlayback;
 }
 /** Sender JID — group participant or DM remote JID, normalized. */
 function getMsgSender(msg, store) {
-    const raw = normalizeJid(msg.key.participant || msg.key.remoteJid || "");
-    return normalizeJid(store.resolveJid(raw));
+    // Prefer the @s.whatsapp.net form when we know it (Baileys-advisor split
+    // exposes both forms on incoming messages). The adapter fills
+    // `fromPn` when known; fall back to `chatId` for DMs.
+    const participant = msg._raw?.key?.participant
+        ?? msg.fromPn;
+    const raw = participant ?? msg.chatId;
+    return normalizeJid(store.resolveJid(normalizeJid(raw)));
+}
+/** Quoted-message metadata as the rest of the api uses it. */
+function getQuotedContext(msg) {
+    if (!msg.quotedKey)
+        return null;
+    return {
+        id: msg.quotedKey.id ?? null,
+        remoteJid: msg.chatId,
+        fromMe: false,
+        participant: msg._raw?.contextInfo?.participant ?? null,
+    };
 }
 function getContextInfo(msg) {
-    const m = unwrap(msg);
-    return (m?.extendedTextMessage?.contextInfo ??
-        m?.imageMessage?.contextInfo ??
-        m?.videoMessage?.contextInfo ??
-        m?.audioMessage?.contextInfo ??
-        m?.documentMessage?.contextInfo ??
-        null);
+    // The context info lives on the raw envelope (it carries mentions,
+    // stanzaId, etc.). The adapter doesn't pre-extract it because no
+    // neutral consumer needs it — pull it on demand from the store.
+    const raw = msg._raw?.contextInfo;
+    return raw ?? null;
+}
+/** True if the message has any @mention at all. */
+function hasMention(contextInfo) {
+    const ci = contextInfo;
+    return !!(ci?.mentionedJid && Array.isArray(ci.mentionedJid) && ci.mentionedJid.length > 0);
+}
+/** True if the bot's own JID (PN or LID) is in contextInfo.mentionedJid. */
+function hasBotMention(contextInfo, sock, store) {
+    const ci = contextInfo;
+    const mentioned = ci?.mentionedJid;
+    if (!mentioned || mentioned.length === 0)
+        return false;
+    const botLid = sock.user?.lid;
+    const botCandidates = [sock.user?.id, botLid]
+        .filter((v) => !!v)
+        .map(v => normalizeJid(store.resolveJid(normalizeJid(v))));
+    if (botCandidates.length === 0)
+        return false;
+    return mentioned.some(jid => {
+        const resolved = normalizeJid(store.resolveJid(normalizeJid(jid)));
+        return botCandidates.includes(resolved);
+    });
 }
 function getMsgMimetype(msg) {
-    const m = unwrap(msg);
-    return (m?.imageMessage?.mimetype ??
-        m?.videoMessage?.mimetype ??
-        m?.audioMessage?.mimetype ??
-        m?.documentMessage?.mimetype ??
-        m?.stickerMessage?.mimetype ??
-        "application/octet-stream");
+    return msg.mimetype ?? "application/octet-stream";
 }
 // ── Chat adapter builder ──────────────────────────────────────────────────────
 // Group subjects only land in `store.chats` once Baileys fires chats.upsert
@@ -131,19 +206,24 @@ const GROUP_NAME_CACHE_TTL_MS = 5 * 60 * 1000;
 const groupNameCache = new Map();
 const GROUP_META_CACHE_TTL_MS = 5 * 60 * 1000;
 const groupMetaCache = new Map();
-async function getGroupMetadataCached(sock, jid) {
+async function getGroupMetadataCached(contract, jid) {
     const cached = groupMetaCache.get(jid);
     if (cached && Date.now() - cached.at < GROUP_META_CACHE_TTL_MS)
         return cached.meta;
+    // Go through the raw sock for the Baileys-flavored metadata (carries
+    // pn/phoneNumber which the neutral contract drops). The neutral
+    // contract's groupMetadata is used everywhere the kernel asks for it.
+    const sock = rawSocketOf(contract);
     const meta = await sock.groupMetadata(jid);
     groupMetaCache.set(jid, { meta, at: Date.now() });
     return meta;
 }
 let groupMetaInvalidationBound = false;
-function bindGroupMetaInvalidation(sock) {
+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) => {
@@ -153,17 +233,17 @@ function bindGroupMetaInvalidation(sock) {
     });
 }
 /**
- * Build a WAChat adapter from a Baileys message + store.
+ * Build a WAChat adapter from a BotMessage + store.
  * Exposed for use in messageHandler.ts.
  *
- * @param {WAProtoMsg} msg
- * @param {WAStore}    store
- * @param {WASocket}   sock
+ * @param {BotMessage}  msg
+ * @param {BotStore}    store
+ * @param {WaContract}  contract
  * @returns {Promise<WAChat>}
  */
-export async function buildChatFromMsg(msg, store, sock) {
-    const rawJid = msg.key.remoteJid ?? "";
-    const jid = normalizeJid(rawJid);
+export async function buildChatFromMsg(msg, store, contract) {
+    const rawJid = msg.chatId;
+    const jid = normalizeJid(store.resolveJid(rawJid));
     const user = jid.split("@")[0];
     const isGroup = rawJid.endsWith("@g.us");
     // Try to get name from store
@@ -176,7 +256,7 @@ export async function buildChatFromMsg(msg, store, sock) {
         }
         else {
             try {
-                const meta = await getGroupMetadataCached(sock, rawJid);
+                const meta = await getGroupMetadataCached(contract, rawJid);
                 if (meta?.subject) {
                     name = meta.subject;
                     groupNameCache.set(rawJid, { name: meta.subject, at: Date.now() });
@@ -377,14 +457,14 @@ function mentionDisplayName(jid) {
 }
 /**
  * Build a normalized contact object from a JID and optional store metadata.
- * isBusiness is resolved via sock.getBusinessProfile(jid) — it resolves to
- * a profile only for WhatsApp Business accounts, undefined otherwise.
- * @param {string}           jid
- * @param {WAStoreContact}   [info]
- * @param {string|null}      [botJid]
- * @param {WASocket}         [sock]
+ * isBusiness is resolved via contract.getBusinessProfile(jid) — it resolves
+ * to a profile only for WhatsApp Business accounts, undefined otherwise.
+ * @param {string}              jid
+ * @param {RawStoreContact}     [info]
+ * @param {string|null}         [botJid]
+ * @param {WaContract}          [contract]
  */
-async function normalizeContact(jid, info, botJid, sock) {
+async function normalizeContact(jid, info, botJid, contract) {
     const number = jid.split("@")[0];
     let isBusiness = false;
     // We already have a contact record for this jid (learned from a real
@@ -394,9 +474,9 @@ async function normalizeContact(jid, info, botJid, sock) {
     // raw @lid we've never resolved to a phone number (returns a false
     // "doesn't exist" instead of throwing).
     let isWAAccount = Boolean(info);
-    if (!isWAAccount && sock && !jid.endsWith("@g.us")) {
+    if (!isWAAccount && contract && !jid.endsWith("@g.us")) {
         try {
-            const results = await sock.onWhatsApp(jid);
+            const results = await contract.onWhatsApp(jid);
             isWAAccount = Boolean(results?.[0]?.exists);
         }
         catch {
@@ -410,9 +490,9 @@ async function normalizeContact(jid, info, botJid, sock) {
     // resolved to null for an unknown ID instead of returning a hollow object.
     if (!jid.endsWith("@g.us") && !isWAAccount)
         return null;
-    if (sock && !jid.endsWith("@g.us")) {
+    if (contract && !jid.endsWith("@g.us")) {
         try {
-            isBusiness = Boolean(await sock.getBusinessProfile(jid));
+            isBusiness = Boolean(await contract.getBusinessProfile(jid));
         }
         catch {
             isBusiness = false;
@@ -453,7 +533,7 @@ function buildChatsApi(store) {
     };
 }
 // ── Contact API ───────────────────────────────────────────────────────────────
-function buildContactsApi(sock, store, botJid) {
+function buildContactsApi(contract, store, botJid) {
     return {
         /**
          * Get a normalized contact object by JID.
@@ -481,24 +561,23 @@ function buildContactsApi(sock, store, botJid) {
                 let freshPn;
                 // 1) Baileys' own protocol-level LID↔PN store — populated as part of
                 // real Signal session/identity handling, so it's authoritative when
-                // it has an answer (unlike our own heuristic lidMap). Not part of
-                // the public v6.7 TS surface, hence the cast; guarded with a
-                // typeof check since older/patched Baileys builds may not have it.
-                try {
-                    const lidMapping = sock.signalRepository?.lidMapping;
-                    if (typeof lidMapping?.getPNForLID === "function") {
-                        freshPn = await lidMapping.getPNForLID(contactId);
+                // it has an answer (unlike our own heuristic lidMap). Routed through
+                // the contract's optional resolveLid() helper (drivers without one
+                // — e.g. the future whatsmeow client — fall through to step 2).
+                if (contract.resolveLid) {
+                    try {
+                        freshPn = await contract.resolveLid(contactId);
+                    }
+                    catch (err) {
+                        logger.warn(`[contacts.get] contract.resolveLid cross-check failed for "${contactId}" — ${err.message}`);
                     }
-                }
-                catch (err) {
-                    logger.warn(`[contacts.get] signalRepository.lidMapping cross-check failed for "${contactId}" — ${err.message}`);
                 }
                 // 2) Fall back to live groupMetadata() when we know the group and
                 // the signal repository didn't have an answer. Best-effort — see
                 // the Baileys 6.7.x caveat in the doc comment above.
                 if (!freshPn && opts?.groupId) {
                     try {
-                        const meta = await sock.groupMetadata(opts.groupId);
+                        const meta = await getGroupMetadataCached(contract, opts.groupId);
                         const participant = meta.participants.find((p) => normalizeJid(p.id) === normalizeJid(contactId));
                         freshPn = participant?.phoneNumber;
                     }
@@ -546,7 +625,7 @@ function buildContactsApi(sock, store, botJid) {
                 notify: resolvedInfo?.notify ?? raw?.notify,
                 verifiedName: resolvedInfo?.verifiedName ?? raw?.verifiedName,
             } : undefined;
-            return normalizeContact(resolved, info, botJid, sock);
+            return normalizeContact(resolved, info, botJid, contract);
         },
         /**
          * Get the profile picture URL of a contact.
@@ -556,7 +635,7 @@ function buildContactsApi(sock, store, botJid) {
         async getPfpUrl(contactId) {
             const resolved = normalizeJid(store.resolveJid(normalizeJid(contactId)));
             try {
-                const url = await sock.profilePictureUrl(resolved, "image");
+                const url = await contract.profilePictureUrl(resolved);
                 return url ?? null;
             }
             catch {
@@ -594,7 +673,7 @@ function buildContactsApi(sock, store, botJid) {
             // (PN when known) rather than a raw @lid, which it may not accept.
             const resolved = normalizeJid(store.resolveJid(normalizeJid(contactId)));
             try {
-                const res = await sock.fetchStatus(resolved);
+                const res = await contract.fetchStatus(resolved);
                 // Current Baileys versions return a USync result array
                 // (`[{ id, status: { status, setAt } }]`) instead of the legacy
                 // single `{ status }` object — handle both shapes.
@@ -602,7 +681,10 @@ function buildContactsApi(sock, store, botJid) {
                     const entry = res.find(r => normalizeJid(r.id) === resolved) ?? res[0];
                     return entry?.status?.status ?? null;
                 }
-                return res?.status ?? null;
+                if (res && typeof res === "object") {
+                    return res.status ?? null;
+                }
+                return null;
             }
             catch (err) {
                 // Previously swallowed silently, which made "always null" look
@@ -616,14 +698,14 @@ function buildContactsApi(sock, store, botJid) {
          * @param {string} contactId
          */
         async block(contactId) {
-            return sock.updateBlockStatus(contactId, "block");
+            await contract.updateBlockStatus(contactId, "block");
         },
         /**
          * Unblock a contact.
          * @param {string} contactId
          */
         async unblock(contactId) {
-            return sock.updateBlockStatus(contactId, "unblock");
+            await contract.updateBlockStatus(contactId, "unblock");
         },
     };
 }
@@ -636,36 +718,73 @@ function makeHistoryArray(entries, store) {
     };
     return arr;
 }
-export function buildMessageContext(msg, sock, store, guardOptions = {}) {
+export function buildMessageContext(msg, contract, store, guardOptions = {}) {
+    const sock = rawSocketOf(contract);
     const body = getMsgBody(msg);
     const prefix = CONFIG.CMD_PREFIX;
     const rawArgs = body.trim().split(/\s+/);
     const first = rawArgs[0]?.toLowerCase() ?? "";
     const hasPrefix = first.startsWith(prefix);
     const command = hasPrefix ? first.slice(prefix.length) : "";
-    const rawJid = msg.key.remoteJid ?? "";
+    const rawJid = msg.chatId;
     const sender = getMsgSender(msg, store);
     const cooldown = guardOptions.cooldown ?? true;
     const jitter = guardOptions.jitter ?? true;
     const contextInfo = getContextInfo(msg);
+    // Build a synthetic quoted BotMessage when the original envelope carries
+    // 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
-        ? {
-            key: {
-                remoteJid: rawJid,
+        ? (() => {
+            const decoded = decodeContent(contextInfo.quotedMessage);
+            return {
+                id: contextInfo.stanzaId ?? "",
+                chatId: msg.chatId,
                 fromMe: false,
-                id: contextInfo.stanzaId ?? undefined,
-                participant: contextInfo.participant ?? undefined,
-            },
-            message: contextInfo.quotedMessage,
-            pushName: null,
-        }
-        : null;
+                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.key.id ?? "",
-        timestamp: Number(msg.messageTimestamp) || 0,
+        id: msg.id,
+        timestamp: msg.timestamp || 0,
         body,
         type: getMsgType(msg),
-        fromMe: !!(msg.key.fromMe),
+        fromMe: msg.fromMe,
         sender,
         senderName: msg.pushName ?? sender.replace(/(:\d+)?@.*$/, ""),
         command,
@@ -674,43 +793,66 @@ export function buildMessageContext(msg, sock, store, guardOptions = {}) {
             return hasPrefix && command === cmd.toLowerCase();
         },
         hasMedia: msgHasMedia(msg),
-        isGif: msgIsGif(msg),
+        isGif: msgIsGif(msg, store),
         async downloadMedia(opts = {}) {
             try {
-                const buffer = await downloadMediaMessage(msg, "buffer", {});
-                if (!buffer || !Buffer.isBuffer(buffer))
+                // contract.downloadMedia handles reupload internally via the
+                // driver's own protocol knowledge (Baileys: sock.updateMediaMessage).
+                const result = await contract.downloadMedia(msg, {});
+                if (!result)
                     return null;
-                const isAnimatedSticker = !!unwrap(msg)?.stickerMessage?.isAnimated;
+                const raw = rawMsgOf(msg, store);
+                const isAnimatedSticker = !!(raw?.message?.stickerMessage?.isAnimated);
                 if (opts.asMp4 && isAnimatedSticker) {
-                    const mp4 = await stickerToMp4(buffer);
+                    const mp4 = await stickerToMp4(result.data);
                     return { mimetype: "video/mp4", data: mp4.toString("base64") };
                 }
-                return { mimetype: getMsgMimetype(msg), data: buffer.toString("base64") };
+                return { mimetype: result.mimetype, data: result.data.toString("base64") };
             }
-            catch {
+            catch (err) {
+                logger.warn(`[whatsapp] downloadMedia failed: ${err.message}`);
                 return null;
             }
         },
-        hasReply: !!(contextInfo?.quotedMessage),
+        hasReply: !!(msg.quotedKey),
         async getReply() {
             if (!quotedRaw)
                 return null;
-            return buildMessageContext(quotedRaw, sock, store, { cooldown: false, jitter: false });
+            return buildMessageContext(quotedRaw, contract, store, { cooldown: false, jitter: false });
         },
-        reply: makeSender(sock, store, rawJid, msg, { cooldown, jitter }),
+        hasMention: hasMention(contextInfo),
+        hasBotMention: hasBotMention(contextInfo, sock, store),
+        reply: makeSender(contract, store, rawJid, msg, { cooldown, jitter }),
         async react(emoji) {
-            return sock.sendMessage(rawJid, { react: { text: emoji, key: msg.key } });
+            await contract.react(rawJid, {
+                id: msg.id,
+                remoteJid: msg.chatId,
+                fromMe: msg.fromMe,
+                participant: msg.participantAlt ?? msg.fromLid ?? msg.fromPn ?? null,
+            }, emoji);
         },
         async delete(forEveryone = true) {
             if (forEveryone) {
-                return sock.sendMessage(rawJid, { delete: msg.key });
+                await contract.deleteMessage(rawJid, {
+                    id: msg.id,
+                    remoteJid: msg.chatId,
+                    fromMe: msg.fromMe,
+                    participant: msg.participantAlt ?? msg.fromLid ?? msg.fromPn ?? null,
+                }, true);
             }
         },
         async edit(text) {
-            if (!msg.key.fromMe) {
+            if (!msg.fromMe) {
                 throw new Error("[pluginApi] edit() can only be used on the bot's own messages");
             }
-            return sock.sendMessage(rawJid, { text, edit: msg.key });
+            if (!msg.id || !(await waitForEditSlot(msg.id)))
+                return;
+            await contract.editMessage(rawJid, {
+                id: msg.id,
+                remoteJid: msg.chatId,
+                fromMe: msg.fromMe,
+                participant: msg.participantAlt ?? msg.fromLid ?? msg.fromPn ?? null,
+            }, text);
         },
         async pin(_duration) {
             logger.warn("[pluginApi] pin() is not supported with Baileys");
@@ -723,10 +865,10 @@ export function buildMessageContext(msg, sock, store, guardOptions = {}) {
         async getContact() {
             const info = store.contacts[sender]
                 ?? store.contacts[denormalizeJid(sender)]
-                ?? store.contacts[store.resolveJid(msg.key.participant ?? "")]
-                ?? store.contacts[denormalizeJid(store.resolveJid(msg.key.participant ?? ""))];
+                ?? store.contacts[store.resolveJid(msg.fromPn ?? "")]
+                ?? store.contacts[denormalizeJid(store.resolveJid(msg.fromPn ?? ""))];
             const botJid = sock.user?.id ? jidNormalizedUser(sock.user.id) : null;
-            return normalizeContact(sender, info, botJid, sock);
+            return normalizeContact(sender, info, botJid, contract);
         },
     };
 }
@@ -734,25 +876,31 @@ export function buildMessageContext(msg, sock, store, guardOptions = {}) {
 /**
  * Wraps a pending send and exposes chainable post-send actions.
  * Thenable: `await ctx.send.text("hi")` resolves to the message context.
+ *
+ * The wrapped `rawPromise` now resolves to a `BotMessage` (driver-neutral)
+ * instead of a raw `WAMessage` — the driver writes its own sent message
+ * into the in-memory store under jid+id, and the api reads it back as a
+ * BotMessage (built from the adapter's WAMessage→BotMessage translator).
+ * This keeps the rest of the api from depending on Baileys' wire shape.
  */
 class MessageHandle {
     _p;
-    _sock;
+    _contract;
     _store;
     _jid = null;
     _guardOptions;
     rawPromise;
-    constructor(promise, sock, store, guardOptions) {
+    constructor(promise, contract, store, guardOptions) {
         this.rawPromise = promise;
-        this._sock = sock;
+        this._contract = contract;
         this._store = store;
         this._guardOptions = guardOptions ?? {};
         this._p = promise.then(msg => {
             if (!msg)
                 return undefined;
             if (!this._jid)
-                this._jid = msg.key.remoteJid || null;
-            return buildMessageContext(msg, sock, store, guardOptions);
+                this._jid = msg.chatId || null;
+            return buildMessageContext(msg, this._contract, store, guardOptions);
         });
     }
     then(onfulfilled, onrejected) {
@@ -773,7 +921,7 @@ class MessageHandle {
      *   const reply = await audio.reply.text("here it is!");
      */
     get reply() {
-        return makeSender(this._sock, this._store, this._jid || "", this.rawPromise, this._guardOptions);
+        return makeSender(this._contract, this._store, this._jid || "", this.rawPromise, this._guardOptions);
     }
     /** Pin the sent message. */
     async pin(_duration) {
@@ -782,31 +930,45 @@ class MessageHandle {
     /** Delete the sent message. */
     async delete(forEveryone = true) {
         const msg = await this.rawPromise;
-        if (!msg?.key)
+        if (!msg)
             return;
-        const jid = msg.key.remoteJid;
         if (forEveryone) {
-            return this._sock.sendMessage(jid, { delete: msg.key });
+            await this._contract.deleteMessage(msg.chatId, {
+                id: msg.id,
+                remoteJid: msg.chatId,
+                fromMe: msg.fromMe,
+                participant: msg.participantAlt ?? msg.fromLid ?? msg.fromPn ?? null,
+            }, true);
         }
     }
     /** React to the sent message. */
     async react(emoji) {
         const msg = await this.rawPromise;
-        if (!msg?.key)
+        if (!msg)
             return;
-        return this._sock.sendMessage(msg.key.remoteJid, {
-            react: { text: emoji, key: msg.key },
-        });
+        await this._contract.react(msg.chatId, {
+            id: msg.id,
+            remoteJid: msg.chatId,
+            fromMe: msg.fromMe,
+            participant: msg.participantAlt ?? msg.fromLid ?? msg.fromPn ?? null,
+        }, emoji);
     }
     /** Edit the sent message's text. Only works on the bot's own messages. */
     async edit(text) {
         const msg = await this.rawPromise;
-        if (!msg?.key)
+        if (!msg)
             return;
-        if (!msg.key.fromMe) {
+        if (!msg.fromMe) {
             throw new Error("[pluginApi] edit() can only be used on the bot's own messages");
         }
-        return this._sock.sendMessage(msg.key.remoteJid, { text, edit: msg.key });
+        if (!msg.id || !(await waitForEditSlot(msg.id)))
+            return;
+        await this._contract.editMessage(msg.chatId, {
+            id: msg.id,
+            remoteJid: msg.chatId,
+            fromMe: msg.fromMe,
+            participant: msg.participantAlt ?? msg.fromLid ?? msg.fromPn ?? null,
+        }, text);
     }
 }
 // ── Sender factory ────────────────────────────────────────────────────────────
@@ -936,81 +1098,100 @@ async function stickerToMp4(webpBuffer) {
 /**
  * Returns send methods bound to a specific JID.
  *
- * @param {WASocket}                                    sock
- * @param {WAStore}                                     store
- * @param {string}                                      jid         — destination JID (raw, not normalized)
- * @param {WAProtoMsg | Promise<WAProtoMsg | null>}    [quoted]    — message to quote (can be Promise)
- * @param {object}                                      [guard]
+ * @param {WaContract}                                                contract
+ * @param {BotStore}                                                  store
+ * @param {string}                                                    jid         — destination JID (raw, not normalized)
+ * @param {BotMessage | Promise<BotMessage | null | undefined> | null} [quoted]   — message to quote (can be Promise)
+ * @param {object}                                                    [guard]
  */
-function makeSender(sock, store, jid, quoted = null, { cooldown = true, jitter = true } = {}) {
+function makeSender(contract, store, jid, quoted = null, { cooldown = true, jitter = true } = {}) {
     const normJid = normalizeJid(jid);
-    // Helper: resolve quoted message if it's a Promise
+    // Helper: resolve quoted message if it's a Promise, then turn it into a
+    // BotQuotedRef the contract's send methods accept.
     const resolveQuoted = async () => {
         if (!quoted)
             return undefined;
-        if (quoted instanceof Promise) {
-            const result = await quoted;
-            return result || undefined;
-        }
-        return quoted;
+        const msg = quoted instanceof Promise ? (await quoted) || undefined : quoted;
+        return msg ? quotedRefFromMsg(msg) : undefined;
     };
     return {
         text(content, opts = {}) {
+            // The text path goes through sendFallbackGuard:
+            // try the active driver, verify the message actually landed in the
+            // driver's history, and on failure swap to the other driver. sendMedia
+            // and react below still go straight to the contract on purpose — media
+            // fallback is out of scope for this phase, react is one-shot and
+            // already idempotent at the protocol level.
             return new MessageHandle((async () => {
-                const quotedMsg = await resolveQuoted();
-                const sendOpts = quotedMsg ? { quoted: quotedMsg } : {};
-                // mentions/linkPreview are part of the message CONTENT, not the send
-                // options — Baileys reads contextInfo.mentionedJid off the content
-                // object. Putting them on sendOpts (3rd arg) is silently ignored: the
-                // message sends fine, "@name" shows as plain text, and nobody actually
-                // gets tagged/notified.
-                const messageContent = { text: content };
-                if (opts.linkPreview === false) {
-                    messageContent.linkPreview = null;
+                const quotedRef = await resolveQuoted();
+                const mentionsResolved = opts.mentions?.length
+                    ? await resolveMentionJids(contract, store, jid, opts.mentions)
+                    : undefined;
+                // Pre-send bookkeeping the Baileys path used to do inline:
+                // waitForSendSlot is already invoked by sendFallbackGuard on the
+                // primary attempt, so we don't repeat it here. simulateState is
+                // best-effort and per-driver, so it stays on this side.
+                await simulateState(contract, jid, typingDuration(content), "typing");
+                const ref = await sendWithFallback(jid, content, {
+                    quoted: quotedRef ?? undefined,
+                    mentions: mentionsResolved,
+                });
+                // The guard returns a SentMessageRef (id + chatId + timestamp) but
+                // the rest of the sender API (MessageHandle, buildPollApi's
+                // rawMsg.chatId, etc.) expects the full BotMessage. The driver's
+                // messages.upsert handler stores own sent messages into the store
+                // keyed by jid+id, so we can read it back. Give the store a tiny
+                // window to catch up — a freshly-sent message may not be in the
+                // map yet on the very same tick — and return undefined if it
+                // never lands; downstream code already tolerates that (e.g.
+                // .reply / .delete are no-ops when rawPromise resolves to
+                // undefined).
+                const deadline = Date.now() + 200;
+                while (Date.now() < deadline) {
+                    const stored = store.messages.get(ref.chatId)?.get(ref.id);
+                    if (stored)
+                        return toBotMessage(stored);
+                    await new Promise(r => setTimeout(r, 20));
                 }
-                if (opts.mentions?.length) {
-                    messageContent.mentions = await resolveMentionJids(sock, store, jid, opts.mentions);
-                }
-                await waitForSendSlot(normJid, { cooldown, jitter });
-                await simulateState(toPresenceCapable(sock), jid, typingDuration(content), "typing");
-                return sock.sendMessage(jid, messageContent, sendOpts);
-            })(), sock, store, { cooldown, jitter });
+                const final = store.messages.get(ref.chatId)?.get(ref.id);
+                return final ? toBotMessage(final) : undefined;
+            })(), contract, store, { cooldown, jitter });
         },
         image(source, caption = "", opts = {}) {
             return new MessageHandle((async () => {
-                const quotedMsg = await resolveQuoted();
-                const sendOpts = quotedMsg ? { quoted: quotedMsg } : {};
+                const quotedRef = await resolveQuoted();
                 await waitForSendSlot(normJid, { cooldown, jitter });
-                await simulateState(toPresenceCapable(sock), jid, mediaDuration(), "typing");
+                await simulateState(contract, jid, mediaDuration(caption), "typing");
                 const buffer = await resolveMediaBuffer(source);
-                // viewOnce/mentions are part of the message CONTENT — see note above.
-                const messageContent = { image: buffer, caption };
-                if (opts.viewOnce) {
-                    messageContent.viewOnce = true;
-                }
-                if (opts.mentions?.length) {
-                    messageContent.mentions = await resolveMentionJids(sock, store, jid, opts.mentions);
-                }
-                return sock.sendMessage(jid, messageContent, sendOpts);
-            })(), sock, store, { cooldown, jitter });
+                const mentionsResolved = opts.mentions?.length
+                    ? await resolveMentionJids(contract, store, jid, opts.mentions)
+                    : undefined;
+                const ref = await contract.sendImage(jid, buffer, {
+                    caption,
+                    quoted: quotedRef ?? undefined,
+                    mentions: mentionsResolved,
+                    viewOnce: opts.viewOnce,
+                });
+                return refToBotMessage(ref, store);
+            })(), contract, store, { cooldown, jitter });
         },
         video(source, caption = "", opts = {}) {
             return new MessageHandle((async () => {
-                const quotedMsg = await resolveQuoted();
-                const sendOpts = quotedMsg ? { quoted: quotedMsg } : {};
+                const quotedRef = await resolveQuoted();
                 await waitForSendSlot(normJid, { cooldown, jitter });
-                await simulateState(toPresenceCapable(sock), jid, mediaDuration(), "typing");
+                await simulateState(contract, jid, mediaDuration(caption), "typing");
                 const buffer = await resolveMediaBuffer(source);
-                // viewOnce/mentions are part of the message CONTENT — see note above.
-                const messageContent = { video: buffer, caption };
-                if (opts.viewOnce) {
-                    messageContent.viewOnce = true;
-                }
-                if (opts.mentions?.length) {
-                    messageContent.mentions = await resolveMentionJids(sock, store, jid, opts.mentions);
-                }
-                return sock.sendMessage(jid, messageContent, sendOpts);
-            })(), sock, store, { cooldown, jitter });
+                const mentionsResolved = opts.mentions?.length
+                    ? await resolveMentionJids(contract, store, jid, opts.mentions)
+                    : undefined;
+                const ref = await contract.sendVideo(jid, buffer, {
+                    caption,
+                    quoted: quotedRef ?? undefined,
+                    mentions: mentionsResolved,
+                    viewOnce: opts.viewOnce,
+                });
+                return refToBotMessage(ref, store);
+            })(), contract, store, { cooldown, jitter });
         },
         /**
          * Send a GIF. WhatsApp has no native GIF format — this sends an mp4
@@ -1022,54 +1203,57 @@ function makeSender(sock, store, jid, quoted = null, { cooldown = true, jitter =
          */
         gif(source, caption = "", opts = {}) {
             return new MessageHandle((async () => {
-                const quotedMsg = await resolveQuoted();
-                const sendOpts = quotedMsg ? { quoted: quotedMsg } : {};
+                const quotedRef = await resolveQuoted();
                 await waitForSendSlot(normJid, { cooldown, jitter });
-                await simulateState(toPresenceCapable(sock), jid, mediaDuration(), "typing");
+                await simulateState(contract, jid, mediaDuration(caption), "typing");
                 const buffer = needsGifConversion(source)
                     ? await gifToMp4(source)
                     : await resolveMediaBuffer(source);
-                const messageContent = { video: buffer, caption, gifPlayback: true };
-                if (opts.viewOnce) {
-                    messageContent.viewOnce = true;
-                }
-                if (opts.mentions?.length) {
-                    messageContent.mentions = await resolveMentionJids(sock, store, jid, opts.mentions);
-                }
-                return sock.sendMessage(jid, messageContent, sendOpts);
-            })(), sock, store, { cooldown, jitter });
+                const mentionsResolved = opts.mentions?.length
+                    ? await resolveMentionJids(contract, store, jid, opts.mentions)
+                    : undefined;
+                const ref = await contract.sendVideo(jid, buffer, {
+                    caption,
+                    quoted: quotedRef ?? undefined,
+                    mentions: mentionsResolved,
+                    viewOnce: opts.viewOnce,
+                    gifPlayback: true,
+                });
+                return refToBotMessage(ref, store);
+            })(), contract, store, { cooldown, jitter });
         },
         audio(source, { asVoice = true, viewOnce = false } = {}) {
             return new MessageHandle((async () => {
-                const quotedMsg = await resolveQuoted();
-                const sendOpts = quotedMsg ? { quoted: quotedMsg } : {};
+                const quotedRef = await resolveQuoted();
                 await waitForSendSlot(normJid, { cooldown, jitter });
-                await simulateState(toPresenceCapable(sock), jid, mediaDuration(), "recording");
+                await simulateState(contract, jid, mediaDuration(), "recording");
                 const buffer = await resolveMediaBuffer(source);
-                // viewOnce is part of the message CONTENT — see note above.
-                const messageContent = { audio: buffer, mimetype: "audio/mp4", ptt: asVoice };
-                if (viewOnce) {
-                    messageContent.viewOnce = true;
-                }
-                return sock.sendMessage(jid, messageContent, sendOpts);
-            })(), sock, store, { cooldown, jitter });
+                const ref = await contract.sendAudio(jid, buffer, {
+                    quoted: quotedRef ?? undefined,
+                    viewOnce: viewOnce,
+                    ptt: asVoice,
+                    mimetype: "audio/mp4",
+                });
+                return refToBotMessage(ref, store);
+            })(), contract, store, { cooldown, jitter });
         },
         sticker(source) {
             return new MessageHandle((async () => {
-                const quotedMsg = await resolveQuoted();
-                const qOpts = quotedMsg ? { quoted: quotedMsg } : undefined;
+                const quotedRef = await resolveQuoted();
                 await waitForSendSlot(normJid, { cooldown, jitter });
-                await simulateState(toPresenceCapable(sock), jid, mediaDuration(), "typing");
+                await simulateState(contract, jid, mediaDuration(), "typing");
                 const buffer = await resolveMediaBuffer(source);
-                return sock.sendMessage(jid, { sticker: buffer }, qOpts);
-            })(), sock, store, { cooldown, jitter });
+                const ref = await contract.sendSticker(jid, buffer, {
+                    quoted: quotedRef ?? undefined,
+                });
+                return refToBotMessage(ref, store);
+            })(), contract, store, { cooldown, jitter });
         },
         file(source, filename) {
             return new MessageHandle((async () => {
-                const quotedMsg = await resolveQuoted();
-                const qOpts = quotedMsg ? { quoted: quotedMsg } : undefined;
+                const quotedRef = await resolveQuoted();
                 await waitForSendSlot(normJid, { cooldown, jitter });
-                await simulateState(toPresenceCapable(sock), jid, mediaDuration(), "typing");
+                await simulateState(contract, jid, mediaDuration(), "typing");
                 const isBuffer = Buffer.isBuffer(source);
                 const buffer = await resolveMediaBuffer(source);
                 // With a path we can always infer the mimetype/name from it. With a
@@ -1078,12 +1262,11 @@ function makeSender(sock, store, jid, quoted = null, { cooldown = true, jitter =
                 // a generic octet-stream document named "file".
                 const mimetype = filename ? mimeFromPath(filename) : (isBuffer ? "application/octet-stream" : mimeFromPath(source));
                 const resolvedFilename = filename ?? (isBuffer ? "file" : path.basename(source));
-                return sock.sendMessage(jid, {
-                    document: buffer,
-                    mimetype,
-                    fileName: resolvedFilename,
-                }, qOpts);
-            })(), sock, store, { cooldown, jitter });
+                const ref = await contract.sendDocument(jid, buffer, resolvedFilename, mimetype, {
+                    quoted: quotedRef ?? undefined,
+                });
+                return refToBotMessage(ref, store);
+            })(), contract, store, { cooldown, jitter });
         },
         /**
          * Send a poll.
@@ -1094,25 +1277,24 @@ function makeSender(sock, store, jid, quoted = null, { cooldown = true, jitter =
          */
         poll(question, options, { allowMultipleAnswers = false } = {}) {
             return new MessageHandle((async () => {
-                const quotedMsg = await resolveQuoted();
-                const qOpts = quotedMsg ? { quoted: quotedMsg } : undefined;
+                const quotedRef = await resolveQuoted();
                 await waitForSendSlot(normJid, { cooldown, jitter });
-                return sock.sendMessage(jid, {
-                    poll: {
-                        name: question,
-                        values: options,
-                        selectableCount: allowMultipleAnswers ? 0 : 1,
-                    },
-                }, qOpts);
-            })(), sock, store, { cooldown, jitter });
+                const ref = await contract.sendPoll(jid, {
+                    name: question,
+                    values: options,
+                    selectableCount: allowMultipleAnswers ? 0 : 1,
+                    quoted: quotedRef ?? undefined,
+                });
+                return refToBotMessage(ref, store);
+            })(), contract, store, { cooldown, jitter });
         },
     };
 }
 // ── Send API ──────────────────────────────────────────────────────────────────
-function buildSendApi(sock, store, rawJid, guardOptions = {}) {
+function buildSendApi(contract, store, rawJid, guardOptions = {}) {
     const cooldown = (guardOptions.cooldown ?? true);
     const jitter = (guardOptions.jitter ?? true);
-    const current = makeSender(sock, store, rawJid, null, { cooldown, jitter });
+    const current = makeSender(contract, store, rawJid, null, { cooldown, jitter });
     return {
         send: {
             text: (text, opts) => current.text(text, opts),
@@ -1127,21 +1309,22 @@ function buildSendApi(sock, store, rawJid, guardOptions = {}) {
              * Returns a sender bound to another chat.
              * @param {string} targetJid
              */
-            to: (targetJid) => makeSender(sock, store, targetJid, null, { cooldown: false, jitter: false }),
+            to: (targetJid) => makeSender(contract, store, targetJid, null, { cooldown: false, jitter: false }),
         },
     };
 }
 /** Setup send API — no current chat, only .to(). */
-function buildSetupSendApi(sock, store) {
+function buildSetupSendApi(contract, store) {
     return {
         send: {
-            to: (targetJid) => makeSender(sock, store, targetJid),
+            to: (targetJid) => makeSender(contract, store, targetJid),
         },
     };
 }
 // ── Events API ────────────────────────────────────────────────────────────────
 const listenerRegistry = new Map();
-export function cleanupPluginEvents(pluginName, sock) {
+export function cleanupPluginEvents(pluginName, contract) {
+    const sock = rawSocketOf(contract);
     const list = listenerRegistry.get(pluginName);
     if (list) {
         for (const { event, handler } of list) {
@@ -1155,10 +1338,11 @@ export function cleanupPluginEvents(pluginName, sock) {
     cancelPlugin(pluginName);
 }
 /**
- * @param {WASocket} sock
- * @param {string}   pluginName
+ * @param {WaContract} contract
+ * @param {string}     pluginName
  */
-function buildEventsApi(sock, pluginName) {
+function buildEventsApi(contract, pluginName) {
+    const sock = rawSocketOf(contract);
     return {
         on(event, handler) {
             sock.ev.on(event, handler);
@@ -1193,30 +1377,6 @@ function buildEventsApi(sock, pluginName) {
  * @param {WASocket}     sock
  * @param {string|null}  chatJid — raw JID of the current group (null in setup context)
  */
-/**
- * Normalize any identifier to the wire JID format WhatsApp's servers and
- * protocol actually expect (`...@s.whatsapp.net`). Used anywhere a JID is
- * handed straight to Baileys — `groupParticipantsUpdate()` and message
- * `mentions` — both of which silently misbehave otherwise: a malformed
- * group-update JID gets the whole IQ query rejected ("bad-request"), and
- * a malformed mentions entry just doesn't tag/notify anyone (the message
- * still sends fine, so it looks like nothing is wrong until you check).
- * Handles this framework's own normalized `@c.us` form (`contact.id`,
- * `getMsgSender()`'s output — see normalizeJid()/denormalizeJid()), a bare
- * phone number (with or without "+", spaces or dashes), and already-valid
- * wire JIDs (`@s.whatsapp.net`, `@lid`, `@g.us`), which pass through
- * unchanged.
- * @param {string} id
- */
-function toWireJid(id) {
-    const trimmed = id.trim();
-    if (/@(s\.whatsapp\.net|lid|g\.us)$/.test(trimmed))
-        return trimmed;
-    if (trimmed.endsWith("@c.us"))
-        return denormalizeJid(trimmed);
-    const digits = trimmed.replace(/\D/g, "");
-    return `${digits}@s.whatsapp.net`;
-}
 /**
  * Resolve mentions to the exact JID form the destination group uses for
  * that participant — not whatever store.resolveJid() happens to have
@@ -1226,7 +1386,7 @@ function toWireJid(id) {
  * member. DMs have no participant list to check against, so just wire-
  * normalize as before (mentions aren't a real thing in DMs anyway).
  */
-async function resolveMentionJids(sock, store, jid, mentions) {
+async function resolveMentionJids(contract, store, jid, mentions) {
     const result = [];
     for (const m of mentions) {
         const wire = toWireJid(m);
@@ -1244,7 +1404,11 @@ async function resolveMentionJids(sock, store, jid, mentions) {
     }
     let meta;
     try {
-        meta = await getGroupMetadataCached(sock, jid);
+        // getGroupMetadataCached uses the raw sock internally for the
+        // Baileys-flavored participant field shape (admin: "admin" |
+        // "superadmin", etc.); the neutral contract's groupMetadata doesn't
+        // expose that yet.
+        meta = await getGroupMetadataCached(contract, jid);
     }
     catch {
         return Array.from(new Set(result.filter(Boolean)));
@@ -1261,22 +1425,22 @@ async function resolveMentionJids(sock, store, jid, mentions) {
     }
     return Array.from(new Set(result.filter(Boolean)));
 }
-function buildAdminApi(sock, chatJid) {
+function buildAdminApi(contract, chatJid) {
     const norm = (v) => (Array.isArray(v) ? v : [v]).map(toWireJid);
     function requireChat() {
         if (!chatJid)
             throw new Error("This admin operation requires a runtime group context.");
     }
     async function getGroup(jid) {
-        const meta = await sock.groupMetadata(jid);
+        const meta = await contract.groupMetadata(jid);
         if (!meta)
             throw new Error(`Group not found: ${jid}`);
         return meta;
     }
     /**
-     * Baileys' `groupParticipantsUpdate()` resolves normally even when
-     * WhatsApp rejected some (or all) of the requested participants — it
-     * returns an array with a per-participant `status` code (`'200'` =
+     * The contract's `groupParticipantsUpdate()` resolves normally even
+     * when WhatsApp rejected some (or all) of the requested participants —
+     * it returns an array with a per-participant `status` code (`'200'` =
      * success; anything else is a rejection — e.g. `'403'`/`'401'` not
      * authorized, often because the target's privacy settings block being
      * added by a non-contact; `'409'` already a participant; `'408'`
@@ -1296,15 +1460,15 @@ function buildAdminApi(sock, chatJid) {
         }
     }
     /**
-     * Thin wrapper around `sock.groupParticipantsUpdate()` that turns an
-     * opaque Boom rejection (e.g. the whole IQ query bounced with
+     * Thin wrapper around `contract.groupParticipantsUpdate()` that turns
+     * an opaque rejection (e.g. the whole IQ query bounced with
      * "bad-request") into an error that names the group/action/participants
      * involved, then still runs the per-participant status check above.
      */
     async function runParticipantsUpdate(jid, users, action) {
         let results;
         try {
-            results = await sock.groupParticipantsUpdate(jid, users, action);
+            results = await contract.groupParticipantsUpdate(jid, users, action);
         }
         catch (err) {
             throw new Error(`groupParticipantsUpdate("${action}") falhou para o grupo "${jid}" com participantes [${users.join(", ")}]: ${err.message}`);
@@ -1351,49 +1515,49 @@ function buildAdminApi(sock, chatJid) {
         /** @param {string} name */
         async setSubject(name) {
             requireChat();
-            return sock.groupUpdateSubject(chatJid, name);
+            return contract.groupUpdateSubject(chatJid, name);
         },
         /** @param {string} text */
         async setDescription(text) {
             requireChat();
-            return sock.groupUpdateDescription(chatJid, text);
+            return contract.groupUpdateDescription(chatJid, text);
         },
         /** @param {string|Buffer} source */
         async setProfilePic(source) {
             requireChat();
             const buffer = Buffer.isBuffer(source) ? source : readFileSync(source);
-            return sock.updateProfilePicture(chatJid, buffer);
+            return contract.updateProfilePicture(chatJid, buffer);
         },
         async getInviteLink(groupId) {
             const jid = groupId ?? chatJid;
             if (!jid)
                 throw new Error("This admin operation requires a runtime group context.");
-            const code = await sock.groupInviteCode(jid);
+            const code = await contract.groupInviteCode(jid);
             return `https://chat.whatsapp.com/${code}`;
         },
         async revokeInvite() {
             requireChat();
-            return sock.groupRevokeInvite(chatJid);
+            return contract.groupRevokeInvite(chatJid);
         },
     };
 }
 // ── Me API ────────────────────────────────────────────────────────────────────
-/** @param {WASocket} sock */
-function buildMeApi(sock) {
+/** @param {WaContract} contract */
+function buildMeApi(contract) {
     return {
         /** @param {string} name */
         async setName(name) {
-            return sock.updateProfileName(name);
+            return contract.updateProfileName(name);
         },
         /** @param {string} text */
         async setAbout(text) {
-            return sock.updateProfileStatus(text);
+            return contract.updateProfileStatus(text);
         },
         /** @param {string|Buffer} source */
         async setProfilePic(source) {
             const buffer = Buffer.isBuffer(source) ? source : readFileSync(source);
-            const jid = sock.user?.id ?? "";
-            return sock.updateProfilePicture(jid, buffer);
+            const jid = contract.me().id ?? "";
+            return contract.updateProfilePicture(jid, buffer);
         },
     };
 }
@@ -1408,13 +1572,13 @@ const pollListenersBySocket = new WeakMap();
  * Tracks votes for an active poll.
  * Obtained via ctx.poll.create().
  */
-class PollHandle {
+export class PollHandle {
     msgId;
     _options;
     _callbacks;
     _registry;
     constructor(msg, options, registry) {
-        this.msgId = msg.key.id ?? "";
+        this.msgId = msg.id ?? "";
         this._options = new Map(options.map(o => [o, new Set()]));
         this._callbacks = [];
         this._registry = registry;
@@ -1463,13 +1627,13 @@ class PollHandle {
     }
 }
 /**
- * @param {WASocket} sock
- * @param {WAStore}  store
- * @param {string}   rawJid       — destination JID (not normalized)
- * @param {object}   guardOptions
- * @param {string}   pluginName
+ * @param {WaContract} contract
+ * @param {BotStore}   store
+ * @param {string}     rawJid       — destination JID (not normalized)
+ * @param {object}     guardOptions
+ * @param {string}     pluginName
  */
-function buildPollApi(sock, store, rawJid, guardOptions, pluginName) {
+function buildPollApi(contract, store, rawJid, guardOptions, pluginName) {
     if (!pollRegistry.has(pluginName))
         pollRegistry.set(pluginName, new Map());
     const registry = pollRegistry.get(pluginName);
@@ -1479,6 +1643,11 @@ function buildPollApi(sock, store, rawJid, guardOptions, pluginName) {
     // 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();
@@ -1592,7 +1761,7 @@ function buildPollApi(sock, store, rawJid, guardOptions, pluginName) {
          * @returns {Promise<PollHandle>}
          */
         async create(question, options, opts = {}) {
-            const sender = makeSender(sock, store, rawJid, null, { cooldown, jitter });
+            const sender = makeSender(contract, store, rawJid, null, { cooldown, jitter });
             const handlePromise = sender.poll(question, options, opts);
             const rawMsg = await handlePromise.rawPromise;
             if (!rawMsg)
@@ -1602,7 +1771,12 @@ function buildPollApi(sock, store, rawJid, guardOptions, pluginName) {
             // Ensure the poll message is in the store before any vote arrives —
             // messages.upsert isn't guaranteed to fire (or land in time) for the
             // bot's own sent messages, which previously dropped every vote.
-            const remoteJid = rawMsg.key.remoteJid;
+            // The store still keeps raw WAMessages keyed by jid+id (the
+            // poll-decryption path below reads the raw envelope off the store),
+            // so push a raw entry back in here too. refToBotMessage keeps the
+            // driver-neutral envelope current; rawStore keeps the Baileys shape
+            // the decryption helper still needs.
+            const remoteJid = rawMsg.chatId;
             if (remoteJid) {
                 if (!store.messages.has(remoteJid))
                     store.messages.set(remoteJid, new Map());
@@ -1622,8 +1796,8 @@ function buildPollApi(sock, store, rawJid, guardOptions, pluginName) {
     };
 }
 // ── Base API (shared between setup and runtime) ───────────────────────────────
-function buildBaseApi(sock, store, pluginRegistry, pluginName) {
-    const botJid = sock.user?.id ? jidNormalizedUser(sock.user.id) : null;
+function buildBaseApi(contract, store, pluginRegistry, pluginName) {
+    const botJid = contract.me().id ? jidNormalizedUser(contract.me().id) : null;
     if (!botJid)
         logger.warn("[pluginApi] botId is null — socket may not be ready yet.");
     return {
@@ -1636,7 +1810,7 @@ function buildBaseApi(sock, store, pluginRegistry, pluginName) {
         scheduler: buildSchedulerApi(pluginName),
         plugins: buildPluginsApi(pluginRegistry),
         chats: buildChatsApi(store),
-        contacts: buildContactsApi(sock, store, botJid),
+        contacts: buildContactsApi(contract, store, botJid),
         storage: buildStorageApi(pluginName),
         botId: botJid,
     };
@@ -1646,19 +1820,19 @@ function buildBaseApi(sock, store, pluginRegistry, pluginName) {
  * Setup API — without message context.
  * Passed to plugin.setup(ctx) during initialization.
  *
- * @param {WASocket}              sock
- * @param {WAStore}               store
- * @param {Map<string, any>}      pluginRegistry
- * @param {string}                pluginName
+ * @param {WaContract}              contract
+ * @param {BotStore}                store
+ * @param {Map<string, any>}        pluginRegistry
+ * @param {string}                  pluginName
  */
-export function buildSetupApi(sock, store, pluginRegistry, pluginName) {
-    bindGroupMetaInvalidation(sock);
+export function buildSetupApi(contract, store, pluginRegistry, pluginName) {
+    bindGroupMetaInvalidation(contract);
     return {
-        ...buildBaseApi(sock, store, pluginRegistry, pluginName),
-        ...buildSetupSendApi(sock, store),
-        admin: buildAdminApi(sock, null),
-        events: buildEventsApi(sock, pluginName),
-        me: buildMeApi(sock),
+        ...buildBaseApi(contract, store, pluginRegistry, pluginName),
+        ...buildSetupSendApi(contract, store),
+        admin: buildAdminApi(contract, null),
+        events: buildEventsApi(contract, pluginName),
+        me: buildMeApi(contract),
         settings: { global: buildSettingsApi(pluginName, "_global").global },
     };
 }
@@ -1668,44 +1842,30 @@ export function buildSetupApi(sock, store, pluginRegistry, pluginName) {
  * Passed to plugin.default(ctx) on every message.
  *
  * @param {object}          params
- * @param {WAProtoMsg}      params.msg
+ * @param {BotMessage}      params.msg
  * @param {WAChat}          params.chat
- * @param {WASocket}        params.sock
- * @param {WAStore}         params.store
+ * @param {WaContract}      params.contract
+ * @param {BotStore}        params.store
  * @param {Map}             params.pluginRegistry
  * @param {string}          params.pluginName
  * @param {object}          [params.guardOptions]
  */
-export function buildApi({ msg, chat, sock, store, pluginRegistry, pluginName, guardOptions = {}, }) {
+export function buildApi({ msg, chat, contract, store, pluginRegistry, pluginName, guardOptions = {}, }) {
     const prefix = CONFIG.CMD_PREFIX;
     const body = getMsgBody(msg);
     const rawArgs = body.trim().split(/\s+/);
     const first = rawArgs[0]?.toLowerCase() ?? "";
     const hasPrefix = first.startsWith(prefix);
     const command = hasPrefix ? first.slice(prefix.length) : "";
-    const rawJid = msg.key.remoteJid ?? "";
+    const rawJid = msg.chatId;
     const normJid = normalizeJid(rawJid);
     const sender = getMsgSender(msg, store);
     const cooldown = (guardOptions.cooldown ?? true);
     const jitter = (guardOptions.jitter ?? true);
-    bindGroupMetaInvalidation(sock);
-    // Sender for quoted messages
-    const contextInfo = getContextInfo(msg);
-    const quotedRaw = contextInfo?.quotedMessage
-        ? {
-            key: {
-                remoteJid: rawJid,
-                fromMe: false,
-                id: contextInfo.stanzaId ?? undefined,
-                participant: contextInfo.participant ?? undefined,
-            },
-            message: contextInfo.quotedMessage,
-            pushName: null,
-        }
-        : null;
+    bindGroupMetaInvalidation(contract);
     // 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 "sock.user.id" are usually PN-normalized, so a straight
+    // "sender" and the bot's own JID are usually PN-normalized, so a straight
     // `=== ` against an @lid participant list silently never matches, even
     // when the person genuinely is an admin. Compare every known form
     // (raw + store-resolved) on both sides instead of trusting a single shape.
@@ -1723,10 +1883,10 @@ export function buildApi({ msg, chat, sock, store, pluginRegistry, pluginName, g
         return false;
     }
     return {
-        ...buildBaseApi(sock, store, pluginRegistry, pluginName),
-        ...buildSendApi(sock, store, rawJid, guardOptions),
+        ...buildBaseApi(contract, store, pluginRegistry, pluginName),
+        ...buildSendApi(contract, store, rawJid, guardOptions),
         // ── msg ──────────────────────────────────────────────────────────────────
-        msg: buildMessageContext(msg, sock, store, { cooldown, jitter }),
+        msg: buildMessageContext(msg, contract, store, { cooldown, jitter }),
         // ── chat ─────────────────────────────────────────────────────────────────
         chat: {
             id: normJid,
@@ -1741,7 +1901,7 @@ export function buildApi({ msg, chat, sock, store, pluginRegistry, pluginName, g
             get history() {
                 const chatMsgs = store.messages.get(rawJid);
                 const entries = chatMsgs
-                    ? [...chatMsgs.values()].map((m) => buildMessageContext(m, sock, store, { cooldown: false, jitter: false }))
+                    ? [...chatMsgs.values()].map((m) => buildMessageContext(toBotMessage(m), contract, store, { cooldown: false, jitter: false }))
                     : [];
                 return makeHistoryArray(entries, store);
             },
@@ -1754,7 +1914,7 @@ export function buildApi({ msg, chat, sock, store, pluginRegistry, pluginName, g
                 if (!chat.isGroup)
                     return [];
                 try {
-                    const meta = await getGroupMetadataCached(sock, rawJid);
+                    const meta = await getGroupMetadataCached(contract, rawJid);
                     return meta.participants.map(p => ({
                         id: normalizeJid(p.id),
                         isAdmin: p.admin === "admin" || p.admin === "superadmin",
@@ -1774,7 +1934,7 @@ export function buildApi({ msg, chat, sock, store, pluginRegistry, pluginName, g
                 if (!chat.isGroup)
                     return false;
                 try {
-                    const meta = await getGroupMetadataCached(sock, rawJid);
+                    const meta = await getGroupMetadataCached(contract, rawJid);
                     return meta.participants.some(p => matchesParticipant([contactId], p.id) && (p.admin === "admin" || p.admin === "superadmin"));
                 }
                 catch {
@@ -1789,8 +1949,11 @@ export function buildApi({ msg, chat, sock, store, pluginRegistry, pluginName, g
                 if (!chat.isGroup)
                     return false;
                 try {
-                    const meta = await getGroupMetadataCached(sock, rawJid);
-                    const rawSenderParticipant = msg.key.participant ?? msg.key.remoteJid ?? "";
+                    const meta = await getGroupMetadataCached(contract, rawJid);
+                    // The adapter's pre-extracted participant fields give us both the
+                    // LID and PN forms of the sender; match either against the group's
+                    // own participant list.
+                    const rawSenderParticipant = msg.participantAlt ?? msg.fromLid ?? msg.fromPn ?? msg.chatId ?? "";
                     return meta.participants.some(p => matchesParticipant([sender, rawSenderParticipant], p.id) && (p.admin === "admin" || p.admin === "superadmin"));
                 }
                 catch {
@@ -1804,12 +1967,13 @@ export function buildApi({ msg, chat, sock, store, pluginRegistry, pluginName, g
             async isBotAdmin() {
                 if (!chat.isGroup)
                     return false;
-                const botLid = sock.user?.lid;
-                const botCandidates = [sock.user?.id, botLid];
+                const me = contract.me();
+                const botLid = me?.lid;
+                const botCandidates = [me.id, botLid];
                 if (!botCandidates.some(Boolean))
                     return false;
                 try {
-                    const meta = await getGroupMetadataCached(sock, rawJid);
+                    const meta = await getGroupMetadataCached(contract, rawJid);
                     return meta.participants.some(p => matchesParticipant(botCandidates, p.id) && (p.admin === "admin" || p.admin === "superadmin"));
                 }
                 catch {
@@ -1822,31 +1986,27 @@ export function buildApi({ msg, chat, sock, store, pluginRegistry, pluginName, g
             },
         },
         // ── admin ─────────────────────────────────────────────────────────────────
-        admin: buildAdminApi(sock, rawJid),
+        admin: buildAdminApi(contract, rawJid),
         // ── me ────────────────────────────────────────────────────────────────────
-        me: buildMeApi(sock),
+        me: buildMeApi(contract),
         // ── poll ──────────────────────────────────────────────────────────────────
-        poll: buildPollApi(sock, store, rawJid, guardOptions, pluginName),
+        poll: buildPollApi(contract, store, rawJid, guardOptions, pluginName),
         // ── settings ──────────────────────────────────────────────────────────────
         settings: buildSettingsApi(pluginName, normJid),
         // ── isolated platform contexts ────────────────────────────────────────────
         wa: {
-            sock,
+            contract,
             store,
             msg,
             downloadMedia: async (opts = {}) => {
                 try {
-                    const buffer = await downloadMediaMessage(msg, "buffer", {});
-                    if (!buffer || !Buffer.isBuffer(buffer))
+                    const result = await contract.downloadMedia(msg, opts);
+                    if (!result)
                         return null;
-                    const isAnimatedSticker = !!unwrap(msg)?.stickerMessage?.isAnimated;
-                    if (opts.asMp4 && isAnimatedSticker) {
-                        const mp4 = await stickerToMp4(buffer);
-                        return { mimetype: "video/mp4", data: mp4.toString("base64") };
-                    }
-                    return { mimetype: getMsgMimetype(msg), data: buffer.toString("base64") };
+                    return { mimetype: result.mimetype, data: result.data.toString("base64") };
                 }
-                catch {
+                catch (err) {
+                    logger.warn(`[whatsapp] downloadMedia failed: ${err.message}`);
                     return null;
                 }
             }