toru-fca 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog — alpha-fca
+
+## v1.0.0 (2026-09-01) — Initial Release
+
+### 🎯 What This Is
+A clean, merged, audited Facebook Chat API built from analyzing 6 FCA variants.
+
+### ✅ Inclusions (Best-of-all merge)
+
+**From hridoy-custom (base):**
+- Full E2EE bridge with Node.js < 22 undici webidl compatibility patch
+- Self-listen filter for E2EE messages (both ID-map and cookie-UID approaches)
+- Multi-domain cookie collection for E2EE (`_cookiesFromJar`)
+- `stopped` flag on bridge to prevent reconnect loops after `disconnect()`
+- MQTT patch stream (fixes Facebook's non-standard PUBACK/SUBACK flag bits)
+- MQTT spinner + connection banner
+- `sessionGuard()` — auto-save appstate with debounce
+- Layered config system (FCA config → bot CWD config → runtime options)
+- Logout disabled (no-op) to preserve Facebook session
+- AdvancedSystem queue for controlled task execution
+
+**From hridoy-akash:**
+- Global `process.on("unhandledRejection")` handler with network-error classification
+- Global `process.on("uncaughtException")` handler (non-exit)
+- Clean `BOOL_OPTIONS` setOptions pattern
+
+**From ST-FCA (extra API methods):**
+- `sendButtons` — send interactive buttons
+- `sendFriendRequest` — send friend request
+- `searchFriends` — search friends list
+- `setActiveStatus` — set active/online status
+- `setProfileLock` — lock profile visibility
+- `storyManager` — story management utilities
+- `suggestFriend` — suggest a friend
+- `setThreadTheme` — set thread theme
+- `setStorySeen` — mark story as seen
+- `metaTheme` — Meta theme utilities
+- `note` — note utilities
+
+**Architecture improvements:**
+- Size-capped E2EE message maps (`_cappedMapSet`, cap: 2000) — prevents memory leak
+- Jittered E2EE reconnect delay (3–4s) — prevents thundering-herd on restarts
+- Fresh `sid` + `cid` on every MQTT reconnect (strips stale params from endpoint)
+- Reconnect state object (`ctx._reconnectState`) with `stopped` flag
+- `stopListenMqtt()` properly cleans up reconnect timers
+- `stopListeningAsync()` on the message emitter
+- Health monitor via `api.getHealth()`
+- Non-blocking update check via `checkUpdate.js`
+- E2EE `devicePath` parent directory auto-created on first use
+
+### ❌ Removed / Disabled
+- All background polling/automation (off by default)
+- Aggressive repeated requests
+- Unnecessary logout flows
+- Duplicate event listeners
+- Dead code from outdated API patterns
+- Third-party image upload to unknown accounts (imgbb/imagekit keys must be user-supplied)
+- Sequelize/SQLite database dependency (removed bloat)
+- `fca-unofficial` package dependency (inlined)
+
+### ⚠️ Known Limitations
+- E2EE binary (`messagix.so` / `.dll`) is pre-built for x86_64; ARM support depends on available binaries
+- Live MQTT/E2EE behavior cannot be statically tested — depends on active Facebook endpoints
+- Facebook API changes may break parsing without warning (inherent to all unofficial FCAs)

package/README.md

@@ -0,0 +1,319 @@
+# alpha-fca v1.0.0
+
+> **Ultimate Merged Facebook Chat API** — Stable Inbox · E2EE Bridge · E2EE Group · Low Automation · Clean Architecture
+
+Built by analyzing, comparing, auditing and merging the best implementations from **6 FCA variants**:
+`hridoy-akash` · `fca-unofficial` · `ST-FCA` · `fca-azad` · `mahmud-fca` · `hridoy-custom`
+
+---
+
+## ✨ Features
+
+| Feature | Status | Details |
+|---|---|---|
+| 📩 Inbox / Normal Messages | ✅ Stable | MQTT-based, auto-reconnect, no duplicate listeners |
+| 🔐 E2EE Bridge | ✅ Working | Labyrinth native bridge, auto-reconnect with jitter |
+| 👥 E2EE Group Messages | ✅ Working | Group JID detection, full event mapping |
+| 🔄 Session / Reconnect | ✅ Stable | sessionGuard, backoff reconnect, no unnecessary logouts |
+| ⚙️ Low Automation | ✅ Enforced | No background polling; automation off by default |
+| 🛡️ Error Handling | ✅ Robust | Global unhandledRejection + uncaughtException guards |
+| 🧠 Memory Safety | ✅ Capped | E2EE message maps size-capped at 2000 entries |
+| 📦 Node.js 18–22 | ✅ Compatible | undici webidl patch for Node < 22 |
+
+---
+
+## 📦 Installation
+
+```bash
+# Clone or copy the folder, then:
+npm install
+```
+
+**Requirements:**
+- Node.js >= 18.0.0
+- `build/messagix.so` (Linux) or `build/messagix.dll` (Windows) — included
+- `lib/index.mjs` — E2EE ESM bundle — included
+
+---
+
+## 🚀 Quick Start
+
+### 1. Prepare your appstate
+
+Export your Facebook cookies as JSON (using a browser extension like [c3c-fbstate](https://github.com/c3cbot/c3c-fbstate) or similar), save as `appstate.json`.
+
+### 2. Basic bot
+
+```js
+const login = require("alpha-fca");
+const fs    = require("fs");
+
+const appState = JSON.parse(fs.readFileSync("appstate.json", "utf8"));
+
+login({ appState }, { listenEvents: true, autoReconnect: true }, (err, api) => {
+  if (err) return console.error(err);
+
+  console.log("Logged in as:", api.getCurrentUserID());
+
+  // Auto-save session every 3 minutes
+  api.sessionGuard("appstate.json", { interval: 3 * 60 * 1000 });
+
+  // Listen for messages
+  api.listenMqtt((err, event) => {
+    if (err) return console.error(err);
+    if (event.type === "message") {
+      console.log(`[${event.threadID}] ${event.senderID}: ${event.body}`);
+      if (event.body === "ping") api.sendMessage("pong!", event.threadID);
+    }
+  });
+});
+```
+
+### 3. E2EE bot
+
+Enable E2EE in `config.json`:
+```json
+{
+  "e2ee": { "enable": true, "saveType": "memory" }
+}
+```
+
+Then:
+```js
+// After login:
+api.connectE2EE((err, event) => {
+  if (err) return console.error(err);
+  // event.type === "e2ee_ready" → "e2ee_fully_ready"
+  // event.type === "message" with event.isE2EE = true → E2EE message
+  if (event.type === "message" && event.isE2EE) {
+    api.sendMessage("Hello E2EE!", event.threadID);
+  }
+});
+```
+
+See `examples/e2ee-bot.js` for a complete example.
+
+---
+
+## ⚙️ Configuration (`config.json`)
+
+```json
+{
+  "automation":  { "enabled": false },
+  "inbox":       { "enabled": true },
+  "smooth":      { "enabled": false, "messageDelay": 400 },
+  "e2ee": {
+    "enable":        false,
+    "saveType":      "memory",
+    "devicePath":    "./data/e2ee-device.json",
+    "autoReconnect": true,
+    "logLevel":      "none"
+  },
+  "enableTypingIndicator": false,
+  "typingDuration": 4000
+}
+```
+
+| Key | Default | Description |
+|---|---|---|
+| `automation.enabled` | `false` | Background task automation. **Keep false.** |
+| `inbox.enabled` | `true` | Enables getThreadList / inbox access |
+| `smooth.enabled` | `false` | Shows typing indicator before sending |
+| `e2ee.enable` | `false` | Activates E2EE Labyrinth bridge |
+| `e2ee.saveType` | `"memory"` | `"memory"` = keys lost on restart · `"path"` = persistent |
+| `e2ee.devicePath` | `"./data/e2ee-device.json"` | Used only when saveType = `"path"` |
+| `enableTypingIndicator` | `false` | Auto typing indicator on sendMessage |
+
+---
+
+## 📚 API Reference
+
+### Login
+
+```js
+login(loginData, options, callback)
+// or: await login(loginData, options)
+```
+
+**loginData:**
+- `{ appState }` — cookie-based login (recommended)
+- `{ email, password }` — credentials (use appState instead)
+
+**options (defaults):**
+```js
+{
+  selfListen    : false,
+  listenEvents  : true,
+  listenTyping  : false,
+  updatePresence: false,
+  autoMarkRead  : false,
+  autoReconnect : true,
+  online        : false
+}
+```
+
+---
+
+### Messaging
+
+```js
+api.sendMessage(msg, threadID, [callback], [replyToMessageID])
+api.sendMessage({ body, attachment, sticker, emoji, mentions, url }, threadID)
+api.unsendMessage(messageID, [callback])
+api.editMessage(body, messageID, [callback])
+api.setMessageReaction(reaction, messageID, [callback])
+api.forwardMessage(messageID, threadID, [callback])
+api.forwardAttachment(attachmentID, userIDs, [callback])
+```
+
+### Threads
+
+```js
+api.getThreadList(limit, cursor, tags, [callback])
+api.getThreadInfo(threadID, [callback])
+api.getThreadHistory(threadID, amount, timestamp, [callback])
+api.createNewGroup(participantIDs, [groupTitle], [callback])
+api.addUserToGroup(userID, threadID, [callback])
+api.removeUserFromGroup(userID, threadID, [callback])
+api.changeAdminStatus(threadID, adminID, adminStatus, [callback])
+api.setTitle(newTitle, threadID, [callback])
+api.changeGroupImage(imageStream, threadID, [callback])
+api.muteThread(threadID, muteSeconds, [callback])
+api.deleteThread(threadID, [callback])
+api.changeArchivedStatus(threadID, archive, [callback])
+api.createPoll(title, threadID, options, [callback])
+api.pinMessage(messageID, threadID, [callback])
+api.markAsRead(threadID, [read], [callback])
+api.markAsDelivered(threadID, messageID, [callback])
+api.markAsSeen([callback])
+```
+
+### Users
+
+```js
+api.getUserInfo(userIDs, [callback])
+api.getUserID(name, [callback])
+api.getFriendsList([callback])
+api.handleFriendRequest(userID, accept, [callback])
+api.addFriend(userID, [callback])
+api.unfriend(userID, [callback])
+```
+
+### E2EE
+
+```js
+api.connectE2EE(callback)           // Start E2EE bridge
+api.getE2EEBridge()                 // Get live bridge instance
+api.getE2EEDeviceData([callback])   // Get E2EE device keys
+api.downloadE2EEMedia(options)      // Decrypt E2EE attachment
+api.resolveE2EEAttachment(att)      // Download + return local URL
+api.sendTypingE2EE(chatJid, bool)   // Send E2EE typing indicator
+```
+
+### Session
+
+```js
+api.sessionGuard(accountPath, { interval, debounce })
+api.getAppState()                   // Get current cookie state
+api.setOptions(options)             // Update runtime options
+api.getHealth()                     // Health status object
+```
+
+### Listening
+
+```js
+const msgEmitter = api.listenMqtt(callback)
+msgEmitter.stopListening([callback])
+await msgEmitter.stopListeningAsync()
+api.stopListenMqtt()
+```
+
+---
+
+## 🔐 E2EE Events
+
+| event.type | Description |
+|---|---|
+| `e2ee_ready` | Bridge loaded, syncing device |
+| `e2ee_fully_ready` | Ready to send/receive messages |
+| `e2ee_connected` | Transport connected |
+| `e2ee_disconnected` | Transport lost (auto-reconnects) |
+| `e2ee_device_data_changed` | Device keys updated |
+| `message` + `isE2EE: true` | Incoming E2EE message (DM or group) |
+| `e2ee_message_edit` | Message was edited |
+| `e2ee_message_reaction` | Reaction added |
+| `e2ee_receipt` | Read/delivery receipt |
+
+> **Normal and E2EE listeners never conflict.** The MQTT inbox handles normal chats; the E2EE bridge handles encrypted chats. Both can run simultaneously.
+
+---
+
+## 🔄 Session Stability
+
+alpha-fca never calls logout automatically. Session is preserved as long as:
+1. `api.sessionGuard(path)` is active (auto-saves fresh cookies)
+2. The Facebook account is not independently logged out
+
+On MQTT disconnect, auto-reconnect fires with exponential backoff (3s–60s).
+
+---
+
+## ⚠️ Limitations
+
+- **Cannot test live network behavior** — all MQTT/E2EE behavior depends on Facebook's active endpoints and your account cookies.
+- **E2EE requires** the native `build/messagix.so` (Linux) or `build/messagix.dll` (Windows) binary. These are pre-built for x86_64.
+- **Facebook API changes** may break parsing without warning — this is inherent to all unofficial FCAs.
+- **Rate limits** — avoid bulk-sending. alpha-fca does not bypass Facebook's rate limits.
+
+---
+
+## 📁 Project Structure
+
+```
+alpha-fca/
+├── index.js             # Main entry — login() function
+├── utils.js             # HTTP helpers, cookie management
+├── e2ee.js              # E2EE bridge (Labyrinth)
+├── advancedSystem.js    # Minimal task queue + health monitor
+├── checkUpdate.js       # Non-blocking version check
+├── config.json          # Default config
+├── fca-config.example.json  # Documented config template
+├── package.json
+├── README.md
+├── CHANGELOG.md
+├── build/
+│   ├── messagix.so      # E2EE native binary (Linux x86_64)
+│   └── messagix.dll     # E2EE native binary (Windows x64)
+├── lib/
+│   └── index.mjs        # E2EE ESM bundle (Labyrinth client)
+├── src/                 # API method modules (95+ files)
+│   ├── listenMqtt.js    # Core inbox listener
+│   ├── sendMessage.js   # Message sending (normal + E2EE routing)
+│   ├── OldMessage.js    # Legacy DM fallback
+│   ├── stopListenMqtt.js
+│   ├── logout.js        # No-op (session preserved)
+│   └── ... (all other FCA methods)
+└── examples/
+    ├── basic-bot.js     # Normal inbox bot
+    └── e2ee-bot.js      # E2EE + normal combined bot
+```
+
+---
+
+## 🔬 Merge Analysis
+
+| Feature | Winner | Reason |
+|---|---|---|
+| E2EE Bridge | hridoy-custom | undici Node<22 patch, self-listen filter, capped maps, stopped flag |
+| MQTT Core | hridoy-custom | MQTT patch stream, spinner, clean reconnect state |
+| Login/Session | hridoy-custom | Cookie parsing, 2FA, sessionGuard, no unnecessary logouts |
+| Error Handling | hridoy-akash | Global unhandledRejection/uncaughtException with network-specific handling |
+| Extra API Methods | ST-FCA | sendButtons, sendFriendRequest, searchFriends, setActiveStatus, etc. |
+| Low Automation | alpha-fca | All background polling disabled by default, config-driven opt-in only |
+| Config System | alpha-fca | Layered config (FCA defaults → bot CWD override → runtime options) |
+
+---
+
+## 📄 License
+
+MIT

package/advancedSystem.js

@@ -0,0 +1,95 @@
+"use strict";
+
+/**
+ * AdvancedSystem — minimal queue + health monitor for alpha-fca.
+ * Automation is OFF by default. No background polling, no aggressive requests.
+ * Only runs tasks you explicitly enqueue.
+ */
+
+const EventEmitter = require("events");
+
+class AdvancedSystem extends EventEmitter {
+  constructor(options) {
+    super();
+    options = options || {};
+    this.options = Object.assign({
+      automationEnabled: false,
+      minDelayMs: 1000,
+      maxDelayMs: 30000,
+      maxQueue: 50
+    }, options);
+    this.startedAt = Date.now();
+    this._queue = [];
+    this._running = false;
+    this._stats = { enqueued: 0, completed: 0, failed: 0 };
+  }
+
+  /** @returns {boolean} */
+  isAutomationEnabled() {
+    return this.options.automationEnabled === true;
+  }
+
+  /** Explicit opt-in only — no background automation started automatically. */
+  setAutomationEnabled(enabled) {
+    this.options.automationEnabled = Boolean(enabled);
+    this.emit("automation", this.options.automationEnabled);
+    return this.options.automationEnabled;
+  }
+
+  /** Health snapshot — safe to call anytime. */
+  health(api) {
+    const mqttClient = api && (api.mqttClient || (api.ctx && api.ctx.mqttClient));
+    return {
+      version: "1.0.0",
+      uptimeMs: Date.now() - this.startedAt,
+      automationEnabled: this.isAutomationEnabled(),
+      inboxEnabled: true,
+      mqtt: mqttClient ? {
+        connected: Boolean(mqttClient.connected),
+        reconnecting: Boolean(mqttClient.reconnecting)
+      } : null,
+      queue: { size: this._queue.length, running: this._running },
+      stats: Object.assign({}, this._stats)
+    };
+  }
+
+  /**
+   * Enqueue a task function. Runs sequentially.
+   * @param {Function} task  async () => result
+   * @returns {Promise<any>}
+   */
+  enqueue(task) {
+    if (typeof task !== "function") return Promise.reject(new TypeError("task must be a function"));
+    if (this._queue.length >= this.options.maxQueue) {
+      return Promise.reject(new Error("AdvancedSystem queue is full (" + this.options.maxQueue + ")"));
+    }
+    this._stats.enqueued++;
+    return new Promise((resolve, reject) => {
+      this._queue.push({ task, resolve, reject });
+      this._drain();
+    });
+  }
+
+  async _drain() {
+    if (this._running || this._queue.length === 0) return;
+    this._running = true;
+    while (this._queue.length > 0) {
+      const { task, resolve, reject } = this._queue.shift();
+      try {
+        const result = await task();
+        this._stats.completed++;
+        resolve(result);
+      } catch (err) {
+        this._stats.failed++;
+        reject(err);
+      }
+      // Small throttle between tasks to avoid burst requests
+      if (this._queue.length > 0) {
+        await new Promise(r => setTimeout(r, this.options.minDelayMs));
+      }
+    }
+    this._running = false;
+  }
+}
+
+module.exports = AdvancedSystem;

package/checkUpdate.js

@@ -0,0 +1,37 @@
+"use strict";
+
+const CURRENT_VERSION = "1.0.0";
+
+/**
+ * Lightweight, non-blocking update check.
+ * Only runs once per process lifetime (guarded by global._alphaFcaUpdateChecked).
+ * Never blocks login or throws on failure.
+ */
+async function checkForFCAUpdate() {
+  try {
+    // Try to fetch latest version from npm registry (or GitHub)
+    const https = require("https");
+    const pkgUrl = "https://registry.npmjs.org/hridoy-ultimate/latest";
+    const data = await new Promise((resolve) => {
+      const req = https.get(pkgUrl, { timeout: 5000 }, (res) => {
+        let body = "";
+        res.on("data", (c) => { body += c; });
+        res.on("end", () => {
+          try { resolve(JSON.parse(body)); }
+          catch (_) { resolve(null); }
+        });
+      });
+      req.on("error", () => resolve(null));
+      req.on("timeout", () => { req.destroy(); resolve(null); });
+    });
+    if (data && data.version && data.version !== CURRENT_VERSION) {
+      const log = require("npmlog");
+      log.warn("alpha-fca", `Update available: v${CURRENT_VERSION} → v${data.version}`);
+      log.warn("alpha-fca", "Run: npm update alpha-fca");
+    }
+  } catch (_) {
+    // Silently ignore — update check must never crash the bot
+  }
+}
+
+module.exports = { checkForFCAUpdate, CURRENT_VERSION };

package/config.json

@@ -0,0 +1,45 @@
+{
+  "version": "1.0.0",
+
+  "automation": {
+    "enabled": false,
+    "comment": "Keep false. Background automation disabled by default for low-automation stable operation."
+  },
+
+  "inbox": {
+    "enabled": true,
+    "comment": "Inbox/getThreadList is always active when true."
+  },
+
+  "smooth": {
+    "enabled": true,
+    "messageDelay": 400,
+    "typingDelay": 600,
+    "comment": "Smooth mode: shows typing indicator before sending. Keep false to minimize automation."
+  },
+
+  "connection": {
+    "minDelayMs": 1000,
+    "maxDelayMs": 30000,
+    "comment": "Min/max reconnect delay in ms."
+  },
+
+  "e2ee": {
+    "enable": true,
+    "saveType": "memory",
+    "devicePath": "./data/e2ee-device.json",
+    "autoReconnect": true,
+    "logLevel": "none",
+    "comment": "Set enable:true to activate E2EE bridge. saveType: 'memory' (default, keys lost on restart) or 'path' (persistent). devicePath used only when saveType='path'."
+  },
+
+  "imgKeys": {
+    "imgbb": null,
+    "ik_pub": null,
+    "ik_priv": null,
+    "comment": "Optional image hosting keys. Leave null to skip image hosting features."
+  },
+
+  "enableTypingIndicator": false,
+  "typingDuration": 4000
+}