@cexy/hoonfca 1.0.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,3 @@
+All rights reserved to NeoKEX(github.com/NeoKEX)
+❌ PLEASE DO NOT STOLE MY SOURCE CODES AND CLAIM AS YOURS
+Thanks for supporting ^_^

package/README.md

@@ -1,83 +1,491 @@
-@cexy/hoonfca
+# nkxfca
 
-A modern, fast, and actively maintained Facebook Chat API for Node.js.
-Built for Messenger bots with improved stability, performance, and compatibility.
+[![npm version](https://img.shields.io/npm/v/@neoaz07/nkxfca.svg)](https://www.npmjs.com/package/@neoaz07/nkxfca)
+[![npm downloads](https://img.shields.io/npm/dm/@neoaz07/nkxfca.svg)](https://www.npmjs.com/package/@neoaz07/nkxfca)
+[![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/@neoaz07/nkxfca.svg)](https://nodejs.org)
+
+**nkxfca** is an advanced Facebook Chat API (FCA) client built for **reliable**, **real-time**, and **modular** interaction with Facebook Messenger.
+
+Developed and maintained by **[NeoKEX](https://github.com/NeoKEX)**.  
+Inspired by **ws3-fca** and **@dongdev/fca-unofficial**
+
+---
+
+## Documentation
+
+- **[Cookie Login Guide](COOKIE_LOGIN.md)** — Authenticate using browser cookies
+- **[Changelog](CHANGELOG.md)** — Version history and updates
+- **[Examples](examples/)** — Code examples and usage patterns
+
+### Support & Issues
+
+- GitHub: [https://github.com/NeoKEX](https://github.com/NeoKEX)
+- Issues: [https://github.com/NeoKEX/nkxfca/issues](https://github.com/NeoKEX/nkxfca/issues)
+
+---
+
+## 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 and accurate concurrency control
+
+**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
+
+---
+
+## Installation
+
+> **Requirements:** Node.js v20.0.0 or higher
+
+```bash
+npm install @neoaz07/nkxfca
+```
+
+---
+
+## Quick Start
+
+```js
+const fs = require("fs");
+const { login } = require("@neoaz07/nkxfca");
+
+const appState = JSON.parse(fs.readFileSync("appstate.json", "utf8"));
+
+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 || event.type !== "message" || !event.body) return;
+
+    if (event.body === "/ping") {
+      api.sendMessage("pong!", event.threadID);
+    }
+  });
+});
+```
+
+---
+
+## 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());
+});
+```
+
+### Circuit Breaker
+
+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.
+
+You can also trip or reset it manually:
+
+```js
+const { globalAntiSuspension } = require("@neoaz07/nkxfca/src/utils/antiSuspension");
+
+// Manually trip (e.g. after you detect a warning in a response)
+globalAntiSuspension.tripCircuitBreaker("manual_pause", 30 * 60 * 1000); // 30 min
+
+// Reset after you've resolved the issue
+globalAntiSuspension.resetCircuitBreaker();
+
+// Check status
+console.log(globalAntiSuspension.getConfig());
+```
+
+### Warmup Mode
+
+Use warmup mode when starting a fresh or recovered session:
+
+```js
+const { globalAntiSuspension } = require("@neoaz07/nkxfca/src/utils/antiSuspension");
+globalAntiSuspension.enableWarmup(); // limits to 25 msg/hour for 20 minutes
+```
 
 ---
 
-📦 Installation
+## End-to-End Encryption for DMs (Opt-In)
+
+Encrypt and decrypt message bodies in direct chats using X25519 + HKDF + AES-256-GCM.
+
+```js
+api.e2ee.enable();
+
+// Share your bot's public key with the peer
+const botPubKey = api.e2ee.getPublicKey();
+
+// Register the peer's public key for a DM thread
+api.e2ee.setPeerKey(threadID, peerPublicKeyBase64);
+
+// Messages to that thread are now auto-encrypted on send
+// and auto-decrypted on receive
+api.sendMessage("Top secret message", threadID);
+```
+
+---
+
+## Security Warning
+
+`appstate.json` contains your Facebook session and must be treated like a password:
+
+- **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
+
+---
+
+## Getting Started — Generate `appstate.json`
+
+1. Install a cookie export extension:
+   - Chrome/Edge: **C3C FbState** or **CookieEditor**
+   - Firefox: **Cookie-Editor**
+
+2. Log in to Facebook in your browser
+
+3. Export cookies as JSON and save as `appstate.json`:
+
+```json
+[
+  { "key": "c_user", "value": "your-user-id" },
+  { "key": "xs", "value": "your-xs-value" }
+]
+```
 
-Install the package using npm:
+4. Use in your bot:
 
-npm install @cexy/rakibfca
+```js
+const { login } = require("@neoaz07/nkxfca");
+const appState = require("./appstate.json");
+login({ appState }, {}, (err, api) => { ... });
+```
+
+See **[COOKIE_LOGIN.md](COOKIE_LOGIN.md)** for more formats and troubleshooting.
 
 ---
 
-🚀 Usage
+## Bot Example with Commands
+
+```js
+const fs = require("fs");
+const path = require("path");
+const { login } = require("@neoaz07/nkxfca");
 
-const login = require("@cexy/rakibfca");
+const appState = JSON.parse(fs.readFileSync("appstate.json", "utf8"));
 
-login(
-  {
-    appState: require("./appstate.json")
-  },
-  (err, api) => {
-    if (err) return console.error(err);
+login({ appState }, {
+  online: true,
+  selfListen: false,
+  simulateTyping: true,
+  autoReconnect: true
+}, async (err, api) => {
+  if (err) return console.error("Login error:", err);
 
-    console.log("Logged in as:", api.getCurrentUserID());
+  console.log("Logged in as:", api.getCurrentUserID());
 
-    api.listenMqtt((err, event) => {
-      if (err) return console.error(err);
+  const commandsDir = path.join(__dirname, "commands");
+  const commands = new Map();
 
-      console.log(event);
-    });
+  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);
+      }
+    }
   }
-);
+
+  api.listenMqtt(async (err, event) => {
+    if (err || event.type !== "message" || !event.body) return;
+
+    const prefix = "/";
+    if (!event.body.startsWith(prefix)) return;
+
+    const args = event.body.slice(prefix.length).trim().split(/ +/);
+    const name = args.shift().toLowerCase();
+    const cmd = commands.get(name);
+    if (!cmd) return;
+
+    try {
+      await cmd.execute({ api, event, args });
+    } catch (e) {
+      console.error(`Error in /${name}:`, e.message);
+      api.sendMessage("An error occurred.", event.threadID);
+    }
+  });
+});
+```
 
 ---
 
-✨ Features
+## AI Themes
 
-- ⚡ Fast and lightweight
-- 🔒 AppState login support
-- 💬 Messenger API support
-- 📩 MQTT listener
-- 🛠️ Regular bug fixes
-- 🚀 Performance improvements
-- 📦 Easy integration with Node.js projects
+```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);
+}
+
+// Browse standard themes
+const themes = await api.getTheme(threadID);
+await api.setThreadThemeMqtt(threadID, themes[0].id);
+
+// Check current theme
+const info = await api.getThemeInfo(threadID);
+console.log(info.color, info.emoji);
+```
 
 ---
 
-📋 Requirements
+## 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 |
 
-- Node.js 20+
-- npm 10+
+### 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 |
 
 ---
 
-📖 Installation Example
+## Login Options
 
-mkdir my-bot
-cd my-bot
-npm init -y
-npm install @cexy/rakibfca
+| 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
+## Examples
 
-Contributions, bug reports, and feature requests are always welcome.
+See the **[examples/](examples/)** directory:
+- `login-with-cookies.js` — Cookie-based authentication guide
+- `verify.js` — Verify the library loads correctly
 
 ---
 
-📄 License
+## Credits
 
-MIT License
+- **Developed and maintained by [NeoKEX](https://github.com/NeoKEX)**
+- **NeoKEX Team** — development, maintenance, and feature contributions
+- **Inspired by ws3-fca** — by @NethWs3Dev and @CommunityExocore
+
+> Copyright (c) 2026 NeoKEX
 
 ---
 
-👨‍💻 Author
+## License
+
+**MIT** — Free to use, modify, and distribute. Attribution appreciated.
+
+See [LICENSE](LICENSE) for full license text.
+
+---
 
-Rakib Hasan
+## Links
 
-NPM: @cexy/hoonfca
+- **npm:** [https://www.npmjs.com/package/@neoaz07/nkxfca](https://www.npmjs.com/package/@neoaz07/nkxfca)
+- **GitHub:** [https://github.com/NeoKEX](https://github.com/NeoKEX)
+- **Issues:** [https://github.com/NeoKEX/nkxfca/issues](https://github.com/NeoKEX/nkxfca/issues)

package/examples/login-with-cookies.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Example: Login with Cookie Array
+ * 
+ * This demonstrates how to login to Facebook Chat API using a cookie array
+ * instead of email/password credentials.
+ * 
+ * Cookie Format:
+ * - Array of objects with 'name' (or 'key') and 'value' properties
+ * - Extracted from browser cookies or previous session
+ */
+
+const login = require('../index.js');
+
+// Method 1: Cookie Array with 'name' property
+const cookieArray = [
+    {
+        name: 'c_user',
+        value: 'YOUR_USER_ID_HERE'
+    },
+    {
+        name: 'xs',
+        value: 'YOUR_XS_TOKEN_HERE'
+    },
+    {
+        name: 'fr',
+        value: 'YOUR_FR_TOKEN_HERE'
+    },
+    {
+        name: 'datr',
+        value: 'YOUR_DATR_TOKEN_HERE'
+    }
+];
+
+// Method 2: Cookie Array with 'key' property (alternative)
+const cookieArrayAlt = [
+    {
+        key: 'c_user',
+        value: 'YOUR_USER_ID_HERE'
+    },
+    {
+        key: 'xs',
+        value: 'YOUR_XS_TOKEN_HERE'
+    }
+];
+
+// Method 3: Cookie String format (semicolon-separated)
+const cookieString = 'c_user=YOUR_USER_ID_HERE; xs=YOUR_XS_TOKEN_HERE; fr=YOUR_FR_TOKEN_HERE; datr=YOUR_DATR_TOKEN_HERE';
+
+/**
+ * Login using cookie array
+ */
+async function loginWithCookies() {
+    try {
+        const api = await login.login({
+            appState: cookieArray // Pass the cookie array here
+        }, {
+            logging: true,
+            listenEvents: true,
+            autoMarkRead: true,
+            selfListen: false
+        });
+
+        console.log('✓ Successfully logged in using cookies!');
+        console.log('✓ User ID:', api.getCurrentUserID());
+
+        // Now you can use the API normally
+        // Example: Send a message
+        // api.sendMessage("Hello World!", threadID);
+
+        // Clean up
+        api.stopListening();
+        process.exit(0);
+
+    } catch (error) {
+        console.error('✗ Login failed:', error.message);
+        process.exit(1);
+    }
+}
+
+/**
+ * How to extract cookies from your browser:
+ * 
+ * 1. Open Facebook in your browser
+ * 2. Open Developer Tools (F12)
+ * 3. Go to Application → Cookies → facebook.com
+ * 4. Copy the critical cookies:
+ *    - c_user: Your user ID
+ *    - xs: Session token
+ *    - fr: Fraud detection
+ *    - datr: Device fingerprint
+ * 
+ * 5. Replace the values in cookieArray above
+ * 6. Run: node examples/login-with-cookies.js
+ */
+
+// Uncomment to run:
+// loginWithCookies();
+
+module.exports = { loginWithCookies, cookieArray };