@manybot/manybot 5.7.0 → 5.9.0

package/dist/kernel/sendFallbackGuard.test.js

@@ -0,0 +1,80 @@
+import test, { describe, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { sendWithFallback, SendFailedError } from "#kernel/sendFallbackGuard.js";
+import { getDriverManager, _resetDriverManagerForTests } from "#kernel/driverManager.js";
+function createMockDriver(name, ready = true, failsSend = false, failsVerify = false) {
+    const mockRef = (id) => ({ id, chatId: "123@c.us", timestamp: Date.now() });
+    return {
+        name,
+        isReady: () => ready,
+        sendText: async (jid, text) => {
+            if (failsSend)
+                throw new Error(`${name} sendText failed`);
+            return mockRef(`msg_${name}`);
+        },
+        getHistory: async () => {
+            if (failsVerify)
+                return [];
+            return [{ id: `msg_${name}`, fromMe: true }];
+        },
+        connect: async () => { },
+        disconnect: async () => { },
+        me: () => ({ id: "123@c.us" }),
+        sendImage: async () => mockRef("image"),
+        sendVideo: async () => mockRef("video"),
+        sendAudio: async () => mockRef("audio"),
+        sendDocument: async () => mockRef("doc"),
+        sendSticker: async () => mockRef("sticker"),
+        sendLocation: async () => mockRef("loc"),
+        sendContact: async () => mockRef("contact"),
+        sendReaction: async () => { },
+        sendPoll: async () => mockRef("poll"),
+        react: async () => { },
+        deleteMessage: async () => { },
+        editMessage: async () => { },
+        sendPresenceUpdate: async () => { },
+        readMessages: async () => { },
+        onWhatsApp: async () => null,
+        getBusinessProfile: async () => null,
+        profilePictureUrl: async () => null,
+        fetchStatus: async () => null,
+        updateBlockStatus: async () => { },
+        addOrEditContact: async () => { },
+        removeContact: async () => { },
+        groupMetadata: async () => ({ subject: "Test Group", participants: [] }),
+        groupParticipantsUpdate: async () => [],
+        groupUpdateSubject: async () => { },
+        groupUpdateDescription: async () => { },
+        groupInviteCode: async () => "",
+        groupRevokeInvite: async () => "",
+        updateProfilePicture: async () => { },
+        updateProfileName: async () => { },
+        updateProfileStatus: async () => { },
+        downloadMedia: async () => null,
+        on: () => () => { },
+    };
+}
+describe("kernel/sendFallbackGuard", () => {
+    beforeEach(() => {
+        _resetDriverManagerForTests();
+    });
+    test("delivers text via primary driver when healthy", async () => {
+        const dm = getDriverManager();
+        const primary = createMockDriver("baileys");
+        dm.register(primary, { isPrimary: true });
+        const ref = await sendWithFallback("5511999999999@c.us", "hello");
+        assert.equal(ref.id, "msg_baileys");
+    });
+    test("throws SendFailedError with no_fallback when send fails", async () => {
+        const dm = getDriverManager();
+        const primaryFailing = createMockDriver("baileys", true, true);
+        dm.register(primaryFailing, { isPrimary: true });
+        await assert.rejects(async () => sendWithFallback("5511999999999@c.us", "no fallback"), (err) => err instanceof SendFailedError && err.reason === "no_fallback");
+    });
+    test("throws SendFailedError with no_fallback when verification fails", async () => {
+        const dm = getDriverManager();
+        const primaryFailing = createMockDriver("baileys", true, false, true);
+        dm.register(primaryFailing, { isPrimary: true });
+        await assert.rejects(async () => sendWithFallback("5511999999999@c.us", "verify fail"), (err) => err instanceof SendFailedError && err.reason === "no_fallback");
+    });
+});

package/dist/kernel/sendGuard.js

@@ -10,8 +10,9 @@
  *   4. Chat-concurrency gate — caps how many different chats the bot can be
  *                              actively answering at the same time
  *   5. Edit throttle         — jittered minimum gap + cap on edits per
- *                              message, so things like loading animations
- *                              don't edit on a fixed, bot-like cadence
+ *                              message. Only active at SECURITY_LEVEL
+ *                              "high"; low/medium leave edit timing to the
+ *                              caller.
  *
  * All of the above scale with SECURITY_LEVEL ("low" | "medium" | "high").
  * Higher levels are slower and more conservative — lower risk of WhatsApp's
@@ -28,8 +29,6 @@ const PROFILES = {
         chatCooldownMs: 100,
         jitterMs: { min: 30, max: 120 },
         concurrency: Infinity,
-        editIntervalMs: { min: 800, max: 2000 },
-        maxEditsPerMessage: 20,
         typingMaxMs: 2000,
     },
     medium: {
@@ -37,8 +36,6 @@ const PROFILES = {
         chatCooldownMs: 150,
         jitterMs: { min: 50, max: 200 },
         concurrency: 2,
-        editIntervalMs: { min: 1200, max: 3000 },
-        maxEditsPerMessage: 12,
         typingMaxMs: 4000,
     },
     high: {
@@ -46,9 +43,11 @@ const PROFILES = {
         chatCooldownMs: 400,
         jitterMs: { min: 150, max: 500 },
         concurrency: 1,
-        editIntervalMs: { min: 2000, max: 5000 },
-        maxEditsPerMessage: 6,
         typingMaxMs: 8000,
+        editThrottle: {
+            minGapMs: { min: 800, max: 2000 },
+            maxEditsPerMessage: 5,
+        },
     },
 };
 function currentProfile() {
@@ -147,40 +146,6 @@ export async function acquireChatSlot(jid) {
         });
     });
 }
