sagor-fca 0.0.13 → 0.0.15

package/README.md

@@ -0,0 +1,244 @@
+# 🚀 SAGOR-FCA: Unofficial Facebook Chat API
+
+![npm](https://img.shields.io/npm/v/sagor-fca) ![License](https://img.shields.io/badge/License-MIT-green) ![GitHub issues](https://img.shields.io/github/issues/SAGOR-KINGx/sagor-fca)
+
+**A lightweight, fast, and unofficial API to interact with Facebook Chat programmatically — ideal for building bots, automation systems, and custom messaging tools.**
+
+**This project is customized and enhanced for improved performance and stability.**
+
+
+
+# 🌟 What's New in SAGOR-FCA
+
+- ✨ Enhanced MQTT connection logging
+- 🔄 Auto-reconnect with configurable intervals
+- 📊 Better connection status indicators
+- 🎨 Improved console output with colors
+- 🔐 Enhanced security and stability
+- 🚀 Automatic update checking and installation
+- 💡 Better error handling and debugging
+
+## 📦 Installation
+```bash
+npm install sagor-fca@latest
+```
+
+Or
+```bash
+npm install sagor-fca
+```
+
+## 🚀 Basic Usage
+
+### 1. Login and Simple 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);
+
+        // Echo back the received message
+        api.sendMessage(event.body, event.threadID);
+    });
+});
+```
+
+### 2. Send Text Message
+
+```javascript
+const login = require("sagor-fca");
+
+login({ appState: [] }, (err, api) => {
+    if (err) {
+        console.error("Login Error:", err);
+        return;
+    }
+
+    let yourID = "000000000000000"; // Replace with actual Facebook ID
+    let msg = "Hey!";
+
+    api.sendMessage(msg, yourID, err => {
+        if (err) console.error("Message Sending Error:", err);
+        else console.log("Message sent successfully!");
+    });
+});
+```
+
+**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");
+const fs = require("fs");
+
+login({ appState: [] }, (err, api) => {
+    if (err) {
+        console.error("Login Error:", err);
+        return;
+    }
+
+    let yourID = "000000000000000";
+    let imagePath = __dirname + "/image.jpg";
+
+    // Check if file exists
+    if (!fs.existsSync(imagePath)) {
+        console.error("Error: Image file not found!");
+        return;
+    }
+
+    let msg = {
+        body: "Hey!",
+        attachment: fs.createReadStream(imagePath)
+    };
+
+    api.sendMessage(msg, yourID, err => {
+        if (err) console.error("Message Sending Error:", err);
+        else console.log("Message sent successfully!");
+    });
+});
+```
+
+## 📝 Message Types
+
+| Type                   | Usage                                                             |
+| ---------------------- | ----------------------------------------------------------------- |
+| **Regular text** | `{ body: "message text" }`                                      |
+| **Sticker**      | `{ sticker: "sticker_id" }`                                     |
+| **File/Image**   | `{ attachment: fs.createReadStream(path) }` or array of streams |
+| **URL**          | `{ url: "https://example.com" }`                                |
+| **Large emoji**  | `{ emoji: "👍", emojiSize: "large" }` (small/medium/large)      |
+
+**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.
+
+## 💾 Saving AppState to Avoid Re-login
+
+### Save AppState
+
+```javascript
+const fs = require("fs");
+const login = require("sagor-fca");
+
+const credentials = { appState: [] };
+
+login(credentials, (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);
+    }
+});
+```
+
+### Use 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!");
+        // Your code here
+    }
+);
+```
+
+**Alternative:** Use [c3c-fbstate](https://github.com/c3cbot/c3c-fbstate) to get fbstate.json
+
+## 👂 Listening for Messages
+
+### Echo Bot with Stop Command
+
+```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;
+        }
+
+        // Enable listening to events (join/leave, title change, etc.)
+        api.setOptions({ listenEvents: true });
+
+        const stopListening = api.listenMqtt((err, event) => {
+            if (err) {
+                console.error("Listen Error:", err);
+                return;
+            }
+
+            // 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(`TEST BOT: ${event.body}`, event.threadID);
+                    break;
+
+                case "event":
+                    console.log("Event Received:", event);
+                    break;
+            }
+        });
+    }
+);
+```
+
+### Listen Options
+
+```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)
+});
+```
+
+**By default:**
+
+- `listenEvents` is `false` - won't receive events like joining/leaving chat, title changes
+- `selfListen` is `false` - will ignore messages sent by the current account
+
+### ⚠️ Disclaime
+> Note: This is an unofficial Facebook API.
+Use at your own risk.
+This project is not affiliated with or endorsed by Meta / Facebook in any way.
+
+
+
+
+🚀 **DEVELOPMENT APPROACH**  
+- 💻 **Copy-paste techniques with customizations**  
+- 🤝 **Collaborative development with friends**  
+- 🤖 **AI-powered using ChatGPT and other advanced tools**  
+
+## Thanks for using FCA