@eryxenx/fca 1.1.0 → 1.1.1

package/README.md

@@ -420,6 +420,109 @@ api.uploadImageToImgbb(imageUrl);
 
 ---
 
+## 🛡️ Command Anti-Spam (Humanizer)
+
+Nobody — not even the bot owner — can spam the bot with commands. This makes
+the account behave like a human operator, which reduces the chance of
+Facebook flagging it as a script and logging it out / suspending it.
+
+On by default. It works on **every incoming command** (and every incoming
+message that starts with a command prefix):
+
+- **Human reaction delay** — an accepted command is only delivered to your
+  listener after a short random delay (default `2–3s`), so the bot replies
+  like a human typing, never instantly like a script.
+- **Spam window** — after a command is accepted in a conversation, any further
+  commands in that conversation within `cooldownMs` (default `5.5s`) are
+  **silently ignored**. `help help help help` → exactly **one** reply.
+- **Idle reset** — after `resetMs` (default `10s`) with no commands in a
+  conversation, the state resets and the next command starts fresh.
+- **Global cap** — at most `maxPerMinute` commands are accepted per minute
+  across all conversations (default `20`).
+
+Non-command messages always pass through instantly, untouched.
+
+### How to use
+
+It's already active after `login()`. No code needed:
+
+```javascript
+const login = require("@eryxenx/fca");
+
+login({ appState }, {}, (err, api) => {
+  if (err) throw err;
+
+  api.listenMqtt((err, event) => {
+    if (err) throw err;
+    // Commands arrive here already delayed by 2-3s, and spam bursts are gone.
+    if (event.body === "/help") api.sendMessage("help text", event.threadID);
+  });
+});
+```
+
+### Configuration
+
+Pass a `humanize` object to `login()`, or call `api.setOptions({ humanize })`
+at runtime:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Master switch |
+| `reactDelayMs` | `[min, max]` | `[2000, 3000]` | Random delay before an accepted command is delivered |
+| `cooldownMs` | number | `5500` | Spam window per conversation (seconds between commands) |
+| `resetMs` | number | `10000` | Idle time after which a conversation resets |
+| `maxPerMinute` | number | `20` | Global command cap per minute (0 = unlimited) |
+| `commands` | string[] | `["/", "!", "."]` | Prefixes that mark a message as a command |
+| `perThread` | boolean | `true` | Cooldown per conversation (false = global) |
+
+```javascript
+const login = require("@eryxenx/fca");
+
+login({ appState }, {
+  humanize: {
+    reactDelayMs: [2500, 4000],
+    cooldownMs: 6000,
+    resetMs: 12000,
+    maxPerMinute: 15,
+    commands: ["/"]
+  }
+}, (err, api) => { /* ... */ });
+```
+
+To turn it off completely:
+
+```javascript
+// option A: at login
+login({ appState }, { humanize: { enabled: false } }, cb);
+// option B: at runtime
+api.setOptions({ humanize: { enabled: false } });
+```
+
+### Programmatic access
+
+The humanizer is a normal class, also exported from the package:
+
+```javascript
+const { CommandHumanizer, createCommandHumanizer } = require("@eryxenx/fca");
+
+const h = new CommandHumanizer({ reactDelayMs: [2000, 3000] });
+const d = h.shouldProcess({ body: "/help", threadID: "t1" });
+// d.ok === true, d.delayMs in [2000, 3000]
+```
+
+At runtime, `api.getHumanizer()` returns the active instance so you can
+inspect statistics or reset a conversation:
+
+```javascript
+const h = api.getHumanizer();
+console.log(h.stats());      // accepted / dropped counts
+h.reset("381234567890");     // clear the state for one thread
+```
+
+> Note: this operates on **incoming** command volume. Outgoing send pacing
+> (the `globalAntiSuspension` pacer in `src/utils/antiSuspension.js`) is a
+> separate, complementary mechanism that spaces out actual `sendMessage` calls.
+
 ## 📋 Login Options
 
 | Option | Type | Default | Description |
@@ -435,6 +538,7 @@ api.uploadImageToImgbb(imageUrl);
 | `emitReady` | boolean | false | Emit ready event when MQTT connected |
 | `proxy` | string | — | HTTP proxy URL |
 | `userAgent` | string | Safari UA | Override HTTP User-Agent |
+| `humanize` | object | enabled | Command anti-spam config (see above) |
 
 ---
 

package/index.js

@@ -5,6 +5,7 @@ const { createFcaClient } = require("./src/app/createFcaClient");
 const { MessengerBot, createMessengerBot } = require("./src/app/MessengerBot");
 const { MessengerContext } = require("./src/app/MessengerContext");
 const { attachThreadInfoRealtimeSync, applyThreadInfoRealtimeEvent } = require("./src/app/threadInfoRealtimeSync");
