toru-fca 1.0.0

package/index.js

@@ -0,0 +1,715 @@
+"use strict";
+/* ═══════════════════════════════════════════════════════════════════════════
+ *  alpha-fca  v1.0.0  —  index.js
+ *  Ultimate merged Facebook Chat API
+ *  Best-of: hridoy-custom · hridoy-akash · ST-FCA · fca-azad · mahmud-fca
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+
+var utils        = require("./utils");
+var cheerio      = require("cheerio");
+var log          = require("npmlog");
+var fs           = require("fs");
+var path         = require("path");
+var request      = require("request");
+var AdvancedSystem = require("./advancedSystem");
+var { checkForFCAUpdate } = require("./checkUpdate");
+
+log.maxRecordSize = 100;
+
+// ─── Global state guards ─────────────────────────────────────────────────────
+global._alphaFcaUpdateChecked = global._alphaFcaUpdateChecked || false;
+global._alphaFcaErrorHandlers = global._alphaFcaErrorHandlers || false;
+
+// Load config.json once per process
+global._alphaFcaConfig = global._alphaFcaConfig || (() => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__dirname, "config.json"), "utf8"));
+  } catch (_) {
+    return {
+      version   : "1.0.0",
+      automation: { enabled: false },
+      inbox     : { enabled: true },
+      smooth    : { enabled: true },
+      e2ee      : { enable: true }
+    };
+  }
+})();
+
+// ─── Global error handlers (install exactly once) ────────────────────────────
+if (!global._alphaFcaErrorHandlers) {
+  global._alphaFcaErrorHandlers = true;
+
+  process.on("unhandledRejection", (reason) => {
+    try {
+      if (reason && typeof reason === "object") {
+        const code = reason.code || (reason.cause && reason.cause.code);
+        const msg  = reason.message || String(reason);
+
+        if (/No Sequelize instance passed/i.test(msg)) return; // silent
+
+        if (code === "UND_ERR_CONNECT_TIMEOUT" || code === "ETIMEDOUT" ||
+            /Connect Timeout|fetch failed/i.test(msg)) {
+          log.warn("alpha-fca", "Network timeout (non-fatal): " + msg);
+          return;
+        }
+        if (/ECONNREFUSED|ENOTFOUND|ECONNRESET/.test(code || msg)) {
+          log.warn("alpha-fca", "Network error (non-fatal): " + msg);
+          return;
+        }
+      }
+      log.warn("alpha-fca", "Unhandled rejection (non-fatal): " +
+        (reason && reason.message ? reason.message : String(reason)));
+    } catch (_) {}
+  });
+
+  process.on("uncaughtException", (error) => {
+    try {
+      const msg  = error.message || String(error);
+      const code = error.code;
+      if (/No Sequelize instance passed/i.test(msg)) return;
+      if (code === "UND_ERR_CONNECT_TIMEOUT" || code === "ETIMEDOUT" ||
+          /Connect Timeout|fetch failed/i.test(msg)) {
+        log.warn("alpha-fca", "Uncaught network timeout (non-fatal): " + msg);
+        return;
+      }
+      log.warn("alpha-fca", "Uncaught exception (continuing): " + msg);
+    } catch (_) {}
+  });
+}
+
+// ─── Non-blocking update check (once per process) ────────────────────────────
+if (!global._alphaFcaUpdateChecked) {
+  global._alphaFcaUpdateChecked = true;
+  setImmediate(() => checkForFCAUpdate().catch(() => {}));
+}
+
+// ─── Boolean options (cast to bool) ──────────────────────────────────────────
+const BOOL_OPTIONS = [
+  "online", "selfListen", "selfListenEvent", "listenEvents", "updatePresence",
+  "forceLogin", "autoMarkDelivery", "autoMarkRead", "listenTyping",
+  "autoReconnect", "emitReady"
+];
+
+function setOptions(globalOptions, options) {
+  if (!options || typeof options !== "object") return;
+  Object.keys(options).forEach(function(key) {
+    if (BOOL_OPTIONS.includes(key)) {
+      globalOptions[key] = Boolean(options[key]);
+    } else {
+      switch (key) {
+        case "pauseLog":
+          options.pauseLog ? log.pause() : log.resume();
+          break;
+        case "logLevel":
+          log.level = options.logLevel;
+          globalOptions.logLevel = options.logLevel;
+          break;
+        case "logRecordSize":
+          log.maxRecordSize = options.logRecordSize;
+          globalOptions.logRecordSize = options.logRecordSize;
+          break;
+        case "pageID":
+          globalOptions.pageID = options.pageID.toString();
+          break;
+        case "userAgent":
+          globalOptions.userAgent = options.userAgent ||
+            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36";
+          break;
+        case "proxy":
+          if (typeof options.proxy !== "string") {
+            delete globalOptions.proxy;
+            utils.setProxy();
+          } else {
+            globalOptions.proxy = options.proxy;
+            utils.setProxy(globalOptions.proxy);
+          }
+          break;
+        default:
+          // Pass through unknown options (e.g., reconnect delays, E2EE opts)
+          globalOptions[key] = options[key];
+      }
+    }
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  buildAPI  —  core context + api object construction
+// ─────────────────────────────────────────────────────────────────────────────
+function buildAPI(globalOptions, html, jar) {
+  const fcaCfg = global._alphaFcaConfig || {};
+
+  const advancedSystem = new AdvancedSystem({
+    automationEnabled: Boolean(fcaCfg.automation && fcaCfg.automation.enabled),
+    minDelayMs       : Number(fcaCfg.connection && fcaCfg.connection.minDelayMs) || 1000,
+    maxDelayMs       : Number(fcaCfg.connection && fcaCfg.connection.maxDelayMs) || 30000
+  });
+
+  // ── Extract fb_dtsg and irisSeqID from HTML ──────────────────────────────
+  let fb_dtsg   = null;
+  let irisSeqID = null;
+
+  ;(function extractFromHTML() {
+    try {
+      const $ = cheerio.load(html);
+      const patterns = [
+        /\["DTSGInitialData",\[\],{"token":"([^"]+)"}\]/,
+        /\["DTSGInitData",\[\],{"token":"([^"]+)"/,
+        /,"token":"([^"]+)"/,
+        /{"token":"([^"]+)"/,
+        /name="fb_dtsg" value="([^"]+)"/,
+        /"async_get_token":"([^"]+)"/,
+        /"dtsg":\{"token":"([^"]+)"/
+      ];
+      $("script").each((_, script) => {
+        if (fb_dtsg) return;
+        const text = $(script).html() || "";
+        for (const p of patterns) {
+          const m = text.match(p);
+          if (m && m[1]) { fb_dtsg = m[1]; break; }
+        }
+      });
+      if (!fb_dtsg) {
+        const inp = $("input[name=\"fb_dtsg\"]").val();
+        if (inp) fb_dtsg = inp;
+      }
+      const seqM = html.match(/irisSeqID":"([^"]+)"/);
+      if (seqM && seqM[1]) irisSeqID = seqM[1];
+    } catch (e) {
+      log.warn("buildAPI", "Error extracting fb_dtsg: " + (e && e.message ? e.message : e));
+    }
+  })();
+
+  // ── Identify the logged-in user ───────────────────────────────────────────
+  const cookies = jar.getCookies("https://www.facebook.com");
+  const userCookie  = cookies.find(c => c.cookieString().startsWith("c_user="));
+  const iUserCookie = cookies.find(c => c.cookieString().startsWith("i_user="));
+
+  if (!userCookie && !iUserCookie) {
+    log.error("buildAPI", "Cookie state is invalid — no c_user or i_user cookie found.");
+    return null;
+  }
+  if (html.includes("/checkpoint/block/?next")) {
+    log.error("buildAPI", "Account is checkpointed. Please resolve on Facebook before retrying.");
+    return null;
+  }
+
+  const userID   = (iUserCookie || userCookie).cookieString().split("=")[1];
+  const clientID = (Math.random() * 2147483648 | 0).toString(16);
+
+  // ── MQTT endpoint / region extraction ────────────────────────────────────
+  let mqttEndpoint = "wss://edge-chat.facebook.com/chat?region=pnb";
+  let region       = "PNB";
+  try {
+    const epMatch = html.match(/"endpoint":"([^"]+)"/);
+    if (epMatch) {
+      let ep = epMatch[1].replace(/\\\//g, "/");
+      try {
+        const epUrl = new URL(ep);
+        epUrl.searchParams.delete("sid");
+        epUrl.searchParams.delete("cid");
+        region       = (epUrl.searchParams.get("region") || "PNB").toUpperCase();
+        mqttEndpoint = epUrl.toString();
+      } catch (_) {
+        mqttEndpoint = ep.replace(/[?&]sid=[^&]*/g, "").replace(/[?&]cid=[^&]*/g, "");
+        region = ((mqttEndpoint.match(/region=([^&]+)/) || [])[1] || "PNB").toUpperCase();
+      }
+    }
+  } catch (_) {}
+
+  log.info("alpha-fca", "Logged in as " + userID + " [region: " + region + "]");
+
+  // ── Core context object ───────────────────────────────────────────────────
+  const ctx = {
+    userID,
+    jar,
+    clientID,
+    globalOptions,
+    loggedIn        : true,
+    access_token    : "NONE",
+    clientMutationId: 0,
+    mqttClient      : undefined,
+    lastSeqId       : irisSeqID,
+    syncToken       : undefined,
+    mqttEndpoint,
+    region,
+    firstListen     : true,
+    fb_dtsg,
+    req_ID          : 0,
+    callback_Task   : {},
+    wsReqNumber     : 0,
+    wsTaskNumber    : 0,
+    reqCallbacks    : {},
+    threadTypes     : {}   // cache thread type (dm/group) per thread
+  };
+
+  // ── Load runtime config ───────────────────────────────────────────────────
+  let runtimeCfg = { enableTypingIndicator: false, typingDuration: 4000 };
+  try {
+    // Bot CWD config.json takes priority over FCA package config
+    const rootCfgPath = path.join(process.cwd(), "config.json");
+    const fcaCfgPath  = path.join(__dirname, "config.json");
+    for (const cfgPath of [fcaCfgPath, rootCfgPath]) {
+      if (fs.existsSync(cfgPath)) {
+        try {
+          const c = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+          if (c && typeof c === "object") {
+            if (c.enableTypingIndicator != null) runtimeCfg.enableTypingIndicator = c.enableTypingIndicator;
+            if (c.typingDuration        != null) runtimeCfg.typingDuration        = c.typingDuration;
+          }
+        } catch (_) {}
+      }
+    }
+    // GoatBot config override
+    if (global.GoatBot && global.GoatBot.config) {
+      const gc = global.GoatBot.config;
+      if (gc.enableTypingIndicator != null) runtimeCfg.enableTypingIndicator = gc.enableTypingIndicator;
+      if (gc.typingDuration        != null) runtimeCfg.typingDuration        = gc.typingDuration;
+    }
+  } catch (_) {}
+  ctx.config = runtimeCfg;
+
+  // ── E2EE options: layered config ──────────────────────────────────────────
+  try {
+    var _e2eeCfg = {};
+    const fcaCfgPath  = path.join(__dirname, "config.json");
+    const rootCfgPath = path.join(process.cwd(), "config.json");
+    for (const cfgPath of [fcaCfgPath, rootCfgPath]) {
+      if (fs.existsSync(cfgPath)) {
+        try {
+          const c = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+          if (c && c.e2ee && typeof c.e2ee === "object") Object.assign(_e2eeCfg, c.e2ee);
+        } catch (_) {}
+      }
+    }
+    if (_e2eeCfg.enable === true) globalOptions.enableE2EE = true;
+    globalOptions.e2eeLogLevel      = _e2eeCfg.logLevel      || "none";
+    globalOptions.e2eeAutoReconnect = _e2eeCfg.autoReconnect !== false;
+    const saveType = _e2eeCfg.saveType || (_e2eeCfg.memoryOnly === false ? "path" : "memory");
+    globalOptions.e2eeMemoryOnly = saveType !== "path";
+    if (saveType === "path") {
+      var devicePath = _e2eeCfg.devicePath || "./data/e2ee-device.json";
+      devicePath = path.resolve(process.cwd(), devicePath);
+      try { fs.mkdirSync(path.dirname(devicePath), { recursive: true }); } catch (_) {}
+      globalOptions.e2eeDevicePath = devicePath;
+    }
+    if (_e2eeCfg.deviceData) globalOptions.e2eeDeviceData = _e2eeCfg.deviceData;
+  } catch (_) {}
+
+  // ── Build default functions ───────────────────────────────────────────────
+  const defaultFuncs = utils.makeDefaults(html, userID, ctx);
+
+  // ── Core api object ───────────────────────────────────────────────────────
+  const api = {
+    ctx,
+    setOptions  : setOptions.bind(null, globalOptions),
+    getAppState : () => utils.getAppState(jar),
+    postFormData: (url, body) => defaultFuncs.postFormData(url, ctx.jar, body)
+  };
+
+  // ── Load all src/*.js modules ─────────────────────────────────────────────
+  try {
+    fs.readdirSync(path.join(__dirname, "src"))
+      .filter(v => v.endsWith(".js"))
+      .forEach(v => {
+        try {
+          api[v.replace(".js", "")] = require(path.join(__dirname, "src", v))(defaultFuncs, api, ctx);
+        } catch (err) {
+          log.warn("buildAPI", "Failed to load src/" + v + ": " + (err && err.message ? err.message : err));
+        }
+      });
+  } catch (err) {
+    log.error("buildAPI", "Failed to read src directory: " + (err && err.message ? err.message : err));
+  }
+
+  // ── Convenience aliases ───────────────────────────────────────────────────
+  api.listen              = api.listenMqtt;
+  api.send                = api.sendMessage;
+  api.getInbox            = api.getThreadList;
+  api.getInboxThreads     = api.getThreadList;
+  api.getInboxHistory     = api.getThreadHistory;
+  api.getCurrentUserID    = api.getCurrentUserID || function() { return ctx.userID; };
+
+  // Inbox guard — ensure always accessible
+  api.inbox = {
+    enabled   : true,
+    getThreads: api.getThreadList  ? api.getThreadList.bind(api)  : null,
+    getHistory: api.getThreadHistory ? api.getThreadHistory.bind(api) : null
+  };
+
+  // ── Logout: safe no-op (session stays alive) ─────────────────────────────
+  // Overrides src/logout.js — explicit decision to never destroy FB session.
+  api.logout = function(callback) {
+    log.warn("logout", "[alpha-fca] Logout is disabled — session kept alive.");
+    var cb = typeof callback === "function" ? callback : function() {};
+    cb(null);
+    return Promise.resolve();
+  };
+
+  // ── Session guard: auto-save appstate ────────────────────────────────────
+  api.sessionGuard = function(accountPath, opts) {
+    if (!accountPath || typeof accountPath !== "string") return null;
+    const _interval = (opts && opts.interval > 0) ? Number(opts.interval) : 3 * 60 * 1000;
+    const _debounce = (opts && opts.debounce > 0) ? Number(opts.debounce) : 30 * 1000;
+    let _lastSave = 0;
+    let _debTimer = null;
+
+    function _save() {
+      _debTimer = null;
+      if (Date.now() - _lastSave < _debounce) return;
+      try {
+        const appState = utils.getAppState(jar);
+        if (!appState || !appState.length) return;
+        fs.writeFileSync(accountPath, JSON.stringify(appState, null, 2), "utf8");
+        _lastSave = Date.now();
+      } catch (e) {
+        log.warn("sessionGuard", "Failed to save appstate: " + (e && e.message ? e.message : e));
+      }
+    }
+
+    // Periodic save
+    const _guardTimer = setInterval(function() {
+      if (!ctx.loggedIn) { clearInterval(_guardTimer); return; }
+      if (_debTimer || Date.now() - _lastSave < _debounce) return;
+      _save();
+    }, _interval);
+
+    // Hook into cookie updates for debounced save
+    if (jar._jar && typeof jar._jar.setCookie === "function") {
+      const _orig = jar._jar.setCookie.bind(jar._jar);
+      jar._jar.setCookie = function() {
+        const result = _orig.apply(this, arguments);
+        if (!_debTimer) _debTimer = setTimeout(_save, _debounce);
+        return result;
+      };
+    }
+
+    return { stop: function() { clearInterval(_guardTimer); if (_debTimer) { clearTimeout(_debTimer); _debTimer = null; } } };
+  };
+
+  // ── Automation guard (off by default) ────────────────────────────────────
+  if (!(fcaCfg.automation && fcaCfg.automation.enabled)) {
+    advancedSystem.setAutomationEnabled(false);
+  }
+  api.advanced             = advancedSystem;
+  api.getHealth            = function() { return advancedSystem.health(api); };
+  api.isAutomationEnabled  = function() { return advancedSystem.isAutomationEnabled(); };
+  api.setAutomationEnabled = function(enabled) { return advancedSystem.setAutomationEnabled(enabled); };
+  ctx.advancedSystem       = advancedSystem;
+
+  // ── Smooth mode (optional typing-indicator before send) ──────────────────
+  ;(function patchSmooth() {
+    const smooth = (fcaCfg.smooth) || {};
+    if (smooth.enabled !== true) return;           // off by default
+    const msgDelay = Number(smooth.messageDelay) || 400;
+    const _origSend = api.sendMessage;
+    if (typeof _origSend !== "function") return;
+    api.sendMessage = function(msg, threadID, callback, replyToMessage, isSingleUser) {
+      try {
+        if (typeof api.sendTypingIndicator === "function") {
+          api.sendTypingIndicator(threadID, function() {});
+        }
+      } catch (_) {}
+      return new Promise(function(resolve, reject) {
+        setTimeout(function() {
+          try {
+            const r = _origSend(msg, threadID, callback, replyToMessage, isSingleUser);
+            if (r && typeof r.then === "function") r.then(resolve).catch(reject);
+            else resolve(r);
+          } catch (e) { reject(e); }
+        }, msgDelay);
+      });
+    };
+    api.send = api.sendMessage;
+  })();
+
+  // ── E2EE: patch api + expose helpers ─────────────────────────────────────
+  if (globalOptions.enableE2EE) {
+    try {
+      const _e2ee = require("./e2ee");
+      _e2ee.patchApiForE2EE(api, ctx);
+
+      api.connectE2EE = function(callback) {
+        const bridge = _e2ee.createBridge(ctx);
+        api._e2eeBridge = bridge;
+        return bridge.connect(callback);
+      };
+
+      api.getE2EEBridge = function() {
+        return ctx._e2eeBridge || null;
+      };
+
+      api.getE2EEDeviceData = function(callback) {
+        let resolve, reject;
+        const promise = new Promise(function(res, rej) { resolve = res; reject = rej; });
+        if (ctx._e2eeDeviceData) {
+          if (typeof callback === "function") callback(null, ctx._e2eeDeviceData);
+          resolve(ctx._e2eeDeviceData);
+          return promise;
+        }
+        _e2ee.createBridge(ctx).getDeviceData()
+          .then(function(d) {
+            ctx._e2eeDeviceData = d;
+            if (typeof callback === "function") callback(null, d);
+            resolve(d);
+          })
+          .catch(function(e) {
+            if (typeof callback === "function") callback(e);
+            reject(e);
+          });
+        return promise;
+      };
+    } catch (patchErr) {
+      log.warn("E2EE", "Failed to init E2EE: " + (patchErr && patchErr.message ? patchErr.message : patchErr));
+    }
+  }
+
+  return { ctx, defaultFuncs, api };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  loginHelper  —  cookie-based login flow
+// ─────────────────────────────────────────────────────────────────────────────
+function makeLoginForm(jar, email, password, loginOptions, callback) {
+  return async function(res) {
+    try {
+      const html = res.body;
+      const $    = cheerio.load(html);
+      let arr    = [];
+      $("#login_form input").each((_, v) => arr.push({ val: $(v).val(), name: $(v).attr("name") }));
+      arr = arr.filter(v => v.val && v.val.length);
+      let form = utils.arrToForm(arr);
+      form.lsd      = utils.getFrom(html, "[\"LSD\",[],{\"token\":\"", "\"}");
+      form.lgndim   = Buffer.from(JSON.stringify({ w: 1440, h: 900, aw: 1440, ah: 834, c: 24 })).toString("base64");
+      form.email    = email;
+      form.pass     = password;
+      form.default_persistent = "0";
+      form.lgnrnd   = utils.getFrom(html, "name=\"lgnrnd\" value=\"", "\"");
+      form.locale   = "en_US";
+      form.timezone = "240";
+      form.lgnjs    = Math.floor(Date.now() / 1000);
+
+      // Inject pre-cookies from HTML
+      html.split("\"_js_").slice(1).forEach(val => {
+        const cd = JSON.parse("[\"" + utils.getFrom(val, "", "]") + "\"]");
+        jar.setCookie(utils.formatCookie(cd, "facebook"), "https://www.facebook.com");
+      });
+
+      log.info("alpha-fca", "Logging in with email/password...");
+      const loginRes = await utils.post(
+        "https://www.facebook.com/login/device-based/regular/login/?login_attempt=1&lwv=110",
+        jar, form, loginOptions
+      );
+      await utils.saveCookies(jar)(loginRes);
+      const headers = loginRes.headers;
+      if (!headers.location) throw new Error("Wrong username/password.");
+
+      if (headers.location.includes("https://www.facebook.com/checkpoint/")) {
+        log.info("alpha-fca", "Login approval required (2FA / checkpoint).");
+        const cpRes  = await utils.get(headers.location, jar, null, loginOptions);
+        await utils.saveCookies(jar)(cpRes);
+        const cpHtml = cpRes.body;
+        const $_cp   = cheerio.load(cpHtml);
+        let cpForm   = [];
+        $_cp("form input").each((_, v) => cpForm.push({ val: $_cp(v).val(), name: $_cp(v).attr("name") }));
+        cpForm = cpForm.filter(v => v.val && v.val.length);
+        const form2 = utils.arrToForm(cpForm);
+
+        if (cpHtml.includes("checkpoint/?next")) {
+          return new Promise((resolve, reject) => {
+            const submit2FA = async (code) => {
+              try {
+                form2.approvals_code = code;
+                form2["submit[Continue]"] = $_cp("#checkpointSubmitButton").html();
+                const r1 = await utils.post("https://www.facebook.com/checkpoint/?next=https%3A%2F%2Fwww.facebook.com%2Fhome.php", jar, form2, loginOptions);
+                await utils.saveCookies(jar)(r1);
+                const approvalError = $_cp("#approvals_code").parent().attr("data-xui-error");
+                if (approvalError) throw new Error("Invalid 2FA code.");
+                form2.name_action_selected = "dont_save";
+                const r2 = await utils.post("https://www.facebook.com/checkpoint/?next=https%3A%2F%2Fwww.facebook.com%2Fhome.php", jar, form2, loginOptions);
+                await utils.saveCookies(jar)(r2);
+                const appState = utils.getAppState(jar);
+                resolve(await loginHelper(appState, email, password, loginOptions, callback));
+              } catch (err) { reject(err); }
+            };
+            callback({ error: "login-approval", continue: submit2FA });
+          });
+        }
+
+        if (!loginOptions.forceLogin) throw new Error("Facebook blocked this login attempt.");
+        form2["submit[This was me]"] = cpHtml.includes("Suspicious Login") ? "This was me" : "This Is Okay";
+        await utils.post("https://www.facebook.com/checkpoint/?next=https%3A%2F%2Fwww.facebook.com%2Fhome.php", jar, form2, loginOptions);
+        form2.name_action_selected = "save_device";
+        await utils.post("https://www.facebook.com/checkpoint/?next=https%3A%2F%2Fwww.facebook.com%2Fhome.php", jar, form2, loginOptions);
+        const appState = utils.getAppState(jar);
+        return loginHelper(appState, email, password, loginOptions, callback);
+      }
+
+      await utils.get("https://www.facebook.com/", jar, null, loginOptions);
+      return utils.saveCookies(jar);
+    } catch (err) {
+      callback(err);
+    }
+  };
+}
+
+function loginHelper(appState, email, password, globalOptions, callback) {
+  const jar = utils.getJar();
+  let mainPromise;
+
+  if (appState) {
+    try {
+      if (typeof appState === "string") {
+        const trimmed = appState.trim();
+        if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+          appState = JSON.parse(trimmed);
+        } else {
+          // Support raw Cookie header string: "c_user=xxx; xs=yyy; ..."
+          appState = trimmed.split(/;\s*/).map(part => {
+            part = part.trim();
+            if (!part) return null;
+            const i = part.indexOf("=");
+            if (i <= 0) return null;
+            return { name: part.slice(0, i).trim(), value: part.slice(i + 1), domain: ".facebook.com", path: "/" };
+          }).filter(Boolean);
+        }
+      }
+    } catch (e) {
+      return callback(new Error("Failed to parse appState: " + e.message));
+    }
+
+    try {
+      if (!Array.isArray(appState)) throw new Error("appState must be an array or cookie string");
+      appState.forEach(c => {
+        const name = c && (c.key || c.name);
+        if (!name || typeof c.value === "undefined") return;
+        const domain  = c.domain || ".facebook.com";
+        const expires = c.expirationDate
+          ? new Date(c.expirationDate * 1000).toUTCString()
+          : (c.expires ? new Date(c.expires).toUTCString() : "");
+        const str = `${name}=${c.value};${expires ? " expires=" + expires + ";" : ""} domain=${domain}; path=${c.path || "/"};`;
+        try { jar.setCookie(str, "https://www.facebook.com/"); } catch (_) {}
+      });
+      mainPromise = utils.get("https://www.facebook.com/", jar, null, globalOptions, { noRef: true })
+        .then(utils.saveCookies(jar));
+    } catch (e) {
+      return callback(new Error("Failed to load appState: " + e.message));
+    }
+  } else {
+    mainPromise = utils.get("https://www.facebook.com/", null, null, globalOptions, { noRef: true })
+      .then(utils.saveCookies(jar))
+      .then(makeLoginForm(jar, email, password, globalOptions, callback))
+      .then(() => utils.get("https://www.facebook.com/", jar, null, globalOptions).then(utils.saveCookies(jar)));
+  }
+
+  function handleRedirect(res) {
+    const redir = /<meta http-equiv="refresh" content="0;url=([^"]+)[^>]+>/.exec(res.body);
+    if (redir && redir[1]) {
+      return utils.get(redir[1], jar, null, globalOptions).then(utils.saveCookies(jar));
+    }
+    return res;
+  }
+
+  let ctx, api;
+  mainPromise = mainPromise
+    .then(handleRedirect)
+    .then(res => {
+      // Ensure we get a desktop HTML response (needed to extract fb_dtsg properly)
+      if (!/MPageLoadClientMetrics/gs.test(res.body)) {
+        globalOptions.userAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36";
+        return utils.get("https://www.facebook.com/", jar, null, globalOptions, { noRef: true })
+          .then(utils.saveCookies(jar));
+      }
+      return res;
+    })
+    .then(handleRedirect)
+    .then(res => {
+      const result = buildAPI(globalOptions, res.body, jar);
+      if (!result) throw new Error("buildAPI returned null — cookie state invalid.");
+      ctx = result.ctx;
+      api = result.api;
+      return res;
+    });
+
+  if (globalOptions.pageID) {
+    mainPromise = mainPromise
+      .then(() => utils.get(
+        "https://www.facebook.com/" + globalOptions.pageID + "/messages/?section=messages&subsection=inbox",
+        jar, null, globalOptions
+      ))
+      .then(resData => {
+        let url = utils.getFrom(resData.body, "window.location.replace(\"https:\\/\\/www.facebook.com\\", "\");").split("\\").join("");
+        url = url.substring(0, url.length - 1);
+        return utils.get("https://www.facebook.com" + url, jar, null, globalOptions);
+      });
+  }
+
+  mainPromise
+    .then(() => {
+      log.info("alpha-fca", "Login successful. UserID: " + (ctx && ctx.userID));
+      callback(null, api);
+    })
+    .catch(e => callback(e));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  login  —  public entry point
+// ─────────────────────────────────────────────────────────────────────────────
+function login(loginData, options, callback) {
+  if (utils.getType(options) === "Function" || utils.getType(options) === "AsyncFunction") {
+    callback = options;
+    options  = {};
+  }
+
+  // Default global options
+  const globalOptions = {
+    selfListen          : true,
+    selfListenEvent     : false,
+    listenEvents        : true,
+    listenTyping        : false,
+    updatePresence      : false,
+    forceLogin          : true,
+    autoMarkDelivery    : false,
+    autoMarkRead        : false,
+    autoReconnect       : true,
+    // Reconnect backoff (used by listenMqtt)
+    reconnectMinDelayMs : 3000,
+    reconnectMaxDelayMs : 60000,
+    reconnectStableResetMs: 30000,
+    logRecordSize       : 100,
+    online              : false,   // false = lower automation / presence footprint
+    emitReady           : false,
+    userAgent           : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
+  };
+
+  // Promisify when no callback provided
+  let resolveFunc, rejectFunc;
+  const returnPromise = new Promise(function(resolve, reject) {
+    resolveFunc = resolve;
+    rejectFunc  = reject;
+  });
+  if (utils.getType(callback) !== "Function" && utils.getType(callback) !== "AsyncFunction") {
+    callback = function(err, api) {
+      if (err) return rejectFunc(err);
+      resolveFunc(api);
+    };
+  }
+
+  // Apply user-supplied options
+  setOptions(globalOptions, options || {});
+
+  if (loginData.email && loginData.password) {
+    setOptions(globalOptions, { logLevel: "silent", forceLogin: true });
+    loginHelper(loginData.appState, loginData.email, loginData.password, globalOptions, callback);
+  } else if (loginData.appState) {
+    loginHelper(loginData.appState, null, null, globalOptions, callback);
+  } else {
+    callback(new Error("loginData must have either appState or email+password."));
+  }
+
+  return returnPromise;
+}
+
+module.exports = login;
+module.exports.login   = login;
+module.exports.default = login;