hridoy-ultimate 8.0.2 → 9.0.0

package/CHANGELOG.md

@@ -1,43 +1,71 @@
 # Changelog
 
-## 8.0.1
-- Rename: package/branding is now `hridoy-ultimate` (was `toru-fca`) in banner, logs, update check, README, examples and config comments.
-- Update check env var `HRIDOY_ULTIMATE_NO_UPDATE_CHECK` added (old `TORU_FCA_NO_UPDATE_CHECK` still honoured).
-- Internal globals (`global._toruFcaConfig`, `_toruFcaInitDone`) intentionally unchanged for backward compatibility.
-
-## 1.2.4
-- Fix (critical): `scheduleReconnect()` called `getSeqID()` which is only defined inside the module factory, so every MQTT reconnect threw `ReferenceError` in a timer. Now exposed as `ctx._getSeqID` and called with a try/catch.
-- Fix: `changeCover` used `log` without requiring `npmlog`.
-- Fix: `createCommentPost` typo `calback`, undefined `image` in attachment error, and `cb(null, err)` resolving errors as success (now rejects).
-- Fix: `package.json` declares `form-data` and `https-proxy-agent` (were required but undeclared); removed unused `chalk`, `tough-cookie`, `protobufjs`.
-- Fix: `checkUpdate.js` hard-coded version 1.2.1; now read from `package.json`.
-- Chore: example config version synced; CRLF -> LF in `reply.js`, `getUID.js`, `httpGet.js`, `httpPost.js`, `changeAvt.js`.
-- Add: `scripts/check.js` (`npm run check`) and `test/fixes-1_2_4.test.js` (6 regression tests, incl. a reconnect test verified to fail on the old code).
-
-## 1.2.3
-- Fix: E2EE reconnect timers are tracked, deduplicated, bounded with exponential backoff, and cleared on explicit disconnect.
-- Fix: TORU owns E2EE reconnect scheduling to avoid competing reconnect managers.
-- Fix: MQTT listener replacement clears stale reconnect/watchdog timers.
-- Fix: pending MQTT request callbacks are failed and cleaned up on transport error/close or explicit stop.
-- Add: regression test for pending MQTT callback cleanup on stop.
-
-## 1.2.2
-- Fix: reaction MQTT requests now reject on missing acknowledgement instead of assuming success.
-- Fix: reaction MQTT callback and Promise settle once and share the same result.
-- Fix: forward explicit MQTT response errors to request callbacks.
-- Fix: callback type checks no longer execute user callbacks as a test (pin/edit/block helpers).
-- Fix: atomic session writes use unique temporary names and restrictive file permissions.
-- Add: Node.js syntax-check script and focused MQTT reaction tests.
-
-
-## 1.2.1
-- Fix: setMessageReactionMqtt invoked the user callback prematurely / threw synchronously; now Promise+callback, real ack.
-- Add: `/ls_resp` dispatch to `ctx.reqCallbacks` (reaction/pin/block helpers finally get acks).
-- Add: richer `message_reaction` event (off, action, isGroup, isSingleUser, null-safe).
-- Fix: stale MQTT client events caused duplicate reconnects; old client is now torn down first.
-- Fix: getSeqID transient failure during reconnect no longer kills the listener (backoff retry).
-- Fix: cookie expiry extension edited a copy; now updates the live jar.
-- Fix: login callback double-fire guard.
-- Change: uncaughtException logs stack for non-network errors.
-- Change: e2ee disabled by default; spinner TTY-only; update check opt-out.
+## 9.0.0 - hridoy-ultimate (merge of 83 analysed builds)
 
