fca-phantom 1.0.0

package/LICENSE

@@ -0,0 +1,58 @@
+MIT License
+
+Copyright (c) 2024–2026 phantom-fca (github.com/ewr-sifu/phantom-fca)
+Original Author: SIFAT (github.com/Ewr-Sifu)
+
+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.
+
+-------------------------------------------------------------------------------
+
+ADDITIONAL TERMS — ATTRIBUTION & FAIR USE
+
+While this software is provided under the MIT License, the following terms
+apply as a matter of good faith and community respect:
+
+  1. Attribution Required
+     Any public distribution, fork, or derivative work must clearly credit the
+     original author (SIFAT / github.com/Ewr-Sifu) and the phantom-fca project
+     in its documentation, README, or about section.
+
+  2. No Misrepresentation
+     You may not claim original authorship of this software or any substantial
+     portion of it. Presenting this work as entirely your own creation without
+     attribution is a violation of these terms.
+
+  3. Forks & Derivatives
+     You are free to fork, modify, and build upon this project. Derivative
+     works must be distributed under the same MIT License and must include a
+     notice stating that changes were made.
+
+  4. Commercial Use
+     Commercial use is permitted under the MIT License. However, selling this
+     software as-is (without substantial modification) as a paid product is
+     discouraged without explicit written permission from the original author.
+
+  5. No Warranty
+     This software is provided for educational and automation purposes. The
+     authors are not responsible for misuse, account bans, data loss, or any
+     damages arising from the use of this software.
+
+-------------------------------------------------------------------------------
+
+By using, copying, or distributing this software, you agree to these terms.

package/README.md

