sagor-fca 0.0.4 → 0.0.5

package/README.md

@@ -0,0 +1,223 @@
+# 💬 sagor-fca
+
+<div align="center">
+
+**Unofficial Facebook Chat API for Node.js - The Ultimate Edition**
+
+</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:
+
+| Category | Feature | Description |
+| :--- | :--- | :--- |
+| **Core Messenger** | Full Messenger API | Send messages, files, stickers, and more. |
+| | Real-time Events | Listen to messages, reactions, and thread events. |
+| | User Account Support | Works with personal Facebook accounts (not just Pages). |
+| | AppState Support | Save login state to avoid re-authentication. |
+| | MQTT Protocol | Real-time messaging via MQTT. |
+| | TypeScript Support | Includes TypeScript definitions. |
+| **Story Interaction** | `getStories`, `reactStory`, `viewStory` | Friends' stories can be viewed, reacted to, and marked as 'Seen'. |
+| **Group Management** | `getGroupJoinRequests`, `handleGroupJoinRequest` | View and manage pending group join requests. |
+| **Feed Interaction** | `getPostInfo`, `commentOnPost` | Retrieve detailed information about a specific post and comment on it. |
+| **Advanced Messaging** | `sendVoiceMessage` | Send audio files as native voice notes. |
+| **Reels Interaction** | `getReels`, `reactReel` | Fetch and react to Facebook Reels. |
+| **Professional Mode** | `getProfessionalInfo`, `toggleProfessionalMode` | View professional profile information and toggle Professional Mode. |
+| **Security & Anti-Ban** | Request Throttling | Configurable delay between requests to avoid detection. |
+| | User-Agent Rotation | Automatic rotation of User-Agents for each request. |
+
+---
+
+## 🚀 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!");
+  });
+});
+```
+
+---
+
+## 📚 API Reference
+
+Detailed documentation for each API endpoint, including parameters and return types, can be found within the `src/api` directory of this repository. Key modules include `action`, `messaging`, `threads`, `users`, `stories`, `groups`, `feed`, `reels`, and `professional`.
+
+---
+
+## 💾 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/func/checkUpdate.js

@@ -0,0 +1,16 @@
+const logger = require("./logger");
+
+async function _checkAndUpdateVersionImpl() {
+  logger("Auto-update is disabled for fca-unofficial-updated to maintain custom fixes.", "info");
+  return;
+}
+
+function checkAndUpdateVersion(callback) {
+  if (typeof callback === "function") {
+    _checkAndUpdateVersionImpl().then(() => callback(null)).catch(err => callback(err));
+    return;
+  }
+  return _checkAndUpdateVersionImpl();
+}
+
+module.exports = { checkAndUpdateVersion };

package/func/logAdapter.js

@@ -0,0 +1,33 @@
+const logger = require("./logger");
+
+function formatArgs(args) {
+  const [prefix, msg] = args;
+
+  // Single argument: log as-is
+  if (msg === undefined) {
+    if (prefix instanceof Error) {
+      return prefix.stack || prefix.message || String(prefix);
+    }
+    return String(prefix);
+  }
+
+  // Two arguments: mimic npmlog("tag", message)
+  const tag = prefix == null ? "" : String(prefix);
+  if (msg instanceof Error) {
+    const base = msg.message || String(msg);
+    return tag ? `${tag}: ${base}` : base;
+  }
+  const text = msg == null ? "" : String(msg);
+  return tag ? `${tag}: ${text}` : text;
+}
+
+const log = {
+  info: (...args) => logger(formatArgs(args), "info"),
+  warn: (...args) => logger(formatArgs(args), "warn"),
+  error: (...args) => logger(formatArgs(args), "error"),
+  verbose: (...args) => logger(formatArgs(args), "info"),
+  silly: (...args) => logger(formatArgs(args), "info")
+};
+
+module.exports = log;
+

package/func/logger.js

@@ -0,0 +1,48 @@
+const chalk = require("chalk");
+const gradient = require("gradient-string");
+
+const themes = [
+  "blue", "dream2", "dream", "fiery", "rainbow", "pastel", "cristal", "red", "aqua", "pink", "retro", "sunlight", "teen", "summer", "flower", "ghost", "hacker"
+];
+
+function buildGradient(name) {
+  const t = String(name || "").toLowerCase();
+  if (t === "blue") return gradient([{ color: "#1affa3", pos: 0.2 }, { color: "cyan", pos: 0.4 }, { color: "pink", pos: 0.6 }, { color: "cyan", pos: 0.8 }, { color: "#1affa3", pos: 1 }]);
+  if (t === "dream2") return gradient("blue", "pink");
+  if (t === "dream") return gradient([{ color: "blue", pos: 0.2 }, { color: "pink", pos: 0.3 }, { color: "gold", pos: 0.6 }, { color: "pink", pos: 0.8 }, { color: "blue", pos: 1 }]);
+  if (t === "fiery") return gradient("#fc2803", "#fc6f03", "#fcba03");
+  if (t === "rainbow") return gradient.rainbow;
+  if (t === "pastel") return gradient.pastel;
+  if (t === "cristal") return gradient.cristal;
+  if (t === "red") return gradient("red", "orange");
+  if (t === "aqua") return gradient("#0030ff", "#4e6cf2");
+  if (t === "pink") return gradient("#d94fff", "purple");
+  if (t === "retro") return gradient.retro;
+  if (t === "sunlight") return gradient("orange", "#ffff00", "#ffe600");
+  if (t === "teen") return gradient.teen;
+  if (t === "summer") return gradient.summer;
+  if (t === "flower") return gradient("blue", "purple", "yellow", "#81ff6e");
+  if (t === "ghost") return gradient.mind;
+  if (t === "hacker") return gradient("#47a127", "#0eed19", "#27f231");
+  return gradient("#243aff", "#4687f0", "#5800d4");
+}
+
+const themeName = themes[Math.floor(Math.random() * themes.length)];
+const co = buildGradient(themeName);
+
+module.exports = (text, type) => {
+  const s = String(type || "info").toLowerCase();
+  if (s === "warn") {
+    process.stderr.write(co(`\r[ FCA-WARN ] > ${text}`) + "\n");
+    return;
+  }
+  if (s === "error") {
+    process.stderr.write(chalk.bold.hex("#ff0000")(`\r[ FCA-ERROR ]`) + ` > ${text}\n`);
+    return;
+  }
+  if (s === "info") {
+    process.stderr.write(chalk.bold(co(`\r[ FCA-SAGOR ] > ${text}`)) + "\n");
+    return;
+  }
+  process.stderr.write(chalk.bold(co(`\r[ ${s.toUpperCase()} ] > ${text}`)) + "\n");
+};

package/func/utils.js

@@ -0,0 +1,5 @@
+module.exports = {
+  sleep: function(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+};