@eryxenx/fca 1.0.9 → 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/loginHelper.js

@@ -1341,7 +1341,8 @@ function loginHelper(appState, Cookie, email, password, globalOptions, callback)
         // sendMessage override with nexca version (better MQTT + HTTP fallback)
         try {
           const nexcaSendMsg = require("../src/api/socket/sendMessage")(defaultFuncs, api, ctxMain);
-          api.sendMessage = nexcaSendMsg;
+          const { wrapSendMessage } = require("../src/utils/outboundRateLimit");
+          api.sendMessage = wrapSendMessage(nexcaSendMsg, ctxMain, config);
           api.sendMessageMqtt = require("../src/api/socket/sendMessageMqtt")(defaultFuncs, api, ctxMain);
           api.OldMessage = require("../src/api/socket/OldMessage")(defaultFuncs, api, ctxMain);
           api.sendMessageDM = (msg, threadID, cb, replyTo) => api.OldMessage(msg, threadID, cb, replyTo, true);

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.0.9",
-  "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
+};

package/src/utils/outboundRateLimit.js

@@ -0,0 +1,284 @@
+"use strict";
+
+const logger = require("./nexca-logger");
+
+/**
+ * Global outbound rate-limit / anti-spam layer for api.sendMessage().
+ *
+ * This module has nothing to do with hiding bot traffic from Facebook
+ * (see antiSuspension.js for that, unrelated / untouched by this file).
+ * Its only job is to stop a single thread/user from being able to make a
+ * bot fire an unbounded burst of outgoing replies, and to stop many busy
+ * threads at once from overwhelming the FCA send path.
+ *
+ * Design:
+ *  - Per-thread sliding window: at most `maxPerWindow` sends per thread
+ *    every `windowMs`. Extra sends for that thread are queued, not sent
+ *    immediately.
+ *  - Global concurrency cap: at most `maxConcurrentSends` sendMessage
+ *    calls in flight at once, across all threads.
+ *  - Bounded queue: at most `maxQueueSize` messages waiting at once. Once
+ *    full, new sends are rejected immediately (never silently grows
+ *    without bound).
+ *  - Queue TTL: a queued message that has been waiting longer than
+ *    `maxQueueWaitMs` is dropped instead of being sent very late.
+ *  - Optional short-window duplicate suppression (off by default).
+ *
+ * This wraps the *existing* sendMessage function — it never re-implements
+ * sending, never retries a failed send, and never changes what happens on
+ * success/failure. It only decides *when* the real sendMessage gets
+ * called, and calls it at most once per accepted message.
+ */
+
+const DEFAULTS = {
+  enabled: true,
+  windowMs: 10000,          // RATE_LIMIT_WINDOW
+  maxPerWindow: 3,          // MAX_MESSAGES_PER_WINDOW (per thread/user)
+  maxQueueSize: 500,        // MAX_QUEUE_SIZE (global)
+  maxConcurrentSends: 5,    // MAX_CONCURRENT_SENDS (global)
+  maxQueueWaitMs: 20000,    // drop a queued message after this long
+  queueTickMs: 300,         // how often to re-check a blocked queue
+  dedupe: {
+    enabled: false,         // opt-in: suppress identical back-to-back text
+    windowMs: 1500
+  }
+};
+
+function buildConfig(ctx, projectConfig) {
+  const fromFile = (projectConfig && projectConfig.rateLimiter) || {};
+  const fromLoginOpts = (ctx && ctx.globalOptions && ctx.globalOptions.rateLimiter) || {};
+
+  const merged = Object.assign({}, DEFAULTS, fromFile, fromLoginOpts);
+  merged.dedupe = Object.assign({}, DEFAULTS.dedupe, fromFile.dedupe, fromLoginOpts.dedupe);
+
+  // Same opt-out convention already used for antiBan in sendMessage.js:
+  // globalOptions.outboundRateLimit === false disables this layer entirely.
+  if (ctx && ctx.globalOptions && ctx.globalOptions.outboundRateLimit === false) {
+    merged.enabled = false;
+  }
+  return merged;
+}
+
+function normalizeDedupeBody(msg) {
+  // Only dedupe plain text sends. Attachments/stickers/locations etc. are
+  // left alone since "identical" is much less meaningful for them and the
+  // risk of dropping something the bot actually meant to (re)send is higher.
+  if (typeof msg === "string") return msg;
+  if (msg && typeof msg === "object" && !msg.attachment && typeof msg.body === "string") {
+    return msg.body;
+  }
+  return null;
+}
+
+class OutboundRateLimiter {
+  constructor(originalSendMessage, config) {
+    this.originalSendMessage = originalSendMessage;
+    this.config = config;
+
+    this.perThread = new Map();   // threadKey -> [timestamps]
+    this.dedupeCache = new Map(); // threadKey -> { body, at }
+    this.queue = [];              // [{ msg, threadID, replyToMessage, isSingleUser, key, settle, enqueuedAt }]
+    this.activeSends = 0;
+    this._processing = false;
+    this._retryTimer = null;
+
+    this._gcTimer = setInterval(() => this._gc(), 60000);
+    if (this._gcTimer.unref) this._gcTimer.unref();
+  }
+
+  destroy() {
+    if (this._gcTimer) clearInterval(this._gcTimer);
+    if (this._retryTimer) clearTimeout(this._retryTimer);
+  }
+
+  getStats() {
+    return {
+      queued: this.queue.length,
+      activeSends: this.activeSends,
+      trackedThreads: this.perThread.size
+    };
+  }
+
+  _gc() {
+    const now = Date.now();
+    for (const [key, timestamps] of this.perThread) {
+      while (timestamps.length && timestamps[0] <= now - this.config.windowMs) timestamps.shift();
+      if (!timestamps.length) this.perThread.delete(key);
+    }
+    for (const [key, entry] of this.dedupeCache) {
+      if (now - entry.at > this.config.dedupe.windowMs) this.dedupeCache.delete(key);
+    }
+  }
+
+  _isRateLimited(key) {
+    const timestamps = this.perThread.get(key);
+    if (!timestamps || !timestamps.length) return false;
+    const cutoff = Date.now() - this.config.windowMs;
+    while (timestamps.length && timestamps[0] <= cutoff) timestamps.shift();
+    return timestamps.length >= this.config.maxPerWindow;
+  }
+
+  _recordSend(key) {
+    let timestamps = this.perThread.get(key);
+    if (!timestamps) {
+      timestamps = [];
+      this.perThread.set(key, timestamps);
+    }
+    timestamps.push(Date.now());
+  }
+
+  _isDuplicate(key, msg) {
+    if (!this.config.dedupe.enabled) return false;
+    const body = normalizeDedupeBody(msg);
+    if (body === null) return false;
+    const last = this.dedupeCache.get(key);
+    const now = Date.now();
+    if (last && last.body === body && (now - last.at) < this.config.dedupe.windowMs) {
+      return true;
+    }
+    this.dedupeCache.set(key, { body, at: now });
+    return false;
+  }
+
+  _sweepExpired() {
+    const now = Date.now();
+    for (let i = this.queue.length - 1; i >= 0; i--) {
+      const job = this.queue[i];
+      if (now - job.enqueuedAt > this.config.maxQueueWaitMs) {
+        this.queue.splice(i, 1);
+        job.settle({ error: "sendMessage: queued message expired before it could be sent (rate-limit backlog)" });
+      }
+    }
+  }
+
+  _processQueue() {
+    if (this._processing) return;
+    this._processing = true;
+    try {
+      this._sweepExpired();
+      let i = 0;
+      while (i < this.queue.length && this.activeSends < this.config.maxConcurrentSends) {
+        const job = this.queue[i];
+        if (this._isRateLimited(job.key)) {
+          i++;
+          continue;
+        }
+        this.queue.splice(i, 1);
+        this._dispatch(job);
+      }
+    } finally {
+      this._processing = false;
+    }
+
+    if (this._retryTimer) return;
+    if (!this.queue.length) return;
+    this._retryTimer = setTimeout(() => {
+      this._retryTimer = null;
+      this._processQueue();
+    }, this.config.queueTickMs);
+    if (this._retryTimer.unref) this._retryTimer.unref();
+  }
+
+  _callOriginal(job) {
+    const original = this.originalSendMessage;
+    return new Promise((resolve, reject) => {
+      try {
+        original(job.msg, job.threadID, (err, result) => {
+          if (err) reject(err); else resolve(result);
+        }, job.replyToMessage, job.isSingleUser);
+      } catch (syncErr) {
+        reject(syncErr);
+      }
+    });
+  }
+
+  async _dispatch(job) {
+    this.activeSends++;
+    this._recordSend(job.key);
+    try {
+      const result = await this._callOriginal(job);
+      job.settle(null, result);
+    } catch (err) {
+      // No automatic retry here on purpose — a failed send stays failed,
+      // exactly like calling the un-wrapped sendMessage would behave.
+      job.settle(err);
+    } finally {
+      this.activeSends--;
+      this._processQueue();
+    }
+  }
+
+  send(msg, threadID, callback, replyToMessage, isSingleUser) {
+    if (typeof callback !== "function") callback = null;
+
+    let resolveOuter, rejectOuter;
+    const outerPromise = new Promise((res, rej) => {
+      resolveOuter = res;
+      rejectOuter = rej;
+    });
+
+    let settled = false;
+    const settle = (err, result) => {
+      if (settled) return;
+      settled = true;
+      if (callback) {
+        try {
+          callback(err || null, result);
+        } catch (cbErr) {
+          logger.warn("RateLimiter", "sendMessage callback threw: " + (cbErr && cbErr.message ? cbErr.message : cbErr));
+        }
+      }
+      if (err) rejectOuter(err); else resolveOuter(result);
+    };
+
+    const key = threadID === undefined || threadID === null ? "unknown" : String(threadID);
+
+    if (this._isDuplicate(key, msg)) {
+      settle(null, { skipped: true, reason: "duplicate" });
+      return outerPromise;
+    }
+
+    if (this.queue.length >= this.config.maxQueueSize) {
+      settle({ error: "sendMessage: outbound queue is full, message dropped" });
+      return outerPromise;
+    }
+
+    this.queue.push({
+      msg,
+      threadID,
+      replyToMessage,
+      isSingleUser,
+      key,
+      settle,
+      enqueuedAt: Date.now()
+    });
+    this._processQueue();
+
+    return outerPromise;
+  }
+}
+
+/**
+ * Wraps an existing sendMessage(msg, threadID, callback, replyToMessage,
+ * isSingleUser) function with the rate-limit/queue layer above. Same
+ * signature in, same signature out — callers (GoatBot command files, etc.)
+ * cannot tell the difference except for pacing under burst load.
+ */
+function wrapSendMessage(originalSendMessage, ctx, projectConfig) {
+  const config = buildConfig(ctx, projectConfig);
+  if (!config.enabled) return originalSendMessage;
+
+  const limiter = new OutboundRateLimiter(originalSendMessage, config);
+
+  const wrapped = function sendMessage(msg, threadID, callback, replyToMessage, isSingleUser) {
+    return limiter.send(msg, threadID, callback, replyToMessage, isSingleUser);
+  };
+
+  wrapped.getRateLimiterStats = () => limiter.getStats();
+  wrapped._rateLimiterConfig = config;
+  wrapped._rateLimiterInstance = limiter;
+
+  return wrapped;
+}
+
+module.exports = { wrapSendMessage, OutboundRateLimiter, DEFAULTS };