@@ -0,0 +1,534 @@
+<div align="center">
+
+<img src="https://img.shields.io/badge/PHANTOM--FCA-v1.0.0-blueviolet?style=for-the-badge&logo=ghost&logoColor=white" />
+<img src="https://img.shields.io/npm/v/fca-phantom?style=for-the-badge&color=blueviolet&label=npm" />
+<img src="https://img.shields.io/badge/Node.js-%3E%3D22.0.0-brightgreen?style=for-the-badge&logo=nodedotjs&logoColor=white" />
+<img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" />
+<img src="https://img.shields.io/badge/Platform-Facebook%20Messenger-1877F2?style=for-the-badge&logo=messenger&logoColor=white" />
+<img src="https://img.shields.io/badge/Author-SIFAT-ff69b4?style=for-the-badge&logo=github&logoColor=white" />
+
+<br /><br />
+
+# 👻 PHANTOM-FCA
+
+### *A powerful Facebook Chat API for Node.js*
+### *by **SIFAT***
+
+> *Session Revival · E2EE Encryption · Real-time MQTT · Smart Rate Control · TypeScript Ready*
+
+<br />
+
+[![npm downloads](https://img.shields.io/npm/dm/fca-phantom?style=flat-square&color=blueviolet)](https://www.npmjs.com/package/fca-phantom)
+[![GitHub Stars](https://img.shields.io/github/stars/ewr-sifu/phantom-fca?style=flat-square&color=yellow)](https://github.com/ewr-sifu/phantom-fca)
+[![GitHub Issues](https://img.shields.io/github/issues/ewr-sifu/phantom-fca?style=flat-square)](https://github.com/ewr-sifu/phantom-fca/issues)
+
+</div>
+
+---
+
+## 👤 Author
+
+<div align="center">
+
+**SIFAT** — Creator & Lead Developer of PHANTOM-FCA
+
+[![GitHub](https://img.shields.io/badge/GitHub-Ewr--Sifu-181717?style=flat-square&logo=github)](https://github.com/Ewr-Sifu)
+
+> *"Every message matters. Every session deserves to survive."*
+
+</div>
+
+---
+
+## 📑 Table of Contents
+
+- [What is PHANTOM-FCA?](#-what-is-phantom-fca)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Configuration Options](#️-configuration-options)
+- [API Reference](#-api-reference)
+- [Global Subsystems](#️-global-subsystems)
+- [End-to-End Encryption](#-end-to-end-encryption)
+- [Session Revival](#-session-revival--auto-reconnect)
+- [Message Types & Formats](#-message-types)
+- [Data Persistence](#️-data-persistence)
+- [TypeScript Support](#-typescript-support)
+
+---
+
+## 🔍 What is PHANTOM-FCA?
+
+**PHANTOM-FCA** is a next-generation Facebook Chat API (FCA) built for Node.js. It lets you build bots and automation tools for Facebook Messenger with a focus on **reliability**, **security**, and **long-term stability**.
+
+| Feature | Description |
+|---------|-------------|
+| 👻 **Smart Shield** | Session protection, browser fingerprinting, and circuit breaker |
+| ⚡ **Real-time MQTT** | Fast real-time event listener via Facebook's MQTT protocol |
+| 🔐 **E2EE Built-in** | End-to-end encryption between bots and trusted peers |
+| 🔄 **Auto Revival** | Automatic session revival, re-login, and reconnect |
+| 🗄️ **SQLite Persistence** | Local session storage for fast cold starts |
+| 📦 **75+ API Methods** | Full coverage of the Facebook Messenger API |
+| 🧩 **TypeScript Ready** | Full `.d.ts` type definitions included |
+
+---
+
+## 📦 Installation
+
+```bash
+npm install fca-phantom
+```
+
+> Requires **Node.js >= 22.0.0**
+
+---
+
+## ⚡ Quick Start
+
+### Cookie Login (Recommended)
+
+```javascript
+const phantom = require("fca-phantom");
+
+const cookies = [
+  { key: "c_user", value: "YOUR_USER_ID"  },
+  { key: "xs",     value: "YOUR_XS_TOKEN" },
+  { key: "fr",     value: "YOUR_FR_TOKEN" },
+];
+
+phantom.connect(cookies, { selfListen: false }, (err, api) => {
+  if (err) return console.error("Login failed:", err);
+
+  console.log("Connected as:", api.getCurrentUserID());
+
+  api.listen((err, message) => {
+    if (err) return console.error(err);
+
+    if (message.type === "message") {
+      api.sendMessage("👻 PHANTOM-FCA is alive!", message.threadID);
+    }
+  });
+});
+```
+
+### Async / Await
+
+```javascript
+const phantom = require("fca-phantom");
+
+async function main() {
+  const api = await phantom.connect(cookies, {
+    selfListen:     false,
+    listenEvents:   true,
+    autoMarkRead:   true,
+    autoReconnect:  true,
+    sessionPersist: true,
+  });
+
+  api.listen(async (err, event) => {
+    if (err) throw err;
+
+    if (event.type === "message") {
+      const thread = await api.getThreadInfo(event.threadID);
+      await api.sendMessage(`Hello from ${thread.name}!`, event.threadID);
+    }
+  });
+}
+
+main().catch(console.error);
+```
+
+---
+
+## ⚙️ Configuration Options
+
+```javascript
+phantom.connect(credentials, {
+  selfListen:        false,     // Receive your own sent messages
+  listenEvents:      true,      // Enable group/thread events
+  listenTyping:      false,     // Listen to typing indicators
+  simulateTyping:    true,      // Add human-like typing delay
+  updatePresence:    false,     // Update online presence status
+  forceLogin:        false,     // Force re-login even if session exists
+  autoMarkDelivery:  false,     // Auto-mark as delivered
+  autoMarkRead:      true,      // Auto-mark messages as read
+  autoReconnect:     true,      // Auto-reconnect on MQTT disconnect
+  online:            true,      // Appear online to contacts
+  emitReady:         false,     // Emit a "ready" event on connect
+  persona:           "desktop", // Browser persona: "desktop" | "mobile"
+  autoReLogin:       true,      // Auto re-login on session expiry
+  sessionPersist:    true,      // Persist session to local SQLite DB
+}, callback);
+```
+
+---
+
+## 📡 API Reference
+
+### 💬 Messaging
+
+| Method | Description |
+|--------|-------------|
+| `sendMessage(msg, threadID)` | Send text, attachment, sticker, or rich message |
+| `sendTypingIndicator(threadID)` | Send a typing indicator |
+| `editMessage(messageID, newMessage)` | Edit a previously sent message |
+| `deleteMessage(messageID)` | Delete a message locally |
+| `unsendMessage(messageID)` | Retract/unsend a message for everyone |
+| `forwardMessage(messageID, threadID)` | Forward a message to another thread |
+| `pinMessage(messageID, threadID)` | Pin a message in a thread |
+| `setMessageReaction(reaction, messageID)` | Add an emoji reaction |
+| `shareContact(userID, threadID)` | Share a contact card |
+| `comment(postID, message)` | Comment on a Facebook post |
+
+### 🧵 Thread Management
+
+| Method | Description |
+|--------|-------------|
+| `getThreadInfo(threadID)` | Fetch thread metadata |
+| `getThreadList(limit, cursor, tags)` | List threads with pagination |
+| `getThreadHistory(threadID, amount, ts)` | Fetch message history |
+| `getThreadPictures(threadID, offset, limit)` | Get thread media/photos |
+| `searchForThread(query)` | Search threads by keyword |
+| `createNewGroup(name, participantIDs)` | Create a new group |
+| `changeThreadColor(color, threadID)` | Set thread accent color |
+| `changeThreadEmoji(emoji, threadID)` | Set thread emoji |
+| `changeGroupImage(image, threadID)` | Update group photo |
+| `muteThread(threadID, muteSeconds)` | Mute a thread |
+| `deleteThread(threadID)` | Delete a thread |
+| `changeArchivedStatus(threadID, archive)` | Archive or unarchive thread |
+| `markAsRead(threadID)` | Mark thread as read |
+| `markAsDelivered(threadID, messageID)` | Mark message as delivered |
+| `markAsSeen(threadList)` | Mark multiple threads as seen |
+| `markAsReadAll()` | Mark all threads as read |
+
+### 👥 Group Administration
+
+| Method | Description |
+|--------|-------------|
+| `addUserToGroup(userID, threadID)` | Add a member to a group |
+| `removeUserFromGroup(userID, threadID)` | Remove a member |
+| `changeAdminStatus(threadID, userID, isAdmin)` | Promote or demote admin |
+| `gcname(threadID, name)` | Rename a group |
+| `gcmember(threadID)` | List group members |
+| `gcrule(threadID, rule)` | Manage group rules |
+| `nickname(threadID, userID, nickname)` | Set a member's nickname |
+| `handleMessageRequest(threadID, accept)` | Accept or decline a message request |
+
+### 🙍 User & Friend Operations
+
+| Method | Description |
+|--------|-------------|
+| `getUserInfo(userIDs)` | Fetch user profile info |
+| `getUserInfoV2(userID)` | Fetch extended user info |
+| `getUserID(name)` | Search for a user by name |
+| `getFriendsList()` | Get full friends list |
+| `friend(userID)` | Send a friend request |
+| `unfriend(userID)` | Remove a friend |
+| `follow(userID)` | Follow a user |
+| `changeBlockedStatus(userID, block)` | Block or unblock a user |
+| `changeBio(bio)` | Update the bot's bio |
+| `changeAvatar(avatar)` | Update profile picture |
+| `getBotInfo()` | Get bot account information |
+| `getBotInitialData()` | Get bot bootstrap/session data |
+
+### 🎨 Themes & Stickers
+
+| Method | Description |
+|--------|-------------|
+| `setThreadTheme(threadID, themeID)` | Apply a Messenger theme |
+| `getTheme(threadID)` | Get current thread theme |
+| `getThemeInfo(themeID)` | Get theme metadata |
+| `fetchThemeData(url)` | Download theme assets |
+| `createAITheme(prompt)` | Generate an AI-powered theme |
+| `produceMetaTheme(config)` | Build a custom Meta theme |
+| `emoji(threadID, emoji)` | Set thread quick-reaction emoji |
+| `stickers(query)` | Search for stickers |
+
+### 📊 Polls, Stories & Notes
+
+| Method | Description |
+|--------|-------------|
+| `createPoll(title, threadID, options)` | Create a poll |
+| `story(action)` | Interact with stories |
+| `notes(action)` | Interact with notes |
+
+### 🌐 HTTP & Media
+
+| Method | Description |
+|--------|-------------|
+| `resolvePhotoUrl(photoID)` | Resolve a photo to a URL |
+| `getMessage(messageID)` | Fetch a specific message |
+| `getAccess(url)` | Get access to a resource |
+| `share(url, threadID)` | Share a link |
+| `httpGet(url, opts)` | Make an authenticated GET request |
+| `httpPost(url, body)` | Make an authenticated POST request |
+| `httpPostFormData(url, form)` | POST with form-data payload |
+
+### 📡 Real-time & MQTT
+
+| Method | Description |
+|--------|-------------|
+| `listen(callback)` | Listen to all events via MQTT |
+| `listenMqtt(callback)` | Raw MQTT listener |
+| `listenSpeed(callback)` | High-speed optimized listener |
+| `realtime(action)` | Perform realtime actions |
+| `mqttDeltaValue(key)` | Read an MQTT delta value |
+
+### 🔒 End-to-End Encryption (E2EE)
+
+| Method | Description |
+|--------|-------------|
+| `e2ee.enable()` | Enable end-to-end encryption |
+| `e2ee.disable()` | Disable encryption |
+| `e2ee.isEnabled()` | Check if encryption is active |
+| `e2ee.getPublicKey()` | Get own public key |
+| `e2ee.setPeerKey(threadID, pubKey)` | Register a peer's public key |
+| `e2ee.clearPeerKey(threadID)` | Remove a peer key |
+| `e2ee.hasPeer(threadID)` | Check if a peer key exists |
+| `e2ee.encrypt(threadID, text)` | Encrypt a message |
+| `e2ee.decrypt(threadID, armored)` | Decrypt a message |
+| `e2ee.encryptBatch(entries)` | Batch encrypt multiple messages |
+| `e2ee.decryptBatch(entries)` | Batch decrypt multiple messages |
+| `e2ee.exportKeyring()` | Export the full key bundle |
+| `e2ee.importKeyring(keyring)` | Import a key bundle |
+| `e2ee.rotatePeerKey(threadID, newKey)` | Rotate a peer's key |
+| `e2ee.clearAllPeers()` | Remove all registered peer keys |
+| `e2ee.getStats()` | Get encryption statistics |
+
+### 🔌 Session & Extensions
+
+| Method | Description |
+|--------|-------------|
+| `logout()` | Logout and clean up session |
+| `addExternalModule(module)` | Extend the FCA with a custom module |
+
+---
+
+## 🛡️ Global Subsystems
+
+Advanced programmatic control over the FCA internals:
+
+```javascript
+const {
+  globalShield,             // Smart shield & circuit breaker
+  globalAntiSuspension,     // Suspension prevention system
+  globalReviveManager,      // Automatic session revival
+  globalAutoReLoginManager, // Auto re-login on session expiry
+  globalGate,               // Request gate controller
+  globalRateLimiter,        // Rate limiter (token bucket)
+  configureRateLimiter,     // Configure rate limits
+  getRateLimiterStats,      // Get current rate limit stats
+  globalMonitor,            // System health monitor
+  Telemetry,                // Telemetry class
+  globalCache,              // In-memory data cache
+  DataCache,                // Cache class constructor
+  CycleManager,             // Session cycle manager
+  TokenRefreshManager,      // Token refresh manager
+  globalCipher,             // AES-256-GCM cipher instance
+  PhantomCipher,            // Cipher class constructor
+} = require("fca-phantom");
+```
+
+### `globalShield` — Smart Protection Shield
+
+Detects threat patterns (checkpoint, rate limits, bans) and trips a circuit breaker to pause operations before permanent damage occurs.
+
+```javascript
+if (!globalShield.isHealthy()) {
+  console.warn("Threat detected — holding back requests");
+}
+
+globalShield.tripCircuitBreaker("checkpoint_detected", 3_600_000); // 1 hour
+globalShield.resetCircuitBreaker();
+globalShield.enableWarmup();
+```
+
+### `globalRateLimiter` — Request Rate Control
+
+```javascript
+const { configureRateLimiter, getRateLimiterStats } = require("fca-phantom");
+
+configureRateLimiter({
+  maxRequestsPerSecond: 5,
+  burstCapacity: 10,
+});
+
+const stats = getRateLimiterStats();
+console.log(`Remaining: ${stats.remaining} / ${stats.total}`);
+```
+
+### `globalCache` — In-Memory Data Cache
+
+```javascript
+const { globalCache } = require("fca-phantom");
+
+globalCache.set("myKey", { payload: 42 }, 60_000); // TTL: 60 seconds
+const val = globalCache.get("myKey");
+globalCache.delete("myKey");
+globalCache.flush();
+```
+
+### `globalCipher` — AES-256-GCM Vault
+
+```javascript
+const { globalCipher } = require("fca-phantom");
+
+const key = globalCipher.generateKey();
+const { encrypted, iv, tag } = globalCipher.encrypt("secret", key);
+const decrypted = globalCipher.decrypt({ encrypted, iv, tag }, key);
+
+const token = globalCipher.sign({ userID: "123" }, "my-secret");
+const result = globalCipher.verify(token, "my-secret", 300_000);
+
+const hex   = globalCipher.randomHex(32);
+const equal = globalCipher.secureCompare(tokenA, tokenB);
+```
+
+---
+
+## 🔐 End-to-End Encryption
+
+PHANTOM-FCA has a built-in E2EE layer for encrypted messaging between bots or trusted peers.
+
+```javascript
+phantom.connect(cookies, {}, async (err, api) => {
+  api.e2ee.enable();
+  console.log("Public Key:", api.e2ee.getPublicKey());
+
+  api.e2ee.setPeerKey(threadID, peerPublicKeyBase64);
+
+  const encrypted = api.e2ee.encrypt(threadID, "Top secret message");
+  await api.sendMessage(encrypted, threadID);
+
+  api.listen((err, msg) => {
+    if (api.e2ee.hasPeer(msg.threadID)) {
+      const plain = api.e2ee.decrypt(msg.threadID, msg.body);
+      console.log("Decrypted:", plain);
+    }
+  });
+});
+```
+
+---
+
+## 🔄 Session Revival & Auto-Reconnect
+
+PHANTOM-FCA automatically manages session health with multiple safety layers:
+
+| Layer | Description |
+|-------|-------------|
+| **Auto-reconnect** | Reconnects MQTT on disconnect |
+| **Session revival** | `globalReviveManager` restores expired sessions |
+| **Auto re-login** | Logs in again using saved credentials |
+| **Circuit breaker** | Pauses all requests on checkpoint/ban detection |
+| **SQLite persistence** | Stores session locally for fast cold starts |
+
+```javascript
+const { globalReviveManager } = require("fca-phantom");
+
+globalReviveManager.on("revived", (ctx) => {
+  console.log(`Session revived for user: ${ctx.userID}`);
+});
+
+globalReviveManager.on("failed", (err) => {
+  console.error("Revival failed:", err.message);
+});
+```
+
+---
+
+## 📨 Message Types
+
+```javascript
+api.listen((err, event) => {
+  switch (event.type) {
+    case "message":           // Incoming message
+    case "event":             // Group/thread event
+    case "typ":               // Typing indicator
+    case "read_receipt":      // Read receipt
+    case "presence":          // Online/offline change
+    case "message_reaction":  // Emoji reaction
+    case "message_unsend":    // Message retracted
+    case "message_reply":     // Reply to a message
+  }
+});
+```
+
+---
+
+## 📤 Rich Message Formats
+
+```javascript
+// Plain text
+api.sendMessage("Hello!", threadID);
+
+// With @mentions
+api.sendMessage({
+  body: "@Alice check this!",
+  mentions: [{ tag: "@Alice", id: "USER_ID", fromIndex: 0 }],
+}, threadID);
+
+// With attachment
+const fs = require("fs");
+api.sendMessage({
+  body: "Here's a file!",
+  attachment: fs.createReadStream("./photo.jpg"),
+}, threadID);
+
+// Poll
+api.createPoll("Favorite language?", threadID, ["JavaScript", "Python", "Rust"]);
+```
+
+---
+
+## 🗃️ Data Persistence
+
+When `sessionPersist: true`, PHANTOM-FCA stores all session data in a local **SQLite database**:
+
+| Store | Contents |
+|-------|----------|
+| **App State** | Encrypted cookie & session tokens |
+| **Threads** | Cached thread metadata |
+| **Users** | Cached user profiles |
+| **Schema** | Auto-migrated on each connect |
+
+---
+
+## 🔧 TypeScript Support
+
+```typescript
+import * as phantom from "fca-phantom";
+
+async function run() {
+  const api = await phantom.connect(cookies, { selfListen: false });
+
+  api.listen((err: Error | null, event: phantom.MessageEvent) => {
+    if (err) throw err;
+    if (event.type === "message") {
+      api.sendMessage("TypeScript reply!", event.threadID);
+    }
+  });
+}
+
+run().catch(console.error);
+```
+
+---
+
+## 📄 License
+
+**MIT** © [PHANTOM-FCA](https://github.com/ewr-sifu/phantom-fca)
+
+Original Author: **SIFAT** — [github.com/Ewr-Sifu](https://github.com/Ewr-Sifu)
+
+---
+
+<div align="center">
+
+*👻 PHANTOM-FCA — Because every message matters.*
+
+*Crafted with passion by **SIFAT**.*
+
+[![npm](https://img.shields.io/badge/npm%20install-fca--phantom-blueviolet?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/fca-phantom)
+[![GitHub](https://img.shields.io/badge/Source-GitHub-181717?style=for-the-badge&logo=github)](https://github.com/ewr-sifu/phantom-fca)
+
+</div>

package/index.js

@@ -0,0 +1,35 @@
+"use strict";
+
+const { connect }                                      = require("./phantom/core/engine");
+const { globalShield, globalAntiSuspension }           = require("./phantom/datastore/models/matrix/ghost");
+const { globalReviveManager, globalAutoReLoginManager } = require("./phantom/datastore/models/matrix/revive");
+const { globalGate, globalRateLimiter, configureRateLimiter, getRateLimiterStats } = require("./phantom/datastore/models/matrix/gate");
+const { globalMonitor, Telemetry }                     = require("./phantom/datastore/models/matrix/telemetry");
+const { globalCache, DataCache }                       = require("./phantom/datastore/models/matrix/store");
+const { CycleManager, TokenRefreshManager }            = require("./phantom/datastore/models/matrix/heartbeat");
+const { globalCipher, PhantomCipher }                  = require("./phantom/datastore/models/cipher/vault");
+const tools = require("./phantom/datastore/models/matrix/tools");
+
+module.exports = {
+    connect,
+
+    globalShield,
+    globalAntiSuspension,
+    globalReviveManager,
+    globalAutoReLoginManager,
+    globalGate,
+    globalRateLimiter,
+    configureRateLimiter,
+    getRateLimiterStats,
+    globalMonitor,
+    Telemetry,
+    globalCache,
+    DataCache,
+    CycleManager,
+    TokenRefreshManager,
+    globalCipher,
+    PhantomCipher,
+
+    ...tools,
+    default: { connect },
+};