@ads-repo/meta-creative-buckets 1.0.0

package/scripts/fetch-buckets-data.cjs

@@ -0,0 +1,398 @@
+#!/usr/bin/env node
+
+/**
+ * Fetch Meta Ads daily ad-level data for one ad account and build a per-ad summary used to
+ * bucket creatives (Not enough data / Wait / Scale / Kill).
+ *
+ * The efficiency metric is
+ *
+ *   CRR = spend / purchase revenue   (expressed as %, 7d click)
+ *
+ * CRR is inverse ROAS (CRR 40% == ROAS 2.5) and LOWER is better. Purchase COUNT is fetched
+ * too, for the reference columns in the table.
+ *
+ * Which account is read comes from scripts/config.cjs — see that file for the resolution
+ * order (--client flag, BUCKETS_CLIENT, buckets.config.json).
+ *
+ * Usage: node fetch-buckets-data.cjs [days] [endDate] [--client slug]
+ *        (default 30 days, ending today)
+ * Output:
+ *   data/meta-ads/<client>/buckets-latest.json            (per-ad summary + daily rows)
+ *   data/meta-ads/<client>/history/YYYYMMDD-buckets.json  (dated snapshot, day-over-day movement)
+ *
+ * Three rules worth keeping when editing this file:
+ *   1. Currency is READ FROM THE API, never assumed — and never inferred from the account
+ *      NAME. An account called "… CZ" may well bill in EUR; guessing "Kč" from the name was
+ *      once wrong by a factor of ~25.
+ *   2. Revenue is read from the NAMED 7d_click sub-field of action_values. Meta's plain
+ *      `value` is the account default attribution (click+view) and can overstate revenue by
+ *      roughly a third, which would silently understate CRR.
+ *   3. /ads with a nested creative{...} expansion trips the per-account rate limit (80004)
+ *      on some accounts, so creative metadata is fetched in two cheap passes that degrade
+ *      to media_type 'unknown' rather than discarding the expensive daily insights.
+ */
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const cfg = require('./config.cjs');
+
+const API_VERSION = cfg.apiVersion;
+const { token: ACCESS_TOKEN, accountId: ACCOUNT_ID } = cfg.requireCredentials();
+
+const DAYS = parseInt(process.argv[2]) || 30;
+// optional end date (YYYY-MM-DD); default today. Use yesterday to avoid a partial day.
+const END_ARG = process.argv[3] && /^\d{4}-\d{2}-\d{2}$/.test(process.argv[3]) ? process.argv[3] : null;
+const PAGE_SIZE = cfg.pageSize;
+// rate-limit sensitive accounts want a longer idle between calls; override in .env
+const RATE_LIMIT_DELAY = cfg.rateLimitDelay;
+
+// date_start last, so daily rows carry the day.
+// action_values is required for revenue — without it Meta returns purchases but no money.
+const FIELDS = [
+  'ad_id',
+  'ad_name',
+  'adset_name',
+  'campaign_name',
+  'spend',
+  'impressions',
+  'reach',
+  'frequency',
+  'clicks',
+  'ctr',
+  'cpm',
+  'actions',
+  'action_values',
+  'date_start',
+].join(',');
+
+function actionVal(actions, type) {
+  if (!Array.isArray(actions)) return 0;
+  const a = actions.find(x => x.action_type === type);
+  return a ? Number(a.value) || 0 : 0;
+}
+
+// Read a specific attribution window off an action_values entry. Meta's plain `value` is
+// the account default attribution, NOT the requested window — the window lives in a named
+// sub-field. Falls back to `value` only if the sub-field is absent.
+function attrVal(rows, type, window) {
+  if (!Array.isArray(rows)) return 0;
+  const a = rows.find(x => x.action_type === type);
+  if (!a) return 0;
+  return Number(a[window] != null ? a[window] : a.value) || 0;
+}
+
+// ecommerce account: main conversion = purchase, and its revenue drives CRR
+function purchaseCount(actions) {
+  return actionVal(actions, 'purchase') || actionVal(actions, 'omni_purchase');
+}
+function purchaseRevenue(actionValues) {
+  return attrVal(actionValues, 'purchase', '7d_click')
+    || attrVal(actionValues, 'omni_purchase', '7d_click');
+}
+
+function ymd(d) { return d.toISOString().slice(0, 10); }
+function makeRequest(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, (res) => {
+      let data = '';
+      res.on('data', chunk => (data += chunk));
+      res.on('end', () => {
+        if (res.statusCode === 200) resolve(JSON.parse(data));
+        else reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+      });
+    }).on('error', reject);
+  });
+}
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+function generateDateRange(start, end) {
+  const dates = [];
+  const cur = new Date(start), last = new Date(end);
+  while (cur <= last) { dates.push(ymd(cur)); cur.setDate(cur.getDate() + 1); }
+  return dates;
+}
+
+async function fetchSingleDay(date) {
+  const all = [];
+  let url = `https://graph.facebook.com/${API_VERSION}/${ACCOUNT_ID}/insights?` +
+    `access_token=${ACCESS_TOKEN}&level=ad&fields=${FIELDS}` +
+    `&time_range={"since":"${date}","until":"${date}"}&time_increment=1` +
+    `&action_attribution_windows=["7d_click"]&limit=${PAGE_SIZE}`;
+  while (url) {
+    const resp = await makeRequest(url);
+    if (resp.data && resp.data.length) all.push(...resp.data);
+    url = resp.paging && resp.paging.next ? resp.paging.next : null;
+    if (url) await sleep(RATE_LIMIT_DELAY);
+  }
+  return all;
+}
+
+async function fetchDayByDay(startDate, endDate) {
+  const dates = generateDateRange(startDate, endDate);
+  const all = [];
+  for (let i = 0; i < dates.length; i++) {
+    process.stdout.write(`  day ${i + 1}/${dates.length} ${dates[i]} ... `);
+    try {
+      const day = await fetchSingleDay(dates[i]);
+      all.push(...day);
+      console.log(`${day.length} rows (total ${all.length})`);
+    } catch (err) {
+      console.log(`SKIP (${err.message.slice(0, 80)})`);
+    }
+    await sleep(RATE_LIMIT_DELAY);
+  }
+  return all;
+}
+
+async function fetchInsights(startDate, endDate) {
+  const all = [];
+  let url = `https://graph.facebook.com/${API_VERSION}/${ACCOUNT_ID}/insights?` +
+    `access_token=${ACCESS_TOKEN}&level=ad&fields=${FIELDS}` +
+    `&time_range={"since":"${startDate}","until":"${endDate}"}&time_increment=1` +
+    `&action_attribution_windows=["7d_click"]&limit=${PAGE_SIZE}`;
+  let page = 0;
+  try {
+    while (url) {
+      page++;
+      console.log(`  page ${page} ...`);
+      const resp = await makeRequest(url);
+      if (resp.data && resp.data.length) {
+        all.push(...resp.data);
+        console.log(`    ${resp.data.length} rows (total ${all.length})`);
+      }
+      url = resp.paging && resp.paging.next ? resp.paging.next : null;
+      if (url) await sleep(RATE_LIMIT_DELAY);
+    }
+    return all;
+  } catch (err) {
+    // 500 = Meta choked on the range; error code 1 ("reduce the amount of data") and the
+    // 80004 rate limit are also survivable day-by-day. Falling back beats losing the run.
+    if (err.message && (err.message.startsWith('HTTP 500') || /reduce the amount of data|"code":\s*1\b|80004/.test(err.message))) {
+      console.warn('\n  Meta refused the bulk range — switching to day-by-day mode...\n');
+      return await fetchDayByDay(startDate, endDate);
+    }
+    throw err;
+  }
+}
+
+// video vs image. Many video ads use object_type "SHARE" with the video in
+// asset_feed_spec.videos[] — must be checked or they read as image.
+function classifyMediaType(creative) {
+  if (!creative) return 'image';
+  if (creative.object_type === 'VIDEO') return 'video';
+  if (creative.video_id) return 'video';
+  const afs = creative.asset_feed_spec || {};
+  if (afs.videos && afs.videos.length) return 'video';
+  const spec = creative.object_story_spec || {};
+  if (spec.video_data && spec.video_data.video_id) return 'video';
+  if (spec.link_data && spec.link_data.video_id) return 'video';
+  return 'image';
+}
+
+// ad -> { media_type, active, preview } for the ads passed in.
+// Preview URLs are static CDN links (no FB login), so they render in the standalone HTML.
+//
+// Two batched passes over ids, never over the account's edges:
+//   1) /?ids=<ad ids>       -> status + creative id
+//   2) /?ids=<creative ids> -> creative details (deduped, so usually fewer calls than pass 1)
+//
+// Both passes degrade: a failure leaves media_type 'unknown' rather than aborting the run,
+// because the daily insights above are the expensive part and must not be thrown away.
+async function fetchAdMeta(spendingAdIds) {
+  const typeMap = {}, statusMap = {}, previewMap = {};
+  const adCreative = {};   // ad_id -> creative_id
+
+  // Look ads up BY ID, in small batches, instead of walking the account's /ads edge.
+  // An account accumulates every ad ever created (8k+ is normal) while a 30-day window
+  // usually has a couple of hundred with spend. Paging the whole edge burns the per-account
+  // rate limit on ads that will never appear in the output, and the limit is counted per
+  // account per hour — so the cheap creative pass that follows gets refused for no reason.
+  const BATCH = 40;
+  async function fetchByIds(ids, fields, onRow) {
+    for (let i = 0; i < ids.length; i += BATCH) {
+      const chunk = ids.slice(i, i + BATCH);
+      const url = `https://graph.facebook.com/${API_VERSION}/?ids=${chunk.join(',')}` +
+        `&fields=${encodeURIComponent(fields)}&access_token=${ACCESS_TOKEN}`;
+      const resp = await makeRequest(url);
+      Object.values(resp || {}).forEach(row => { if (row && row.id) onRow(row); });
+      if (i + BATCH < ids.length) await sleep(Math.max(RATE_LIMIT_DELAY, 500));
+    }
+  }
+
+  // pass 1 — status + creative id for the ads that actually spent.
+  // thumbnail_url is NOT requestable on the batched /?ids= endpoint (only on the /ads edge);
+  // asking for it 400s the whole batch. Thumbnails come from the creative pass below.
+  try {
+    await fetchByIds(spendingAdIds, 'id,effective_status,creative{id}', ad => {
+      statusMap[ad.id] = ad.effective_status === 'ACTIVE';
+      if (ad.creative && ad.creative.id) adCreative[ad.id] = ad.creative.id;
+    });
+    console.log(`  mapped ${Object.keys(statusMap).length}/${spendingAdIds.length} ads (status)`);
+  } catch (err) {
+    console.warn(`  ⚠ ad lookup failed (${err.message.slice(0, 70)}) — status unknown`);
+  }
+
+  // pass 2 — creative details, only for the creatives those ads point at (deduped)
+  const creatives = {};
+  const uniqCreatives = [...new Set(Object.values(adCreative))];
+  try {
+    if (uniqCreatives.length) {
+      await fetchByIds(uniqCreatives,
+        'id,object_type,video_id,asset_feed_spec{videos},object_story_spec,thumbnail_url,image_url',
+        cr => { creatives[cr.id] = cr; });
+    }
+    console.log(`  mapped ${Object.keys(creatives).length}/${uniqCreatives.length} creatives (type + preview)`);
+  } catch (err) {
+    console.warn(`  ⚠ creative fetch failed (${err.message.slice(0, 70)}) — media types unknown`);
+  }
+
+  for (const adId of spendingAdIds) {
+    const cr = creatives[adCreative[adId]];
+    typeMap[adId] = cr ? classifyMediaType(cr) : 'unknown';
+    previewMap[adId] = {
+      thumb: (cr && cr.thumbnail_url) || null,
+      image: (cr && cr.image_url) || null,
+    };
+  }
+  const known = Object.values(typeMap).filter(t => t !== 'unknown').length;
+  console.log(`  ${known}/${Object.keys(typeMap).length} ads have a known media type`);
+  return { typeMap, statusMap, previewMap };
+}
+
+// Account currency, straight from Meta. Never assume it from the account NAME — an account
+// named "… CZ" may still bill in EUR, and a hardcoded "Kč" label was once wrong by a factor
+// of ~25. Everything downstream (axis, tooltips, table) derives its symbol from this field.
+// The account name comes from the same call, so the dashboard header labels itself without
+// anyone hardcoding a client. A config override wins, an API miss falls back to the id.
+async function fetchAccountInfo() {
+  try {
+    const r = await makeRequest(`https://graph.facebook.com/${API_VERSION}/${ACCOUNT_ID}?fields=currency,name&access_token=${ACCESS_TOKEN}`);
+    if (r) {
+      if (r.currency) console.log(`  account currency: ${r.currency}`);
+      if (r.name) console.log(`  account name:     ${r.name}`);
+      return { currency: r.currency || null, name: r.name || null };
+    }
+  } catch (err) {
+    console.warn(`  ⚠ account info fetch failed (${err.message.slice(0, 60)})`);
+  }
+  return { currency: null, name: null };
+}
+
+// Collapse daily rows into one summary per ad (whole-window totals + a daily series so the
+// dashboard can replay the window on its time slider). CRR/CTR/frequency are recomputed from
+// the summed atoms, never averaged from daily rates.
+function summarize(rows, typeMap, statusMap, previewMap) {
+  const byAd = {};
+  for (const r of rows) {
+    const id = r.ad_id;
+    if (!byAd[id]) {
+      byAd[id] = {
+        ad_id: id, ad_name: r.ad_name, adset_name: r.adset_name, campaign_name: r.campaign_name,
+        media_type: typeMap[id] || 'unknown', active: statusMap[id] === true,
+        preview_thumb: (previewMap[id] && previewMap[id].thumb) || null,
+        preview_image: (previewMap[id] && previewMap[id].image) || null,
+        spend: 0, impressions: 0, reach: 0, clicks: 0,
+        purchases: 0, revenue: 0, active_days: 0, daily: [],
+      };
+    }
+    const a = byAd[id];
+    const spend = +r.spend || 0, impr = +r.impressions || 0, clicks = +r.clicks || 0;
+    const purchases = purchaseCount(r.actions);
+    const revenue = purchaseRevenue(r.action_values);
+    a.spend += spend; a.impressions += impr; a.reach += (+r.reach || 0); a.clicks += clicks;
+    a.purchases += purchases; a.revenue += revenue;
+    if (impr > 0) a.active_days += 1;
+    a.daily.push({
+      date: r.date_start,
+      spend: Math.round(spend * 100) / 100,
+      purchases,
+      revenue: Math.round(revenue * 100) / 100,
+      impr, clicks,
+    });
+  }
+  return Object.values(byAd).map(a => {
+    a.daily.sort((x, y) => x.date.localeCompare(y.date));
+    // CRR as a percentage. null = no revenue yet, which is "unknown", not "infinitely bad" —
+    // the dashboard parks those ads in a separate no-result strip instead of the top of the axis.
+    a.crr = a.revenue > 0 ? (a.spend / a.revenue) * 100 : null;
+    a.roas = a.spend > 0 && a.revenue > 0 ? a.revenue / a.spend : null;
+    a.ctr = a.impressions > 0 ? (a.clicks / a.impressions) * 100 : 0;
+    a.frequency = a.reach > 0 ? a.impressions / a.reach : 0;
+    a.aov = a.purchases > 0 ? a.revenue / a.purchases : null;
+    a.spend = Math.round(a.spend * 100) / 100;
+    a.revenue = Math.round(a.revenue * 100) / 100;
+    a.crr = a.crr == null ? null : Math.round(a.crr * 10) / 10;
+    a.roas = a.roas == null ? null : Math.round(a.roas * 100) / 100;
+    a.ctr = Math.round(a.ctr * 100) / 100;
+    a.frequency = Math.round(a.frequency * 100) / 100;
+    a.aov = a.aov == null ? null : Math.round(a.aov * 100) / 100;
+    return a;
+  }).sort((x, y) => y.spend - x.spend);
+}
+
+async function main() {
+  const end = END_ARG ? new Date(END_ARG + 'T00:00:00Z') : new Date();
+  const start = new Date(end);
+  start.setDate(start.getDate() - (DAYS - 1));
+  const startDate = ymd(start), endDate = ymd(end);
+
+  console.log(`\nMeta Creative Buckets — data fetch`);
+  console.log(`  Client:  ${cfg.client}`);
+  console.log(`  Account: ${ACCOUNT_ID}`);
+  console.log(`  Range:   ${startDate} → ${endDate} (${DAYS} days)`);
+  console.log(`  CRR = spend ÷ purchase revenue (7d click), as %\n`);
+
+  console.log('Fetching account info...');
+  const { currency, name: apiName } = await fetchAccountInfo();
+  const accountName = cfg.accountName || apiName || ACCOUNT_ID;
+
+  console.log('\nFetching daily ad-level insights...');
+  const insights = await fetchInsights(startDate, endDate);
+  console.log(`✓ ${insights.length} daily rows\n`);
+
+  // Only the ads that appear in the window need creative metadata — look them up by id
+  // rather than paging the account's whole ad list, which is typically 30-40x larger and
+  // spends the per-account rate limit before the creative pass gets a turn.
+  const spendingAdIds = [...new Set(
+    insights.filter(r => (+r.spend || 0) > 0).map(r => r.ad_id)
+  )];
+  console.log(`Fetching creative types + status + preview for ${spendingAdIds.length} ads...`);
+  const { typeMap, statusMap, previewMap } = await fetchAdMeta(spendingAdIds);
+
+  const ads = summarize(insights, typeMap, statusMap, previewMap);
+  console.log(`✓ ${ads.length} ads summarized\n`);
+
+  // account-level blended numbers — the dashboard seeds its default Target CRR from these
+  const totSpend = ads.reduce((s, a) => s + a.spend, 0);
+  const totRevenue = ads.reduce((s, a) => s + a.revenue, 0);
+  const totPurchases = ads.reduce((s, a) => s + a.purchases, 0);
+  const blendedCrr = totRevenue > 0 ? Math.round((totSpend / totRevenue) * 1000) / 10 : null;
+  const blendedAov = totPurchases > 0 ? Math.round((totRevenue / totPurchases) * 100) / 100 : null;
+
+  console.log(`  blended: spend ${Math.round(totSpend)} ${currency || ''} · revenue ${Math.round(totRevenue)} ${currency || ''}`);
+  console.log(`  blended CRR ${blendedCrr == null ? 'n/a' : blendedCrr + '%'}` +
+              `${blendedCrr ? ` (ROAS ${Math.round(100 / blendedCrr * 100) / 100})` : ''}` +
+              ` · ${totPurchases} purchases · AOV ${blendedAov == null ? 'n/a' : blendedAov}\n`);
+
+  const payload = {
+    account: ACCOUNT_ID, accountName, client: cfg.client, currency,
+    startDate, endDate, days: DAYS, metric: 'crr',
+    generatedAt: new Date().toISOString(),
+    totals: { spend: Math.round(totSpend * 100) / 100, revenue: Math.round(totRevenue * 100) / 100, purchases: totPurchases, crr: blendedCrr, aov: blendedAov },
+    ads,
+  };
+
+  const histDir = cfg.historyDir;
+  fs.mkdirSync(histDir, { recursive: true });
+
+  const latest = cfg.latestFile;
+  const snapshot = path.join(histDir, `${endDate.replace(/-/g, '')}-buckets.json`);
+  fs.writeFileSync(latest, JSON.stringify(payload, null, 2));
+  fs.writeFileSync(snapshot, JSON.stringify(payload, null, 2));
+
+  console.log(`✓ Saved`);
+  console.log(`  ${latest}`);
+  console.log(`  ${snapshot}  (day-over-day snapshot)`);
+}
+
+main().catch(e => { console.error('❌ Fatal:', e.message); process.exit(1); });

