fca-phantom 1.0.0

package/phantom/dispatch/getFriendsList.js

@@ -0,0 +1,118 @@
+"use strict";
+
+const utils = require('../datastore/models/matrix/tools');
+
+const FRIENDS_CACHE = new Map();
+const CACHE_TTL = 5 * 60 * 1000;
+
+const GENDERS = {
+  0: "unknown", 1: "female_singular", 2: "male_singular",
+  3: "female_singular_guess", 4: "male_singular_guess",
+  5: "mixed", 6: "neuter_singular", 7: "unknown_singular",
+  8: "female_plural", 9: "male_plural", 10: "neuter_plural",
+  11: "unknown_plural"
+};
+
+function formatData(obj) {
+  return Object.keys(obj).map(key => {
+    const user = obj[key];
+    return {
+      alternateName: user.alternateName || null,
+      firstName: user.firstName || null,
+      gender: GENDERS[user.gender] || "unknown",
+      userID: utils.formatID(String(user.id)),
+      isFriend: user.is_friend != null ? !!user.is_friend : false,
+      fullName: user.name || null,
+      profilePicture: user.thumbSrc || null,
+      type: user.type || null,
+      profileUrl: user.uri || null,
+      vanity: user.vanity || null,
+      isBirthday: !!user.is_birthday
+    };
+  });
+}
+
+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));
+    }
+  }
+}
+
+async function fetchViaGraphQL(defaultFuncs, ctx) {
+  const form = {
+    fb_api_caller_class: "RelayModern",
+    fb_api_req_friendly_name: "FriendingCometFriendListQuery",
+    doc_id: "28046706820346836",
+    variables: JSON.stringify({ count: 1000, cursor: null, scale: 2 })
+  };
+  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));
+  const edges = res.data?.viewer?.all_friends?.edges || [];
+  return edges.map(edge => ({
+    userID: edge.node?.id,
+    fullName: edge.node?.name,
+    profilePicture: edge.node?.profile_picture?.uri,
+    profileUrl: edge.node?.url,
+    alternateName: null,
+    firstName: edge.node?.short_name || null,
+    gender: "unknown",
+    isFriend: true,
+    type: "friend",
+    vanity: null,
+    isBirthday: false
+  }));
+}
+
+module.exports = (defaultFuncs, api, ctx) => {
+  return async function getFriendsList(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 {
+      const cacheKey = `friendslist_${ctx.userID}`;
+      const cached = FRIENDS_CACHE.get(cacheKey);
+      if (cached && (Date.now() - cached.ts < CACHE_TTL)) {
+        return callback(null, cached.data);
+      }
+
+      let result;
+
+      try {
+        const res = await retryOp(() =>
+          defaultFuncs.postFormData(
+            "https://www.facebook.com/chat/user_info_all",
+            ctx.jar, {},
+            { viewer: ctx.userID }
+          ).then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+        );
+        if (!res || res.error) throw res || new Error("Empty response");
+        result = formatData(res.payload);
+      } catch (legacyErr) {
+        utils.warn("getFriendsList", "Legacy API failed, trying GraphQL:", legacyErr.message || legacyErr.error);
+        result = await retryOp(() => fetchViaGraphQL(defaultFuncs, ctx));
+      }
+
+      FRIENDS_CACHE.set(cacheKey, { data: result, ts: Date.now() });
+      callback(null, result);
+    } catch (err) {
+      utils.error("getFriendsList", err);
+      callback(err);
+    }
+
+    return returnPromise;
+  };
+};

package/phantom/dispatch/getMessage.js

