@lazyneoaz/metachat 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/metachat
+
+[![npm version](https://img.shields.io/npm/v/@lazyneoaz/metachat.svg)](https://www.npmjs.com/package/@lazyneoaz/metachat)
+[![npm downloads](https://img.shields.io/npm/dm/@lazyneoaz/metachat.svg)](https://www.npmjs.com/package/@lazyneoaz/metachat)
+[![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/metachat.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/metachat
+```
+
+---
+
+## Quick Start
+
+```js
+const { login } = require('@lazyneoaz/metachat');
+
+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/metachat');
+
+(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/metachat](https://www.npmjs.com/package/@lazyneoaz/metachat)
+
+---
+
+## License
+
+MIT

package/index.js

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

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@lazyneoaz/metachat",
+  "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/",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lazyneoaz/metachat.git"
+  },
+  "author": "NeoKEX",
+  "contributors": [
+    "NeoKEX"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/lazyneoaz/metachat/issues"
+  },
+  "homepage": "https://neoaz.is-a.dev",
+  "keywords": [
+    "facebook",
+    "messenger",
+    "chat",
+    "bot",
+    "fca",
+    "mqtt",
+    "messaging",
+    "api",
+    "automation",
+    "facebook-chat-api",
+    "metachat"
+  ],
+  "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 @lazyneoaz/metachat for npm...\"",
+    "test": "echo \"No tests configured yet\""
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

package/src/apis/changeAdminStatus.js

@@ -0,0 +1,148 @@
+"use strict";
+
+const utils = require('../utils');
+
+function generateOfflineThreadingID() {
+    return Date.now().toString() + Math.floor(Math.random() * 1000000).toString();
+}
+
+function getType(obj) {
+    return Object.prototype.toString.call(obj).slice(8, -1);
+}
+
+module.exports = function (defaultFuncs, api, ctx) {
+    return function changeAdminStatus(threadID, adminID, adminStatus, callback) {
+        let resolveFunc = function() {};
+        let rejectFunc = function() {};
+        const returnPromise = new Promise(function(resolve, reject) {
+            resolveFunc = resolve;
+            rejectFunc = reject;
+        });
+
+        if (!callback) {
+            callback = function(err, data) {
+                if (err) return rejectFunc(err);
+                resolveFunc(data);
+            };
+        }
+
+        if (getType(threadID) !== "String") {
+            return callback({ error: "changeAdminStatus: threadID must be a string" });
+        }
+        if (getType(adminID) !== "String" && getType(adminID) !== "Array") {
+            return callback({ error: "changeAdminStatus: adminID must be a string or an array" });
+        }
+        if (getType(adminStatus) !== "Boolean") {
+            return callback({ error: "changeAdminStatus: adminStatus must be true or false" });
+        }
+
+        if (ctx.mqttClient) {
+            const tasks = [];
+            const isAdmin = adminStatus ? 1 : 0;
+            const epochID = generateOfflineThreadingID();
+
+            if (getType(adminID) === "Array") {
+                adminID.forEach((id, index) => {
+                    tasks.push({
+                        failure_count: null,
+                        label: "25",
+                        payload: JSON.stringify({
+                            thread_key: threadID,
+                            contact_id: id,
+                            is_admin: isAdmin
+                        }),
+                        queue_name: "admin_status",
+                        task_id: index + 1
+                    });
+                });
+            } else {
+                tasks.push({
+                    failure_count: null,
+                    label: "25",
+                    payload: JSON.stringify({
+                        thread_key: threadID,
+                        contact_id: adminID,
+                        is_admin: isAdmin
+                    }),
+                    queue_name: "admin_status",
+                    task_id: 1
+                });
+            }
+
+            let count_req = 0;
+            const form = JSON.stringify({
+                app_id: "2220391788200892",
+                payload: JSON.stringify({
+                    epoch_id: epochID,
+                    tasks: tasks,
+                    version_id: "8798795233522156"
+                }),
+                request_id: ++count_req,
+                type: 3
+            });
+
+            ctx.mqttClient.publish("/ls_req", form, {}, (err, _packet) => {
+                if (err) {
+                    utils.error("changeAdminStatus (MQTT)", err);
+                    return callback(err);
+                } else {
+                    utils.log("Admin status changed successfully via MQTT");
+                    return callback(null, { success: true });
+                }
+            });
+        } else {
+            utils.warn("MQTT client not available, using HTTP fallback for changeAdminStatus");
+            const tasks = [];
+            const epochID = generateOfflineThreadingID();
+
+            if (getType(adminID) === "Array") {
+                adminID.forEach((id, index) => {
+                    tasks.push({
+                        label: '25',
+                        payload: JSON.stringify({ thread_key: threadID, contact_id: id, is_admin: adminStatus }),
+                        queue_name: 'admin_status',
+                        task_id: index + 1,
+                        failure_count: null
+                    });
+                });
+            } else {
+                tasks.push({
+                    label: '25',
+                    payload: JSON.stringify({ thread_key: threadID, contact_id: adminID, is_admin: adminStatus }),
+                    queue_name: 'admin_status',
+                    task_id: 1,
+                    failure_count: null
+                });
+            }
+
+            const form = {
+                fb_dtsg: ctx.fb_dtsg,
+                request_id: 1,
+                type: 3,
+                payload: {
+                    version_id: '3816854585040595',
+                    tasks: tasks,
+                    epoch_id: epochID,
+                    data_trace_id: null
+                },
+                app_id: '772021112871879'
+            };
+
+            form.payload = JSON.stringify(form.payload);
+
+            defaultFuncs
+                .post("https://www.facebook.com/api/graphqlbatch/", ctx.jar, form)
+                .then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+                .then(() => {
+                    utils.log("Admin status changed successfully via HTTP");
+                    callback(null, { success: true });
+                })
+                .catch(err => {
+                    utils.error("changeAdminStatus (HTTP)", err);
+                    callback(err);
+                });
+        }
+
+        return returnPromise;
+    };
+};

package/src/apis/changeArchivedStatus.js

@@ -0,0 +1,61 @@
+"use strict";
+
+const utils = require('../utils');
+
+module.exports = (defaultFuncs, api, ctx) => {
+  return async function changeArchivedStatus(threadIDs, archive, 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 (utils.getType(archive) === "Function") {
+        callback = archive;
+        archive = true;
+      }
+
+      if (utils.getType(archive) !== "Boolean") {
+        throw new Error("archive parameter must be a boolean");
+      }
+
+      if (!Array.isArray(threadIDs)) {
+        threadIDs = [threadIDs];
+      }
+
+      const form = {
+        should_archive: archive
+      };
+      
+      threadIDs.forEach(id => {
+        form[`thread_fbids[${id}]`] = true;
+      });
+
+      const res = await defaultFuncs.post(
+        "https://www.facebook.com/ajax/mercury/change_archived_status.php",
+        ctx.jar,
+        form
+      ).then(utils.parseAndCheckLogin(ctx, defaultFuncs));
+
+      if (res && res.error) {
+        throw res;
+      }
+
+      callback(null, { success: true });
+    } catch (err) {
+      utils.error("changeArchivedStatus", err);
+      callback(err);
+    }
+
+    return returnPromise;
+  };
+};