mini-fca 0.1.0

package/.github/workflows/main.yml

@@ -0,0 +1,28 @@
+name: Publish npm
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Publish to NPM
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,125 @@
+# mini-fca
+
+Minimal unofficial Facebook Messenger chat API for Node.js. Reverse-engineered
+from Facebook's web client (ajax endpoints + MQTT over WebSocket) — this is
+**not** Meta's official API, and it *will* break when Facebook changes internal
+endpoints, GraphQL `doc_id` values, or page markup. Untested against a live
+account; treat as a starting skeleton, not a finished product.
+
+## Install
+
+```bash
+npm install
+```
+
+Requires Node 18+ (uses global `fetch`, `FormData`, `Blob`).
+
+## Setup
+
+1. Log into Facebook in a browser with the account you'll automate — **use a
+   throwaway/test account**, not your main one.
+2. Export cookies as AppState JSON, e.g. with the `c3c-fbstate` browser
+   extension. Save it as `appstate.json` next to `example.js`.
+3. `node example.js`
+
+## API
+
+```js
+const login = require("./index");
+
+login({ appState, options: { /* see below */ } }, (err, api) => {
+  // or: const api = await login({ appState });
+});
+```
+
+### Options
+
+| key | default | meaning |
+|---|---|---|
+| `selfListen` | `false` | also emit events for messages you send |
+| `listenEvents` | `true` | emit group/thread events, not just messages |
+| `sendDelayMs` | `1200` | minimum gap between outgoing sends (throttling) |
+| `autoReconnect` | `true` | reconnect MQTT with backoff on drop |
+| `maxRetries` | `20` | give up after this many reconnect attempts |
+
+### Methods
+
+- `api.sendMessage(body | {body, attachment, sticker, mentions, replyTo}, threadID, {isGroup})`
+- `api.unsendMessage(messageID)`
+- `api.setMessageReaction(emoji, messageID)` — pass `""` to remove
+- `api.markAsRead(threadID, read=true)`
+- `api.sendTypingIndicator(threadID, isTyping, isGroup)`
+- `api.uploadAttachment(path | Buffer | {buffer, filename, contentType} | stream)`
+- `api.getUserInfo(userID)`
+- `api.getFriendsList()`
+- `api.getThreadInfo(threadID)`
+- `api.getThreadList(limit, offset)`
+- `api.getThreadHistory(threadID, amount, beforeTimestamp, isGroup)`
+- `api.changeNickname(nickname, threadID, participantID)`
+- `api.setTitle(newTitle, threadID)`
+- `api.addUserToGroup(userIDs, threadID)`
+- `api.removeUserFromGroup(userID, threadID)`
+- `api.createGroup(userIDs, title?)` — needs ≥2 other participants, returns new `threadID`
+- `api.changeAdminStatus(threadID, userID, makeAdmin=true)`
+- `api.changeThreadColor(threadID, hexColor)`
+- `api.changeThreadEmoji(threadID, emoji)`
+- `api.muteThread(threadID, muteSeconds)` — `-1` mute indefinitely, `0` unmute
+- `api.pinMessage(threadID, messageID, pinned=true)`
+- `api.createPoll(threadID, question, options[], multiSelect=false)` → returns `pollID`
+- `api.voteInPoll(pollID, optionIDs[])`
+- `api.blockUser(userID)` / `api.unblockUser(userID)`
+- `api.searchThreads(query, limit)` — find people/groups/pages by name
+- `api.searchMessages(threadID, query, limit)` — search within one thread's history
+- `api.uploadLargeAttachment(file, {chunkSizeBytes})` — chunked upload for large video/files, falls back to `uploadAttachment` under the chunk size
+- `api.listen(callback)` / `api.listenMqtt(callback)` — returns a `stop()` function
+- `api.getAppState()` — export refreshed cookies to persist between runs
+- `api.setOptions(partial)`, `api.refreshTokens()`
+
+### Listen events
+
+`callback(err, event)` where `event.type` is one of:
+
+- `"message"` — `{threadID, senderID, messageID, body, isGroup, attachments, reply()}`
+- `"event"` — `logMessageType` of `log:subscribe` / `log:unsubscribe` / `log:thread-name`
+- `"message_reaction"` — `{threadID, messageID, userID, reaction, action}`
+- `"message_unsend"` — `{threadID, messageID, senderID}`
+- `"read_receipt"` — `{threadID, readerID, time}`
+- `"typ"` — typing indicator
+- `"system"` — connection state (`connected`, `reconnecting`)
+
+## Known weak points
+
+- `src/listen.js` `fetchSeqID()` calls a GraphQL `doc_id` that Facebook rotates
+  periodically. If `listen()` fails immediately, this is the first suspect —
+  capture the endpoint again from browser devtools and swap the id.
+- `pinMessage()` and `setMessageReaction()` also call `webgraphql/mutation/`
+  with hardcoded `doc_id`s — same rotation risk as above.
+- Legacy `ajax/mercury/*` endpoints (`thread_info.php`, `threadlist_info.php`,
+  `search_snippets.php`) may return partial data or be deprecated outright.
+- `searchMessages()`'s response shape is the least certain endpoint in this
+  library — Facebook has changed its message-search backend multiple times;
+  treat the return value as "probably an array of snippet objects" and log
+  the raw response the first time you call it.
+- `uploadLargeAttachment()`'s resumable-upload endpoints
+  (`upload_resumable_start/chunk/finish.php`) are named by analogy with how
+  Facebook's own resumable upload flow works elsewhere; they have not been
+  confirmed against Messenger's current upload pipeline. For anything under
+  ~25MB, prefer plain `uploadAttachment()`.
+- `createGroup()` requires at least 2 other participants (Facebook's own
+  restriction) — passing 1 will silently produce a 1-to-1 thread, not a
+  group, and the returned `threadID` won't behave like a group thread.
+- No captcha/checkpoint handling — if Facebook interrupts login with a
+  checkpoint, `refreshTokens()` will throw and you resolve it manually in a
+  browser, then re-export AppState.
+- Not implemented at all: voice/video calls (needs a full WebRTC signaling +
+  media stack, out of scope for an HTTP/MQTT client), Stories, vanish mode.
+
+## Risk notes
+
+- Automating a personal account this way violates Facebook's Terms of
+  Service; the account can be checkpointed or banned regardless of how
+  careful the code is.
+- `appstate.json` is equivalent to your login session — never commit it or
+  share it.
+- For anything long-running or Page-based, Meta's official Messenger
+  Platform API is the stable, ToS-compliant alternative.