+Base: hridoy-ultimate 8.0.5 (`fca.zip`), plus fixes taken from the `@eryxenx/fca` 1.0.0-1.1.9,
+`fca-eryxenx` 1.x-39.x lines (see `MERGE_REPORT.md` for the per-fix source versions).
+
+### Added
+- **Typing indicator, default ON** (`src/utils/typingIndicator.js`): shows typing when a
+  command-like message arrives, clears it when the reply is sent or after 8 s; zero added
+  latency; MQTT and E2EE threads. Options `typingIndicator: false | {...}`,
+  `api.getTypingIndicator()`, `api.setTypingIndicator()`, `api.withTyping()`.
+- `messagix.so` / `messagix.dll` bundled in `src/api/socket/e2ee/native/build/` (SHA-256 pinned
+  in a test and in `THIRD_PARTY_NOTICES.md`). Enabling needs only `FCA_E2EE_NATIVE=1`; the
+  engine stays opt-in because it kicks the vendored engine's socket (same E2EE device).
+- `MERGE_REPORT.md`, `THIRD_PARTY_NOTICES.md` (both were listed in `files` but missing).
+- 10 typing tests, fingerprint test, pinned-binary package test.
+
+### Fixed
+- `setMessageReaction` no longer falls back to the bogus thread id `"0"`; it rejects with a
+  clear error when the thread cannot be resolved.
+- Chrome fingerprint pool refreshed to 149.0.7827.102 / 151.0.7922.75 (was Chrome 131-135).
+  The User-Agent is now the reduced `Chrome/<major>.0.0.0` form real Chrome sends; the full
+  build stays in `Sec-CH-UA-Full-Version-List` (client hints derived from the same fingerprint).
+- `index.d.ts`: `sendTypingIndicator` had the wrong signature; 23 previously undeclared API methods
+  and the `humanize` / `typingIndicator` options are now declared.
+- Logout / stopListening clear typing timers.
+
+## 8.0.5 - hridoy-ultimate (first release under this name)
+
+Built by merging the eryxenx-fca 1.0.0 - 1.1.9 lineage. Base tree: 1.1.9, with
+`module/loginHelper.js` from 1.1.8 (1.1.9 regressed it).
+
+### Security
+- Removed the hard-coded third-party credential-login host; `apiServer` is now empty by
+  default and credential login refuses to run without one explicitly configured.
+- Removed unverifiable prebuilt native binaries (messagix .so/.dll). Native E2EE engine is
+  opt-in (`FCA_E2EE_NATIVE=1` + `FCA_E2EE_NATIVE_LIB`).
+- `autoUpdate` default is now `false` (it was an inert stub upstream).
+
+### Fixed
+- Pending reconnect / getSeqID retry timers could revive the listener after `stopListening()`
+  (reproduced on 1.1.9: 30 `getSeqID` calls after stop). Timers are now tracked and
+  gated by a `_stopped` flag.
+- Reconnect used a fixed 2 s delay forever. Now bounded exponential backoff with jitter,
+  attempt budget (default 10) and a `stop_listen` event when exhausted.
+- Calling listen twice left two live MQTT clients; the old client is now replaced.
+- Events from stale/replaced clients are ignored.
+- Late socket `error` after cleanup could throw (EventEmitter with no error handler).
+- Sync queue is published after SUBACKs instead of immediately after subscribe.
+- `logout()` now stops MQTT, disconnects E2EE and clears all timers.
+- `emitAuth` now clears heartbeat / session-keeper / dtsg timers.
+- Session keeper no longer re-arms after stop; heartbeat no longer fights a pending backoff.
+- Undeclared dependencies (`request`, `tough-cookie`, `form-data`, `undici`) are declared.
+- `index.d.ts` declared the wrong module name and had an `IFCAU_Api` typo.
+- Silent `.catch(() => {})` on E2EE disconnect now logs.
+
+### Changed (defaults)
+- Humanizer (reply delay + command cooldown) is opt-in: `humanize: true`.
+- Native E2EE engine is opt-in (reverts 1.0.8 default-on).
+- `t_ms` wait 5 s -> 8 s, MQTT connect timeout 5 s -> 12 s (configurable).
+- Node >= 18 required.
+
+### Added
+- `api.listenMqtt(callback, options)` second argument (reconnect/cycle options).
+- Test suite (36 tests), `scripts/run-tests.js`, `scripts/syntax-check.js`.
+- Docs: README, MERGE_REPORT, THIRD_PARTY_NOTICES, upstream API docs in `docs/`.
+
+### Removed
+- `cheerio`, `totp-generator`, `@noble/curves`, `@noble/hashes` (unused in source).
+- Bogus `versionCheck` update notice (it compared against an unrelated npm package).

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) EryXenX and contributors (eryxenx-fca 1.0.0 - 1.1.9)
+Copyright (c) DongDev and contributors (original fca-unofficial lineage)
+Copyright (c) 2026 HR ID OY (hridoy-ultimate modifications)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MERGE_REPORT.md

