levix-bot 2.0.0 → 2.1.0

package/public/dashboard.js

@@ -174,11 +174,46 @@
   }
 
   // --- connection status --------------------------------------------------
+  //
+  // The backend owns the session (src/core/session.js); this file only draws
+  // what it reports. Nothing here starts, stops or retries a connection on its
+  // own, and closing this tab does not touch the bot.
+
+  // What each backend state looks like: the pill class, the label, and the
+  // sentence under the Connection card's heading.
+  const SESSION_LABELS = {
+    idle: { tone: "off", label: "Not started", tag: "danger", tagText: "Not started" },
+    starting: { tone: "warn", label: "Connecting", tag: "warn", tagText: "Connecting" },
+    waiting_for_qr: { tone: "warn", label: "Waiting for scan", tag: "warn", tagText: "Waiting for scan" },
+    linking: { tone: "warn", label: "Linking", tag: "warn", tagText: "Linking" },
+    connected: { tone: "on", label: "Connected", tag: "ok", tagText: "Linked" },
+    reconnecting: { tone: "warn", label: "Reconnecting", tag: "warn", tagText: "Reconnecting" },
+    disconnected: { tone: "off", label: "Disconnected", tag: "danger", tagText: "Disconnected" },
+    retry_exhausted: { tone: "off", label: "Disconnected", tag: "danger", tagText: "Gave up reconnecting" },
+    logged_out: { tone: "off", label: "Not linked", tag: "danger", tagText: "Not linked" },
+    error: { tone: "off", label: "Error", tag: "danger", tagText: "Error" },
+  };
+
+  const describeSession = (state) =>
+    SESSION_LABELS[state] || { tone: "off", label: "Disconnected", tag: "danger", tagText: "Disconnected" };
 
