levix-bot 2.0.1 → 2.1.1

package/src/core/socket.js

@@ -45,20 +45,54 @@ function withThumbnailSupport(sock) {
   return sock;
 }
 
-// Create and configure WhatsApp socket
-export async function createWhatsAppSocket() {
-  logger.info('[Socket] Initializing WhatsApp socket with database auth');
+/**
+ * Create and configure a WhatsApp socket.
+ *
+ * @param {object} [options]
+ * @param {object|null} [options.proxy] - what createProxyAgents() returned, or
+ *   null for a direct connection. Built by the session manager and passed in
+ *   rather than read here, so this factory stays a pure function of its
+ *   arguments and a test can hand it a fake.
+ */
+export async function createWhatsAppSocket({ proxy = null } = {}) {
+  logger.info(
+    proxy
+      ? `[Socket] Initializing WhatsApp socket through ${proxy.label}`
+      : '[Socket] Initializing WhatsApp socket with database auth'
+  );
 
   const { state, saveCreds, clearAll } = await useDatabaseAuthState();
 
+  // Whether this install is already paired. NOT `store.hasCredentials()`: the
+  // auth state writes a `creds` row on its very first call, paired or not, so
+  // that row proves nothing. `creds.me.id` is only filled in by a successful
+  // pairing, which is exactly the question the session manager is asking —
+  // it decides whether a close is a failed pairing attempt or a dropped
+  // connection worth retrying.
+  const isPaired = !!state?.creds?.me?.id;
+
   const cachedGroupMetadata = (jid) => groupMetadataCache.get(jid);
 
+  const config = getBaileysConfig(cachedGroupMetadata);
+
+  // Three separate hooks, because Baileys has three separate network paths:
+  //   agent              -> the `ws` WebSocket        (https.request, classic agent)
+  //   fetchAgent         -> media UPLOAD on Node      (https.request, classic agent)
+  //   options.dispatcher -> media DOWNLOAD            (global fetch, undici Dispatcher)
+  // Setting only the first would leave every photo the bot sends or receives
+  // going out from the real IP. See src/core/proxy.js.
+  if (proxy) {
+    config.agent = proxy.agent;
+    config.fetchAgent = proxy.fetchAgent;
+    config.options = { ...(config.options || {}), dispatcher: proxy.dispatcher };
+  }
+
   const sock = withThumbnailSupport(
     makeWASocket({
       auth: state,
-      ...getBaileysConfig(cachedGroupMetadata),
+      ...config,
     })
   );
 
-  return { sock, saveCreds, clearAll };
+  return { sock, saveCreds, clearAll, isPaired };
 }

package/src/index.js

@@ -3,10 +3,15 @@
 // Two shapes, one core:
 //
 //   levix            bootstrapCore() + bootstrapPanel(), then maybe a browser
-//   levix headless   bootstrapCore() only — nothing binds a port
+//   levix headless   bootstrapCore({ autoStart: true }) — nothing binds a port
 //
 // The difference is which bootstrap runs, not a flag threaded through the
 // codebase. See src/bootstrap/.
+//
+// WhatsApp is not dialled by starting the process. In panel mode the session
+// sits idle until somebody presses Start on the Connection screen, so a fresh
+// install can be configured before it ever tries to pair. Headless has no
+// screen and nobody to press anything, so it asks the core to connect for it.
 
 import os from "node:os";
 import { createRequire } from "module";
@@ -15,9 +20,9 @@ import { flushStore } from "./db/store.esm.js";
 import brand from "./config/brand.esm.js";
 
 const require = createRequire(import.meta.url);
+const qrcodeTerminal = require("qrcode-terminal");
 const logger = require("./utils/logger.cjs");
 const secrets = require("./config/secrets.cjs");
-const settings = require("./config/settings.cjs");
 const { DATA_DIR } = require("./config/paths.cjs");
 const { release: releaseLock } = require("./config/lock.cjs");
 const { close: closeDatabase } = require("./db/db.cjs");
@@ -32,6 +37,10 @@ function short(path) {
   return home && path.startsWith(home) ? path.replace(home, "~") : path;
 }
 
+// The session manager, so the shutdown handler can cancel its timers. Set as
+// soon as the core is up.
+let liveSession = null;
+
 /**
  * Start Levix.
  *
@@ -48,17 +57,66 @@ export async function start({ headless = false, open = true } = {}) {
   return headless ? startHeadless() : startWithPanel({ open });
 }
 
+/**
+ * Print the QR in the terminal.
+ *
+ * A QR belongs there in both modes: the panel shows one too, but somebody on an
+ * SSH session has no browser to show it in. This used to live inside the
+ * connection handler, which meant src/core had to know a human might be
+ * watching. Attached after whatever else the mode wants to say about a QR, so
+ * the explanation comes before the block of glyphs rather than after it.
+ */
+function attachTerminalQr() {
+  attach((event, payload) => {
+    if (event === "qr" && typeof payload === "string") {
+      qrcodeTerminal.generate(payload, { small: true });
+    }
+  });
+}
+
 // ---------------------------------------------------------------------------
 // headless
 // ---------------------------------------------------------------------------
 
+/**
+ * What headless does when the session reaches a state that needs a person.
+ *
+ * The panel answers this with a Start button. Headless has no button, no stdin
+ * and no UI, so a bot sitting in `disconnected` or `retry_exhausted` there is
+ * not "still running" in any useful sense — it is a silent process that will
+ * never answer another message. Handing the decision to the supervisor is the
+ * honest ending: systemd, pm2 and Docker all bring it back, and a genuinely
+ * persistent refusal trips their own restart limits and surfaces as a failed
+ * unit rather than as a bot that quietly stopped working.
+ *
+ * Panel mode never calls this. There, Levix stays up by design.
+ */
+const HEADLESS_GRACE_MS = 5000;
+
+function surrender(state) {
+  line();
+  line("  No panel here to start it again — stopping so the supervisor can.");
+  line("  (systemd / pm2 / docker restart it; without one, run levix again.)");
+  line();
+  logger.error(`[headless] session ended in ${state} — exiting for the supervisor`);
+  // Not unref'd: in a terminal state nothing else is holding the loop open, so
+  // an unref'd timer would let the process fall out with code 0 before this
+  // ever ran — the same restart, but with no signal that anything went wrong.
+  setTimeout(() => process.exit(1), HEADLESS_GRACE_MS);
+}
+
 async function startHeadless() {
   line();
   line(`  ${brand.name} — headless`);
 
   // Attached before the bot starts, because the QR can arrive during the very
   // first connection attempt.
+  //
+  // Headless has no Connection screen, so the terminal has to say what the
+  // panel would have shown — including the states that need a person, where
+  // "restart it" is the only instruction that exists here.
   let announcedPairing = false;
+  let lastState = null;
   attach((event, payload) => {
     if (event === "qr" && !announcedPairing) {
       announcedPairing = true;
@@ -69,16 +127,36 @@ async function startHeadless() {
       line("  WhatsApp -> Linked devices -> Link a device");
       line();
     }
-    if (event === "status_update" && payload?.status === "Connected") {
-      line();
-      line("  ✓ WhatsApp connected");
-    }
-    if (event === "status_update" && payload?.status === "Disconnected") {
-      line("  … WhatsApp disconnected, reconnecting");
+
+    if (event !== "session" || payload?.state === lastState) return;
+    lastState = payload.state;
+
+    switch (payload.state) {
+      case "connected":
+        line();
+        line("  ✓ WhatsApp connected");
+        break;
+      case "reconnecting":
+        line(`  … WhatsApp disconnected, reconnecting (attempt ${payload.attempt}/${payload.maxAttempts})`);
+        break;
+      case "logged_out":
+      case "retry_exhausted":
+      case "disconnected":
+      case "error":
+        line();
+        line(`  ✗ WhatsApp is not connected${payload.detail ? ` — ${payload.detail}` : ""}`);
+        surrender(payload.state);
+        break;
+      default:
+        break;
     }
   });
 
-  const core = await bootstrapCore();
+  attachTerminalQr();
+
+  // Headless has no Start button, so it starts itself.
+  const core = await bootstrapCore({ autoStart: true });
+  liveSession = core.session;
 
   if (announcedPairing) line("  Waiting for connection...");
 
@@ -101,18 +179,12 @@ async function startHeadless() {
 async function startWithPanel({ open }) {
   const { bootstrapPanel, panelUrl } = await import("./bootstrap/panel.js");
 
-  let setBotInstance = null;
-  let setBotControls = null;
-
-  // The panel needs the live socket, and a reconnect replaces it. Passing the
-  // callback into the core keeps that true without the core knowing what a
-  // panel is.
-  const core = await bootstrapCore({
-    onSocket(sock, controls) {
-      if (setBotInstance) setBotInstance(sock);
-      if (setBotControls) setBotControls({ clearAll: controls.clearAll });
-    },
-  });
+  attachTerminalQr();
+
+  // Nothing dials WhatsApp here. The panel comes up against an idle session and
+  // the Connection screen offers a Start button.
+  const core = await bootstrapCore({ autoStart: false });
+  liveSession = core.session;
 
   let panel;
   try {
@@ -126,9 +198,6 @@ async function startWithPanel({ open }) {
     throw error;
   }
 
-  ({ setBotInstance, setBotControls } = panel);
-  setBotInstance(core.sock);
-
   const firstRun = !secrets.hasDashboardPassword();
   const url = panelUrl({ port: panel.port, firstRun });
 
@@ -140,10 +209,15 @@ async function startWithPanel({ open }) {
   line(`  Panel: ${url}`);
   line(`  Data:  ${short(DATA_DIR)}`);
 
-  if (firstRun && !settings.get("public_domain")) {
+  // Only while the panel is unclaimed, and only once per process. Printed on
+  // every deployment shape, including one behind a domain: a proxied request
+  // can never count as local, so that is precisely the case that needs it.
+  if (firstRun) {
     line();
     line("  First run — that link asks you to pick a password.");
-    line(`  Opening it from another machine also needs this code: ${secrets.getSetupCode()}`);
+    line("  Opening it from another machine also needs this code:");
+    line();
+    line(`  ${secrets.formatSetupCodeLine()}`);
   }
 
   if (open) {
@@ -156,6 +230,9 @@ async function startWithPanel({ open }) {
     );
   }
 
+  line();
+  line("  Not linked to WhatsApp yet? Open the panel, go to Connection and");
+  line("  press Start session.");
   line();
   line("  Press Ctrl+C to stop.");
   line();
@@ -188,10 +265,30 @@ function installShutdownHandlers() {
     shuttingDown = true;
     logger.info(`[shutdown] ${signal} received, closing down...`);
 
+    // Armed first, not last: everything below is awaited, and a socket close or
+    // a request that refuses to end would otherwise mean the watchdog is never
+    // reached at all. Not unref'd, for the same reason — this timer exists
+    // precisely for the case where nothing else is going to wake the loop.
+    const watchdog = setTimeout(() => {
+      logger.error("[shutdown] took too long — exiting anyway");
+      process.exit(1);
+    }, 10_000);
+
+    // Before anything else: no reconnect may fire while we are going down, and
+    // a pending retry timer must not outlive the process it was scheduled in.
+    if (liveSession) {
+      try {
+        await liveSession.shutdown();
+      } catch (error) {
+        logger.warn({ err: error }, "[shutdown] closing the WhatsApp session failed");
+      }
+    }
+
     const finish = async () => {
       await Promise.allSettled([flushStore()]);
       closeDatabase();
       releaseLock();
+      clearTimeout(watchdog);
       process.exit(0);
     };
 
@@ -199,16 +296,26 @@ function installShutdownHandlers() {
     // listening yet. Reaching into the module cache rather than requiring it
     // keeps this from constructing an Express app during shutdown.
     let server = null;
+    let io = null;
     try {
       const cached = require.cache[require.resolve("../app.cjs")];
       server = cached?.exports?.server ?? null;
+      io = cached?.exports?.io ?? null;
     } catch {}
 
+    // server.close() waits for every open connection, and a dashboard sitting
+    // on a socket.io websocket is an open connection that never ends by itself
+    // — so without this the shutdown ran to the 10s hard exit every time a tab
+    // was open, which is exactly what the panel's own Restart button does.
+    try {
+      io?.disconnectSockets(true);
+      server?.closeIdleConnections?.();
+    } catch (error) {
+      logger.debug({ err: error?.message }, "[shutdown] closing panel connections failed");
+    }
+
     if (server?.listening) server.close(finish);
     else await finish();
-
-    // Don't wait forever on a request that refuses to end.
-    setTimeout(() => process.exit(1), 10_000).unref();
   };
 
   ["SIGTERM", "SIGINT"].forEach((signal) => process.on(signal, () => shutdown(signal)));

package/src/routes/dashboard.api.esm.js

@@ -7,9 +7,10 @@
 // Two rules the handlers follow:
 //   * error text stays in the log. The internal message names collections and
 //     server paths, and this response is rendered in a browser.
-//   * nothing here can change the bot's identity. The name and the credit come
-//     from src/config/brand.cjs, are injected into the AI prompt, and are not
-//     exposed as an editable field anywhere below.
+//   * nothing here can change the bot's identity. What the UI renders comes
+//     from src/config/brand.cjs; what the model is told comes from
+//     src/config/ai-identity.cjs, which this file does not import and no route
+//     below returns. Neither is an editable field anywhere in the panel.
 
 import { Router } from "express";
 import { createRequire } from "module";
@@ -52,17 +53,44 @@ const { deleteScheduledJob } = require("../../scheduler.cjs");
 
 const router = Router();
 
-// The live socket, and the auth-clearing callback that comes with it.
-let botInstance = null;
-let botControls = { clearAll: null };
+// The backend's WhatsApp session manager (src/core/session.js). The routes ask
+// it questions and give it orders; they never create or destroy a socket
+// themselves, and nothing a browser does to its websocket reaches it.
+let session = null;
 
-export function setBotInstance(sock) {
-  botInstance = sock;
+export function setSession(manager) {
+  session = manager;
 }
 
-/** Handed the pieces of the current socket that /bot/* needs. */
-export function setBotControls(controls = {}) {
-  botControls = { ...botControls, ...controls };
+/** The live socket, or null. Re-read every time — a reconnect replaces it. */
+function currentSocket() {
+  return session?.socket ?? null;
+}
+
+/** A safe snapshot even before the session manager has been handed over. */
+function sessionState() {
+  return (
+    session?.getState() ?? {
+      state: "idle",
+      status: "Disconnected",
+      connected: false,
+      canStart: false,
+      canStop: false,
+      canUnlink: false,
+      proxy: null,
+      proxyChanged: false,
+      terminal: false,
+      hasQr: false,
+      attempt: 0,
+      maxAttempts: 0,
+      nextRetryAt: null,
+      reason: "no_session",
+      detail: null,
+      user: null,
+      lastDisconnect: null,
+      since: null,
+    }
+  );
 }
 
 // --- helpers --------------------------------------------------------------
@@ -91,9 +119,12 @@ function asyncRoute(handler) {
 
 router.get("/stats", (req, res) => {
   try {
+    const connection = sessionState();
+    const sock = currentSocket();
     res.json({
       success: true,
       stats: {
+        connection,
         totalGroups: countGroups(),
         totalWarnings: countWarnings(),
         totalTodos: countTodos(),
@@ -102,9 +133,9 @@ router.get("/stats", (req, res) => {
         totalSettledDebts: countDebts(true),
         totalSchedules: countSchedules(),
 
-        isConnected: !!botInstance?.user,
-        botNumber: botInstance?.user?.id || null,
-        botName: botInstance?.user?.name || null,
+        isConnected: connection.connected && !!sock?.user,
+        botNumber: sock?.user?.id || null,
+        botName: sock?.user?.name || null,
 
         prefix: runtimeConfig.getPrefix(),
         commandCount: getCommandCatalog().length,
@@ -123,12 +154,16 @@ router.get("/stats", (req, res) => {
 });
 
 router.get("/health", (req, res) => {
+  const connection = sessionState();
   res.json({
     success: true,
     health: {
+      // Levix is healthy whether or not WhatsApp is linked: the panel is the
+      // only surface, and it answers long before a pairing exists.
       status: "healthy",
       database: true,
-      bot: botInstance?.user ? "connected" : "disconnected",
+      bot: connection.connected ? "connected" : "disconnected",
+      session: connection.state,
       uptime: process.uptime(),
       timestamp: Date.now(),
     },
@@ -742,38 +777,100 @@ router.post("/security/password", (req, res) => {
 // Bot control
 // ===========================================================================
 
-// Unlink the WhatsApp account. The connection handler sees the logout, clears
-// the stored credentials and comes back with a fresh QR — no restart needed.
+// The WhatsApp session. These four routes are the only way a browser can
+// influence it, and each is a request to the backend's state machine rather
+// than an instruction to make or break a socket. Everything under
+// /dashboard/api is already behind the panel session and the cross-origin
+// check in app.cjs, so no new surface is exposed here.
+
+// The whole Connection screen in one request, including the QR already on
+// screen. Without the code here a dashboard opened (or reloaded) while a
+// pairing was already waiting showed an empty frame until Baileys happened to
+// issue the next one.
+router.get("/bot/session", (req, res) => {
+  res.json({ success: true, session: sessionState(), qr: session?.qr ?? null });
+});
+
+// Idempotent by construction: the manager returns the state it is already in
+// when a socket exists or is being made, so a double-click, two operators and a
+// retry firing at the same moment all end up with exactly one socket.
 router.post(
-  "/bot/logout",
+  "/bot/session/start",
   asyncRoute(async (req, res) => {
-    if (!botInstance) {
-      return res.status(409).json({ success: false, error: "Bot is not connected" });
+    if (!session) {
+      return res.status(503).json({ success: false, error: "Session manager is not ready" });
     }
+    const state = await session.start({ reason: "dashboard" });
+    logger.info(`[Dashboard] Start session requested — now ${state.state}`);
+    res.json({ success: true, session: state });
+  })
+);
 
-    try {
-      await botInstance.logout();
-    } catch (error) {
-      // A logout that fails still has to clear the local credentials, or the
-      // bot reconnects with a session WhatsApp already dropped.
-      logger.warn({ err: error }, "[Dashboard] logout call failed, clearing anyway");
-      if (botControls.clearAll) await botControls.clearAll();
+// Apply configuration that only a new socket can pick up — the proxy, today.
+// It goes through the session's own stop()+start(), so this route creates
+// nothing and the state machine stays the only thing that owns a socket.
+router.post(
+  "/bot/session/reconnect",
+  asyncRoute(async (req, res) => {
+    if (!session) {
+      return res.status(503).json({ success: false, error: "Session manager is not ready" });
     }
+    const state = await session.reconnect({ reason: "dashboard" });
+    logger.info(`[Dashboard] Reconnect requested — now ${state.state}`);
+    res.json({ success: true, session: state });
+  })
+);
 
+// Stop talking to WhatsApp but keep the pairing. No retry follows a manual
+// stop, and any pending one is cancelled.
+router.post(
+  "/bot/session/stop",
+  asyncRoute(async (req, res) => {
+    if (!session) {
+      return res.status(503).json({ success: false, error: "Session manager is not ready" });
+    }
+    const state = await session.stop({ reason: "dashboard" });
+    logger.warn("[Dashboard] WhatsApp session stopped from the dashboard");
+    res.json({ success: true, session: state });
+  })
+);
+
+// Unlink the WhatsApp account: WhatsApp drops the companion device and the
+// stored credentials go with it. Levix stays up, and the operator can start a
+// fresh pairing whenever they want one.
+router.post(
+  "/bot/logout",
+  asyncRoute(async (req, res) => {
+    if (!session) {
+      return res.status(503).json({ success: false, error: "Session manager is not ready" });
+    }
+    // Deliberately NOT gated on a live socket. A pairing WhatsApp has refused
+    // (403, 405) leaves dead credentials with no connection to unlink through,
+    // and that is precisely when the operator needs this.
+    if (!sessionState().canUnlink) {
+      return res.status(409).json({ success: false, error: "There is nothing linked to unlink" });
+    }
+
+    const state = await session.logout();
     logger.warn("[Dashboard] WhatsApp account unlinked from the dashboard");
-    res.json({ success: true });
+    res.json({ success: true, session: state });
   })
 );
 
 // Only useful under a supervisor (pm2 / systemd / docker restart:always) —
-// this exits the process and something else has to bring it back.
+// this stops the process and something else has to bring it back.
+//
+// SIGTERM to ourselves rather than process.exit(): that is the path in
+// src/index.js that cancels the reconnect timers, closes the WhatsApp socket,
+// flushes the store and closes the database. Exiting straight from here skipped
+// all four.
 router.post("/bot/restart", (req, res) => {
   logger.warn("[Dashboard] restart requested");
   res.json({
     success: true,
     message: "Restarting. If the bot is not running under a supervisor, start it again yourself.",
   });
-  setTimeout(() => process.exit(0), 500);
+  setTimeout(() => process.kill(process.pid, "SIGTERM"), 500).unref();
 });
 
 export default router;