levix-bot 2.0.0 → 2.1.0

package/src/config/settings.cjs

@@ -59,9 +59,10 @@ const SETTINGS = [
   {
     key: "gemini_model",
     type: "string",
-    default: "gemini-2.5-flash",
+    default: "gemini-3.7-flash",
     group: "ai",
     label: "Gemini model",
+    hint: "The model that answers. Flash is the default because a WhatsApp reply is judged on how fast it arrives; it still takes Google Search and Levix's own function tools in the same request, which is what the agent depends on. A Gemini 3 Pro model works here too if you would rather trade latency for depth.",
   },
   {
     key: "ai_agent",
@@ -108,6 +109,30 @@ const SETTINGS = [
     label: "Memory injected (chars)",
     hint: "How much of the long-term memory files goes into every prompt.",
   },
+  {
+    key: "gemini_stt_model",
+    type: "string",
+    default: "gemini-3.7-flash",
+    group: "ai",
+    label: "Gemini transcription model",
+    hint: "Used by !stt only. Transcription is high-volume and latency-bound, so it stays on Flash whatever the chat model is set to.",
+  },
+  {
+    key: "gemini_image_model",
+    type: "string",
+    default: "gemini-3.1-flash-image",
+    group: "ai",
+    label: "Gemini image model",
+    hint: "Used by !generate only. Image output needs a model that can return images, which is not the same one that answers chat — gemini-3.1-flash-image is the dedicated stable one.",
+  },
+  {
+    key: "ai_google_search",
+    type: "bool",
+    default: true,
+    group: "ai",
+    label: "Gemini Google Search",
+    hint: "Lets Gemini use Google's own search grounding when a question needs current information. Gemini only — the Groq fallback is unaffected.",
+  },
   {
     key: "groq_api_key",
     type: "secret",
@@ -185,6 +210,65 @@ const SETTINGS = [
     hint: "Only if the bundled ffmpeg-static binary can't run on this machine.",
   },
 
+  // --- WhatsApp proxy ----------------------------------------------------
+  //
+  // Applies to the WhatsApp connection ONLY: the session manager hands these
+  // to the one makeWASocket() call (src/core/proxy.js). The control panel, the
+  // AI providers and every other outbound request are untouched.
+  //
+  // None of these apply to a socket that is already open — the Connection
+  // screen offers "Reconnect to apply" instead of dropping a healthy session
+  // the moment somebody opens Settings.
+  {
+    key: "whatsapp_proxy_enabled",
+    type: "bool",
+    default: false,
+    group: "whatsapp",
+    label: "Route WhatsApp through a proxy",
+    hint: "Off means WhatsApp connects directly, exactly as before.",
+  },
+  {
+    key: "whatsapp_proxy_protocol",
+    type: "string",
+    default: "http",
+    choices: ["http", "https", "socks5"],
+    group: "whatsapp",
+    label: "Proxy protocol",
+  },
+  {
+    key: "whatsapp_proxy_host",
+    type: "string",
+    default: "",
+    group: "whatsapp",
+    label: "Proxy host",
+    hint: "Hostname or IP of the proxy server. Required when the proxy is on.",
+  },
+  {
+    key: "whatsapp_proxy_port",
+    type: "int",
+    default: 0,
+    min: 0,
+    max: 65535,
+    group: "whatsapp",
+    label: "Proxy port",
+  },
+  {
+    key: "whatsapp_proxy_username",
+    type: "string",
+    default: "",
+    group: "whatsapp",
+    label: "Proxy username",
+    hint: "Leave empty for a proxy that needs no authentication.",
+  },
+  {
+    key: "whatsapp_proxy_password",
+    type: "secret",
+    default: "",
+    group: "whatsapp",
+    label: "Proxy password",
+    hint: "Stored like an API key: never sent back to this page, never logged.",
+  },
+
   // --- Server ------------------------------------------------------------
   {
     key: "port",
@@ -251,6 +335,7 @@ const GROUP_LABELS = {
   integrations: "Integrations",
   media: "Media",
   server: "Server",
+  whatsapp: "WhatsApp proxy",
 };
 
 // This module is required by files that load before the database is opened in
@@ -319,7 +404,15 @@ function validate(definition, value) {
 
   if (definition.type === "bool") return coerce(definition, value);
 
-  const text = String(value ?? "");
+  const text = String(value ?? "").trim();
+
+  // A fixed set of values (the proxy protocol) is still a string setting; the
+  // list is what makes the dashboard render a dropdown and what stops a
+  // hand-crafted PATCH from storing something the code cannot act on.
+  if (definition.choices && text && !definition.choices.includes(text)) {
+    throw new Error(`${definition.label} must be one of: ${definition.choices.join(", ")}`);
+  }
+
   if (text.length > 500) throw new Error(`${definition.label} is too long`);
   if (definition.key === "bot_timezone" && text) {
     try {
@@ -372,6 +465,7 @@ function describe() {
       hint: definition.hint || null,
       min: definition.min ?? null,
       max: definition.max ?? null,
+      choices: definition.choices ?? null,
       restart: definition.restart === true,
       source: sourceOf(definition.key),
     };

package/src/core/connection.js

@@ -1,152 +1,158 @@
-import { delay, DisconnectReason } from "@whiskeysockets/baileys";
-import qrcode from "qrcode-terminal";
+// What a WhatsApp connection means, minus the decision of when to make one.
+//
+// The retry schedule, the socket's lifetime and the state machine live in
+// src/core/session.js. This file answers two narrower questions:
+//
+//   classifyDisconnect(statusCode)  — is this close terminal, and why?
+//   handleConnectionOpen(sock, …)   — what has to happen once one is open?
+//
+// Keeping them apart is what lets the state machine be tested without Baileys
+// and without a database.
+
+import { DisconnectReason } from "@whiskeysockets/baileys";
 import { createRequire } from "module";
-import { MAX_RETRIES, RETRY_DELAY_MS } from "../config/constants.js";
 import { groupMetadataCache } from "./socket.js";
 import {
-  saveQrCode,
-  deleteQrCode,
   saveUserMetadata,
   getAllOwners,
   getAllBotAdmins,
 } from "../utils/storage.esm.js";
-import {
-  bootstrapOwners,
-  bootstrapAdmins,
-} from "../utils/permissions.esm.js";
+import { bootstrapOwners, bootstrapAdmins } from "../utils/permissions.esm.js";
 
 const require = createRequire(import.meta.url);
 const logger = require("../utils/logger.cjs");
 const { primePermissions } = require("../utils/permissions.cjs");
 
-let retryCount = 0;
-
-// Handle connection updates
-export async function handleConnectionUpdate(
-  update,
-  sock,
-  clearAll,
-  io,
-  initializeScheduledJobs
-) {
-  const { connection, lastDisconnect, qr } = update;
-
-  if (qr) {
-    logger.info("Scan the QR code below:");
-    saveQrCode(qr);
-    io.emit("qr", qr);
-    io.emit("status_update", { status: "QR Code Received" });
-    qrcode.generate(qr, { small: true });
+/**
+ * WhatsApp answers a `<failure reason="405">` when it refuses the connection
+ * outright — the number is not in Baileys' DisconnectReason enum, so it is
+ * named here rather than left as a bare literal in a comparison. Retrying it is
+ * how an install ends up hammering a server that has already said no, so Levix
+ * treats it as terminal and waits for a person.
+ */
+export const CONNECTION_FAILURE_405 = 405;
+
+/**
+ * Read a close and say what should happen next.
+ *
+ * Terminal means: do not reconnect on our own. Everything else gets the staged
+ * retry schedule in session.js.
+ *
+ * @param {number|undefined} statusCode - `lastDisconnect.error.output.statusCode`
+ */
+export function classifyDisconnect(statusCode) {
+  // Baileys reports an intentional logout and a server-side unlink with the
+  // same code (DisconnectReason.loggedOut === 401), and it is the only case
+  // where the stored credentials are genuinely dead.
+  if (statusCode === DisconnectReason.loggedOut) {
+    return {
+      terminal: true,
+      loggedOut: true,
+      restartRequired: false,
+      reason: "logged_out",
+      label: "logged out",
+      detail: "WhatsApp unlinked this device. Start a session to pair again.",
+    };
   }
 
-  if (connection === "close") {
-    const statusCode = lastDisconnect?.error?.output?.statusCode;
-    const reason =
-      lastDisconnect?.error?.output?.payload?.error ||
-      lastDisconnect?.error?.message ||
-      "Unknown";
-
-    // Define which status codes should trigger reconnection
-    // 515: QR timeout, 500/503: Server errors, 404: Not found, etc.
-    const noReconnectCodes = [401, 403, DisconnectReason.loggedOut];
-    const shouldReconnect = !noReconnectCodes.includes(statusCode);
-
-    io.emit("status_update", { status: "Disconnected" });
-
-    // Log full disconnect info for debugging
-    logger.debug(
-      { lastDisconnect, statusCode, reason },
-      "[Connection] Disconnect details"
-    );
-
-    if (shouldReconnect && retryCount < MAX_RETRIES) {
-      retryCount++;
-      const delayMs = RETRY_DELAY_MS * retryCount; // Exponential backoff: 5s, 10s, 15s, 20s, 25s
-
-      // Special message for QR timeout
-      const messagePrefix =
-        statusCode === 515 ? "🔄 QR code expired" : "🔌 Connection closed";
-
-      logger.warn(
-        `${messagePrefix}. Reason: ${statusCode || reason}. Retrying in ${
-          delayMs / 1000
-        }s... (Attempt ${retryCount}/${MAX_RETRIES})`
-      );
-
-      await delay(delayMs);
-      return { shouldReconnect: true };
-    } else if (!shouldReconnect) {
-      if (statusCode === DisconnectReason.loggedOut) {
-        logger.error(
-          "❌ Connection closed permanently. Logged out. Clearing auth data from database."
-        );
-
-        // Clear authentication data from database
-        if (clearAll) {
-          await clearAll();
-          logger.info("[Auth] Authentication data cleared from database");
-        }
-
-        // Reset retry count and trigger reconnection for new QR
-        retryCount = 0;
-        return { shouldReconnect: true };
-      } else {
-        logger.error(
-          `❌ Connection closed with non-recoverable error: ${statusCode}. Not retrying.`
-        );
-      }
-    } else {
-      logger.error(`❌ Max retries (${MAX_RETRIES}) reached. Exiting.`);
-
-      process.exit(1);
-    }
-  } else if (connection === "open") {
-    logger.info("✅ Connection opened successfully!");
-    deleteQrCode();
-
-    retryCount = 0;
-    io.emit("status_update", { status: "Connected" });
-
-    // The paired account is always an owner — that's the whole bootstrap.
-    // Everyone else is granted from the dashboard (Roles) or with `!perm`, and
-    // is already a row in user_metadata by the time we get here.
-    await saveBotOwnerMetadata(sock);
+  if (statusCode === CONNECTION_FAILURE_405) {
+    return {
+      terminal: true,
+      loggedOut: false,
+      restartRequired: false,
+      reason: "connection_failure",
+      label: "refused by WhatsApp (405)",
+      // Deliberately not a credential wipe: a 405 says WhatsApp would not take
+      // this connection, not that the pairing is gone.
+      detail:
+        "WhatsApp refused the connection (405). The pairing was left alone — try starting the session again later.",
+    };
+  }
 
-    const botPn = sock.user?.id
-      ? `${sock.user.id.split(":")[0].split("@")[0]}@s.whatsapp.net`
-      : null;
-    const botLid = sock.user?.lid
-      ? `${sock.user.lid.split(":")[0].split("@")[0]}@lid`
-      : null;
+  if (statusCode === DisconnectReason.forbidden) {
+    return {
+      terminal: true,
+      loggedOut: false,
+      restartRequired: false,
+      reason: "forbidden",
+      label: "forbidden",
+      detail: "WhatsApp rejected this account (403). Reconnecting will not help.",
+    };
+  }
 
-    // Both rosters are seeded from the database so a permission check never
-    // has to hit it on the hot path.
-    const ownersRoster = [
-      botPn,
-      botLid,
-      ...getAllOwners().flatMap((user) => [user.jid, user.lid]),
-    ].filter(Boolean);
-    const adminsRoster = getAllBotAdmins()
-      .flatMap((user) => [user.jid, user.lid])
-      .filter(Boolean);
-
-    bootstrapOwners(ownersRoster);
-    bootstrapAdmins(adminsRoster);
-
-    await primePermissions();
-    logger.info(
-      `[Permissions] Owner roster: ${ownersRoster.length} entries; ` +
-        `admin roster: ${adminsRoster.length} entries`
-    );
-
-    // Initialize scheduled jobs
-    initializeScheduledJobs(sock);
-
-    // Cache all groups
-    await cacheAllGroups(sock);
+  // Part of the pairing handshake: WhatsApp asks for the socket to be made
+  // again once a phone has scanned the code. Recoverable, and never the end of
+  // a pairing attempt.
+  if (statusCode === DisconnectReason.restartRequired) {
+    return {
+      terminal: false,
+      loggedOut: false,
+      restartRequired: true,
+      reason: "restart_required",
+      label: "restart required",
+      detail: "WhatsApp asked for a fresh connection.",
+    };
   }
 
-  return { shouldReconnect: false };
+  return {
+    terminal: false,
+    loggedOut: false,
+    restartRequired: false,
+    reason: "connection_closed",
+    label: "recoverable",
+    detail: null,
+  };
+}
+
+/**
+ * Everything that has to happen the moment a connection is open: record the
+ * paired account as an owner, seed the permission rosters, (re)start the
+ * scheduled jobs against the new socket, and cache the group metadata.
+ *
+ * @param {object} sock
+ * @param {(sock: object) => void} [initializeScheduledJobs]
+ */
+export async function handleConnectionOpen(sock, initializeScheduledJobs) {
+  logger.info("✅ Connection opened successfully!");
+
+  // The paired account is always an owner — that's the whole bootstrap.
+  // Everyone else is granted from the dashboard (Roles) or with `!perm`, and
+  // is already a row in user_metadata by the time we get here.
+  await saveBotOwnerMetadata(sock);
+
+  const botPn = sock?.user?.id
+    ? `${sock.user.id.split(":")[0].split("@")[0]}@s.whatsapp.net`
+    : null;
+  const botLid = sock?.user?.lid
+    ? `${sock.user.lid.split(":")[0].split("@")[0]}@lid`
+    : null;
+
+  // Both rosters are seeded from the database so a permission check never has
+  // to hit it on the hot path.
+  const ownersRoster = [
+    botPn,
+    botLid,
+    ...getAllOwners().flatMap((user) => [user.jid, user.lid]),
+  ].filter(Boolean);
+  const adminsRoster = getAllBotAdmins()
+    .flatMap((user) => [user.jid, user.lid])
+    .filter(Boolean);
+
+  bootstrapOwners(ownersRoster);
+  bootstrapAdmins(adminsRoster);
+
+  await primePermissions();
+  logger.info(
+    `[Permissions] Owner roster: ${ownersRoster.length} entries; ` +
+      `admin roster: ${adminsRoster.length} entries`
+  );
+
+  // Called on every open, including a reconnect: scheduleNewJob() stops the
+  // previous timer for the same id first, so a weekly message is not sent twice
+  // after the first reconnect.
+  if (initializeScheduledJobs) initializeScheduledJobs(sock);
+
+  await cacheAllGroups(sock);
 }
 
 // Record the paired WhatsApp account as the bot's first owner. Whoever scanned
@@ -155,12 +161,12 @@ async function saveBotOwnerMetadata(sock) {
   try {
     logger.info("[User Metadata] Saving bot owner metadata...");
 
-    const phoneNumber = sock.user?.id?.split(":")[0]?.split("@")[0];
+    const phoneNumber = sock?.user?.id?.split(":")[0]?.split("@")[0];
     const userJid = phoneNumber ? `${phoneNumber}@s.whatsapp.net` : null;
-    const userLid = sock.user?.lid
+    const userLid = sock?.user?.lid
       ? `${sock.user.lid.split(":")[0].split("@")[0]}@lid`
       : null;
-    const displayName = sock.user?.name || sock.user?.verifiedName || null;
+    const displayName = sock?.user?.name || sock?.user?.verifiedName || null;
 
     if (userJid) {
       saveUserMetadata({

package/src/core/events.js

@@ -1,26 +1,63 @@
 import { createRequire } from 'module';
-import { handleConnectionUpdate } from './connection.js';
 import { handleIncomingMessage } from '../handlers/message.handler.js';
 import { handleGroupParticipantsUpdate, handleGroupJoinRequests } from '../handlers/group.handler.js';
 import { groupMetadataCache } from './socket.js';
-import { storeLidPnMapping, storeLidPnMappings } from '../utils/storage.esm.js';
+import { storeLidPnMappings } from '../utils/storage.esm.js';
 
 const require = createRequire(import.meta.url);
 const logger = require('../utils/logger.cjs');
 
-// Setup all event listeners for WhatsApp socket
-export function setupEventListeners(sock, saveCreds, clearAll, io, initializeScheduledJobs, reconnectCallback) {
-  // Connection updates
-  sock.ev.on('connection.update', async (update) => {
-    const result = await handleConnectionUpdate(update, sock, clearAll, io, initializeScheduledJobs);
-    if (result?.shouldReconnect && reconnectCallback) {
-      // Trigger reconnection
-      await reconnectCallback();
-    }
-  });
+/**
+ * Wire one socket up.
+ *
+ * `connection.update` is handed straight to the session manager
+ * (src/core/session.js) — it owns the state machine and the retry schedule, so
+ * nothing here decides whether to reconnect.
+ *
+ * @param {object} sock
+ * @param {object} handlers
+ * @param {() => Promise<void>} handlers.saveCreds
+ * @param {(update: object) => void} handlers.onConnectionUpdate
+ * @param {(response: object) => void} [handlers.onHandshakeRejected]
+ */
+export function setupEventListeners(
+  sock,
+  { saveCreds, onConnectionUpdate, onHandshakeRejected } = {}
+) {
+  // Every listener below goes through this. A bare `async` listener hands its
+  // promise to Baileys' emitter, which drops it — so one rejection anywhere in
+  // the message pipeline becomes an unhandledRejection, and src/index.js turns
+  // that into a process exit. A group lookup failing mid-disconnect is exactly
+  // the case the reconnect ladder exists to survive, so it must not be fatal.
+  const contained = (label, handler) => (payload) => {
+    Promise.resolve()
+      .then(() => handler(payload))
+      .catch((err) => logger.error({ err }, `[Events] ${label} handler failed`));
+  };
+
+  sock.ev.on(
+    'connection.update',
+    contained('connection.update', (update) => onConnectionUpdate?.(update))
+  );
+
+  // A handshake the server answered with an HTTP status instead of an upgrade.
+  //
+  // This has to be listened for or the connection hangs silently forever: ws
+  // only calls abortHandshake() when NOTHING is listening for
+  // 'unexpected-response' (ws/lib/websocket.js:928), and Baileys' own
+  // WebSocketClient registers a re-emitting listener for it — which satisfies
+  // that guard and then does nothing with the event. A proxy answering 407
+  // therefore produced no error, no close and no connection.update at all: the
+  // session simply sat in `starting` until somebody noticed.
+  sock.ws?.on?.(
+    'unexpected-response',
+    contained('unexpected-response', (_request, response) => {
+      onHandshakeRejected?.(response);
+    })
+  );
 
   // Save credentials
-  sock.ev.on('creds.update', saveCreds);
+  if (saveCreds) sock.ev.on('creds.update', saveCreds);
 
   // V7: LID mapping updates
   sock.ev.on('lid-mapping.update', (updates) => {
@@ -45,17 +82,22 @@ export function setupEventListeners(sock, saveCreds, clearAll, io, initializeSch
   });
 
   // Incoming messages
-  sock.ev.on('messages.upsert', async (m) => {
-    await handleIncomingMessage(sock, m);
-  });
+  sock.ev.on(
+    'messages.upsert',
+    contained('messages.upsert', (m) => handleIncomingMessage(sock, m))
+  );
 
   // Group participant updates
-  sock.ev.on('group-participants.update', async (update) => {
-    await handleGroupParticipantsUpdate(sock, update);
-  });
+  sock.ev.on(
+    'group-participants.update',
+    contained('group-participants.update', (update) =>
+      handleGroupParticipantsUpdate(sock, update)
+    )
+  );
 
   // Group join requests
-  sock.ev.on('group-requests.update', async (events) => {
-    await handleGroupJoinRequests(sock, events);
-  });
+  sock.ev.on(
+    'group-requests.update',
+    contained('group-requests.update', (events) => handleGroupJoinRequests(sock, events))
+  );
 }