package/index.js

@@ -0,0 +1,97 @@
+"use strict";
+
+const crypto = require("crypto");
+const Http = require("./src/http");
+const { buildApi } = require("./src/api");
+
+const DEFAULT_OPTIONS = {
+  selfListen: false, // নিজের পাঠানো message-এও event পাবে কিনা
+  listenEvents: true, // group join/leave, reaction, typing ইত্যাদি event
+  sendDelayMs: 1200, // দুটি message-এর মাঝে ন্যূনতম বিরতি (ban ঝুঁকি কমায়)
+  autoReconnect: true,
+  maxRetries: 20,
+};
+
+function computeJazoest(dtsg) {
+  let sum = 0;
+  for (let i = 0; i < dtsg.length; i++) sum += dtsg.charCodeAt(i);
+  return "2" + sum;
+}
+
+function parseHome(html) {
+  const dtsg = (
+    html.match(/"DTSGInitialData",\[\],\{"token":"([^"]+)"/) ||
+    html.match(/name="fb_dtsg" value="([^"]+)"/) ||
+    html.match(/"dtsg":\{"token":"([^"]+)"/) ||
+    []
+  )[1];
+  if (!dtsg) {
+    throw new Error(
+      "fb_dtsg not found: AppState expired, checkpoint required, or Facebook changed its page layout"
+    );
+  }
+  const jazoest = (html.match(/name="jazoest" value="(\d+)"/) || [])[1] || computeJazoest(dtsg);
+  const region = ((html.match(/"region":"([a-z]{3})"/i) || [])[1] || "prn").toLowerCase();
+  return { dtsg, jazoest, region };
+}
+
+async function doLogin(credentials) {
+  if (!credentials || !Array.isArray(credentials.appState)) {
+    throw new Error("appState (array of cookies) is required");
+  }
+
+  const http = new Http(credentials.appState);
+  const userID = http.jar.get("c_user");
+  if (!userID) throw new Error("c_user cookie missing: AppState is invalid or expired");
+
+  const ctx = {
+    http,
+    userID,
+    fbDtsg: "",
+    jazoest: "",
+    region: "prn",
+    clientID: crypto.randomBytes(4).toString("hex"),
+    req: 0,
+    lastSeqId: null,
+    syncToken: null,
+    options: { ...DEFAULT_OPTIONS, ...(credentials.options || {}) },
+
+    // Common form fields Facebook expects on ajax calls
+    form(extra = {}) {
+      ctx.req += 1;
+      return {
+        __user: userID,
+        __a: "1",
+        __req: ctx.req.toString(36),
+        __rev: "1000000000",
+        fb_dtsg: ctx.fbDtsg,
+        jazoest: ctx.jazoest,
+        ...extra,
+      };
+    },
+
+    // Re-scrape tokens (used on reconnect / after session hiccups)
+    async refreshTokens() {
+      const html = await http.getText("https://www.facebook.com/");
+      const t = parseHome(html);
+      ctx.fbDtsg = t.dtsg;
+      ctx.jazoest = t.jazoest;
+      ctx.region = t.region;
+    },
+  };
+
+  await ctx.refreshTokens();
+  return buildApi(ctx);
+}
+
+// Works both with callback and with promises
+function login(credentials, callback) {
+  const p = doLogin(credentials);
+  if (typeof callback === "function") {
+    p.then((api) => callback(null, api)).catch((err) => callback(err));
+    return;
+  }
+  return p;
+}
+
+module.exports = login;

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "mini-fca",
+  "version": "0.1.0",
+  "description": "Minimal unofficial Facebook Messenger chat API for Node.js (experimental, untested)",
+  "main": "index.js",
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "mqtt": "^4.3.8"
+  }
+}

package/src/api.js

