@manybot/manybot 5.7.0 → 5.9.0

package/dist/drivers/baileys/adapter.js

@@ -25,6 +25,7 @@
 import { normalizeMessageContent, downloadMediaMessage, jidNormalizedUser, decryptPollVote as baileysDecryptPollVote, getAggregateVotesInPollMessage, } from "@whiskeysockets/baileys";
 import { createHash } from "node:crypto";
 import { logger } from "#logger";
+import { splitLidPn } from "#drivers/jid.js";
 /**
  * Classify a Baileys message-content payload (`WAMessageContent`) into
  * the neutral `(type, body, mimetype)` triple used by `BotMessage`. Pure
@@ -72,6 +73,22 @@ export function decodeContent(content) {
         type = "sticker";
         mimetype = m.stickerMessage.mimetype ?? undefined;
     }
+    else if (m?.templateMessage) {
+        type = "text";
+        const tpl = m.templateMessage.hydratedTemplate ?? m.templateMessage.hydratedFourRowTemplate;
+        const buttonUrls = tpl?.hydratedButtons?.map((b) => b.urlButton?.url).filter(Boolean).join(" ") ?? "";
+        body = [tpl?.hydratedContentText ?? "", buttonUrls].filter(Boolean).join(" ");
+    }
+    else if (m?.interactiveMessage) {
+        type = "text";
+        const buttonParams = m.interactiveMessage.nativeFlowMessage?.buttons
+            ?.map((b) => b.buttonParamsJson).filter(Boolean).join(" ") ?? "";
+        body = [m.interactiveMessage.body?.text ?? "", buttonParams].filter(Boolean).join(" ");
+    }
+    else if (m?.buttonsMessage) {
+        type = "text";
+        body = [m.buttonsMessage.contentText ?? "", m.buttonsMessage.footerText ?? ""].filter(Boolean).join(" ");
+    }
     return { type, body, mimetype };
 }
 export function createBaileysAdapter(initial) {
@@ -115,6 +132,29 @@ export function createBaileysAdapter(initial) {
         // which throws if `.message` is missing.
         return { quoted: { key: toFlatKey(quoted), message: inner } };
     }
+    /**
+     * Merge `quoted` reply-citation with the chat's current
+     * `ephemeralExpiration` so every outgoing send in a chat with a
+     * disappearing-message timer inherits it automatically. Returns
+     * `undefined` when there's nothing to set, so callers can pass it
+     * through as the third argument to `sock.sendMessage` without
+     * conditionally building the options object.
+     *
+     * The timer is read off the in-memory store, which is populated by
+     * `chats.upsert` / `chats.update` / `messages.upsert` (via the
+     * `ephemeralMessage` envelope) and from `groupMetadata().ephemeralDuration`
+     * in this same adapter — i.e. everything WhatsApp tells us about the
+     * chat's timer ends up there, and the send path just reads it back.
+     */
+    function buildSendOpts(jid, quoted) {
+        const quotedOpts = buildQuotedOpts(quoted);
+        const timer = store.chats.get(jid)?.ephemeralExpiration;
+        if (!timer)
+            return quotedOpts;
+        if (!quotedOpts)
+            return { ephemeralExpiration: timer };
+        return { ...quotedOpts, ephemeralExpiration: timer };
+    }
     /**
      * Translate a neutral `BotQuotedRef` into the FLAT key shape Baileys
      * expects for `react`/`delete`/`edit`/`readMessages` (proto.IMessageKey
@@ -141,7 +181,17 @@ export function createBaileysAdapter(initial) {
         }
         return hash.digest("hex");
     }
-    /** Translate a Baileys WAMessage into the neutral BotMessage envelope. */
+    /** Normalize a mentioned JID: convert PN JIDs to LID when a mapping is known. */
+    function normalizeMentionedJid(jid) {
+        if (!jid)
+            return jid;
+        // Already LID — pass through.
+        if (jid.endsWith("@lid"))
+            return jid;
+        // Phone-based JID: look up the LID in the reverse map.
+        const lid = store.resolvePn(jid);
+        return lid ?? jid;
+    }
     function toBotMessage(msg) {
         const m = normalizeMessageContent(msg.message) ?? undefined;
         const { type, body, mimetype } = decodeContent(msg.message);
@@ -151,8 +201,16 @@ export function createBaileysAdapter(initial) {
             m?.videoMessage?.contextInfo ??
             m?.audioMessage?.contextInfo ??
             m?.documentMessage?.contextInfo ??
+            m?.templateMessage?.contextInfo ??
+            m?.interactiveMessage?.contextInfo ??
+            m?.buttonsMessage?.contextInfo ??
             undefined;
         const ciTyped = contextInfo;
+        // See splitLidPn() — `key.participant`/`key.remoteJid` are only the PN
+        // form under legacy `addressingMode: "pn"`; under the modern default
+        // "lid" mode they're already the LID and the *Alt field carries the PN.
+        const participantIds = splitLidPn(key.participant, key.participantAlt);
+        const remoteJidIds = splitLidPn(key.remoteJid, key.remoteJidAlt);
         return {
             id: msg.key.id ?? "",
             chatId: msg.key.remoteJid ?? "",
@@ -163,17 +221,23 @@ export function createBaileysAdapter(initial) {
             body,
             mimetype: mimetype ?? undefined,
             pushName: msg.pushName,
-            mentionedJid: ciTyped?.mentionedJid ?? undefined,
+            mentionedJid: ciTyped?.mentionedJid?.map(normalizeMentionedJid) ?? undefined,
             quotedKey: ciTyped?.stanzaId ? {
                 id: ciTyped.stanzaId,
                 remoteJid: msg.key.remoteJid ?? undefined,
                 fromMe: false,
                 participant: ciTyped.participant ?? undefined,
             } : undefined,
-            fromLid: key.participantAlt,
-            fromPn: key.participant,
-            participantAlt: key.participantAlt,
-            remoteJidAlt: key.remoteJidAlt,
+            // Resolve LID/PN by actual JID suffix, not by field position — see
+            // splitLidPn() for why `key.participantAlt` can't be trusted to
+            // always be the LID. `participantAlt`/`remoteJidAlt` below are
+            // reassigned to the suffix-verified LID (or `undefined` if neither
+            // candidate is one), so every existing consumer that reads them
+            // directly gets the corrected value for free.
+            fromLid: participantIds.lid,
+            fromPn: participantIds.pn,
+            participantAlt: participantIds.lid,
+            remoteJidAlt: remoteJidIds.lid,
             // Driver-specific escape hatches:
             //   - pollEncKeyRaw: poll-decryption key for vote decryption
             //   - contextInfo:   full IContextInfo (incl. embedded quotedMessage)
@@ -295,7 +359,7 @@ export function createBaileysAdapter(initial) {
         async sendText(jid, text, opts) {
             const content = { text };
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const sendOpts = buildQuotedOpts(opts?.quoted);
+            const sendOpts = buildSendOpts(jid, opts?.quoted);
             if (opts?.mentions?.length)
                 content.mentions = opts.mentions;
             const ref = await sock.sendMessage(jid, content, sendOpts);
@@ -309,7 +373,7 @@ export function createBaileysAdapter(initial) {
                 content.viewOnce = true;
             if (opts?.mentions?.length)
                 content.mentions = opts.mentions;
-            const ref = await sock.sendMessage(jid, content, buildQuotedOpts(opts?.quoted));
+            const ref = await sock.sendMessage(jid, content, buildSendOpts(jid, opts?.quoted));
             return toSentRef(ref, jid);
         },
         async sendVideo(jid, buffer, opts) {
@@ -322,7 +386,7 @@ export function createBaileysAdapter(initial) {
                 content.gifPlayback = true;
             if (opts?.mentions?.length)
                 content.mentions = opts.mentions;
-            const ref = await sock.sendMessage(jid, content, buildQuotedOpts(opts?.quoted));
+            const ref = await sock.sendMessage(jid, content, buildSendOpts(jid, opts?.quoted));
             return toSentRef(ref, jid);
         },
         async sendAudio(jid, buffer, opts) {
@@ -332,20 +396,20 @@ export function createBaileysAdapter(initial) {
                 content.ptt = true;
             if (opts?.viewOnce)
                 content.viewOnce = true;
-            const ref = await sock.sendMessage(jid, content, buildQuotedOpts(opts?.quoted));
+            const ref = await sock.sendMessage(jid, content, buildSendOpts(jid, opts?.quoted));
             return toSentRef(ref, jid);
         },
         async sendSticker(jid, buffer, opts) {
-            const ref = await sock.sendMessage(jid, { sticker: buffer }, buildQuotedOpts(opts?.quoted));
+            const ref = await sock.sendMessage(jid, { sticker: buffer }, buildSendOpts(jid, opts?.quoted));
             return toSentRef(ref, jid);
         },
         async sendDocument(jid, buffer, filename, mimetype, opts) {
-            const ref = await sock.sendMessage(jid, { document: buffer, mimetype, fileName: filename }, buildQuotedOpts(opts?.quoted));
+            const ref = await sock.sendMessage(jid, { document: buffer, mimetype, fileName: filename }, buildSendOpts(jid, opts?.quoted));
             return toSentRef(ref, jid);
         },
         async sendPoll(jid, opts) {
             const poll = { name: opts.name, values: opts.values, selectableCount: opts.selectableCount ?? 1 };
-            const ref = await sock.sendMessage(jid, { poll }, buildQuotedOpts(opts.quoted));
+            const ref = await sock.sendMessage(jid, { poll }, buildSendOpts(jid, opts.quoted));
             return toSentRef(ref, jid);
         },
         async react(jid, target, emoji) {
@@ -427,6 +491,25 @@ export function createBaileysAdapter(initial) {
         // ── groups ─────────────────────────────────────────────────────────────
         async groupMetadata(jid) {
             const meta = await sock.groupMetadata(jid);
+            // WhatsApp reports the group's current disappearing-message
+            // timer as `ephemeralDuration` on the metadata payload — promote
+            // it to the in-memory store so the next send to this group
+            // picks it up automatically (and so the timer survives a
+            // snapshot round-trip without us re-fetching metadata).
+            const rawDuration = meta.ephemeralDuration;
+            if (rawDuration !== undefined) {
+                store.setChatEphemeralExpiration(jid, Number(rawDuration) || 0);
+            }
+            // Baileys v7's GroupMetadata carries per-participant `id` (LID, the
+            // addressing mode the group uses) AND `phoneNumber` (the traditional
+            // PN form). Feed the LID↔PN store for any participant that carries
+            // both — passive cache, never a network call.
+            for (const p of meta.participants) {
+                const lid = p.id;
+                const phone = p.phoneNumber;
+                if (lid && phone)
+                    store.learnLid(lid, phone);
+            }
             return {
                 subject: meta.subject,
                 participants: meta.participants.map(p => ({
@@ -676,8 +759,37 @@ export function createBaileysAdapter(initial) {
             emit("contacts.update", { updates: arg.map(contactSummary) });
         });
         register("group-participants.update", (arg) => {
-            const { id, participants } = arg;
-            emit("group-participants.update", { id, participants });
+            // Baileys v7 ships `participants` as GroupParticipant[] (Contact & { admin… }),
+            // carrying `id`, `lid?`, and `phoneNumber?` per entry. The kernel-public
+            // contract still uses `string[]` of JIDs (one per participant), so we
+            // project `id` down here — but we also take the opportunity to feed the
+            // LID↔PN store from the richer data while we have it: when a single
+            // payload delivers both forms of the same identity, that's the cleanest
+            // mapping we can ever hope to learn.
+            const a = arg;
+            const jids = a.participants.map(p => jidNormalizedUser(p.id));
+            for (const p of a.participants) {
+                // v7 sometimes provides both forms; sometimes only one. Use whichever
+                // is available — learnLid() filters out incomplete or non-LID inputs.
+                // The richest case is `lid` + `phoneNumber` both explicit; otherwise
+                // we accept `lid`+`id` or `id`+`phoneNumber` (Baileys commonly puts
+                // the LID in `id` and the PN in `phoneNumber` on group metadata).
+                if (p.lid && p.phoneNumber)
+                    store.learnLid(p.lid, p.phoneNumber);
+                else if (p.lid && p.id)
+                    store.learnLid(p.lid, p.id);
+                else if (p.id && p.phoneNumber)
+                    store.learnLid(p.id, p.phoneNumber);
+            }
+            // authorPn (the inviter's PN) is the same source of truth — feed it too.
+            if (a.author && a.authorPn)
+                store.learnLid(a.author, a.authorPn);
+            emit("group-participants.update", {
+                id: a.id,
+                author: a.author,
+                participants: jids,
+                action: a.action,
+            });
         });
         register("groups.upsert", (arg) => {
             const groups = arg;
@@ -687,7 +799,13 @@ export function createBaileysAdapter(initial) {
             emit("groups.update", { updates: arg });
         });
         register("group.join-request", (arg) => {
+            // Baileys v7 emits `participantPn` (and `authorPn`) on the join-request
+            // payload — feed the LID↔PN store from those while we have both sides.
             const a = arg;
+            if (a.participant && a.participantPn)
+                store.learnLid(a.participant, a.participantPn);
+            if (a.author && a.authorPn)
+                store.learnLid(a.author, a.authorPn);
             emit("group.join-request", {
                 id: a.id,
                 author: a.author,

package/dist/drivers/baileys/api/contacts.integration.test.js

@@ -0,0 +1,261 @@
+/**
+ * src/drivers/baileys/api/contacts.integration.test.ts
+ *
+ * Real-WhatsApp integration tests for the LID-aware contact API surface
+ * (`IContact.id` is LID-or-null, `number`/`numberRaw`/`numberPretty`/
+ * `country`/`countryCallingCode` populated by libphonenumber-js).
+ *
+ * Exercises the full driver stack end-to-end:
+ *   - The integration plugin (gated by `MANYBOT_RUN_WHATSAPP_TESTS=1`)
+ *     drives real sends + listens for the test marker's echo.
+ *   - Each test sends a uniquely-prefixed message into the configured
+ *     `TEST_CHAT`, waits for the round-trip, then reads
+ *     `ctx.contacts.get(...)` from a freshly-built plugin context and
+ *     asserts the new shape is honored against a live WhatsApp account.
+ *
+ * All tests skip when integration mode is not fully ready (no opt-in,
+ * no `TEST_CHAT`, or no saved WhatsApp session). Skipped tests do not
+ * count as failures — they're informational.
+ *
+ * Requires:
+ *   - `MANYBOT_RUN_WHATSAPP_TESTS=1`
+ *   - `TEST_CHAT="<phone>"` (env or manybot.toml) — MUST be an
+ *     individual chat (a bare phone number, or a JID ending in
+ *     `@s.whatsapp.net`/`@c.us`/`@lid`), NOT a group (`@g.us`).
+ *     Every assertion below reads per-person contact fields (LID,
+ *     E.164 number, numberPretty, country, countryCallingCode) —
+ *     `normalizeContact()` (src/drivers/baileys/api/index.ts) never
+ *     populates any of those for a group JID, since a group has no
+ *     LID or phone number of its own. Sending/receiving still works
+ *     fine against a group (the round-trip itself doesn't care), so
+ *     a group `TEST_CHAT` will pass the integration-mode gate and
+ *     even echo markers successfully, then fail every shape
+ *     assertion below with `expected: /@lid$/, actual: "...@g.us"`
+ *     (and `null` for number/country/etc.) — if you see that
+ *     specific failure pattern, point TEST_CHAT at a DM instead.
+ *   - A logged-in WhatsApp session (creds.json + app-state-sync-… in
+ *     CONFIG_DIR, same as a normal run).
+ *   - Either:
+ *       - `npm run test:integration:local`  — boots `src/main.ts` first
+ *         so the bot connects and the integration plugin is registered;
+ *       - a one-shot manual run with the integration plugin loaded by
+ *         the caller (see scripts/probe-contacts.mjs).
+ *
+ * `npm run test:integration` (without `:local`) is supported but every
+ * test will skip because no live socket exists in that mode.
+ */
+import test, { describe } from "node:test";
+import assert from "node:assert/strict";
+import { loadIntegrationPlugin, pluginRegistry, getGlobalKernelRefs, } from "#kernel/pluginLoader.js";
+import { getIntegrationModeStatus, INTEGRATION_PLUGIN_NAME } from "#kernel/integrationMode.js";
+import { logger } from "#logger";
+// ── Integration-mode gate (resolved at top level) ────────────────────────────
+//
+// Two distinct gates need to pass before a test runs:
+//
+//   1. Configuration gate (`getIntegrationModeStatus().ready`):
+//      MANYBOT_RUN_WHATSAPP_TESTS=1 is set AND TEST_CHAT is configured
+//      (env or manybot.toml). This is what `npm run test:integration`
+//      auto-enables via the script's env prefix.
+//
+//   2. Live-socket gate (`getGlobalKernelRefs() !== null`):
+//      The Baileys driver has actually connected at least once so a
+//      `WaContract` is available for real sends. With
+//      `npm run test:integration:local` (which boots main.ts first),
+//      this resolves as soon as the bot connects. With the bare
+//      `npm run test:integration` (no main.ts preload), it never
+//      resolves and every test skips — which is correct.
+//
+// We resolve both gates up-front (top-level await) instead of in a
+// `before()` hook so the `{ skip: !integrationReady }` option on
+// each `test()` call is honored by the runner — an early-return
+// inside the test body looks like `pass: N` in CI output, which is
+// confusing when scanning for "did this actually run?".
+let integrationReady = false;
+let integrationSkipReason = "not evaluated";
+let integrationChat = null;
+let kernelRefs = null;
+async function evaluateGates() {
+    const status = await getIntegrationModeStatus();
+    const configReady = status.ready;
+    const configReason = status.reason ?? "";
+    integrationChat = status.chat;
+    // Make sure the integration plugin is registered — its `setup()`
+    // populates `api.testChat` and `api.waitForMarker`, both needed by
+    // the test helpers below. When the bot is already running (the
+    // `:local` variant), `loadPlugins`/`setupPlugins` ran during boot
+    // and called `loadIntegrationPlugin()` for us; `loadIntegrationPlugin`
+    // is idempotent so calling it again here is safe.
+    if (configReady) {
+        try {
+            await loadIntegrationPlugin();
+        }
+        catch (e) {
+            logger.warn(`[contacts.integration] loadIntegrationPlugin failed: ${e.message}`);
+        }
+    }
+    // With `npm run test:integration:local`, main.ts is preloaded and
+    // begins connecting as soon as it's imported — the test runner may
+    // execute this file before the connection has resolved. Poll for
+    // the global refs for up to 60s before giving up; this lets
+    // contributors run the suite immediately after `node main.ts` and
+    // have it work without manual timing.
+    const SOCKET_WAIT_MS = 60_000;
+    const deadline = Date.now() + SOCKET_WAIT_MS;
+    while (Date.now() < deadline) {
+        kernelRefs = getGlobalKernelRefs();
+        if (kernelRefs)
+            break;
+        await new Promise((r) => setTimeout(r, 250));
+    }
+    const socketReady = kernelRefs !== null;
+    integrationReady = configReady && socketReady;
+    integrationSkipReason = !configReady
+        ? configReason
+        : `bot did not connect within ${SOCKET_WAIT_MS / 1000}s — check the main.ts preload output for connection errors`;
+    if (integrationReady) {
+        logger.info(`[contacts.integration] integration mode ready — chat=${integrationChat} ` +
+            `kernelRefs=${!!kernelRefs}`);
+    }
+    else {
+        logger.warn(`[contacts.integration] integration mode NOT ready — ${integrationSkipReason}. ` +
+            `Every test in this file will skip.`);
+    }
+}
+// Resolve the gates up-front. Top-level await pauses module
+// initialization until `evaluateGates()` resolves, so by the time any
+// `test()` call below is reached the `integrationReady` flag is
+// stable. This is what lets us pass `{ skip: !integrationReady }` to
+// each test — `node:test` honors the flag at test-definition time.
+await evaluateGates();
+function getIntegrationApi() {
+    const entry = pluginRegistry.get(INTEGRATION_PLUGIN_NAME);
+    if (!entry || entry.status !== "active")
+        return null;
+    return entry.exports;
+}
+const ROUND_TRIP_TIMEOUT_MS = 30_000;
+/**
+ * Send a marker-prefixed message into the test chat and wait for an
+ * inbound message with the same marker — exercises the round-trip
+ * (BotStore + adapter + listener + contact store feeding) that the
+ * LID/PN resolution depends on.
+ */
+async function sendAndAwaitEcho(api, contract, marker, opts) {
+    await contract.sendText(api.testChat, marker, opts);
+    await api.waitForMarker(marker, ROUND_TRIP_TIMEOUT_MS);
+}
+// ── Tests ────────────────────────────────────────────────────────────────────
+//
+// All tests below pass `{ skip: !integrationReady }` so they report
+// as `skipped` in CI output (not `pass`) when the integration suite
+// can't actually run. The `if (!integrationReady) return;` guard at
+// the top of each test body is belt-and-braces — if the skip flag is
+// ever ignored (e.g. someone wires this suite into a different
+// runner), the test still no-ops instead of crashing on a null
+// `integrationChat`.
+describe("contacts.integration — gate", () => {
+    test("integration mode reports ready (sanity)", { skip: !integrationReady }, () => {
+        assert.ok(integrationSkipReason, "skip reason must explain the skip");
+        assert.equal(integrationReady, true, "integration mode must be ready for this suite to run");
+        assert.ok(integrationChat, "integration chat must be configured when ready");
+        assert.ok(kernelRefs, "live WaContract must be available when integration mode is ready");
+    });
+});
+describe("contacts.integration — IContact shape on a live WhatsApp account", () => {
+    test("id is the LID form (preferred canonical identifier)", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs, "integration api + kernel refs must be available");
+        const marker = `ICONTACT-ID-${Date.now()}-`;
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker);
+        const me = await (await import("#drivers/baileys/api/index.js")).buildContactsApi(kernelRefs.contract, kernelRefs.store, null).get(api.testChat);
+        assert.ok(me, "expected contacts.get to resolve the test chat");
+        assert.match(me.id ?? "", /@lid$/, `expected id to be @lid form, got ${me.id}`);
+    });
+    test("number is canonical E.164 with leading +", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs);
+        const marker = `ICONTACT-NUMBER-${Date.now()}-`;
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker);
+        const me = await (await import("#drivers/baileys/api/index.js")).buildContactsApi(kernelRefs.contract, kernelRefs.store, null).get(api.testChat);
+        assert.match(me.number ?? "", /^\+\d+$/, `expected E.164 with +, got ${me.number}`);
+    });
+    test("numberPretty is internationally formatted", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs);
+        const marker = `ICONTACT-PRETTY-${Date.now()}-`;
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker);
+        const me = await (await import("#drivers/baileys/api/index.js")).buildContactsApi(kernelRefs.contract, kernelRefs.store, null).get(api.testChat);
+        assert.ok((me.numberPretty ?? "").startsWith("+"), `expected pretty form to start with +, got ${me.numberPretty}`);
+    });
+    test("country is ISO alpha-2", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs);
+        const marker = `ICONTACT-COUNTRY-${Date.now()}-`;
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker);
+        const me = await (await import("#drivers/baileys/api/index.js")).buildContactsApi(kernelRefs.contract, kernelRefs.store, null).get(api.testChat);
+        assert.match(me.country ?? "", /^[A-Z]{2}$/, `expected ISO alpha-2, got ${me.country}`);
+    });
+    test("countryCallingCode is the ITU dial code", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs);
+        const marker = `ICONTACT-CC-${Date.now()}-`;
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker);
+        const me = await (await import("#drivers/baileys/api/index.js")).buildContactsApi(kernelRefs.contract, kernelRefs.store, null).get(api.testChat);
+        assert.match(me.countryCallingCode ?? "", /^\d{1,4}$/, `expected ITU dial code, got ${me.countryCallingCode}`);
+    });
+});
+describe("contacts.integration — LID↔PN cache populated by a real round-trip", () => {
+    test("after one round-trip the @s.whatsapp.net form resolves back to LID", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs);
+        const marker = `PNMAP-CACHE-${Date.now()}-`;
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker);
+        const lid = kernelRefs.store.resolvePn(api.testChat);
+        assert.ok(lid, `expected pnMap to have learned the LID for ${api.testChat}`);
+        assert.match(lid, /@lid$/, `expected resolved LID, got ${lid}`);
+    });
+    test("contacts.get(normalizedPn) returns LID-backed IContact after cache warmup", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs);
+        const marker = `GET-PN-RESOLVES-LID-${Date.now()}-`;
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker);
+        const me = await (await import("#drivers/baileys/api/index.js")).buildContactsApi(kernelRefs.contract, kernelRefs.store, null).get(api.testChat);
+        assert.match(me.id ?? "", /@lid$/, "expected LID form after cache warmup");
+    });
+});
+describe("contacts.integration — mentionedJid is normalized to LID form", () => {
+    test("sending a real mention succeeds and the store learns a LID↔PN pair", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs);
+        const marker = `MENTION-LID-${Date.now()}-`;
+        // WaContract.sendText() already accepts `mentions` — no need to reach
+        // into Baileys internals to send a real mention (see waContract.ts).
+        // Modern WhatsApp delivers contextInfo.mentionedJid in @lid form
+        // already (confirmed against WhiskeySockets/Baileys#1683/#1667), so
+        // there's no PN→LID "resolution" for a mention to teach — this test
+        // just proves the send round-trips and, if the account has a phone
+        // number mapping learned along the way (e.g. via the contact/message
+        // sync that accompanies any real WhatsApp exchange), the store
+        // reflects it.
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker, { mentions: [api.testChat] });
+        const bodies = api.recentBodies();
+        assert.ok(bodies.some((b) => b.startsWith(marker)), `expected recent bodies to include "${marker}" — got ${JSON.stringify(bodies)}`);
+        const lidKeys = Object.keys(kernelRefs.store.contacts).filter((k) => k.endsWith("@lid"));
+        assert.ok(lidKeys.length > 0, `expected store.contacts to contain at least one @lid key after mention round-trip — got ${JSON.stringify(Object.keys(kernelRefs.store.contacts))}`);
+    });
+});
+// ── Live-harness readiness probe ────────────────────────────────────────────
+//
+// Single test that fails (rather than skips) when the harness is
+// missing a piece — useful so a contributor who has TEST_CHAT + a
+// session can immediately see what's still left to wire. Skips
+// cleanly when integration mode isn't ready at all.
+describe("contacts.integration — harness readiness", () => {
+    test("integration plugin is registered and active", { skip: !integrationReady }, () => {
+        const entry = pluginRegistry.get(INTEGRATION_PLUGIN_NAME);
+        assert.ok(entry, `expected "${INTEGRATION_PLUGIN_NAME}" to be registered in pluginRegistry`);
+        assert.equal(entry.status, "active", `expected plugin status "active", got "${entry.status}"`);
+        assert.ok(entry.exports, "expected integration plugin exports to be populated");
+    });
+});