@lazyneoaz/nkxchat 1.0.0

package/src/apis/pinMessage.js

@@ -0,0 +1,150 @@
+"use strict";
+
+const utils = require('../utils'); 
+const fs = require("fs");
+const path = require("path");
+const _ = require("lodash");
+const deepdash = require("deepdash");
+const { JSONPath } = require("jsonpath-plus");
+
+deepdash(_);
+
+/**
+ * Extract and save the full lightspeed_web_request object from thread data.
+ * Also search for specific pinned message commands.
+ * @param {Object} allJsonData - Raw JSON response from Facebook.
+ * @param {Object} options - Options for debug output.
+ * @returns {Object|null} The full lightspeed_web_request object or null.
+ */
+function extractAndSearchLightspeedRequest(allJsonData, options = {}) {
+  const { saveDebugFile = false, debugFilePath } = options;
+
+  let outputFile = null;
+  if (saveDebugFile && debugFilePath) {
+    outputFile = debugFilePath;
+  } else if (saveDebugFile) {
+    // Only save to current working directory if explicitly requested
+    outputFile = require('path').join(process.cwd(), "fca_neo_pro_lightspeed_debug.json");
+  }
+
+  const lightReq = _.get(allJsonData, "__bbox.result.data.viewer.lightspeed_web_request");
+  if (!lightReq) {
+    utils.warn("pin.js: lightspeed_web_request not found.");
+    return null;
+  }
+
+
+  try {
+    fs.writeFileSync(outputFile, JSON.stringify(lightReq, null, 2), "utf8");
+    utils.log(`pin.js: Saved lightspeed_web_request to ${outputFile}`);
+  } catch (err) {
+    utils.error("pin.js: Failed to write lightspeed_web_request.json", err);
+  }
+
+
+  try {
+    const matches = JSONPath({
+      path: `$..[?(@ === "setPinnedMessage" || @ === "deleteThenInsertMessage")]`,
+      json: lightReq
+    });
+
+    utils.log(`pin.js: Found ${matches.length} matching command(s).`);
+    matches.forEach((match, idx) => {
+      utils.log(`📌 Match ${idx + 1}:`, match);
+    });
+  } catch (err) {
+    utils.error("pin.js: JSONPath search failed.", err);
+  }
+
+  return lightReq;
+}
+
+module.exports = function (defaultFuncs, api, ctx) {
+  return async function pin(action, threadID, messageID) {
+    if (action === "list") {
+      if (!threadID) throw new Error('Action "list" requires threadID.');
+
+      try {
+        const url = `https://www.facebook.com/messages/t/${threadID}/`;
+        const allJsonData = await utils.json(url, ctx.jar, null, ctx.globalOptions, ctx);
+
+
+        const lightReq = extractAndSearchLightspeedRequest(allJsonData, { saveDebugFile: false });
+        if (!lightReq || !lightReq.pin_status) {
+          utils.warn("pin.js: No pinned messages found or pin_status missing.");
+          return [];
+        }
+        return lightReq;
+      } catch (err) {
+        utils.error(`pin.js: Failed to process "list" for thread ${threadID}`, err);
+        throw err;
+      }
+    }
+
+    if (!ctx.mqttClient) throw new Error("MQTT not connected.");
+    if (!threadID || !messageID) throw new Error(`"${action}" requires threadID and messageID.`);
+
+    const epoch_id = parseInt(utils.generateOfflineThreadingID());
+    const version_id = "9523201934447612";
+    const app_id = "2220391788200892";
+
+    const createMqttRequest = (tasks, increment = 0) => ({
+      app_id,
+      payload: JSON.stringify({ epoch_id: epoch_id + increment, tasks, version_id }),
+      request_id: (ctx.wsReqNumber = (ctx.wsReqNumber || 0) + 1),
+      type: 3
+    });
+
+    const publishMqtt = (content) =>
+      new Promise((resolve, reject) => {
+        ctx.mqttClient.publish("/ls_req", JSON.stringify(content), { qos: 1, retain: false }, (err) => {
+          if (err) reject(err);
+          else resolve({ success: true, request_id: content.request_id });
+        });
+      });
+
+    if (action === "pin") {
+      const pinTask = {
+        label: "430",
+        payload: JSON.stringify({ thread_key: threadID, message_id: messageID, timestamp_ms: Date.now() }),
+        queue_name: `pin_msg_v2_${threadID}`,
+        task_id: (ctx.wsTaskNumber = (ctx.wsTaskNumber || 0) + 1)
+      };
+      const setSearchTask = {
+        label: "751",
+        payload: JSON.stringify({ thread_key: threadID, message_id: messageID, pinned_message_state: 1 }),
+        queue_name: "set_pinned_message_search",
+        task_id: (ctx.wsTaskNumber = (ctx.wsTaskNumber || 0) + 1)
+      };
+      const req1 = createMqttRequest([pinTask], 0);
+      const req2 = createMqttRequest([setSearchTask], 1);
+      return Promise.all([publishMqtt(req1), publishMqtt(req2)]);
+    }
+
+    if (action === "unpin") {
+      const setSearchTask1 = {
+        label: "751",
+        payload: JSON.stringify({ thread_key: threadID, message_id: messageID, pinned_message_state: 0 }),
+        queue_name: "set_pinned_message_search",
+        task_id: (ctx.wsTaskNumber = (ctx.wsTaskNumber || 0) + 1)
+      };
+      const unpinTask = {
+        label: "431",
+        payload: JSON.stringify({ thread_key: threadID, message_id: messageID, timestamp_ms: Date.now() }),
+        queue_name: `unpin_msg_v2_${threadID}`,
+        task_id: (ctx.wsTaskNumber = (ctx.wsTaskNumber || 0) + 1)
+      };
+      const setSearchTask2 = {
+        label: "751",
+        payload: JSON.stringify({ thread_key: threadID, message_id: messageID, pinned_message_state: 0 }),
+        queue_name: "set_pinned_message_search",
+        task_id: (ctx.wsTaskNumber = (ctx.wsTaskNumber || 0) + 1)
+      };
+      await publishMqtt(createMqttRequest([setSearchTask1], 0));
+      await publishMqtt(createMqttRequest([unpinTask], 1));
+      return publishMqtt(createMqttRequest([setSearchTask2], 2));
+    }
+
+    throw new Error(`Invalid action: "${action}". Use "pin", "unpin", or "list".`);
+  };
+};

