sagor-fca 0.0.9 → 0.0.10

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/.github/workflows/SaGor.yml

@@ -0,0 +1,22 @@
+name: "publish npm by SaGor"
+
+on: push
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v2
+        with:
+          node-version: 16
+          registry-url: https://registry.npmjs.org
+
+      - name: Publish to NPM
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phạm Minh Đồng (DongDev)
+
+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/README.md

@@ -1,8 +1,10 @@
-# 💬 sagor-fca
-
 <div align="center">
 
-**Unofficial Facebook Chat API for Node.js**
+#   sagor-nx-fca
+
+**Unofficial Facebook Chat API for Node.js** - Interact with Facebook Messenger programmatically
+
+[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Support](#-author--support)
 
 </div>
 
@@ -11,15 +13,21 @@
 ## 📋 Table of Contents
 
 - [⚠️ Disclaimer & Support Policy](#️-disclaimer--support-policy)
+- [⚡ Why this fork?](#-why-this-fork)
 - [✨ Features](#-features)
+- [🔍 Introduction](#-introduction)
+- [📦 Installation](#-installation)
 - [🚀 Quick Start](#-quick-start)
-- [📚 API Reference](#-api-reference)
+- [📝 Message Types](#-message-types)
 - [💾 AppState Management](#-appstate-management)
 - [🔄 Auto Login](#-auto-login)
-- [🔐 Security & Anti-Ban](#-security--anti-ban)
+- [👂 Listening for Messages](#-listening-for-messages)
+- [🎯 API Quick Reference](#-api-quick-reference)
+- [📚 Documentation](#-documentation)
+- [🛠️ Projects Using This API](#️-projects-using-this-api)
 - [🤝 Contributing](#-contributing)
 - [📄 License](#-license)
-- [👨‍💻 Author](#-author)
+- [👨‍💻 Author & Support](#-author--support)
 
 ---
 
@@ -33,60 +41,82 @@
 
 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**.
+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:** I maintain the core updates and security patches for the community for free. I do **not** provide free JavaScript/TypeScript tutorials, nor will I 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 me to write custom logic, reverse-engineer specific endpoints, or provide 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.
+If you don't like this policy, feel free to fork the repository and maintain it yourself.
 
-**Recommendations to minimize ban risks:**
+**Recommendations to avoid bans:**
 
--   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.
+- Use **Firefox** or the [fca.dongdev.id.vn](https://fca.dongdev.id.vn) flow to reduce logout issues (especially on iOS).
+- Prefer **AppState** over email/password when possible.
+- Use strict **rate limiting** in your bots.
 
 ---
 
-## ✨ Features
+## ⚡ Why this fork?
 
-This **sagor-fca** extends the base functionality with advanced features for a more robust and versatile Facebook automation experience:
+Unlike other outdated forks, `@sagor/fca-unofficial` is built with a focus on **real-world practicality and performance**:
 
-| 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. |
+- **Performance First:** Stripped out legacy, redundant code that causes technical debt.
+- **Modernized Architecture:** Adapted to the latest Facebook backend structure.
+- **Clean Logic:** No messy wrappers. The codebase is straightforward and easy to navigate if you actually open the files.
 
 ---
 
-## 🚀 Quick Start
+## ✨ Features
+
+- ✅ **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
+- ✅ **Active Development** - Regularly updated and maintained
+
+---
+
+## 🔍 Introduction
 
-### Installation
+Facebook provides an [official API for chat bots](https://developers.facebook.com/docs/messenger-platform), but it's **only available for Facebook Pages**.
 
-To install `sagor-fca`, ensure you have Node.js (version 12.0.0 or higher) installed. Then, use npm:
+`@sagor/fca-unofficial` is the API that allows you to automate chat functionalities on a **user account** by emulating the browser. This means:
+
+- 🔄 Making the exact same GET/POST requests as a browser
+- 🔐 Does not work with auth tokens
+- 📝 Requires Facebook account credentials (email/password) or AppState
+
+**Perfect for:**
+
+- 🤖 Building chatbots
+- 📱 Automating message responses
+- 🔔 Creating notification systems
+- 🎮 Building interactive games
+- 📊 Analytics and monitoring
+
+---
+
+## 📦 Installation
 
 ```bash
-npm install sagor-fca
+npm install @sagor/fca-unofficial@latest
 ```
 
-### Basic Usage (Echo Bot)
+**Requirements:**
+
+- Node.js >= 12.0.0
+- Active Facebook account
 
-Here's a simple example to get started with an echo bot:
+---
+
+## 🚀 Quick Start
+
+### 1️⃣ Login and Simple Echo Bot
 
 ```javascript
-const login = require("sagor-fca");
+const login = require("@sagor/fca-unofficial");
 
 login({ appState: [] }, (err, api) => {
   if (err) return console.error(err);
@@ -94,6 +124,7 @@ login({ appState: [] }, (err, api) => {
   api.listenMqtt((err, event) => {
     if (err) return console.error(err);
 
+    // Echo back the received message
     if (event.type === "message") {
       api.sendMessage(event.body, event.threadID);
     }
@@ -101,10 +132,10 @@ login({ appState: [] }, (err, api) => {
 });
 ```
 
-### Sending a Text Message
+### 2️⃣ Send Text Message
 
 ```javascript
-const login = require("sagor-fca");
+const login = require("@sagor/fca-unofficial");
 
 login({ appState: [] }, (err, api) => {
   if (err) {
@@ -113,7 +144,7 @@ login({ appState: [] }, (err, api) => {
   }
 
   const yourID = "000000000000000"; // Replace with actual Facebook ID
-  const msg = "Hello I'm SaGor bot👋";
+  const msg = "Hey! 👋";
 
   api.sendMessage(msg, yourID, (err) => {
     if (err) console.error("Message Sending Error:", err);
@@ -122,25 +153,72 @@ login({ appState: [] }, (err, api) => {
 });
 ```
 
+> **💡 Tip:** To find your Facebook ID, look inside the cookies under the name `c_user`
+
+### 3️⃣ Send File/Image
+
+```javascript
+const login = require("@sagor/fca-unofficial");
+const fs = require("fs");
+
+login({ appState: [] }, (err, api) => {
+  if (err) {
+    console.error("Login Error:", err);
+    return;
+  }
+
+  const yourID = "000000000000000";
+  const imagePath = __dirname + "/image.jpg";
+
+  // Check if file exists
+  if (!fs.existsSync(imagePath)) {
+    console.error("❌ Error: Image file not found!");
+    return;
+  }
+
+  const msg = {
+    body: "Check out this image! 📷",
+    attachment: fs.createReadStream(imagePath),
+  };
+
+  api.sendMessage(msg, yourID, (err) => {
+    if (err) console.error("Message Sending Error:", err);
+    else console.log("✅ Image sent successfully!");
+  });
+});
+```
+
 ---
 
-## 📚 API Reference
+## 📝 Message Types
+
+| Type             | Usage                                       | Example                                            |
+| ---------------- | ------------------------------------------- | -------------------------------------------------- |
+| **Regular text** | `{ body: "message text" }`                  | `{ body: "Hello!" }`                               |
+| **Sticker**      | `{ sticker: "sticker_id" }`                 | `{ sticker: "369239263222822" }`                   |
+| **File/Image**   | `{ attachment: fs.createReadStream(path) }` | `{ attachment: fs.createReadStream("image.jpg") }` |
+| **URL**          | `{ url: "https://example.com" }`            | `{ url: "https://github.com" }`                    |
+| **Large emoji**  | `{ emoji: "👍", emojiSize: "large" }`       | `{ emoji: "👍", emojiSize: "large" }`              |
 
-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`.
+> **📌 Note:** A message can only be a regular message (which can be empty) and optionally **one of the following**: a sticker, an attachment, or a URL.
+
+**Emoji sizes:** `small` | `medium` | `large`
 
 ---
 
 ## 💾 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.
+### Save AppState
 
-### Saving AppState
+Save your login session to avoid re-authentication:
 
 ```javascript
 const fs = require("fs");
-const login = require("sagor-fca");
+const login = require("@sagor/fca-unofficial");
+
+const credentials = { email: "YOUR_EMAIL", password: "YOUR_PASSWORD" }; // Or use existing appState
 
-login({ email: "YOUR_EMAIL", password: "YOUR_PASSWORD" }, (err, api) => {
+login(credentials, (err, api) => {
   if (err) {
     console.error("Login Error:", err);
     return;
@@ -156,11 +234,13 @@ login({ email: "YOUR_EMAIL", password: "YOUR_PASSWORD" }, (err, api) => {
 });
 ```
 
-### Using Saved AppState
+### Use Saved AppState
+
+Load your saved AppState for faster login:
 
 ```javascript
 const fs = require("fs");
-const login = require("sagor-fca");
+const login = require("@sagor/fca-unofficial");
 
 login(
   { appState: JSON.parse(fs.readFileSync("appstate.json", "utf8")) },
@@ -170,8 +250,8 @@ login(
       return;
     }
 
-    console.log("✅ Logged in successfully using AppState!");
-    // Your bot logic here
+    console.log("✅ Logged in successfully!");
+    // Your code here
   },
 );
 ```
@@ -180,44 +260,265 @@ login(
 
 ## 🔄 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:
+When your session (AppState) expires, the library can **automatically re-login** using credentials from a config file, so your bot can keep running without manual intervention.
+
+1. Create **`fca-config.json`** in your project root (same folder as where you run `node`):
 
 ```json
 {
   "autoLogin": true,
+  "apiServer": "https://minhdong.site",
+  "apiKey": "",
   "credentials": {
     "email": "YOUR_EMAIL_OR_PHONE",
     "password": "YOUR_PASSWORD",
-    "twofactor": "" // Base32 secret for 2FA, leave empty if not used
+    "twofactor": ""
   }
 }
 ```
 
-If `autoLogin` is `true` and credentials are provided, the library will attempt to re-authenticate if the current session becomes invalid.
+2. **Log in with AppState** as usual. If the session later expires (e.g. Facebook invalidates cookies), the library will use `credentials` (and optionally the external `apiServer`) to log in again and retry the request.
+
+- Set **`autoLogin`** to `false` to disable automatic re-login.
+- **`twofactor`**: Base32 secret for 2FA (not the 6-digit code). Leave empty if you do not use 2FA.
+- **`apiServer`** / **`apiKey`**: Optional; used for external iOS-style login. Default server is `https://minhdong.site`.
+
+Keep **`fca-config.json`** out of version control (add it to `.gitignore`) since it contains credentials.
+
+---
+
+## 🔐 Security, Trust & Supply Chain
+
+- Published via **GitHub Actions** using `npm publish --provenance`, so the tarball on npm can be cryptographically tied back to this repo.
+- Core runtime code in `module/` and `src/` is **readable JavaScript** with no obfuscated logic.
+- Legacy forks (such as Horizon) are kept only for reference and are **not** shipped in the npm package.
+- No telemetry or hidden network calls:
+  - All HTTP traffic is implemented in `src/utils/request.js` and `module/loginHelper.js`.
+  - External URLs (such as `apiServer` or proxies) are fully user‑configurable.
+- The npm publish account uses **2FA** and dedicated automation tokens.
+
+See `SECURITY.md` for more details.
+
+---
+
+## 👂 Listening for Messages
+
+### Echo Bot with Stop Command
+
+```javascript
+const fs = require("fs");
+const login = require("@sagor/fca-unofficial");
+
+login(
+  { appState: JSON.parse(fs.readFileSync("appstate.json", "utf8")) },
+  (err, api) => {
+    if (err) return console.error("Login Error:", err);
+
+    // Enable listening to events (join/leave, title change, etc.)
+    api.setOptions({ listenEvents: true });
+
+    const stopListening = api.listenMqtt((err, event) => {
+      if (err) return console.error("Listen Error:", err);
+
+      // Mark as read
+      api.markAsRead(event.threadID, (err) => {
+        if (err) console.error("Mark as read error:", err);
+      });
+
+      // Handle different event types
+      switch (event.type) {
+        case "message":
+          if (event.body && event.body.trim().toLowerCase() === "/stop") {
+            api.sendMessage("Goodbye… 👋", event.threadID);
+            stopListening();
+            return;
+          }
+          api.sendMessage(`🤖 BOT: ${event.body}`, event.threadID);
+          break;
+
+        case "event":
+          console.log("📢 Event Received:", event);
+          break;
+      }
+    });
+  },
+);
+```
+
+### Listen Options
+
+Configure listening behavior:
+
+```javascript
+api.setOptions({
+  listenEvents: true, // Receive events (join/leave, rename, etc.)
+  selfListen: true, // Receive messages from yourself
+  logLevel: "silent", // Disable logs (silent/error/warn/info/verbose)
+});
+```
+
+---
+
+## 🎯 API Quick Reference
+
+_(For full details, please read the source code or `DOCS.md`)_
+
+### 📨 Messaging
+
+`sendMessage`, `sendTypingIndicator`, `getMessage`, `editMessage`, `deleteMessage`, `unsendMessage`, `setMessageReaction`, `forwardAttachment`, `uploadAttachment`, `createPoll`
+
+### 📬 Read Receipt & Delivery
+
+`markAsRead`, `markAsReadAll`, `markAsDelivered`, `markAsSeen`
+
+### 👥 Thread Management
+
+`getThreadInfo`, `getThreadList`, `getThreadHistory`, `deleteThread`, `changeThreadColor`, `changeThreadEmoji`, `changeGroupImage`, `setTitle`, `changeNickname`
+
+### 👤 User & Group Management
+
+`getUserInfo`, `getFriendsList`, `getCurrentUserID`, `createNewGroup`, `addUserToGroup`, `removeUserFromGroup`, `changeAdminStatus`
+
+### ⚙️ Thread Settings & Actions
+
+`muteThread`, `changeArchivedStatus`, `changeBlockedStatus`, `handleMessageRequest`, `changeAvatar`, `changeBio`, `handleFriendRequest`, `unfriend`
+
+### 🔐 Auth & Listening
+
+`logout`, `getAppState`, `setOptions`, `listenMqtt`
+
+---
+## 🎛 Event Hooks & Remote Control (Advanced)
+
+Starting from `3.x`, the API instance also behaves like an **EventEmitter** for lifecycle and remote‑control events:
+
+- **Lifecycle events**:
+  - `sessionExpired` — login session is no longer valid, auto‑login will be attempted (if configured).
+  - `autoLoginSuccess` — auto‑login succeeded and the failed request will be retried.
+  - `autoLoginFailed` — auto‑login could not recover the session.
+  - `checkpoint` — generic checkpoint, with subtype in `{ type: "282" | "956" | "scraping_warning" }`.
+  - `checkpoint_282`, `checkpoint_956` — more specific checkpoint events.
+  - `loginBlocked` — Facebook actively blocked the login (error `1357001`).
+  - `rateLimit` — HTTP 429 detected on Facebook endpoints.
+  - `networkError` — network‑level failure (timeouts, DNS, connection reset, etc.).
+
+Usage:
+
+```javascript
+api.on("checkpoint_956", ({ res }) => {
+  console.error("Checkpoint 956 detected, manual action required.");
+});
+
+api.on("rateLimit", ({ url, method }) => {
+  console.warn("Rate limit hit on", method, url);
+});
+```
+
+- **Remote control events** (when `remoteControl.enabled` is `true` in `fca-config.json`):
+  - `remoteConnected` / `remoteDisconnected`
+  - `remoteStop`
+  - `remoteBroadcast`
+  - `remoteMessage` (raw messages from your WS backend)
+
+See `examples/remote-control.js` for a concrete integration example.
+
+---
+
+## 🌐 Proxy Configuration & Broadcast Helper
+
+- **Proxy support**:
+  - You can pass a proxy per‑login:
+
+```javascript
+login({ appState }, (err, api) => {
+  if (err) return console.error(err);
+  api.setOptions({ proxy: "http://user:pass@host:port" });
+});
+```
+
+  - Or define a default in `fca-config.json`:
+
+```json
+{
+  "proxy": "http://user:pass@host:port"
+}
+```
+
+  - All HTTP calls go through this proxy using `https-proxy-agent`.
+
+- **Broadcast helper** (optional util):
+  - Not part of the public API surface on purpose (to avoid encouraging spam).
+  - You can use it manually:
+
+```javascript
+const broadcast = require("@sagor/fca-unofficial/src/utils/broadcast");
+
+const threads = ["1000...", "2000..."];
+await broadcast(api, threads, { body: "Hello!" }, {
+  delayMs: 1200,
+  skipBlocked: true
+});
+```
 
 ---
 
-## 🔐 Security & Anti-Ban
+## 📚 Documentation
+
+- **[DOCS.md](./DOCS.md)** — Full API reference, examples, and best practices.
+- **[docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — Codebase structure and modules (for contributors).
+- For implementation details, the `src/` folder is the authoritative reference.
+
+---
 
-To enhance the longevity and stability of your bot, `sagor-fca` includes built-in anti-ban measures:
+## 🛠️ Projects Using This API
 
--   **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.
+Here are some awesome projects built with `@sagor/fca-unofficial`:
+_(See [GitHub Repository](https://github.com/SAGOR-KINGx/fca-unofficial) for the full list)._
 
 ---
 
 ## 🤝 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.
+Contributions are welcome! If you want to optimize something or fix a bug:
+
+1. 🍴 Fork the repository
+2. 🌿 Create a new branch
+3. 💾 Commit your changes
+4. 📤 Push to the branch
+5. 🔄 Open a Pull Request
+
+**Rule:** Keep it clean, minimal, and performant. No bloated dependencies.
 
 ---
 
 ## 📄 License
 
-This project is open-source and available under the [MIT License](LICENSE).
+This project is licensed under the **MIT License** - see the [LICENSE-MIT](./LICENSE-MIT) file for details.
+
+---
+
+## 👨‍💻 Author & Support
+
+<div align="center">
+
+**Maintained by SaGor**
+
+</div>
+
+### 🛠️ Need Custom Work?
+
+If you have the budget and need specialized features, API reverse-engineering, or private bot development, reach out to me directly via Facebook. **Do not contact me for free coding lessons.**
+
+### 🔗 Links
+
+- 📦 [NPM Package](https://www.npmjs.com/package/@sagor/fca-unofficial)
+- 🐙 [GitHub Repository](https://github.com/SAGOR- KINGx/fca-unofficial)
+- 🐛 [Issue Tracker](https://github.com/SAGOR-KINGx/fca-unofficial/issues)
 
 ---
 
-## 👨‍💻 Author
+<div align="center">
+
+Made with ❤️ (and a lot of caffeine) for the developer community.
 
-Developed and maintained by **SAGOR**.
+</div>