nexus-fca 1.0.0

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Nexus-016
+
+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,240 @@
+<div align="center">
+
+<img src="https://i.ibb.co/LzkQMGWz/Future-Studio-Synthwave-Logo-Future-Studio-Synthwave-Logo.png" alt="Nexus-FCA Logo" width="500"/>
+
+
+<h2 align="center"><b>Nexus-FCA: Advanced Facebook Chat API</b></h2>
+
+---
+
+Nexus-FCA is a modern, safe, and advanced Facebook Chat API for Node.js. It is designed for developers who want a reliable, easy-to-use, and actively maintained solution for Messenger automation, bots, and integrations.
+
+---
+
+## Key Features
+
+- **Modern & Safe:**
+  - Built with ES6+ features and TypeScript. No legacy code.
+- **Active Development:**
+  - Regular updates and improvements. Open to contributions.
+- **Easy to Use:**
+  - Simple API with clear documentation. Get started quickly.
+- **No External Dependencies:**
+  - No need for external libraries. Everything is included.
+- **No WebView/Browser Required:**
+  - Directly interacts with Facebook's Messenger API. No browser automation.
+- **No CAPTCHA/Verification:**
+  - Bypass CAPTCHA and verification challenges. Use at your own risk.
+- **No Rate Limits:**
+  - No restrictions on message sending. Use responsibly.
+- **No Account Verification:**
+  - No need to verify your account. Use with caution.
+- **All Major Messenger Features:**
+  - Messaging, reactions, group management, user info, and more.
+- **Safe & Testable:**
+  - No legacy/unsafe code. Test every feature live in Messenger.
+- **Admin & Safety Tools:**
+  - Rate limiting, allow/block lists, Safe Mode.
+- **Easy Login:**
+  - Use `appstate.json` for secure, passwordless login.
+- **Full Documentation:**
+  - Every feature documented in the `docs/` folder with real usage examples.
+
+---
+
+_Disclaimer_: Use responsibly. Nexus-FCA is not affiliated with Facebook. Your account may be at risk if you use this for spam or automation against Facebook's terms.
+
+---
+
+## Install
+
+```bash
+npm install nexus-fca
+```
+
+## Example Usage
+
+```js
+const login = require("nexus-fca");
+
+login({ appState: [] }, (err, api) => {
+    if (err) return console.error(err);
+
+    api.listenMqtt((err, event) => {
+        if (err) return console.error(err);
+        api.sendMessage(event.body, event.threadID);
+    });
+});
+```
+
+Result:
+
+<img width="517" alt="screen shot 2016-11-04 at 14 36 00" src="https://cloud.githubusercontent.com/assets/4534692/20023545/f8c24130-a29d-11e6-9ef7-47568bdbc1f2.png">
+
+## Main Functionality
+
+### Sending a message
+
+#### api.sendMessage(message, threadID[, callback][, messageID])
+
+Various types of message can be sent:
+
+* *Regular:* set field `body` to the desired message as a string.
+* *Sticker:* set a field `sticker` to the desired sticker ID.
+* *File or image:* Set field `attachment` to a readable stream or an array of readable streams.
+* *URL:* set a field `url` to the desired URL.
+* *Emoji:* set field `emoji` to the desired emoji as a string and set field `emojiSize` with size of the emoji (`small`, `medium`, `large`)
+
+Note that a message can only be a regular message (which can be empty) and optionally one of the following: a sticker, an attachment or a url.
+
+__Tip__: to find your own ID, you can look inside the cookies. The `userID` is under the name `c_user`.
+
+__Example (Basic Message)__
+
+```js
+const login = require("nexus-fca");
+
+login({ appState: [] }, (err, api) => {
+    if (err) {
+        console.error("Login Error:", err);
+        return;
+    }
+
+    let yourID = "000000000000000"; // Replace with actual Facebook ID
+    let msg = "Hey!";
+  
+    api.sendMessage(msg, yourID, (err) => {
+        if (err) console.error("Message Sending Error:", err);
+        else console.log("Message sent successfully!");
+    });
+});
+
+```
+
+__Example (File upload)__
+
+```js
+const login = require("nexus-fca");
+const fs = require("fs"); // ✅ Required the fs module
+
+login({ appState: [] }, (err, api) => {
+    if (err) {
+        console.error("Login Error:", err);
+        return;
+    }
+
+    let yourID = "000000000000000"; // Replace with actual Facebook ID
+    let imagePath = __dirname + "/image.jpg";
+
+    // Check if the file exists before sending
+    if (!fs.existsSync(imagePath)) {
+        console.error("Error: Image file not found!");
+        return;
+    }
+
+    let msg = {
+        body: "Hey!",
+        attachment: fs.createReadStream(imagePath)
+    };
+
+    api.sendMessage(msg, yourID, (err) => {
+        if (err) console.error("Message Sending Error:", err);
+        else console.log("Message sent successfully!");
+    });
+});
+
+```
+
+---
+
+### Saving session.
+
+To avoid logging in every time you should save AppState (cookies etc.) to a file, then you can use it without having password in your scripts.
+
+__Example__
+
+```js
+const fs = require("fs");
+const login = require("nexus-fca");
+
+const credentials = { appState: [] };
+
+login(credentials, (err, api) => {
+    if (err) {
+        console.error("Login Error:", err);
+        return;
+    }
+
+    try {
+        const appState = JSON.stringify(api.getAppState(), null, 2); // Pretty print for readability
+        fs.writeFileSync("appstate.json", appState);
+        console.log("✅ AppState saved successfully!");
+    } catch (error) {
+        console.error("Error saving AppState:", error);
+    }
+});
+
+```
+
+---
+
+### Listening to a chat
+
+#### api.listenMqtt(callback)
+
+Listen watches for messages sent in a chat. By default this won't receive events (joining/leaving a chat, title change etc…) but it can be activated with `api.setOptions({listenEvents: true})`. This will by default ignore messages sent by the current account, you can enable listening to your own messages with `api.setOptions({selfListen: true})`.
+
+__Example__
+
+```js
+const fs = require("fs");
+const login = require("nexus-fca");
+
+// Simple echo bot: Repeats everything you say. Stops when you say "/stop".
+login({ appState: JSON.parse(fs.readFileSync("appstate.json", "utf8")) }, (err, api) => {
+    if (err) {
+        console.error("Login Error:", err);
+        return;
+    }
+
+    api.setOptions({ listenEvents: true });
+
+    const stopListening = api.listenMqtt((err, event) => {
+        if (err) {
+            console.error("Listen Error:", err);
+            return;
+        }
+
+        // Mark message as read
+        api.markAsRead(event.threadID, (err) => {
+            if (err) console.error("Mark as read error:", err);
+        });
+
+        // Handle different event types
+        switch (event.type) {
+            case "message":
+                if (event.body && event.body.trim().toLowerCase() === "/stop") {
+                    api.sendMessage("Goodbye…", event.threadID);
+                    stopListening();
+                    return;
+                }
+                api.sendMessage(`TEST BOT: ${event.body}`, event.threadID);
+                break;
+
+            case "event":
+                console.log("Event Received:", event);
+                break;
+        }
+    });
+});
+
+```
+
+---
+
+## Advanced Safety & Admin Features
+
+- **Global Rate Limiting:** Prevents spam and abuse for all sensitive actions (e.g., avatar change, messaging).
+- **Safe Mode:** Set `NEXUS_FCA_SAFE_MODE=1` in your environment to disable risky features (like avatar/group changes) for extra protection.
+- **Allow/Block List:** Control who can use the API with `NEXUS_FCA_ALLOW_LIST` and `NEXUS_FCA_BLOCK_LIST` (comma-separated user IDs).
+- **Health Check:** Use `api.healthCheck((err, status) => { ... })` to verify the bot is running and see current safety status.

