shadowx-fca 8.0.0

package/README.md

@@ -0,0 +1,1066 @@
+
+```markdown
+
+# ⚡ SHADOWX
+
+<p align="center">
+  <strong> Facebook Chat API and next-generation Facebook Messenger bot library for Node.js with Auto-Update System</strong><br>
+  Modified by Mueid Mursalin Rifat🖤
+</p>
+
+🔐 Signal Protocol E2EE Added
+
+<br>
+
+</div>
+
+---
+
+## 📑 Table of Contents
+
+- [✨ Installation](#-installation)
+- [🚀 Quick Start](#-quick-start)
+- [⚙️ Login Options](#️-login-options)
+- [📋 shadowxConfig.json](#-shadowxconfigjson)
+- [📡 Event Types](#-event-types)
+- [📚 API Reference](#-api-reference)
+  - [🔑 Login](#-login)
+  - [👂 Listening](#-listening)
+  - [🔐 E2EE — Encrypted Conversations](#-e2ee--encrypted-conversations)
+  - [💬 Sending Messages](#-sending-messages)
+  - [✏️ Message Actions](#️-message-actions)
+  - [📎 Attachments & Media](#-attachments--media)
+  - [🧵 Thread Management](#-thread-management)
+  - [🎨 Thread Customization](#-thread-customization)
+  - [👥 Thread Members](#-thread-members)
+  - [📊 Polls](#-polls)
+  - [📌 Pins](#-pins)
+  - [📬 Read / Delivery Receipts](#-read--delivery-receipts)
+  - [👤 User Info & Friends](#-user-info--friends)
+  - [🌐 Social / Posting](#-social--posting)
+  - [🏷️ Stickers](#️-stickers)
+  - [🔧 HTTP Utilities](#-http-utilities)
+  - [⚡ Misc / Config](#-misc--config)
+  - [📢 Broadcast](#-broadcast)
+  - [🛡️ Session Guard](#-session-guard)
+- [🏗️ E2EE Architecture](#-e2ee-architecture)
+- [🔄 Auto Update System](#-auto-update-system)
+
+---
+
+## ✨ Installation
+
+```bash
+npm install shadowx-fca
+```
+
+🔥 Node.js ≥ 18 required. No TypeScript, no build step — just pure JavaScript power!
+
+🔄 Automatic Updates
+
+SHADOWX comes with a built-in auto-update system that keeps your bot running on the latest version:
+
+```bash
+# Auto-update is enabled by default
+node index.js
+
+# Disable auto-update
+DISABLE_UPDATE=true node index.js
+# or
+node index.js --no-update
+
+# Force update check
+node -e "require('shadowx-fca').checkUpdate()"
+```
+
+---
+
+🚀 Quick Start
+
+```js
+const login = require("shadowx-fca");
+const fs    = require("fs");
+
+const appState = JSON.parse(fs.readFileSync("./appstate.json", "utf8"));
+
+login({ appState }, { listenEvents: true }, async (err, api) => {
+    if (err) throw err;
+
+    console.log("✅ Logged in as:", api.getCurrentUserID());
+    // shadowxConfig.json is auto-created here ↑
+
+    // Optional: Enable session protection
+    api.sessionGuard("./appstate.json");
+
+    api.listen((err, event) => {
+        if (err) throw err;
+        if (event.type === "message" && event.body === "!ping") {
+            api.sendMessage("🏓 Pong! I'm alive and kicking!", event.threadID);
+        }
+    });
+});
+```
+
+---
+
+⚙️ Login Options
+
+🎛️ Option 🔤 Type 🎯 Default 📝 Description
+selfListen boolean false Receive your own sent messages
+listenEvents boolean true Receive thread/group events
+listenTyping boolean false Receive typing indicator events
+updatePresence boolean false Receive online/offline presence events
+autoMarkDelivery boolean false Auto-mark incoming messages as delivered
+autoMarkRead boolean false Auto-mark threads as read after delivery
+autoReconnect boolean true Auto-reconnect MQTT on disconnect
+online boolean false Appear as online to others
+emitReady boolean false Emit a ready event when MQTT is connected
+autoUpdate boolean true Automatically check for updates on login
+pageID string — Act as a Facebook Page
+userAgent string Safari UA Override the HTTP User-Agent
+proxy string — HTTP proxy URL (http://127.0.0.1:8080)
+
+---
+
+📋 shadowxConfig.json
+
+🎯 SHADOWX automatically creates shadowxConfig.json in your project directory every time login() succeeds. It's like magic — no setup needed, it just appears!
+
+```json
+{
+  "botUID":    "61589208980818",
+  "botName":  "My Awesome Bot",
+  "region":   "EAG",
+  "version":  "2.0.0",
+  "lastLogin": "2026-05-30T12:00:00.000Z",
+  "logs":      false
+}
+```
+
+🔍 Set "logs": true to enable colorful per-message console logs showing the sender UID, message body, DM/group indicator, and timestamp. Toggle it live without restarting — the bot re-reads the file on every message. Pretty cool, right?
+
+📖 Read it from your bot code at any time:
+
+```js
+const config = require("./shadowxConfig.json");
+
+console.log(`🤖 ${config.botName} running in ${config.region}`);
+api.sendMessage("Running as: " + config.botName, threadID);
+```
+
+💡 Add your own fields — SHADOWX preserves custom keys on every login update:
+
+```js
+const fs = require("fs");
+const config = JSON.parse(fs.readFileSync("./shadowxConfig.json", "utf8"));
+
+// Customize it your way!
+config.prefix  = "!";
+config.adminID = "100000000000001";
+config.customSettings = {
+    autoReply: true,
+    timezone: "Asia/Dhaka"
+};
+
+fs.writeFileSync("./shadowxConfig.json", JSON.stringify(config, null, 2));
+```
+
+---
+
+📡 Event Types
+
+All events arrive in the listen / listenE2EE callback as callback(err, event). Think of it as your bot's nervous system! 🧠
+
+🎪 event.type ⚡ When it fires
+message New text or media message
+message_reply A reply to an existing message — includes event.messageReply
+message_reaction Reaction added or removed
+message_unsend A message was unsent — includes original body, attachments, and attachmentType
+event Thread event (rename, add/remove member, etc.)
+typ Typing indicator (listenTyping: true)
+presence User online/offline status (updatePresence: true)
+change_thread_image Group image changed
+ready MQTT ready (emitReady: true)
+
+💌 Message Object
+
+```js
+{
+    type:         "message",
+    senderID:     "100000000000001",
+    threadID:     "100000000000002",
+    messageID:    "mid.$abc...",
+    body:         "Hello world 👋",
+    args:         ["Hello", "world"],
+    attachments:  [],
+    mentions:     {},              // { "uid": "@Name" }
+    timestamp:    1716000000000,
+    isGroup:      false,
+    isE2EE:       false            // true when from listenE2EE
+}
+```
+
+↩️ Reply Object (message_reply)
+
+When event.type === "message_reply", the event carries a messageReply field describing the original message being replied to. It's like message archaeology! 🏺
+
+```js
+{
+    type:         "message_reply",
+    senderID:     "100000000000001",   // who sent the reply
+    threadID:     "100000000000002",
+    messageID:    "mid.$reply...",
+    body:         "This is the reply text",
+    args:         ["This", "is", ...],
+    attachments:  [],
+    mentions:     {},
+    timestamp:    1716000000001,
+    isGroup:      true,
+    isE2EE:       false,
+
+    // ── The original message being replied to ──
+    messageReply: {
+        messageID: "mid.$original...",
+        senderID:  "100000000000003",  // who sent the original
+        threadID:  "100000000000002",
+        body:      "Original message text",
+        args:      ["Original", "message", "text"],
+        attachments: [],
+        mentions:  {},
+        isGroup:   true,
+        timestamp: 1716000000000
+    }
+}
+```
+
+🎯 Reply handler pattern:
+
+```js
+api.listen(async (err, event) => {
+    if (event.type === "message_reply" && event.messageReply) {
+        const repliedMsgID = event.messageReply.messageID;
+
+        if (replyHandlers.has(repliedMsgID)) {
+            const handler = replyHandlers.get(repliedMsgID);
+            replyHandlers.delete(repliedMsgID);
+            await handler(event);
+        }
+    }
+});
+```
+
+🔄 Works identically in both api.listen (MQTT) and api.listenE2EE (encrypted). E2EE reply events carry isE2EE: true on both the event and the messageReply object.
+
+🗑️ Unsend Event (message_unsend)
+
+Fired when someone unsends a message. SHADOWX automatically caches every incoming message so the original content is available at unsend time — including the full attachments array with URLs. It's like having a photographic memory! 📸
+
+```js
+{
+    type:              "message_unsend",
+    threadID:          "100000000000002",
+    messageID:         "mid.$abc123",
+    senderID:          "100000000000001",
+    deletionTimestamp: 1716000000001,
+    timestamp:         1716000000000,
+
+    // ── Original message content (from SHADOWX's message cache) ──
+    body:           "Hello world 🌍",     // original text, "" if attachment-only
+    attachments:    [ ... ],               // same shape as a normal message's attachments
+    attachmentType: "text"                 // convenience field — see values below
+}
+```
+
+attachmentType values:
+
+🏷️ Value 📝 What was unsent
+"text" Plain text message
+"photo" Image 🖼️
+"video" Video 🎬
+"audio" Voice / audio clip 🎵
+"sticker" Sticker
+"animated_image" GIF
+"file" File / document 📄
+"unknown" Not seen before unsend (bot was offline when it arrived) 😴
+
+🛡️ Anti-unsend example:
+
+```js
+api.listen((err, event) => {
+    if (event.type !== "message_unsend") return;
+
+    const { attachmentType, body, attachments, threadID, senderID } = event;
+
+    if (attachmentType === "text") {
+        api.sendMessage(`⚠️ ${senderID} unsent: "${body}"`, threadID);
+    } else if (attachmentType === "photo" && attachments[0]) {
+        api.sendMessage({ body: `⚠️ ${senderID} unsent a photo:`, attachment: require("request")(attachments[0].url) }, threadID);
+    } else if (attachmentType === "video") {
+        api.sendMessage(`⚠️ ${senderID} unsent a video: ${attachments[0] && attachments[0].url}`, threadID);
+    } else if (attachmentType === "audio") {
+        api.sendMessage(`⚠️ ${senderID} unsent an audio clip: ${attachments[0] && attachments[0].url}`, threadID);
+    } else if (attachmentType === "sticker") {
+        api.sendMessage(`⚠️ ${senderID} unsent a sticker: ${attachments[0] && attachments[0].url}`, threadID);
+    } else if (attachmentType === "animated_image") {
+        api.sendMessage(`⚠️ ${senderID} unsent a GIF: ${attachments[0] && attachments[0].url}`, threadID);
+    } else {
+        api.sendMessage(`⚠️ ${senderID} unsent a ${attachmentType} message.`, threadID);
+    }
+});
+```
+
+💡 Pro tip: Content is only available if the bot was online when the message arrived. Messages unsent before the bot saw them will have body: "", attachments: [], and attachmentType: "unknown". The cache holds the last 500 messages to keep things snappy!
+
+---
+
+🎭 Thread Events (event type)
+
+When event.type === "event", the logMessageType field identifies what went down:
+
+🎪 event.logMessageType 📝 Description
+log:subscribe Members added to a group — logMessageData.addedParticipants
+log:unsubscribe Member left or was removed — logMessageData.leftParticipantFbId
+log:thread-name Group name changed — logMessageData.name
+log:thread-color Chat theme/color changed 🎨
+log:thread-icon Thread emoji changed
+log:user-nickname Nickname changed
+log:thread-admins Admin status changed 👑
+log:thread-poll Poll created or updated 📊
+log:thread-pinned Message pinned/unpinned 📌
+log:thread-call Call log entry 📞
+log:thread-approval-mode Join approval mode changed
+log:link-status Joinable link reset 🔗
+
+👋 Join/leave handler example:
+
+```js
+api.listen((err, event) => {
+    if (event.type !== "event") return;
+
+    if (event.logMessageType === "log:subscribe") {
+        const added = (event.logMessageData.addedParticipants || [])
+            .map(p => p.userFbId || p);
+        api.sendMessage(`🎉 Welcome to the group!`, event.threadID);
+    }
+
+    if (event.logMessageType === "log:unsubscribe") {
+        const who = event.logMessageData.leftParticipantFbId;
+        api.sendMessage(`👋 Goodbye ${who}! We'll miss you!`, event.threadID);
+    }
+});
+```
+
+📎 Attachment Shapes
+
+```js
+{ type: "photo",   ID, url, width, height, filename }  // 🖼️
+{ type: "video",   ID, url, duration, width, height }  // 🎬
+{ type: "audio",   ID, url, duration, filename }       // 🎵
+{ type: "file",    ID, url, size, mimeType, filename }  // 📄
+{ type: "sticker", stickerID, url, width, height }     // 🏷️
+```
+
+---
+
+📚 API Reference
+
+---
+
+🔑 Login
+
+login(loginData, [options], [callback]) → Promise<api>
+
+```js
+// appState (recommended) 🔐
+const api = await login({ appState: require("./appstate.json") });
+
+// Email + password 📧
+login({ email: "you@example.com", password: "secret" }, callback);
+
+// With options ⚙️
+login({ appState }, { listenEvents: true, autoReconnect: true, autoUpdate: true }, callback);
+```
+
+---
+
+👂 Listening
+
+api.listen(callback) → MessageEmitter
+
+Start listening for all events via MQTT. Your bot's ears are now open! 👂
+
+```js
+const emitter = api.listen((err, event) => {
+    if (err) return console.error(err);
+
+    if (event.type === "message")
+        console.log(`💬 ${event.senderID} → ${event.body}`);
+
+    if (event.type === "message_reaction")
+        console.log(`👍 ${event.senderID} reacted ${event.reaction}`);
+
+    if (event.type === "typ")
+        console.log(event.from, event.isTyping ? "is typing..." : "stopped typing");
+});
+
+// Stop listening
+await emitter.stopListeningAsync();
+```
+
+api.listenE2EE(callback) → MessageEmitter
+
+🔐 Combined listener: receives both regular MQTT messages and decrypted E2EE messages in the same callback. Call api.connectE2EE() first.
+
+```js
+await api.connectE2EE(); // auto-creates .shadowx/e2ee_device.json
+
+api.listenE2EE((err, event) => {
+    if (err) return console.error(err);
+
+    if (event.type === "message") {
+        if (event.isE2EE) {
+            // Must reply via E2EE for encrypted threads 🔒
+            api.e2ee.sendMessage(event.threadID, "Got your encrypted message! 🔐");
+        } else {
+            api.sendMessage("Got it! 👍", event.threadID);
+        }
+    }
+});
+```
+
+⚠️ Important: For E2EE DM replies, always use api.e2ee.sendMessage() — the regular MQTT path does not reach E2EE threads.
+
+---
+
+🔐 E2EE — Encrypted Conversations
+
+SHADOWX connects to Facebook's real E2EE infrastructure using the Signal Protocol — the same battle-tested encryption used by the official Messenger mobile app. Military-grade security for your bot! 🛡️
+
+api.connectE2EE([deviceStorePath]) → Promise
+
+Initialize E2EE. Automatically creates the device store directory if it doesn't exist.
+
+```js
+// Default path: .shadowx/e2ee_device.json in process.cwd()
+// Directory is auto-created — no manual setup needed! ✨
+await api.connectE2EE();
+
+// Custom path
+await api.connectE2EE("./my_data/e2ee.json");
+
+console.log("🔐 E2EE connected:", api.e2ee.isConnected()); // true
+```
+
+🔑 Keep the device store file safe. Deleting it forces device re-registration with Facebook.
+
+api.e2ee.sendMessage(threadId, msg, [replyToMessageId]) → Promise
+
+msg can be a plain string or a message object with body and/or attachment (readable stream or array of streams).
+Attachments on E2EE threads are automatically encrypted and sent via the Noise WebSocket.
+Attachments on non-E2EE threads fall back to SHADOWX's own sendMessage.
+
+```js
+// Text only 📝
+await api.e2ee.sendMessage("100000000000001", "Hello, encrypted! 🔒");
+
+// Reply ↩️
+await api.e2ee.sendMessage("100000000000001", "Reply!", "mid.$replyID");
+
+// Image 🖼️
+const fs = require("fs");
+await api.e2ee.sendMessage("100000000000001", {
+    body: "Check this out! 📸",
+    attachment: fs.createReadStream("photo.jpg")
+});
+
+// Audio / Video / File — same pattern, type detected automatically 🎯
+await api.e2ee.sendMessage("100000000000001", { attachment: fs.createReadStream("voice.ogg") });
+await api.e2ee.sendMessage("100000000000001", { attachment: fs.createReadStream("clip.mp4") });
+
+// Multiple attachments 📎
+await api.e2ee.sendMessage("100000000000001", {
+    attachment: [fs.createReadStream("a.jpg"), fs.createReadStream("b.jpg")]
+});
+```
+
+api.e2ee.sendReaction(threadId, messageId, reaction) → Promise
+
+```js
+await api.e2ee.sendReaction("100000000000001", "mid.$abc123", "❤️");
+```
+
+api.e2ee.sendTyping(threadId, isTyping) → Promise
+
+```js
+await api.e2ee.sendTyping("100000000000001", true);
+await api.e2ee.sendTyping("100000000000001", false);
+```
+
+api.e2ee.unsendMessage(messageId, threadId) → Promise
+
+```js
+await api.e2ee.unsendMessage("mid.$abc123", "100000000000001");
+```
+
+api.e2ee.editMessage(threadId, messageId, text) → Promise
+
+```js
+await api.e2ee.editMessage("100000000000001", "mid.$abc123", "Updated! ✨");
+```
+
+api.e2ee.onMessage(callback)
+
+```js
+api.e2ee.onMessage((err, event) => {
+    // event.isE2EE is always true 🔒
+    console.log("[🔐 E2EE]", event.senderID, ":", event.body);
+});
+```
+
+api.e2ee.isConnected() → boolean
+
+```js
+if (api.e2ee.isConnected()) await api.e2ee.sendMessage(threadID, "hi 👋");
+```
+
+api.e2ee.disconnect() → Promise
+
+```js
+await api.e2ee.disconnect();
+```
+
+---
+
+💬 Sending Messages
+
+api.sendMessage(msg, threadID, [callback], [replyToMessageID]) → Promise
+
+MQTT-first, HTTP fallback. Lightning fast! ⚡
+
+```js
+// Text 📝
+await api.sendMessage("Hello! 👋", threadID);
+
+// Reply ↩️
+api.sendMessage("Noted! 👍", threadID, callback, replyToMessageID);
+
+// Mention — tag must include the @ prefix; fromIndex is the position of @ in body
+api.sendMessage({
+    body: "Hey @John!",
+    mentions: [{ id: "100000000000001", tag: "@John", fromIndex: 4 }]
+}, threadID);
+
+// Multiple mentions 👥
+api.sendMessage({
+    body: "@Alice and @Bob check this out",
+    mentions: [
+        { id: "111111111111", tag: "@Alice", fromIndex: 0 },
+        { id: "222222222222", tag: "@Bob",   fromIndex: 11 }
+    ]
+}, threadID);
+
+// Attachment from file stream 📎
+api.sendMessage({ body: "File!", attachment: fs.createReadStream("./photo.jpg") }, threadID);
+
+// Attachment from a remote URL (stream via request) 🌐
+const request = require("request");
+api.sendMessage({ attachment: request("https://example.com/img.jpg") }, threadID);
+
+// Sticker / Emoji / Location 🎯
+api.sendMessage({ sticker: "369239263222822" }, threadID);
+api.sendMessage({ emoji: "❤️", emojiSize: "large" }, threadID);
+api.sendMessage({ location: { latitude: 14.5995, longitude: 120.9842, current: true } }, threadID);
+```
+
+api.sendSticker(stickerID, threadID, [replyTo], [callback])
+
+```js
+api.sendSticker("369239263222822", threadID);
+```
+
+api.sendEmoji(emoji, [emojiSize], threadID, [callback])
+
+```js
+api.sendEmoji("🔥", "large", threadID);
+// emojiSize: "small" | "medium" | "large"
+```
+
+api.sendGif(gifSrc, threadID, [callback])
+
+```js
+api.sendGif("https://media.giphy.com/media/xyz/giphy.gif", threadID);
+```
+
+api.sendLocation(lat, lng, threadID, [isCurrent], [callback])
+
+```js
+api.sendLocation(14.5995, 120.9842, threadID);
+```
+
+api.sendImage(path, threadID, [caption], [callback])
+
+```js
+api.sendImage("./photo.jpg", threadID, "Look at this! 📸");
+```
+
+api.sendVideo(path, threadID, [caption], [callback])
+
+```js
+api.sendVideo("./video.mp4", threadID, "Watch 👀");
+```
+
+api.sendAudio(path, threadID, [callback])
+
+```js
+api.sendAudio("./voice.ogg", threadID);
+```
+
+api.sendFile(path, threadID, [caption], [callback])
+
+```js
+api.sendFile("./doc.pdf", threadID, "Here's the doc 📄");
+```
+
+api.shareLink(url, threadID, [message], [callback])
+
+```js
+api.shareLink("https://github.com", threadID, "Check this out! 🔗");
+```
+
+api.shareContact(text, userID, threadID, [callback])
+
+```js
+api.shareContact("Meet my friend! 👤", "100000000000001", threadID);
+```
+
+api.forwardAttachment(attachmentID, userOrUsers, [callback])
+
+```js
+api.forwardAttachment("attach_fbid", ["uid1", "uid2"]);
+```
+
+Other send methods
+
+🚀 Method 📝 Description
+api.sendMessageMqtt(msg, threadID) MQTT-only, no HTTP fallback
+api.OldMessage(msg, threadID, cb, replyTo, isSingleUser) HTTP-only (legacy)
+api.sendMessageDM(msg, threadID) HTTP DM shorthand
+
+---
+
+✏️ Message Actions
+
+api.editMessage(text, messageID, [callback])
+
+Uses MQTT (label 742) for instant delivery; falls back to HTTP if MQTT is not yet connected.
+
+```js
+// Promise ✨
+await api.editMessage("Updated text ✏️", "mid.$abc123");
+
+// Callback
+api.editMessage("Updated text ✏️", "mid.$abc123", (err) => {
+    if (err) return console.error(err);
+    console.log("✅ Message edited!");
+});
+```
+
+api.unsendMessage(messageID, [callback])
+
+```js
+api.unsendMessage("mid.$abc123", callback);
+```
+
+api.deleteMessage(messageIDs, [callback])
+
+```js
+api.deleteMessage(["mid.$abc123", "mid.$def456"], callback);
+```
+
+api.setMessageReaction(reaction, messageID, threadID, [callback])
+
+```js
+api.setMessageReaction("😍", messageID, threadID);
+api.setMessageReaction("", messageID, threadID); // remove
+```
+
+api.getMessage(threadID, messageID, [callback])
+
+```js
+const msg = await api.getMessage(threadID, "mid.$abc123");
+console.log(`💬 ${msg.senderID}: ${msg.body}`);
+```
+
+---
+
+📎 Attachments & Media
+
+api.uploadAttachment(attachments, [callback]) → Promise
+
+```js
+const [meta] = await api.uploadAttachment([fs.createReadStream("./photo.jpg")]);
+console.log("📁 File ID:", meta.attach_fbid);
+```
+
+💡 Pro tip — stream a URL as attachment:
+
+```js
+const request = require("request");
+api.sendMessage({ attachment: request("https://example.com/img.jpg") }, threadID);
+```
+
+api.uploadImageToImgbb(image, [expiration], [callback]) → Promise
+
+```js
+// URL, Buffer, or base64
+const result = await api.uploadImageToImgbb("https://example.com/img.jpg");
+console.log("🖼️ URL:", result.data.url);
+```
+
+api.resolvePhotoUrl(photoID, [callback])
+
+```js
+api.resolvePhotoUrl("photo_id", (err, url) => console.log(url));
+```
+
+---
+
+🧵 Thread Management
+
+api.getThreadInfo(threadID, [callback]) → Promise
+
+```js
+const info = await api.getThreadInfo(threadID);
+// info.threadName, .participantIDs, .isGroup, .unreadCount, .adminIDs, .emoji, .color
+```
+
+api.getThreadList(limit, [timestamp], [tags], [callback]) → Promise
+
+```js
+const threads = await api.getThreadList(10, null, ["INBOX"]);
+// tags: "INBOX" | "PENDING" | "ARCHIVED"
+```
+
+api.getThreadHistory(threadID, amount, [timestamp], [callback]) → Promise
+
+```js
+const messages = await api.getThreadHistory(threadID, 20, null);
+```
+
+api.createGroup(message, participantIDs, [callback])
+
+```js
+const { threadID } = await api.createGroup("Hey! 👋", ["uid1", "uid2"]);
+```
+
+api.deleteThread(threadID, [callback])
+
+```js
+api.deleteThread(threadID);
+```
+
+api.muteThread(threadID, muteSeconds, [callback])
+
+```js
+api.muteThread(threadID, 3600); // mute 1 hour 🔇
+api.muteThread(threadID, 0);    // unmute 🔊
+```
+
+api.changeArchivedStatus(threadID, archive, [callback])
+
+```js
+api.changeArchivedStatus(threadID, true);  // archive 📦
+api.changeArchivedStatus(threadID, false); // unarchive 📂
+```
+
+---
+
+🎨 Thread Customization
+
+```js
+api.setTitle("New Name ✨", threadID);
+api.changeThreadColor("#0084FF", threadID);
+api.changeThreadEmoji("🔥", threadID);
+api.changeNickname("The Boss 👑", threadID, "100000000000001");
+api.changeGroupImage(fs.createReadStream("./group.jpg"), threadID);
+api.changeThreadTheme("197931430960496", threadID);
+```
+
+---
+
+👥 Thread Members
+
+```js
+api.addUserToGroup("100000000000001", threadID);
+api.removeUserFromGroup("100000000000001", threadID);
+api.changeAdminStatus(threadID, "100000000000001", true);  // promote 👑
+api.changeAdminStatus(threadID, "100000000000001", false); // demote
+```
+
+---
+
+📊 Polls
+
+api.createPoll(title, threadID, [options], [callback])
+
+```js
+api.createPoll("Favorite language? 🤔", threadID, { JS: false, Python: false });
+```
+
+api.setPollVote(pollID, optionIDs, [newOptions], [callback])
+
+```js
+api.setPollVote(pollID, ["option_id"], [], callback);
+```
+
+---
+
+📌 Pins
+
+```js
+api.pinMessage("mid.$abc123", threadID);   // MQTT label 430 — pin_msg_v2_
+api.unpinMessage("mid.$abc123", threadID); // MQTT label 431 — unpin_msg_v2_
+```
+
+---
+
+📬 Read / Delivery Receipts
+
+```js
+api.markAsRead(threadID);
+api.markAsDelivered(threadID, messageID);
+api.markAsSeen();
+api.markAsReadAll();
+
+// Typing indicator ✍️
+api.sendTypingIndicator(threadID, true);
+setTimeout(() => api.sendTypingIndicator(threadID, false), 3000);
+```
+
+---
+
+👤 User Info & Friends
+
+api.getUserInfo(id, [callback]) → Promise
+
+```js
+const users = await api.getUserInfo(["uid1", "uid2"]);
+// users[uid].name, .thumbSrc, .gender
+```
+
+Quick reference
+
+```js
+api.getCurrentUserID()                        // → string
+api.getUserID("John Doe", callback)           // search by name 🔍
+api.getUID("https://facebook.com/zuck", cb)   // → "4"
+api.getFriendsList(callback)                  // full friends list 👥
+api.searchFriends("Maria", callback)
+api.getAvatarUser("uid", callback)            // returns graph.facebook.com picture URL 🖼️
+api.getAvatarUser("uid", "square", callback)  // type: square | large | normal | small
+api.getProfileInfo("uid", callback)           // GraphQL node
+api.getPublicData("uid", callback)            // public scrape (name, vanity, uid)
+api.getRepInfo(callback)                      // account rep info
+```
+
+Actions
+
+```js
+api.sendFriendRequest("uid");                 // GraphQL FriendingCometFriendRequestSendMutation
+api.handleFriendRequest("uid", true);         // accept via /requests/friends/ajax/ ✅
+api.handleFriendRequest("uid", false);        // decline ❌
+api.handleMessageRequest(threadID, true);
+api.changeBlockedStatus("uid", true);         // block 🚫
+api.changeBlockedStatus("uid", false);        // unblock
+api.followUser("uid");
+api.unfollowUser("uid");
+api.unfriend("uid");
+api.setActiveStatus(true);                    // appear online 🟢
+api.logout();
+```
+
+---
+
+🌐 Social / Posting
+
+```js
+// Reactions: "like" | "love" | "haha" | "wow" | "sad" | "angry" | "care" | "none"
+api.reactToPost("postID", "love");           // ❤️
+api.reactToComment("commentID", "haha");     // 😄
+api.postComment("postID", "Great post! 🔥");
+api.deleteComment("commentID");
+api.sharePost("postID", "Check this!");
+api.getPostInfo("postID", callback);
+api.getStoryReactions("feedbackID", callback);
+```
+
+---
+
+🏷️ Stickers
+
+```js
+api.getStickers("thumbs up", null, (err, stickers) => {
+    if (stickers.length) api.sendSticker(stickers[0].id, threadID);
+});
+
+api.getStickerPacks((err, packs) => {
+    packs.forEach(p => console.log(`🏷️ ${p.id}: ${p.name}`));
+});
+```
+
+---
+
+🔧 HTTP Utilities
+
+```js
+api.httpGet(url, params, callback);
+api.httpPost(url, form, callback);
+api.httpPostFormData(url, form, callback);
+
+const dtsg = await api.getFreshDtsg();
+```
+
+---
+
+⚡ Misc / Config
+
+```js
+api.setOptions({ listenTyping: true, proxy: "http://127.0.0.1:8080" });
+api.getAppState()        // → cookie array (save to reuse session) 🍪
+api.getCurrentUserID()   // → string
+api.getCtx()             // → internal ctx object (region, fb_dtsg, etc.)
+api.checkForUpdate()     // → Promise<boolean> 🔄
+
+// Add a custom method to the api object
+api.addExternalModule("myFunc", (defaultFuncs, api, ctx) => {
+    return function (text, threadID) {
+        return api.sendMessage("[🤖 BOT] " + text, threadID);
+    };
+});
+api.myFunc("Hello!", threadID);
+```
+
+---
+
+📢 Broadcast
+
+api.sendBroadcast(msg, threadIDs, [options], [callback]) → Promise
+
+Send to multiple threads with rate limiting and per-thread delivery tracking. Mass messaging made easy! 📣
+
+```js
+const result = await api.sendBroadcast(
+    "Hello everyone! 👋",
+    ["THREAD_1", "THREAD_2", "THREAD_3"],
+    {
+        delay:    2000,  // ms between sends
+        parallel: 2,     // max concurrent sends
+        onEach: (err, info, id) => {
+            console.log(err ? `❌ Failed: ${id}` : `✅ Sent: ${id}`);
+        }
+    }
+);
+
+console.log(`📊 ${result.sent.length}/${result.total} delivered`);
+```
+
+---
+
+🛡️ Session Guard
+
+Protects your appstate from corruption and silent logouts. Your appstate's bodyguard! 💪
+
+```js
+// Call right after login
+api.sessionGuard("./appstate.json");
+
+// Custom timing ⏱️
+api.sessionGuard("./appstate.json", {
+    interval: 3 * 60 * 1000,  // save every 3 min
+    debounce: 60 * 1000        // cooldown after sendMessage
+});
+```
+
+What it does:
+
+· 💾 Auto-saves appstate every N minutes
+· 📝 Saves after every successful sendMessage (debounced)
+· 🛡️ Corruption guard: never overwrites a larger appstate with a smaller one
+· 📦 Auto-backup: writes appstate.json.bak before every overwrite
+
+```js
+api.saveSession()            // → boolean  (force save now) 💾
+api.restoreSessionBackup()   // → boolean  (restore .bak if corrupted) 🔄
+api.stopSessionGuard()       // stop the timer ⏹️
+```
+
+---
+
+🔄 Auto Update System
+
+SHADOWX includes an intelligent auto-update system that keeps your bot current with the latest features and fixes:
+
+How It Works
+
+1. On Startup: Automatically checks for updates when you require('shadowx-fca')
+2. On Login: Checks again after successful Facebook login
+3. Graceful: Failed update checks never break your bot
+4. Smart: Shows changelog before updating
+
+Manual Control
+
+```js
+// Check for updates manually
+const { checkUpdate } = require('shadowx-fca');
+checkUpdate().then(updated => {
+    console.log(updated ? "Updated! 🔄" : "Already latest! ✅");
+});
+
+// Via API after login
+api.checkForUpdate();
+
+// Environment variables
+DISABLE_UPDATE=true node index.js     // Skip update check
+AUTO_UPDATE=true node index.js        // Auto-accept updates (CI/CD)
+```
+
+---
+
+🏗️ E2EE Architecture
+
+SHADOWX harnesses Facebook's real E2EE infrastructure — identical to the official Messenger mobile app:
+
+```
+🔐 Signal Protocol stack
+  ├── @signalapp/libsignal-client  — Double Ratchet + X3DH
+  ├── Noise_XX_25519_AESGCM_SHA256 — WebSocket handshake
+  ├── WA-binary + Protobuf          — message frame encoding
+  └── ICDC device registration      — registers bot as E2EE device
+
+🚀 Connection flow
+  api.connectE2EE()
+    ├─ 1. Auto-create device store directory 📁
+    ├─ 2. Bootstrap auth (re-use existing cookie session) 🍪
+    ├─ 3. Register device keys with Facebook (first run only) 🔑
+    └─ 4. Open Noise WebSocket → ready ✅
+
+📨 Message flow
+  Incoming  →  Noise WS  →  listenE2EE callback  (event.isE2EE = true)
+  Outgoing  →  api.e2ee.sendMessage()  →  Noise WS  →  Facebook
+```
+
+🔒 The E2EE engine is vendored inside the package. Your bot continues to work even if the upstream npm dependency is removed or broken. Maximum reliability! 💪
+
+---
+
+<div align="center">
+
+⭐ If this project helps you, consider giving it a star!
+📧 Questions? Open an issue or reach out on GitHub.
+
+<br>
+
+MIT License · Copyright © 2026 Mueid Mursalin Rifat
+
+</div>
+```