fca-phantom 1.0.0

package/phantom/dispatch/createAITheme.js

@@ -0,0 +1,333 @@
+"use strict";
+
+/**
+ * createAITheme — Advanced AI Theme Generation for Phantom SDK
+ * Generates Facebook Messenger AI-powered themes from natural-language prompts.
+ *
+ * Features:
+ *  - Automatic prompt enrichment with context-aware suffixes
+ *  - In-memory response cache (5-minute TTL, keyed by prompt+count)
+ *  - Exponential-backoff retry on transient network failures
+ *  - Parallel dual-batch generation for large numThemes requests
+ *  - Deep theme normalisation: preview URLs, gradient extraction, dark-mode detection
+ *  - Color-harmony accessibility scoring (WCAG contrast ratio)
+ *  - Rank ordering by accessibility score
+ *  - Full callback + Promise dual API
+ *
+ * @by Allou Mohamed (original) — massively extended for phantom-fca
+ */
+
+const utils = require('../datastore/models/matrix/tools');
+
+// ── In-memory cache ──────────────────────────────────────────────────────────
+const _cache    = new Map();
+const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+
+// ── Prompt enrichment table ──────────────────────────────────────────────────
+const PROMPT_ENRICHERS = [
+  { re: /\bnature\b/i,        add: ", lush greenery, organic textures, earthy tones" },
+  { re: /\bocean|sea\b/i,     add: ", deep blues, aqua gradients, bioluminescent wave patterns" },
+  { re: /\bspace|galaxy\b/i,  add: ", cosmic purples, starfield depth, nebula glow, zero-gravity" },
+  { re: /\bsunset\b/i,        add: ", warm amber, golden-hour glow, gradient horizon fade" },
+  { re: /\bneon\b/i,          add: ", cyberpunk aesthetic, high-contrast vivid saturation, grid glow" },
+  { re: /\bminimal\b/i,       add: ", clean whitespace, muted tones, geometric precision" },
+  { re: /\bvintage\b/i,       add: ", muted sepia, retro film-grain palette, nostalgic warmth" },
+  { re: /\bforest\b/i,        add: ", deep canopy greens, dappled forest light, mossy hues" },
+  { re: /\bfire|flame\b/i,    add: ", molten ember reds, scorched black, dynamic orange heat" },
+  { re: /\bpastel\b/i,        add: ", soft blush rose, lavender mist, peachy cloud tones" },
+  { re: /\bcity|urban\b/i,    add: ", concrete greys, skyline neon, metropolitan night glow" },
+  { re: /\bwinter|snow\b/i,   add: ", icy blue-white, frosted crystal clarity, cold silence" },
+  { re: /\bspring|bloom\b/i,  add: ", fresh petal pink, verdant growth, dewdrop luminosity" },
+  { re: /\boutdoor|adventure\b/i, add: ", rugged terrain, horizon distance, open-sky freedom" },
+];
+
+function enrichPrompt(raw) {
+  if (!raw || typeof raw !== 'string') return raw;
+  let out = raw.trim();
+  for (const { re, add } of PROMPT_ENRICHERS) {
+    if (re.test(out) && !out.toLowerCase().includes(add.slice(2, 14))) {
+      out += add;
+      break;
+    }
+  }
+  return out;
+}
+
+// ── Color helpers ────────────────────────────────────────────────────────────
+function hexToRgb(hex) {
+  if (!hex || typeof hex !== 'string') 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 relativeLuminance({ r, g, b }) {
+  const lin = v => {
+    v /= 255;
+    return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+function isDark(hex) {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return null;
+  return relativeLuminance(rgb) < 0.179;
+}
+
+function wcagContrast(hex1, hex2) {
+  const r1 = hexToRgb(hex1), r2 = hexToRgb(hex2);
+  if (!r1 || !r2) return null;
+  const L1 = relativeLuminance(r1), L2 = relativeLuminance(r2);
+  const [hi, lo] = L1 > L2 ? [L1, L2] : [L2, L1];
+  return +((hi + 0.05) / (lo + 0.05)).toFixed(2);
+}
+
+// ── Theme accessibility scoring (0–100) ──────────────────────────────────────
+function scoreTheme(t) {
+  let s = 40;
+  const grads = t.gradient_colors || [];
+
+  if (grads.length >= 2) s += 10;
+  if (grads.length >= 3) s += 5;
+  if (t.preview_image_urls?.light_mode) s += 15;
+  if (t.preview_image_urls?.dark_mode  && t.preview_image_urls.dark_mode !== t.preview_image_urls.light_mode) s += 8;
+  if (t.alternative_themes?.length)    s += 7;
+  if (t.background_asset)              s += 5;
+
+  if (grads.length >= 2) {
+    const ratio = wcagContrast(grads[0], grads[grads.length - 1]);
+    if (ratio !== null) {
+      if (ratio > 3)  s += 5;
+      if (ratio > 4.5) s += 5;
+      if (ratio > 7)  s += 5;
+    }
+  }
+
+  return Math.min(100, s);
+}
+
+// ── URL extraction ───────────────────────────────────────────────────────────
+function extractUrl(obj) {
+  if (!obj) return null;
+  if (typeof obj === 'string') return obj;
+  return obj.uri || obj.url || null;
+}
+
+// ── Gradient extraction ──────────────────────────────────────────────────────
+function extractGradient(theme) {
+  const raw = theme.gradient_colors || theme.gradient || theme.colors;
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw;
+  if (typeof raw === 'string') {
+    try { return JSON.parse(raw); } catch { return [raw]; }
+  }
+  return [];
+}
+
+// ── Full theme normalisation ─────────────────────────────────────────────────
+function normalizeTheme(theme, index) {
+  const t = { ...theme };
+
+  // Preview images
+  let lightUrl = null, darkUrl = null;
+  const previewSrc = t.preview_image_urls || t.preview_images || t.preview_urls;
+
+  if (previewSrc) {
+    if (typeof previewSrc === 'string') {
+      lightUrl = darkUrl = previewSrc;
+    } else if (Array.isArray(previewSrc)) {
+      lightUrl = extractUrl(previewSrc[0]);
+      darkUrl  = extractUrl(previewSrc[1]) || lightUrl;
+    } else {
+      lightUrl = extractUrl(previewSrc.light_mode) || extractUrl(previewSrc.light);
+      darkUrl  = extractUrl(previewSrc.dark_mode)  || extractUrl(previewSrc.dark);
+    }
+  }
+
+  if (!lightUrl) lightUrl = extractUrl(t.background_asset?.image) || extractUrl(t.icon_asset?.image);
+  if (!darkUrl && Array.isArray(t.alternative_themes) && t.alternative_themes.length) {
+    const alt = t.alternative_themes[0];
+    darkUrl = extractUrl(alt?.background_asset?.image) || extractUrl(alt?.icon_asset?.image);
+  }
+  if (lightUrl && !darkUrl) darkUrl = lightUrl;
+  if (darkUrl  && !lightUrl) lightUrl = darkUrl;
+  if (lightUrl || darkUrl)  t.preview_image_urls = { light_mode: lightUrl, dark_mode: darkUrl };
+
+  // Gradient
+  t.gradient_colors = extractGradient(theme);
+
+  // Primary color
+  t.primary_color   = theme.primary_color || theme.fallback_color || t.gradient_colors[0] || null;
+
+  // Dark-mode flag
+  t.is_dark         = t.primary_color ? isDark(t.primary_color) : null;
+
+  // WCAG contrast between first and last gradient stops
+  if (t.gradient_colors.length >= 2) {
+    t.gradient_contrast = wcagContrast(t.gradient_colors[0], t.gradient_colors[t.gradient_colors.length - 1]);
+  }
+
+  // Accessibility + ranking
+  t.accessibility_score = scoreTheme(t);
+  t.rank                = index;
+
+  // Background image shortcut
+  t.backgroundImage = extractUrl(t.background_asset?.image) || lightUrl || null;
+
+  return t;
+}
+
+// ── GraphQL form builder ─────────────────────────────────────────────────────
+function buildForm(ctx, prompt, numThemes) {
+  return {
+    av: ctx.i_userID || ctx.userID,
+    qpl_active_flow_ids: "25308101,25309433,521482085",
+    fb_api_caller_class: "RelayModern",
+    fb_api_req_friendly_name: "useGenerateAIThemeMutation",
+    variables: JSON.stringify({
+      input: {
+        client_mutation_id: String(Date.now() % 1e9),
+        actor_id: ctx.i_userID || ctx.userID,
+        bypass_cache: true,
+        caller: "MESSENGER",
+        num_themes: numThemes,
+        prompt,
+      }
+    }),
+    server_timestamps: true,
+    doc_id: "23873748445608673",
+    fb_api_analytics_tags: JSON.stringify(["qpl_active_flow_ids=25308101,25309433,521482085"]),
+    fb_dtsg: ctx.fb_dtsg,
+  };
+}
+
+// ── Fetch with retry ─────────────────────────────────────────────────────────
+async function fetchRaw(defaultFuncs, ctx, form, maxRetries = 3, baseMs = 700) {
+  let lastErr;
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const res = await defaultFuncs
+        .post("https://web.facebook.com/api/graphql/", ctx.jar, form)
+        .then(utils.parseAndCheckLogin(ctx, defaultFuncs));
+
+      if (res.errors) {
+        const msg = res.errors[0]?.message || JSON.stringify(res.errors);
+        throw Object.assign(new Error(msg), { isFatal: true });
+      }
+
+      const payload = res?.data?.xfb_generate_ai_themes_from_prompt;
+      if (!payload?.themes?.length)
+        throw Object.assign(new Error("No themes returned for the given prompt"), { isFatal: true });
+
+      return payload.themes;
+    } catch (err) {
+      lastErr = err;
+      if (err.isFatal || attempt >= maxRetries) throw err;
+      const wait = baseMs * Math.pow(2, attempt - 1) + Math.random() * 300;
+      utils.warn("createAITheme", `Attempt ${attempt} failed (${err.message}) — retry in ${Math.round(wait)}ms`);
+      await new Promise(r => setTimeout(r, wait));
+    }
+  }
+  throw lastErr;
+}
+
+// ── Module export ─────────────────────────────────────────────────────────────
+module.exports = function (defaultFuncs, api, ctx) {
+
+  /**
+   * Generate AI-powered Messenger themes from a natural-language prompt.
+   *
+   * @param {string}   prompt        Natural-language description
+   * @param {number}  [numThemes=3]  Number of themes to generate (1–10)
+   * @param {object}  [options]
+   *   @param {boolean} [options.enrichPrompt=true]  Auto-enrich the prompt
+   *   @param {boolean} [options.useCache=true]       Use/populate the 5-min cache
+   *   @param {boolean} [options.parallel=false]      Split large requests into 2 parallel calls
+   *   @param {number}  [options.retries=3]           Max retry attempts on transient errors
+   * @param {Function} [callback]    Node-style (err, themes[]) callback
+   * @returns {Promise<Array>}       Array of fully-normalised theme objects
+   *
+   * Each theme contains:
+   *   id, name, description, primary_color, gradient_colors, gradient_contrast,
+   *   preview_image_urls { light_mode, dark_mode }, backgroundImage,
+   *   is_dark, accessibility_score, rank, alternative_themes, background_asset, ...
+   */
+  return async function createAITheme(prompt, numThemes, options, callback) {
+    // ── Argument normalisation ───────────────────────────────────────────────
+    if (typeof numThemes === 'function')                           { callback = numThemes; numThemes = 3; options = {}; }
+    else if (typeof numThemes === 'object' && numThemes !== null) { options = numThemes; numThemes = 3; }
+    if (typeof options === 'function')                            { callback = options; options = {}; }
+    options   = options || {};
+    numThemes = Math.max(1, Math.min(10, Number.isFinite(+numThemes) ? +numThemes : 3));
+
+    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);
+    }
+
+    // ── Validation ───────────────────────────────────────────────────────────
+    if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
+      done(new Error("createAITheme: 'prompt' must be a non-empty string"));
+      return promise;
+    }
+
+    const rawPrompt   = prompt.trim();
+    const finalPrompt = options.enrichPrompt !== false ? enrichPrompt(rawPrompt) : rawPrompt;
+    const cacheKey    = `${finalPrompt}::${numThemes}`;
+
+    // ── Cache lookup ──────────────────────────────────────────────────────────
+    if (options.useCache !== false) {
+      const hit = _cache.get(cacheKey);
+      if (hit && Date.now() - hit.ts < CACHE_TTL) {
+        utils.log("createAITheme", `Cache hit — "${rawPrompt}"`);
+        done(null, hit.data);
+        return promise;
+      }
+    }
+
+    utils.log("createAITheme", `Generating ${numThemes} theme(s) — "${rawPrompt}"`);
+    if (finalPrompt !== rawPrompt)
+      utils.log("createAITheme", `Enriched prompt: "${finalPrompt}"`);
+
+    try {
+      const retries = options.retries || 3;
+      let rawThemes;
+
+      if (options.parallel && numThemes > 5) {
+        const half = Math.ceil(numThemes / 2);
+        const [a, b] = await Promise.all([
+          fetchRaw(defaultFuncs, ctx, buildForm(ctx, finalPrompt, half),          retries),
+          fetchRaw(defaultFuncs, ctx, buildForm(ctx, finalPrompt, numThemes - half), retries),
+        ]);
+        rawThemes = [...a, ...b];
+      } else {
+        rawThemes = await fetchRaw(defaultFuncs, ctx, buildForm(ctx, finalPrompt, numThemes), retries);
+      }
+
+      const themes = rawThemes.map((t, i) => normalizeTheme(t, i));
+
+      // Sort best first
+      themes.sort((a, b) => (b.accessibility_score || 0) - (a.accessibility_score || 0));
+      themes.forEach((t, i) => { t.rank = i; });
+
+      if (options.useCache !== false)
+        _cache.set(cacheKey, { data: themes, ts: Date.now() });
+
+      utils.log("createAITheme", `Done — ${themes.length} theme(s) generated`);
+      done(null, themes);
+    } catch (err) {
+      utils.error("createAITheme", err.message || err);
+      done(err);
+    }
+
+    return promise;
+  };
+};