package/docs/README.md

@@ -0,0 +1,9 @@
+# Nexus-FCA Documentation Folder
+
+This folder contains individual documentation files for each advanced and core feature of Nexus-FCA. For a full overview, see the main `DOCS.md` or browse the files here for per-feature usage, arguments, and safety notes.
+
+---
+
+- Each `.md` file in this folder documents a single feature/module.
+- You can add your own notes or examples to any file.
+- For the latest and most complete API reference, always check the main `DOCS.md`.

package/docs/addExternalModule.md

@@ -0,0 +1,15 @@
+# addExternalModule
+
+Dynamically add an external module to Nexus-FCA (advanced).
+
+## Usage
+```js
+api.addExternalModule('path/to/module.js', (err) => {
+  if (err) return console.error(err);
+  console.log('Module added!');
+});
+```
+
+## Arguments
+- `modulePath`: Path to the external module (string).
+- `callback(err)`: Callback called when the operation is done (error or null).

package/docs/addUserToGroup.md

@@ -0,0 +1,20 @@
+# addUserToGroup
+
+Add a user or users to a group chat.
+
+## Usage
+```js
+api.addUserToGroup(userID, threadID, (err) => {
+  if (err) return console.error(err);
+  console.log('User(s) added to group!');
+});
+```
+
+## Arguments
+- `userID`: User ID or array of user IDs.
+- `threadID`: Group chat ID (string or number).
+- `callback(err)`: Callback called when the operation is done (error or null).
+
+## Notes
+- `userID` can be a single ID or an array of IDs.
+- Throws an error if `threadID` is not a string or number.