-  function setStatus(connected, label) {
+  // The last snapshot the backend sent. Every renderer reads this rather than
+  // its own idea of what is going on, so the pill and the Connection card can
+  // never disagree.
+  let sessionSnapshot = null;
+
+  function setStatus(snapshot) {
+    if (!snapshot) return;
+    sessionSnapshot = snapshot;
+    const look = describeSession(snapshot.state);
     const pill = $("#status-pill");
-    pill.className = `pill ${connected ? "on" : "off"}`;
-    pill.innerHTML = `<span class="dot"></span>${esc(label)}`;
+    pill.className = `pill ${look.tone}`;
+    pill.innerHTML = `<span class="dot"></span>${esc(look.label)}`;
+    // Outside the `currentView` check: leaving the Connection screen while a
+    // reconnect was pending used to leave the ticker running for the life of
+    // the page, because only renderConnection() could ever stop it.
+    syncRetryTicker(snapshot);
+    if (currentView === "connection") renderConnection();
   }
 
   // --- overview -----------------------------------------------------------
@@ -186,7 +221,10 @@
   async function loadStats() {
     const { stats } = await api("/stats");
 
-    setStatus(stats.isConnected, stats.isConnected ? "Connected" : "Disconnected");
+    // /stats carries the same session snapshot the socket pushes, so the poll
+    // that runs every 15s refreshes the pill instead of flattening whatever the
+    // last live event put there.
+    setStatus(stats.connection);
 
     const cards = [
       ["Groups", stats.totalGroups],
@@ -253,55 +291,174 @@
     $("#qr-note").textContent = "Scan it from WhatsApp → Linked devices.";
   }
 
+  function clearQr() {
+    qrRendered = null;
+    $("#qr-frame").innerHTML = "";
+    $("#qr-note").textContent = "Waiting for a QR code…";
+  }
+
+  function retryHint(snapshot) {
+    if (snapshot.state !== "reconnecting" || !snapshot.nextRetryAt) return "";
+    const seconds = Math.max(0, Math.round((snapshot.nextRetryAt - Date.now()) / 1000));
+    return ` Next attempt in ${seconds}s.`;
+  }
+
+  // A countdown that only ticks while there is one to show. Rendering it once
+  // and leaving it would put a number on screen that stops being true a second
+  // later.
+  let retryTicker = null;
+
+  function syncRetryTicker(snapshot) {
+    const counting = snapshot.state === "reconnecting" && snapshot.nextRetryAt;
+    if (counting && !retryTicker) {
+      retryTicker = setInterval(() => {
+        if (currentView === "connection") renderConnection();
+      }, 1000);
+    } else if (!counting && retryTicker) {
+      clearInterval(retryTicker);
+      retryTicker = null;
+    }
+  }
+
+  /** Draw the Connection card from the last snapshot. No network call. */
+  function renderConnection() {
+    const snapshot = sessionSnapshot;
+    if (!snapshot) return;
+
+    const look = describeSession(snapshot.state);
+    const who = snapshot.user?.id ? shortJid(snapshot.user.id) : "";
+
+    $("#conn-state").innerHTML =
+      `<span class="tag ${esc(look.tag)}">${esc(look.tagText)}</span>` +
+      (who ? ` <span class="hint">${esc(who)}</span>` : "");
+
+    $("#conn-detail").textContent = (snapshot.detail || "") + retryHint(snapshot);
+
+    // The proxy line, and the one action that can apply a changed one. The
+    // label is already redacted server-side — there is no password to leak
+    // here because the browser was never told it.
+    const proxyLine = $("#conn-proxy");
+    if (snapshot.proxy) {
+      proxyLine.textContent = `Connecting through ${snapshot.proxy}.`;
+    } else if (snapshot.connected || snapshot.state === "waiting_for_qr") {
+      proxyLine.textContent = "Connecting directly, with no proxy.";
+    } else {
+      proxyLine.textContent = "";
+    }
+    if (snapshot.proxyChanged) {
+      proxyLine.textContent +=
+        " The saved proxy settings differ from the connection in use — reconnect to apply them.";
+    }
+
+    // Only offered when it would do something: there has to be a live session
+    // to replace, and a reason to replace it.
+    const canReconnect = snapshot.canStop && snapshot.proxyChanged;
+    $("#reconnect-btn").style.display = canReconnect ? "" : "none";
+    $("#reconnect-btn").disabled = !canReconnect;
+
+    // Buttons follow the backend, so a state that cannot accept an action
+    // cannot be asked for one.
+    $("#start-btn").disabled = !snapshot.canStart;
+    $("#start-btn").textContent =
+      snapshot.state === "logged_out" || snapshot.state === "idle"
+        ? "Start session"
+        : "Retry connection";
+    $("#stop-btn").disabled = !snapshot.canStop;
+    // Not "only while connected": a refused pairing leaves dead credentials
+    // that can only be cleared by unlinking.
+    $("#unlink-btn").disabled = !snapshot.canUnlink;
+
+    // The QR frame is only up while a code can actually be scanned.
+    const pairing = snapshot.state === "waiting_for_qr";
+    $("#qr-panel").style.display = pairing ? "block" : "none";
+    if (!pairing) clearQr();
+  }
+
   VIEWS.connection = {
     title: "Connection",
+    // One request for the whole screen, including a QR that was already on
+    // offer before this tab existed — a reload has to show the real backend
+    // state, not an empty frame.
     load: guard(async () => {
-      const { stats } = await api("/stats");
-      const connected = stats.isConnected;
-
-      $("#conn-state").innerHTML = connected
-        ? `<span class="tag ok">Linked</span> <span class="hint">${esc(shortJid(stats.botNumber))}</span>`
-        : `<span class="tag danger">Not linked</span>`;
-
-      $("#qr-panel").style.display = connected ? "none" : "block";
-      if (connected) {
-        qrRendered = null;
-        $("#qr-frame").innerHTML = "";
-        $("#qr-note").textContent = "";
-      }
+      const { session, qr } = await api("/bot/session");
+      setStatus(session);
+      renderConnection();
+      if (qr && session.state === "waiting_for_qr") renderQr(qr);
     }),
   };
 
+  function confirmed(question, fn) {
+    return guard(async () => {
+      if (!confirm(question)) return;
+      await fn();
+    });
+  }
+
   function initConnectionActions() {
-    $("#unlink-btn").addEventListener(
+    // Starting is idempotent on the server: a second click while a socket is
+    // being made is answered with the state it is already in.
+    $("#start-btn").addEventListener(
       "click",
       guard(async () => {
-        if (
-          !confirm(
-            "Unlink this WhatsApp account? The bot stops answering until you scan a new QR code."
-          )
-        ) {
-          return;
+        // Disabled straight away so an impatient second click cannot even be
+        // made, and put back from the backend's answer either way — a failed
+        // request must not leave a dead button behind.
+        $("#start-btn").disabled = true;
+        try {
+          const { session } = await api("/bot/session/start", { method: "POST" });
+          setStatus(session);
+          toast("Session starting…", "ok");
+        } finally {
+          renderConnection();
         }
-        await api("/bot/logout", { method: "POST" });
-        toast("Unlinked. A new QR code will appear here shortly.", "ok");
-        setStatus(false, "Disconnected");
       })
     );
 
+    $("#reconnect-btn").addEventListener(
+      "click",
+      confirmed(
+        "Reconnect WhatsApp now to apply the saved settings? The bot stops answering for a few seconds.",
+        async () => {
+          const { session } = await api("/bot/session/reconnect", { method: "POST" });
+          setStatus(session);
+          toast("Reconnecting with the new settings…", "ok");
+        }
+      )
+    );
+
+    $("#stop-btn").addEventListener(
+      "click",
+      confirmed(
+        "Stop the WhatsApp session? The bot stops answering until you start it again. The pairing is kept.",
+        async () => {
+          const { session } = await api("/bot/session/stop", { method: "POST" });
+          setStatus(session);
+          toast("Session stopped.", "ok");
+        }
+      )
+    );
+
+    $("#unlink-btn").addEventListener(
+      "click",
+      confirmed(
+        "Unlink this WhatsApp account? The bot stops answering until you start a new session and scan a QR code.",
+        async () => {
+          const { session } = await api("/bot/logout", { method: "POST" });
+          setStatus(session);
+          toast("Unlinked. Press Start session to pair again.", "ok");
+        }
+      )
+    );
+
     $("#restart-btn").addEventListener(
       "click",
-      guard(async () => {
-        if (
-          !confirm(
-            "Restart the bot? It only comes back on its own if it runs under a supervisor (pm2, systemd, Docker)."
-          )
-        ) {
-          return;
+      confirmed(
+        "Restart the bot? It only comes back on its own if it runs under a supervisor (pm2, systemd, Docker).",
+        async () => {
+          const data = await api("/bot/restart", { method: "POST" });
+          toast(data.message || "Restarting…", "ok");
         }
-        const data = await api("/bot/restart", { method: "POST" });
-        toast(data.message || "Restarting…", "ok");
-      })
+      )
     );
   }
 
@@ -925,7 +1082,8 @@
     if (setting.type === "secret") {
       control = `
         <div class="inline">
-          <input type="password" id="${id}" placeholder="${setting.configured ? "•••••••• (set)" : "not set"}" autocomplete="new-password" />
+          <input type="password" id="${id}" placeholder="${setting.configured ? "•••••••• (set)" : "not set"}"
+                 autocomplete="new-password"${setting.configured ? ' data-configured="1"' : ""} />
           <button class="btn btn-sm" data-save-setting="${esc(setting.key)}">Save</button>
           ${setting.configured ? `<button class="btn btn-sm btn-danger" data-clear-setting="${esc(setting.key)}">Clear</button>` : ""}
         </div>`;
@@ -938,6 +1096,19 @@
           </label>
           <button class="btn btn-sm" data-save-setting="${esc(setting.key)}">Save</button>
         </div>`;
+    } else if (Array.isArray(setting.choices) && setting.choices.length) {
+      control = `
+        <div class="inline">
+          <select id="${id}">
+            ${setting.choices
+              .map(
+                (choice) =>
+                  `<option value="${esc(choice)}"${choice === setting.value ? " selected" : ""}>${esc(choice)}</option>`
+              )
+              .join("")}
+          </select>
+          <button class="btn btn-sm" data-save-setting="${esc(setting.key)}">Save</button>
+        </div>`;
     } else {
       control = `
         <div class="inline">
@@ -1005,6 +1176,16 @@
 
       const key = save ? save.dataset.saveSetting : clear.dataset.clearSetting;
       const input = document.getElementById(`set-${key}`);
+
+      // An already-set secret with an empty box means "leave it alone", not
+      // "erase it". The box is always empty — the server never sends the value
+      // back — so saving the field as-is would wipe a working password every
+      // time somebody edited the host next to it. Clear is the explicit way.
+      if (save && input.dataset.configured === "1" && input.value === "") {
+        toast("Left unchanged. Use Clear to remove it.");
+        return;
+      }
+
       const value = clear
         ? ""
         : input.type === "checkbox"
@@ -1015,28 +1196,37 @@
         await api("/settings", { method: "PATCH", body: { key, value } });
         toast(clear ? "Cleared" : "Saved", "ok");
         VIEWS.settings.load();
+        // A proxy change cannot reach a socket that is already open; the
+        // Connection screen is where that is offered, so refresh its state.
+        if (key.startsWith("whatsapp_proxy_")) loadStats().catch(() => {});
       })();
     });
   }
 
   // --- boot ---------------------------------------------------------------
 
+  // The socket is a one-way feed of what the backend is already doing. Opening
+  // it, losing it or reloading the page changes nothing about the WhatsApp
+  // session; a reconnect happens in the backend with every tab shut.
   function initSocket() {
     // eslint-disable-next-line no-undef
     const socket = io();
 
+    socket.on("session", (snapshot) => setStatus(snapshot));
+
     socket.on("qr", (qr) => {
       renderQr(qr);
-      setStatus(false, "Waiting for scan");
       if (currentView !== "connection") {
         toast("A new QR code is ready — open Connection to scan it.");
       }
     });
 
-    socket.on("status_update", (data) => {
-      const connected = data.status === "Connected";
-      setStatus(connected, data.status);
-      if (connected && currentView === "connection") VIEWS.connection.load();
+    socket.on("qr_cleared", () => clearQr());
+
+    // A socket that dropped may have missed transitions while it was away.
+    socket.on("connect", () => {
+      if (currentView === "connection") VIEWS.connection.load();
+      else loadStats().catch(() => {});
     });
   }
 

package/scheduler.cjs

@@ -103,6 +103,20 @@ function scheduleAt(whenMs, run) {
   return { stop: () => clearTimeout(timer) };
 }
 
+/**
+ * Stop every running task.
+ *
+ * Each task closes over the socket it was armed with (see scheduleNewJob), so
+ * once that socket is gone the task can only fail. The connection handler calls
+ * initializeScheduledJobs() again on the next open, which re-arms every job
+ * against the socket that is actually alive.
+ */
+function stopAllScheduledJobs() {
+  const count = runningTasks.size;
+  for (const jobId of [...runningTasks.keys()]) stopTask(jobId);
+  if (count) logger.info(`[Scheduler] Stopped ${count} job(s) — no live connection`);
+}
+
 function stopTask(jobId) {
   const existing = runningTasks.get(jobId);
   if (!existing) return;
@@ -189,6 +203,7 @@ function updateJobStatus(jobId, status) {
 
 module.exports = {
   initializeScheduledJobs,
+  stopAllScheduledJobs,
   scheduleNewJob,
   getScheduledJobs,
   saveScheduledJob,

package/src/bootstrap/core.js

@@ -1,15 +1,21 @@
 // Everything Levix needs to be a WhatsApp bot.
 //
-// Database, settings, commands, the WhatsApp socket, the scheduler. No HTTP,
-// no Express, no socket.io — those live in bootstrap/panel.js and are entirely
-// optional. `levix headless` runs this file and nothing else, which is what
-// makes "no panel port is opened" a fact rather than a promise.
+// Database, settings, commands, the WhatsApp session manager, the scheduler.
+// No HTTP, no Express, no socket.io — those live in bootstrap/panel.js and are
+// entirely optional. `levix headless` runs this file and nothing else, which is
+// what makes "no panel port is opened" a fact rather than a promise.
+//
+// Note what this does NOT do: it does not dial WhatsApp. It builds the session
+// manager and hands it back. Panel mode leaves it idle until somebody presses
+// Start on the Connection screen; headless has nobody to press anything, so it
+// asks for `autoStart`. That is the whole of the difference between the two
+// modes — there is no `if (headless)` anywhere below this line.
 
 import { createRequire } from "module";
-import { createWhatsAppSocket } from "../core/socket.js";
-import { setupEventListeners } from "../core/events.js";
+import { WhatsAppSession } from "../core/session.js";
 import { loadCommands, getLoadedCommands } from "../handlers/command.handler.js";
 import { initStore } from "../db/store.esm.js";
+import { deleteQrCode } from "../utils/storage.esm.js";
 
 const require = createRequire(import.meta.url);
 const logger = require("../utils/logger.cjs");
@@ -17,18 +23,17 @@ const { sink } = require("./events.cjs");
 const { acquireSingleInstanceLock } = require("../config/lock.cjs");
 const { ensureDataDir } = require("../config/paths.cjs");
 const store = require("../db/store.cjs");
-const { initializeScheduledJobs } = require("../../scheduler.cjs");
+const { initializeScheduledJobs, stopAllScheduledJobs } = require("../../scheduler.cjs");
 
 /**
  * Start the bot.
  *
  * @param {object} [options]
- * @param {(sock: object, controls: object) => void} [options.onSocket]
- *   Called with every socket, including the ones a reconnect produces — the
- *   panel uses it to keep its "unlink" button pointed at the live connection.
- * @returns {Promise<{ sock: object, commandCount: number, wasPaired: boolean }>}
+ * @param {boolean} [options.autoStart] - connect to WhatsApp straight away.
+ *   Headless does; the panel waits to be asked.
+ * @returns {Promise<{ session: object, commandCount: number, wasPaired: boolean }>}
  */
-export async function bootstrapCore({ onSocket } = {}) {
+export async function bootstrapCore({ autoStart = false } = {}) {
   // Claim the data directory before anything touches the WhatsApp session. A
   // second copy has to fail here, not after it has written to the auth rows
   // the first one is using.
@@ -45,30 +50,29 @@ export async function bootstrapCore({ onSocket } = {}) {
   await initStore();
   await loadCommands();
 
-  const sock = await connect({ onSocket });
-
-  return { sock, commandCount: getLoadedCommands().size, wasPaired };
-}
-
-async function connect({ onSocket, isReconnect = false } = {}) {
-  const { sock, saveCreds, clearAll } = await createWhatsAppSocket();
+  // A pairing code belongs to the socket that issued it. One left in the table
+  // by a process that was killed rather than stopped can never be scanned, and
+  // GET /qr would happily serve it to somebody who then waits for nothing.
+  deleteQrCode();
 
-  setupEventListeners(
-    sock,
-    saveCreds,
-    clearAll,
+  const session = new WhatsAppSession({
     // The bot reports into the hub; whoever is listening decides what that
     // means — a socket.io broadcast, a line in the terminal, or nothing.
-    sink,
+    emit: sink.emit,
     initializeScheduledJobs,
-    async () => {
-      logger.info("[Reconnect] Attempting to reconnect to WhatsApp...");
-      await connect({ onSocket, isReconnect: true });
-    }
-  );
+    stopScheduledJobs: stopAllScheduledJobs,
+    log: logger,
+  });
 
-  if (onSocket) onSocket(sock, { clearAll, isReconnect });
+  if (autoStart) await session.start({ reason: "autostart" });
 
-  logger.info("WhatsApp socket initialized successfully");
-  return sock;
+  return {
+    session,
+    commandCount: getLoadedCommands().size,
+    wasPaired,
+    /** The live socket, or null. Re-read it; a reconnect replaces it. */
+    get sock() {
+      return session.socket;
+    },
+  };
 }

package/src/bootstrap/events.cjs

@@ -10,8 +10,10 @@
 //   panel     -> forwards every event to socket.io
 //   headless  -> prints the ones a person waiting at a terminal cares about
 //
-// `sink` is shaped like the socket.io server object because that is what
-// `setupEventListeners` is handed. Nothing in src/core had to change.
+// `sink` is shaped like the socket.io server object because that is what the
+// panel forwards from. The WhatsApp session manager (src/core/session.js) emits
+// into it; nothing that listens here can emit back into the bot, which is what
+// keeps a browser attaching or leaving from touching the connection.
 
 const listeners = new Set();
 

package/src/bootstrap/panel.js

@@ -31,8 +31,9 @@ export async function bootstrapPanel({ core } = {}) {
     installFinalHandlers,
   } = require("../../app.cjs");
 
-  const { default: dashboardApiRoutes, setBotInstance, setBotControls } =
-    await import("../routes/dashboard.api.esm.js");
+  const { default: dashboardApiRoutes, setSession } = await import(
+    "../routes/dashboard.api.esm.js"
+  );
 
   // Same session as the control panel: these routes hand back groups, debts
   // and warnings with people's numbers in them.
@@ -40,12 +41,13 @@ export async function bootstrapPanel({ core } = {}) {
   logger.info("Dashboard API routes registered");
 
   // Everything the bot reports goes out to the browsers watching the panel.
+  // One direction only: a browser attaching or leaving cannot reach back and
+  // change the WhatsApp session's lifecycle. See src/core/session.js.
   attach((event, payload) => io.emit(event, payload));
 
-  if (core?.sock) {
-    setBotInstance(core.sock);
-    setBotControls({ clearAll: core.clearAll });
-  }
+  // The routes read the live socket off the session manager, so a reconnect
+  // needs no re-wiring here.
+  if (core?.session) setSession(core.session);
 
   // After every route is registered — the 404 and the error handler have to be
   // last, or they swallow what comes after them.
@@ -73,7 +75,7 @@ export async function bootstrapPanel({ core } = {}) {
     server.listen(port, host, resolve);
   });
 
-  return { port, host, server, setBotInstance, setBotControls };
+  return { port, host, server };
 }
 
 /**

package/src/commands/autoschedule.cjs

@@ -2,7 +2,7 @@ const {
   scheduleNewJob,
   saveScheduledJob,
 } = require("../../scheduler.cjs");
-const { v4: uuidv4 } = require("uuid"); // Use UUID for unique IDs
+const { randomUUID } = require("node:crypto");
 const { defaultTimezone } = require("../utils/datetime.cjs");
 
 module.exports = {
@@ -58,7 +58,7 @@ module.exports = {
     }
 
     const newJob = {
-      id: uuidv4(),
+      id: randomUUID(),
       type: "recurring",
       cronString: cronString,
       message: message,
@@ -81,4 +81,3 @@ module.exports = {
     });
   },
 };
-// Note: You need to run `npm install uuid` for this command.