package/src/apis/produceMetaTheme.js

@@ -0,0 +1,160 @@
+"use strict";
+
+const utils = require("../utils");
+
+/**
+ * Generates custom Meta AI chat themes from a text prompt.
+ * Wraps the `useGenerateAIThemeMutation` GraphQL mutation.
+ *
+ * @param {string}  prompt       Natural-language description of the desired theme
+ * @param {object}  [opts]       { numThemes: 1-5, imageUrl? }
+ * @param {Function}[callback]
+ * @returns {Promise}
+ */
+module.exports = function (defaultFuncs, api, ctx) {
+  return function produceMetaTheme(prompt, opts, callback) {
+    let resolveFunc, rejectFunc;
+    const promise = new Promise((resolve, reject) => {
+      resolveFunc = resolve;
+      rejectFunc  = reject;
+    });
+
+    if (typeof opts === "function") {
+      callback = opts;
+      opts = {};
+    }
+    opts = opts || {};
+    if (typeof callback !== "function") {
+      callback = (err, data) => {
+        if (err) return rejectFunc(err);
+        resolveFunc(data);
+      };
+    }
+
+    if (!prompt || typeof prompt !== "string") {
+      callback(new Error("Prompt is required and must be a string"));
+      return promise;
+    }
+
+    const clamp  = (v, min, max) => Math.max(min, Math.min(max, v));
+    const randId = () => Math.floor(Math.random() * 10).toString();
+
+    const makeInput = () => {
+      const desired   = ("numThemes" in opts) ? Number(opts.numThemes) : 1;
+      const safeCount = clamp(Number.isFinite(desired) ? desired : 1, 1, 5);
+      const body = {
+        client_mutation_id: randId(),
+        actor_id:           ctx.userID,
+        bypass_cache:       true,
+        caller:             "MESSENGER",
+        num_themes:         safeCount,
+        prompt,
+      };
+      if (opts.imageUrl) body.image_url = opts.imageUrl;
+      return body;
+    };
+
+    const constructForm = (input) => ({
+      av:     ctx.userID,
+      __user: ctx.userID,
+      __a:    1,
+      __req:  utils.getSignatureID(),
+      dpr:    1,
+      fb_dtsg:  ctx.fb_dtsg,
+      jazoest:  ctx.jazoest,
+      lsd:      ctx.lsd || ctx.fb_dtsg,
+      fb_api_caller_class:      "RelayModern",
+      fb_api_req_friendly_name: "useGenerateAIThemeMutation",
+      variables:        JSON.stringify({ input }),
+      server_timestamps: true,
+      doc_id:           "23873748445608673",
+      fb_api_analytics_tags: JSON.stringify(["qpl_active_flow_ids=25309433,521485406"]),
+    });
+
+    const normalizeTheme = (t, idx) => ({
+      success:      true,
+      themeId:      t.id,
+      name:         t.accessibility_label || t.name || '',
+      description:  t.description || '',
+      serialNumber: idx + 1,
+      colors: {
+        primary:             (t.gradient_colors || [])[0] || t.fallback_color || null,
+        fallback:            t.fallback_color,
+        gradient:            t.gradient_colors || [],
+        backgroundGradient:  t.background_gradient_colors || t.gradient_colors || [],
+        composerBackground:  t.composer_background_color,
+        composerTint:        t.composer_tint_color,
+        titleBarBackground:  t.title_bar_background_color,
+        titleBarText:        t.title_bar_text_color,
+        titleBarButton:      t.title_bar_button_tint_color,
+        messageText:         t.message_text_color,
+        inboundGradient:     t.inbound_message_gradient_colors || t.gradient_colors || [],
+        primaryButton:       t.primary_button_background_color,
+        hotLike:             t.hot_like_color,
+      },
+      backgroundImage: t.background_asset ? (t.background_asset.image || {}).uri || null : null,
+      iconImage:       t.icon_asset       ? (t.icon_asset.image || {}).uri       || null : null,
+      alternativeThemes: Array.isArray(t.alternative_themes)
+        ? t.alternative_themes.map(a => ({
+            id:             a.id,
+            name:           a.accessibility_label || a.name || '',
+            backgroundImage: a.background_asset ? (a.background_asset.image || {}).uri || null : null,
+            iconImage:       a.icon_asset        ? (a.icon_asset.image || {}).uri        || null : null,
+            gradient_colors: a.gradient_colors || [],
+            fallback_color:  a.fallback_color || null,
+          }))
+        : [],
+    });
+
+    const KNOWN_ERRORS = [
+      { test: (e) => /not authorized/i.test(e && e.message || ''),  msg: "This account doesn't have permission to create AI themes." },
+      { test: (e) => /rate limit/i.test(e && e.message || ''),      msg: "Too many requests. Please wait before retrying." },
+      { test: (e) => /invalid/i.test(e && e.message || ''),         msg: "Invalid request parameters. Please review your input." },
+      { test: (e) => !!(e && e.statusCode === 403),                  msg: "Access forbidden. Your account may not support AI theme generation." },
+      { test: (e) => !!(e && e.statusCode === 429),                  msg: "Rate limit reached. Please wait before retrying." },
+    ];
+
+    const friendlyError = (err) => {
+      for (const { test, msg } of KNOWN_ERRORS) {
+        if (test(err)) return msg;
+      }
+      return "Something went wrong while generating your theme.";
+    };
+
+    (async function run() {
+      try {
+        const formData = constructForm(makeInput());
+        const raw      = await defaultFuncs.post("https://www.facebook.com/api/graphql/", ctx.jar, formData);
+        const checked  = await utils.parseAndCheckLogin(ctx, defaultFuncs)(raw);
+
+        if (checked.errors) throw checked.errors;
+
+        const payload = checked && checked.data && checked.data.xfb_generate_ai_themes_from_prompt;
+        if (!payload) throw new Error("Invalid response from AI theme generation");
+
+        if (!payload.success || !Array.isArray(payload.themes) || payload.themes.length === 0) {
+          throw new Error("No themes generated for the given prompt");
+        }
+
+        const normalized = payload.themes.map(normalizeTheme);
+        const out = {
+          success: true,
+          count:   normalized.length,
+          themes:  normalized,
+          ...normalized[0],
+        };
+
+        callback(null, out);
+      } catch (err) {
+        utils.error("produceMetaTheme", err.message || err);
+        callback({
+          error:         friendlyError(err),
+          originalError: (err && (err.message || err)) || String(err),
+          statusCode:    err && err.statusCode ? err.statusCode : null,
+        });
+      }
+    })();
+
+    return promise;
+  };
+};