package/docs/changeAdminStatus.md

@@ -0,0 +1,21 @@
+# changeAdminStatus
+
+Set or remove admin status for users in a group chat.
+
+## Usage
+```js
+api.changeAdminStatus(threadID, adminIDs, adminStatus, (err) => {
+  if (err) return console.error(err);
+  console.log('Admin status changed!');
+});
+```
+
+## Arguments
+- `threadID`: Group chat ID (string).
+- `adminIDs`: User ID or array of user IDs to promote/demote.
+- `adminStatus`: Boolean (`true` to promote, `false` to demote).
+- `callback(err)`: Callback called when the operation is done (error or null).
+
+## Notes
+- Throws if arguments are not the correct type.
+- `adminIDs` can be a string or array.

package/docs/changeArchivedStatus.md

@@ -0,0 +1,19 @@
+# changeArchivedStatus
+
+Archive or unarchive one or more threads.
+
+## Usage
+```js
+api.changeArchivedStatus(threadOrThreads, archive, (err) => {
+  if (err) return console.error(err);
+  console.log('Archive status changed!');
+});
+```
+
+## Arguments
+- `threadOrThreads`: Thread ID or array of thread IDs.
+- `archive`: Boolean (`true` to archive, `false` to unarchive).
+- `callback(err)`: Callback called when the operation is done (error or null).
+
+## Notes
+- Accepts a single thread ID or an array.

package/docs/changeAvatar.md

@@ -0,0 +1,21 @@
+# changeAvatar
+
+Change your Facebook profile avatar (profile picture).
+
+## Usage
+```js
+api.changeAvatar(fs.createReadStream('./avatar.jpg'), 'My new avatar!', null, (err, res) => {
+  if (err) return console.error(err);
+  console.log('Avatar changed!', res);
+});
+```
+
+## Arguments
+- `image`: File stream of the image.
+- `caption`: (Optional) Caption for the image (string).
+- `timestamp`: (Optional) Timestamp for the change (null for now).
+- `callback(err, res)`: Callback with error or result.
+
+## Notes
+- Use a readable stream for the image file.
+- You can add a caption or leave it blank.

package/docs/changeAvatarV2.md

@@ -0,0 +1,18 @@
+# changeAvatarV2
+
+Change your Facebook profile avatar using a local image file.
+
+## Usage
+```js
+api.changeAvatarV2('./avatar.jpg', (err, res) => {
+  if (err) return console.error(err);
+  console.log('Avatar changed!', res);
+});
+```
+
+## Arguments
+- `imagePath`: Path to the image file (string).
+- `callback(err, res)`: Callback with error or result.
+
+## Safety Note
+Use images that comply with Facebook's community standards.