@@ -0,0 +1,199 @@
+"use strict";
+
+const utils = require('../datastore/models/matrix/tools');
+const { formatAttachment: _formatAttachment } = require('../datastore/models/matrix/transform/index');
+
+const MSG_CACHE = new Map();
+const CACHE_TTL = 3 * 60 * 1000;
+
+const THEME_COLORS = [
+  { theme_color: "FF000000", theme_id: "788274591712841", theme_name_with_subtitle: "Monochrome" },
+  { theme_color: "FF0084FF", theme_id: "196241301102133", theme_name_with_subtitle: "Default Blue" },
+  { theme_color: "FFFF5CA1", theme_id: "169463077092846", theme_name_with_subtitle: "Hot Pink" },
+  { theme_color: "FF2825B5", theme_id: "271607034185782", theme_name_with_subtitle: "Shadow" },
+  { theme_color: "FF7646FF", theme_id: "234137870477637", theme_name_with_subtitle: "Bright Purple" },
+  { theme_color: "FF44BEC7", theme_id: "1928399724138152", theme_name_with_subtitle: "Teal Blue" },
+  { theme_color: "FFFE5F03", theme_id: "175615189761153", theme_name_with_subtitle: "Orange" },
+  { theme_color: "FF13CF13", theme_id: "2136751179887052", theme_name_with_subtitle: "Green" },
+  { theme_color: "FFFA3C4C", theme_id: "2129984390566328", theme_name_with_subtitle: "Red" },
+  { theme_color: "FFF25C54", theme_id: "3022526817824329", theme_name_with_subtitle: "Peach" },
+  { theme_color: "FFF01D6A", theme_id: "724096885023603", theme_name_with_subtitle: "Berry" },
+  { theme_color: "FFFF7CA8", theme_id: "624266884847972", theme_name_with_subtitle: "Candy" }
+];
+
+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() * 250));
+    }
+  }
+}
+
+function formatMessage(threadID, data) {
+  const baseMessage = {
+    threadID,
+    messageID: data.message_id,
+    timestamp: data.timestamp_precise,
+    author: data.message_sender ? data.message_sender.id : null
+  };
+
+  switch (data.__typename) {
+    case "ThreadNameMessage":
+      return { ...baseMessage, type: "event", logMessageType: "log:thread-name", logMessageData: { name: data.thread_name }, logMessageBody: data.snippet };
+
+    case "ThreadImageMessage":
+      const meta = data.image_with_metadata;
+      return { ...baseMessage, type: "event", logMessageType: "log:thread-image", logMessageData: meta ? { attachmentID: meta.legacy_attachment_id, width: meta.original_dimensions?.x, height: meta.original_dimensions?.y, url: meta.preview?.uri } : null, logMessageBody: data.snippet };
+
+    case "GenericAdminTextMessage": {
+      const adminType = data.extensible_message_admin_text_type;
+      const adminText = data.extensible_message_admin_text;
+
+      const adminTypeMap = {
+        CHANGE_THREAD_THEME: () => {
+          const colorMatch = THEME_COLORS.find(c => c.theme_color === adminText?.theme_color);
+          return { logMessageType: "log:thread-color", logMessageData: colorMatch || { theme_color: adminText?.theme_color } };
+        },
+        CHANGE_THREAD_ICON: () => {
+          const icon = adminText?.thread_icon;
+          let iconUrl = null;
+          if (icon) {
+            try { iconUrl = `https://static.xx.fbcdn.net/images/emoji.php/v9/t3c/1/16/${icon.codePointAt(0).toString(16)}.png`; } catch {}
+          }
+          return { logMessageType: "log:thread-icon", logMessageData: { thread_icon: icon || null, thread_icon_url: iconUrl } };
+        },
+        CHANGE_THREAD_NICKNAME: () => ({ logMessageType: "log:user-nickname", logMessageData: { nickname: adminText?.nickname, participant_id: adminText?.participant_id } }),
+        GROUP_POLL: () => {
+          const q = adminText?.question;
+          if (!q) return { logMessageType: "log:thread-poll", logMessageData: { error: "Missing poll question data" } };
+          return { logMessageType: "log:thread-poll", logMessageData: { question_json: JSON.stringify({ id: q.id, text: q.text, options: (q.options?.nodes || []).map(o => ({ id: o.id, text: o.text, voters: (o.voters?.nodes || []).map(v => v.id) })) }), event_type: (adminText.event_type || "").toLowerCase(), question_id: q.id } };
+        },
+        CHANGE_THREAD_QUICK_REACTION: () => ({ logMessageType: "log:thread-icon", logMessageData: { thread_quick_reaction: adminText?.thread_quick_reaction } }),
+        CHANGE_THREAD_ADMINS: () => ({ logMessageType: "log:thread-admins", logMessageData: { admin_type: adminText?.admin_type, target_id: adminText?.target_id } }),
+        CHANGE_THREAD_APPROVAL_MODE: () => ({ logMessageType: "log:thread-approval-mode", logMessageData: { approval_mode: adminText?.approval_mode } }),
+        PIN_MESSAGES_V2: () => ({ logMessageType: "log:thread-pinned", logMessageData: { pinned_message_id: adminText?.pinned_message_id } }),
+        UNPIN_MESSAGES_V2: () => ({ logMessageType: "log:unpin-message", logMessageData: { unpinned_message_id: adminText?.unpinned_message_id } }),
+        JOINABLE_GROUP_LINK_MODE_CHANGE: () => ({ logMessageType: "log:link-status", logMessageData: { link_status: adminText?.joinable_mode } }),
+        MAGIC_WORDS: () => ({ logMessageType: "log:magic-words", logMessageData: { magic_word: adminText?.magic_word } }),
+        MESSENGER_CALL_LOG: () => ({ logMessageType: "log:thread-call", logMessageData: { event_type: adminType, call_duration: adminText?.call_duration || 0 } }),
+        PARTICIPANT_JOINED_GROUP_CALL: () => ({ logMessageType: "log:thread-call", logMessageData: { event_type: adminType, call_duration: adminText?.call_duration || 0 } })
+      };
+
+      const handler = adminTypeMap[adminType];
+      const extra = handler ? handler() : { logMessageType: "log:generic-admin", logMessageData: { admin_type: adminType } };
+      return { ...baseMessage, type: "event", ...extra, logMessageBody: data.snippet };
+    }
+
+    case "UserMessage": {
+      const attachments = [];
+      if (data.blob_attachments?.length) {
+        for (const att of data.blob_attachments) {
+          try { attachments.push(_formatAttachment(att)); } catch (ex) { attachments.push({ type: "unknown", error: ex.message, rawAttachment: att }); }
+        }
+      } else if (data.extensible_attachment && Object.keys(data.extensible_attachment).length) {
+        try {
+          attachments.push(_formatAttachment({ extensible_attachment: data.extensible_attachment }));
+        } catch (ex) {
+          const sa = data.extensible_attachment.story_attachment || {};
+          attachments.push({ type: "share", ID: data.extensible_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, playable: sa.media?.is_playable || false });
+        }
+      }
+
+      const mentions = {};
+      if (data.message?.ranges) {
+        for (const mention of data.message.ranges) {
+          if (mention.entity?.id && data.message.text) {
+            mentions[mention.entity.id] = data.message.text.substring(mention.offset, mention.offset + mention.length);
+          }
+        }
+      }
+
+      return {
+        type: "message",
+        senderID: data.message_sender?.id || null,
+        body: data.message?.text || "",
+        threadID,
+        messageID: data.message_id,
+        reactions: (data.message_reactions || []).map(r => ({ [r.user.id]: r.reaction })),
+        attachments,
+        mentions,
+        timestamp: data.timestamp_precise,
+        isUnsent: !!data.is_unsent
+      };
+    }
+
+    default:
+      return { ...baseMessage, type: "unknown", data };
+  }
+}
+
+function parseDelta(threadID, delta) {
+  if (delta.replied_to_message) {
+    return { type: "message_reply", ...formatMessage(threadID, delta), messageReply: formatMessage(threadID, delta.replied_to_message.message) };
+  }
+  return formatMessage(threadID, delta);
+}
+
+module.exports = (defaultFuncs, api, ctx) => {
+  return function getMessage(threadID, messageID, callback) {
+    let resolveFunc, rejectFunc;
+    const returnPromise = new Promise((resolve, reject) => {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+
+    if (typeof callback !== "function") {
+      callback = (err, info) => {
+        if (err) return rejectFunc(err);
+        resolveFunc(info);
+      };
+    }
+
+    if (!threadID || !messageID) {
+      callback({ error: "getMessage: threadID and messageID are required" });
+      return returnPromise;
+    }
+
+    const cacheKey = `msg_${threadID}_${messageID}`;
+    const cached = MSG_CACHE.get(cacheKey);
+    if (cached && (Date.now() - cached.ts < CACHE_TTL)) {
+      callback(null, cached.data);
+      return returnPromise;
+    }
+
+    const form = {
+      av: ctx.userID,
+      fb_dtsg: ctx.fb_dtsg,
+      queries: JSON.stringify({
+        o0: {
+          doc_id: "1768656253222505",
+          query_params: {
+            thread_and_message_id: { thread_id: String(threadID), message_id: String(messageID) }
+          }
+        }
+      })
+    };
+
+    retryOp(() =>
+      defaultFuncs.post("https://www.facebook.com/api/graphqlbatch/", ctx.jar, form)
+        .then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+    ).then(resData => {
+      if (!resData || !resData.length) throw { error: "getMessage: no response data" };
+      if (resData[resData.length - 1].error_results > 0) throw resData[0].o0.errors;
+      if (resData[resData.length - 1].successful_results === 0) throw { error: "getMessage: no successful results" };
+
+      const fetchData = resData[0].o0.data.message;
+      if (!fetchData) throw { error: "getMessage: message not found" };
+
+      const result = parseDelta(String(threadID), fetchData);
+      MSG_CACHE.set(cacheKey, { data: result, ts: Date.now() });
+      callback(null, result);
+    }).catch(err => {
+      utils.error("getMessage", err);
+      callback(err);
+    });
+
+    return returnPromise;
+  };
+};

package/phantom/dispatch/getTheme.js

@@ -0,0 +1,199 @@
+"use strict";
+
+/**
+ * getTheme — Advanced Thread Theme Catalogue Fetcher for Phantom SDK
+ *
+ * Features:
+ *  - Fetches full catalogue of available Messenger themes for a thread
+ *  - Parallel detailed metadata resolution for all themes via fetchThemeData
+ *  - In-memory catalogue cache (8-minute TTL)
+ *  - Rich normalisation: gradients, images, dark-mode flag, accessibility score
+ *  - Search helpers: findByName(), findByColor(), findByID()
+ *  - Full callback + Promise dual API
+ */
+
+const utils = require('../datastore/models/matrix/tools');
+
+const _catalogueCache = new Map();
+const CACHE_TTL       = 8 * 60 * 1000; // 8 minutes
+
+function parseGradient(raw) {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw;
+  if (typeof raw === 'string') { try { return JSON.parse(raw); } catch { return [raw]; } }
+  return [];
+}
+
+function hexToRgb(hex) {
+  if (!hex) return null;
+  const c = hex.replace(/^#/, '').replace(/^[Ff]{2}/, '');
+  if (c.length !== 6) return null;
+  return { r: parseInt(c.slice(0, 2), 16), g: parseInt(c.slice(2, 4), 16), b: parseInt(c.slice(4, 6), 16) };
+}
+function lum({ r, g, b }) {
+  const f = v => { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); };
+  return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b);
+}
+function isDark(hex) { const r = hexToRgb(hex); return r ? lum(r) < 0.179 : null; }
+
+function normalizeThemeEntry(raw) {
+  if (!raw || !raw.id) return null;
+  const gradients = parseGradient(raw.gradient_colors || raw.gradientColors);
+  const bg        = raw.background_asset?.image?.uri || raw.backgroundImage || null;
+  const primary   = gradients[0] || raw.fallback_color || raw.fallbackColor || null;
+
+  return {
+    id:                         raw.id,
+    name:                       raw.accessibility_label || raw.name || '',
+    description:                raw.description || null,
+
+    // Colors
+    primary_color:              primary,
+    fallback_color:             raw.fallback_color || raw.fallbackColor || null,
+    gradient_colors:            gradients,
+    background_gradient_colors: parseGradient(raw.background_gradient_colors || raw.backgroundGradientColors),
+    inbound_message_gradient_colors: parseGradient(raw.inbound_message_gradient_colors || raw.inboundMessageGradientColors),
+    message_text_color:         raw.message_text_color || raw.messageTextColor || null,
+    inbound_message_text_color: raw.inbound_message_text_color || raw.inboundMessageTextColor || null,
+    title_bar_text_color:       raw.title_bar_text_color || raw.titleBarTextColor || null,
+    title_bar_button_tint_color: raw.title_bar_button_tint_color || raw.titleBarButtonTintColor || null,
+    title_bar_background_color: raw.title_bar_background_color || raw.titleBarBackgroundColor || null,
+    title_bar_attribution_color: raw.title_bar_attribution_color || raw.titleBarAttributionColor || null,
+    composer_background_color:  raw.composer_background_color || raw.composerBackgroundColor || null,
+    composer_input_background_color: raw.composer_input_background_color || raw.composerInputBackgroundColor || null,
+    composer_tint_color:        raw.composer_tint_color || raw.composerTintColor || null,
+    primary_button_background_color: raw.primary_button_background_color || raw.primaryButtonBackgroundColor || null,
+    reaction_pill_background_color: raw.reaction_pill_background_color || raw.reactionPillBackgroundColor || null,
+    secondary_text_color:       raw.secondary_text_color || raw.secondaryTextColor || null,
+    tertiary_text_color:        raw.tertiary_text_color || raw.tertiaryTextColor || null,
+    hot_like_color:             raw.hot_like_color || raw.hotLikeColor || null,
+    app_color_mode:             raw.app_color_mode || raw.appColorMode || null,
+    normal_theme_id:            raw.normal_theme_id || raw.normalThemeId || null,
+    theme_idx:                  raw.theme_idx,
+
+    // Images
+    backgroundImage: bg,
+    iconImage:       raw.icon_asset?.image?.uri || raw.iconAsset || null,
+    background_asset: raw.background_asset || null,
+    icon_asset:      raw.icon_asset || null,
+
+    // Derived
+    is_dark: isDark(primary),
+  };
+}
+
+module.exports = function (defaultFuncs, api, ctx) {
+
+  /**
+   * Fetch the full theme catalogue for a Messenger thread.
+   *
+   * @param {string}   threadID  Target thread ID
+   * @param {object}  [options]
+   *   @param {boolean} [options.resolveDetails=true]  Fetch full metadata for each theme in parallel
+   *   @param {boolean} [options.useCache=true]         Use catalogue cache
+   *   @param {string}  [options.search]                If set, return only themes matching this string
+   *   @param {string}  [options.searchColor]           If set, return only themes whose gradient starts with this color
+   * @param {Function} [callback]  Node-style (err, themes[]) callback
+   * @returns {Promise<Array>}     Fully normalised theme catalogue
+   */
+  return async function getTheme(threadID, options, callback) {
+    if (typeof options === 'function') { callback = options; options = {}; }
+    options = options || {};
+
+    if (!threadID) {
+      const err = new Error("getTheme: threadID is required");
+      if (callback) return callback(err);
+      throw err;
+    }
+
+    let resolveFunc, rejectFunc;
+    const promise = new Promise((res, rej) => { resolveFunc = res; rejectFunc = rej; });
+
+    function done(err, data) {
+      if (callback) return err ? callback(err) : callback(null, data);
+      if (err) rejectFunc(err); else resolveFunc(data);
+    }
+
+    // Cache
+    const cacheKey = `catalogue::${threadID}`;
+    if (options.useCache !== false) {
+      const hit = _catalogueCache.get(cacheKey);
+      if (hit && Date.now() - hit.ts < CACHE_TTL) {
+        utils.log("getTheme", `Cache hit for thread ${threadID}`);
+        const data = applyFilters(hit.data, options);
+        done(null, data);
+        return promise;
+      }
+    }
+
+    const form = {
+      av:                         ctx.userID,
+      __user:                     ctx.userID,
+      fb_dtsg:                    ctx.fb_dtsg,
+      lsd:                        ctx.lsd || ctx.fb_dtsg,
+      fb_api_caller_class:        'RelayModern',
+      fb_api_req_friendly_name:   'MWPThreadThemeQuery_AllThemesQuery',
+      variables:                  JSON.stringify({ version: "default" }),
+      server_timestamps:          true,
+      doc_id:                     '24474714052117636',
+    };
+
+    try {
+      const resData = await defaultFuncs
+        .post("https://www.facebook.com/api/graphql/", ctx.jar, form, null, {
+          "x-fb-friendly-name": "MWPThreadThemeQuery_AllThemesQuery",
+          "x-fb-lsd":           ctx.lsd,
+          "referer":            `https://www.facebook.com/messages/t/${threadID}`,
+        })
+        .then(utils.parseAndCheckLogin(ctx, defaultFuncs));
+
+      if (resData.errors) throw new Error(JSON.stringify(resData.errors));
+      if (!resData.data?.messenger_thread_themes) throw new Error("getTheme: No theme data in response");
+
+      const rawList = resData.data.messenger_thread_themes;
+      const baseThemes = rawList.map(normalizeThemeEntry).filter(Boolean);
+
+      let themes = baseThemes;
+
+      // Parallel detail resolution
+      if (options.resolveDetails !== false && api.fetchThemeData) {
+        themes = await Promise.all(
+          baseThemes.map(async base => {
+            try {
+              const detail = await api.fetchThemeData(base.id, { useCache: true });
+              return { ...base, ...detail };
+            } catch {
+              return base;
+            }
+          })
+        );
+      }
+
+      // Cache
+      if (options.useCache !== false) {
+        _catalogueCache.set(cacheKey, { data: themes, ts: Date.now() });
+      }
+
+      utils.log("getTheme", `Loaded ${themes.length} theme(s) for thread ${threadID}`);
+      done(null, applyFilters(themes, options));
+    } catch (err) {
+      utils.error("getTheme", err.message || err);
+      done(err);
+    }
+
+    return promise;
+  };
+
+  function applyFilters(themes, options) {
+    let out = themes;
+    if (options.search) {
+      const q = options.search.toLowerCase();
+      out = out.filter(t => (t.name || '').toLowerCase().includes(q) || (t.description || '').toLowerCase().includes(q));
+    }
+    if (options.searchColor) {
+      const col = options.searchColor.toLowerCase().replace(/^#/, '');
+      out = out.filter(t => (t.gradient_colors || []).some(c => c.toLowerCase().includes(col)));
+    }
+    return out;
+  }
+};

package/phantom/dispatch/getThemeInfo.js

@@ -0,0 +1,160 @@
+"use strict";
+
+/**
+ * getThemeInfo — Advanced Thread / Theme Info Fetcher for Phantom SDK
+ *
+ * Resolves either a theme ID or a thread ID:
+ *  - Theme ID → calls fetchThemeData for full theme metadata
+ *  - Thread ID → calls getThreadInfo + optionally getTheme for active theme details
+ *
+ * Features:
+ *  - Smart ID detection (theme vs thread)
+ *  - Combined thread + active-theme metadata
+ *  - In-memory cache (6-minute TTL)
+ *  - Graceful degradation with sensible defaults on partial failures
+ *  - Full callback + Promise dual API
+ */
+
+const utils = require('../datastore/models/matrix/tools');
+
+const _cache    = new Map();
+const CACHE_TTL = 6 * 60 * 1000; // 6 minutes
+
+const THEME_ID_RE  = /^\d{10,}$/;
+const THREAD_ID_RE = /^\d{7,}$/;
+
+function defaultThemeInfo(identifier, extras) {
+  return Object.assign({
+    threadID:       identifier,
+    threadName:     '',
+    participantCount: 0,
+    isGroup:        null,
+    color:          null,
+    emoji:          '👍',
+    theme_id:       null,
+    theme_color:    null,
+    gradient_colors: null,
+    backgroundImage: null,
+    is_dark:        null,
+    is_default:     true,
+  }, extras || {});
+}
+
+module.exports = function (defaultFuncs, api, ctx) {
+
+  /**
+   * Get combined theme + thread info for a thread ID, or full theme data for a theme ID.
+   *
+   * @param {string}   identifier  Thread ID or Theme ID
+   * @param {object}  [options]
+   *   @param {boolean} [options.useCache=true]        Use 6-minute cache
+   *   @param {boolean} [options.fetchActiveTheme=true] Also resolve active theme details when threadID is given
+   * @param {Function} [callback]  Node-style (err, info) callback
+   * @returns {Promise<object>}    Resolved info object
+   */
+  return async function getThemeInfo(identifier, options, callback) {
+    if (typeof options === 'function') { callback = options; options = {}; }
+    options = options || {};
+
+    if (!identifier) {
+      const err = new Error("getThemeInfo: identifier is required (threadID or themeID)");
+      if (callback) return callback(err);
+      throw err;
+    }
+
+    let resolveFunc, rejectFunc;
+    const promise = new Promise((res, rej) => { resolveFunc = res; rejectFunc = rej; });
+
+    function done(err, data) {
+      if (callback) return err ? callback(err) : callback(null, data);
+      if (err) rejectFunc(err); else resolveFunc(data);
+    }
+
+    const id       = identifier.toString().trim();
+    const cacheKey = `themeinfo::${id}`;
+
+    if (options.useCache !== false) {
+      const hit = _cache.get(cacheKey);
+      if (hit && Date.now() - hit.ts < CACHE_TTL) {
+        done(null, hit.data);
+        return promise;
+      }
+    }
+
+    // ── Detect if this is a pure theme ID ───────────────────────────────────
+    if (THEME_ID_RE.test(id) && api.fetchThemeData) {
+      try {
+        const themeData = await api.fetchThemeData(id, { useCache: options.useCache !== false });
+        const result = Object.assign({ _type: 'theme' }, themeData);
+        if (options.useCache !== false) _cache.set(cacheKey, { data: result, ts: Date.now() });
+        done(null, result);
+      } catch (themeErr) {
+        // Could still be a thread ID — fall through
+        utils.warn("getThemeInfo", `Theme fetch failed for ${id}: ${themeErr.message} — trying as thread`);
+        await resolveAsThread(id, options, done, cacheKey);
+      }
+      return promise;
+    }
+
+    // ── Treat as thread ID ───────────────────────────────────────────────────
+    await resolveAsThread(id, options, done, cacheKey);
+    return promise;
+
+    async function resolveAsThread(tid, opts, finish, ck) {
+      let threadInfo = null;
+      try {
+        threadInfo = await api.getThreadInfo(tid);
+      } catch (tiErr) {
+        utils.warn("getThemeInfo", `getThreadInfo failed: ${tiErr.message}`);
+        const fallback = defaultThemeInfo(tid, { error: tiErr.message || 'Could not retrieve thread info' });
+        if (opts.useCache !== false) _cache.set(ck, { data: fallback, ts: Date.now() });
+        finish(null, fallback);
+        return;
+      }
+
+      if (!threadInfo) {
+        const fallback = defaultThemeInfo(tid);
+        if (opts.useCache !== false) _cache.set(ck, { data: fallback, ts: Date.now() });
+        finish(null, fallback);
+        return;
+      }
+
+      const info = Array.isArray(threadInfo) ? threadInfo[0] : threadInfo;
+
+      const base = {
+        _type:            'thread',
+        threadID:         tid,
+        threadName:       info.threadName || info.name || '',
+        participantCount: info.participantIDs?.length || 0,
+        isGroup:          info.isGroup || false,
+        color:            info.color || null,
+        emoji:            info.emoji || '👍',
+        theme_id:         info.theme_id || info.themeID || null,
+        theme_color:      info.theme_color || info.color || null,
+        gradient_colors:  info.gradient_colors || null,
+        backgroundImage:  info.backgroundImage || null,
+        is_dark:          null,
+        is_default:       !info.color && !info.theme_id,
+        muteUntil:        info.muteUntil || null,
+        unreadCount:      info.unreadCount || 0,
+      };
+
+      // Try to resolve the active theme's full details
+      if (opts.fetchActiveTheme !== false && base.theme_id && api.fetchThemeData) {
+        try {
+          const activeTheme = await api.fetchThemeData(base.theme_id, { useCache: true });
+          Object.assign(base, {
+            active_theme:   activeTheme,
+            gradient_colors: activeTheme.gradient_colors || base.gradient_colors,
+            backgroundImage: activeTheme.backgroundImage || base.backgroundImage,
+            is_dark:         activeTheme.is_dark,
+            theme_color:     activeTheme.primary_color || base.theme_color,
+          });
+        } catch (_) {}
+      }
+
+      if (opts.useCache !== false) _cache.set(ck, { data: base, ts: Date.now() });
+      finish(null, base);
+    }
+  };
+};