@manybot/manybot 4.4.0 → 5.1.0

package/src/kernel/pluginApi.js

@@ -17,26 +17,51 @@ import { emptyFolder }                         from "#utils/file";
 import { getChatId }                           from "#utils/getChatId";
 import pkg                                     from "whatsapp-web.js";
 import { mkdirSync }                           from "fs";
+import path                                    from "path";
+import { waitForSendSlot, simulateState,
+         typingDuration, mediaDuration }       from "#sendguard";
 
 const { MessageMedia } = pkg;
 
 // ── Storage API ──────────────────────────────────────────────────────────────
 
 export function buildStorageApi(pluginName) {
+  if (typeof pluginName !== "string" || pluginName.trim() === "") {
+    throw new Error("[storage] buildStorageApi: pluginName must be a non-empty string");
+  }
+
   const dir = path.join(CONFIG_DIR, "data", pluginName);
   mkdirSync(dir, { recursive: true });
-  
+
   return {
     dir,
 
     /**
-     * Resolves a path inside data directory.
-     * Make subdirectories automatically.
+     * Resolves a path inside the plugin's data directory.
+     * Creates subdirectories automatically.
      * @param {string} relativePath
      * @returns {string}
      */
-    path(relativePath) {
+    resolve(relativePath) {
+      if (!relativePath || typeof relativePath !== "string") {
+        throw new Error(`[storage] resolve() requires a non-empty string, got: ${typeof relativePath}`);
+      }
+      if (relativePath.includes("..")) {
+        throw new Error(`[storage] path traversal detected in: "${relativePath}"`);
+      }
+      if (path.isAbsolute(relativePath)) {
+        throw new Error(`[storage] absolute paths are not allowed: "${relativePath}"`);
+      }
+      if (relativePath.includes("\\")) {
+        throw new Error(`[storage] Windows-style paths are not allowed: "${relativePath}"`);
+      }
+
       const resolved = path.join(dir, relativePath);
+
+      if (!resolved.startsWith(path.resolve(dir) + path.sep)) {
+        throw new Error(`[storage] resolved path escapes plugin data dir: "${resolved}"`);
+      }
+
       mkdirSync(path.dirname(resolved), { recursive: true });
       return resolved;
     },
@@ -55,9 +80,6 @@ function buildConfigApi() {
     get(key, defaultValue = null) {
       return CONFIG[key] ?? defaultValue;
     },
-
-    /** Full config object — read only. */
-    all: CONFIG,
   };
 }
 
@@ -135,7 +157,7 @@ function buildPluginsApi(pluginRegistry) {
     require(name) {
       const plugin = pluginRegistry.get(name);
       if (!plugin || plugin.status !== "active") {
-        throw new Error(`Plugin dependency "${name}" does not exist or is not active.`);
+        throw new Error(`[plugins] dependency "${name}" does not exist or is not active`);
       }
       return plugin.exports;
     },
@@ -249,28 +271,70 @@ function mediaFromSource(source, mimetype) {
 
 /**
  * Returns send methods bound to a target that exposes `.sendMessage()`.
+ *
  * @param {{ sendMessage: Function }} target
+ * @param {object}      [extraOpts]  — merged into every sendMessage call (e.g. { quoted: msg })
+ * @param {string|null} [chatId]     — serialized chat ID; enables sendGuard when set
+ * @param {object|null} [chatObj]    — real Chat object; enables typing indicator when set
  */
-function makeSender(target) {
+function makeSender(target, extraOpts = {}, chatId = null, chatObj = null, { cooldown = true, jitter = true } = {}) {
   return {
     async text(content, opts = {}) {
-      return target.sendMessage(content, opts);
+      if (chatId) {
+        await waitForSendSlot(chatId, { cooldown, jitter });
+        await simulateState(chatObj, typingDuration(content), "typing");
+      }
+      return target.sendMessage(content, { ...extraOpts, ...opts });
     },
+
     async image(filePath, caption = "") {
+      if (chatId) {
+        await waitForSendSlot(chatId, { cooldown, jitter });
+        await simulateState(chatObj, mediaDuration(), "typing");
+      }
       const media = MessageMedia.fromFilePath(filePath);
-      return target.sendMessage(media, { caption });
+      return target.sendMessage(media, { caption, ...extraOpts });
     },
+
     async video(filePath, caption = "") {
+      if (chatId) {
+        await waitForSendSlot(chatId, { cooldown, jitter });
+        await simulateState(chatObj, mediaDuration(), "typing");
+      }
       const media = MessageMedia.fromFilePath(filePath);
-      return target.sendMessage(media, { caption });
+      return target.sendMessage(media, { caption, ...extraOpts });
     },
+
     async audio(filePath, { asVoice = true } = {}) {
+      if (chatId) {
+        await waitForSendSlot(chatId, { cooldown, jitter });
+        // "gravando áudio…" é mais convincente que "digitando…" para áudio
+        await simulateState(chatObj, mediaDuration(), "recording");
+      }
       const media = MessageMedia.fromFilePath(filePath);
-      return target.sendMessage(media, { sendAudioAsVoice: asVoice });
+      return target.sendMessage(media, { sendAudioAsVoice: asVoice, ...extraOpts });
     },
+
     async sticker(source) {
+      if (chatId) {
+        await waitForSendSlot(chatId, { cooldown, jitter });
+        await simulateState(chatObj, mediaDuration(), "typing");
+      }
       const media = mediaFromSource(source, "image/webp");
-      return target.sendMessage(media, { sendMediaAsSticker: true });
+      return target.sendMessage(media, { sendMediaAsSticker: true, ...extraOpts });
+    },
+
+    async file(filePath, filename) {
+      if (chatId) {
+        await waitForSendSlot(chatId, { cooldown, jitter });
+        await simulateState(chatObj, mediaDuration(), "typing");
+      }
+      const media = MessageMedia.fromFilePath(filePath);
+      return target.sendMessage(media, {
+        sendMediaAsDocument: true,
+        filename: filename ?? path.basename(filePath),
+        ...extraOpts,
+      });
     },
   };
 }
@@ -291,27 +355,28 @@ function chatIdTarget(client, chatId) {
  * ctx.send.image("./foto.jpg", "legenda")
  * ctx.send.to("5511@c.us").text("oi")
  */
-function buildSendApi(chat, client) {
-  const current = makeSender(chat);
-
+function buildSendApi(chat, client, guardOptions = {}) {
+  const chatId  = chat.id._serialized;
+  const { cooldown = true, jitter = true } = guardOptions;
+  const current = makeSender(chat, {}, chatId, chat, { cooldown, jitter });
   return {
     send: {
-      text:    (text, opts)        => current.text(text, opts),
-      image:   (filePath, caption) => current.image(filePath, caption),
-      video:   (filePath, caption) => current.video(filePath, caption),
-      audio:   (filePath, opts)    => current.audio(filePath, opts),
-      sticker: (source)            => current.sticker(source),
-
+      text:    (text, opts)         => current.text(text, opts),
+      image:   (filePath, caption)  => current.image(filePath, caption),
+      video:   (filePath, caption)  => current.video(filePath, caption),
+      audio:   (filePath, opts)     => current.audio(filePath, opts),
+      sticker: (source)             => current.sticker(source),
+      file:    (filePath, filename) => current.file(filePath, filename),
       /**
        * Returns a sender bound to another chat.
-       * @param {string} chatId
-       * @returns {{ text, image, video, audio, sticker }}
+       * Typing simulation is skipped (no Chat object available without a fetch).
+       * @param {string} targetChatId
        */
-      to: (chatId) => makeSender(chatIdTarget(client, chatId)),
+      to: (targetChatId) =>
+        makeSender(chatIdTarget(client, targetChatId), {}, targetChatId, null),
     },
   };
 }
-
 /**
  * Setup send API — no current chat, only .to().
  *
@@ -320,46 +385,82 @@ function buildSendApi(chat, client) {
 function buildSetupSendApi(client) {
   return {
     send: {
-      to: (chatId) => makeSender(chatIdTarget(client, chatId)),
+      to: (targetChatId) =>
+        makeSender(chatIdTarget(client, targetChatId), {}, targetChatId, null),
     },
   };
 }
 
 // ── Events API (setup only) ───────────────────────────────────────────────────
 
-function buildEventsApi(client) {
+/**
+ * @param {import("whatsapp-web.js").Client} client
+ * @param {string} pluginName
+ */
+const listenerRegistry = new Map();
+
+function buildEventsApi(client, pluginName) {
   return {
-    /**
-     * Registers a persistent listener for a client event.
-     * Returns an 'off()' function to cancel the listener when the plugin wants.
-     *
-     * @param {string}   event
-     * @param {Function} handler
-     * @returns {Function} off
-     *
-     * @example
-     * const off = ctx.events.on("group_join", (notification) => { ... });
-     * // cancels when the plugin doesn't want anymore:
-     * off();
-     */
     on(event, handler) {
       client.on(event, handler);
-      return () => client.off(event, handler);
+
+      if (!listenerRegistry.has(pluginName)) {
+        listenerRegistry.set(pluginName, new Set());
+      }
+
+      const ref = { event, handler };
+
+      listenerRegistry
+        .get(pluginName)
+        .add(ref);
+
+      return () => {
+        client.off(event, handler);
+
+        listenerRegistry
+          .get(pluginName)
+          ?.delete(ref);
+
+        if (
+          listenerRegistry
+            .get(pluginName)
+            ?.size === 0
+        ) {
+          listenerRegistry.delete(pluginName);
+        }
+      };
     },
 
-    /**
-     * Returns a Promise that resolves on the next ocurrence of the event.
-     * Useful for waiting a specific event without having to manage listeners manually.
-     *
-     * @param {string} event
-     * @returns {Promise<any>}
-     *
-     * @example
-     * const notification = await ctx.events.once("group_join");
-     */
-    once(event) {
-      return new Promise((resolve) => client.once(event, resolve));
-    }
+  once(event) {
+    return new Promise((resolve) => {
+      const off =
+        this.on(
+          event,
+          (data) => {
+            off();
+            resolve(data);
+          }
+        );
+    });
+  },
+
+    cleanup() {
+      const list =
+        listenerRegistry.get(pluginName);
+
+      if (!list) return;
+
+      for (const {
+        event,
+        handler
+      } of list) {
+        client.off(
+          event,
+          handler
+        );
+      }
+      listenerRegistry.delete(pluginName);
+    },
   };
 }
 
@@ -367,7 +468,7 @@ function buildEventsApi(client) {
 
 function buildBaseApi(client, pluginRegistry, pluginName) {
   const botId = client.info?.wid?._serialized ?? null;
-  if (!botId) logger.warn("[pluginApi] botId is null - client may not be ready yet.");
+  if (!botId) logger.warn("[pluginApi] botId is null — client may not be ready yet.");
 
   return {
     log,
@@ -390,14 +491,15 @@ function buildBaseApi(client, pluginRegistry, pluginName) {
  * Passed to plugin.setup(ctx) during initialization.
  *
  * @param {import("whatsapp-web.js").Client} client
- * @param {Map<string, any>} pluginRegistry
+ * @param {Map<string, any>}                 pluginRegistry
+ * @param {string}                           pluginName
  * @returns {object}
  */
-export function buildSetupApi(client, pluginRegistry, pluginName) {
+export function buildSetupApi(client, pluginRegistry, pluginName ) {
   return {
     ...buildBaseApi(client, pluginRegistry, pluginName),
     ...buildSetupSendApi(client),
-    events: buildEventsApi(client),
+    events: buildEventsApi(client, pluginName),
   };
 }
 
@@ -412,17 +514,21 @@ export function buildSetupApi(client, pluginRegistry, pluginName) {
  * @param {import("whatsapp-web.js").Chat}    params.chat
  * @param {import("whatsapp-web.js").Client}  params.client
  * @param {Map<string, any>}                  params.pluginRegistry
+ * @param {string}                            params.pluginName
  * @returns {object} ctx
  */
-export function buildApi({ msg, chat, client, pluginRegistry }) {
-  const prefix  = CONFIG.CMD_PREFIX ?? "!";
+export function buildApi({ msg, chat, client, pluginRegistry, pluginName, guardOptions = {} }) {
+  const prefix  = CONFIG.CMD_PREFIX;
   const rawArgs = msg.body?.trim().split(/\s+/) ?? [];
-  const command = rawArgs[0]?.toLowerCase().startsWith(prefix)
-    ? rawArgs[0].slice(prefix.length).toLowerCase()
-    : rawArgs[0]?.toLowerCase() ?? "";
+  const first = rawArgs[0]?.toLowerCase() ?? "";
+  const hasPrefix = first.startsWith(prefix)
+  const command = hasPrefix ? first.slice(prefix.length) : "";
+
+  const chatId = chat.id._serialized;
+  const { cooldown = true, jitter = true } = guardOptions;
 
   return {
-    ...buildBaseApi(client, pluginRegistry),
+    ...buildBaseApi(client, pluginRegistry, pluginName),
     ...buildSendApi(chat, client),
 
     // ── msg ──────────────────────────────────────────────────
@@ -441,11 +547,11 @@ export function buildApi({ msg, chat, client, pluginRegistry }) {
       args: rawArgs.slice(1),
 
       /**
-       * Check if message is a given command.
-       * @param {string} cmd — without prefix
+       * Check if message matches a given command.
+       * @param {string} cmd
        */
       is(cmd) {
-        return command === cmd.toLowerCase();
+        return this.hasPrefix && command === cmd.toLowerCase();
       },
 
       hasMedia:  msg.hasMedia,
@@ -464,14 +570,14 @@ export function buildApi({ msg, chat, client, pluginRegistry }) {
         return msg.getQuotedMessage();
       },
 
-      async reply(text) {
-        return msg.reply(text);
-      },
+      reply: makeSender(chat, { quotedMessageId: msg.id._serialized }, chatId, chat, { cooldown, jitter }),
 
       async react(emoji) {
         return msg.react(emoji);
       },
 
+      hasPrefix,
+
       /**
        * Get the sender as a normalized Contact object.
        * Same shape as ctx.contacts.get().
@@ -490,9 +596,9 @@ export function buildApi({ msg, chat, client, pluginRegistry }) {
     // ── chat ─────────────────────────────────────────────────
 
     chat: {
-      id:      chat.id._serialized,
+      id:      chatId,
       name:    chat.name || chat.id.user,
-      isGroup: /@g\.us$/.test(chat.id._serialized),
+      isGroup: /@g\.us$/.test(chatId),
 
       /**
        * List of group participants.

package/src/kernel/pluginGuard.js

@@ -2,36 +2,77 @@
  * pluginGuard.js
  *
  * Runs a plugin safely.
- * If plugin throws an error:
- *   - Logs error with context
- *   - Marks plugin as "error" in registry
+ *
+ * Protections:
+ *   - Hard timeout per plugin run (prevents infinite hangs from locking the queue)
+ *   - Catches and logs all errors with structured context
+ *   - Marks errored plugins so they are silently skipped from then on
  *   - Never crashes the bot
  *
- * Disabled or errored plugins are silently ignored.
+ * Per-plugin overrides:
+ *   Plugins may export a `guardOptions` object to opt out of specific
+ *   protections. The pluginLoader is responsible for reading this export
+ *   and storing it as `plugin.guardOptions` in the registry entry.
+ *
+ *   Supported keys:
+ *     timeout {boolean}  — set to `false` to disable the hard timeout.
+ *                          Use only for plugins that intentionally block
+ *                          (e.g. heavy media processing, sticker generation).
  */
-
 import { logger }         from "#logger";
-import { t }              from "#i18n";
 import { pluginRegistry } from "#kernel/pluginLoader";
 
+/** Max ms a single plugin run is allowed to take before it's force-aborted. */
+const PLUGIN_TIMEOUT_MS = 120_000;
+
+/**
+ * Races `promise` against a timeout rejection.
+ * @param {Promise}  promise
+ * @param {number}   ms
+ * @param {string}   pluginName
+ */
+function withTimeout(promise, ms, pluginName) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) =>
+      setTimeout(
+        () => reject(new Error(`timed out after ${ms}ms`)),
+        ms
+      )
+    ),
+  ]);
+}
+
 /**
  * @param {object} plugin   — pluginRegistry entry
  * @param {object} context  — buildApi ctx
+ *
+ * plugin.guardOptions (optional, read from plugin's own export):
+ *   @param {boolean} [plugin.guardOptions.timeout=true]
  */
 export async function runPlugin(plugin, context) {
   if (plugin.status !== "active") return;
 
+  const useTimeout = plugin.guardOptions?.timeout !== false;
+
   try {
-    await plugin.run(context);
+    const run = plugin.run(context);
+    await (useTimeout ? withTimeout(run, PLUGIN_TIMEOUT_MS, plugin.name) : run);
   } catch (err) {
-    // Disable plugin to prevent further breakage
     plugin.status = "error";
     plugin.error  = err;
     pluginRegistry.set(plugin.name, plugin);
 
-    logger.error(
-      t("system.pluginDisabledAfterError", { name: plugin.name, message: err.message }),
-      `\n             ${t("errors.stack")}: ${err.stack?.split("\n")[1]?.trim() ?? ""}`
-    );
+    const isTimeout = useTimeout && err.message?.startsWith("timed out");
+    const headline  = isTimeout
+      ? `[pluginGuard] Plugin "${plugin.name}" forcibly stopped: ${err.message}`
+      : `[pluginGuard] Plugin "${plugin.name}" threw an unhandled error and was disabled`;
+
+    logger.error(headline);
+    logger.error(`  message : ${err.message}`);
+    if (!isTimeout) {
+      const frame = err.stack?.split("\n")[1]?.trim() ?? "(no stack)";
+      logger.error(`  at      : ${frame}`);
+    }
   }
 }

package/src/kernel/pluginLoader.js

@@ -15,7 +15,7 @@ import { logger }        from "#logger";
 import { t }             from "#i18n";
 import { pathToFileURL } from "url";
 import { PATHS }         from "#config";
-import { buildStorageApi } from "#manyapi";
+import { buildSetupApi } from "#manyapi";
 
 const PLUGINS_DIR = path.join(PATHS.HOME, "plugins");
 
@@ -64,33 +64,59 @@ export async function loadPlugins(activePlugins) {
  *
  * @param {object} api — api without message context (only sendTo, log, schedule...)
  */
-export async function setupPlugins(baseApi) {
+export async function setupPlugins(client) {
   for (const plugin of pluginRegistry.values()) {
-    if (plugin.status !== "active" || !plugin.setup) continue;
+    if (plugin.status !== "active" || !plugin.setup)
+      continue;
+  
     try {
-      const api = { ...baseApi, storage: buildStorageApi(plugin.name) };
+      const api = buildSetupApi(
+        client,
+        pluginRegistry,
+        plugin.name
+      );
+  
       await plugin.setup(api);
+  
     } catch (err) {
-      logger.error(t("system.pluginSetupFailed", { name: plugin.name, message: err.message }));
+      logger.error(
+        t("system.pluginSetupFailed", {
+          name: plugin.name,
+          message: err.message
+        })
+      );
     }
   }
 }
 
 async function findPluginPath(name) {
-  // key direto: synt-xerror/figurinha
-  const direct = path.join(PLUGINS_DIR, name, "index.js");
-  if (fs.existsSync(direct)) return direct;
-
-  // nome simples em subdir: plugins/synt-xerror/figurinha
-  if (!fs.existsSync(PLUGINS_DIR)) return null;
-  for (const entry of fs.readdirSync(PLUGINS_DIR, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const nested = path.join(PLUGINS_DIR, entry.name, name, "index.js");
-    if (fs.existsSync(nested)) return nested;
-  }
-
-  return null;
+  const dir = path.join(PLUGINS_DIR, name);
+  const manifest = path.join(dir, "manyplug.json");
+
+  if (!fs.existsSync(manifest))
+    return null;
+
+  const { main = "index.js" } =
+    JSON.parse(
+      await fs.promises.readFile(
+        manifest,
+        "utf8"
+      )
+    );
+
+  const entry =
+    path.join(
+      dir,
+      main
+    );
+
+  return (
+    fs.existsSync(entry)
+      ? entry
+      : null
+  );
 }
+
 /**
  * Carrega um único plugin pelo nome.
  * @param {string} name
@@ -121,9 +147,10 @@ async function loadPlugin(name) {
       name,
       status:  "active",
       run:     mod.default,
-      setup:   mod.setup ?? null,     // opcional — chamado uma vez na inicialização
+      setup:   mod.setup ?? null,
       exports: mod.api ?? null,
       error:   null,
+      guardOptions: mod.guardOptions ?? {},
     });
 
     logger.info(t("system.pluginLoaded", { name }));
@@ -132,3 +159,19 @@ async function loadPlugin(name) {
     pluginRegistry.set(name, { name, status: "error", run: null, exports: null, error: err });
   }
 }
+
+export async function cleanupPlugins() {
+  for (const plugin of pluginRegistry.values()) {
+    try {
+      await plugin.exports?.events?.cleanup?.();
+
+    } catch (err) {
+      logger.error(
+        t("system.pluginCleanupFailed", {
+          name: plugin.name,
+          message: err.message
+        })
+      );
+    }
+  }
+}