alpha-fca v1.0.0

Ultimate Facebook Chat API — Stable Inbox · E2EE Bridge · E2EE Group · Low Automation · Session Recovery

Merged and optimized from 6 FCA sources:

• fca-unofficial-4_0_3 (primary base — best MQTT core)
• Hridoy_Fca_by_akash (E2EE store, socket structure)
• fca-hridoy-custom-v1_0_3 (session/reconnect patterns)
• ST-FCA-main (API coverage)
• fca-azadx69x-main (notification, extra APIs)
• mahmud-fca-main (typing, session patterns)

Features

| Feature | Status | |---|---| | ✅ Normal Inbox (MQTT) | Stable | | ✅ Messenger Inbox | Working | | ✅ E2EE Bridge (key mgmt) | Working | | ✅ E2EE Group support | Working | | ✅ Auto-reconnect | Working | | ✅ Session recovery | Working | | ✅ Low automation (no polling) | Working | | ✅ Memory leak prevention | Working | | ✅ Message reactions | Working | | ✅ Typing indicator | Working | | ✅ Reply/mention | Working | | ✅ Attachments | Working | | ✅ Event handling | Working |

Requirements

• Node.js >= 15.0.0 (required for crypto.hkdfSync and X25519)
• A valid Facebook appState (cookies)

Installation

# 1. Extract the ZIP
unzip alpha-fca-v1.0.0.zip
cd alpha-fca

# 2. Install dependencies
npm install

# 3. Add your appState
# Create appstate.json with your Facebook session cookies
# (use an FCA appState extractor tool)

Quick Start

const login = require("alpha-fca");
const appState = require("./appstate.json");

login({ appState }, { listenEvents: true, autoReconnect: true }, (err, api) => {
  if (err) return console.error(err);

  console.log("Logged in:", api.getCurrentUserID());

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

    if (event.type === "message") {
      console.log(`${event.senderID}: ${event.body}`);
      api.sendMessage("Got it!", event.threadID);
    }
  });
});

E2EE Bridge Usage

login({ appState }, options, async (err, api) => {
  if (err) return console.error(err);

  // 1. Connect E2EE bridge (generates/loads key material)
  const e2ee = await api.connectE2EE({
    storePath: "./.alpha-fca-e2ee"  // where keys are stored
  });

  console.log("My public bundle:", e2ee.getPublicBundle());

  // 2. Listen — receives both normal + E2EE messages
  api.listenE2EE((err, event) => {
    if (err) return;
    if (event.isE2EE) console.log("[E2EE]", event.body);
    else console.log("[inbox]", event.body);
  });

  // 3. Establish E2EE session with peer (needs their public bundle)
  // const session = await e2ee.establishSession(threadID, peerPublicBundle);

  // 4. Encrypt a message manually
  // const encrypted = e2ee.encryptMessage(threadID, "secret message");

  // 5. List active E2EE sessions
  console.log("Sessions:", e2ee.listSessions());
});

E2EE Group Support

E2EE Group messages are received via the same listenE2EE callback. Events from E2EE sources carry event.isE2EE = true.

api.listenE2EE((err, event) => {
  if (event.type === "message" && event.isE2EE) {
    // E2EE group or bridge message
    api.sendMessage("Reply to E2EE", event.threadID);
  }
});

API Reference

login(loginData, options, callback)

| Field | Type | Description | |---|---|---| | loginData.appState | Array | Facebook cookies array | | loginData.Cookie | string | Cookie string (alternative) | | options | object | See options below | | callback | function(err, api) | Called on login |

Options

{
  selfListen: false,      // receive own messages
  listenEvents: true,     // group/thread events
  listenTyping: false,    // typing notifications (low automation: keep false)
  updatePresence: false,  // presence updates (low automation: keep false)
  autoReconnect: true,    // auto-reconnect on disconnect
  autoMarkRead: false,    // auto mark as read (low automation: keep false)
  online: true,           // appear online
  emitReady: false        // emit "ready" event on connect
}

API Methods

api.listen(callback)              // Normal Inbox listener
api.listenE2EE(callback)          // Inbox + E2EE combined listener
api.connectE2EE(options)          // Initialize E2EE bridge (async)

api.sendMessage(msg, threadID, callback, replyToMessage)
api.markAsRead(threadID, callback)
api.sendTypingIndicator(threadID, callback)  // returns stop function
api.setMessageReaction(reaction, messageID, callback)
api.unsendMessage(messageID, callback)

api.getUserInfo(ids, callback)
api.getThreadInfo(threadID, callback)

api.getCurrentUserID()            // returns string userID
api.getAppState()                 // returns current cookies (async)
api.setOptions(options)           // update options at runtime
api.logout(callback)

api.stopListening(callback)       // stop MQTT listener
api.stopListeningAsync()          // async version

sendMessage formats

// Text
api.sendMessage("Hello!", threadID);

// Reply
api.sendMessage("Replying!", threadID, callback, originalMessageID);

// With mentions
api.sendMessage({
  body: "Hey @User!",
  mentions: [{ id: "123456", tag: "@User" }]
}, threadID);

// Emoji
api.sendMessage({ emoji: "❤️", emojiSize: "large" }, threadID);

// Sticker
api.sendMessage({ sticker: "369239263222822" }, threadID);

// Attachment (stream)
const fs = require("fs");
api.sendMessage({
  body: "Here's a file",
  attachment: fs.createReadStream("./image.jpg")
}, threadID);

Event Types

{ type: "message", senderID, threadID, body, messageID, attachments, mentions, timestamp, isGroup }
{ type: "message_reply", ...same + repliedTo: { messageID, senderID, body } }
{ type: "message_reaction", threadID, messageID, reaction, senderID, userID }
{ type: "message_unsend", threadID, messageID, senderID }
{ type: "message_edit", threadID, messageID, senderID, body }
{ type: "event", threadID, logMessageType, logMessageData, author }
{ type: "typ", from, threadID, isTyping }
{ type: "read_receipt", threadID, reader, time }
{ type: "presence", userID, timestamp, statuses }
{ type: "friend_request_received", actorFbId }
{ type: "friend_request_cancel", actorFbId }
{ type: "account_inactive", reason, error }  // session expired
{ type: "ready" }  // MQTT connected (if emitReady: true)

Session / Reconnect

alpha-fca automatically:

• Reconnects on MQTT disconnect (configurable delay, default 2s)
• Cycles MQTT connection every 1 hour (prevents stale connections)
• Retries getSeqID up to 3 times on auth error before giving up
• Cleans up all timers, intervals, and listeners on stop/disconnect
• Prevents memory leaks via proper listener/task cleanup

On account_inactive event: save a new appState and restart.

E2EE Key Storage

Keys are stored in .alpha-fca-e2ee/alpha_e2ee_{userID}.json, encrypted with a per-device AES-256-GCM key. Do not commit this directory to version control.

.alpha-fca-e2ee/
  alpha_e2ee_100012345678.json   ← encrypted key material

Limitations

• Email/password login not supported — appState required.
• Facebook E2EE (Signal-based) messages are decrypted by Facebook before MQTT delivery and appear as normal messages. The E2EE bridge here provides developer-controlled encryption for custom implementations.
• Some features (file upload, photo URL resolve) may need session refresh if cookies expire.
• Node.js >= 15.0.0 required for X25519 crypto.

Run Tests

npm test

License

Apache-2.0