@@ -0,0 +1,54 @@
+# Merge report - hridoy-ultimate 9.0.0
+
+## Inputs
+- 83 published packages, analysed statically (extract, per-version diff, `node --check`, reading
+  the core paths): `@eryxenx/fca` 1.0.0-1.1.9 (18), `fca-eryxenx` 1.0.0-29.0.0 (20),
+  3.0.2 + 30.0.0-39.1.8 (20), 4.0.x + 39.1.9-39.9.0 (20), 6.0.0-9.0.3 (5).
+- `fca.zip` = hridoy-ultimate 8.0.5, used as the base tree (already a hardened merge of
+  `@eryxenx/fca` 1.1.9 with `loginHelper.js` from 1.1.8, with a 36-test suite).
+- `messagix.so` / `messagix.dll` supplied by the maintainer.
+
+Nothing was run against Facebook. Not every one of the ~14,000 extracted files was read line by
+line; the 12,144 `.js/.cjs/.mjs` files contain only 352 distinct contents.
+
+## What the best builds contributed, and where it stands in 9.0.0
+Verified by reading the 8.0.5 code before touching it.
+
+| Improvement | Best source | Status |
+|---|---|---|
+| Stable MQTT (backoff, SUBACK, 8 s / 12 s timeouts, stale-client guard) | `fca-eryxenx` 20-23 | already in base (own implementation, tested) |
+| Native client reuse + `koffi.disposable` string free (leak fixes) | 39.2.0 / 39.2.1 | already in base |
+| 15 s `withTimeout` on native calls | 39.1.8 | already in base |
+| `getThreadInfo` E2EE branch | 39.1.6 | already in base |
+| E2EE group routing in react / unsend / edit | 39.2.2 | already in base (`isE2EEGroup`) |
+| Session keeper (cookie + `fb_dtsg` refresh) | 39.2.7 | already in base |
+| `Accept` header navigation vs XHR | 39.2.5 | already in base |
+| Attachment id fallback in `sendMessage` | 7.0.0 | already in base |
+| Native E2EE engine opt-in (not auto-connected) | 39.2.8 | already in base |
+| Logout stops MQTT / E2EE / timers | none (all builds lacked it) | already in base |
+| Typing indicator | none (only the opt-in humanizer had one) | **new in 9.0.0** |
+| Bundled `messagix` binaries | maintainer upload | **restored in 9.0.0, opt-in** |
+| Reduced UA + refreshed Chrome pool | fingerprint.js from 1.1.7, rebuilt | **new in 9.0.0** |
+| `setMessageReaction` thread `"0"` fallback | present in every build | **fixed in 9.0.0** |
+| `index.d.ts` coverage | 23 of 66 methods missing in 1.1.9 | **fixed in 9.0.0** |
+
+## Rejected on purpose
+- `autoLogin: true` default and the `minhdong.site` credential host (every `fca-eryxenx` build and
+  `@eryxenx/fca` 1.0.0-1.0.5). Credentials and the 2FA secret would go to a third party.
+- Default-on humanizer (silently drops commands inside its cooldown), default-on native engine
+  (kicks the vendored E2EE socket), bogus `versionCheck` (1.1.9), inert auto-update.
+- 39.3.0-39.9.0: branch cut from the 39.1.2-39.1.4 tree, loses the 39.2.x fixes, adds
+  `[E2EE-DEBUG]` logging of full reaction payloads. 39.1.0-39.1.4 / 39.3.0+ also ship a duplicate
+  17.5 MB native copy.
+- `fca-eryxenx` 9.0.0 (syntax error in `core/channel.js:178`), 3.0.2-6.0.0 (`editMessage` requires a
+  non-existent `../utils`), 4.0.4's dead "stability patch", the stray `index.js.nexca`, nested
+  `e2ee/e2ee/` copies.
+
+## Known issues kept (documented, not hidden)
+- `module/login.js` still installs process-wide `unhandledRejection` / `uncaughtException`
+  handlers that log and continue; they keep bots alive but can hide a fatal state.
+- `src/api/messaging/sendMessage.js` is loaded and then overridden by `src/api/socket/sendMessage.js`
+  (`loginHelper.js`); kept for backward compatibility.
+- Legacy HTTP paths still use the deprecated `request` library (`src/utils/nexca-utils.js`).
+- Native binaries: x86-64 only, stripped, license wording conflicts (see `THIRD_PARTY_NOTICES.md`).
+- Live Facebook behaviour (login, MQTT, send, react, E2EE, typing) is NOT verified here.

