sagor-fca 0.0.10 → 0.0.12

package/README.md

@@ -1,524 +1,502 @@
-<div align="center">
+# sagor-fca
 
-#   sagor-nx-fca
+[![npm version](https://img.shields.io/npm/v/sagor-fca.svg)](https://www.npmjs.com/package/sagor-fca)
+[![npm downloads](https://img.shields.io/npm/dm/sagor-fca.svg)](https://www.npmjs.com/package/sagor-fca)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/sagor-fca.svg)](https://nodejs.org)
 
-**Unofficial Facebook Chat API for Node.js** - Interact with Facebook Messenger programmatically
+**sagor-fca** is an advanced Facebook Chat API (FCA) client built for **reliable**, **real-time**, and **modular** interaction with Facebook Messenger.
 
-[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Support](#-author--support)
-
-</div>
-
----
-
-## 📋 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)
-- [📝 Message Types](#-message-types)
-- [💾 AppState Management](#-appstate-management)
-- [🔄 Auto Login](#-auto-login)
-- [👂 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 & Support](#-author--support)
+Developed and maintained by **[SaGor](https://github.com/SAGOR-KINGx)**.  
+Inspired by **ws3-fca** and **@dongdev/fca-unofficial**
 
 ---
 
-## ⚠️ 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:** 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 don't like this policy, feel free to fork the repository and maintain it yourself.
-
-**Recommendations to avoid bans:**
-
-- 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.
-
----
+## Documentation
 
-## ⚡ Why this fork?
+- **[Cookie Login Guide](COOKIE_LOGIN.md)** — Authenticate using browser cookies
+- **[Theme Features](THEME_FEATURES.md)** — Comprehensive guide to theme management
+- **[Changelog](CHANGELOG.md)** — Version history and updates
+- **[Examples](examples/)** — Code examples and usage patterns
 
-Unlike other outdated forks, `@sagor/fca-unofficial` is built with a focus on **real-world practicality and performance**:
+### Support & Issues
 
-- **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.
+- GitHub: [https://github.com/SAGOR-KINGx](https://github.com/SAGOR-KINGx)
+- Issues: [https://github.com/SAGOR-KINGx/sagor-fca/issues](https://github.com/SAGOR-KINGx/sagor-fca/issues)
 
 ---
 
-## ✨ 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
+## Features
+
+**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
 
 ---
 
-## 🔍 Introduction
-
-Facebook provides an [official API for chat bots](https://developers.facebook.com/docs/messenger-platform), but it's **only available for Facebook Pages**.
-
-`@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
 
-## 📦 Installation
+> **Requirements:** Node.js v18.0.0 or higher
 
 ```bash
-npm install @sagor/fca-unofficial@latest
+npm install sagor-fca
 ```
 
-**Requirements:**
-
-- Node.js >= 12.0.0
-- Active Facebook account
-
 ---
 
-## 🚀 Quick Start
+## Quick Start
 
-### 1️⃣ Login and Simple Echo Bot
+```js
+const fs = require("fs");
+const { login } = require("sagor-fca");
 
-```javascript
-const login = require("@sagor/fca-unofficial");
+const appState = JSON.parse(fs.readFileSync("appstate.json", "utf8"));
 
-login({ appState: [] }, (err, api) => {
-  if (err) return console.error(err);
+login({ appState }, {
+  online: true,
+  listenEvents: true,
+  autoMarkRead: 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) return console.error(err);
+    if (err || event.type !== "message" || !event.body) return;
 
-    // Echo back the received message
-    if (event.type === "message") {
-      api.sendMessage(event.body, event.threadID);
+    if (event.body === "/ping") {
+      api.sendMessage("pong!", event.threadID);
     }
   });
 });
 ```
 
-### 2️⃣ Send Text Message
-
-```javascript
-const login = require("@sagor/fca-unofficial");
-
-login({ appState: [] }, (err, api) => {
-  if (err) {
-    console.error("Login Error:", err);
-    return;
-  }
-
-  const yourID = "000000000000000"; // Replace with actual Facebook ID
-  const msg = "Hey! 👋";
+---
 
-  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;
+
+  // Check anti-suspension and rate limiter status
+  console.log(api.getHealthStatus());
 });
 ```
 
-> **💡 Tip:** To find your Facebook ID, look inside the cookies under the name `c_user`
+### Circuit Breaker
 
-### 3️⃣ Send File/Image
+The circuit breaker trips automatically after detecting 2 or more suspension signals (checkpoints, spam flags, rate limits, etc.). It pauses all activity for 45 minutes by default.
 
-```javascript
-const login = require("@sagor/fca-unofficial");
-const fs = require("fs");
-
-login({ appState: [] }, (err, api) => {
-  if (err) {
-    console.error("Login Error:", err);
-    return;
-  }
+You can also trip or reset it manually:
 
-  const yourID = "000000000000000";
-  const imagePath = __dirname + "/image.jpg";
+```js
+const { globalAntiSuspension } = require("sagor-fca/src/utils/antiSuspension");
 
-  // Check if file exists
-  if (!fs.existsSync(imagePath)) {
-    console.error("❌ Error: Image file not found!");
-    return;
-  }
+// Manually trip (e.g. after you detect a warning in a response)
+globalAntiSuspension.tripCircuitBreaker("manual_pause", 30 * 60 * 1000); // 30 min
 
-  const msg = {
-    body: "Check out this image! 📷",
-    attachment: fs.createReadStream(imagePath),
-  };
+// Reset after you've resolved the issue
+globalAntiSuspension.resetCircuitBreaker();
 
-  api.sendMessage(msg, yourID, (err) => {
-    if (err) console.error("Message Sending Error:", err);
-    else console.log("✅ Image sent successfully!");
-  });
-});
+// Check status
+console.log(globalAntiSuspension.getConfig());
 ```
 
----
+### Warmup Mode
 
-## 📝 Message Types
+Use warmup mode when starting a fresh or recovered session:
 
-| 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" }`              |
-
-> **📌 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`
+```js
+const { globalAntiSuspension } = require("sagor-fca/src/utils/antiSuspension");
+globalAntiSuspension.enableWarmup(); // limits to 25 msg/hour for 20 minutes
+```
 
 ---
 
-## 💾 AppState Management
+## End-to-End Encryption for DMs (Opt-In)
 
-### Save AppState
+Encrypt and decrypt message bodies in direct chats using X25519 + HKDF + AES-256-GCM.
 
-Save your login session to avoid re-authentication:
+```js
+api.e2ee.enable();
 
-```javascript
-const fs = require("fs");
-const login = require("@sagor/fca-unofficial");
-
-const credentials = { email: "YOUR_EMAIL", password: "YOUR_PASSWORD" }; // Or use existing appState
+// Share your bot's public key with the peer
+const botPubKey = api.e2ee.getPublicKey();
 
-login(credentials, (err, api) => {
-  if (err) {
-    console.error("Login Error:", err);
-    return;
-  }
+// Register the peer's public key for a DM thread
+api.e2ee.setPeerKey(threadID, peerPublicKeyBase64);
 
-  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
-
-Load your saved AppState for faster login:
-
-```javascript
-const fs = require("fs");
-const login = require("@sagor/fca-unofficial");
-
-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
-  },
-);
+// Messages to that thread are now auto-encrypted on send
+// and auto-decrypted on receive
+api.sendMessage("Top secret message", threadID);
 ```
 
 ---
 
-## 🔄 Auto Login
+## Security Warning
 
-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.
+`appstate.json` contains your Facebook session and must be treated like a password:
 
-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": ""
-  }
-}
-```
-
-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.
+- **Never commit `appstate.json` to version control**
+- **Never share your `appstate.json` publicly**
+- Add it to `.gitignore`
+- Use environment variables or a secrets manager in production
 
 ---
 
-## 🔐 Security, Trust & Supply Chain
+## Getting Started — Generate `appstate.json`
 
-- 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.
+1. Install a cookie export extension:
+   - Chrome/Edge: **C3C FbState** or **CookieEditor**
+   - Firefox: **Cookie-Editor**
 
-See `SECURITY.md` for more details.
+2. Log in to Facebook in your browser
 
----
-
-## 👂 Listening for Messages
+3. Export cookies as JSON and save as `appstate.json`:
 
-### 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;
-      }
-    });
-  },
-);
+```json
+[
+  { "key": "c_user", "value": "your-user-id" },
+  { "key": "xs", "value": "your-xs-value" }
+]
 ```
 
-### Listen Options
-
-Configure listening behavior:
+4. Use in your bot:
 
-```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)
-});
+```js
+const { login } = require("sagor-fca");
+const appState = require("./appstate.json");
+login({ appState }, {}, (err, api) => { ... });
 ```
 
----
-
-## 🎯 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
+See **[COOKIE_LOGIN.md](COOKIE_LOGIN.md)** for more formats and troubleshooting.
 
-`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`
+## Bot Example with Commands
 
-### ⚙️ Thread Settings & Actions
+```js
+const fs = require("fs");
+const path = require("path");
+const { login } = require("sagor-fca");
 
-`muteThread`, `changeArchivedStatus`, `changeBlockedStatus`, `handleMessageRequest`, `changeAvatar`, `changeBio`, `handleFriendRequest`, `unfriend`
+const appState = JSON.parse(fs.readFileSync("appstate.json", "utf8"));
 
-### 🔐 Auth & Listening
+login({ appState }, {
+  online: true,
+  selfListen: false,
+  simulateTyping: true,
+  autoReconnect: true
+}, async (err, api) => {
+  if (err) return console.error("Login error:", err);
 
-`logout`, `getAppState`, `setOptions`, `listenMqtt`
+  console.log("Logged in as:", api.getCurrentUserID());
 
----
-## 🎛 Event Hooks & Remote Control (Advanced)
+  const commandsDir = path.join(__dirname, "commands");
+  const commands = new Map();
 
-Starting from `3.x`, the API instance also behaves like an **EventEmitter** for lifecycle and remote‑control events:
+  if (fs.existsSync(commandsDir)) {
+    for (const file of fs.readdirSync(commandsDir).filter(f => f.endsWith(".js"))) {
+      const cmd = require(path.join(commandsDir, file));
+      if (cmd.name && typeof cmd.execute === "function") {
+        commands.set(cmd.name, cmd);
+      }
+    }
+  }
 
-- **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.).
+  api.listenMqtt(async (err, event) => {
+    if (err || event.type !== "message" || !event.body) return;
 
-Usage:
+    const prefix = "/";
+    if (!event.body.startsWith(prefix)) return;
 
-```javascript
-api.on("checkpoint_956", ({ res }) => {
-  console.error("Checkpoint 956 detected, manual action required.");
-});
+    const args = event.body.slice(prefix.length).trim().split(/ +/);
+    const name = args.shift().toLowerCase();
+    const cmd = commands.get(name);
+    if (!cmd) return;
 
-api.on("rateLimit", ({ url, method }) => {
-  console.warn("Rate limit hit on", method, url);
+    try {
+      await cmd.execute({ api, event, args });
+    } catch (e) {
+      console.error(`Error in /${name}:`, e.message);
+      api.sendMessage("An error occurred.", event.threadID);
+    }
+  });
 });
 ```
 
-- **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:
+## AI Themes
 
-```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"
+```js
+// Generate an AI theme from a text prompt
+const aiThemes = await api.createAITheme("vibrant ocean sunset purple");
+if (aiThemes && aiThemes.length > 0) {
+  await api.setThreadThemeMqtt(threadID, aiThemes[0].id);
 }
-```
-
-  - 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:
+// Browse standard themes
+const themes = await api.getTheme(threadID);
+await api.setThreadThemeMqtt(threadID, themes[0].id);
 
-```javascript
-const broadcast = require("@sagor/fca-unofficial/src/utils/broadcast");
-
-const threads = ["1000...", "2000..."];
-await broadcast(api, threads, { body: "Hello!" }, {
-  delayMs: 1200,
-  skipBlocked: true
-});
+// Check current theme
+const info = await api.getThemeInfo(threadID);
+console.log(info.color, info.emoji);
 ```
 
 ---
 
-## 📚 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.
+## 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 |
 
 ---
 
-## 🛠️ Projects Using This API
-
-Here are some awesome projects built with `@sagor/fca-unofficial`:
-_(See [GitHub Repository](https://github.com/SAGOR-KINGx/fca-unofficial) for the full list)._
+## 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 |
 
 ---
 
-## 🤝 Contributing
-
-Contributions are welcome! If you want to optimize something or fix a bug:
+## Examples
 
-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.
+See the **[examples/](examples/)** directory:
+- `simple-bot.js` — Basic bot setup and message handling
+- `theme-usage-example.js` — Theme management
+- `test-bot.js` — Full-featured test bot
 
 ---
 
-## 📄 License
+## Publishing
 
-This project is licensed under the **MIT License** - see the [LICENSE-MIT](./LICENSE-MIT) file for details.
+```bash
+npm pack --dry-run
+```
 
 ---
 
-## 👨‍💻 Author & Support
+## Credits
 
-<div align="center">
+- **Developed and maintained by [SaGor](https://github.com/SAGOR-KINGx)**
+- **SaGor Team** — development, maintenance, and feature contributions
+- **Inspired by ws3-fca** — by @NethWs3Dev and @CommunityExocore
 
-**Maintained by SaGor**
+> Copyright (c) 2026 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.**
+## License
 
-### 🔗 Links
+**MIT** — Free to use, modify, and distribute. Attribution appreciated.
 
-- 📦 [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)
+See [LICENSE](LICENSE) for full license text.
 
 ---
 
-<div align="center">
-
-Made with ❤️ (and a lot of caffeine) for the developer community.
+## Links
 
-</div>
+- **npm:** [https://www.npmjs.com/package/sagor-fca](https://www.npmjs.com/package/sagor-fca)
+- **GitHub:** [https://github.com/SAGOR-KINGx](https://github.com/SAGOR-KINGx)
+- **Issues:** [https://github.com/SAGOR-KINGx/sagor-fca/issues](https://github.com/SAGOR-KINGx/sagor-fca/issues)