package/src/apis/realtime.js

@@ -0,0 +1,182 @@
+"use strict";
+
+const { WebSocket } = require("undici");
+const EventEmitter = require("events");
+const utils = require('../utils'); 
+const HttpsProxyAgent = require("https-proxy-agent");
+
+function formatNotification(data) {
+    if (!data.data || !data.data.viewer) return null;
+    const notifEdge = data.data.viewer.notifications_page?.edges?.[1]?.node?.notif;
+    if (!notifEdge) return null;
+
+    return {
+        type: "notification",
+        notifID: notifEdge.notif_id,
+        body: notifEdge.body?.text,
+        senderID: Object.keys(notifEdge.tracking.from_uids || {})[0],
+        url: notifEdge.url,
+        timestamp: notifEdge.creation_time.timestamp,
+        seenState: notifEdge.seen_state,
+    };
+}
+
+module.exports = function (defaultFuncs, api, ctx) {
+    return function listenRealtime() {
+        const emitter = new EventEmitter();
+        let ws;
+        let reconnectTimeout;
+        let keepAliveInterval;
+        let stopped = false;
+        let reconnectAttempts = 0;
+
+        const subscriptions = [
+            '{"x-dgw-app-XRSS-method":"Falco","x-dgw-app-xrs-body":"true","x-dgw-app-XRS-Accept-Ack":"RSAck","x-dgw-app-XRSS-http_referer":"https://www.facebook.com/friends"}',
+            '{"x-dgw-app-XRSS-method":"FBGQLS:USER_ACTIVITY_UPDATE_SUBSCRIBE","x-dgw-app-XRSS-doc_id":"9525970914181809","x-dgw-app-XRSS-routing_hint":"UserActivitySubscription","x-dgw-app-xrs-body":"true","x-dgw-app-XRS-Accept-Ack":"RSAck","x-dgw-app-XRSS-http_referer":"https://www.facebook.com/friends"}',
+            '{"x-dgw-app-XRSS-method":"FBGQLS:ACTOR_GATEWAY_EXPERIENCE_SUBSCRIBE","x-dgw-app-XRSS-doc_id":"24191710730466150","x-dgw-app-XRSS-routing_hint":"CometActorGatewayExperienceSubscription","x-dgw-app-xrs-body":"true","x-dgw-app-XRS-Accept-Ack":"RSAck","x-dgw-app-XRSS-http_referer":"https://www.facebook.com/friends"}',
+            `{"x-dgw-app-XRSS-method":"FBLQ:comet_notifications_live_query_experimental","x-dgw-app-XRSS-doc_id":"9784489068321501","x-dgw-app-XRSS-actor_id":"${ctx.userID}","x-dgw-app-XRSS-page_id":"${ctx.userID}","x-dgw-app-XRSS-request_stream_retry":"false","x-dgw-app-xrs-body":"true","x-dgw-app-XRS-Accept-Ack":"RSAck","x-dgw-app-XRSS-http_referer":"https://www.facebook.com/friends"}`,
+            '{"x-dgw-app-XRSS-method":"FBGQLS:FRIEND_REQUEST_CONFIRM_SUBSCRIBE","x-dgw-app-XRSS-doc_id":"9687616244672204","x-dgw-app-XRSS-routing_hint":"FriendingCometFriendRequestConfirmSubscription","x-dgw-app-xrs-body":"true","x-dgw-app-XRS-Accept-Ack":"RSAck","x-dgw-app-XRSS-http_referer":"https://www.facebook.com/friends"}',
+            '{"x-dgw-app-XRSS-method":"FBGQLS:FRIEND_REQUEST_RECEIVE_SUBSCRIBE","x-dgw-app-XRSS-doc_id":"24047008371656912","x-dgw-app-XRSS-routing_hint":"FriendingCometFriendRequestReceiveSubscription","x-dgw-app-xrs-body":"true","x-dgw-app-XRS-Accept-Ack":"RSAck","x-dgw-app-XRSS-http_referer":"https://www.facebook.com/friends"}',
+            '{"x-dgw-app-XRSS-method":"FBGQLS:RTWEB_CALL_BLOCKED_SETTING_SUBSCRIBE","x-dgw-app-XRSS-doc_id":"24429620016626810","x-dgw-app-XRSS-routing_hint":"RTWebCallBlockedSettingSubscription_CallBlockSettingSubscription","x-dgw-app-xrs-body":"true","x-dgw-app-XRS-Accept-Ack":"RSAck","x-dgw-app-XRSS-http_referer":"https://www.facebook.com/friends"}',
+            '{"x-dgw-app-XRSS-method":"PresenceUnifiedJSON","x-dgw-app-xrs-body":"true","x-dgw-app-XRS-Accept-Ack":"RSAck","x-dgw-app-XRSS-http_referer":"https://www.facebook.com/friends"}',
+            '{"x-dgw-app-XRSS-method":"FBGQLS:MESSENGER_CHAT_TABS_NOTIFICATION_SUBSCRIBE","x-dgw-app-XRSS-doc_id":"23885219097739619","x-dgw-app-XRSS-routing_hint":"MWChatTabsNotificationSubscription_MessengerChatTabsNotificationSubscription","x-dgw-app-xrs-body":"true","x-dgw-app-XRS-Accept-Ack":"RSAck","x-dgw-app-XRSS-http_referer":"https://www.facebook.com/friends"}',
+            '{"x-dgw-app-XRSS-method":"FBGQLS:BATCH_NOTIFICATION_STATE_CHANGE_SUBSCRIBE","x-dgw-app-XRSS-doc_id":"30300156509571373","x-dgw-app-XRSS-routing_hint":"CometBatchNotificationsStateChangeSubscription","x-dgw-app-xrs-body":"true","x-dgw-app-XRS-Accept-Ack":"RSAck","x-dgw-app-XRSS-http_referer":"https://www.facebook.com/friends"}',
+            '{"x-dgw-app-XRSS-method":"FBGQLS:NOTIFICATION_STATE_CHANGE_SUBSCRIBE","x-dgw-app-XRSS-doc_id":"23864641996495578","x-dgw-app-XRSS-routing_hint":"CometNotificationsStateChangeSubscription","x-dgw-app-xrs-body":"true","x-dgw-app-XRS-Accept-Ack":"RSAck","x-dgw-app-XRSS-http_referer":"https://www.facebook.com/friends"}',
+            '{"x-dgw-app-XRSS-method":"FBGQLS:NOTIFICATION_STATE_CHANGE_SUBSCRIBE","x-dgw-app-XRSS-doc_id":"9754477301332178","x-dgw-app-XRSS-routing_hint":"CometFriendNotificationsStateChangeSubscription","x-dgw-app-xrs-body":"true","x-dgw-app-XRS-Accept-Ack":"RSAck","x-dgw-app-XRSS-http_referer":"https://www.facebook.com/friends"}'
+        ];
+
+        async function handleMessage(data) {
+            try {
+                const text = await data.text();
+                const jsonStart = text.indexOf("{");
+                if (jsonStart !== -1) {
+                    const jsonData = JSON.parse(text.substring(jsonStart));
+                    if (jsonData.code === 200) {
+                        utils.log("Realtime subscription ready");
+                        emitter.emit("success", jsonData);
+                        return;
+                    }
+
+                    const formattedNotif = formatNotification(jsonData);
+                    if (formattedNotif) {
+                        emitter.emit("notification", formattedNotif);
+                    } else {
+                        emitter.emit("payload", jsonData);
+                    }
+                }
+            } catch (err) {
+                utils.error("Realtime message parse error:", err);
+                emitter.emit("error", err);
+            }
+        }
+
+        function scheduleReconnect() {
+            if (stopped) return;
+            const base = 1000;
+            const max = 30000;
+            reconnectAttempts += 1;
+            const backoff = Math.min(max, base * Math.pow(2, Math.min(reconnectAttempts, 5)));
+            const jitter = Math.floor(Math.random() * 1000);
+            const delay = backoff + jitter;
+            clearTimeout(reconnectTimeout);
+            reconnectTimeout = setTimeout(connect, delay);
+            utils.warn("Realtime reconnect scheduled in", delay + "ms");
+        }
+
+        async function connect() {
+            try {
+                if (stopped) return;
+                const queryParams = new URLSearchParams({
+                    "x-dgw-appid": "2220391788200892",
+                    "x-dgw-appversion": "0",
+                    "x-dgw-authtype": "1:0",
+                    "x-dgw-version": "5",
+                    "x-dgw-uuid": ctx.userID,
+                    "x-dgw-tier": "prod",
+                    "x-dgw-deviceid": ctx.clientID,
+                    "x-dgw-app-stream-group": "group1"
+                });
+
+                const url = `wss://gateway.facebook.com/ws/realtime?${queryParams.toString()}`;
+                const cookies = ctx.jar.getCookiesSync("https://www.facebook.com").join("; ");
+
+                const baseHeaders = {
+                    "Cookie": cookies,
+                    "Origin": "https://www.facebook.com",
+                    "User-Agent": ctx.globalOptions.userAgent,
+                    "Referer": "https://www.facebook.com",
+                    "Host": new URL(url).hostname,
+                    "Accept-Encoding": "gzip, deflate, br",
+                    "Accept-Language": "en-US,en;q=0.9"
+                };
+
+                const wsOptions = { headers: baseHeaders };
+                if (ctx.globalOptions.proxy) {
+                    wsOptions.agent = new HttpsProxyAgent(ctx.globalOptions.proxy);
+                }
+
+                ws = new WebSocket(url, wsOptions);
+
+                ws.onopen = () => {
+                    reconnectAttempts = 0;
+                    utils.log("Realtime connected");
+                    subscriptions.forEach((payload, index) => {
+                        const prefix = Buffer.from([14, index, 0, payload.length]);
+                        const suffix = Buffer.from([0, 0]);
+                        const fullMessage = Buffer.concat([prefix, Buffer.from(payload), suffix]);
+                        ws.send(fullMessage);
+                    });
+
+                    keepAliveInterval = setInterval(() => {
+                        if (ws.readyState === ws.OPEN) {
+                            ws.send("ping");
+                        }
+                    }, 10000);
+                };
+
+                ws.onmessage = (event) => {
+                    if (event.data instanceof Blob) {
+                        handleMessage(event.data);
+                    } else if (typeof event.data === "string") {
+                        handleMessage(new Blob([event.data]));
+                    } else if (event.data instanceof ArrayBuffer) {
+                        handleMessage(new Blob([event.data]));
+                    } else {
+                        utils.warn("Realtime unknown message type:", typeof event.data);
+                    }
+                };
+
+                ws.onerror = (err) => {
+                    if (stopped) return;
+                    utils.error("Realtime socket error:", err.message || err);
+                    emitter.emit("error", err);
+                };
+
+                ws.onclose = () => {
+                    if (stopped) return;
+                    utils.warn("Realtime socket closed");
+                    clearInterval(keepAliveInterval);
+                    scheduleReconnect();
+                };
+
+            } catch (err) {
+                if (stopped) return;
+                utils.error("Realtime connection error:", err.message);
+                emitter.emit("error", err);
+                clearInterval(keepAliveInterval);
+                scheduleReconnect();
+            }
+        }
+
+        connect();
+
+        emitter.stop = () => {
+            stopped = true;
+            clearInterval(keepAliveInterval);
+            clearTimeout(reconnectTimeout);
+            if (ws) ws.close();
+        };
+
+        return emitter;
+    };
+};