+const humanizer = require("./src/utils/humanizer");
 
 // CommonJS default export — the login function (classic FCA / GoatBot compatible)
 module.exports = login;
@@ -20,3 +21,9 @@ module.exports.createMessengerBot = createMessengerBot;
 module.exports.MessengerContext = MessengerContext;
 module.exports.attachThreadInfoRealtimeSync = attachThreadInfoRealtimeSync;
 module.exports.applyThreadInfoRealtimeEvent = applyThreadInfoRealtimeEvent;
+
+// Command anti-spam / humanizer
+module.exports.CommandHumanizer = humanizer.CommandHumanizer;
+module.exports.createCommandHumanizer = humanizer.createCommandHumanizer;
+module.exports.createHumanizerMiddleware = humanizer.createHumanizerMiddleware;
+module.exports.humanizer = humanizer;

package/module/login.js

@@ -98,8 +98,12 @@ function login(loginData, options, callback) {
     autoReconnect: true,
     online: true,
     emitReady: false,
-    userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36"
+    userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
+    humanize: undefined
   };
+  if (options && options.humanize !== undefined) {
+    globalOptions.humanize = options.humanize;
+  }
   setOptions(globalOptions, options);
   let prCallback = null;
   let rejectFunc = null;

package/module/options.js

@@ -34,6 +34,10 @@ function setOptions(globalOptions, options) {
         }
         break;
       }