package/phantom/dispatch/createNewGroup.js

@@ -0,0 +1,99 @@
+"use strict";
+
+const utils = require('../datastore/models/matrix/tools');
+const { globalShield } = require('../datastore/models/matrix/ghost');
+
+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));
+    }
+  }
+}
+
+module.exports = (defaultFuncs, api, ctx) => {
+  return async function createNewGroup(participantIDs, groupTitle, options, callback) {
+    let resolveFunc, rejectFunc;
+    const returnPromise = new Promise((resolve, reject) => {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+
+    if (typeof groupTitle === "function") { callback = groupTitle; groupTitle = null; options = {}; }
+    if (typeof options === "function") { callback = options; options = {}; }
+    if (typeof callback !== "function") {
+      callback = (err, data) => {
+        if (err) return rejectFunc(err);
+        resolveFunc(data);
+      };
+    }
+    if (!options || typeof options !== "object") options = {};
+
+    try {
+      if (!Array.isArray(participantIDs)) throw new Error("createNewGroup: participantIDs must be an array");
+      if (participantIDs.length < 1) throw new Error("createNewGroup: at least 1 participantID required");
+      if (participantIDs.length > 250) throw new Error("createNewGroup: maximum 250 participants allowed");
+
+      const actorID = ctx.i_userID || ctx.userID;
+
+      const pids = participantIDs
+        .map(String)
+        .filter(id => id !== String(actorID))
+        .map(id => ({ fbid: id }));
+      pids.push({ fbid: actorID });
+
+      const uniqueMap = new Map();
+      for (const p of pids) uniqueMap.set(p.fbid, p);
+      const dedupedPids = Array.from(uniqueMap.values());
+
+      await globalShield.addSmartDelay();
+
+      const form = {
+        fb_api_caller_class: "RelayModern",
+        fb_api_req_friendly_name: "MessengerGroupCreateMutation",
+        av: actorID,
+        doc_id: "577041672419534",
+        variables: JSON.stringify({
+          input: {
+            entry_point: options.entryPoint || "jewel_new_group",
+            actor_id: actorID,
+            participants: dedupedPids,
+            client_mutation_id: String(Math.round(Math.random() * 10000)),
+            thread_settings: {
+              name: groupTitle || null,
+              joinable_mode: options.joinableMode || "PRIVATE",
+              thread_image_fbid: options.imageID || null
+            }
+          }
+        })
+      };
+
+      const res = await retryOp(() =>
+        defaultFuncs.post("https://www.facebook.com/api/graphql/", ctx.jar, form)
+          .then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+      );
+
+      if (res.errors) throw res;
+
+      const thread = res.data?.messenger_group_thread_create?.thread;
+      if (!thread) throw new Error("createNewGroup: no thread data in response");
+
+      const threadID = thread.thread_key?.thread_fbid;
+      const result = {
+        threadID,
+        name: thread.name || groupTitle || null,
+        participantCount: dedupedPids.length,
+        participants: dedupedPids.map(p => p.fbid),
+        timestamp: Date.now()
+      };
+
+      callback(null, result);
+    } catch (err) {
+      utils.error("createNewGroup", err);
+      callback(err);
+    }
+
+    return returnPromise;
+  };
+};

package/phantom/dispatch/createPoll.js

@@ -0,0 +1,148 @@
+"use strict";
+
+const utils = require('../datastore/models/matrix/tools');
+
+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() * 300));
+    }
+  }
+}
+
+async function mqttCreatePoll(ctx, threadID, questionText, options) {
+  return new Promise((resolve, reject) => {
+    const reqID = ++ctx.wsReqNumber;
+    const taskID = ++ctx.wsTaskNumber;
+
+    const normalizedOptions = options.map(opt =>
+      typeof opt === "string" ? { text: opt } : opt
+    );
+
+    const form = JSON.stringify({
+      app_id: "772021112871879",
+      payload: JSON.stringify({
+        epoch_id: utils.generateOfflineThreadingID(),
+        tasks: [{
+          failure_count: null,
+          label: "163",
+          payload: JSON.stringify({
+            question_text: questionText,
+            thread_key: threadID,
+            options: normalizedOptions,
+            sync_group: 1
+          }),
+          queue_name: "poll_creation",
+          task_id: taskID
+        }],
+        version_id: "8768858626531631"
+      }),
+      request_id: reqID,
+      type: 3
+    });
+
+    let handled = false;
+    const onResp = (topic, message) => {
+      if (topic !== "/ls_resp" || handled) return;
+      let j;
+      try { j = JSON.parse(message.toString()); j.payload = JSON.parse(j.payload); } catch { return; }
+      if (j.request_id !== reqID) return;
+      handled = true;
+      clearTimeout(timer);
+      ctx.mqttClient.removeListener("message", onResp);
+      resolve({
+        success: true,
+        threadID,
+        question: questionText,
+        options: normalizedOptions,
+        timestamp: Date.now(),
+        response: j.payload
+      });
+    };
+
+    const timer = setTimeout(() => {
+      if (!handled) {
+        handled = true;
+        ctx.mqttClient.removeListener("message", onResp);
+        resolve({ success: true, threadID, question: questionText, options, sent: true });
+      }
+    }, 20000);
+
+    ctx.mqttClient.on("message", onResp);
+    ctx.mqttClient.publish("/ls_req", form, { qos: 1, retain: false }, (err) => {
+      if (err && !handled) {
+        handled = true;
+        clearTimeout(timer);
+        ctx.mqttClient.removeListener("message", onResp);
+        reject(err);
+      }
+    });
+  });
+}
+
+async function httpCreatePoll(defaultFuncs, ctx, threadID, questionText, options) {
+  const form = {
+    fb_api_caller_class: "RelayModern",
+    fb_api_req_friendly_name: "MessengerCreatePollMutation",
+    doc_id: "4738060229603032",
+    variables: JSON.stringify({
+      input: {
+        thread_id: threadID,
+        question: { text: questionText },
+        options: options.map(opt => ({
+          text: typeof opt === "string" ? opt : opt.text
+        })),
+        actor_id: ctx.userID,
+        client_mutation_id: String(Math.round(Math.random() * 10000))
+      }
+    })
+  };
+  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 { success: true, threadID, question: questionText, options, method: "graphql" };
+}
+
+module.exports = (defaultFuncs, api, ctx) => {
+  return async function createPoll(threadID, questionText, options, 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 (!threadID) throw new Error("createPoll: threadID is required");
+      if (!questionText || typeof questionText !== "string") throw new Error("createPoll: questionText must be a string");
+      if (!Array.isArray(options) || options.length < 2) throw new Error("createPoll: options must be an array with at least 2 entries");
+      if (options.length > 10) throw new Error("createPoll: maximum 10 poll options allowed");
+
+      let result;
+      if (ctx.mqttClient) {
+        try {
+          result = await retryOp(() => mqttCreatePoll(ctx, String(threadID), questionText, options));
+        } catch (mqttErr) {
+          utils.warn("createPoll", "MQTT failed, using HTTP:", mqttErr.message);
+          result = await retryOp(() => httpCreatePoll(defaultFuncs, ctx, String(threadID), questionText, options));
+        }
+      } else {
+        result = await retryOp(() => httpCreatePoll(defaultFuncs, ctx, String(threadID), questionText, options));
+      }
+
+      callback(null, result);
+    } catch (err) {
+      utils.error("createPoll", err);
+      callback(err);
+    }
+
+    return returnPromise;
+  };
+};