package/src/apis/refreshFb_dtsg.js

@@ -0,0 +1,94 @@
+"use strict";
+
+const utils = require("../utils");
+
+/**
+ * Refreshes the `fb_dtsg` and `jazoest` security tokens in the current session.
+ *
+ * Two modes:
+ *   1. Called with no arguments (or just a callback) — fetches a fresh token by
+ *      loading the Facebook homepage and parsing the token from the HTML.
+ *   2. Called with a payload object — directly assigns the provided fields to ctx.
+ *
+ * @example
+ * // Auto-refresh from Facebook:
+ * await api.refreshFb_dtsg();
+ *
+ * // Manual override:
+ * await api.refreshFb_dtsg({ fb_dtsg: "newToken", jazoest: "12345" });
+ *
+ * @param {object|Function} [payload]  Object with { fb_dtsg?, jazoest?, lsd? }, or callback.
+ * @param {Function}        [callback]
+ * @returns {Promise<{ data: object, message: string }>}
+ */
+module.exports = function (defaultFuncs, api, ctx) {
+  return function refreshFb_dtsg(payload, callback) {
+    let opts  = payload;
+    let cb    = callback;
+
+    if (typeof payload === "function") {
+      cb   = payload;
+      opts = {};
+    }
+    if (!opts) opts = {};
+
+    if (utils.getType(opts) !== "Object") {
+      throw new Error("The first parameter must be an object or a callback function");
+    }
+
+    let resolveFunc, rejectFunc;
+    const promise = new Promise((resolve, reject) => {
+      resolveFunc = resolve;
+      rejectFunc  = reject;
+    });
+    if (!cb) {
+      cb = (err, data) => { if (err) return rejectFunc(err); resolveFunc(data); };
+    }
+
+    if (Object.keys(opts).length === 0) {
+      // ── Auto-refresh: parse from Facebook HTML ────────────────────
+      defaultFuncs
+        .get("https://www.facebook.com/", ctx.jar, { noRef: true })
+        .then((res) => {
+          const html = typeof res === "string" ? res : (res && res.body ? res.body : (res && res.data ? res.data : ""));
+
+          const fb_dtsg = utils.getFrom(html, '["DTSGInitData",[],{"token":"', '","') ||
+                          utils.getFrom(html, '"fb_dtsg":{"token":"', '"') ||
+                          utils.getFrom(html, 'name="fb_dtsg" value="', '"');
+          const jazoest = utils.getFrom(html, "jazoest=", '"') ||
+                          utils.getFrom(html, '"jazoest":"', '"');
+
+          if (!fb_dtsg) throw new Error("Could not find fb_dtsg in HTML. Session may have expired.");
+
+          const updated = { fb_dtsg };
+          if (jazoest) updated.jazoest = jazoest;
+
+          Object.assign(ctx, updated);
+
+          const result = {
+            data:    updated,
+            message: "Refreshed fb_dtsg" + (jazoest ? " and jazoest" : ""),
+          };
+          cb(null, result);
+        })
+        .catch((err) => {
+          utils.error("refreshFb_dtsg", err.message || err);
+          cb(err instanceof Error ? err : new Error(String(err.message || err)));
+        });
+    } else {
+      // ── Manual override: apply provided fields directly ───────────
+      const allowed = ["fb_dtsg", "jazoest", "lsd", "clientID", "userID"];
+      const filtered = {};
+      for (const key of allowed) {
+        if (key in opts) filtered[key] = opts[key];
+      }
+      Object.assign(ctx, filtered);
+      cb(null, {
+        data:    filtered,
+        message: `Updated: ${Object.keys(filtered).join(", ")}`,
+      });
+    }
+
+    return promise;
+  };
+};