sagor-fca 0.0.4 → 0.0.6

package/README.md

@@ -0,0 +1,426 @@
+# 💬 sagor-fca
+
+<div align="center">
+
+**Unofficial Facebook Chat API for Node.js**
+
+</div>
+
+---
+
+## 📋 Table of Contents
+
+- [⚠️ Disclaimer & Support Policy](#️-disclaimer--support-policy)
+- [✨ Features](#-features)
+- [🚀 Quick Start](#-quick-start)
+- [📚 API Reference](#-api-reference)
+- [💾 AppState Management](#-appstate-management)
+- [🔄 Auto Login](#-auto-login)
+- [🔐 Security & Anti-Ban](#-security--anti-ban)
+- [🤝 Contributing](#-contributing)
+- [📄 License](#-license)
+- [👨‍💻 Author](#-author)
+
+---
+
+## ⚠️ Disclaimer & Support Policy
+
+<div align="center">
+
+**READ THIS BEFORE USING OR OPENING AN ISSUE.**
+
+</div>
+
+This repository is provided **"AS IS"** and is entirely open-source. By using this project, you explicitly agree to the following terms:
+
+1.  **Use at your own risk:** We are NOT responsible if your account gets banned for spammy activities (sending messages too fast, unsolicited mass messaging, suspicious URLs, or rapid login/logout).
+2.  **No Spoon-Feeding:** This is a tool for developers. If you cannot read source code, navigate directories, or use basic search tools (`Ctrl + Shift + F`), you should not be using this library.
+3.  **No Free Programming Lessons:** The maintainers provide core updates and security patches for the community for free. We do **not** provide free JavaScript/TypeScript tutorials, nor will we tell you exactly which line of code to edit for your specific bot.
+4.  **Custom Features = Paid Service:** Brainpower and time are not free. If you need custom logic, reverse-engineer specific endpoints, or 1-on-1 support for your personal project, **that is a paid service**.
+
+If you do not agree with this policy, you are free to fork the repository and maintain it yourself.
+
+**Recommendations to minimize ban risks:**
+
+-   Utilize **AppState** over direct email/password authentication whenever possible.
+-   Implement strict **rate limiting** within your bot's operations.
+-   Ensure your application adheres to Facebook's platform policies.
+
+---
+
+## ✨ Features
+
+This **sagor-fca** extends the base functionality with advanced features for a more robust and versatile Facebook automation experience:
+
+**Authentication**
+- Cookie array login (`appState`) — the safest method for long-running bots
+- Email/password login with TOTP/2FA support
+- Session fingerprint locking — User-Agent, Sec-Ch-Ua, locale, timezone locked per session to prevent detection
+- AppState auto-backup and restore on restart
+
+**Real-time Messaging**
+- MQTT and HTTP messaging with automatic protocol fallback
+- Send text, attachments, stickers, emoji, mentions, and location
+- Message editing, unsend, forward, and delete
+- Message reactions via HTTP and MQTT
+- Pin/unpin messages, list pinned messages
+
+**Anti-Suspension System**
+- Circuit breaker — halts activity after repeated suspension signals, resumes after cooldown
+- 60+ suspension signal patterns: checkpoints, spam flags, rate limits, identity verification, policy violations, session expiry, and more
+- Adaptive per-thread delay that increases with session volume
+- Hourly and daily message volume limits with automatic warning pauses
+- Warmup mode for fresh sessions — gradually increases allowed message rate
+- Humanized typing simulation before every send
+- Randomized request intervals and jitter to avoid periodicity detection
+- Session fingerprint locking to maintain consistent browser identity
+- PostSafe guard: detects auth failures and checkpoint responses in real-time
+- MQTT watchdog: detects stale connections and forces clean reconnect
+
+**Stability & Reliability**
+- MQTT auto-reconnect with exponential backoff and jitter
+- Auto re-login using refreshed AppState when session expires
+- TokenRefreshManager with randomized intervals to keep sessions alive
+- Sliding-window rate limiter with per-endpoint tracking
+- SQLite-backed thread and user data cache for fast lookups
+
+**Thread & Group Management**
+- Get thread info, history, pictures, and lists
+- Create groups, add/remove members, change admin status
+- Update group image, name, color, emoji
+- Archive, mute, delete threads
+- Create polls, manage notes and rules
+- Search threads by name, handle message requests
+
+**User & Friends**
+- Get user info (basic and extended), resolve user IDs
+- Get full friends list, send/cancel friend requests, unfriend, block/unblock
+
+**Social**
+- Comment on posts, share posts, follow/unfollow users
+
+**Themes & Stickers**
+- Browse 90+ Messenger themes, apply themes via MQTT
+- Generate AI-powered themes with text prompts
+- Search stickers, browse packs, add packs, get AI stickers
+
+**E2EE (Opt-In)**
+- Application-layer end-to-end encryption for DMs using X25519 + HKDF + AES-256-GCM
+
+**Monitoring**
+- `api.getHealthStatus()` — MQTT status, token refresh stats, rate limiter metrics
+- Built-in `ProductionMonitor` for request/error/performance telemetry
+
+**Proxy Support**
+- Full proxy support via the `proxy` login option
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+To install `sagor-fca`, ensure you have Node.js (version 12.0.0 or higher) installed. Then, use npm:
+
+```bash
+npm install sagor-fca
+```
+
+### Basic Usage (Echo Bot)
+
+Here's a simple example to get started with an echo bot:
+
+```javascript
+const login = require("sagor-fca");
+
+login({ appState: [] }, (err, api) => {
+  if (err) return console.error(err);
+
+  api.listenMqtt((err, event) => {
+    if (err) return console.error(err);
+
+    if (event.type === "message") {
+      api.sendMessage(event.body, event.threadID);
+    }
+  });
+});
+```
+
+### Sending a Text Message
+
+```javascript
+const login = require("sagor-fca");
+
+login({ appState: [] }, (err, api) => {
+  if (err) {
+    console.error("Login Error:", err);
+    return;
+  }
+
+  const yourID = "000000000000000"; // Replace with actual Facebook ID
+  const msg = "Hello from Sagor-fca! 👋";
+
+  api.sendMessage(msg, yourID, (err) => {
+    if (err) console.error("Message Sending Error:", err);
+    else console.log("✅ Message sent successfully!");
+  });
+});
+```
+
+---
+
+## Anti-Suspension Configuration
+
+The anti-suspension system is active by default. You can tune it through login options:
+
+```js
+login({ appState }, {
+  autoReconnect: true,
+  listenEvents: true,
+  autoMarkRead: true,
+  simulateTyping: true,       // humanized typing delays before send
+  randomUserAgent: true,      // rotate user agent on each session
+  persona: "desktop",         // "desktop" or "android"
+  maxConcurrentRequests: 5,   // max parallel HTTP requests
+  maxRequestsPerMinute: 50,   // sliding-window rate cap
+  requestCooldownMs: 60000,   // per-endpoint cooldown duration
+  errorCacheTtlMs: 300000     // how long to suppress repeated errors
+}, (err, api) => {
+  if (err) throw err;
+
+  console.log(api.getHealthStatus());
+});
+```
+
+
+## API Reference
+
+### Authentication
+| Method | Description |
+|---|---|
+| `login(credentials, options, callback)` | Log in and receive the API object |
+| `api.logout()` | End the session |
+| `api.getAppState()` | Get current session cookies |
+| `api.getCurrentUserID()` | Get logged-in user ID |
+
+### Messaging
+| Method | Description |
+|---|---|
+| `api.sendMessage(msg, threadID)` | Send (HTTP + MQTT fallback) |
+| `api.sendMessageMqtt(msg, threadID)` | Send over MQTT |
+| `api.editMessage(text, messageID)` | Edit a message |
+| `api.unsendMessage(messageID, threadID)` | Retract a message |
+| `api.forwardMessage(messageID, threadID)` | Forward a message |
+| `api.deleteMessage(messageIDs)` | Delete locally |
+| `api.shareContact(senderID, threadID)` | Share a contact card |
+
+### Reactions & Status
+| Method | Description |
+|---|---|
+| `api.setMessageReaction(reaction, messageID)` | React via HTTP |
+| `api.setMessageReactionMqtt(reaction, messageID, threadID)` | React via MQTT |
+| `api.sendTypingIndicator(isTyping, threadID)` | Show/hide typing |
+| `api.markAsRead(threadID)` | Mark thread as read |
+| `api.markAsReadAll()` | Mark all threads as read |
+| `api.markAsSeen()` | Mark as seen |
+| `api.markAsDelivered(threadID, messageID)` | Mark as delivered |
+
+### Threads
+| Method | Description |
+|---|---|
+| `api.getThreadInfo(threadID)` | Thread metadata |
+| `api.getThreadList(limit, timestamp, tags)` | List threads |
+| `api.getThreadHistory(threadID, amount, timestamp)` | Message history |
+| `api.getThreadPictures(threadID, offset, limit)` | Thread images |
+| `api.searchForThread(name)` | Search by name |
+| `api.createNewGroup(participantIDs, name?)` | Create group |
+| `api.deleteThread(threadID)` | Delete thread |
+| `api.muteThread(threadID, muteSeconds)` | Mute thread |
+| `api.changeArchivedStatus(threadID, archive)` | Archive/unarchive |
+| `api.pinMessage(action, threadID, messageID?)` | Pin/unpin/list |
+| `api.createPoll(title, threadID, options?)` | Create poll |
+| `api.handleMessageRequest(threadID, accept)` | Accept/decline |
+
+### Group Admin
+| Method | Description |
+|---|---|
+| `api.addUserToGroup(userID, threadID)` | Add member |
+| `api.removeUserFromGroup(userID, threadID)` | Remove member |
+| `api.changeAdminStatus(threadID, userID, isAdmin)` | Promote/demote |
+| `api.changeGroupImage(image, threadID)` | Group photo |
+| `api.gcname(name, threadID)` | Rename group |
+
+### Users
+| Method | Description |
+|---|---|
+| `api.getUserInfo(id)` | Basic user info |
+| `api.getUserInfoV2(id)` | Extended user info |
+| `api.getUserID(name)` | Resolve name to ID |
+| `api.getFriendsList()` | Friends list |
+| `api.getBotInfo()` | Bot account info |
+
+### Themes & Customization
+| Method | Description |
+|---|---|
+| `api.getTheme(threadID)` | List available themes |
+| `api.getThemeInfo(threadID)` | Current theme |
+| `api.setThreadThemeMqtt(threadID, themeID)` | Apply theme |
+| `api.createAITheme(prompt)` | AI theme |
+| `api.changeThreadColor(color, threadID)` | Thread color |
+| `api.changeThreadEmoji(emoji, threadID)` | Thread emoji |
+| `api.nickname(nickname, threadID, participantID)` | Set nickname |
+| `api.emoji(emoji, threadID)` | Thread emoji shorthand |
+
+### Stickers
+| Method | Description |
+|---|---|
+| `api.stickers.search(query)` | Search stickers |
+| `api.stickers.listPacks()` | Installed packs |
+| `api.stickers.getStorePacks()` | Sticker store |
+| `api.stickers.addPack(packID)` | Add pack |
+| `api.stickers.getStickersInPack(packID)` | Stickers in pack |
+| `api.stickers.getAiStickers(options?)` | AI stickers |
+
+### E2EE
+| Method | Description |
+|---|---|
+| `api.e2ee.enable()` | Enable E2EE |
+| `api.e2ee.disable()` | Disable E2EE |
+| `api.e2ee.getPublicKey()` | Get public key |
+| `api.e2ee.setPeerKey(threadID, key)` | Set peer key |
+| `api.e2ee.hasPeer(threadID)` | Has peer key |
+| `api.e2ee.clearPeerKey(threadID)` | Remove peer key |
+
+### Social
+| Method | Description |
+|---|---|
+| `api.comment(msg, postID)` | Comment on post |
+| `api.share(postID)` | Share post |
+| `api.follow(userID, follow)` | Follow/unfollow |
+| `api.unfriend(userID)` | Unfriend |
+| `api.changeBlockedStatus(userID, block)` | Block/unblock |
+
+### Health
+| Method | Description |
+|---|---|
+| `api.getHealthStatus()` | MQTT, token, rate limiter stats |
+
+---
+
+## Login Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `online` | `boolean` | `true` | Appear online |
+| `selfListen` | `boolean` | `false` | Receive own messages |
+| `listenEvents` | `boolean` | `true` | Receive thread events |
+| `listenTyping` | `boolean` | `false` | Receive typing events |
+| `updatePresence` | `boolean` | `false` | Broadcast presence |
+| `autoMarkDelivery` | `boolean` | `false` | Auto-mark delivered |
+| `autoMarkRead` | `boolean` | `true` | Auto-mark read |
+| `autoReconnect` | `boolean` | `true` | MQTT auto-reconnect |
+| `simulateTyping` | `boolean` | `true` | Humanized typing delays |
+| `randomUserAgent` | `boolean` | `false` | Random User-Agent |
+| `persona` | `"desktop"\|"android"` | `"desktop"` | Browser persona |
+| `proxy` | `string` | — | Proxy URL |
+| `forceLogin` | `boolean` | `false` | Force fresh login |
+| `maxConcurrentRequests` | `number` | `5` | Max parallel requests |
+| `maxRequestsPerMinute` | `number` | `50` | Rate cap per minute |
+| `requestCooldownMs` | `number` | `60000` | Endpoint cooldown |
+| `errorCacheTtlMs` | `number` | `300000` | Error suppression TTL |
+| `stealthMode` | `boolean` | `false` | Extra stealth headers |
+
+---
+
+
+## 💾 AppState Management
+
+AppState is crucial for maintaining login sessions without re-authenticating with email/password. It helps prevent frequent logouts and reduces the risk of account flags.
+
+### Saving AppState
+
+```javascript
+const fs = require("fs");
+const login = require("sagor-fca");
+
+login({ email: "YOUR_EMAIL", password: "YOUR_PASSWORD" }, (err, api) => {
+  if (err) {
+    console.error("Login Error:", err);
+    return;
+  }
+
+  try {
+    const appState = JSON.stringify(api.getAppState(), null, 2);
+    fs.writeFileSync("appstate.json", appState);
+    console.log("✅ AppState saved successfully!");
+  } catch (error) {
+    console.error("❌ Error saving AppState:", error);
+  }
+});
+```
+
+### Using Saved AppState
+
+```javascript
+const fs = require("fs");
+const login = require("sagor-fca");
+
+login(
+  { appState: JSON.parse(fs.readFileSync("appstate.json", "utf8")) },
+  (err, api) => {
+    if (err) {
+      console.error("Login Error:", err);
+      return;
+    }
+
+    console.log("✅ Logged in successfully using AppState!");
+    // Your bot logic here
+  },
+);
+```
+
+---
+
+## 🔄 Auto Login
+
+This library supports automatic re-login if your session expires, ensuring continuous operation of your bot. Configure `fca-config.json` in your project root:
+
+```json
+{
+  "autoLogin": true,
+  "credentials": {
+    "email": "YOUR_EMAIL_OR_PHONE",
+    "password": "YOUR_PASSWORD",
+    "twofactor": "" // Base32 secret for 2FA, leave empty if not used
+  }
+}
+```
+
+If `autoLogin` is `true` and credentials are provided, the library will attempt to re-authenticate if the current session becomes invalid.
+
+---
+
+## 🔐 Security & Anti-Ban
+
+To enhance the longevity and stability of your bot, `sagor-fca` includes built-in anti-ban measures:
+
+-   **Request Throttling:** A default delay of 500ms is introduced between API requests. This can be configured in `src/utils/request/config.js` via `requestThrottlingMs`.
+-   **User-Agent Rotation:** The library automatically rotates through a list of up-to-date browser User-Agents (as of March 2026) to mimic legitimate browser traffic, reducing the likelihood of detection and blocking by Facebook.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! If you have suggestions for improvements, new features, or bug fixes, please feel free to open an issue or submit a pull request to the repository.
+
+---
+
+## 📄 License
+
+This project is open-source and available under the [MIT License](LICENSE).
+
+---
+
+## 👨‍💻 Author
+
+Developed and maintained by **SAGOR**.

package/examples/login-with-cookies.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Example: Login with Cookie Array
+ *
+ * Demonstrates how to authenticate using a browser cookie array
+ * instead of email/password credentials.
+ *
+ * Usage:
+ *   1. Export cookies from your browser (c_user, xs, fr, datr)
+ *   2. Replace the placeholder values below
+ *   3. Run: node examples/login-with-cookies.js
+ */
+
+const { login } = require("goat-fca");
+
+const cookieArray = [
+  { name: "c_user", value: "YOUR_USER_ID_HERE" },
+  { name: "xs",     value: "YOUR_XS_TOKEN_HERE" },
+  { name: "fr",     value: "YOUR_FR_TOKEN_HERE" },
+  { name: "datr",   value: "YOUR_DATR_TOKEN_HERE" }
+];
+
+login({ appState: cookieArray }, {
+  listenEvents: true,
+  autoMarkRead: true,
+  selfListen: false
+}, (err, api) => {
+  if (err) return console.error("Login failed:", err);
+
+  console.log("Logged in as:", api.getCurrentUserID());
+
+  api.listenMqtt((err, event) => {
+    if (err || event.type !== "message" || !event.body) return;
+    console.log("Message from", event.senderID, ":", event.body);
+  });
+});

package/examples/ping.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Example: Simple Ping Bot
+ *
+ * Listens for "/ping" in any thread and replies with "pong!".
+ *
+ * Usage:
+ *   1. Save your cookies to appstate.json
+ *   2. Run: node examples/ping.js
+ */
+
+const fs = require("fs");
+const { login } = require("goat-fca");
+
+const appState = JSON.parse(fs.readFileSync("appstate.json", "utf8"));
+
+login({ appState }, {
+  online: true,
+  listenEvents: true,
+  autoReconnect: true,
+  simulateTyping: true
+}, (err, api) => {
+  if (err) return console.error("Login error:", err);
+
+  console.log("Logged in as:", api.getCurrentUserID());
+
+  api.listenMqtt((err, event) => {
+    if (err || event.type !== "message" || !event.body) return;
+
+    if (event.body.toLowerCase() === "/ping") {
+      api.sendMessage("pong!", event.threadID);
+    }
+  });
+});

package/examples/verify.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Quick sanity check — verifies the library loads correctly and
+ * prints the anti-suspension and rate limiter configuration. Run with:
+ *   node examples/verify.js
+ */
+
+const fca = require("goat-fca");
+const { globalAntiSuspension } = require("goat-fca/src/utils/antiSuspension");
+const { globalRateLimiter } = require("goat-fca/src/utils/rateLimiter");
+
+console.log("goat-fca Library Verification");
+console.log("==============================\n");
+
+console.log("Library entry point:", typeof fca.login === "function" ? "OK" : "FAIL");
+
+const config = globalAntiSuspension.getConfig();
+console.log("\nAnti-Suspension Configuration:");
+console.log(`  Message Delay       : ${config.messageDelayMs}ms`);
+console.log(`  Thread Delay        : ${config.threadDelayMs}ms`);
+console.log(`  Max Login Tries     : ${config.maxLoginAttempts}`);
+console.log(`  Login Cooldown      : ${config.loginCooldownMs}ms`);
+console.log(`  Daily Msg Limit     : ${config.dailyStats.maxDailyMessages}`);
+console.log(`  Hourly Msg Limit    : ${config.hourlyStats.maxPerHour}`);
+
+console.log("\nEnabled Features:");
+Object.entries(config.features).forEach(([feature, enabled]) => {
+  console.log(`  ${enabled ? "[x]" : "[ ]"} ${feature}`);
+});
+
+const activityPattern = globalAntiSuspension.getRealisticActivityPattern();
+console.log("\nActivity Pattern:");
+console.log(`  Current activity  : ${activityPattern.messageFrequency}`);
+console.log(`  Next action delay : ${activityPattern.nextActionDelayMs.toFixed(0)}ms`);
+console.log(`  Is active hours   : ${activityPattern.isActiveHours}`);
+
+console.log("\nCircuit Breaker:");
+console.log(`  Tripped           : ${globalAntiSuspension.isCircuitBreakerTripped()}`);
+console.log(`  Signal count      : ${globalAntiSuspension.suspensionCircuitBreaker.signalCount}`);
+
+const rateLimiterStats = globalRateLimiter.getStats();
+console.log("\nRate Limiter:");
+console.log(`  Max concurrent    : ${rateLimiterStats.maxConcurrentRequests}`);
+console.log(`  Max per minute    : ${rateLimiterStats.maxRequestsPerMinute}`);
+console.log(`  Requests (1 min)  : ${rateLimiterStats.requestsInLastMinute}`);
+
+const testSignals = [
+  { text: "Everything is fine, message sent", expectSuspicion: false },
+  { text: "Your account has been suspended due to policy violation", expectSuspicion: true },
+  { text: "checkpoint required to verify identity", expectSuspicion: true },
+  { text: "Too many requests - rate limited", expectSuspicion: true },
+  { text: "Unusual activity detected on your account", expectSuspicion: true },
+];
+console.log("\nSuspension Signal Detection:");
+testSignals.forEach(({ text, expectSuspicion }) => {
+  globalAntiSuspension.resetCircuitBreaker();
+  const detected = globalAntiSuspension.detectSuspensionSignal(text);
+  const passed = detected === expectSuspicion;
+  globalAntiSuspension.resetCircuitBreaker();
+  console.log(`  ${passed ? "[x]" : "[!]"} "${text.substring(0, 40)}" → ${detected ? "SUSPICIOUS" : "CLEAN"}`);
+});
+globalAntiSuspension.resetCircuitBreaker();
+
+console.log("\nAll checks passed. Library is ready to use.");
+console.log("==============================\n");
+
+process.exit(0);