package/docs/changeBio.md

@@ -0,0 +1,15 @@
+# changeBio
+
+Change your Facebook profile bio.
+
+## Usage
+```js
+api.changeBio('This is my new bio!', (err, res) => {
+  if (err) return console.error(err);
+  console.log('Bio changed!', res);
+});
+```
+
+## Arguments
+- `bio`: New bio text (string).
+- `callback(err, res)`: Callback with error or result.

package/docs/changeBlockedStatus.md

@@ -0,0 +1,16 @@
+# changeBlockedStatus
+
+Block or unblock a user (basic method).
+
+## Usage
+```js
+api.changeBlockedStatus('1000123456789', true, (err) => {
+  if (err) return console.error(err);
+  console.log('User blocked!');
+});
+```
+
+## Arguments
+- `userID`: The user ID (string).
+- `block`: Boolean to block (true) or unblock (false).
+- `callback(err)`: Callback called when the operation is done (error or null).

package/docs/changeBlockedStatusMqtt.md

@@ -0,0 +1,16 @@
+# changeBlockedStatusMqtt
+
+Block or unblock a user using the MQTT protocol.
+
+## Usage
+```js
+api.changeBlockedStatusMqtt('1000123456789', true, (err, res) => {
+  if (err) return console.error(err);
+  console.log('User blocked!', res);
+});
+```
+
+## Arguments
+- `userID`: The user ID (string).
+- `block`: Boolean to block (true) or unblock (false).
+- `callback(err, res)`: Callback with error or result.

package/docs/changeCover.md

@@ -0,0 +1,15 @@
+# changeCover
+
+Change your Facebook cover photo.
+
+## Usage
+```js
+api.changeCover('./cover.jpg', (err, res) => {
+  if (err) return console.error(err);
+  console.log('Cover photo changed!', res);
+});
+```
+
+## Arguments
+- `imagePath`: Path to the image file (string).
+- `callback(err, res)`: Callback with error or result.

package/docs/changeGroupImage.md

@@ -0,0 +1,16 @@
+# changeGroupImage
+
+Change the group chat's image.
+
+## Usage
+```js
+api.changeGroupImage(fs.createReadStream('./group.jpg'), '1234567890', (err) => {
+  if (err) return console.error(err);
+  console.log('Group image changed!');
+});
+```
+
+## Arguments
+- `image`: File stream of the image.
+- `threadID`: Group chat ID (string).
+- `callback(err)`: Callback called when the operation is done (error or null).

package/docs/changeName.md

@@ -0,0 +1,18 @@
+# changeName
+
+Change your Facebook profile name.
+
+## Usage
+```js
+api.changeName('New Name', (err, res) => {
+  if (err) return console.error(err);
+  console.log('Name changed!', res);
+});
+```
+
+## Arguments
+- `newName`: New name (string).
+- `callback(err, res)`: Callback with error or result.
+
+## Safety Note
+Changing your name too frequently may result in Facebook restrictions.

package/docs/changeNickname.md

@@ -0,0 +1,17 @@
+# changeNickname
+
+Change a user's nickname in a thread.
+
+## Usage
+```js
+api.changeNickname('Cool Guy', '1234567890', '1000123456789', (err) => {
+  if (err) return console.error(err);
+  console.log('Nickname changed!');
+});
+```
+
+## Arguments
+- `nickname`: New nickname (string).
+- `threadID`: Thread ID (string).
+- `participantID`: User ID (string).
+- `callback(err)`: Callback called when the operation is done (error or null).

package/docs/changeThreadColor.md

@@ -0,0 +1,16 @@
+# changeThreadColor
+
+Change the thread color.
+
+## Usage
+```js
+api.changeThreadColor('#0000ff', '1234567890', (err) => {
+  if (err) return console.error(err);
+  console.log('Thread color changed!');
+});
+```
+
+## Arguments
+- `color`: Color hex string (e.g. '#0000ff').
+- `threadID`: Thread ID (string).
+- `callback(err)`: Callback called when the operation is done (error or null).

