autobot-fca

Unofficial Facebook Chat API for Node.js (v1.0.0)
A fast, reliable, fully typed and modular Facebook Chat API library supporting modern TypeScript/ESM imports and full backwards compatibility with classic CommonJS and Mirai bot frameworks.

🚀 Feature

• ⚡ Dual Module Support: Seamlessly works with import (ESM) and require() (CommonJS / Mirai bots).
• 🛡️ Full TypeScript Support: Complete type definitions, Intellisense, and payload validation.
• 💬 Comprehensive Message Controls: Send, reply, edit, unsend, delete, forward attachments, send typing indicators, and emoji reactions.
• 👥 Rich Group & User Management: Set thread titles, change colors/emojis, manage nicknames, add/remove group members, grant admin privileges, create polls, block/unblock users.
• 🍪 Universal Cookie & AppState Support: Built-in parsers for standard headers, JSON AppState, and Netscape curl formats (cookieToAppState, appStateToCookie, toNetscapeCookieText).
• 🤖 Bot Handler Registries: Integrated api.handleReply, api.handleReaction, and api.handleSchedule maps for conversational state management.
• 🔄 Real-Time MQTT & Middleware: Built-in MQTT event listener with custom middleware interception pipelines.
• ⚙️ Configurable: Automatically resolves configurations from fca-config.json.

📦 Installation

npm install autobot-fca

Or using yarn / pnpm / bun:

yarn add autobot-fca
# or
pnpm add autobot-fca
# or
bun add autobot-fca

💡 Quick Start

1. Modern TypeScript / ESM

import { login, cookieToAppState } from "autobot-fca";

// Login with raw cookie string or JSON appState
const { api, userID } = await login({
  Cookie: "c_user=100088921827162; xs=...; fr=...;"
});

console.log("Logged in as user:", userID);

// Send message
const msg = await api.sendMessage("Hello from autobot-fca! 🚀", "100010001000101");

// React to a message
await api.setMessageReaction("❤️", msg.messageID);

// Edit message
await api.editMessage("Updated message content ✨", msg.messageID);

// Listen to incoming messages via MQTT
const stopListening = api.listenMqtt((err, event) => {
  if (err) return console.error("MQTT Error:", err);
  if (event.type === "message") {
    console.log(`[${event.senderID}]: ${event.body}`);
  }
});

2. Classic CommonJS / Mirai Bot Framework

const login = require("autobot-fca");
const fs = require("fs");

const appState = JSON.parse(fs.readFileSync("appstate.json", "utf8"));

login({ appState }, (err, api) => {
  if (err) return console.error("Login failed:", err);

  api.setOptions({ listenEvents: true, selfListen: false });

  api.listenMqtt((err, event) => {
    if (err) return console.error(err);

    if (event.body === "ping") {
      api.sendMessage("pong! 🏓", event.threadID);
    }
  });
});

🛠️ API Reference

📨 Messages & Interactions

| Method | Description | |---|---| | api.sendMessage(msg, threadID, callback) | Send text or attachment message | | api.editMessage(text, messageID, callback) | Edit an already sent message | | api.replyMessage(msg, messageID, callback) | Reply directly to a specific message | | api.unsendMessage(messageID, callback) | Unsend / recall a message | | api.setMessageReaction(reaction, messageID, callback) | React to message with emoji (e.g. ❤️, 👍, 😆) | | api.sendTypingIndicator(threadID, callback) | Send typing indicator dots | | api.deleteMessage(messageIDs, callback) | Delete message(s) from history | | api.forwardAttachment(attachmentID, threadID, callback) | Forward an attachment to another thread |

👥 Threads & Group Management

| Method | Description | |---|---| | api.getThreadInfo(threadID, callback) | Get group/chat metadata | | api.getThreadList(limit, timestamp, tags, callback) | List recent conversations | | api.getThreadHistory(threadID, amount, timestamp, callback) | Fetch message history | | api.setTitle(newTitle, threadID, callback) | Change chat title | | api.changeThreadColor(color, threadID, callback) | Change chat theme color | | api.changeThreadEmoji(emoji, threadID, callback) | Change chat quick emoji | | api.changeNickname(nickname, threadID, participantID, callback) | Set or reset member nickname | | api.changeAdminStatus(threadID, adminIDs, status, callback) | Promote / demote group admins | | api.addUserToGroup(userIDs, threadID, callback) | Add members to group | | api.removeUserFromGroup(userID, threadID, callback) | Remove member from group | | api.createPoll(title, options, threadID, callback) | Create group poll | | api.deleteThread(threadID, callback) | Delete conversation thread | | api.markAsRead(threadID, callback) | Mark thread as read |

👤 User & Profile Utilities

| Method | Description | |---|---| | api.getUserInfo(userIDs, callback) | Retrieve user profile metadata | | api.getUserID(name, callback) | Search user ID by name | | api.getFriendsList(callback) | Get user's Facebook friends list | | api.blockUser(userID, callback) | Block a user | | api.unblockUser(userID, callback) | Unblock a user | | api.setBio(bio, callback) | Update account biography |

🍪 Cookie & AppState Converters

import {
  cookieToAppState,
  appStateToCookie,
  toNetscapeCookieText,
  parseCookieHeaderString,
  normalizeCookiePayload
} from "autobot-fca";

// Convert raw header string to JSON AppState
const appState = cookieToAppState("c_user=100088921827162; xs=2:abcdef;");

// Convert AppState back to Cookie string
const cookieString = appStateToCookie(appState);

// Export to Netscape format for curl / external tools
const netscapeText = toNetscapeCookieText(appState);

⚙️ Configuration (fca-config.json)

You can customize runtime behavior by placing an fca-config.json file in your project root:

{
  "autoUpdate": true,
  "checkUpdate": {
    "enabled": true,
    "packageName": "autobot-fca"
  },
  "mqtt": {
    "enabled": true,
    "reconnectInterval": 3600
  },
  "antiGetInfo": {
    "AntiGetThreadInfo": false,
    "AntiGetUserInfo": false
  }
}

🚢 Publishing to npm

To publish this package to npm under your account:

1. Login to npm in your terminal:

   npm login

2. Build and test the project:

   npm run build
   npm test

3. Publish to npm:

   npm publish --access public

📄 License

Licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Developed & Maintained by Aminul Sardar.