package/scripts/fetch-creative-meta.cjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+/**
+ * OPTIONAL repair pass for media types + previews on
+ * data/meta-ads/<client>/buckets-latest.json.
+ *
+ * Some accounts trip Meta's per-account rate limit (code 80004) easily, and the main fetch
+ * deliberately degrades to media_type 'unknown' rather than throwing away the expensive
+ * daily insights. This script re-runs ONLY the cheap creative passes and patches the
+ * existing JSON in place, so a rate-limited run can be healed without re-fetching insights.
+ *
+ * It only fetches creatives for ads that actually appear in the summary (a few hundred),
+ * not the whole account, which is what makes the bulk pass trip the limit.
+ *
+ * The dashboard does not depend on this — on a hard-limited account it may never succeed,
+ * and the bucket maths never used media_type. Treat it as a nicety.
+ *
+ * Usage: node fetch-creative-meta.cjs [--client slug]
+ */
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const cfg = require('./config.cjs');
+
+const API_VERSION = cfg.apiVersion;
+const { token: ACCESS_TOKEN, accountId: ACCOUNT_ID } = cfg.requireCredentials();
+
+const LATEST = cfg.latestFile;
+const DELAY = parseInt(process.env.META_API_RATE_LIMIT_DELAY) || 600;
+const BATCH = 40;   // ad ids per ?ids= call — small enough to stay under the account limit
+
+function makeRequest(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, (res) => {
+      let data = '';
+      res.on('data', c => (data += c));
+      res.on('end', () => {
+        if (res.statusCode === 200) resolve(JSON.parse(data));
+        else reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+      });
+    }).on('error', reject);
+  });
+}
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+
+function classifyMediaType(creative) {
+  if (!creative) return 'image';
+  if (creative.object_type === 'VIDEO') return 'video';
+  if (creative.video_id) return 'video';
+  const afs = creative.asset_feed_spec || {};
+  if (afs.videos && afs.videos.length) return 'video';
+  const spec = creative.object_story_spec || {};
+  if (spec.video_data && spec.video_data.video_id) return 'video';
+  if (spec.link_data && spec.link_data.video_id) return 'video';
+  return 'image';
+}
+
+// Batched ?ids= lookup.
+//
+// Backoff policy: retry the 80004 rate limit with escalating waits, but ABORT THE WHOLE RUN
+// once a few batches in a row have exhausted their retries. When this account is hard-limited
+// no batch succeeds, and grinding through every batch's full 60+180+300s burns ~9 minutes each
+// for nothing. Failing fast tells the user "come back later" in under a minute instead.
+//
+// Any NON-rate-limit error (e.g. a bad field) is a bug, not a wait: throw immediately rather
+// than silently leaving every ad unpatched.
+const GIVE_UP_AFTER = 2;   // consecutive fully-exhausted batches before aborting the run
+
+class RateLimitedError extends Error {}
+
+async function fetchBatch(ids, fields, label) {
+  const out = {};
+  let consecutiveFailures = 0, succeeded = 0;
+  for (let i = 0; i < ids.length; i += BATCH) {
+    const chunk = ids.slice(i, i + BATCH);
+    const url = `https://graph.facebook.com/${API_VERSION}/?ids=${chunk.join(',')}` +
+      `&fields=${encodeURIComponent(fields)}&access_token=${ACCESS_TOKEN}`;
+    const n = Math.floor(i / BATCH) + 1, total = Math.ceil(ids.length / BATCH);
+    process.stdout.write(`  ${label} batch ${n}/${total} ... `);
+    let done = false, ok = false;
+    const WAITS = [30000, 90000, 180000];
+    for (let attempt = 0; attempt <= WAITS.length && !done; attempt++) {
+      try {
+        const resp = await makeRequest(url);
+        Object.assign(out, resp);
+        console.log(`ok`);
+        done = true; ok = true;
+      } catch (err) {
+        const limited = /80004|too many calls|request limit/i.test(err.message);
+        if (!limited) throw new Error(`${label} batch ${n} failed: ${err.message.slice(0, 200)}`);
+        if (attempt === WAITS.length) { console.log(`SKIP (still rate limited)`); done = true; }
+        else { console.log(`rate limited — waiting ${WAITS[attempt] / 1000}s`); await sleep(WAITS[attempt]); }
+      }
+    }
+    if (ok) { succeeded++; consecutiveFailures = 0; }
+    else if (++consecutiveFailures >= GIVE_UP_AFTER && succeeded === 0) {
+      throw new RateLimitedError(
+        `account is hard rate-limited (${consecutiveFailures} batches exhausted their retries, none succeeded)`);
+    }
+    await sleep(DELAY);
+  }
+  return out;
+}
+
+async function main() {
+  const payload = JSON.parse(fs.readFileSync(LATEST, 'utf-8'));
+  const ads = payload.ads.filter(a => a.spend > 0);
+  console.log(`\nCreative repair pass — ${cfg.client}`);
+  console.log(`  ${ads.length} ads with spend in ${path.basename(LATEST)}\n`);
+
+  const adIds = ads.map(a => a.ad_id);
+
+  // pass 1 — ad -> creative id + status (flat, no nested expansion).
+  // NOTE: thumbnail_url is NOT requestable on the batched /?ids= endpoint (only on the
+  // /ads edge) — asking for it 400s the whole batch. Thumbnails come from pass 2 instead.
+  const adInfo = await fetchBatch(adIds, 'id,effective_status,creative{id}', 'ads');
+
+  const creativeIds = [];
+  const adCreative = {}, adStatus = {};
+  for (const id of adIds) {
+    const a = adInfo[id];
+    if (!a) continue;
+    adStatus[id] = a.effective_status === 'ACTIVE';
+    if (a.creative && a.creative.id) {
+      adCreative[id] = a.creative.id;
+      creativeIds.push(a.creative.id);
+    }
+  }
+  const uniqCreatives = [...new Set(creativeIds)];
+  console.log(`\n  resolved ${Object.keys(adCreative).length}/${adIds.length} ads to ${uniqCreatives.length} creatives\n`);
+
+  // pass 2 — creative details
+  const crInfo = await fetchBatch(uniqCreatives,
+    'id,object_type,video_id,asset_feed_spec{videos},object_story_spec,thumbnail_url,image_url', 'creatives');
+
+  let patched = 0, stillUnknown = 0;
+  for (const a of payload.ads) {
+    const cr = crInfo[adCreative[a.ad_id]];
+    if (cr) {
+      a.media_type = classifyMediaType(cr);
+      a.preview_thumb = cr.thumbnail_url || a.preview_thumb || null;
+      a.preview_image = cr.image_url || a.preview_image || null;
+      patched++;
+    } else if (a.media_type === 'unknown') {
+      stillUnknown++;
+    }
+    if (adStatus[a.ad_id] != null) a.active = adStatus[a.ad_id];
+  }
+
+  const counts = payload.ads.reduce((m, a) => (m[a.media_type] = (m[a.media_type] || 0) + 1, m), {});
+  console.log(`\n✓ patched ${patched} ads · still unknown: ${stillUnknown}`);
+  console.log(`  media types: ${JSON.stringify(counts)}`);
+
+  fs.writeFileSync(LATEST, JSON.stringify(payload, null, 2));
+  console.log(`✓ Updated ${LATEST}`);
+}
+
+main().catch(e => {
+  // A hard rate limit is an expected, retryable state on this account — not a crash.
+  // Say so plainly and leave buckets-latest.json untouched (nothing was written).
+  if (e instanceof RateLimitedError) {
+    console.error(`\n⏳ Aborted: ${e.message}`);
+    console.error('   Nothing was changed — buckets-latest.json is intact.');
+    console.error('   Meta\'s ads-management limit resets on a rolling window; wait ~15-30 min and re-run:');
+    console.error('     npm run meta:buckets-creatives && npm run meta:buckets-chart');
+    console.error('   The dashboard works meanwhile; only the video/static badges stay "?".');
+    process.exit(2);
+  }
+  console.error('❌ Fatal:', e.message);
+  process.exit(1);
+});