@@ -0,0 +1,480 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { createListener } = require("./listen");
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const MIME = {
+  ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".gif": "image/gif",
+  ".webp": "image/webp", ".mp4": "video/mp4", ".mov": "video/quicktime", ".mp3": "audio/mpeg",
+  ".m4a": "audio/mp4", ".ogg": "audio/ogg", ".wav": "audio/wav", ".pdf": "application/pdf",
+  ".txt": "text/plain", ".zip": "application/zip",
+};
+
+// Offline threading ID: timestamp bits + 22 random bits, as a decimal string
+function genOfflineThreadingID() {
+  const now = Date.now();
+  const rand = Math.floor(Math.random() * 4294967295);
+  const bits = ("0000000000000000000000" + rand.toString(2)).slice(-22);
+  return BigInt("0b" + now.toString(2) + bits).toString();
+}
+
+async function streamToBuffer(stream) {
+  const chunks = [];
+  for await (const c of stream) chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+  return Buffer.concat(chunks);
+}
+
+// Accepts: file path | Buffer | { buffer, filename, contentType } | readable stream
+async function toFile(att) {
+  let buffer, filename = "file", ext = "";
+  if (typeof att === "string") {
+    buffer = await fs.promises.readFile(att);
+    filename = path.basename(att);
+  } else if (Buffer.isBuffer(att)) {
+    buffer = att;
+  } else if (att && att.buffer) {
+    buffer = att.buffer;
+    filename = att.filename || filename;
+  } else if (att && typeof att.pipe === "function") {
+    buffer = await streamToBuffer(att);
+    if (att.path) filename = path.basename(String(att.path));
+  } else {
+    throw new Error("Unsupported attachment type");
+  }
+  ext = path.extname(filename).toLowerCase();
+  const contentType = (att && att.contentType) || MIME[ext] || "application/octet-stream";
+  return { buffer, filename, contentType };
+}
+
+function buildApi(ctx) {
+  const api = {};
+
+  // ---------- internal helpers ----------
+  const call = async (url, extra = {}) => {
+    const res = await ctx.http.postJson(url, ctx.form(extra));
+    if (res.error) {
+      const e = new Error(
+        `${url.split("/").slice(-2).join("/")} failed: ${res.errorDescription || res.errorSummary || res.error}`
+      );
+      e.code = res.error;
+      e.response = res;
+      throw e;
+    }
+    return res;
+  };
+
+  // Serialize sends with a minimum delay to reduce spam detection
+  let chain = Promise.resolve();
+  const enqueue = (fn) => {
+    const run = chain.then(fn);
+    chain = run.catch(() => {}).then(() => sleep(ctx.options.sendDelayMs));
+    return run;
+  };
+
+  const messageBase = () => {
+    const otid = genOfflineThreadingID();
+    return {
+      otid,
+      fields: {
+        client: "mercury",
+        action_type: "ma-type:user-generated-message",
+        author: "fbid:" + ctx.userID,
+        timestamp: Date.now(),
+        source: "source:chat:web",
+        "source_tags[0]": "source:chat",
+        html_body: false,
+        ui_push_phase: "V3",
+        status: "0",
+        offline_threading_id: otid,
+        message_id: otid,
+        threading_id: `<${Date.now()}:${Math.floor(Math.random() * 4294967295)}-${ctx.clientID}@mail.projektitan.com>`,
+        "ephemeral_ttl_mode:": "0",
+        manual_retry_cnt: "0",
+        has_attachment: false,
+        signatureID: Math.floor(Math.random() * 2147483648).toString(16),
+      },
+    };
+  };
+
+  const SEND_URL = "https://www.facebook.com/messaging/send/";
+
+  // ---------- session ----------
+  api.getCurrentUserID = () => ctx.userID;
+  api.getAppState = () => ctx.http.exportAppState();
+  api.setOptions = (opts) => Object.assign(ctx.options, opts);
+  api.refreshTokens = () => ctx.refreshTokens();
+
+  // ---------- attachments ----------
+  api.uploadAttachment = async (att) => {
+    const file = await toFile(att);
+    const res = await ctx.http.postMultipart(
+      "https://upload.facebook.com/ajax/mercury/upload.php",
+      ctx.form({ voice_clip: "false" }),
+      { field: "upload_1024", ...file }
+    );
+    if (res.error) throw new Error("upload failed: " + (res.errorDescription || res.error));
+    const meta = res.payload && res.payload.metadata && res.payload.metadata[0];
+    if (!meta) throw new Error("upload failed: empty metadata");
+    const key = Object.keys(meta).find((k) => /_id$/.test(k));
+    if (!key) throw new Error("upload failed: unknown metadata shape");
+    return { type: key, id: meta[key] }; // e.g. { type: "image_id", id: "123..." }
+  };
+
+  // ---------- messaging ----------
+  // sendMessage("hi", threadID, { isGroup })
+  // sendMessage({ body, attachment: [path|Buffer], sticker, mentions:[{tag,id}], replyTo }, threadID, { isGroup })
+  api.sendMessage = (message, threadID, opts = {}) =>
+    enqueue(async () => {
+      if (!threadID) throw new Error("threadID is required");
+      const msg = typeof message === "string" ? { body: message } : { ...message };
+      if (!msg.body && !msg.attachment && !msg.sticker) throw new Error("Nothing to send");
+
+      const { otid, fields } = messageBase();
+      fields.body = msg.body || "";
+
+      (msg.mentions || []).forEach((m, i) => {
+        const offset = fields.body.indexOf(m.tag, m.fromIndex || 0);
+        if (offset < 0) return;
+        fields[`profile_xmd[${i}][id]`] = m.id;
+        fields[`profile_xmd[${i}][offset]`] = offset;
+        fields[`profile_xmd[${i}][length]`] = m.tag.length;
+        fields[`profile_xmd[${i}][type]`] = "p";
+      });
+
+      const atts = msg.attachment ? [].concat(msg.attachment) : [];
+      const counters = {};
+      for (const a of atts) {
+        const { type, id } = await api.uploadAttachment(a);
+        const n = counters[type] || 0;
+        counters[type] = n + 1;
+        fields[`${type}s[${n}]`] = id;
+        fields.has_attachment = true;
+      }
+
+      if (msg.sticker) {
+        fields.sticker_id = msg.sticker;
+        fields.has_attachment = true;
+      }
+      if (msg.replyTo) fields.replied_to_message_id = msg.replyTo;
+
+      if (opts.isGroup) {
+        fields.thread_fbid = threadID;
+      } else {
+        fields.other_user_fbid = threadID;
+        fields["specific_to_list[0]"] = "fbid:" + threadID;
+        fields["specific_to_list[1]"] = "fbid:" + ctx.userID;
+      }
+
+      const res = await call(SEND_URL, fields);
+      const act = res.payload && res.payload.actions && res.payload.actions[0];
+      return { messageID: (act && act.message_id) || otid, threadID };
+    });
+
+  api.unsendMessage = async (messageID) => {
+    await call("https://www.facebook.com/messaging/unsend_message/", { message_id: messageID });
+  };
+
+  // emoji = "❤" etc. Pass "" to remove the reaction
+  api.setMessageReaction = async (emoji, messageID) => {
+    const res = await ctx.http.postJson(
+      "https://www.facebook.com/webgraphql/mutation/",
+      ctx.form({
+        doc_id: "1491398900900362",
+        variables: JSON.stringify({
+          data: {
+            action: emoji ? "ADD_REACTION" : "REMOVE_REACTION",
+            client_mutation_id: "1",
+            actor_id: ctx.userID,
+            message_id: String(messageID),
+            reaction: emoji || undefined,
+          },
+        }),
+        dpr: 1,
+      })
+    );
+    if (res.error) throw new Error("setMessageReaction failed: " + (res.errorDescription || res.error));
+  };
+
+  api.markAsRead = async (threadID, read = true) => {
+    await call("https://www.facebook.com/ajax/mercury/change_read_status.php", {
+      [`ids[${threadID}]`]: read,
+      watermarkTimestamp: Date.now(),
+      shouldSendReadReceipt: true,
+      commerce_last_message_type: "non_ad",
+    });
+  };
+
+  api.sendTypingIndicator = async (threadID, isTyping = true, isGroup = false) => {
+    await ctx.http.postRaw(
+      "https://www.facebook.com/ajax/messaging/typ.php",
+      ctx.form({ typ: isTyping ? 1 : 0, to: isGroup ? "" : threadID, source: "mercury-chat", thread: threadID })
+    );
+  };
+
+  // ---------- users ----------
+  api.getUserInfo = async (userID) => {
+    const res = await call("https://www.facebook.com/chat/user_info/", { "ids[0]": userID });
+    return res.payload && res.payload.profiles ? res.payload.profiles[userID] || null : null;
+  };
+
+  api.getFriendsList = async () => {
+    const res = await call("https://www.facebook.com/chat/user_info_all", { viewer: ctx.userID });
+    const p = (res && res.payload) || {};
+    return Object.keys(p).map((id) => ({ userID: id, ...p[id] }));
+  };
+
+  // ---------- threads ----------
+  api.getThreadInfo = async (threadID) => {
+    const res = await call("https://www.facebook.com/ajax/mercury/thread_info.php", {
+      client: "mercury",
+      "threads[thread_fbids][0]": threadID,
+    });
+    return (res.payload && res.payload.threads && res.payload.threads[0]) || null;
+  };
+
+  api.getThreadList = async (limit = 20, offset = 0) => {
+    const res = await call("https://www.facebook.com/ajax/mercury/threadlist_info.php", {
+      client: "mercury",
+      "inbox[offset]": offset,
+      "inbox[limit]": limit,
+      "inbox[filter]": "",
+    });
+    return (res.payload && res.payload.threads) || [];
+  };
+
+  api.getThreadHistory = async (threadID, amount = 20, beforeTimestamp = null, isGroup = false) => {
+    const kind = isGroup ? "thread_fbids" : "user_ids";
+    const form = {
+      client: "mercury",
+      [`messages[${kind}][${threadID}][offset]`]: 0,
+      [`messages[${kind}][${threadID}][limit]`]: amount,
+    };
+    if (beforeTimestamp) form[`messages[${kind}][${threadID}][timestamp]`] = beforeTimestamp;
+    const res = await call("https://www.facebook.com/ajax/mercury/thread_info.php", form);
+    return (res.payload && res.payload.actions) || [];
+  };
+
+  // ---------- group management ----------
+  api.changeNickname = async (nickname, threadID, participantID) => {
+    await call("https://www.facebook.com/messaging/save_thread_nickname/", {
+      nickname,
+      participant_id: participantID,
+      thread_or_other_fbid: threadID,
+    });
+  };
+
+  api.setTitle = (newTitle, threadID) =>
+    enqueue(async () => {
+      const { fields } = messageBase();
+      Object.assign(fields, {
+        action_type: "ma-type:log-message",
+        log_message_type: "log:thread-name",
+        thread_name: newTitle,
+        thread_fbid: threadID,
+        thread_id: threadID,
+      });
+      await call(SEND_URL, fields);
+    });
+
+  api.addUserToGroup = (userIDs, threadID) =>
+    enqueue(async () => {
+      const { fields } = messageBase();
+      Object.assign(fields, {
+        action_type: "ma-type:log-message",
+        log_message_type: "log:subscribe",
+        thread_fbid: threadID,
+      });
+      [].concat(userIDs).forEach((id, i) => {
+        fields[`log_message_data[added_participants][${i}]`] = "fbid:" + id;
+      });
+      await call(SEND_URL, fields);
+    });
+
+  api.removeUserFromGroup = async (userID, threadID) => {
+    await call("https://www.facebook.com/chat/remove_participants/", { uid: userID, tid: threadID });
+  };
+
+  // Create a brand-new group chat. Returns the new threadID.
+  // Facebook requires at least 2 other participants to create a *group* thread;
+  // with exactly 1 participant it will just be a normal 1-to-1 thread.
+  api.createGroup = (userIDs, title) =>
+    enqueue(async () => {
+      const ids = [].concat(userIDs);
+      if (ids.length < 2) throw new Error("createGroup needs at least 2 other participants");
+
+      const { otid, fields } = messageBase();
+      fields.body = "";
+      ids.forEach((id, i) => {
+        fields[`specific_to_list[${i}]`] = "fbid:" + id;
+      });
+      fields[`specific_to_list[${ids.length}]`] = "fbid:" + ctx.userID;
+      fields.client_thread_id = "root:" + otid;
+      if (title) fields.thread_name = title;
+
+      const res = await call(SEND_URL, fields);
+      const act = res.payload && res.payload.actions && res.payload.actions[0];
+      const threadID = act && (act.thread_fbid || act.threadid);
+      if (!threadID) throw new Error("createGroup: could not read new thread id from response");
+      return String(threadID);
+    });
+
+  // role: "admin" grants, "member" revokes
+  api.changeAdminStatus = async (threadID, userID, makeAdmin = true) => {
+    await call("https://www.facebook.com/messaging/save_admins/", {
+      thread_fbid: threadID,
+      [`admin_ids[${makeAdmin ? "add" : "remove"}][0]`]: userID,
+    });
+  };
+
+  // hex color like "#0084ff", or one of Messenger's named theme ids
+  api.changeThreadColor = async (threadID, color) => {
+    await call("https://www.facebook.com/messaging/save_thread_color/", {
+      thread_fbid: threadID,
+      color,
+    });
+  };
+
+  // emoji = single emoji character used as the thread's quick-reaction/icon
+  api.changeThreadEmoji = async (threadID, emoji) => {
+    await call("https://www.facebook.com/messaging/save_thread_emoji/", {
+      thread_fbid: threadID,
+      emoji_choice: emoji,
+    });
+  };
+
+  api.muteThread = async (threadID, muteSeconds = -1) => {
+    // muteSeconds: -1 = mute indefinitely, 0 = unmute, N = mute for N seconds
+    await call("https://www.facebook.com/ajax/mercury/change_mute_thread.php", {
+      thread_fbid: threadID,
+      mute_settings: muteSeconds,
+    });
+  };
+
+  api.pinMessage = async (threadID, messageID, pinned = true) => {
+    const res = await ctx.http.postJson(
+      "https://www.facebook.com/webgraphql/mutation/",
+      ctx.form({
+        doc_id: "4260452710709500",
+        variables: JSON.stringify({
+          input: {
+            thread_key: threadID,
+            message_id: messageID,
+            pinned_state: pinned ? "PINNED" : "UNPINNED",
+            actor_id: ctx.userID,
+            client_mutation_id: "1",
+          },
+        }),
+      })
+    );
+    if (res.error) throw new Error("pinMessage failed: " + (res.errorDescription || res.error));
+  };
+
+  // options: array of strings; multiSelect allows more than one vote per person
+  api.createPoll = async (threadID, question, options, multiSelect = false) => {
+    const form = ctx.form({
+      thread_fbid: threadID,
+      question_text: question,
+      group_poll_allow_multiselect: multiSelect,
+    });
+    options.forEach((opt, i) => {
+      form[`options_text_array[${i}]`] = opt;
+    });
+    const res = await call("https://www.facebook.com/messaging/group_polling/create_poll/", form);
+    return (res.payload && res.payload.poll_id) || null;
+  };
+
+  api.voteInPoll = async (pollID, optionIDs) => {
+    const form = ctx.form({ question_id: pollID });
+    [].concat(optionIDs).forEach((id, i) => {
+      form[`option_ids[${i}]`] = id;
+    });
+    await call("https://www.facebook.com/messaging/group_polling/update_vote/", form);
+  };
+
+  // ---------- privacy ----------
+  api.blockUser = async (userID) => {
+    await call("https://www.facebook.com/ajax/settings/blocking/block.php", { uid: userID });
+  };
+
+  api.unblockUser = async (userID) => {
+    await call("https://www.facebook.com/ajax/settings/blocking/unblock.php", { uid: userID });
+  };
+
+  // ---------- search ----------
+  // Search threads by name (people or group titles)
+  api.searchThreads = async (query, limit = 10) => {
+    const res = await call("https://www.facebook.com/ajax/typeahead/search.php", {
+      filter: "user,group,pages",
+      value: query,
+      viewer: ctx.userID,
+      rsp: "search",
+      context: "search",
+      limit,
+    });
+    return (res.payload && (res.payload.entries || res.payload)) || [];
+  };
+
+  // Full-text search within one thread's message history.
+  // Facebook's search backend for this shifts around; treat the shape of
+  // the response as unstable and verify against your own account.
+  api.searchMessages = async (threadID, query, limit = 20) => {
+    const res = await call("https://www.facebook.com/ajax/mercury/search_snippets.php", {
+      query,
+      snippetLimit: limit,
+      "identifiers[0]": threadID,
+    });
+    return (res.payload && res.payload.snippets && res.payload.snippets[threadID]) || [];
+  };
+
+  // ---------- media (large/chunked upload) ----------
+  // For files too large for a single multipart POST (long videos, large
+  // archives). Splits into chunks and uploads sequentially, then finalizes.
+  // Chunk size and the resumable-upload endpoint shape are the parts of
+  // Facebook's upload pipeline most likely to have moved; if this fails,
+  // fall back to api.uploadAttachment for files under ~25MB.
+  api.uploadLargeAttachment = async (att, { chunkSizeBytes = 4 * 1024 * 1024 } = {}) => {
+    const file = await toFile(att);
+    const total = file.buffer.length;
+    if (total <= chunkSizeBytes) return api.uploadAttachment(att);
+
+    const startRes = await ctx.http.postJson(
+      "https://www.facebook.com/ajax/mercury/upload_resumable_start.php",
+      ctx.form({ file_name: file.filename, file_size: total, content_type: file.contentType })
+    );
+    if (startRes.error) throw new Error("resumable start failed: " + (startRes.errorDescription || startRes.error));
+    const uploadSessionId = startRes.payload && startRes.payload.upload_session_id;
+    if (!uploadSessionId) throw new Error("resumable start: no upload_session_id in response");
+
+    for (let offset = 0; offset < total; offset += chunkSizeBytes) {
+      const chunk = file.buffer.subarray(offset, Math.min(offset + chunkSizeBytes, total));
+      const res = await ctx.http.postMultipart(
+        "https://upload.facebook.com/ajax/mercury/upload_resumable_chunk.php",
+        ctx.form({ upload_session_id: uploadSessionId, offset }),
+        { field: "chunk", buffer: chunk, filename: file.filename, contentType: file.contentType }
+      );
+      if (res.error) throw new Error(`chunk upload failed at offset ${offset}: ` + (res.errorDescription || res.error));
+    }
+
+    const finishRes = await ctx.http.postJson(
+      "https://www.facebook.com/ajax/mercury/upload_resumable_finish.php",
+      ctx.form({ upload_session_id: uploadSessionId })
+    );
+    if (finishRes.error) throw new Error("resumable finish failed: " + (finishRes.errorDescription || finishRes.error));
+    const meta = finishRes.payload && finishRes.payload.metadata && finishRes.payload.metadata[0];
+    if (!meta) throw new Error("resumable finish: empty metadata");
+    const key = Object.keys(meta).find((k) => /_id$/.test(k));
+    return { type: key, id: meta[key] };
+  };
+
+  // ---------- listening ----------
+  // const stop = api.listen((err, event) => {...})
+  api.listen = (callback) => createListener(ctx, api, callback);
+  api.listenMqtt = api.listen; // FCA-style alias
+
+  return api;
+}
+
+module.exports = { buildApi };

