@lazyneoaz/nkxchat 1.0.0

package/src/apis/removeUserFromGroup.js

@@ -0,0 +1,117 @@
+"use strict";
+
+const utils = require('../utils');
+
+module.exports = (defaultFuncs, api, ctx) => {
+  return async function removeUserFromGroup(userID, threadID, callback) {
+    let resolveFunc = () => {};
+    let rejectFunc = () => {};
+    const returnPromise = new Promise((resolve, reject) => {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+
+    if (!callback) {
+      callback = (err, result) => {
+        if (err) return rejectFunc(err);
+        resolveFunc(result);
+      };
+    }
+
+    try {
+      if (utils.getType(threadID) !== "Number" && utils.getType(threadID) !== "String") {
+        throw new Error("threadID should be of type Number or String");
+      }
+      if (utils.getType(userID) !== "Number" && utils.getType(userID) !== "String") {
+        throw new Error("userID should be of type Number or String");
+      }
+
+      if (ctx.mqttClient) {
+        const reqID = ++ctx.wsReqNumber;
+        const taskID = ++ctx.wsTaskNumber;
+
+        const payload = {
+          epoch_id: utils.generateOfflineThreadingID(),
+          tasks: [
+            {
+              failure_count: null,
+              label: '140',
+              payload: JSON.stringify({
+                thread_id: threadID,
+                contact_id: userID,
+                sync_group: 1
+              }),
+              queue_name: 'remove_participant_v2',
+              task_id: taskID
+            }
+          ],
+          version_id: '8798795233522156'
+        };
+
+        const form = JSON.stringify({
+          app_id: "2220391788200892",
+          payload: JSON.stringify(payload),
+          request_id: reqID,
+          type: 3
+        });
+
+        let responseHandled = false;
+        const handleRes = (topic, message) => {
+          if (topic !== "/ls_resp" || responseHandled) return;
+          let jsonMsg;
+          try {
+            jsonMsg = JSON.parse(message.toString());
+            jsonMsg.payload = JSON.parse(jsonMsg.payload);
+          } catch {
+            return;
+          }
+          if (jsonMsg.request_id !== reqID) return;
+          responseHandled = true;
+          ctx.mqttClient.removeListener("message", handleRes);
+          callback(null, { success: true });
+          resolveFunc({ success: true });
+        };
+
+        const timeout = setTimeout(() => {
+          if (!responseHandled) {
+            responseHandled = true;
+            ctx.mqttClient.removeListener("message", handleRes);
+            const err = new Error("MQTT request timeout");
+            callback(err);
+            rejectFunc(err);
+          }
+        }, 30000);
+
+        ctx.mqttClient.on("message", handleRes);
+        ctx.mqttClient.publish("/ls_req", form, { qos: 1, retain: false }, (err) => {
+          if (err && !responseHandled) {
+            responseHandled = true;
+            clearTimeout(timeout);
+            ctx.mqttClient.removeListener("message", handleRes);
+            callback(err);
+            rejectFunc(err);
+          }
+        });
+      } else {
+        const form = {
+          uid: userID,
+          tid: threadID
+        };
+
+        const res = await defaultFuncs.post("https://www.facebook.com/chat/remove_participants", ctx.jar, form)
+          .then(utils.parseAndCheckLogin(ctx, defaultFuncs));
+
+        if (!res || res.error) {
+          throw res || new Error("Remove from group failed");
+        }
+
+        callback(null, { success: true });
+      }
+    } catch (err) {
+      utils.error("removeUserFromGroup", err);
+      callback(err);
+    }
+
+    return returnPromise;
+  };
+};

package/src/apis/resolvePhotoUrl.js

@@ -0,0 +1,58 @@
+"use strict";
+
+const utils = require('../utils');
+
+/**
+ * @module resolvePhotoUrl
+ * @description Fetches the direct URL of a Facebook photo using its photo ID.
+ * @param {Object} defaultFuncs - An object containing default request functions.
+ * @param {Object} api - Facebook API object (unused here but kept for compatibility).
+ * @param {Object} ctx - Context object containing cookies (jar) and other session info.
+ * @returns {Function} resolvePhotoUrl - A function that takes a photo ID and optional callback, and returns a Promise resolving to the photo URL.
+ */
+module.exports = function (defaultFuncs, api, ctx) {
+/**
+* @function resolvePhotoUrl
+* @param {string} photoID - The ID of the Facebook photo to resolve.
+* @param {Function} [callback] - Optional Node-style callback function `(err, photoUrl)`.
+* @returns {Promise<string>} A Promise that resolves to the direct photo URL.
+*/
+return function resolvePhotoUrl(photoID, callback) {
+let resolveFunc = function () {};
+let rejectFunc = function () {};
+const returnPromise = new Promise(function (resolve, reject) {
+resolveFunc = resolve;
+rejectFunc = reject;
+});
+
+if (!callback) {
+callback = function (err, photoUrl) {
+if (err) {
+return rejectFunc(err);
+}
+resolveFunc(photoUrl);
+};
+}
+
+defaultFuncs
+.get("https://www.facebook.com/mercury/attachments/photo", ctx.jar, {
+photo_id: photoID,
+})
+.then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+.then((resData) => {
+if (resData.error) {
+throw resData;
+}
+
+const photoUrl = resData.jsmods.require[0][3][0];
+
+return callback(null, photoUrl);
+})
+.catch((err) => {
+utils.error("resolvePhotoUrl", err);
+return callback(err);
+});
+
+return returnPromise;
+};
+};

package/src/apis/searchForThread.js

@@ -0,0 +1,154 @@
+"use strict";
+
+const utils = require('../utils');
+
+module.exports = (defaultFuncs, api, ctx) => {
+  return async function searchForThread(searchQuery, callback) {
+    let resolveFunc = () => {};
+    let rejectFunc = () => {};
+    const returnPromise = new Promise((resolve, reject) => {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+
+    // Store original callback if provided
+    const originalCallback = callback;
+    
+    // Always use a wrapped callback that settles the promise
+    callback = (err, result) => {
+      if (originalCallback) {
+        originalCallback(err, result);
+      }
+      if (err) return rejectFunc(err);
+      resolveFunc(result);
+    };
+
+    if (!searchQuery || typeof searchQuery !== 'string') {
+      const error = { error: "searchForThread: searchQuery parameter must be a non-empty string" };
+      utils.error("searchForThread", error);
+      callback(error);
+      return returnPromise;
+    }
+
+    try {
+      // Strategy 1: Use GraphQL-based getThreadList and filter locally
+      // This bypasses checkpoint issues entirely
+      utils.log("searchForThread", "Using GraphQL-based search (bypasses checkpoints)");
+      
+      try {
+        // Use getThreadList to fetch threads from INBOX
+        // This ensures consistent behavior and avoids tag parameter issues
+        const threads = await api.getThreadList(100, null, ["INBOX"]);
+        
+        if (!threads || threads.length === 0) {
+          utils.warn("searchForThread", "No threads available in INBOX, trying legacy method");
+          throw new Error("No threads available from GraphQL");
+        }
+
+        utils.log("searchForThread", `Retrieved ${threads.length} threads from GraphQL`);
+
+        // Filter threads by search query (case-insensitive, partial match)
+        const searchLower = searchQuery.toLowerCase().trim();
+        const matchedThreads = threads.filter(thread => {
+          // Search in thread name
+          if (thread.threadName && thread.threadName.toLowerCase().includes(searchLower)) {
+            return true;
+          }
+          
+          // Search in thread ID (exact or partial match)
+          if (thread.threadID && thread.threadID.toString().includes(searchQuery)) {
+            return true;
+          }
+          
+          // Search in participant names
+          if (thread.userInfo && Array.isArray(thread.userInfo)) {
+            return thread.userInfo.some(user => 
+              user.name && user.name.toLowerCase().includes(searchLower)
+            );
+          }
+          
+          return false;
+        });
+
+        if (matchedThreads.length === 0) {
+          callback({ 
+            error: `Could not find thread matching "${searchQuery}".`,
+            details: "No threads match your search query. Try a different search term."
+          });
+          return returnPromise;
+        }
+
+        utils.log("searchForThread", `Found ${matchedThreads.length} matching thread(s) using GraphQL method`);
+        callback(null, matchedThreads);
+        return returnPromise;
+        
+      } catch (graphqlError) {
+        utils.warn("searchForThread", "GraphQL method failed, falling back to legacy AJAX endpoint");
+        utils.error("searchForThread GraphQL error", graphqlError);
+        
+        // Strategy 2: Fallback to legacy AJAX endpoint (may trigger checkpoints)
+        const form = {
+          client: "web_messenger",
+          query: searchQuery,
+          offset: 0,
+          limit: 21,
+          index: "fbid"
+        };
+
+        const res = await defaultFuncs.post(
+          "https://www.facebook.com/ajax/mercury/search_threads.php",
+          ctx.jar,
+          form
+        ).then(utils.parseAndCheckLogin(ctx, defaultFuncs));
+
+        if (!res) {
+          const error = { 
+            error: "Account checkpoint required - searchForThread is restricted until verification",
+            details: "Please verify your account on facebook.com. This function requires additional permissions.",
+            errorCode: 1357004,
+            errorType: 'CHECKPOINT'
+          };
+          callback(error);
+          return returnPromise;
+        }
+
+        if (res.error) {
+          throw res;
+        }
+
+        // Support both legacy payload.threads (object map) and newer payload.mercury_payload.threads (array)
+        let threadsData = res.payload?.mercury_payload?.threads || res.payload?.threads;
+        
+        if (!threadsData) {
+          callback({ 
+            error: `Could not find thread "${searchQuery}".`,
+            details: "The thread may not exist or access may be restricted."
+          });
+          return returnPromise;
+        }
+
+        // Convert legacy object format to array if needed
+        if (!Array.isArray(threadsData)) {
+          threadsData = Object.values(threadsData);
+        }
+
+        const threads = threadsData.map(utils.formatThread);
+        utils.log("searchForThread", `Found ${threads.length} thread(s) using legacy AJAX method`);
+        callback(null, threads);
+      }
+    } catch (err) {
+      // Enhanced error handling for checkpoint errors
+      if (err.errorCode === 1357004 || err.errorType === 'CHECKPOINT') {
+        err.error = "Account checkpoint required - searchForThread is restricted until verification";
+        err.friendlyMessage = "Your account requires verification on facebook.com before using search features";
+      } else if (err.error && typeof err.error === 'string' && err.error.includes('checkpoint')) {
+        err.friendlyMessage = "Account checkpoint required - searchForThread is restricted until verification";
+      }
+      
+      utils.error("searchForThread", err);
+      callback(err);
+    }
+
+    return returnPromise;
+  };
+};

package/src/apis/sendEffect.js

@@ -0,0 +1,306 @@
+"use strict";
+
+const utils = require('../utils');
+
+/**
+ * Facebook Messenger send effects — visual animations that play when a message is sent/received.
+ *
+ * Usage:
+ *   api.sendEffect.fire('Hello!', threadID)
+ *   api.sendEffect.send('love', 'Hello!', threadID)
+ *   api.sendEffect.list()  →  [{tag, aliases, emoji}, ...]
+ */
+
+const EFFECTS = {
+  fire:          { tag: 'FIRE',          emoji: '🔥', label: 'Fire' },
+  love:          { tag: 'LOVE',          emoji: '❤️', label: 'Love' },
+  heart:         { tag: 'LOVE',          emoji: '❤️', label: 'Love' },
+  hearts:        { tag: 'LOVE',          emoji: '❤️', label: 'Love' },
+  confetti:      { tag: 'CELEBRATION',   emoji: '🎉', label: 'Confetti' },
+  celebration:   { tag: 'CELEBRATION',   emoji: '🎉', label: 'Confetti' },
+  wand:          { tag: 'WAND',          emoji: '🪄', label: 'Wand' },
+  magic:         { tag: 'WAND',          emoji: '🪄', label: 'Wand' },
+  fireworks:     { tag: 'FIREWORKS',     emoji: '🎆', label: 'Fireworks' },
+  shooting_star: { tag: 'SHOOTING_STAR', emoji: '🌠', label: 'Shooting Star' },
+  stars:         { tag: 'SHOOTING_STAR', emoji: '🌠', label: 'Shooting Star' },
+  starstruck:    { tag: 'SHOOTING_STAR', emoji: '🌠', label: 'Shooting Star' },
+  balloons:      { tag: 'BIRTHDAY',      emoji: '🎈', label: 'Balloons' },
+  birthday:      { tag: 'BIRTHDAY',      emoji: '🎈', label: 'Balloons' },
+  horror:        { tag: 'HORROR',        emoji: '👻', label: 'Horror' },
+  halloween:     { tag: 'HORROR',        emoji: '👻', label: 'Horror' },
+  las_vegas:     { tag: 'LAS_VEGAS',     emoji: '🎰', label: 'Las Vegas' },
+  vegas:         { tag: 'LAS_VEGAS',     emoji: '🎰', label: 'Las Vegas' },
+  anniversary:   { tag: 'ANNIVERSARY',   emoji: '💍', label: 'Anniversary' },
+  spotlight:     { tag: 'SPOTLIGHT',     emoji: '✨', label: 'Spotlight' },
+};
+
+function resolveEffect(name) {
+  if (!name) return null;
+  const key = String(name).toLowerCase().replace(/[\s\-]+/g, '_');
+  return EFFECTS[key] ? EFFECTS[key].tag : name.toUpperCase();
+}
+
+function buildForm(effectTag, msgObj, threadID, ctx) {
+  const messageAndOTID = utils.generateOfflineThreadingID();
+  const timestamp = Date.now();
+  const messagingTag = 'fb.messaging.effects.' + effectTag;
+  const body = typeof msgObj === 'string' ? msgObj : (msgObj.body || '');
+
+  const form = {
+    client:               'mercury',
+    action_type:          'ma-type:user-generated-message',
+    author:               'fbid:' + ctx.userID,
+    timestamp,
+    timestamp_absolute:   'Today',
+    timestamp_relative:   utils.generateTimestampRelative(),
+    timestamp_time_passed:'0',
+    is_unread:            false,
+    is_cleared:           false,
+    is_forward:           false,
+    is_filtered_content:  false,
+    is_filtered_content_bh: false,
+    is_filtered_content_account: false,
+    is_filtered_content_quasar: false,
+    is_filtered_content_invalid_app: false,
+    is_spoof_warning:     false,
+    source:               'source:chat:web',
+    'source_tags[0]':     'source:chat',
+    body,
+    html_body:            false,
+    ui_push_phase:        'V3',
+    status:               '0',
+    offline_threading_id: messageAndOTID,
+    message_id:           messageAndOTID,
+    threading_id:         utils.generateThreadingID(ctx.clientID),
+    'ephemeral_ttl_mode:':'0',
+    manual_retry_cnt:     '0',
+    has_attachment:       !!(msgObj && msgObj.sticker),
+    signatureID:          utils.getSignatureID(),
+    has_lightweight_action:                          true,
+    'lightweight_action_attached[message_id]':       messageAndOTID,
+    'lightweight_action_attached[messaging_tag]':    messagingTag,
+  };
+
+  if (msgObj && msgObj.sticker) {
+    form.sticker_id = msgObj.sticker;
+  }
+
+  if (typeof msgObj === 'object' && msgObj.reply_to_message_id) {
+    form.replied_to_message_id = msgObj.reply_to_message_id;
+  }
+
+  const tid = String(threadID);
+  const isGroup = tid.length >= 16;
+  if (isGroup) {
+    form.thread_fbid = tid;
+  } else {
+    form['specific_to_list[0]'] = 'fbid:' + tid;
+    form['specific_to_list[1]'] = 'fbid:' + ctx.userID;
+    form.other_user_fbid        = tid;
+    form.client_thread_id       = 'root:' + messageAndOTID;
+  }
+
+  return { form, messageAndOTID, timestamp, messagingTag };
+}
+
+function buildMqttPayload(effectTag, msgObj, threadID, ctx) {
+  const otid      = utils.generateOfflineThreadingID();
+  const epoch_id  = utils.generateOfflineThreadingID();
+  const timestamp = Date.now();
+  const body      = typeof msgObj === 'string' ? msgObj : (msgObj && msgObj.body || '');
+  const tid       = String(threadID);
+
+  const sendPayload = {
+    thread_id:            tid,
+    otid:                 otid.toString(),
+    source:               0,
+    send_type:            1,
+    sync_group:           1,
+    text:                 body,
+    initiating_source:    1,
+    skip_url_preview_gen: 0,
+    lightweight_action_attached: {
+      messaging_tag: 'fb.messaging.effects.' + effectTag,
+    },
+  };
+
+  if (typeof msgObj === 'object' && msgObj && msgObj.sticker) {
+    sendPayload.send_type  = 2;
+    sendPayload.sticker_id = msgObj.sticker;
+    sendPayload.text       = null;
+  }
+
+  const request_id = ++ctx.wsReqNumber;
+  const content = {
+    app_id:  '2220391788200892',
+    payload: JSON.stringify({
+      tasks: [
+        {
+          label:        '46',
+          payload:      JSON.stringify(sendPayload),
+          queue_name:   tid,
+          task_id:      ++ctx.wsTaskNumber,
+          failure_count: null,
+        },
+        {
+          label:  '21',
+          payload: JSON.stringify({
+            thread_id:             tid,
+            last_read_watermark_ts: timestamp,
+            sync_group:            1,
+          }),
+          queue_name:   tid,
+          task_id:      ++ctx.wsTaskNumber,
+          failure_count: null,
+        },
+      ],
+      epoch_id,
+      version_id:    '6120284488008082',
+      data_trace_id: null,
+    }),
+    request_id,
+    type: 3,
+  };
+
+  return { content, request_id, otid, timestamp };
+}
+
+module.exports = function (defaultFuncs, api, ctx) {
+  /**
+   * Lists all available send effects.
+   * @returns {Array<{tag, label, emoji, aliases}>}
+   */
+  function list() {
+    const seen  = new Set();
+    const result = [];
+    for (const [alias, { tag, label, emoji }] of Object.entries(EFFECTS)) {
+      if (!seen.has(tag)) {
+        seen.add(tag);
+        result.push({
+          tag,
+          label,
+          emoji,
+          aliases: Object.entries(EFFECTS).filter(([, v]) => v.tag === tag).map(([k]) => k),
+        });
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Sends a message with a visual effect animation.
+   *
+   * @param {string}          effectName  Effect alias or tag (e.g. 'fire', 'LOVE', 'confetti')
+   * @param {string|object}   message     Message text or object ({ body, sticker, reply_to_message_id })
+   * @param {string|number}   threadID    Thread / conversation ID
+   * @param {Function}        [callback]  Optional callback(err, { messageID, threadID, effect, timestamp })
+   * @returns {Promise}
+   */
+  async function send(effectName, message, threadID, callback) {
+    let resolveFunc, rejectFunc;
+    const returnPromise = new Promise((resolve, reject) => {
+      resolveFunc = resolve;
+      rejectFunc  = reject;
+    });
+    if (!callback) {
+      callback = (err, data) => { if (err) return rejectFunc(err); resolveFunc(data); };
+    }
+
+    try {
+      if (!effectName) return callback(new Error('effectName is required.'));
+      if (message === undefined || message === null) return callback(new Error('message is required.'));
+      if (!threadID) return callback(new Error('threadID is required.'));
+
+      const effectTag = resolveEffect(effectName);
+      utils.log('sendEffect', `Effect "${effectTag}" → thread ${threadID}`);
+
+      // ── Try HTTP first ───────────────────────────────────────────────────
+      try {
+        const { form, messageAndOTID, timestamp } = buildForm(effectTag, message, threadID, ctx);
+
+        const resData = await defaultFuncs
+          .post('https://www.facebook.com/messaging/send/', ctx.jar, form, { ...ctx, requestThreadID: String(threadID) })
+          .then(utils.parseAndCheckLogin(ctx, defaultFuncs));
+
+        if (!resData) throw new Error('Empty response from messaging/send');
+        if (resData.error) throw new Error(JSON.stringify(resData));
+
+        const actions  = (resData.payload && resData.payload.actions) || [];
+        const msgInfo  = actions.reduce((p, v) => ({
+          threadID:  v.thread_fbid  || p.threadID,
+          messageID: v.message_id   || p.messageID,
+          timestamp: v.timestamp    || p.timestamp,
+        }), { threadID, messageID: messageAndOTID, timestamp });
+
+        return callback(null, { ...msgInfo, effect: effectTag, method: 'http' });
+      } catch (httpErr) {
+        utils.warn('sendEffect', `HTTP failed: ${httpErr.message}. Falling back to MQTT.`);
+      }
+
+      // ── MQTT fallback ────────────────────────────────────────────────────
+      if (!ctx.mqttClient) {
+        throw new Error('MQTT is not connected. Call api.listenMqtt() first.');
+      }
+
+      const { content, request_id, otid, timestamp } = buildMqttPayload(effectTag, message, threadID, ctx);
+
+      await new Promise((res, rej) => {
+        let done    = false;
+        const timer = setTimeout(() => {
+          if (done) return;
+          done = true;
+          ctx.mqttClient.removeListener('message', onMsg);
+          rej(new Error('MQTT effect send timeout'));
+        }, 15000);
+
+        const onMsg = (topic, raw) => {
+          if (topic !== '/ls_resp') return;
+          let parsed;
+          try { parsed = JSON.parse(raw.toString()); parsed.payload = JSON.parse(parsed.payload); } catch { return; }
+          if (parsed.request_id !== request_id) return;
+          if (done) return;
+          done = true;
+          clearTimeout(timer);
+          ctx.mqttClient.removeListener('message', onMsg);
+          callback(null, { threadID, messageID: otid, timestamp, effect: effectTag, method: 'mqtt' });
+          res();
+        };
+
+        ctx.mqttClient.on('message', onMsg);
+        ctx.mqttClient.publish('/ls_req', JSON.stringify(content), { qos: 1, retain: false }, (err) => {
+          if (err && !done) {
+            done = true;
+            clearTimeout(timer);
+            ctx.mqttClient.removeListener('message', onMsg);
+            rej(err);
+          }
+        });
+      });
+
+    } catch (err) {
+      utils.error('sendEffect', err.message || err);
+      callback(err instanceof Error ? err : new Error(String(err.message || err)));
+    }
+
+    return returnPromise;
+  }
+
+  // ── Convenience shortcuts ──────────────────────────────────────────────────
+  const shortcuts = {};
+  const seen = new Set();
+  for (const [alias, { tag }] of Object.entries(EFFECTS)) {
+    if (!seen.has(tag)) {
+      seen.add(tag);
+      const _tag = tag;
+      shortcuts[alias] = (message, threadID, callback) => send(_tag, message, threadID, callback);
+    }
+  }
+
+  return {
+    list,
+    send,
+    effects: EFFECTS,
+    resolveEffect,
+    ...shortcuts,
+  };
+};