package/scripts/optional/README.md

@@ -0,0 +1,65 @@
+# Optional extras — not part of the standard workflow
+
+The dashboard runs on the Meta Ads API alone. The two scripts in this folder add a promo
+dimension and creative thumbnails on top of it, and **both need data this skill does not
+produce**: a Meta Ad Library scrape, classified per creative.
+
+They are kept here as a working reference for anyone who has that pipeline. If you do not,
+ignore this folder — the matrix works without it, it just has no promo filter and falls back
+to Meta's own preview images.
+
+## What they expect
+
+Both read from `research/meta-ads-library/<client>/` in the project root:
+
+| file | produced by | used for |
+|---|---|---|
+| `_data/promo-labels.json` | your classifier | ad id → promo verdict |
+| `creatives-manifest.json` | your scraper | ad id → downloaded image files |
+| `dedupe-map.json` | your scraper | file → its representative in `unique/` |
+| `unique/*.jpg` | your scraper | the images themselves |
+
+Paths are hardcoded to that layout. Adapt them, or write your own equivalent — the dashboard
+only cares about the two output files.
+
+## The output contract
+
+That is the part worth knowing, because you can produce these two files any way you like and
+the dashboard will pick them up:
+
+**`data/meta-ads/<client>/promo-labels.json`** — a flat map, ad id to one of three exact
+strings:
+
+```json
+{
+  "120210000000000001": "Promo - main message",
+  "120210000000000002": "Promo - secondary message",
+  "120210000000000003": "Non-promo"
+}
+```
+
+Meaning: the offer *is* the argument / an offer rides alongside a different argument / no
+offer in the creative.
+
+**`data/meta-ads/<client>/thumbs.json`** — ad id to an image path, relative to the dashboard
+HTML:
+
+```json
+{ "120210000000000001": "thumbs/120210000000000001.jpg" }
+```
+
+Write a second file per ad with an `@full` suffix (`thumbs/<id>@full.jpg`) for the lightbox.
+A missing `@full` falls back to the small image rather than breaking.
+
+## Two things that bite
+
+**Labels drop ads.** When `promo-labels.json` is present, ads without a label are dropped
+from the dashboard entirely rather than shown as "Unclassified" — an unactionable bucket is
+worse than a stated coverage gap. A **stale** label file is therefore the dangerous case: if
+none of the current ad ids match, the dashboard comes out empty. Re-extract labels after
+every fresh fetch, and read the "dropped" count the build prints.
+
+**Join on your classifier's map, not on a rendered report page.** A report card typically
+shows one representative creative per concept, so scraping ids out of the HTML silently drops
+every other ad running the same visual. That mistake once labelled 88 of 208 ads where the
+generator's own map covered 154.