package/README.md

@@ -1,134 +1,179 @@
-# hridoy-ultimate v8.0.1
+# hridoy-ultimate
 
-**Ultimate Merged, Fixed & Advanced Facebook Chat API**
+**Version 9.0.0 - Owner/maintainer: HR ID OY**
 
-> Cookie-based login, session persistence, and MQTT reconnection are best-effort. Server-side logout, checkpoints, and platform restrictions cannot be prevented or guaranteed against by this library.
+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.** 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.
 
-## ✅ Features
-
-| Feature | Status |
+## Verification status (read this first)
+| Area | Status |
 |---|---|
-| Session refresh helper (best-effort) | ⚠️ Best-effort only |
-| Conservative presence/delay options | ⚠️ No guarantee |
-| Inbox Smooth (bot inbox reply) | ✅ Active |
-| GoatBot Compatible | ✅ Ready |
-| Session Guard (auto-save) | ✅ Every 3min |
-| fb_dtsg Auto-Refresh | ✅ Every 20min |
-| MQTT Stable Reconnect | ✅ Active |
-| Error reporting | ✅ Host process handlers preserved |
-| E2EE Labyrinth Bridge | ✅ Active |
-| Facebook Protection | ✅ New in v1.0.6 |
-| Human-like Delay | ✅ New in v1.0.6 |
-
----
-
-## 📦 Install
+| 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) |
+
+Full results: `docs/TEST_RESULTS.md`. Honest limits: [Known limitations](#known-limitations).
 
+## Install
+Requires Node.js >= 18.
 ```bash
-npm install
+npm install hridoy-ultimate            # from a registry, or:
+npm install ./hridoy-ultimate-9.0.0.tgz
 ```
+`sqlite3` compiles/downloads a native module; E2EE-related packages are optional.
 
----
-
-## 🚀 Usage (GoatBot / Goat-Bot)
-
+## Quick start
 ```js
-const login = require("hridoy-ultimate");
+const login = require("hridoy-ultimate");           // also: require(...).login, .default
 const fs = require("fs");
 
-login({ appState: JSON.parse(fs.readFileSync("appstate.json", "utf8")) }, {
-  listenEvents: true,
-  selfListen: false,
-  autoReconnect: true,
-  online: false
-}, (err, api) => {
-  if (err) return console.error(err);
+const appState = JSON.parse(fs.readFileSync("appstate.json", "utf8")); // keep this file secret
 
-  // Session guard — auto-save appstate
-  api.sessionGuard("appstate.json");
+login({ appState }, { listenEvents: true, autoReconnect: true }, (err, api) => {
+  if (err) return console.error("login failed:", err.error || err.message || err);
 
-  api.listenMqtt((err, event) => {
-    if (event.type === "message") {
-      api.sendMessage("Hello!", event.threadID);
+  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);
+    }
+  }, { maxReconnectAttempts: 10 });
+
+  process.on("SIGINT", async () => {
+    stop.stopListening(async () => { await api.logout(); process.exit(0); });
   });
 });
 ```
+(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.
 
----
-
-## ⚙️ config.json Options
+```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 } });
 
-```json
-{
-  "antiLogout": { "enabled": true, "refreshIntervalMs": 1200000 },
-  "sessionGuard": { "enabled": true, "intervalMs": 180000 },
-  "automation": { "enabled": false },
-  "smooth": { "enabled": true, "messageDelay": 300 },
-  "facebookProtection": { "enabled": true, "blockAutomationDetection": true, "humanLikeDelay": true },
-  "inbox": { "enabled": true, "replyToInbox": 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
 ```
-
----
-
-## 🔐 Anti-Logout System
-
-Cookie login করলে `api.logout()` automatically blocked হয়।
-- Session refresh does not guarantee that Facebook will preserve a login session
-- `api.logout()` is currently overridden; use `api.forceLogout()` only when you explicitly intend to terminate the session
-- Force logout দরকার হলে: `api.forceLogout()`
-- Anti-logout বন্ধ করতে: `api.stopAntiLogout()`
-
----
-
-## 📊 API Methods
-
-| Method | Description |
-|---|---|
-| `api.sendMessage(msg, threadID)` | Message পাঠাও |
-| `api.listenMqtt(callback)` | Message শোনো |
-| `api.sessionGuard(path, opts)` | Appstate auto-save |
-| `api.saveSession(path)` | Manual session save |
-| `api.getHealth()` | MQTT + session health |
-| `api.forceLogout()` | Force logout (opt-in) |
-| `api.stopAntiLogout()` | Anti-logout timer বন্ধ |
-| `api.refreshFb_dtsg()` | Manual fb_dtsg refresh |
-| `api.sendTypingIndicatorV2(typing, threadID)` | MQTT typing indicator |
-
----
-
-## 🛡️ Facebook Protection (v1.0.6)
-
-- `humanLikeDelay: true` — প্রতিটি message এ random 50-200ms delay, bot traffic pattern unpredictable
-- `blockAutomationDetection: true` — online=false, presence update বন্ধ
-- ফলে Facebook account এ restriction বা ban আসে না
-
----
-
-**hridoy-ultimate v8.0.1** — Built on toru-fca 1.2.0 (itself derived from HRIDOY-FCA / ST-FCA). Other packages were analysed and only selected ideas were ported — see ANALYSIS.md
-
-
-## What's new in v1.2.4
-- **Critical fix:** MQTT auto-reconnect crashed with `ReferenceError: getSeqID is not defined` (the reconnect timer called a function that lives in another scope). The factory now exposes it as `ctx._getSeqID` and the timer uses that, guarded by try/catch.
-- `changeCover`: missing `npmlog` import (ReferenceError on every error path) fixed.
-- `createCommentPost`: fixed `calback` typo (crash whenever a callback was passed), undefined `image` in the attachment error, and failures that *resolved* with the error object instead of rejecting.
-- `package.json`: declared `form-data` and `https-proxy-agent` (both were required but missing); removed unused `chalk`, `tough-cookie`, `protobufjs`.
-- `checkUpdate` now reads its version from `package.json` (was hard-coded 1.2.1). Example config version synced. CRLF line endings normalised to LF.
-- New `npm run check` (syntax + relative/undeclared require check on every file) and regression tests in `test/fixes-1_2_4.test.js`.
-
-## Earlier: v1.2.3
-- **Reactions:** `message_reaction` events now carry `off`, `action` ("add"/"remove"), `userID` (reactor), `isGroup`, `isSingleUser` (inbox vs group) and are null-safe. `selfListen:false` also ignores the bot's own reactions.
-- **api.setMessageReactionSafe(reaction, messageID, threadID, opts):** MQTT first, HTTP fallback with retry (idea from shadowx `setMessageReactionv2`). `setMessageReaction` now accepts any real emoji and no longer crashes on retry/redirect (it passed `ctx.jar` instead of `ctx` to `parseAndCheckLogin`; same bug fixed in `forwardAttachment`).
-- **api.setMessageReactionMqtt:** the old `isCallable()` helper *called* your callback with no arguments and the call could throw synchronously. Fixed; supports callbacks and Promises; real ack via `/ls_resp`.
-- **MQTT stability:** events from replaced clients are ignored (no double-reconnect loops), a failed `getSeqID` during reconnect now retries with backoff instead of silently killing the listener, spinner only draws on a TTY.
-- **Session safety:** cookie-expiry extension now really works (v1.2.0 edited a throw-away copy). Login callback can no longer fire twice.
-- **Errors:** uncaught exceptions are still non-fatal but now print the stack instead of hiding it.
-- E2EE is off by default (needs the native `messagix` binary which is not bundled).
-- Update check never installs anything; disable with `HRIDOY_ULTIMATE_NO_UPDATE_CHECK=1` (old `TORU_FCA_NO_UPDATE_CHECK` still works).
-
-## Honest notes
-- Login: use `appState` (cookie array / cookie string). `api.logout()` is blocked on purpose; use `api.forceLogout()` if you really want to log out.
-- "Facebook protection" (online=false, small delays) only lowers noise. No library can guarantee Facebook will not flag or checkpoint an account that is driven by a bot.
+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
+```
+Credits and licenses: `LICENSE`, `THIRD_PARTY_NOTICES.md`. Merge details: `MERGE_REPORT.md`.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,36 @@
+# Third-party notices
+
+hridoy-ultimate is MIT licensed (see `LICENSE`). It contains or builds on the following.
+
+## Code lineage (MIT)
+- `eryxenx-fca` / `@eryxenx/fca` and its contributors (builds 1.x - 39.x were analysed and merged).
+- DongDev and the original `fca-unofficial` lineage (<https://github.com/dongp06>).
+- Optional dependency `fca-unofficial` from `github:VangBanLaNhat/fca-unofficial`.
+
+## Bundled native binaries (opt-in, `FCA_E2EE_NATIVE=1`)
+Location: `src/api/socket/e2ee/native/build/`
+
+| File | Size (bytes) | Type | SHA-256 |
+|---|---|---|---|
+| `messagix.so` | 17,504,872 | ELF 64-bit x86-64, stripped | `6249f50cc23de0b11a710266a2323c306d44cf46530880e58e0cd1cf4b5bf8d9` |
+| `messagix.dll` | 15,802,368 | PE32+ DLL x86-64, stripped | `f8597ba86c90c39cec19b660e75eba59f2022678eb20866b740cfa321036885e` |
+
+- Supplied by the maintainer. They are byte-identical to the copies found in every analysed
+  `eryxenx` package (58 `.so` and 45 `.dll` copies, no differing hash). They are stripped, so
+  they could **not** be audited here, and no source ships with them.
+- A test (`test/integration/package.test.js`) fails if either hash changes.
+- Platforms: x86-64 Linux and Windows only. macOS and ARM (e.g. Termux) need your own build via
+  `FCA_E2EE_NATIVE_LIB=/path/to/messagix`.
+- **License question to resolve before you redistribute:** the analysed packages disagree about the
+  upstream. `native/NOTICE.md` describes mautrix-go / mautrix-meta as MPL-2.0, while the
+  `vendor/stfca-native/NOTICE.md` that shipped in some builds (39.1.0-39.1.4, 39.3.0-39.9.0) says the
+  `messagix` part is AGPL-3.0. AGPL-3.0 carries network-use source-offer obligations. Check the
+  upstream repository for the exact build you use. See also `src/api/socket/e2ee/native/NOTICE.md`.
+
+## Vendored E2EE bundle
+`src/api/socket/e2ee/vendor/fme/dist/index.cjs` (bundled `fb-messenger-e2ee` client) has no license
+header or source in the analysed packages. Treat its terms as unknown.
+
+## Runtime dependencies
+Declared in `package.json`; each keeps its own license (axios, mqtt, ws, sequelize, sqlite3,
+@signalapp/libsignal-client, protobufjs, koffi and others).

package/docs/TEST_RESULTS.md

@@ -0,0 +1,68 @@
+# Test results (actual output)
+
+Environment: v22.22.2, Linux 6.18.44-fc-v114, no network, third-party modules stubbed (MOCKED where marked).
+Generated: 2026-10-13T20:03Z
+
+## npm test (node --test, spec reporter)
+```
+✔ [mocked] logout stops MQTT, disconnects E2EE and clears every timer (50.186778ms)
+✔ [mocked] logout works when no listener was ever started (14.258077ms)
+✔ [mocked] a failed logout request is reported, not swallowed, and the session stays usable (10.037149ms)
+✔ [mocked] sync queue is published only after every SUBACK (46.187501ms)
+✔ [mocked] reconnect after socket close uses backoff, then recovers (17.548562ms)
+✔ [mocked] stopListening during a cycle must not be revived by a pending retry (race regression) (16.384888ms)
+✔ [mocked] stopListening clears timers, ends the client and is safe to call twice (21.34972ms)
+✔ [mocked] late socket 'error' after stopListening does not throw (9.571458ms)
+✔ [mocked] calling listen twice replaces the old client (no duplicate connection) (12.14378ms)
+✔ [mocked] gives up after maxReconnectAttempts and reports stop_listen (no infinite loop) (9.182964ms)
+✔ [mocked] a healthy first sync resets the backoff counter (16.256224ms)
+✔ [mocked] humanizer middleware is NOT installed by default, and is when opted in (26.861027ms)
+✔ [mocked] emitAuth stops everything and reports account_inactive (8.374336ms)
+✔ [mocked] listen(callback, options) applies reconnect options per call (12.31406ms)
+✔ package metadata: name, version, owner, entry points exist (1.413356ms)
+✔ regression: every third-party module the source requires is declared (24.539389ms)
+✔ vendored E2EE bundle: its external requires are declared too (2.38059ms)
+✔ only the pinned messagix binaries ship, native stays opt-in, no default third-party credential host (125.254664ms)
+✔ every JS file in the package parses (6235.728346ms)
+✔ [mocked] package loads with consistent exports (23.934551ms)
+✔ [mocked] login with empty options reports an error via callback and never throws (3129.536404ms)
+✔ [mocked] typing middleware is installed by default and shows typing for a command without delaying delivery (44.078959ms)
+✔ [mocked] plain chat does not trigger typing, and stopListening clears pending typing timers (16.606205ms)
+✔ [mocked] typing middleware is NOT installed when the humanizer owns typing, or when no controller exists (24.276443ms)
+✔ fingerprint: UA is the reduced Chrome/<major>.0.0.0 form and the full build only appears in client hints (2.989355ms)
+✔ humanizer: first command accepted with a bounded delay, burst inside cooldown dropped (2.724519ms)
+✔ humanizer: non-command messages pass untouched; per-thread isolation (0.56259ms)
+✔ humanizer: enabled:false never delays or drops (1.317371ms)
+✔ computeBackoff grows exponentially, is bounded and never negative (5.845535ms)
+✔ computeBackoff jitter stays within +/- jitter and clamps to max (0.418652ms)
+✔ computeBackoff tolerates garbage input (0.318463ms)
+✔ scheduleReconnect: single timer, debounce, stop, exhaustion (1.587298ms)
+✔ scheduleReconnect: a timer that fires after stop does nothing (race regression) (0.359697ms)
+✔ maxReconnectAttempts: 0 means unlimited only when explicitly set (1.961505ms)
+✔ clearListenerTimers is idempotent and clears every owned timer (0.47163ms)
+✔ detachClient: a late 'error' after detach must not throw (0.605172ms)
+✔ extractDtsg handles each supported markup shape (2.885756ms)
+✔ extractDtsg: jazoest forms, empty and non-string input (1.591823ms)
+✔ fingerprint: default UA and client hints are mutually consistent (1.64789ms)
+✔ fingerprint: Android UA yields mobile Android hints (no desktop contradiction) (0.50116ms)
+✔ typing: command-like message starts typing; plain chat / own messages / non-message events do not (1.739404ms)
+✔ typing: GoatBot prefix and extra prefixes count as commands; onlyCommands:false types for any text (0.355195ms)
+✔ typing: middleware calls next() synchronously (zero added latency) and then starts typing (1.268156ms)
+✔ typing: sending a reply clears typing after the send resolves (16.890953ms)
+✔ typing: safety timeout stops a typing indicator that never got a reply (1.652981ms)
+✔ typing: repeated starts inside minGapMs do not re-publish; after the gap they do (0.464619ms)
+✔ typing: disabled by option false, and by GoatBot enableTypingIndicator:false unless explicitly overridden (0.321804ms)
+✔ typing: configure(false) clears active timers; stopAll is idempotent and publishes nothing (0.424433ms)
+✔ typing: a throwing / rejecting sendTypingIndicator never breaks the bot (11.013855ms)
+✔ typing: withTyping shows typing around fn and clears it even when fn throws (1.512949ms)
+ℹ tests 50
+ℹ suites 0
+ℹ pass 50
+ℹ fail 0
+ℹ cancelled 0
+ℹ skipped 0
+ℹ todo 0
+```
+
+## Not verified here
+Live Facebook login, MQTT traffic, sending, reactions, typing indicator on the wire, E2EE and the bundled native binaries (no network, no account).