+      case "humanize": {
+        globalOptions.humanize = options.humanize;
+        break;
+      }
       default: {
         logger("setOptions Unrecognized option given to setOptions: " + key, "warn");
         break;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@eryxenx/fca",
-  "version": "1.1.0",
-  "description": "Facebook Chat API by EryXenX | Stable • Auto Re-login • Full E2EE Support — send messages, media, reactions & more in encrypted chats, hassle-free",
+  "version": "1.1.1",
+  "description": "Facebook Chat API by EryXenX | Stable • Auto Re-login • Full E2EE Support — with Command Anti-Spam (Humanizer)",
   "main": "index.js",
   "types": "index.d.ts",
   "exports": {

package/src/api/socket/listenE2EE.js

@@ -2,6 +2,7 @@
 
 var logger = require("../../utils/nexca-logger");
 var EventEmitter = require("events");
+var { createHumanizerMiddleware } = require("../../utils/humanizer");
 
 /**
  * listenE2EE — merges E2EE messages into the same event stream as MQTT.
@@ -64,6 +65,22 @@ module.exports = function (defaultFuncs, api, ctx) {
                 if (!ctx.globalOptions.selfListen && event.senderID === ctx.userID) return;
 
                 event.isE2EE = true;
+
+                // Run E2EE events through the same middleware pipeline as
+                // MQTT events so command anti-spam also applies here.
+                if (ctx._middleware && ctx._middleware.count > 0) {
+                    // Ensure the humanizer middleware is present for E2EE too.
+                    if (ctx._humanizer && !ctx._humanizerMiddlewareInstalled) {
+                        ctx._middleware.use("humanizer", createHumanizerMiddleware(ctx._humanizer, logger));
+                        ctx._humanizerMiddlewareInstalled = true;
+                    }
+                    return ctx._middleware.process(event, (err2, processed) => {
+                        if (err2) { logger.error("listenE2EE", "Middleware error: " + (err2 && err2.message ? err2.message : String(err2))); return; }
+                        if (!processed) return; // dropped by middleware
+                        globalCallback(null, processed);
+                    });
+                }
+
                 globalCallback(null, event);
             });
 

package/src/api/socket/listenMqtt.js

@@ -17,6 +17,7 @@ const createGetSeqID = require("./core/getSeqID");
 const getTaskResponseData = require("./core/getTaskResponseData");
 const createEmitAuth = require("./core/emitAuth");
 const createMiddlewareSystem = require("./middleware");
+const { createCommandHumanizer, createHumanizerMiddleware } = require("../../utils/humanizer");
 
 // Auto-cycle is OFF by default now: a real browser keeps one MQTT socket
 // open for hours. Cycling every exactly-3600.000s (full unsubscribe,
@@ -50,6 +51,18 @@ module.exports = function (defaultFuncs, api, ctx, opts) {
   }
   const middleware = ctx._middleware;
 
+  function installHumanizerMiddleware() {
+    if (ctx._humanizerMiddlewareInstalled) return;
+    ctx._humanizerMiddlewareInstalled = true;
+
+    if (!ctx._humanizer) {
+      ctx._humanizer = createCommandHumanizer(ctx.globalOptions.humanize);
+    }
+
+    middleware.use("humanizer", createHumanizerMiddleware(ctx._humanizer, logger));
+    logger("Humanizer middleware installed (command anti-spam active)", "info");
+  }
+
   function installPostGuard() {
     if (ctx._postGuarded) return defaultFuncs.post;
     const rawPost = defaultFuncs.post && defaultFuncs.post.bind(defaultFuncs);
@@ -349,6 +362,25 @@ module.exports = function (defaultFuncs, api, ctx, opts) {
 
     const msgEmitter = new MessageEmitter();
 
+    // Command anti-spam. Enabled by default so that nobody (the owner or
+    // anyone else) can spam the bot with commands — which also protects the
+    // account from looking automated to Facebook. Opt out via
+    // api.setOptions({ humanize: { enabled: false } }) or pass
+    // { humanize: { enabled: false } } to login().
+    const humanizeEnabled = ctx.globalOptions.humanize === undefined ||
+      (ctx.globalOptions.humanize && ctx.globalOptions.humanize.enabled !== false);
+
+    if (humanizeEnabled) {
+      try {
+        installHumanizerMiddleware();
+      } catch (e) {
+        logger(`Humanizer middleware install failed (non-fatal): ${e && e.message ? e.message : String(e)}`, "warn");
+      }
+    }
+
+    // Expose the humanizer for diagnostics / runtime reconfiguration.
+    api.getHumanizer = () => ctx._humanizer || null;
+
     // Original callback without middleware
     const originalCallback = callback || function (error, message) {
       if (error) { logger("mqtt emit error", "error"); return msgEmitter.emit("error", error); }

package/src/utils/humanizer.js

@@ -0,0 +1,199 @@
+"use strict";
+
+/**
+ * CommandHumanizer — makes a bot behave like a human when it receives
+ * commands so that neither the owner nor anyone else can spam the bot.
+ * This keeps the account from looking like a script to Facebook.
+ *
+ * Behavior (all tunable via options):
+ *  1. Human reaction delay — an accepted command is only forwarded to the
+ *     bot handler after a short random delay (default 2-3 seconds), so the
+ *     reply never fires instantly like a script.
+ *  2. Spam window — once a command in a conversation is accepted, any
+ *     further command in that same conversation within `cooldownMs`
+ *     (default 5.5s) is IGNORED. A burst such as "help help help help"
+ *     therefore gets exactly one reply.
+ *  3. Idle reset — after `resetMs` (default 10s) with no commands in a
+ *     conversation, the state resets and the next command is treated as a
+ *     fresh one.
+ *  4. Global cap — at most `maxPerMinute` commands are accepted per minute
+ *     across all conversations; anything past the cap is ignored.
+ *
+ * Non-command messages (no command prefix) always pass through untouched.
+ */
+
+const DEFAULT_OPTIONS = Object.freeze({
+  enabled: true,
+  reactDelayMs: [2000, 3000],
+  cooldownMs: 5500,
+  resetMs: 10000,
+  maxPerMinute: 20,
+  commands: ["/", "!", "."],
+  perThread: true
+});
+
+function isCommandLike(body, prefixes) {
+  if (typeof body !== "string") return false;
+  const text = body.trim();
+  if (!text || !Array.isArray(prefixes) || !prefixes.length) return false;
+  return prefixes.some(p => typeof p === "string" && p.length > 0 && text.startsWith(p));
+}
+
+function randomBetween(min, max) {
+  if (Array.isArray(min)) {
+    const pair = min;
+    min = pair[0];
+    max = pair[1];
+  }
+  min = Number(min) || 0;
+  max = Number(max) || min;
+  if (max < min) { const t = min; min = max; max = t; }
+  return min + Math.floor(Math.random() * (max - min + 1));
+}
+
+class CommandHumanizer {
+  constructor(options) {
+    this.setOptions(options);
+    this._threads = new Map(); // key -> state
+    this._global = { windowStart: 0, count: 0, accepted: 0, dropped: 0 };
+    this._eventCount = 0;
+  }
+
+  setOptions(options) {
+    const o = options || {};
+    this.enabled = o.enabled !== false;
+    this.reactDelayMs = o.reactDelayMs || DEFAULT_OPTIONS.reactDelayMs;
+    this.cooldownMs = typeof o.cooldownMs === "number" ? o.cooldownMs : DEFAULT_OPTIONS.cooldownMs;
+    this.resetMs = typeof o.resetMs === "number" ? o.resetMs : DEFAULT_OPTIONS.resetMs;
+    this.maxPerMinute = typeof o.maxPerMinute === "number" ? o.maxPerMinute : DEFAULT_OPTIONS.maxPerMinute;
+    this.prefixes = o.commands || o.prefixes || DEFAULT_OPTIONS.commands;
+    this.perThread = o.perThread !== false;
+  }
+
+  isCommand(event) {
+    return Boolean(event && isCommandLike(event.body, this.prefixes));
+  }
+
+  _keyFor(event) {
+    return this.perThread && event.threadID ? String(event.threadID) : "_global";
+  }
+
+  _globalAllowed() {
+    const now = Date.now();
+    if (now - this._global.windowStart >= 60000) {
+      this._global.windowStart = now;
+      this._global.count = 0;
+    }
+    if (this._global.count >= this.maxPerMinute) return false;
+    this._global.count++;
+    return true;
+  }
+
+  /**
+   * Decide what to do with a command event, based purely on arrival time
+   * (the emission delay is applied separately by the middleware).
+   *
+   * @returns {{ok: boolean, delayMs: number, reason?: string}}
+   */
+  shouldProcess(event) {
+    this._eventCount++;
+    if (!this.enabled) return { ok: true, delayMs: 0 };
+
+    const key = this._keyFor(event);
+    const now = Date.now();
+
+    let st = this._threads.get(key);
+    if (!st) {
+      st = { acceptedAt: 0, coolUntil: 0, lastCmdAt: 0, accepted: 0, dropped: 0 };
+      this._threads.set(key, st);
+    }
+
+    // Idle reset: no command in this conversation for resetMs -> the next
+    // command starts a fresh window instead of inheriting the old cooldown.
+    if (st.lastCmdAt > 0 && (now - st.lastCmdAt >= this.resetMs)) {
+      st.acceptedAt = 0;
+      st.coolUntil = 0;
+    }
+    st.lastCmdAt = now;
+
+    if (st.coolUntil > 0 && now < st.coolUntil) {
+      st.dropped++;
+      this._global.dropped++;
+      return { ok: false, delayMs: 0, reason: "cooldown" };
+    }
+
+    if (this.maxPerMinute > 0 && !this._globalAllowed()) {
+      st.dropped++;
+      this._global.dropped++;
+      return { ok: false, delayMs: 0, reason: "global-cap" };
+    }
+
+    st.acceptedAt = now;
+    st.coolUntil = now + this.cooldownMs;
+    st.accepted++;
+    this._global.accepted++;
+    return { ok: true, delayMs: randomBetween(this.reactDelayMs) };
+  }
+
+  reset(key) {
+    if (key === undefined) { this._threads.clear(); return; }
+    this._threads.delete(String(key));
+  }
+
+  stats() {
+    const threads = [];
+    this._threads.forEach((st, k) => threads.push({ threadID: k, ...st }));
+    return {
+      enabled: this.enabled,
+      global: { ...this._global },
+      eventCount: this._eventCount,
+      threads
+    };
+  }
+}
+
+function createCommandHumanizer(options) {
+  return new CommandHumanizer(options);
+}
+
+/**
+ * Middleware for the FCA middleware system (api.useMiddleware).
+ * - Non-commands: forwarded immediately.
+ * - Dropped commands: next(false) so the bot never sees them.
+ * - Accepted commands: forwarded after the human reaction delay.
+ */
+function createHumanizerMiddleware(humanizer, logger) {
+  const log = typeof logger === "function"
+    ? (msg, level) => logger(msg, level || "info")
+    : () => {};
+
+  return function commandHumanizerMiddleware(event, next) {
+    if (!humanizer.isCommand(event)) { next(); return; }
+
+    const decision = humanizer.shouldProcess(event);
+
+    if (!decision.ok) {
+      const snippet = typeof event.body === "string" ? event.body.slice(0, 40) : String(event.body || "");
+      log(`Humanizer: dropped command "${snippet}" (${decision.reason})`, "warn");
+      next(false); // stop processing, do not emit
+      return;
+    }
+
+    const delay = Math.max(0, decision.delayMs || 0);
+    if (delay <= 0) { next(); return; }
+
+    // Forward the event after a human-like delay. setTimeout is used
+    // (instead of an async function) because this middleware system calls
+    // next() itself; returning a promise would make it call next() twice.
+    setTimeout(() => next(), delay);
+  };
+}
+
+module.exports = {
+  CommandHumanizer,
+  createCommandHumanizer,
+  createHumanizerMiddleware,
+  randomBetween,
+  isCommandLike,
+  DEFAULT_OPTIONS
+};