hridoy-ultimate 9.0.0 → 9.0.2

package/README.md

@@ -1,179 +1,554 @@
-# hridoy-ultimate
+<div align="center">
 
-**Version 9.0.0 - Owner/maintainer: HR ID OY**
+# 💬 hridoy-ultimate
 
-An unofficial Facebook Chat API (FCA) for Node.js Messenger bots, unified from the
-`@eryxenx/fca` 1.0.0 - 1.1.9 and `fca-eryxenx` 1.x - 39.x lineages (83 published builds
-analysed, see `MERGE_REPORT.md`; itself derived from fca-unofficial) with a hardened
-MQTT lifecycle: bounded exponential backoff, a reconnect budget, clean shutdown and no
-timer left behind after `stopListening()` / `logout()`.
+**Unofficial Facebook Messenger Bot API for Node.js**
+NEXCA MQTT · Signal Protocol E2EE (mautrix-go powered) · sessionGuard · 90+ API Methods · Zero TypeScript
 
-> **Unofficial.** This automates a personal Facebook account and may violate Facebook's
-> terms. Accounts can be restricted. Use a throwaway account, never one you can't lose.
+[![npm](https://img.shields.io/npm/v/hridoy-ultimate?color=blue)](https://www.npmjs.com/package/hridoy-ultimate)
+[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE-MIT)
+[![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
-## Verification status (read this first)
-| Area | Status |
-|---|---|
-| Unit tests (backoff, scheduler, parsers, humanizer, typing indicator, fingerprint) | **PASS** (real code, no mocks) |
-| MQTT lifecycle, logout, typing wiring, package surface (incl. pinned binary hashes) | **PASS - MOCKED** (fake mqtt/axios; see `test/helpers/stub-modules.js`) |
-| TypeScript typings | **PASS** with `tsc` against a consumer sample (Node types stubbed) |
-| Live Facebook login / MQTT / sending / reactions / attachments | **NOT TESTED** (no network or account in the build environment) |
-| E2EE (encrypted chats) and the bundled native binaries | **NOT TESTED** - needs optional deps and a live account |
-| `npm install` from a clean registry | **NOT TESTED** (build sandbox was offline) |
+[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [E2EE](#-e2ee--encrypted-conversations) • [sessionGuard](#-sessionguard) • [sendBroadcast](#-sendbroadcast) • [API Reference](#-api-reference)
+
+</div>
+
+---
+
+## ⚡ Why hridoy-ultimate?
+
+- ✅ **NEXCA MQTT** — stable connection core, autoReconnect, jitter
+- ✅ **Signal Protocol E2EE** — Facebook real encrypted conversations support. Reliable media/reaction/unsend delivery is powered by a bundled **mautrix-go / mautrix-meta** native engine (© Tulir Asokan, MPL-2.0) — NEXCA's own hand-written E2EE encoder produced protocol-valid messages that Facebook accepted but Messenger clients failed to render for attachments/reactions/unsend, so this fork routes those through the native engine instead. Text messaging still uses the original engine (already reliable). The native engine is opt-in (`FCA_E2EE_NATIVE=1`) — see [Native media engine](#native-media-engine).
+- ✅ **sessionGuard** — appstate corruption and silent logout protection, auto-backup
+- ✅ **sendBroadcast** — rate-limited multi-thread broadcast
+- ✅ **Fixed MQTT subscribe race condition** — no more "Connection refused: No subscription existed"
+- ✅ **`isActiveClient()` guard** — stale MQTT client events no longer processed
+- ✅ **`connectTimeout` extended** — no premature logout on slow networks
+- ✅ **autoReconnect** — auto-reconnect on connection drop
+- ✅ **GoatBot compatible** — all API signatures unchanged (`threadID` optional etc.)
+- ✅ **90+ API methods** — sendMessage, editMessage, setMessageReaction, getThreadInfo and more
+
+---
 
-Full results: `docs/TEST_RESULTS.md`. Honest limits: [Known limitations](#known-limitations).
+## ✨ Features
+
+- ✅ Full Messenger API — messages, reactions, attachments, stickers, polls, pins
+- ✅ NEXCA MQTT — stable connection, autoReconnect, jitter, isActiveClient guard
+- ✅ E2EE — Signal Protocol encrypted threads, auto-connects after login (listenE2EE, e2ee.*)
+- ✅ E2EE media engine — native mautrix-go engine (opt-in via `FCA_E2EE_NATIVE=1`) for reliable image/video/audio/document sending, reactions, and unsend in encrypted threads (falls back to the built-in JS engine automatically)
+- ✅ E2EE incoming media — attachments on encrypted messages (including replies) are auto-decrypted and served locally, so existing commands work unmodified
+- ✅ sessionGuard — appstate auto-save, corruption guard, .bak backup
+- ✅ Command anti-spam humanizer — human-like reply delay, per-thread cooldown, GoatBot no-prefix/onChat/onReply auto-detection
+- ✅ sendBroadcast — parallel/sequential multi-thread sending with rate limit
+- ✅ MessengerBot — Discord.js/Telegraf style (.command, .hears, .launch)
+- ✅ createFcaClient — namespaced facade (client.messages, client.threads etc.)
+- ✅ GoatBot / Mirai compatible — drop-in replacement
+
+---
+
+## 📦 Installation
 
-## Install
-Requires Node.js >= 18.
 ```bash
-npm install hridoy-ultimate            # from a registry, or:
-npm install ./hridoy-ultimate-9.0.0.tgz
+npm install hridoy-ultimate
 ```
-`sqlite3` compiles/downloads a native module; E2EE-related packages are optional.
 
-## Quick start
-```js
-const login = require("hridoy-ultimate");           // also: require(...).login, .default
-const fs = require("fs");
+Node.js >= 20 required.
 
-const appState = JSON.parse(fs.readFileSync("appstate.json", "utf8")); // keep this file secret
+The E2EE media engine ships a precompiled native binary (`src/api/socket/e2ee/native/build/`) for **Linux (.so)** and **Windows (.dll)**, loaded via the `koffi` FFI. `npm install` pulls in `koffi` and `yumi-json-bigint` automatically — no extra setup needed. Note the native engine only runs when `FCA_E2EE_NATIVE=1` is set (see [Native media engine](#native-media-engine)); on platforms other than Linux/Windows x64 (e.g. macOS, ARM) the binary fails to load and E2EE media/reactions/unsend automatically fall back to the built-in JS engine (text messaging is unaffected either way).
 
-login({ appState }, { listenEvents: true, autoReconnect: true }, (err, api) => {
-  if (err) return console.error("login failed:", err.error || err.message || err);
+The E2EE socket's User-Agent defaults to desktop Windows Chrome 139 to match the rest of the client; override with `FCA_E2EE_UA` if you run with a different UA.
 
-  const stop = api.listenMqtt((err, event) => {
-    if (err) {
-      if (err.type === "stop_listen") return console.error("listener gave up:", err.error);
-      return console.error(err);
-    }
-    if (event.type === "message" && event.body === "ping") {
-      api.sendMessage("pong", event.threadID, undefined, event.messageID);
-      api.setMessageReaction("👍", event.messageID, event.threadID, () => {}, true);
+---
+
+## 🚀 Quick Start
+
+### Classic (GoatBot compatible)
+
+```javascript
+const login = require("hridoy-ultimate");
+
+login({ appState: require("./account.json") }, { listenEvents: true }, (err, api) => {
+  if (err) throw err;
+
+  api.sessionGuard("./account.json", {
+    interval: 3 * 60 * 1000,
+    debounce: 30 * 1000
+  });
+
+  api.listenMqtt((err, event) => {
+    if (err) throw err;
+    if (event.type === "message") api.sendMessage(event.body, event.threadID);
+  });
+});
+```
+
+### With E2EE (regular + encrypted threads)
+
+`connectE2EE()` runs **automatically** right after login — you never call it yourself. Calling it again in your own code opens a second, racing connection on the same bridge. Just check `api.e2ee.isConnected()` if you need to know the status.
+
+```javascript
+login({ appState: require("./account.json") }, { listenEvents: true }, (err, api) => {
+  if (err) throw err;
+
+  api.sessionGuard("./account.json");
+  // E2EE is already connecting in the background here — do not call connectE2EE().
+
+  api.listenE2EE((err, event) => {
+    if (err) throw err;
+    if (event.type === "message") {
+      if (event.isE2EE) {
+        api.e2ee.sendMessage(event.threadID, "Got your encrypted message!");
+      } else {
+        api.sendMessage("Got it!", event.threadID);
+      }
     }
-  }, { maxReconnectAttempts: 10 });
+  });
+});
+```
+
+### GoatBot login.js
+
+```javascript
+const login = require("hridoy-ultimate");
+
+login({ appState }, options, (err, api) => {
+  if (err) return;
 
-  process.on("SIGINT", async () => {
-    stop.stopListening(async () => { await api.logout(); process.exit(0); });
+  api.sessionGuard(path.join(process.cwd(), "account.txt"), {
+    interval: 3 * 60 * 1000,
+    debounce: 30 * 1000
   });
+
+  // Nothing else needed for E2EE — it auto-connects inside hridoy-ultimate
+  // right after login. Do NOT call api.connectE2EE() here.
+
+  api.listenMqtt(callback);
 });
 ```
-(Argument orders (`sendMessage(msg, threadID, callback, replyToMessageID)`,
-`setMessageReaction(reaction, messageID, threadID, callback, force)`) were read from the source; see
-`docs/UPSTREAM_API_DOCS.md` and `index.d.ts`. These calls are **NOT TESTED live**.)
-
-## Authentication and session security
-- Prefer **appState/cookie login**. Never commit `appstate.json`, cookies or tokens.
-- Credential (email/password/2FA) login goes through a **third-party HTTP API that you must
-  configure** (`apiServer` in `fca-config.json`). It is empty by default because those
-  secrets would be sent to that host. Only point it at a server you control.
-- Log lines mention cookie *counts*, but I did not audit every log call; treat console output as sensitive.
-- `api.getAppState()` output equals full account access.
-
-## Options
-Login options (`setOptions`): `online`, `selfListen`, `listenEvents`, `updatePresence`,
-`forceLogin`, `autoMarkRead`, `listenTyping`, `autoReconnect`, `emitReady`,
-`selfListenEvent`, `userAgent`, `proxy`, `humanize`, `typingIndicator`.
-
-`api.listenMqtt(callback, options)` options (all optional):
-| option | default | meaning |
-|---|---|---|
-| `autoReconnect` | `true` | reconnect after socket loss |
-| `reconnectDelayMs` | 2000 | first backoff delay (doubles each attempt) |
-| `maxReconnectDelayMs` | 300000 | backoff ceiling |
-| `reconnectJitter` | 0.3 | +/- fraction randomised |
-| `maxReconnectAttempts` | 10 | `0` = unlimited (explicit opt-in); on exhaustion you get `{type:"stop_listen"}` |
-| `tmsWaitTimeoutMs` | 8000 | wait for first sync response before cycling |
-| `connectTimeoutMs` | 12000 | MQTT connect timeout |
-| `cycleMs` | 0 | periodic forced reconnect (off) |
-| `reconnectAfterStop` | `false` | restart after `stopListening` |
-
-The attempt counter resets after the first healthy sync response.
-
-## Events and MQTT recovery
-- `callback(err, event)`; events include `message`, `message_reply`, `message_edit`,
-  `message_reaction`, `message_unsend`, `event`, `typ`, `presence`, `share`,
-  `friend_request_received`, `friend_request_cancel` (type strings found in the source parsers;
-  per-type shapes are in the upstream docs; none exercised live).
-- Control events arrive as `err` objects: `{type:"ready"}`, `{type:"account_inactive"}`
-  (session lost; everything is stopped), `{type:"stop_listen"}` (retry budget exhausted or stopped).
-- Recovery: socket close/error -> backoff reconnect (reuses sync token) -> on repeated
-  failure refresh session/dtsg -> give up with `stop_listen`. Stale clients are ignored.
-- Shutdown: `stopListening(cb)` cancels all timers, ends the client, is idempotent.
-  `logout()` additionally disconnects E2EE and clears the dtsg refresh timer.
-
-## Typing indicator (default ON)
-Shows "typing..." in a thread the moment a command-like message arrives (GoatBot prefix,
-`/`, `!`, `.`) and clears it when your reply is sent, or after a safety timeout (8 s). It
-adds **no latency**: the event is delivered first, the typing signal is fire-and-forget. Works
-for normal and E2EE threads.
-
-```js
-login(cookie, { typingIndicator: false });                    // off
-login(cookie, { typingIndicator: { onlyCommands: false } });  // type for every text message
-login(cookie, { typingIndicator: { commands: ["#"], maxMs: 6000, groups: true, dms: true } });
-
-api.setTypingIndicator(false);                    // switch at runtime
-await api.withTyping(threadID, async () => { /* slow work */ });   // typing while fn runs
-api.sendTypingIndicator(threadID, true, { duration: 5000 });       // manual control
-```
-A GoatBot `config.enableTypingIndicator: false` also disables it unless you pass the option
-explicitly. When `humanize` is enabled the humanizer shows typing itself and this one stays out of the way.
-
-## Opt-in features
-- **Humanizer** (`humanize: true`): delays command replies 2-3 s and *drops* commands inside a
-  5.5 s cooldown. Drops are intentional and counted; it is off by default. It contains
-  special handling for GoatBot globals.
-- **Native E2EE engine** (group E2EE receive/send and E2EE media): the `messagix` binaries are
-  bundled in `src/api/socket/e2ee/native/build/` (x86-64 `.so` / `.dll`, SHA-256 pinned in
-  `THIRD_PARTY_NOTICES.md`). It is still **off by default**: set `FCA_E2EE_NATIVE=1` to enable it
-  (`FCA_E2EE_NATIVE_LIB=/path` overrides the bundled file, e.g. for ARM or macOS). Why off: the
-  native and vendored engines register the same E2EE device and kick each other, so enabling it
-  causes socket churn. Provenance of the binaries is "supplied by the maintainer, not
-  independently verifiable" - see `THIRD_PARTY_NOTICES.md`.
-
-## API surface
-Package exports (verified by test): `login`, `default`, `createFcaClient`, `MessengerBot`,
-`createMessengerBot`, `MessengerContext`, `attachThreadInfoRealtimeSync`,
-`applyThreadInfoRealtimeEvent`, `CommandHumanizer`, `createCommandHumanizer`,
-`createHumanizerMiddleware`, `humanizer`.
-
-Methods attached to `api` after login (one per file in `src/api/`; signatures in upstream docs):
-- action: `addExternalModule changeAvatar changeBio dismissScrapingWarning enableAutoSaveAppState getCurrentUserID handleFriendRequest logout refreshFb_dtsg setPostReaction unfriend`
-- http: `httpGet httpPost postFormData`
-- messaging: `addUserToGroup changeAdminStatus changeArchivedStatus changeBlockedStatus changeGroupImage changeNickname changeThreadColor changeThreadEmoji createNewGroup createPoll createThemeAI deleteMessage deleteThread editMessage forwardAttachment forwardMessage getEmojiUrl getFriendsList getMessage getThemePictures handleMessageRequest markAsDelivered markAsRead markAsReadAll markAsSeen muteThread pinMessage removeUserFromGroup resolvePhotoUrl scheduler searchForThread sendBroadcast sendMessage sendTypingIndicator setMessageReaction setTitle shareContact unsendMessage uploadAttachment`
-- threads: `getThreadHistory getThreadInfo getThreadList getThreadPictures`
-- users: `getUserID getUserInfo getUserInfoV2`
-- socket: `listenMqtt` (= `listen`), `listenE2EE`, `stopListening`, `stopListeningAsync`
-(Listed from the source tree; none were exercised against live Facebook.)
-
-## Troubleshooting
-- `Cannot find module ...` -> run `npm install`; optional E2EE deps may be absent by design.
-- Login callback error -> appState expired; re-export cookies. Credential login needs `apiServer`.
-- `stop_listen` event -> reconnect budget exhausted; check network/session, then call listen again.
-- `account_inactive` -> Facebook invalidated the session (checkpoint/logout); re-login manually.
-- A `Fca_Database/` folder appears in the working directory on first use (SQLite cache).
-
-## Known limitations
-- No live verification of anything that talks to Facebook; Facebook changes endpoints without notice.
-- Subscribe-then-publish ordering and the 8 s / 12 s timeouts follow upstream's changelog
-  reasoning and mqtt.js semantics; not confirmed against live servers.
-- Legacy HTTP paths still use the deprecated `request` library (`nexca-utils.js`); porting to axios is future work.
-- `sequelize`+`sqlite3` are hard dependencies (heavy); `index.d.ts` is upstream-derived; newer methods are typed loosely (`any`).
-- Vendored E2EE bundle has no license header or source.
-
-## Migration from eryxenx-fca 1.x
-- Package name `hridoy-ultimate`; Node >= 18.
-- Humanizer and native E2EE are now **opt-in** (they were default-on in 1.1.x / 1.0.8+).
-- 9.0.0: typing indicator is **on by default** (`typingIndicator: false` to disable); the native binaries are bundled again (still opt-in).
-- `apiServer` has no default; autoUpdate is off.
-- Reconnects are bounded: handle `{type:"stop_listen"}`.
-- `api.listenMqtt(cb, options)` gains an optional second argument.
-
-## Develop
-```bash
-npm install
-npm test            # unit + integration (mocked) tests
-npm run lint        # syntax check of every source file
-npm pack            # builds hridoy-ultimate-9.0.0.tgz
+
+**This is the only setup needed — nothing else in `login.js` (or anywhere in GoatBot) has to change for E2EE.** Once login succeeds, `api.e2ee` is already connecting in the background, and every existing GoatBot call — `api.sendMessage(...)` (with or without `attachment`), `api.setMessageReaction(...)`, `api.unsendMessage(...)` — automatically detects when a thread is an encrypted DM and routes through the E2EE engine internally. Commands don't need to know or care whether a thread is encrypted; they call the same functions either way.
+
+#### Adding this to your own login.js
+
+Your bot's actual `login.js` will look different from the snippet above (dashboard setup, database sync, custom logging, etc.) — you're not replacing the file, just adding/checking two things inside your existing login callback:
+
+| Step | What to do |
+|---|---|
+| 1. sessionGuard | Add `api.sessionGuard(accountPath, { interval, debounce })` once, right after login succeeds, if it's not already there. |
+| 2. E2EE | Nothing to add — it's automatic. If your `login.js` already has an explicit `await api.connectE2EE()` call, **delete it** — it's redundant with the automatic connection and the two can race. |
+
+To check whether E2EE is already wired into your bot, search for `e2ee.isConnected` in your `login.js` — if it's there, setup is already done.
+
+---
+
+## 🔐 E2EE — Encrypted Conversations
+
+Uses Facebook's real Signal Protocol infrastructure — same as the official Messenger app.
+
+### Setup
+
+E2EE connects automatically after login (creating `.nexca/e2ee_device.json` on first run) — there's nothing to call manually. Just check status once connected:
+
+```javascript
+console.log(api.e2ee.isConnected()); // true (may need a moment right after login)
+```
+
+### Listen (regular + E2EE combined)
+
+```javascript
+api.listenE2EE((err, event) => {
+  if (event.type === "message") {
+    if (event.isE2EE) {
+      api.e2ee.sendMessage(event.threadID, "Encrypted reply!");
+    } else {
+      api.sendMessage("Normal reply!", event.threadID);
+    }
+  }
+});
+```
+
+### E2EE Methods
+
+```javascript
+await api.e2ee.sendMessage(threadID, "Hello!");
+await api.e2ee.sendMessage(threadID, { body: "Photo!", attachment: fs.createReadStream("photo.jpg") });
+await api.e2ee.sendReaction(threadID, messageID, "❤️");
+await api.e2ee.sendTyping(threadID, true);
+await api.e2ee.unsendMessage(messageID, threadID);
+await api.e2ee.editMessage(threadID, messageID, "Updated!");
+api.e2ee.isConnected();
+await api.e2ee.disconnect();
+```
+
+### Native media engine
+
+Sending image/video/audio/document attachments, reactions, and unsend in E2EE threads can be routed through a precompiled **mautrix-go / mautrix-meta** binary (`src/api/socket/e2ee/native/`) via the `koffi` FFI, instead of this project's own hand-written Signal Protocol encoder. This project's own encoder builds protocol-valid messages that Facebook's servers accept, but real Messenger clients silently fail to render — the native engine avoids that entirely.
+
+**⚠️ The native engine is DISABLED by default.** Both the vendored JS engine and the native engine register with Facebook as the *same* E2EE device (same device id), and Facebook's server keeps only one live E2EE socket per device — so when both run at once they kick each other off in a loop (a fresh handshake every few seconds, which looks like automated behavior to Facebook). The vendored JS engine is therefore given exclusive use of the socket unless you opt in:
+
+- Set `FCA_E2EE_NATIVE=1` in the environment to enable the native engine. With it on you get E2EE group text receive/send, native media sends, native reactions/unsend/edit/markRead — but you also accept the device-kick socket churn described above (the JS engine reconnects with exponential backoff, so it stays usable, just noisy).
+- With it off (default): E2EE DM text + DM media work through the vendored engine. E2EE **group** send/receive, and E2EE markRead, are unavailable; reactions/unsend/edit in E2EE DMs fall back to the vendored engine.
+
+- Text messages always use hridoy-ultimate's own E2EE engine (already reliable, no native dependency).
+- If the native engine fails to load or a send fails (unsupported platform, binary mismatch, etc.), hridoy-ultimate automatically falls back to its own engine and logs `[native-media] ... falling back to legacy vendor engine`.
+- See `src/api/socket/e2ee/native/NOTICE.md` for the required MPL-2.0 attribution to the upstream mautrix-go/mautrix-meta project (© Tulir Asokan and contributors) — do not remove it if you redistribute this fork.
+
+### Receiving E2EE media (attachments & replies)
+
+Incoming encrypted image/video/audio/document messages are automatically decrypted and served over a short-lived local URL (`http://127.0.0.1:<port>/<token>`, 15 min TTL), and populated into `event.attachments` / `event.messageReply.attachments` — same shape as normal (non-E2EE) attachments. Reply-based commands (e.g. "reply to an image with `/imgur`") work the same in E2EE threads as in normal ones, no command code changes needed.
+
+```javascript
+if (event.messageReply && event.messageReply.attachments.length) {
+  const url = event.messageReply.attachments[0].url; // works for E2EE too
+}
+```
+
+If media resolution fails, check the console for `[media-resolve]` / `[media-decode]` errors — this usually means the CDN download host (`FB_E2EE_MEDIA_DOWNLOAD_HOST` env var, default `rupload.facebook.com`) needs adjusting for your account/region.
+
+---
+
+## 🛡️ Command Anti-Spam (Humanizer)
+
+Delays and rate-limits command replies so the bot reacts like a person
+typing, not a script firing instantly — and drops commands sent faster
+than a human could plausibly send them (spam bursts).
+
+Installed automatically on login (`enabled` by default). No setup needed:
+
+```javascript
+login({ appState }, {}, (err, api) => {
+  api.listenMqtt((err, event) => { /* ... */ });
+});
+```
+
+Configure it via the `humanize` login option, or `api.setOptions({ humanize })`:
+
+```javascript
+login({ appState }, {
+  humanize: {
+    enabled: true,
+    reactDelayMs: [2000, 3000], // random delay before a command is let through
+    cooldownMs: 5500,           // min gap between two accepted commands (per thread)
+    resetMs: 10000,             // idle gap before cooldown state resets
+    maxPerMinute: 20,           // global accepted-commands cap
+    commands: ["/", "!", "."],  // prefixes that count as "this is a command"
+    perThread: true             // cooldown tracked per thread vs. globally
+  }
+}, cb);
+```
+
+`api.setOptions({ humanize: { enabled: false } })` turns it off entirely.
+
+### What counts as a "command"
+
+By default, only messages starting with one of the `commands` prefixes are
+treated as commands — everything else (plain chat) passes through
+untouched, with no delay and no typing indicator.
+
+If `global.GoatBot` is present (i.e. running under GoatBot-Pro), the
+humanizer **automatically** also treats these as commands, with zero
+config needed:
+
+- **No-prefix admin commands** — `config.noPrefix.enable: true` +
+  sender in `config.adminBot`, first word matches a real command/alias.
+- **`onChat` triggers** — a message whose full text exactly matches a
+  command name registered in `GoatBot.onChat` (e.g. typing `prefix` with
+  no `/`, which GoatBot's `prefix.js` reacts to).
+- **`onReply` flows** — a reply to a message tracked in `GoatBot.onReply`
+  (e.g. the numeric "1", "2", "3" replies used by GoatBot's `setting.js`
+  menu system).
+
+This means the whole multi-step `setting` command flow — not just the
+initial `/setting` — gets the same delay/cooldown/typing treatment as a
+normal command.
+
+For anything outside these built-ins, give it a custom matcher:
+
+```javascript
+const h = api.getHumanizer();
+h.setMatcher((event) => {
+  // your own logic — return true to treat this event as a command
+  return event.body === "some no-prefix trigger";
+});
+```
+
+`matcher` can also be passed directly in the `humanize` config
+(`humanize: { matcher: fn }`). A message counts as a command if it matches
+the prefix list **or** a built-in GoatBot check **or** the matcher.
+
+### Typing indicator
+
+When a command is accepted, `api.sendTypingIndicator(threadID, true)` is
+called immediately, held for the exact accepted delay, then turned off
+right before the event is forwarded — so the typing indicator and the
+reply delay are the same window, not two stacked waits. Disabled
+automatically if `global.GoatBot.config.enableTypingIndicator` is `false`.
+
+### Inspecting it
+
+```javascript
+const h = api.getHumanizer();
+h.stats();     // { enabled, global: {accepted, dropped, ...}, threads: [...] }
+h.reset();     // clear all cooldown state
+```
+
+> Note: this operates on **incoming** command volume — separate from
+> outgoing send pacing (see `sendBroadcast` below, and any queueing you
+> add yourself around `api.sendMessage`).
+
+---
+
+## 🛡️ sessionGuard
+
+Protects your appstate from corruption and silent logouts.
+
+```javascript
+api.sessionGuard("./account.json");
+
+// Custom timing
+api.sessionGuard("./account.json", {
+  interval: 3 * 60 * 1000,
+  debounce: 30 * 1000
+});
+```
+
+What it does:
+- Auto-saves appstate every N minutes
+- Saves after every successful sendMessage (debounced)
+- Corruption guard — never overwrites a larger appstate with a smaller one
+- Auto-backup — writes `.bak` before every overwrite
+
+```javascript
+api.saveSession();           // force save now
+api.restoreSessionBackup();  // restore from .bak
+api.stopSessionGuard();      // stop the timer
+```
+
+---
+
+## 📡 sendBroadcast
+
+Rate-limited multi-thread broadcast.
+
+```javascript
+const result = await api.sendBroadcast(
+  "Hello everyone!",
+  ["THREAD_1", "THREAD_2", "THREAD_3"],
+  {
+    delay: 2000,
+    parallel: 2,
+    onEach: (err, info, id) => {
+      console.log(err ? "Failed: " + id : "Sent: " + id);
+    }
+  }
+);
+console.log(result.sent.length + "/" + result.total + " delivered");
+```
+
+---
+
+## 🤖 MessengerBot
+
+Discord.js/Telegraf style high-level bot class.
+
+```javascript
+const { createMessengerBot } = require("hridoy-ultimate");
+
+const bot = await createMessengerBot(
+  { appState: require("./account.json") },
+  { commandPrefix: "/", stopOnSignals: true }
+);
+
+bot.command("ping", async ctx => await ctx.replyAsync("pong 🏓"));
+bot.hears(/hello/i, async ctx => await ctx.replyAsync("Hi! 👋"));
+bot.on("messageCreate", event => console.log(event.body));
+
+await bot.launch({ stopOnSignals: true });
+```
+
+---
+
+## 🎯 createFcaClient
+
+Namespaced facade grouping all API methods by domain.
+
+```javascript
+const { createFcaClient } = require("hridoy-ultimate");
+const client = createFcaClient(api);
+
+await client.messages.send("Hello!", threadID);
+await client.messages.react("❤️", messageID, threadID);
+await client.threads.getInfo(threadID);
+await client.users.getInfo(userID);
+await client.account.refreshDtsg();
+```
+
+---
+
+## 📖 API Reference
+
+### Sending Messages
+
+```javascript
+api.sendMessage("Hello!", threadID);
+api.sendMessage({ body: "Photo!", attachment: fs.createReadStream("photo.jpg") }, threadID);
+api.sendMessage({ body: "Hey @John", mentions: [{ id: "uid", tag: "@John", fromIndex: 4 }] }, threadID);
+api.sendMessage({ sticker: "369239263222822" }, threadID);
+api.sendMessage({ location: { latitude: 23.8, longitude: 90.4, current: true } }, threadID);
+api.sendBroadcast("msg", ["tid1", "tid2"], { delay: 2000 });
+api.sendGif("https://media.giphy.com/xyz.gif", threadID);
+api.sendLocation(23.8, 90.4, threadID);
+api.sendImage("./photo.jpg", threadID, "caption");
+api.sendVideo("./video.mp4", threadID);
+api.sendAudio("./voice.ogg", threadID);
+api.sendFile("./doc.pdf", threadID);
+api.shareLink("https://github.com", threadID, "Check this!");
+api.shareContact("Meet my friend!", userID, threadID);
+```
+
+### Message Actions
+
+```javascript
+api.editMessage("Updated text", messageID);
+api.unsendMessage(messageID);
+api.deleteMessage([messageID]);
+api.setMessageReaction("😍", messageID, threadID);  // threadID optional
+api.setMessageReaction("", messageID);               // remove reaction
+api.getMessage(threadID, messageID);
+api.forwardAttachment(attachmentID, [userID]);
+api.uploadAttachment([fs.createReadStream("photo.jpg")]);
+```
+
+### Read Receipts & Typing
+
+```javascript
+api.markAsRead(threadID);
+api.markAsReadAll();
+api.markAsDelivered(threadID, messageID);
+api.markAsSeen();
+api.sendTypingIndicator(threadID, true);
+```
+
+### Thread Management
+
+```javascript
+api.getThreadInfo(threadID);
+api.getThreadList(10, null, ["INBOX"]);
+api.getThreadHistory(threadID, 20);
+api.createGroup("Hey!", ["uid1", "uid2"]);
+api.deleteThread(threadID);
+api.muteThread(threadID, 3600);
+api.changeArchivedStatus(threadID, true);
+api.handleMessageRequest(threadID, true);
+api.searchForThread("query");
+```
+
+### Thread Customization
+
+```javascript
+api.setTitle("New Name", threadID);
+api.changeThreadColor("#0084FF", threadID);
+api.changeThreadEmoji("🔥", threadID);
+api.changeNickname("The Boss", threadID, userID);
+api.changeGroupImage(fs.createReadStream("group.jpg"), threadID);
+api.changeAdminStatus(threadID, userID, true);
+api.addUserToGroup(userID, threadID);
+api.removeUserFromGroup(userID, threadID);
+api.createPoll("Question?", threadID, { "Yes": false, "No": false });
+api.pinMessage(messageID, threadID);
+api.unpinMessage(messageID, threadID);
+```
+
+### User Info
+
+```javascript
+api.getUserInfo(userID);
+api.getUserID("John Doe", callback);
+api.getUID("https://facebook.com/zuck");
+api.getFriendsList();
+api.getAvatarUser(userID);
+api.getProfileInfo(userID);
+api.getPublicData(userID);
+api.sendFriendRequest(userID);
+api.handleFriendRequest(userID, true);
+api.changeBlockedStatus(userID, true);
+api.followUser(userID);
+api.unfollowUser(userID);
+api.unfriend(userID);
+```
+
+### Social
+
+```javascript
+api.reactToPost(postID, "love");
+api.reactToComment(commentID, "haha");
+api.postComment(postID, "Great post!");
+api.sharePost(postID, "Check this!");
 ```
-Credits and licenses: `LICENSE`, `THIRD_PARTY_NOTICES.md`. Merge details: `MERGE_REPORT.md`.
+
+### Account & Config
+
+```javascript
+api.getCurrentUserID();
+api.getAppState();
+api.setOptions({ listenTyping: true });
+api.logout();
+api.refreshFb_dtsg();
+api.addExternalModule("myFunc", (defaultFuncs, api, ctx) => {
+  return function(text, threadID) {
+    return api.sendMessage("[BOT] " + text, threadID);
+  };
+});
+```
+
+### HTTP Utilities
+
+```javascript
+api.httpGet(url, params, callback);
+api.httpPost(url, form, callback);
+api.httpPostFormData(url, form, callback);
+api.uploadImageToImgbb(imageUrl);
+```
+
+---
+
+## 📋 Login Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `selfListen` | boolean | false | Receive your own sent messages |
+| `listenEvents` | boolean | true | Receive thread/group events |
+| `listenTyping` | boolean | false | Receive typing indicator events |
+| `updatePresence` | boolean | false | Receive online/offline presence events |
+| `autoMarkDelivery` | boolean | false | Auto-mark incoming messages as delivered |
+| `autoMarkRead` | boolean | false | Auto-mark threads as read |
+| `autoReconnect` | boolean | true | Auto-reconnect MQTT on disconnect |
+| `online` | boolean | false | Appear as online to others |
+| `emitReady` | boolean | false | Emit ready event when MQTT connected |
+| `proxy` | string | — | HTTP proxy URL |
+| `userAgent` | string | Safari UA | Override HTTP User-Agent |
+
+---
+
+## 📄 License
+
+MIT License
+
+**hridoy-ultimate** v9.0.1 by [HR ID OY](https://github.com/hridoyhossen48360)
+
+> The E2EE native media engine (`src/api/socket/e2ee/native/`) bundles a
+> precompiled binary built from **mautrix-go** / **mautrix-meta**, © Tulir
+> Asokan and contributors, licensed under **MPL-2.0** (not MIT). See
+> `src/api/socket/e2ee/native/NOTICE.md` for full attribution — this notice
+> must be preserved in any redistribution of this fork.
+NEXCA MQTT core by [Deku](https://github.com/dekuzxc) — MIT License
+
+> Unauthorized copying or redistribution without credit is prohibited.
+
+---
+
+<div align="center">
+
+Made with ❤️ by HR ID OY
+
+</div>