-const editState = new Map();
-const EDIT_STATE_STALE_MS = 10 * 60 * 1000;
-function cleanupEditState(now) {
-    for (const [id, s] of editState) {
-        if (now - s.lastEditAt > EDIT_STATE_STALE_MS)
-            editState.delete(id);
-    }
-}
-/**
- * Waits for a safe edit slot for `messageId`, applying a jittered minimum
- * gap since its last edit. Returns false once the message has hit its
- * per-level edit cap — callers should skip the edit silently in that case.
- * @param {string} messageId
- * @returns {Promise<boolean>} true if the edit may proceed
- */
-export async function waitForEditSlot(messageId) {
-    const now = Date.now();
-    cleanupEditState(now);
-    const profile = currentProfile();
-    const s = editState.get(messageId) ?? { lastEditAt: 0, count: 0 };
-    if (s.count >= profile.maxEditsPerMessage) {
-        editState.set(messageId, s);
-        logger.debug(`[sendGuard] edit cap reached for ${messageId}`);
-        return false;
-    }
-    const minGap = randomBetween(profile.editIntervalMs);
-    const wait = s.lastEditAt + minGap - Date.now();
-    if (wait > 0)
-        await sleep(wait);
-    s.lastEditAt = Date.now();
-    s.count += 1;
-    editState.set(messageId, s);
-    return true;
-}
 // ── Public API ────────────────────────────────────────────────────────────────
 /**
  * Wait for a safe send slot: global rate → per-chat cooldown → jitter.
@@ -208,6 +173,37 @@ export async function waitForSendSlot(jid, { cooldown = true, jitter = true } =
         await sleep(randomBetween(currentProfile().jitterMs));
     recordSend(jid);
 }
+// ── Edit throttle ─────────────────────────────────────────────────────────────
+// Only enforced when the active profile defines `editThrottle` (currently
+// just "high"). low/medium always allow immediately.
+const editState = new Map();
+/**
+ * Wait for a safe edit slot for `messageId`, then record the edit.
+ * Returns `false` if the per-message edit cap has been reached — the
+ * caller should drop the edit instead of sending it.
+ *
+ * @param {string} messageId
+ * @returns {Promise<boolean>} whether the edit is allowed to proceed
+ */
+export async function waitForEditSlot(messageId) {
+    const throttle = currentProfile().editThrottle;
+    if (!throttle)
+        return true;
+    const state = editState.get(messageId) ?? { count: 0, lastEditAt: 0 };
+    if (state.count >= throttle.maxEditsPerMessage) {
+        logger.debug(`[sendGuard] edit cap (${throttle.maxEditsPerMessage}) reached for message ${messageId} — dropping edit`);
+        return false;
+    }
+    const gap = randomBetween(throttle.minGapMs);
+    const elapsed = Date.now() - state.lastEditAt;
+    if (state.lastEditAt > 0 && elapsed < gap) {
+        await sleep(gap - elapsed);
+    }
+    state.count++;
+    state.lastEditAt = Date.now();
+    editState.set(messageId, state);
+    return true;
+}
 /**
  * Show a presence indicator for `ms` milliseconds, then clear it.
  * Best-effort — errors are swallowed.

package/dist/kernel/sendGuard.test.js

@@ -0,0 +1,102 @@
+import test, { describe, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { CONFIG } from "#config";
+import { typingDuration, mediaDuration, acquireChatSlot, simulateState, waitForSendSlot } from "#kernel/sendGuard.js";
+describe("kernel/sendGuard", () => {
+    beforeEach(() => {
+        CONFIG.SECURITY_LEVEL = "medium";
+    });
+    describe("typingDuration", () => {
+        test("returns 0 for empty or invalid text", () => {
+            assert.equal(typingDuration(""), 0);
+            assert.equal(typingDuration(null), 0);
+        });
+        test("calculates duration based on CPS and caps at profile typingMaxMs", () => {
+            CONFIG.SECURITY_LEVEL = "medium"; // typingMaxMs = 4000
+            // 90 chars at 90 CPS = 1000 ms
+            const text90 = "a".repeat(90);
+            assert.equal(typingDuration(text90), 1000);
+            // 900 chars at 90 CPS = 10000 ms -> capped at 4000 ms
+            const text900 = "a".repeat(900);
+            assert.equal(typingDuration(text900), 4000);
+        });
+        test("respects SECURITY_LEVEL profile caps", () => {
+            const text900 = "a".repeat(900);
+            CONFIG.SECURITY_LEVEL = "low"; // cap = 2000
+            assert.equal(typingDuration(text900), 2000);
+            CONFIG.SECURITY_LEVEL = "high"; // cap = 8000
+            assert.equal(typingDuration(text900), 8000);
+        });
+    });
+    describe("mediaDuration", () => {
+        test("returns base jitter range when no caption is provided", () => {
+            const duration = mediaDuration();
+            assert.ok(duration >= 400 && duration <= 1000);
+        });
+        test("adds typing duration when caption is provided", () => {
+            CONFIG.SECURITY_LEVEL = "medium";
+            const text90 = "a".repeat(90); // 1000ms typing
+            const duration = mediaDuration(text90);
+            assert.ok(duration >= 1400 && duration <= 2000);
+        });
+    });
+    describe("acquireChatSlot (concurrency gate)", () => {
+        test("allows up to profile concurrency before blocking", async () => {
+            CONFIG.SECURITY_LEVEL = "high"; // concurrency = 1
+            const release1 = await acquireChatSlot("chat1");
+            let slot2Acquired = false;
+            const promise2 = acquireChatSlot("chat2").then(rel => {
+                slot2Acquired = true;
+                return rel;
+            });
+            // Give microtask tick to verify slot2 is waiting
+            await new Promise(r => setImmediate(r));
+            assert.equal(slot2Acquired, false);
+            // Release slot 1 allows slot 2 to proceed
+            release1();
+            const release2 = await promise2;
+            assert.equal(slot2Acquired, true);
+            release2();
+        });
+    });
+    describe("simulateState", () => {
+        test("sends presence update composing/recording, waits, then sends paused", async (t) => {
+            t.mock.timers.enable({ apis: ["setTimeout"] });
+            const updates = [];
+            const mockContract = {
+                sendPresenceUpdate: async (state, jid) => {
+                    updates.push({ state, jid });
+                }
+            };
+            const simPromise = simulateState(mockContract, "123@c.us", 1000, "typing");
+            // simulateState awaits the first presence update before scheduling its
+            // timeout, so let that continuation run before advancing mock time.
+            await Promise.resolve();
+            t.mock.timers.tick(1000);
+            await simPromise;
+            assert.deepEqual(updates, [
+                { state: "composing", jid: "123@c.us" },
+                { state: "paused", jid: "123@c.us" }
+            ]);
+        });
+        test("handles non-fatal contract errors gracefully", async () => {
+            const failingContract = {
+                sendPresenceUpdate: async () => {
+                    throw new Error("Network error");
+                }
+            };
+            // Should not throw exception
+            await assert.doesNotReject(async () => {
+                await simulateState(failingContract, "123@c.us", 100, "typing");
+            });
+        });
+    });
+    describe("waitForSendSlot", () => {
+        test("completes send throttle without errors", async (t) => {
+            t.mock.timers.enable({ apis: ["setTimeout", "Date"] });
+            const sendPromise = waitForSendSlot("123@c.us", { cooldown: false, jitter: false });
+            t.mock.timers.tick(500);
+            await sendPromise;
+        });
+    });
+});

package/dist/kernel/settingsDb.js

@@ -14,9 +14,10 @@ import { DatabaseSync } from "node:sqlite";
 import path from "path";
 import { mkdirSync } from "fs";
 import { CONFIG_DIR } from "#config";
-// ── DB init ───────────────────────────────────────────────────────────────────
-const DB_PATH = path.join(CONFIG_DIR, "settings.db");
-mkdirSync(path.dirname(DB_PATH), { recursive: true });
+const DB_PATH = process.env.NODE_ENV === "test" ? ":memory:" : path.join(CONFIG_DIR, "settings.db");
+if (DB_PATH !== ":memory:") {
+    mkdirSync(path.dirname(DB_PATH), { recursive: true });
+}
 const db = new DatabaseSync(DB_PATH);
 db.exec("PRAGMA journal_mode = WAL");
 db.exec("PRAGMA foreign_keys = ON");
@@ -93,6 +94,17 @@ function dbDelete(pluginName, chatId, key) {
 function dbDeleteAll(pluginName, chatId) {
     stmts.deleteAll.run(pluginName, chatId);
 }
+/**
+ * Direct read of a single (plugin, chat, key) setting, bypassing the
+ * `ctx.settings` scoped-accessor pattern. For call sites that need a
+ * value before a `PluginContext` exists yet — e.g. resolving the
+ * per-chat command prefix while still parsing the incoming message,
+ * or resolving the per-chat language from outside the "core" plugin's
+ * own context. See `kernel/chatOverrides.ts`.
+ */
+export function getPluginSetting(pluginName, chatId, key) {
+    return dbGet(pluginName, chatId, key);
+}
 // ── Scoped accessor factory ───────────────────────────────────────────────────
 /**
  * Returns a settings accessor for a specific (pluginName, chatId) pair.
@@ -105,9 +117,11 @@ function scopedAccessor(pluginName, chatId) {
          * @param {string} key
          * @param {*}      [defaultValue]
          */