package/docs/changeThreadEmoji.md

@@ -0,0 +1,16 @@
+# changeThreadEmoji
+
+Change the thread emoji.
+
+## Usage
+```js
+api.changeThreadEmoji('😎', '1234567890', (err) => {
+  if (err) return console.error(err);
+  console.log('Thread emoji changed!');
+});
+```
+
+## Arguments
+- `emoji`: Emoji character (string).
+- `threadID`: Thread ID (string).
+- `callback(err)`: Callback called when the operation is done (error or null).

package/docs/changeUsername.md

@@ -0,0 +1,15 @@
+# changeUsername
+
+Change your Facebook username.
+
+## Usage
+```js
+api.changeUsername('newusername', (err, res) => {
+  if (err) return console.error(err);
+  console.log('Username changed!', res);
+});
+```
+
+## Arguments
+- `username`: New username (string).
+- `callback(err, res)`: Callback with error or result.

package/docs/createCommentPost.md

@@ -0,0 +1,16 @@
+# createCommentPost
+
+Comment on a Facebook post.
+
+## Usage
+```js
+api.createCommentPost('1234567890', 'Nice post!', (err, res) => {
+  if (err) return console.error(err);
+  console.log('Comment posted!', res);
+});
+```
+
+## Arguments
+- `postID`: The post ID (string).
+- `comment`: Comment text (string).
+- `callback(err, res)`: Callback with error or result.

package/docs/createNewGroup.md

@@ -0,0 +1,16 @@
+# createNewGroup
+
+Create a new group chat.
+
+## Usage
+```js
+api.createNewGroup(['10001','10002'], 'My Group', (err, threadID) => {
+  if (err) return console.error(err);
+  console.log('Group created! ID:', threadID);
+});
+```
+
+## Arguments
+- `participantIDs`: Array of user IDs.
+- `groupTitle`: (Optional) Group name (string).
+- `callback(err, threadID)`: Callback with error or new thread ID.

package/docs/createPoll.md

@@ -0,0 +1,17 @@
+# createPoll
+
+Create a poll in a thread.
+
+## Usage
+```js
+api.createPoll('Favorite color?', '1234567890', { Red: false, Blue: true }, (err) => {
+  if (err) return console.error(err);
+  console.log('Poll created!');
+});
+```
+
+## Arguments
+- `title`: Poll title (string).
+- `threadID`: Thread ID (string).
+- `options`: Object of poll options (e.g. `{ Red: false, Blue: true }`).
+- `callback(err)`: Callback called when the operation is done (error or null).

package/docs/createPost.md

@@ -0,0 +1,15 @@
+# createPost
+
+Create a new Facebook post.
+
+## Usage
+```js
+api.createPost('Hello, world!', (err, res) => {
+  if (err) return console.error(err);
+  console.log('Post created!', res);
+});
+```
+
+## Arguments
+- `content`: Post content (string).
+- `callback(err, res)`: Callback with error or result.

package/docs/deleteMessage.md

@@ -0,0 +1,15 @@
+# deleteMessage
+
+Delete one or more messages by ID.
+
+## Usage
+```js
+api.deleteMessage('mid.$cAA...', (err) => {
+  if (err) return console.error(err);
+  console.log('Message deleted!');
+});
+```
+
+## Arguments
+- `messageOrMessages`: Message ID or array of message IDs.
+- `callback(err)`: Callback called when the operation is done (error or null).

package/docs/deleteThread.md

@@ -0,0 +1,15 @@
+# deleteThread
+
+Delete one or more threads by ID.
+
+## Usage
+```js
+api.deleteThread('1234567890', (err) => {
+  if (err) return console.error(err);
+  console.log('Thread deleted!');
+});
+```
+
+## Arguments
+- `threadOrThreads`: Thread ID or array of thread IDs.
+- `callback(err)`: Callback called when the operation is done (error or null).