@vangbanlanhat/fca-unofficial 1.4.2

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Avery, Benjamin, David, Maude
+
+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.

package/README.md

@@ -0,0 +1,198 @@
+# Unofficial Facebook Chat API
+
+<div align="center">
+  <a href="https://www.npmjs.com/package/fca-unofficial"><img alt="npm version" src="https://img.shields.io/npm/v/fca-unofficial.svg?style=flat-square"></a>
+  <img alt="version" src="https://img.shields.io/github/package-json/v/VangBanLaNhat/fca-unofficial?label=github&style=flat-square">
+  <a href="https://www.npmjs.com/package/fca-unofficial"><img src="https://img.shields.io/npm/dm/fca-unofficial.svg?style=flat-square" alt="npm downloads"></a>
+  <a href="https://github.com/prettier/prettier"><img alt="code style: prettier" src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square"></a>
+</div>
+
+This project provides an unofficial API for automating Facebook chat and Messenger functionalities. Facebook has deprecated their XMPP chat interface, leaving emulating a browser as the only viable method for account automation. 
+
+This API simulates exact GET/POST requests and MQTT connections, tricking Facebook into thinking it's a legitimate browser session.
+
+> **Disclaimer:** We are not responsible if your account gets banned for spammy activities (sending messages too quickly, spamming strangers, logging in/out rapidly). Be a responsible Facebook citizen. Use [Facebook Whitehat Accounts](https://www.facebook.com/whitehat/accounts/) for safe testing.
+
+---
+
+## Documentation
+
+For a comprehensive list of all available API methods, options, and parameters, please see the **[Full API Documentation (DOCS.md)](DOCS.md)**.
+
+## Tech Stack
+
+- **Language**: JavaScript (Node.js)
+- **Real-time Protocol**: MQTT (`mqtt` package)
+- **HTML Parsing**: `cheerio`
+- **Networking**: Built-in HTTP/HTTPS + `https-proxy-agent`
+- **Testing Framework**: Jest
+
+## Prerequisites
+
+- **Node.js**: v14.0.0 or higher
+- **NPM or Yarn**: To install dependencies
+- A valid Facebook account or a Facebook Whitehat Account for testing.
+
+## Getting Started
+
+### 1. Installation
+
+Install the package via NPM:
+
+```bash
+npm install @VangBanLaNhat/fca-unofficial
+```
+
+### 2. Basic Echo Bot Example
+
+Create an `index.js` file and add the following code to create a bot that echoes messages back to the sender:
+
+```javascript
+const login = require("@VangBanLaNhat/fca-unofficial");
+
+// Login using your Facebook credentials
+login({email: "FB_EMAIL", password: "FB_PASSWORD"}, (err, api) => {
+    if(err) return console.error("Login failed:", err);
+
+    console.log("Bot successfully logged in!");
+
+    // Start listening for incoming messages
+    api.listen((err, message) => {
+        if(err) return console.error(err);
+
+        // Echo the message back to the same chat thread
+        api.sendMessage("Echo: " + message.body, message.threadID);
+    });
+});
+```
+
+Run your bot:
+```bash
+node index.js
+```
+
+### 3. Saving the Session (Avoiding Bans & Re-logins)
+
+Logging in repeatedly with an email and password is a massive red flag for Facebook's anti-spam systems. **You must save and reuse your session (AppState).**
+
+```javascript
+const fs = require("fs");
+const login = require("@VangBanLaNhat/fca-unofficial");
+
+// 1. Try to load an existing session
+let appState = null;
+try {
+    appState = JSON.parse(fs.readFileSync('appstate.json', 'utf8'));
+} catch (e) {
+    console.log("No saved session found. Logging in with credentials...");
+}
+
+const credentials = appState 
+    ? { appState: appState } 
+    : { email: "FB_EMAIL", password: "FB_PASSWORD" };
+
+login(credentials, (err, api) => {
+    if(err) return console.error(err);
+
+    // 2. Save the session for the next run
+    fs.writeFileSync('appstate.json', JSON.stringify(api.getAppState()));
+    console.log("Logged in and session saved!");
+
+    // ... continue with your bot logic ...
+});
+```
+
+*Alternative:* You can use browser extensions like [c3c-fbstate](https://github.com/lequanglam/c3c-fbstate) to manually extract your `fbstate.json` (appstate) directly from your browser.
+
+## Architecture Overview
+
+This library essentially functions as a headless Facebook web client.
+
+### Request Lifecycle
+1. **Login:** The library performs a sequence of GET/POST requests to Facebook's login endpoints, mimicking a real browser login to acquire authentication cookies (`c_user`, `xs`, etc.).
+2. **Context Creation:** It builds an internal `ctx` (context) object containing your User ID, Client ID, and cookies.
+3. **MQTT Connection:** It establishes an MQTT over WebSockets connection to Facebook's servers to receive real-time events (new messages, typing indicators, read receipts).
+4. **Action Execution:** When you call an API method (like `sendMessage`), the library constructs the exact GraphQL or form-data HTTP request that the Messenger web app would send, and dispatches it.
+
+### Core Directory Structure
+
+```text
+src/
+├── index.js          # Main entrypoint and API builder
+├── actions/      # Contains all the individual API methods
+│   ├── listenMqtt.js # Manages the real-time MQTT socket
+│   ├── sendMessage.js# Handles message formatting and sending
+│   └── ...           # Other actions (reactions, unsending, etc.)
+└── utils/            # Shared utilities
+    ├── auth.js       # Cookie formatting and session extraction
+    ├── base.js       # Core network request wrappers (get, post)
+    ├── formatters.js # Parsers that turn raw FB payloads into clean JSON
+    └── identity.js   # Generators for IDs, GUIDs, and timestamps
+```
+
+## Available Scripts
+
+| Command | Description |
+| --- | --- |
+| `npm run test` | Runs the full Jest test suite |
+| `npm run test:unit` | Runs only unit tests |
+| `npm run test:integration`| Runs integration tests (requires active config) |
+| `npm run lint` | Runs ESLint to check for syntax/style issues |
+| `npm run prettier` | Formats all code using Prettier |
+
+## Testing
+
+The project uses **Jest** for unit and integration testing.
+
+To run the unit tests:
+```bash
+npm run test:unit
+```
+
+To run integration tests (which actually hit Facebook endpoints), you must first create a valid config:
+1. Copy `example-config.json` to `test-config.json` inside the `test` directory.
+2. Fill in your test account credentials or appState.
+3. Run: `npm run test:integration`
+
+## Deployment
+
+Since this is a standard Node.js application, you can deploy your bot anywhere Node.js runs (VPS, Heroku, Render, AWS, Docker).
+
+**Important Deployment Tips:**
+1. **Do not commit `appstate.json` or passwords to Git.** Use environment variables for sensitive data.
+2. **IP Changes:** If you deploy your bot to a cloud server in a different country, Facebook might temporarily lock the account due to a "Suspicious Login". You may need to log into the account manually and approve the new location.
+
+## Troubleshooting
+
+### 1. "Login failed" or getting prompted for a code
+If you have Two-Factor Authentication (2FA) or Login Approvals enabled, you must handle the approval step. Read the specific guide on [handling login approvals](DOCS.md#login).
+
+### 2. My account got locked/banned!
+This happens if you send messages too fast or to people who are not your friends. 
+- Use `setTimeout` to add human-like delays.
+- Always use cached sessions (`appState`) instead of logging in repeatedly.
+- Use a throwaway account for development.
+
+### 3. `sendMessage` isn't working when logged in as a Page
+Facebook Pages cannot initiate conversations with users to prevent spam. Your bot can only reply to users who have messaged the Page first within the last 24 hours.
+
+### 4. How do I stop the spammy console logs?
+Pass a `logLevel` option when configuring the API:
+```javascript
+api.setOptions({
+    logLevel: "silent" // Options: "silly", "verbose", "info", "warn", "error", "silent"
+});
+```
+
+---
+
+## Projects using this API
+
+- [c3c](https://github.com/lequanglam/c3c) - A bot that can be customizable using plugins. Support Facebook & Discord.
+
+**Historical Projects (from the original `facebook-chat-api`):**
+- [Messer](https://github.com/mjkaufer/Messer) - Command-line messaging for Facebook Messenger
+- [messen](https://github.com/tomquirk/messen) - Rapidly build Facebook Messenger apps in Node.js
+- [Concierge](https://github.com/concierge/Concierge) - Modular chat bot with a package manager
+- [Botium](https://github.com/codeforequity-at/botium-core) - The Selenium for Chatbots
+- [Miscord](https://github.com/Bjornskjald/miscord) - Facebook bridge for Discord.

package/jest.config.js

@@ -0,0 +1,10 @@
+"use strict";
+
+module.exports = {
+  testEnvironment: "node",
+  testMatch: ["<rootDir>/test/**/*.test.js"],
+  setupFiles: ["<rootDir>/test/jest.setup.js"],
+  clearMocks: true,
+  restoreMocks: true,
+  verbose: true
+};

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@vangbanlanhat/fca-unofficial",
+  "version": "1.4.2",
+  "main": "src/index.js",
+  "description": "A Facebook chat API that doesn't rely on XMPP. Will NOT be deprecated after April 30th 2015.",
+  "scripts": {
+    "test": "jest --runInBand --testPathIgnorePatterns=\"/test/integration/\"",
+    "test:unit": "jest --runInBand",
+    "test:integration": "jest --runInBand --testPathPattern=\"test/integration\"",
+    "lint": "eslint \"src/**/*.js\" && eslint --env jest \"test/**/*.js\"",
+    "prettier": "prettier \"src/**/*.js\" \"test/**/*.js\" --write"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/VangBanLaNhat/fca-unofficial"
+  },
+  "keywords": [
+    "facebook",
+    "chat",
+    "api",
+    "fca"
+  ],
+  "bugs": {
+    "url": "https://github.com/VangBanLaNhat/fca-unofficial/issues"
+  },
+  "author": "Avery, David, Maude, Benjamin, UIRI, HerokeyVN",
+  "license": "MIT",
+  "dependencies": {
+    "bluebird": "^2.11.0",
+    "cheerio": "^0.22.0",
+    "https-proxy-agent": "^4.0.0",
+
+    "mqtt": "^3.0.0",
+    "npmlog": "^1.2.1",
+    "request": "^2.88.2",
+    "websocket-stream": "^5.5.2"
+  },
+  "pnpm": {
+    "overrides": {
+      "request@2.88.2>form-data": "2.5.5"
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "devDependencies": {
+    "dotenv": "^16.6.1",
+    "eslint": "^7.32.0",
+    "jest": "^27.5.1",
+    "prettier": "^1.19.1"
+  },
+  "eslintConfig": {
+    "env": {
+      "es6": true,
+      "es2017": true,
+      "node": true
+    },
+    "extends": "eslint:recommended",
+    "parserOptions": {
+      "sourceType": "module"
+    },
+    "rules": {
+      "linebreak-style": [
+        "error",
+        "unix"
+      ],
+      "semi": [
+        "error",
+        "always"
+      ],
+      "no-unused-vars": [
+        1,
+        {
+          "argsIgnorePattern": "^_",
+          "varsIgnorePattern": "^_"
+        }
+      ],
+      "no-empty": [
+        "error",
+        {
+          "allowEmptyCatch": true
+        }
+      ]
+    }
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+onlyBuiltDependencies:
+  - koffi
+  - meta-messenger.js

package/src/actions/addExternalModule.js

@@ -0,0 +1,34 @@
+"use strict";
+
+const utils = require("../utils");
+
+module.exports = function(defaultFuncs, api, ctx) {
+  return function addExternalModule(moduleObj, callback) {
+    var done = typeof callback === "function" ? callback : null;
+
+    if (utils.getType(moduleObj) == "Object") {
+      for (let apiName in moduleObj) {
+        if (
+          utils.getType(moduleObj[apiName]) == "Function" ||
+          utils.getType(moduleObj[apiName]) == "AsyncFunction"
+        ) {
+          api[apiName] = moduleObj[apiName](defaultFuncs, api, ctx);
+        } else {
+          var err = new Error(`Item "${apiName}" in moduleObj must be a function, not ${utils.getType(moduleObj[apiName])}!`);
+          if (done) done(err);
+          throw err;
+        }
+      }
+    } else {
+      var typeErr = new Error(`moduleObj must be an object, not ${utils.getType(moduleObj)}!`);
+      if (done) done(typeErr);
+      throw typeErr;
+    }
+
+    if (done) {
+      done(null, true);
+    }
+
+    return true;
+  };
+};

package/src/actions/addUserToGroup.js

@@ -0,0 +1,113 @@
+"use strict";
+
+var utils = require("../utils");
+var log = require("npmlog");
+
+module.exports = function(defaultFuncs, api, ctx) {
+  return function addUserToGroup(userID, threadID, callback) {
+    var resolveFunc = function(){};
+    var rejectFunc = function(){};
+    var returnPromise = new Promise(function (resolve, reject) {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+
+    if (
+      !callback &&
+      (utils.getType(threadID) === "Function" ||
+        utils.getType(threadID) === "AsyncFunction")
+    ) {
+      throw { error: "please pass a threadID as a second argument." };
+    }
+
+    if (!callback) {
+      callback = function(err) {
+        if (err) {
+          return rejectFunc(err);
+        }
+        resolveFunc();
+      };
+    }
+
+    if (
+      utils.getType(threadID) !== "Number" &&
+      utils.getType(threadID) !== "String"
+    ) {
+      throw {
+        error:
+          "ThreadID should be of type Number or String and not " +
+          utils.getType(threadID) +
+          "."
+      };
+    }
+
+    if (utils.getType(userID) !== "Array") {
+      userID = [userID];
+    }
+
+    var messageAndOTID = utils.generateOfflineThreadingID();
+    var form = {
+      client: "mercury",
+      action_type: "ma-type:log-message",
+      author: "fbid:" + ctx.userID,
+      thread_id: "",
+      timestamp: Date.now(),
+      timestamp_absolute: "Today",
+      timestamp_relative: utils.generateTimestampRelative(),
+      timestamp_time_passed: "0",
+      is_unread: false,
+      is_cleared: false,
+      is_forward: false,
+      is_filtered_content: false,
+      is_filtered_content_bh: false,
+      is_filtered_content_account: false,
+      is_spoof_warning: false,
+      source: "source:chat:web",
+      "source_tags[0]": "source:chat",
+      log_message_type: "log:subscribe",
+      status: "0",
+      offline_threading_id: messageAndOTID,
+      message_id: messageAndOTID,
+      threading_id: utils.generateThreadingID(ctx.clientID),
+      manual_retry_cnt: "0",
+      thread_fbid: threadID
+    };
+
+    for (var i = 0; i < userID.length; i++) {
+      if (
+        utils.getType(userID[i]) !== "Number" &&
+        utils.getType(userID[i]) !== "String"
+      ) {
+        throw {
+          error:
+            "Elements of userID should be of type Number or String and not " +
+            utils.getType(userID[i]) +
+            "."
+        };
+      }
+
+      form["log_message_data[added_participants][" + i + "]"] =
+        "fbid:" + userID[i];
+    }
+
+    defaultFuncs
+      .post("https://www.facebook.com/messaging/send/", ctx.jar, form)
+      .then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+      .then(function(resData) {
+        if (!resData) {
+          throw { error: "Add to group failed." };
+        }
+        if (resData.error) {
+          throw resData;
+        }
+
+        return callback();
+      })
+      .catch(function(err) {
+        log.error("addUserToGroup", err);
+        return callback(err);
+      });
+      
+    return returnPromise;
+  };
+};

package/src/actions/changeAdminStatus.js

@@ -0,0 +1,79 @@
+"use strict";
+
+const utils = require("../utils");
+const log = require("npmlog");
+
+module.exports = function(defaultFuncs, api, ctx) {
+  return function changeAdminStatus(threadID, adminIDs, adminStatus, callback) {
+    if (utils.getType(threadID) !== "String") {
+      throw {error: "changeAdminStatus: threadID must be a string"};
+    }
+
+    if (utils.getType(adminIDs) === "String") {
+      adminIDs = [adminIDs];
+    }
+
+    if (utils.getType(adminIDs) !== "Array") {
+      throw {error: "changeAdminStatus: adminIDs must be an array or string"};
+    }
+
+    if (utils.getType(adminStatus) !== "Boolean") {
+      throw {error: "changeAdminStatus: adminStatus must be a string"};
+    }
+
+    var resolveFunc = function(){};
+    var rejectFunc = function(){};
+    var returnPromise = new Promise(function (resolve, reject) {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+
+    if (!callback) {
+      callback = function (err) {
+        if (err) {
+          return rejectFunc(err);
+        }
+        resolveFunc();
+      };
+    }
+
+    if (utils.getType(callback) !== "Function" && utils.getType(callback) !== "AsyncFunction") {
+      throw {error: "changeAdminStatus: callback is not a function"};
+    }
+
+    let form = {
+      "thread_fbid": threadID,
+    };
+
+    let i = 0;
+    for (let u of adminIDs) {
+      form[`admin_ids[${i++}]`] = u;
+    }
+    form["add"] = adminStatus;
+
+    defaultFuncs
+      .post("https://www.facebook.com/messaging/save_admins/?dpr=1", ctx.jar, form)
+      .then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+      .then(function(resData) {
+        if (resData.error) {
+          switch (resData.error) {
+            case 1976004:
+              throw { error: "Cannot alter admin status: you are not an admin.", rawResponse: resData };
+            case 1357031:
+              throw { error: "Cannot alter admin status: this thread is not a group chat.", rawResponse: resData };
+            default:
+              throw { error: "Cannot alter admin status: unknown error.", rawResponse: resData };
+          }
+        }
+
+        callback();
+      })
+      .catch(function(err) {
+        log.error("changeAdminStatus", err);
+        return callback(err);
+      });
+      
+    return returnPromise;
+  };
+};
+

package/src/actions/changeArchivedStatus.js

@@ -0,0 +1,55 @@
+"use strict";
+
+var utils = require("../utils");
+var log = require("npmlog");
+
+module.exports = function(defaultFuncs, api, ctx) {
+  return function changeArchivedStatus(threadOrThreads, archive, callback) {
+    var resolveFunc = function(){};
+    var rejectFunc = function(){};
+    var returnPromise = new Promise(function (resolve, reject) {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+
+    if (!callback) {
+      callback = function(err) {
+        if (err) {
+          return rejectFunc(err);
+        }
+        resolveFunc();
+      };
+    }
+
+    var form = {};
+
+    if (utils.getType(threadOrThreads) === "Array") {
+      for (var i = 0; i < threadOrThreads.length; i++) {
+        form["ids[" + threadOrThreads[i] + "]"] = archive;
+      }
+    } else {
+      form["ids[" + threadOrThreads + "]"] = archive;
+    }
+
+    defaultFuncs
+      .post(
+        "https://www.facebook.com/ajax/mercury/change_archived_status.php",
+        ctx.jar,
+        form
+      )
+      .then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+      .then(function(resData) {
+        if (resData.error) {
+          throw resData;
+        }
+
+        return callback();
+      })
+      .catch(function(err) {
+        log.error("changeArchivedStatus", err);
+        return callback(err);
+      });
+      
+    return returnPromise;
+  };
+};

package/src/actions/changeBio.js

@@ -0,0 +1,77 @@
+"use strict";
+
+var utils = require("../utils");
+var log = require("npmlog");
+
+module.exports = function (defaultFuncs, api, ctx) {
+  return function changeBio(bio, publish, callback) {
+    var resolveFunc = function () { };
+    var rejectFunc = function () { };
+    var returnPromise = new Promise(function (resolve, reject) {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+
+    if (!callback) {
+      if (utils.getType(publish) == "Function" || utils.getType(publish) == "AsyncFunction") {
+        callback = publish;
+      } else {
+        callback = function (err) {
+          if (err) {
+            return rejectFunc(err);
+          }
+          resolveFunc();
+        };
+      }
+    }
+
+    if (utils.getType(publish) != "Boolean") {
+      publish = false;
+    }
+
+    if (utils.getType(bio) != "String") {
+      bio = "";
+      publish = false;
+    }
+
+    var form = {
+      fb_api_caller_class: "RelayModern",
+      fb_api_req_friendly_name: "ProfileCometSetBioMutation",
+      // This doc_is is valid as of May 23, 2020
+      doc_id: "2725043627607610",
+      variables: JSON.stringify({
+        input: {
+          bio: bio,
+          publish_bio_feed_story: publish,
+          actor_id: ctx.userID,
+          client_mutation_id: Math.round(Math.random() * 1024).toString()
+        },
+        hasProfileTileViewID: false,
+        profileTileViewID: null,
+        scale: 1
+      }),
+      av: ctx.userID
+    };
+
+    defaultFuncs
+      .post(
+        "https://www.facebook.com/api/graphql/",
+        ctx.jar,
+        form
+      )
+      .then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+      .then(function (resData) {
+        if (resData.errors) {
+          throw resData;
+        }
+
+        return callback();
+      })
+      .catch(function (err) {
+        log.error("changeBio", err);
+        return callback(err);
+      });
+
+    return returnPromise;
+  };
+};