@lazyneoaz/nkxchat 1.0.0

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

@@ -0,0 +1,199 @@
+# @lazyneoaz/nkxchat
+
+[![npm version](https://img.shields.io/npm/v/@lazyneoaz/nkxchat.svg)](https://www.npmjs.com/package/@lazyneoaz/nkxchat)
+[![npm downloads](https://img.shields.io/npm/dm/@lazyneoaz/nkxchat.svg)](https://www.npmjs.com/package/@lazyneoaz/nkxchat)
+[![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/@lazyneoaz/nkxchat.svg)](https://nodejs.org)
+
+Advanced Facebook Chat API client for building Messenger bots — real-time messaging, thread management, MQTT, and session stability.
+
+---
+
+## Installation
+
+```bash
+npm install @lazyneoaz/nkxchat
+```
+
+---
+
+## Quick Start
+
+```js
+const { login } = require('@lazyneoaz/nkxchat');
+
+login({ appState: require('./appstate.json') }, (err, api) => {
+  if (err) return console.error(err);
+
+  api.listenMqtt((err, event) => {
+    if (err) return console.error(err);
+    if (event.type === 'message') {
+      api.sendMessage('Hello!', event.threadID);
+    }
+  });
+});
+```
+
+### Promise / async style
+
+```js
+const { login } = require('@lazyneoaz/nkxchat');
+
+(async () => {
+  const api = await login({ appState: require('./appstate.json') });
+
+  api.listenMqtt((err, event) => {
+    if (event.type === 'message') {
+      api.sendMessage(`Echo: ${event.body}`, event.threadID);
+    }
+  });
+})();
+```
+
+---
+
+## Authentication
+
+| Method | Description |
+|---|---|
+| `appState` | Array of cookie objects from a browser session. **Recommended.** |
+| `Cookie` | Raw cookie header string |
+| `email` + `password` | Credential login (may trigger checkpoints — not recommended) |
+
+---
+
+## API Reference
+
+### Messages
+| Method | Description |
+|---|---|
+| `sendMessage(msg, threadID, [cb])` | Send text, attachments, stickers, mentions |
+| `editMessage(text, messageID, [cb])` | Edit a sent message |
+| `unsendMessage(messageID, [cb])` | Retract a message |
+| `deleteMessage(messageIDs, [cb])` | Delete messages locally |
+| `setMessageReaction(reaction, messageID, [cb])` | React to a message |
+| `sendTypingIndicator(threadID, [cb])` | Show/hide typing indicator |
+| `markAsRead(threadID, [cb])` | Mark thread as read |
+| `markAsDelivered(threadID, messageID, [cb])` | Mark as delivered |
+| `markAsSeen([cb])` | Mark all as seen |
+| `markAsReadAll([cb])` | Mark all threads as read |
+| `uploadAttachment(streams, [cb])` | Upload files, get attachment IDs |
+| `forwardAttachment(ids, threadID, [cb])` | Forward attachments to a thread |
+| `forwardMessage(messageID, threadIDs, [cb])` | Forward a message |
+| `shareContact(text, userID, threadID, [cb])` | Share a contact card |
+| `getMessage(messageID, [cb])` | Fetch a message by ID |
+| `resolvePhotoUrl(fbid, [cb])` | Resolve full-resolution photo URL |
+| `getEmojiUrl(char, size, [pixelRatio])` | Get CDN URL for an emoji image |
+| `getThreadColors([query])` | List all Messenger color themes |
+| `changeThreadColor(color, threadID, [cb])` | Change thread color |
+| `changeThreadEmoji(emoji, threadID, [cb])` | Change thread emoji |
+| `sendEffect(type, msg, threadID, [cb])` | Send a message effect (fire, confetti, etc.) |
+| `pinMessage(messageID, threadID, [cb])` | Pin a message |
+| `setPostReaction(postID, type, [cb])` | React to a Facebook post |
+
+### Threads
+| Method | Description |
+|---|---|
+| `getThreadInfo(threadID, [cb])` | Get thread details |
+| `getThreadList(limit, cursor, tags, [cb])` | List threads |
+| `getThreadHistory(threadID, amount, timestamp, [cb])` | Get message history |
+| `getThreadPictures(threadID, offset, limit, [cb])` | Get shared photos |
+| `getThemePictures(themeID, [cb])` | Get theme asset images |
+| `searchForThread(query, [cb])` | Search threads |
+| `createNewGroup(name, userIDs, [cb])` | Create a group |
+| `addUserToGroup(userID, threadID, [cb])` | Add user to group |
+| `removeUserFromGroup(userID, threadID, [cb])` | Remove user from group |
+| `changeAdminStatus(threadID, userID, adminStatus, [cb])` | Set admin status |
+| `changeGroupImage(image, threadID, [cb])` | Update group photo |
+| `changeNickname(nickname, threadID, participantID, [cb])` | Set nickname |
+| `setTitle(title, threadID, [cb])` | Change group name |
+| `gcname(name, threadID, [cb])` | Change group name (MQTT) |
+| `createPoll(title, threadID, options, [cb])` | Create a poll |
+| `createAITheme(prompt, threadID, [cb])` | Create AI-generated theme |
+| `deleteThread(threadID, [cb])` | Delete a thread |
+| `changeArchivedStatus(threadID, archived, [cb])` | Archive/unarchive |
+| `muteThread(threadID, muteSeconds, [cb])` | Mute notifications |
+| `handleMessageRequest(threadID, accept, [cb])` | Accept/decline message request |
+| `getTheme(threadID, [cb])` | Get thread theme |
+| `setThreadTheme(threadID, themeID, [cb])` | Set thread theme |
+
+### Users
+| Method | Description |
+|---|---|
+| `getUserInfo(userIDs, [cb])` | Get user info by ID(s) |
+| `getUserInfoV2(userID, [cb])` | Alternative user info endpoint |
+| `getUserID(name, [cb])` | Resolve username to user ID |
+| `getFriendsList([cb])` | Get friends list |
+| `getCurrentUserID()` | Get the logged-in user's ID |
+
+### Account
+| Method | Description |
+|---|---|
+| `changeAvatar(image, [cb])` | Update profile picture |
+| `changeBio(bio, [cb])` | Update bio |
+| `changeBlockedStatus(userID, block, [cb])` | Block/unblock a user |
+| `handleFriendRequest(userID, accept, [cb])` | Accept/decline friend request |
+| `unfriend(userID, [cb])` | Remove friend |
+| `follow(userID, follow, [cb])` | Follow/unfollow a user |
+| `refreshFb_dtsg([payload], [cb])` | Refresh session security token |
+| `enableAutoSaveAppState([options])` | Auto-save cookies to file |
+| `logout([cb])` | End session |
+| `addExternalModule(name, module)` | Add an external module |
+
+### HTTP Utilities
+| Method | Description |
+|---|---|
+| `httpGet(url, qs, [cb])` | Authenticated GET request |
+| `httpPost(url, form, [cb])` | Authenticated POST request |
+| `httpPostFormData(url, form, [cb])` | Multipart POST request |
+
+### Realtime
+| Method | Description |
+|---|---|
+| `listenMqtt(cb)` | Start MQTT listener for real-time events |
+
+---
+
+## Events
+
+| Type | Description |
+|---|---|
+| `message` | Incoming message |
+| `message_reply` | Reply to a message |
+| `message_reaction` | Reaction added/removed |
+| `message_unsend` | Message retracted |
+| `event` | Thread event (join, leave, name change, etc.) |
+| `typ` | Typing indicator |
+| `read` / `read_receipt` | Read receipt |
+| `presence` | Online/offline status |
+
+---
+
+## Options
+
+```js
+api.setOptions({
+  listenEvents: true,      // receive thread events (joins, leaves, etc.)
+  selfListen: false,       // receive own messages
+  autoMarkRead: false,     // auto-mark incoming messages as read
+  autoReconnect: true,     // reconnect MQTT on disconnect
+  online: false,           // appear online
+  logLevel: 'info',        // 'silent' | 'info' | 'warn' | 'error'
+});
+```
+
+---
+
+## Credits
+
+Developed and maintained by **NeoKEX**
+
+- GitHub: [https://github.com/lazyneoaz](https://github.com/lazyneoaz)
+- Website: [https://neoaz.is-a.dev](https://neoaz.is-a.dev)
+- npm: [https://www.npmjs.com/package/@lazyneoaz/nkxchat](https://www.npmjs.com/package/@lazyneoaz/nkxchat)
+
+---
+
+## License
+
+MIT

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 };

package/examples/verify.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Quick sanity check — verifies the library loads correctly and
+ * prints the anti-suspension configuration. Run with:
+ *   node examples/verify.js
+ */
+
+const fca = require('../index.js');
+const { globalAntiSuspension } = require('../src/utils/antiSuspension');
+const { globalRateLimiter } = require('../src/utils/rateLimiter');
+
+console.log('dhoner-fca Library Verification');
+console.log('================================\n');
+
+console.log('Library entry point:', typeof fca.login === 'function' ? 'OK' : 'FAIL');
+
+const config = globalAntiSuspension.getConfig();
+console.log('\nAnti-Suspension Configuration:');
+console.log(`  Message Delay       : ${config.messageDelayMs}ms`);
+console.log(`  Thread Delay        : ${config.threadDelayMs}ms`);
+console.log(`  Max Login Tries     : ${config.maxLoginAttempts}`);
+console.log(`  Login Cooldown      : ${config.loginCooldownMs}ms`);
+console.log(`  Daily Msg Limit     : ${config.dailyStats.maxDailyMessages}`);
+console.log(`  Hourly Msg Limit    : ${config.hourlyStats.maxPerHour}`);
+
+console.log('\nEnabled Features:');
+Object.entries(config.features).forEach(([feature, enabled]) => {
+    console.log(`  ${enabled ? '[x]' : '[ ]'} ${feature}`);
+});
+
+const activityPattern = globalAntiSuspension.getRealisticActivityPattern();
+console.log('\nActivity Pattern:');
+console.log(`  Current activity  : ${activityPattern.messageFrequency}`);
+console.log(`  Next action delay : ${activityPattern.nextActionDelayMs.toFixed(0)}ms`);
+console.log(`  Is active hours   : ${activityPattern.isActiveHours}`);
+
+console.log('\nCircuit Breaker:');
+console.log(`  Tripped           : ${globalAntiSuspension.isCircuitBreakerTripped()}`);
+console.log(`  Signal count      : ${globalAntiSuspension.suspensionCircuitBreaker.signalCount}`);
+
+const rateLimiterStats = globalRateLimiter.getStats();
+console.log('\nRate Limiter:');
+console.log(`  Max concurrent    : ${rateLimiterStats.maxConcurrentRequests}`);
+console.log(`  Max per minute    : ${rateLimiterStats.maxRequestsPerMinute}`);
+console.log(`  Requests (1 min)  : ${rateLimiterStats.requestsInLastMinute}`);
+
+// Test suspension signal detection
+const testSignals = [
+    { text: 'Everything is fine, message sent', expectSuspicion: false },
+    { text: 'Your account has been suspended due to policy violation', expectSuspicion: true },
+    { text: 'checkpoint required to verify identity', expectSuspicion: true },
+    { text: 'Too many requests - rate limited', expectSuspicion: true },
+    { text: 'Unusual activity detected on your account', expectSuspicion: true },
+];
+console.log('\nSuspension Signal Detection:');
+testSignals.forEach(({ text, expectSuspicion }) => {
+    globalAntiSuspension.resetCircuitBreaker();
+    const detected = globalAntiSuspension.detectSuspensionSignal(text);
+    const passed = detected === expectSuspicion;
+    globalAntiSuspension.resetCircuitBreaker();
+    console.log(`  ${passed ? '[x]' : '[!]'} "${text.substring(0, 40)}" → ${detected ? 'SUSPICIOUS' : 'CLEAN'}`);
+});
+globalAntiSuspension.resetCircuitBreaker();
+
+console.log('\nAll checks passed. Library is ready to use.');
+console.log('============================\n');
+
+process.exit(0);

package/index.js

@@ -0,0 +1,2 @@
+"use strict";
+module.exports = require('./src/engine/client');

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@lazyneoaz/nkxchat",
+  "version": "1.0.0",
+  "type": "commonjs",
+  "types": "src/types/index.d.ts",
+  "description": "Advanced Facebook Chat API client for building Messenger bots — real-time messaging, thread management, MQTT, and session stability.",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "src/",
+    "examples/",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lazyneoaz/nkxchat.git"
+  },
+  "author": "NeoKEX",
+  "contributors": [
+    "NeoKEX"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/lazyneoaz/nkxchat/issues"
+  },
+  "homepage": "https://neoaz.is-a.dev",
+  "keywords": [
+    "facebook",
+    "messenger",
+    "chat",
+    "bot",
+    "fca",
+    "mqtt",
+    "messaging",
+    "api",
+    "automation",
+    "facebook-chat-api",
+    "nkxchat"
+  ],
+  "dependencies": {
+    "axios": "^1.13.5",
+    "axios-cookiejar-support": "^4.0.7",
+    "bluebird": "^3.7.2",
+    "cheerio": "^1.0.0",
+    "cli-progress": "^3.12.0",
+    "deepdash": "^5.3.9",
+    "duplexify": "^4.1.3",
+    "form-data": "^4.0.4",
+    "gradient-string": "^3.0.0",
+    "https-proxy-agent": "^7.0.6",
+    "jsonpath-plus": "^10.3.0",
+    "lodash": "^4.17.21",
+    "mqtt": "^4.3.8",
+    "node-cron": "^3.0.3",
+    "ora": "^9.4.0",
+    "picocolors": "^1.1.1",
+    "sequelize": "^6.37.5",
+    "sqlite3": "^5.1.7",
+    "totp-generator": "^2.0.1",
+    "tough-cookie": "^4.1.4",
+    "undici": "^6.21.0",
+    "uuid": "^9.0.1",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/form-data": "^2.2.1",
+    "@types/node": "^20.17.6",
+    "@types/tough-cookie": "^4.0.5",
+    "eslint": "^9.15.0",
+    "mocha": "^10.7.3",
+    "prettier": "^3.4.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "validate": "npm pack --dry-run",
+    "prepack": "echo \"Preparing package for npm...\"",
+    "test": "echo \"No tests configured yet\""
+  }
+}

package/src/apis/addExternalModule.js

@@ -0,0 +1,24 @@
+"use strict";
+const utils = require('../utils');
+
+module.exports = function (defaultFuncs, api, ctx) {
+  return function addExternalModule(moduleObj) {
+    if (utils.getType(moduleObj) == "Object") {
+      for (const apiName in moduleObj) {
+        if (utils.getType(moduleObj[apiName]) == "Function") {
+          api[apiName] = moduleObj[apiName](defaultFuncs, api, ctx);
+        } else {
+          throw new Error(
+            `Item "${apiName}" in moduleObj must be a function, not ${utils.getType(
+              moduleObj[apiName],
+            )}!`,
+          );
+        }
+      }
+    } else {
+      throw new Error(
+        `moduleObj must be an object, not ${utils.getType(moduleObj)}!`,
+      );
+    }
+  };
+};

package/src/apis/addUserToGroup.js

@@ -0,0 +1,108 @@
+"use strict";
+
+const utils = require('../utils');
+
+module.exports = (defaultFuncs, api, ctx) => {
+  return async function addUserToGroup(userID, threadID, callback) {
+    let resolveFunc = () => {};
+    let rejectFunc = () => {};
+    const returnPromise = new Promise((resolve, reject) => {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+
+    if (!callback) {
+      callback = (err, result) => {
+        if (err) return rejectFunc(err);
+        resolveFunc(result);
+      };
+    }
+
+    try {
+      if (!ctx.mqttClient) {
+        throw new Error("Not connected to MQTT. Please use listenMqtt first.");
+      }
+
+      if (utils.getType(threadID) !== "Number" && utils.getType(threadID) !== "String") {
+        throw new Error("ThreadID should be of type Number or String");
+      }
+
+      if (utils.getType(userID) !== "Array") {
+        userID = [userID];
+      }
+
+      const reqID = ++ctx.wsReqNumber;
+      const taskID = ++ctx.wsTaskNumber;
+
+      const payload = {
+        epoch_id: utils.generateOfflineThreadingID(),
+        tasks: [
+          {
+            failure_count: null,
+            label: "23",
+            payload: JSON.stringify({
+              thread_key: threadID,
+              contact_ids: userID,
+              sync_group: 1
+            }),
+            queue_name: threadID.toString(),
+            task_id: taskID
+          }
+        ],
+        version_id: "24502707779384158"
+      };
+
+      const form = JSON.stringify({
+        app_id: "772021112871879",
+        payload: JSON.stringify(payload),
+        request_id: reqID,
+        type: 3
+      });
+
+      let responseHandled = false;
+      const handleRes = (topic, message) => {
+        if (topic !== "/ls_resp" || responseHandled) return;
+        let jsonMsg;
+        try {
+          jsonMsg = JSON.parse(message.toString());
+          jsonMsg.payload = JSON.parse(jsonMsg.payload);
+        } catch {
+          return;
+        }
+        if (jsonMsg.request_id !== reqID) return;
+        responseHandled = true;
+        clearTimeout(timeout);
+        ctx.mqttClient.removeListener("message", handleRes);
+        callback(null, { success: true, response: jsonMsg.payload });
+        resolveFunc({ success: true, response: jsonMsg.payload });
+      };
+
+      const timeout = setTimeout(() => {
+        if (!responseHandled) {
+          responseHandled = true;
+          ctx.mqttClient.removeListener("message", handleRes);
+          const err = new Error("MQTT request timeout");
+          callback(err);
+          rejectFunc(err);
+        }
+      }, 30000);
+
+      ctx.mqttClient.on("message", handleRes);
+      ctx.mqttClient.publish("/ls_req", form, { qos: 1, retain: false }, (err) => {
+        if (err && !responseHandled) {
+          responseHandled = true;
+          clearTimeout(timeout);
+          ctx.mqttClient.removeListener("message", handleRes);
+          callback(err);
+          rejectFunc(err);
+        }
+      });
+    } catch (err) {
+      utils.error("addUserToGroup", err);
+      callback(err);
+      rejectFunc(err);
+    }
+
+    return returnPromise;
+  };
+};