package/src/http.js

@@ -0,0 +1,94 @@
+"use strict";
+
+const UA =
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36";
+
+class Http {
+  constructor(appState) {
+    this.jar = new Map();
+    for (const c of appState) {
+      const name = c.key || c.name;
+      if (name && c.value !== undefined) this.jar.set(name, c.value);
+    }
+  }
+
+  get userAgent() {
+    return UA;
+  }
+
+  cookieHeader() {
+    return [...this.jar].map(([k, v]) => `${k}=${v}`).join("; ");
+  }
+
+  exportAppState() {
+    return [...this.jar].map(([key, value]) => ({
+      key,
+      value,
+      domain: ".facebook.com",
+      path: "/",
+    }));
+  }
+
+  _absorb(res) {
+    const list = typeof res.headers.getSetCookie === "function" ? res.headers.getSetCookie() : [];
+    for (const line of list) {
+      const kv = line.split(";")[0];
+      const i = kv.indexOf("=");
+      if (i > 0) this.jar.set(kv.slice(0, i).trim(), kv.slice(i + 1).trim());
+    }
+  }
+
+  _headers(extra = {}) {
+    return {
+      "User-Agent": UA,
+      Cookie: this.cookieHeader(),
+      Origin: "https://www.facebook.com",
+      Referer: "https://www.facebook.com/",
+      "Accept-Language": "en-US,en;q=0.9",
+      ...extra,
+    };
+  }
+
+  _parse(text) {
+    try {
+      // Facebook prefixes JSON responses with "for (;;);"
+      return JSON.parse(text.replace(/^for \(;;\);/, ""));
+    } catch (e) {
+      const err = new Error("Non-JSON response from Facebook (session expired, blocked, or endpoint changed)");
+      err.raw = text.slice(0, 300);
+      throw err;
+    }
+  }
+
+  async getText(url) {
+    const res = await fetch(url, { headers: this._headers(), redirect: "follow" });
+    this._absorb(res);
+    return res.text();
+  }
+
+  async postRaw(url, form) {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: this._headers({ "Content-Type": "application/x-www-form-urlencoded" }),
+      body: new URLSearchParams(form).toString(),
+    });
+    this._absorb(res);
+    return res.text();
+  }
+
+  async postJson(url, form) {
+    return this._parse(await this.postRaw(url, form));
+  }
+
+  // file: { field, buffer, filename, contentType }
+  async postMultipart(url, form, file) {
+    const fd = new FormData();
+    for (const [k, v] of Object.entries(form)) fd.append(k, String(v));
+    fd.append(file.field, new Blob([file.buffer], { type: file.contentType }), file.filename);
+    const res = await fetch(url, { method: "POST", headers: this._headers(), body: fd });
+    this._absorb(res);
+    return this._parse(await res.text());
+  }
+}
+
+module.exports = Http;