-        get(key, defaultValue = undefined) {
+        get(key, defaultValue) {
             const val = dbGet(pluginName, chatId, key);
-            return val !== undefined ? val : defaultValue;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- `get<T>` is a
+            // type-level convenience for callers; the store itself is untyped JSON.
+            return (val !== undefined ? val : defaultValue);
         },
         /**
          * Get all settings for this chat as a plain object.

package/dist/kernel/statusServer.js

@@ -11,11 +11,17 @@ let status = {
     since: new Date().toISOString(),
 };
 export function setStatus(online, lastError) {
-    if (status.online === online)
+    // Same-state updates are a no-op for `online` / `since` so polling the
+    // status page doesn't see the timestamp flicker on every redundant
+    // call (the connection.update listener fires more than once per
+    // reconnect). An explicit `lastError` always wins — if the caller is
+    // reporting a new failure while we're already marked offline, that
+    // message is more useful than the stale one from before.
+    if (status.online === online && !lastError)
         return;
     status = {
         online,
-        since: new Date().toISOString(),
+        since: status.online === online ? status.since : new Date().toISOString(),
         ...(lastError ? { lastError } : {}),
     };
 }
@@ -36,4 +42,5 @@ export function startStatusServer(port) {
     server.listen(port, () => {
         logger.info(`[status] JSON endpoint em http://localhost:${port}`);
     });
+    return server;
 }

package/dist/kernel/statusServer.test.js

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import { afterEach, describe, test } from "node:test";
+import { getStatus, setStatus, startStatusServer } from "#kernel/statusServer.js";
+describe("kernel/statusServer", () => {
+    let activeServer = null;
+    afterEach(async () => {
+        if (activeServer) {
+            await new Promise((resolve) => activeServer.close(() => resolve()));
+            activeServer = null;
+        }
+        // Reset status back to offline
+        setStatus(false);
+    });
+    test("getStatus returns initial state", () => {
+        const status = getStatus();
+        assert.equal(typeof status.online, "boolean");
+        assert.equal(typeof status.since, "string");
+    });
+    test("setStatus updates online state and timestamps", async () => {
+        setStatus(false, "Initial error");
+        const initial = getStatus();
+        assert.equal(initial.online, false);
+        assert.equal(initial.lastError, "Initial error");
+        // Allow timestamp to advance
+        await new Promise((r) => setTimeout(r, 10));
+        setStatus(true);
+        const updated = getStatus();
+        assert.equal(updated.online, true);
+        assert.equal(updated.lastError, undefined);
+        assert.notEqual(updated.since, initial.since);
+        // Setting same status is a no-op for since timestamp
+        const sinceBefore = updated.since;
+        setStatus(true);
+        assert.equal(getStatus().since, sinceBefore);
+    });
+    test("setStatus captures error message when going offline", () => {
+        setStatus(true);
+        setStatus(false, "Stream closed");
+        const status = getStatus();
+        assert.equal(status.online, false);
+        assert.equal(status.lastError, "Stream closed");
+    });
+    test("startStatusServer responds with JSON status and CORS headers", async () => {
+        setStatus(true);
+        activeServer = startStatusServer(0);
+        // Wait until the server is listening
+        await new Promise((resolve) => {
+            if (activeServer.listening)
+                resolve();
+            else
+                activeServer.once("listening", () => resolve());
+        });
+        const addr = activeServer.address();
+        const url = `http://127.0.0.1:${addr.port}/status`;
+        const res = await fetch(url);
+        assert.equal(res.status, 200);
+        assert.equal(res.headers.get("content-type"), "application/json");
+        assert.equal(res.headers.get("access-control-allow-origin"), "*");
+        const body = (await res.json());
+        assert.equal(body.online, true);
+        assert.equal(typeof body.since, "string");
+        assert.equal(body.lastError, undefined);
+        // Mutate status and verify dynamic response on subsequent request
+        setStatus(false, "Socket hung up");
+        const res2 = await fetch(url);
+        const body2 = (await res2.json());
+        assert.equal(body2.online, false);
+        assert.equal(body2.lastError, "Socket hung up");
+    });
+});

package/dist/kernel/testConfig.js

@@ -0,0 +1,192 @@
+/**
+ * kernel/testConfig.ts
+ *
+ * Reads the configuration that gates the WhatsApp integration test suite.
+ *
+ * Two values are exposed:
+ *
+ *   1. `chat` — the JID (or bare phone number) of the chat the integration
+ *      suite is allowed to exercise. Comes from, in precedence order:
+ *        a. environment variable `TEST_CHAT`
+ *        b. `TEST_CHAT` key in `manybot.toml`
+ *        c. otherwise absent (`chat === null`) — integration tests skip
+ *           with an explanatory message instead of crashing.
+ *
+ *      This module accepts any chat shape `normalizeTestChat()` allows,
+ *      including a group (`@g.us`) — it has no opinion on what a given
+ *      test file actually needs. Individual suites are the ones with
+ *      that requirement: contacts.integration.test.ts, for instance,
+ *      needs an individual chat (a phone number, or a JID ending in
+ *      `@s.whatsapp.net`/`@c.us`/`@lid`) because it asserts on
+ *      per-person contact fields (LID, number, country) that a group
+ *      simply doesn't have — see that file's own header for details.
+ *
+ *   2. `runWhatsApp` — explicit opt-in flag (env `MANYBOT_RUN_WHATSAPP_TESTS=1`).
+ *      A saved WhatsApp session plus a `TEST_CHAT` is NOT enough to fire real
+ *      messages; this is the single, deliberate signal that the operator
+ *      actually wants the integration suite to run.
+ *
+ * The module never throws on its own. `getTestConfig()` returns the
+ * resolved state and lets the caller decide what to do (skip vs run vs
+ * fail). `requireTestConfig()` is the hard version for code paths that
+ * must not run without a configured chat + opt-in.
+ *
+ * Deliberately kept out of `CONFIG` — `TEST_CHAT` is a test-time
+ * concern and shouldn't pollute the runtime config object's shape.
+ */
+import fs from "fs/promises";
+import { parse as parseToml } from "smol-toml";
+import { CONFIG_DIR, TOML_CONFIG_FILE } from "#config";
+import { logger } from "#logger";
+// ── Constants ───────────────────────────────────────────────────────────────
+/** Env var that signals "yes, the integration suite should really run". */
+export const RUN_WHATSAPP_TESTS_ENV = "MANYBOT_RUN_WHATSAPP_TESTS";
+/** Env var that overrides any value set in manybot.toml. */
+export const TEST_CHAT_ENV = "TEST_CHAT";
+/** Key read from manybot.toml as a fallback when the env var is unset. */
+export const TEST_CHAT_TOML_KEY = "TEST_CHAT";
+// ── JID normalization ──────────────────────────────────────────────────────
+/**
+ * Acceptable chat-id shapes:
+ *   - bare number:                 "5516999999999"
+ *   - WhatsApp PN JID:             "5516999999999@s.whatsapp.net"
+ *   - legacy framework PN JID:     "5516999999999@c.us"
+ *   - LID JID:                     "1234@lid"
+ *   - group JID:                   "120363…@g.us"
+ *
+ * Any other suffix is rejected so the integration plugin can rely on
+ * `chat.endsWith(...)` checks and not silently mismatch. Bare numbers
+ * are normalized to the WhatsApp PN JID form (the form the bot's own
+ * contract uses to reach that contact).
+ */
+export function normalizeTestChat(raw) {
+    if (typeof raw !== "string") {
+        throw new TypeError(`TEST_CHAT must be a string, got ${typeof raw}`);
+    }
+    const trimmed = raw.trim();
+    if (trimmed === "") {
+        throw new Error("TEST_CHAT is empty");
+    }
+    const ALLOWED_SUFFIXES = ["@s.whatsapp.net", "@c.us", "@lid", "@g.us"];
+    for (const suffix of ALLOWED_SUFFIXES) {
+        if (trimmed.endsWith(suffix)) {
+            const local = trimmed.slice(0, -suffix.length);
+            if (local === "" || /[^\dA-Za-z._-]/.test(local)) {
+                throw new Error(`TEST_CHAT has invalid local part: "${raw}"`);
+            }
+            return trimmed;
+        }
+    }
+    // Bare number — accept digits, plus, and the leading "+".
+    if (/^\+?\d+$/.test(trimmed)) {
+        return `${trimmed.replace(/^\+/, "")}@s.whatsapp.net`;
+    }
+    throw new Error(`TEST_CHAT must be a bare phone number or a JID with one of: ` +
+        `${ALLOWED_SUFFIXES.join(", ")} — got "${raw}"`);
+}
+// ── Resolution ──────────────────────────────────────────────────────────────
+async function readTomlTestChat() {
+    let raw;
+    try {
+        raw = await fs.readFile(TOML_CONFIG_FILE, "utf-8");
+    }
+    catch (e) {
+        if (e.code !== "ENOENT") {
+            logger.warn(`[testConfig] could not read ${TOML_CONFIG_FILE}: ${e.message}`);
+        }
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = parseToml(raw);
+    }
+    catch (e) {
+        logger.warn(`[testConfig] invalid TOML in ${TOML_CONFIG_FILE}: ${e.message}`);
+        return null;
+    }
+    const value = parsed[TEST_CHAT_TOML_KEY];
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string") {
+        logger.warn(`[testConfig] ${TEST_CHAT_TOML_KEY} in TOML is not a string, ignoring`);
+        return null;
+    }
+    return value.trim() === "" ? null : value;
+}
+let cached = null;
+/**
+ * Resolve the test configuration. Result is cached after the first call
+ * because the env and `manybot.toml` don't change mid-process; the
+ * cache gives every test a stable view without re-reading disk.
+ */
+export async function getTestConfig() {
+    if (cached)
+        return cached;
+    const envValue = process.env[TEST_CHAT_ENV];
+    let raw = null;
+    let source = null;
+    if (typeof envValue === "string" && envValue.trim() !== "") {
+        raw = envValue;
+        source = "env";
+    }
+    else {
+        const tomlValue = await readTomlTestChat();
+        if (tomlValue) {
+            raw = tomlValue;
+            source = "toml";
+        }
+    }
+    let chat = null;
+    if (raw !== null) {
+        try {
+            chat = normalizeTestChat(raw);
+        }
+        catch (e) {
+            logger.warn(`[testConfig] ${e.message}`);
+        }
+    }
+    const runWhatsApp = process.env[RUN_WHATSAPP_TESTS_ENV] === "1";
+    let skipReason = null;
+    if (chat === null) {
+        skipReason =
+            `TEST_CHAT is not set (env ${TEST_CHAT_ENV} or key ` +
+                `${TEST_CHAT_TOML_KEY} in ${TOML_CONFIG_FILE})`;
+    }
+    else if (!runWhatsApp) {
+        skipReason =
+            `${RUN_WHATSAPP_TESTS_ENV}=1 is required to run the WhatsApp ` +
+                `integration suite (TEST_CHAT alone is not enough)`;
+    }
+    cached = { chat, source, runWhatsApp, skipReason };
+    return cached;
+}
+/**
+ * Hard version of {@link getTestConfig}: throws if the chat is not
+ * configured or the opt-in flag is missing. Use this in code paths that
+ * should never run unless the operator has consciously opted in.
+ */
+export async function requireTestConfig() {
+    const cfg = await getTestConfig();
+    if (cfg.chat === null) {
+        throw new Error(`[testConfig] cannot run: ${cfg.skipReason}. ` +
+            `Set ${TEST_CHAT_ENV} or add '${TEST_CHAT_TOML_KEY} = "…"' to ${TOML_CONFIG_FILE}.`);
+    }
+    if (!cfg.runWhatsApp) {
+        throw new Error(`[testConfig] cannot run without opt-in: ${cfg.skipReason}. ` +
+            `Re-run with ${RUN_WHATSAPP_TESTS_ENV}=1.`);
+    }
+    return cfg;
+}
+/**
+ * Test-only — drops the cached value so the next `getTestConfig()`
+ * call re-reads env and disk. Use this after mutating env vars in a
+ * test; production code must not call it.
+ */
+export function _resetTestConfigForTests() {
+    cached = null;
+}
+// Keep `CONFIG_DIR` referenced so this module participates in the
+// project's path-resolution behavior the same way other kernel modules
+// do, and so future test fixtures that need to point at a different
+// config dir (e.g. MANYBOT_CONFIG_DIR) keep working.
+void CONFIG_DIR;