fca-phantom 1.0.0

package/phantom/dispatch/getThreadHistory.js

@@ -0,0 +1,139 @@
+"use strict";
+
+const utils = require('../datastore/models/matrix/tools');
+const { formatAttachment: _formatAttachment } = require('../datastore/models/matrix/transform/index');
+
+const HISTORY_CACHE = new Map();
+const CACHE_TTL = 90 * 1000;
+const MAX_FETCH_PER_CALL = 1000;
+
+async function retryOp(fn, retries = 3, base = 700) {
+  for (let i = 0; i < retries; i++) {
+    try { return await fn(); } catch (err) {
+      if (i === retries - 1) throw err;
+      await new Promise(r => setTimeout(r, base * Math.pow(2, i) + Math.random() * 300));
+    }
+  }
+}
+
+function formatAttachmentsGraphQLResponse(attachment) {
+  switch (attachment.__typename) {
+    case "MessageImage":
+      return { type: "photo", ID: attachment.legacy_attachment_id, filename: attachment.filename, thumbnailUrl: attachment.thumbnail?.uri, previewUrl: attachment.preview?.uri, previewWidth: attachment.preview?.width, previewHeight: attachment.preview?.height, largePreviewUrl: attachment.large_preview?.uri, largePreviewHeight: attachment.large_preview?.height, largePreviewWidth: attachment.large_preview?.width, url: attachment.large_preview?.uri, width: attachment.original_dimensions?.x, height: attachment.original_dimensions?.y, name: attachment.filename };
+    case "MessageAnimatedImage":
+      return { type: "animated_image", ID: attachment.legacy_attachment_id, filename: attachment.filename, previewUrl: attachment.preview_image?.uri, previewWidth: attachment.preview_image?.width, previewHeight: attachment.preview_image?.height, url: attachment.animated_image?.uri, width: attachment.animated_image?.width, height: attachment.animated_image?.height, name: attachment.filename };
+    case "MessageVideo":
+      return { type: "video", ID: attachment.legacy_attachment_id, filename: attachment.filename, duration: attachment.playable_duration_in_ms, thumbnailUrl: attachment.large_image?.uri, previewUrl: attachment.large_image?.uri, previewWidth: attachment.large_image?.width, previewHeight: attachment.large_image?.height, url: attachment.playable_url, width: attachment.original_dimensions?.x, height: attachment.original_dimensions?.y, videoType: attachment.video_type?.toLowerCase() };
+    case "MessageFile":
+      return { type: "file", ID: attachment.message_file_fbid, filename: attachment.filename, url: attachment.url, isMalicious: attachment.is_malicious, contentType: attachment.content_type, name: attachment.filename };
+    case "MessageAudio":
+      return { type: "audio", ID: attachment.url_shimhash, filename: attachment.filename, duration: attachment.playable_duration_in_ms, audioType: attachment.audio_type, url: attachment.playable_url, isVoiceMail: attachment.is_voicemail };
+    default:
+      return { type: "unknown", error: "Unknown attachment type " + attachment.__typename };
+  }
+}
+
+function formatExtensibleAttachment(attachment) {
+  if (attachment.story_attachment) {
+    const sa = attachment.story_attachment;
+    return { type: "share", ID: attachment.legacy_attachment_id, url: sa.url, title: sa.title_with_entities?.text, description: sa.description?.text, source: sa.source?.text, image: sa.media?.image?.uri, width: sa.media?.image?.width, height: sa.media?.image?.height, playable: sa.media?.is_playable, duration: sa.media?.playable_duration_in_ms, playableUrl: sa.media?.playable_url, subattachments: sa.subattachments, properties: (sa.properties || []).reduce((obj, cur) => { obj[cur.key] = cur.value?.text; return obj; }, {}) };
+  }
+  return { type: "unknown", error: "Unknown extensible attachment" };
+}
+
+function formatMessagesGraphQLResponse(data) {
+  const messageThread = data.o0?.data?.message_thread;
+  if (!messageThread) return [];
+
+  const threadID = messageThread.thread_key?.thread_fbid || messageThread.thread_key?.other_user_id;
+  const isGroup = messageThread.thread_type === "GROUP";
+
+  return messageThread.messages.nodes.map(d => {
+    switch (d.__typename) {
+      case "UserMessage": {
+        const mentions = {};
+        if (d.message?.ranges) {
+          for (const e of d.message.ranges) {
+            if (e.entity?.id && d.message.text) mentions[e.entity.id] = d.message.text.substring(e.offset, e.offset + e.length);
+          }
+        }
+        const attachments = d.sticker
+          ? [{ type: "sticker", ID: d.sticker.id, url: d.sticker.url, packID: d.sticker.pack?.id, frameCount: d.sticker.frame_count, frameRate: d.sticker.frame_rate }]
+          : (d.blob_attachments || []).map(formatAttachmentsGraphQLResponse).concat(d.extensible_attachment ? [formatExtensibleAttachment(d.extensible_attachment)] : []);
+
+        return { type: "message", attachments, body: d.message?.text || "", isGroup, messageID: d.message_id, senderID: d.message_sender?.id, threadID, timestamp: d.timestamp_precise, mentions, isUnread: d.unread, isUnsent: !!d.is_unsent, messageReactions: (d.message_reactions || []).map(r => ({ reaction: r.reaction, userID: r.user?.id })) };
+      }
+      case "ThreadNameMessage":
+      case "ThreadImageMessage":
+      case "ParticipantLeftMessage":
+      case "ParticipantsAddedMessage":
+      case "GenericAdminTextMessage":
+        return { type: "event", messageID: d.message_id, threadID, isGroup, senderID: d.message_sender?.id, author: d.message_sender?.id, timestamp: d.timestamp_precise, snippet: d.snippet, logMessageType: utils.getAdminTextMessageType(d.extensible_message_admin_text_type || d.__typename), logMessageData: d.extensible_message_admin_text || {} };
+      default:
+        return { type: "unknown", error: "Unknown message type " + d.__typename, raw: d, messageID: d.message_id, threadID, timestamp: d.timestamp_precise };
+    }
+  });
+}
+
+module.exports = (defaultFuncs, api, ctx) => {
+  return async function getThreadHistory(threadID, amount, timestamp, callback) {
+    let resolveFunc, rejectFunc;
+    const returnPromise = new Promise((resolve, reject) => {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+
+    if (typeof timestamp === "function") { callback = timestamp; timestamp = null; }
+    if (typeof callback !== "function") {
+      callback = (err, data) => {
+        if (err) return rejectFunc(err);
+        resolveFunc(data);
+      };
+    }
+
+    try {
+      if (!threadID) throw new Error("getThreadHistory: threadID is required");
+      if (!amount || typeof amount !== "number" || amount <= 0) throw new Error("getThreadHistory: amount must be a positive number");
+
+      amount = Math.min(amount, MAX_FETCH_PER_CALL);
+
+      const cacheKey = `hist_${threadID}_${amount}_${timestamp || "latest"}`;
+      const cached = HISTORY_CACHE.get(cacheKey);
+      if (cached && (Date.now() - cached.ts < CACHE_TTL)) return callback(null, cached.data);
+
+      const form = {
+        av: ctx.globalOptions?.pageID || ctx.userID,
+        queries: JSON.stringify({
+          o0: {
+            doc_id: "1498317363570230",
+            query_params: {
+              id: String(threadID),
+              message_limit: amount,
+              load_messages: 1,
+              load_read_receipts: false,
+              before: timestamp || null
+            }
+          }
+        })
+      };
+
+      const resData = await retryOp(() =>
+        defaultFuncs.post("https://www.facebook.com/api/graphqlbatch/", ctx.jar, form)
+          .then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+      );
+
+      if (resData.error || (Array.isArray(resData) && resData[resData.length - 1].error_results !== 0)) throw resData;
+      if (!Array.isArray(resData) || !resData[0]?.o0?.data) throw { error: "getThreadHistory: malformed response" };
+
+      const messages = formatMessagesGraphQLResponse(resData[0]);
+
+      HISTORY_CACHE.set(cacheKey, { data: messages, ts: Date.now() });
+      callback(null, messages);
+    } catch (err) {
+      utils.error("getThreadHistory", err);
+      callback(err);
+    }
+
+    return returnPromise;
+  };
+};

package/phantom/dispatch/getThreadInfo.js

@@ -0,0 +1,153 @@
+"use strict";
+
+const utils = require('../datastore/models/matrix/tools');
+
+const THREAD_CACHE = new Map();
+const CACHE_TTL = 3 * 60 * 1000;
+
+async function retryOp(fn, retries = 3, base = 700) {
+  for (let i = 0; i < retries; i++) {
+    try { return await fn(); } catch (err) {
+      if (i === retries - 1) throw err;
+      await new Promise(r => setTimeout(r, base * Math.pow(2, i) + Math.random() * 300));
+    }
+  }
+}
+
+function formatEventReminders(reminder) {
+  return {
+    reminderID: reminder.id,
+    eventCreatorID: reminder.lightweight_event_creator?.id,
+    time: reminder.time,
+    eventType: reminder.lightweight_event_type?.toLowerCase(),
+    locationName: reminder.location_name,
+    eventStatus: reminder.lightweight_event_status?.toLowerCase(),
+    note: reminder.note,
+    repeatMode: reminder.repeat_mode?.toLowerCase(),
+    eventTitle: reminder.event_title,
+    members: (reminder.event_reminder_members?.edges || []).map(member => ({ memberID: member.node?.id, state: member.guest_list_state?.toLowerCase() }))
+  };
+}
+
+function formatThreadGraphQLResponse(data) {
+  if (data.errors) {
+    const details = data.errors.map(e => e.message || e).join(", ");
+    throw Object.assign(new Error(`GraphQL error in getThreadInfo: ${details}`), { details, fullErrors: data.errors });
+  }
+
+  const messageThread = data.message_thread;
+  if (!messageThread) throw new Error("No message_thread in GraphQL response");
+
+  const threadID = messageThread.thread_key?.thread_fbid || messageThread.thread_key?.other_user_id;
+
+  return {
+    threadID,
+    threadName: messageThread.name,
+    participantIDs: messageThread.all_participants.edges.map(d => d.node.messaging_actor.id),
+    userInfo: messageThread.all_participants.edges.map(d => {
+      const p = d.node.messaging_actor;
+      return { id: p.id, name: p.name, firstName: p.short_name, vanity: p.username, url: p.url, thumbSrc: p.big_image_src?.uri, profileUrl: p.big_image_src?.uri, gender: p.gender, type: p.__typename, isFriend: p.is_viewer_friend, isBirthday: !!p.is_birthday };
+    }),
+    unreadCount: messageThread.unread_count,
+    messageCount: messageThread.messages_count,
+    timestamp: messageThread.updated_time_precise,
+    muteUntil: messageThread.mute_until,
+    isGroup: messageThread.thread_type === "GROUP",
+    isSubscribed: messageThread.is_viewer_subscribed,
+    isArchived: messageThread.has_viewer_archived,
+    folder: messageThread.folder,
+    cannotReplyReason: messageThread.cannot_reply_reason,
+    eventReminders: messageThread.event_reminders ? messageThread.event_reminders.nodes.map(formatEventReminders) : null,
+    emoji: messageThread.customization_info?.emoji || null,
+    color: messageThread.customization_info?.outgoing_bubble_color ? messageThread.customization_info.outgoing_bubble_color.slice(2) : null,
+    threadTheme: messageThread.thread_theme,
+    nicknames: (messageThread.customization_info?.participant_customizations || []).reduce((res, val) => { if (val.nickname) res[val.participant_id] = val.nickname; return res; }, {}),
+    adminIDs: messageThread.thread_admins || [],
+    approvalMode: Boolean(messageThread.approval_mode),
+    approvalQueue: (messageThread.group_approval_queue?.nodes || []).map(a => ({ inviterID: a.inviter?.id, requesterID: a.requester?.id, timestamp: a.request_timestamp, request_source: a.request_source })),
+    reactionsMuteMode: messageThread.reactions_mute_mode?.toLowerCase() || "all_reactions",
+    mentionsMuteMode: messageThread.mentions_mute_mode?.toLowerCase() || "all_mentions",
+    isPinProtected: messageThread.is_pin_protected,
+    relatedPageThread: messageThread.related_page_thread,
+    name: messageThread.name,
+    snippet: messageThread.last_message?.nodes?.[0]?.snippet || null,
+    snippetSender: messageThread.last_message?.nodes?.[0]?.message_sender?.messaging_actor?.id || null,
+    snippetAttachments: [],
+    serverTimestamp: messageThread.updated_time_precise,
+    imageSrc: messageThread.image?.uri || null,
+    isCanonicalUser: messageThread.is_canonical_neo_user,
+    isCanonical: messageThread.thread_type !== "GROUP",
+    recipientsLoadable: true,
+    hasEmailParticipant: false,
+    readOnly: false,
+    canReply: messageThread.cannot_reply_reason == null,
+    lastMessageTimestamp: messageThread.last_message?.timestamp_precise || null,
+    lastReadTimestamp: messageThread.last_read_receipt?.nodes?.[0]?.timestamp_precise || null,
+    threadType: messageThread.thread_type === "GROUP" ? 2 : 1,
+    inviteLink: { enable: messageThread.joinable_mode?.mode === 1, link: messageThread.joinable_mode?.link || null }
+  };
+}
+
+module.exports = (defaultFuncs, api, ctx) => {
+  return async function getThreadInfo(threadID) {
+    const threadIDs = Array.isArray(threadID) ? threadID : [threadID];
+
+    if (threadIDs.length === 0) throw new Error("getThreadInfo: at least one threadID is required");
+
+    const cachedResults = {};
+    const toFetch = [];
+
+    for (const tid of threadIDs) {
+      const cached = THREAD_CACHE.get(`thread_${tid}`);
+      if (cached && (Date.now() - cached.ts < CACHE_TTL)) {
+        cachedResults[tid] = cached.data;
+      } else {
+        toFetch.push(tid);
+      }
+    }
+
+    if (toFetch.length === 0) {
+      return Array.isArray(threadID) ? cachedResults : Object.values(cachedResults)[0] || null;
+    }
+
+    if (ctx.validator && !ctx.validator.validateIDArray(toFetch, ctx.validator.isValidThreadID)) {
+      throw new Error("Invalid thread ID(s)");
+    }
+
+    const queriesObj = {};
+    toFetch.forEach((t, i) => {
+      queriesObj[`o${i}`] = {
+        doc_id: "3449967031715030",
+        query_params: { id: t, message_limit: 0, load_messages: false, load_read_receipts: false, before: null }
+      };
+    });
+
+    const form = { queries: JSON.stringify(queriesObj), batch_name: "MessengerGraphQLThreadFetcher" };
+
+    const resData = await retryOp(() =>
+      defaultFuncs.post("https://www.facebook.com/api/graphqlbatch/", ctx.jar, form)
+        .then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+    );
+
+    if (resData.error) throw resData;
+
+    const threadInfos = { ...cachedResults };
+    for (let i = resData.length - 2; i >= 0; i--) {
+      const res = resData[i];
+      if (res.error_results) throw Object.assign(new Error(`Facebook error_results for thread query`), { error_count: res.error_results });
+      const oKey = Object.keys(res)[0];
+      const responseData = res[oKey];
+      if (responseData.errors) throw Object.assign(new Error(JSON.stringify(responseData.errors)), { fullErrors: responseData.errors });
+
+      const info = formatThreadGraphQLResponse(responseData.data);
+      if (info) {
+        const tid = info.threadID || toFetch[toFetch.length - 1 - i];
+        threadInfos[tid] = info;
+        THREAD_CACHE.set(`thread_${tid}`, { data: info, ts: Date.now() });
+        if (ctx.cache) ctx.cache.set(`thread_${tid}`, info);
+      }
+    }
+
+    return Array.isArray(threadID) ? threadInfos : Object.values(threadInfos)[0] || null;
+  };
+};

package/phantom/dispatch/getThreadList.js

@@ -0,0 +1,132 @@
+"use strict";
+
+const utils = require('../datastore/models/matrix/tools');
+
+const LIST_CACHE = new Map();
+const CACHE_TTL = 60 * 1000;
+
+async function retryOp(fn, retries = 3, base = 700) {
+  for (let i = 0; i < retries; i++) {
+    try { return await fn(); } catch (err) {
+      if (i === retries - 1) throw err;
+      await new Promise(r => setTimeout(r, base * Math.pow(2, i) + Math.random() * 300));
+    }
+  }
+}
+
+function formatEventReminders(reminder) {
+  return {
+    reminderID: reminder.id,
+    eventCreatorID: reminder.lightweight_event_creator?.id,
+    time: reminder.time,
+    eventType: reminder.lightweight_event_type?.toLowerCase(),
+    eventTitle: reminder.event_title,
+    members: (reminder.event_reminder_members?.edges || []).map(m => ({ memberID: m.node?.id, state: m.guest_list_state?.toLowerCase() }))
+  };
+}
+
+function formatThread(messageThread) {
+  if (!messageThread?.thread_key) return null;
+
+  const threadID = messageThread.thread_key.thread_fbid || messageThread.thread_key.other_user_id;
+
+  return {
+    threadID,
+    threadName: messageThread.name,
+    participantIDs: messageThread.all_participants.edges.map(d => d.node.messaging_actor.id),
+    userInfo: messageThread.all_participants.edges.map(d => {
+      const p = d.node.messaging_actor;
+      return { id: p.id, name: p.name, firstName: p.short_name, vanity: p.username, url: p.url, thumbSrc: p.big_image_src?.uri, profileUrl: p.big_image_src?.uri, gender: p.gender, type: p.__typename, isFriend: p.is_viewer_friend, isBirthday: !!p.is_birthday, isMessengerUser: p.is_messenger_user, isVerified: p.is_verified };
+    }),
+    unreadCount: messageThread.unread_count,
+    messageCount: messageThread.messages_count,
+    timestamp: messageThread.updated_time_precise,
+    muteUntil: messageThread.mute_until,
+    isGroup: messageThread.thread_type === "GROUP",
+    isSubscribed: messageThread.is_viewer_subscribed,
+    isArchived: messageThread.has_viewer_archived,
+    folder: messageThread.folder,
+    cannotReplyReason: messageThread.cannot_reply_reason,
+    eventReminders: messageThread.event_reminders ? messageThread.event_reminders.nodes.map(formatEventReminders) : null,
+    emoji: messageThread.customization_info?.emoji || null,
+    color: messageThread.customization_info?.outgoing_bubble_color ? messageThread.customization_info.outgoing_bubble_color.slice(2) : null,
+    threadTheme: messageThread.thread_theme,
+    nicknames: (messageThread.customization_info?.participant_customizations || []).reduce((res, val) => { if (val.nickname) res[val.participant_id] = val.nickname; return res; }, {}),
+    adminIDs: (messageThread.thread_admins || []).map(a => a.id || a),
+    approvalMode: Boolean(messageThread.approval_mode),
+    approvalQueue: (messageThread.group_approval_queue?.nodes || []).map(a => ({ inviterID: a.inviter?.id, requesterID: a.requester?.id, timestamp: a.request_timestamp })),
+    reactionsMuteMode: messageThread.reactions_mute_mode?.toLowerCase() || "all_reactions",
+    mentionsMuteMode: messageThread.mentions_mute_mode?.toLowerCase() || "all_mentions",
+    isPinProtected: messageThread.is_pin_protected,
+    name: messageThread.name,
+    snippet: messageThread.last_message?.nodes?.[0]?.snippet || null,
+    snippetSender: messageThread.last_message?.nodes?.[0]?.message_sender?.messaging_actor?.id || null,
+    snippetAttachments: [],
+    serverTimestamp: messageThread.updated_time_precise,
+    imageSrc: messageThread.image?.uri || null,
+    isCanonical: messageThread.thread_type !== "GROUP",
+    canReply: messageThread.cannot_reply_reason == null,
+    lastMessageTimestamp: messageThread.last_message?.timestamp_precise || null,
+    lastReadTimestamp: messageThread.last_read_receipt?.nodes?.[0]?.timestamp_precise || null,
+    threadType: messageThread.thread_type === "GROUP" ? 2 : 1,
+    inviteLink: { enable: messageThread.joinable_mode?.mode === 1, link: messageThread.joinable_mode?.link || null }
+  };
+}
+
+const VALID_FOLDERS = new Set(["INBOX", "ARCHIVED", "PENDING", "OTHER", "SPAM", "UNREAD"]);
+
+module.exports = (defaultFuncs, api, ctx) => {
+  return async function getThreadList(limit, timestamp, tags) {
+    if (typeof timestamp === "undefined") timestamp = null;
+    if (typeof tags === "undefined") tags = ["INBOX"];
+    if (typeof tags === "string") tags = [tags];
+
+    if (!Number.isInteger(limit) || limit <= 0) throw new Error("getThreadList: limit must be a positive integer");
+    if (timestamp !== null && !Number.isInteger(timestamp)) throw new Error("getThreadList: timestamp must be integer or null");
+    if (!Array.isArray(tags)) throw new Error("getThreadList: tags must be an array");
+
+    const normalizedTags = tags.map(t => t.toUpperCase()).filter(t => VALID_FOLDERS.has(t));
+    if (normalizedTags.length === 0) throw new Error(`getThreadList: invalid tags. Valid values: ${[...VALID_FOLDERS].join(", ")}`);
+
+    const cacheKey = `threadlist_${limit}_${timestamp}_${normalizedTags.join(",")}`;
+    const cached = LIST_CACHE.get(cacheKey);
+    if (cached && (Date.now() - cached.ts < CACHE_TTL)) return cached.data;
+
+    const form = {
+      av: ctx.i_userID || ctx.userID,
+      queries: JSON.stringify({
+        o0: {
+          doc_id: "3336396659757871",
+          query_params: {
+            limit: limit + (timestamp ? 1 : 0),
+            before: timestamp,
+            tags: normalizedTags,
+            includeDeliveryReceipts: true,
+            includeSeqID: false
+          }
+        }
+      }),
+      batch_name: "MessengerGraphQLThreadlistFetcher"
+    };
+
+    const resData = await retryOp(() =>
+      defaultFuncs.post("https://www.facebook.com/api/graphqlbatch/", ctx.jar, form)
+        .then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+    );
+
+    if (!Array.isArray(resData) || !resData.length) throw new Error("getThreadList: invalid server response");
+
+    const lastResult = resData[resData.length - 1];
+    if (lastResult.error_results > 0) throw new Error(JSON.stringify(resData[0]?.o0?.errors || "Unknown error"));
+    if (lastResult.successful_results === 0) throw new Error("getThreadList: no successful results");
+    if (!resData[0]?.o0?.data) throw new Error("getThreadList: invalid data structure");
+
+    let nodes = resData[0].o0.data.viewer.message_threads.nodes;
+    if (timestamp) nodes = nodes.slice(1);
+
+    const result = nodes.map(formatThread).filter(Boolean);
+
+    LIST_CACHE.set(cacheKey, { data: result, ts: Date.now() });
+    return result;
+  };
+};

package/phantom/dispatch/getThreadPictures.js

@@ -0,0 +1,93 @@
+"use strict";
+
+const utils = require('../datastore/models/matrix/tools');
+
+const PIC_CACHE = new Map();
+const CACHE_TTL = 5 * 60 * 1000;
+
+async function retryOp(fn, retries = 3, base = 600) {
+  for (let i = 0; i < retries; i++) {
+    try { return await fn(); } catch (err) {
+      if (i === retries - 1) throw err;
+      await new Promise(r => setTimeout(r, base * Math.pow(2, i) + Math.random() * 200));
+    }
+  }
+}
+
+async function fetchViaGraphQL(defaultFuncs, ctx, threadID, offset, limit) {
+  const form = {
+    fb_api_caller_class: "RelayModern",
+    fb_api_req_friendly_name: "MessengerThreadSharedMediaQuery",
+    doc_id: "4629398273799357",
+    variables: JSON.stringify({
+      threadID: String(threadID),
+      first: limit,
+      after: offset > 0 ? String(offset) : null,
+      mediaTypes: ["photo", "video"]
+    })
+  };
+  const res = await defaultFuncs.post("https://www.facebook.com/api/graphql/", ctx.jar, form)
+    .then(utils.parseAndCheckLogin(ctx, defaultFuncs));
+  if (res.errors) throw new Error(JSON.stringify(res.errors));
+  return res.data?.message_thread?.shared_media?.edges?.map(e => ({
+    imageID: e.node?.id,
+    url: e.node?.image?.uri,
+    thumbnailUrl: e.node?.image?.uri,
+    width: e.node?.image?.width,
+    height: e.node?.image?.height,
+    messageID: e.node?.message_id,
+    timestamp: e.node?.timestamp_precise
+  })) || [];
+}
+
+module.exports = (defaultFuncs, api, ctx) => {
+  return async function getThreadPictures(threadID, offset, limit, callback) {
+    let resolveFunc, rejectFunc;
+    const returnPromise = new Promise((resolve, reject) => {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+
+    if (typeof limit === "function") { callback = limit; limit = 50; }
+    else if (typeof offset === "function") { callback = offset; offset = 0; limit = 50; }
+    if (typeof callback !== "function") {
+      callback = (err, result) => {
+        if (err) return rejectFunc(err);
+        resolveFunc(result);
+      };
+    }
+
+    offset = typeof offset === "number" ? offset : 0;
+    limit = typeof limit === "number" ? Math.min(limit, 200) : 50;
+
+    try {
+      if (!threadID) throw new Error("getThreadPictures: threadID is required");
+
+      const cacheKey = `pics_${threadID}_${offset}_${limit}`;
+      const cached = PIC_CACHE.get(cacheKey);
+      if (cached && (Date.now() - cached.ts < CACHE_TTL)) return callback(null, cached.data);
+
+      let result;
+      try {
+        const form = { thread_id: String(threadID), offset, limit };
+        const res = await retryOp(() =>
+          defaultFuncs.post("https://www.facebook.com/ajax/mercury/thread_images.php", ctx.jar, form)
+            .then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+        );
+        if (res?.error) throw res;
+        result = res?.payload || res;
+      } catch (legacyErr) {
+        utils.warn("getThreadPictures", "Legacy API failed, trying GraphQL:", legacyErr.message || legacyErr.error);
+        result = await retryOp(() => fetchViaGraphQL(defaultFuncs, ctx, threadID, offset, limit));
+      }
+
+      PIC_CACHE.set(cacheKey, { data: result, ts: Date.now() });
+      callback(null, result);
+    } catch (err) {
+      utils.error("getThreadPictures", err);
+      callback(err);
+    }
+
+    return returnPromise;
+  };
+};

package/phantom/dispatch/getUserID.js

@@ -0,0 +1,147 @@
+"use strict";
+
+const utils = require('../datastore/models/matrix/tools');
+
+const UID_CACHE = new Map();
+const CACHE_TTL = 10 * 60 * 1000;
+
+async function retryOp(fn, retries = 3, base = 600) {
+  for (let i = 0; i < retries; i++) {
+    try { return await fn(); } catch (err) {
+      if (i === retries - 1) throw err;
+      await new Promise(r => setTimeout(r, base * Math.pow(2, i) + Math.random() * 200));
+    }
+  }
+}
+
+function formatData(data) {
+  return {
+    userID: utils.formatID(String(data.uid)),
+    photoUrl: data.photo,
+    indexRank: data.index_rank,
+    name: data.text,
+    isVerified: !!data.is_verified,
+    profileUrl: data.path,
+    category: data.category,
+    score: data.score,
+    type: data.type
+  };
+}
+
+function extractIDFromUrl(url) {
+  if (!url) return null;
+
+  const profileMatch = url.match(/profile\.php\?id=(\d+)/);
+  if (profileMatch) return profileMatch[1];
+
+  const fbidMatch = url.match(/[?&]fbid=(\d+)/);
+  if (fbidMatch) return fbidMatch[1];
+
+  const idMatch = url.match(/\/(\d{10,})/);
+  if (idMatch) return idMatch[1];
+
+  return null;
+}
+
+async function resolveVanityURL(defaultFuncs, ctx, url) {
+  const cleanUrl = url.replace(/\?.*$/, "").replace(/\/$/, "");
+
+  try {
+    const res = await retryOp(() => defaultFuncs.get(cleanUrl, ctx.jar));
+    const html = res.body || (typeof res === "string" ? res : "");
+
+    const patterns = [
+      /"userID":"(\d+)"/,
+      /"USER_ID":"(\d+)"/,
+      /"id":"(\d+)"/,
+      /entity_id[":\s]+(\d+)/,
+      /profile_id=(\d+)/,
+      /"actorID":"(\d+)"/,
+      /"ownerID":"(\d+)"/
+    ];
+
+    for (const pattern of patterns) {
+      const match = html.match(pattern);
+      if (match && /^\d{8,}$/.test(match[1])) return match[1];
+    }
+
+    const extracted = extractIDFromUrl(url);
+    if (extracted) return extracted;
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = (defaultFuncs, api, ctx) => {
+  return async function getUID(link, callback) {
+    let resolveFunc, rejectFunc;
+    const returnPromise = new Promise((resolve, reject) => {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+
+    if (typeof callback !== "function") {
+      callback = (err, result) => {
+        if (err) return rejectFunc(err);
+        resolveFunc(result);
+      };
+    }
+
+    try {
+      if (!link || typeof link !== "string") throw { error: "getUserID: link must be a non-empty string" };
+
+      const cacheKey = `uid_${link.trim().toLowerCase()}`;
+      const cached = UID_CACHE.get(cacheKey);
+      if (cached && (Date.now() - cached.ts < CACHE_TTL)) return callback(null, cached.data);
+
+      const isURL = link.includes(".com") || link.startsWith("http");
+
+      if (isURL) {
+        let uid = extractIDFromUrl(link);
+
+        if (!uid) {
+          uid = await resolveVanityURL(defaultFuncs, ctx, link);
+        }
+
+        if (!uid || !/^\d+$/.test(uid)) throw new Error("getUserID: could not extract user ID from URL");
+
+        UID_CACHE.set(cacheKey, { data: uid, ts: Date.now() });
+        return callback(null, uid);
+      }
+
+      const form = {
+        value: link.toLowerCase().trim(),
+        viewer: ctx.userID,
+        rsp: "search",
+        context: "search",
+        path: "/home.php",
+        request_id: ctx.clientID || utils.getGUID()
+      };
+
+      const res = await retryOp(() =>
+        defaultFuncs.get("https://www.facebook.com/ajax/typeahead/search.php", ctx.jar, form)
+          .then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+      );
+
+      if (res.error) throw res;
+
+      if (!res.payload?.entries) {
+        throw {
+          error: "getUserID: no results found. Account may require checkpoint verification.",
+          details: "Visit facebook.com to verify your account."
+        };
+      }
+
+      const data = res.payload.entries.map(formatData);
+      UID_CACHE.set(cacheKey, { data, ts: Date.now() });
+      callback(null, data);
+    } catch (err) {
+      utils.error("getUserID", err);
+      callback(err);
+    }
+
+    return returnPromise;
+  };
+};