package/src/listen.js

@@ -0,0 +1,290 @@
+"use strict";
+
+const mqtt = require("mqtt");
+
+const TOPICS = [
+  "/t_ms", "/thread_typing", "/orca_typing_notifications", "/orca_presence", "/legacy_web",
+  "/br_sr", "/sr_res", "/webrtc", "/onevc", "/notify_disconnect", "/inbox", "/mercury",
+  "/messaging_events", "/orca_message_notifications", "/pp", "/webrtc_response",
+];
+
+// Initial sync sequence id via GraphQL.
+// The doc_id below is an internal Facebook value and may be outdated.
+async function fetchSeqID(ctx) {
+  const form = ctx.form({
+    queries: JSON.stringify({
+      o0: {
+        doc_id: "3336396659757871",
+        query_params: { limit: 1, before: null, tags: ["INBOX"], includeDeliveryReceipts: false, includeSeqID: true },
+      },
+    }),
+    batch_name: "MessengerGraphQLThreadlistFetcher",
+  });
+  const text = await ctx.http.postRaw("https://www.facebook.com/api/graphqlbatch/", form);
+  const first = text.split("\n")[0].replace(/^for \(;;\);/, "");
+  let json;
+  try {
+    json = JSON.parse(first);
+  } catch (e) {
+    throw new Error("Could not parse sequence id response (session invalid?)");
+  }
+  const seq =
+    json && json.o0 && json.o0.data && json.o0.data.viewer && json.o0.data.viewer.message_threads &&
+    json.o0.data.viewer.message_threads.sync_sequence_id;
+  if (!seq) throw new Error("Could not read sync_sequence_id (doc_id outdated or session invalid)");
+  return seq;
+}
+
+const tid = (key) => String((key && (key.threadFbId || key.otherUserFbId)) || "");
+const isGroupKey = (key) => !!(key && key.threadFbId);
+
+// Returns an array of normalized events for one delta
+function parseDelta(delta, api) {
+  const out = [];
+  const cls = delta.class;
+  const md = delta.messageMetadata;
+
+  if (cls === "NewMessage" && md) {
+    const threadID = tid(md.threadKey);
+    const isGroup = isGroupKey(md.threadKey);
+    out.push({
+      type: "message",
+      threadID,
+      senderID: String(md.actorFbId),
+      messageID: md.messageId,
+      body: delta.body || "",
+      timestamp: md.timestamp,
+      isGroup,
+      attachments: delta.attachments || [],
+      replyToMessageID: delta.messageReply && delta.messageReply.replyToMessageId
+        ? delta.messageReply.replyToMessageId.id
+        : null,
+      reply: (text) => api.sendMessage(text, threadID, { isGroup }),
+    });
+  } else if (cls === "ParticipantsAddedToGroupThread" && md) {
+    out.push({
+      type: "event",
+      logMessageType: "log:subscribe",
+      threadID: tid(md.threadKey),
+      authorID: String(md.actorFbId),
+      addedParticipants: (delta.addedParticipants || []).map((p) => String(p.userFbId)),
+      isGroup: true,
+    });
+  } else if (cls === "ParticipantLeftGroupThread" && md) {
+    out.push({
+      type: "event",
+      logMessageType: "log:unsubscribe",
+      threadID: tid(md.threadKey),
+      authorID: String(md.actorFbId),
+      leftParticipantFbId: String(delta.leftParticipantFbId),
+      isGroup: true,
+    });
+  } else if (cls === "ThreadName" && md) {
+    out.push({
+      type: "event",
+      logMessageType: "log:thread-name",
+      threadID: tid(md.threadKey),
+      authorID: String(md.actorFbId),
+      name: delta.name,
+      isGroup: true,
+    });
+  } else if (cls === "ReadReceipt") {
+    out.push({
+      type: "read_receipt",
+      threadID: tid(delta.threadKey),
+      readerID: String(delta.actorFbId),
+      time: delta.actionTimestampMs,
+    });
+  } else if (cls === "ClientPayload" && Array.isArray(delta.payload)) {
+    // Reactions and unsends arrive as a byte-array JSON payload
+    let inner;
+    try {
+      inner = JSON.parse(Buffer.from(delta.payload).toString("utf8"));
+    } catch (e) {
+      return out;
+    }
+    for (const d of inner.deltas || []) {
+      if (d.deltaMessageReaction) {
+        const r = d.deltaMessageReaction;
+        out.push({
+          type: "message_reaction",
+          threadID: tid(r.threadKey),
+          messageID: r.messageId,
+          senderID: String(r.senderId), // author of the reacted message
+          userID: String(r.userId), // person who reacted
+          reaction: r.reaction,
+          action: r.action === 1 ? "remove" : "add",
+        });
+      }
+      if (d.deltaRecallMessageData) {
+        const r = d.deltaRecallMessageData;
+        out.push({
+          type: "message_unsend",
+          threadID: tid(r.threadKey),
+          messageID: r.messageID,
+          senderID: String(r.senderID),
+          deletionTimestamp: r.deletionTimestamp,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+function createListener(ctx, api, callback) {
+  let client = null;
+  let stopped = false;
+  let retry = 0;
+  let timer = null;
+
+  const emit = (event) => {
+    const o = ctx.options;
+    if (event.type === "message") {
+      if (!o.selfListen && event.senderID === ctx.userID) return;
+    } else if (event.type !== "system" && !o.listenEvents) {
+      return;
+    }
+    callback(null, event);
+  };
+
+  function scheduleReconnect() {
+    if (stopped || !ctx.options.autoReconnect || timer) return;
+
+    if (client) {
+      client.removeAllListeners();
+      client.on("error", () => {});
+      client.end(true);
+      client = null;
+    }
+
+    retry += 1;
+    if (retry > ctx.options.maxRetries) {
+      callback(new Error("Giving up after too many reconnect attempts"));
+      return;
+    }
+
+    const delay = Math.min(30000, 1000 * 2 ** retry);
+    emit({ type: "system", state: "reconnecting", attempt: retry, delayMs: delay });
+    timer = setTimeout(async () => {
+      timer = null;
+      try {
+        await ctx.refreshTokens();
+      } catch (e) {
+        /* ignore; connect() will report */
+      }
+      connect();
+    }, delay);
+  }
+
+  async function connect() {
+    if (stopped) return;
+    try {
+      if (!ctx.lastSeqId) ctx.lastSeqId = await fetchSeqID(ctx);
+
+      const sessionID = Math.floor(Math.random() * 9007199254740991) + 1;
+      const username = {
+        u: ctx.userID, s: sessionID, chat_on: true, fg: false, d: ctx.clientID, ct: "websocket",
+        aid: "219994525426954", aids: null, mqtt_sid: "", cp: 3, ecp: 10, st: [], pm: [], dc: "",
+        no_auto_fg: true, gas: null, pack: [], p: null, php_override: "",
+      };
+      const url = `wss://edge-chat.facebook.com/chat?region=${ctx.region}&sid=${sessionID}&cid=${ctx.clientID}`;
+
+      client = mqtt.connect(url, {
+        clientId: "mqttwsclient",
+        protocolId: "MQIsdp",
+        protocolVersion: 3,
+        username: JSON.stringify(username),
+        clean: true,
+        keepalive: 10,
+        reschedulePings: false,
+        reconnectPeriod: 0, // we handle reconnects ourselves
+        wsOptions: {
+          headers: {
+            Cookie: ctx.http.cookieHeader(),
+            Origin: "https://www.facebook.com",
+            "User-Agent": ctx.http.userAgent,
+            Referer: "https://www.facebook.com/",
+            Host: "edge-chat.facebook.com",
+          },
+          origin: "https://www.facebook.com",
+          protocolVersion: 13,
+        },
+      });
+
+      client.on("connect", () => {
+        retry = 0;
+        TOPICS.forEach((t) => client.subscribe(t));
+
+        const queue = {
+          sync_api_version: 10,
+          max_deltas_able_to_process: 1000,
+          delta_batch_size: 500,
+          encoding: "JSON",
+          entity_fbid: ctx.userID,
+        };
+        let topic;
+        if (ctx.syncToken) {
+          topic = "/messenger_sync_get_diffs";
+          queue.last_seq_id = ctx.lastSeqId;
+          queue.sync_token = ctx.syncToken;
+        } else {
+          topic = "/messenger_sync_create_queue";
+          queue.initial_titles_cursor = null;
+          queue.device_params = null;
+          queue.last_seq_id = ctx.lastSeqId;
+        }
+        client.publish(topic, JSON.stringify(queue), { qos: 1, retain: false });
+        emit({ type: "system", state: "connected" });
+      });
+
+      client.on("message", (topic, payload) => {
+        let msg;
+        try {
+          msg = JSON.parse(payload.toString());
+        } catch (e) {
+          return;
+        }
+
+        if (topic === "/thread_typing" || topic === "/orca_typing_notifications") {
+          if (msg.type === "typ") {
+            emit({
+              type: "typ",
+              isTyping: !!msg.state,
+              from: String(msg.sender_fbid),
+              threadID: String(msg.thread || msg.sender_fbid),
+            });
+          }
+          return;
+        }
+
+        if (topic !== "/t_ms") return;
+
+        if (msg.firstDeltaSeqId && msg.syncToken) {
+          ctx.lastSeqId = msg.firstDeltaSeqId;
+          ctx.syncToken = msg.syncToken;
+        }
+        if (msg.lastIssuedSeqId) ctx.lastSeqId = msg.lastIssuedSeqId;
+
+        for (const delta of msg.deltas || []) {
+          for (const event of parseDelta(delta, api)) emit(event);
+        }
+      });
+
+      client.on("error", (err) => callback(err));
+      client.on("close", scheduleReconnect);
+    } catch (err) {
+      callback(err);
+      scheduleReconnect();
+    }
+  }
+
+  connect();
+
+  return function stop() {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    if (client) client.end(true);
+  };
+}
+
+module.exports = { createListener };