@ads-repo/meta-creative-buckets 1.0.0

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2026 Tomas Kliment / adsrepo.com
+
+All rights reserved.
+
+This tool and its contents are the exclusive property of adsrepo.com.
+You may use this tool solely for your own internal business purposes.
+
+You may NOT:
+- Redistribute, resell, sublicense, or share this tool or any part of it
+- Make the source code or generated outputs publicly available
+- Use this tool to build competing products or services
+- Share download links or access credentials with third parties
+
+For licensing inquiries: tomas@adsrepo.com

package/README.md

@@ -0,0 +1,76 @@
+# Meta Creative Buckets
+
+A Claude Code skill that reads your Meta ad account and plots every creative on a
+spend vs efficiency grid, so each ad lands in one of four buckets:
+
+```
+    CRR bad (high)  │  Wait     │  Kill
+                    ├───────────┼──────────
+    CRR good (low)  │  NotData  │  Scale
+                    └──────────────────────
+                      low spend    enough spend
+```
+
+The output is a single self-contained HTML file that opens in your browser.
+
+## Install
+
+```bash
+npm install -g @ads-repo/meta-creative-buckets
+```
+
+That copies the skill into `~/.claude/skills/meta-creative-buckets`. Restart Claude
+Code and it will pick it up.
+
+## Setup
+
+You need two values from Meta.
+
+**1. An access token** with the `ads_read` permission. The quickest route is the
+[Graph API Explorer](https://developers.facebook.com/tools/explorer/): pick your app,
+add the `ads_read` scope, generate the token. That one expires in about an hour - for
+repeat use, exchange it for a long-lived token or create a System User token in
+Business Manager.
+
+**2. Your ad account id** - the `act_…` number in the Ads Manager URL.
+
+Put both in a `.env` file in your project root:
+
+```bash
+META_ACCESS_TOKEN=your-token-here
+META_AD_ACCOUNT_ID=act_1234567890
+```
+
+Reading several accounts from one project? Suffix each pair with a client slug
+(`META_ACCESS_TOKEN_ACME_CZ`) and pass `--client acme-cz`.
+
+## Use it
+
+In Claude Code, say:
+
+> build the creative buckets dashboard
+
+It pulls 30 days of ad-level spend and purchase revenue, works out CRR per creative,
+and opens the dashboard in your browser.
+
+## The metric
+
+**CRR = spend ÷ purchase revenue**, on the 7-day-click window. It is ROAS upside down:
+CRR 40% means 40 € of ads per 100 € of sales, so **lower is better** (CRR 40% = ROAS 2.5).
+
+Both thresholds are computed from your own account at build time - the target starts at
+your blended CRR, the spend gate at the 75th percentile of per-ad spend - and both are
+live sliders you can move.
+
+## Requires
+
+- Node.js 18+
+- Claude Code
+- A Meta ad account that tracks purchases (the grid is built on revenue)
+
+No npm dependencies: the scripts use only Node's standard library.
+
+## Docs
+
+Full walkthrough, bucket rules and the two Meta API details worth knowing:
+<https://adsrepo.com/products/meta-creative-buckets>

package/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: meta-creative-buckets
+description: >
+  Build a Spend × CRR creative-bucket matrix dashboard from any Meta ad account — every ad
+  plotted as a bubble in a Not-enough-data / Wait / Scale / Kill quadrant grid, with a time
+  slider that replays the window day by day. Answers "which creatives deserve more budget
+  and which are burning it" for ecommerce accounts, using CRR (spend ÷ revenue) as the
+  efficiency metric.
+
+  Auto-activates when you mention:
+  - "creative buckets", "buckets dashboard", "creative matrix"
+  - "which creatives should I scale", "scale kill wait"
+  - "crr dashboard", "spend vs crr matrix", "roas by creative"
+---
+
+# Meta Creative Buckets
+
+Sorts every creative into four buckets on a Spend × CRR grid, so you can see at a glance
+which ads deserve more budget and which are burning it.
+
+```
+    CRR bad (high)  │  Wait     │  Kill
+                    ├───────────┼──────────
+    CRR good (low)  │  NotData  │  Scale
+                    └──────────────────────
+                      low spend    enough spend
+```
+
+Works with any Meta ad account that tracks purchases. One dependency: a Meta access token.
+
+## Setup (once)
+
+**1. Get a Meta access token** with `ads_read` permission for the account you want to read.
+The quickest route is [Graph API Explorer](https://developers.facebook.com/tools/explorer/):
+pick your app, add the `ads_read` scope, generate the token. Short-lived tokens expire in an
+hour — for repeated use, exchange it for a long-lived one or create a System User token in
+Business Manager.
+
+**2. Find your ad account id** — it is the `act_…` number in the Ads Manager URL.
+
+**3. Put both in `.env`** in your project root (see `env.example` in this folder):
+
+```bash
+META_ACCESS_TOKEN=your-token-here
+META_AD_ACCOUNT_ID=act_1234567890
+```
+
+Managing several accounts? Suffix each pair with the client slug, upper-cased:
+`META_ACCESS_TOKEN_ACME_CZ` / `META_AD_ACCOUNT_ID_ACME_CZ`, then pass `--client acme-cz`.
+
+**4. Add the npm scripts** to your `package.json`:
+
+```json
+"meta:buckets": "node .claude/skills/meta-creative-buckets/scripts/fetch-buckets-data.cjs 30 && node .claude/skills/meta-creative-buckets/scripts/build-buckets-matrix.cjs",
+"meta:buckets-chart": "node .claude/skills/meta-creative-buckets/scripts/build-buckets-matrix.cjs",
+"meta:buckets-creatives": "node .claude/skills/meta-creative-buckets/scripts/fetch-creative-meta.cjs",
+"meta:buckets-lock": "node .claude/skills/meta-creative-buckets/scripts/encrypt-dashboard.cjs"
+```
+
+No install step — the scripts use only Node's standard library. They are `.cjs` so they run
+in both ESM and CommonJS projects.
+
+**5. Optional — `buckets.config.json`** in your project root, for a nicer header:
+
+```json
+{
+  "client": "acme-cz",
+  "accountName": "Acme s.r.o.",
+  "logo": "public/acme-logo.png",
+  "agencyLogo": "public/my-agency-logo.png"
+}
+```
+
+Every field is optional. With no config the client slug is `default`, the title comes from
+the account name Meta reports, and no logo is drawn.
+
+## Running it
+
+```bash
+npm run meta:buckets           # fetch 30 days + build (the usual command)
+npm run meta:buckets-chart     # rebuild the HTML from data already on disk
+```
+
+The dashboard opens in your browser automatically. Everything lands in
+`data/meta-ads/<client>/`:
+
+- `buckets-latest.json` — per-ad summary + daily series
+- `history/YYYYMMDD-buckets.json` — dated snapshot, drives the day-over-day ▲▼ arrows
+- `buckets-matrix.html` — the dashboard
+
+Run it a second day and the table gains movement arrows, comparing against the last snapshot.
+
+Custom window: `node …/fetch-buckets-data.cjs 60 2026-09-07` fetches 60 days ending on that
+date. Passing yesterday avoids a partial final day.
+
+## The metric
+
+**CRR = spend ÷ purchase revenue**, shown as a percentage, on the 7-day-click window.
+
+It is **ROAS upside down**: CRR 40% means you spend 40 € of ads per 100 € of sales, so
+**lower is better** (CRR 40% = ROAS 2.5).
+
+## Bucket rules
+
+With **target CRR** `T` and **spend gate** `S` (both live sliders):
+
+| Bucket | Rule |
+|---|---|
+| **Not enough data** | `spend < S` — under the gate, never judged |
+| **Scale** | `spend ≥ S` and `CRR ≤ T` — earning well, give it more |
+| **Wait** | `spend ≥ S` and `T < CRR < 3T` — mediocre, watch it |
+| **Kill** | `spend ≥ S` and `CRR ≥ 3T` — burning money |
+
+An ad with **no revenue at all** stays in Not-enough-data until it burns `3 × S`, then goes
+to Kill. It is never "Wait" — there is nothing to wait on without a single purchase. Those
+ads have no CRR, so they sit in a separate strip below the plot, placed by spend only.
+
+## Defaults come from the data
+
+Both defaults are computed at build time from your account, not hardcoded:
+
+- **Target CRR** = the account's **blended CRR** over the window. Starting the line at the
+  account average splits creatives into "better than my current average" vs "worse", which
+  is the honest opening question.
+- **Spend gate** = 75th percentile of per-ad spend, floored at **3 × AOV**, rounded to 10.
+  An ad that has not spent a few average order values cannot be judged on revenue; the
+  median would wave through far too many.
+
+Both are sliders and click-to-edit — these are only the opening position.
+
+## The dashboard
+
+A standalone HTML file, no server needed. Open it off disk, email it, put it anywhere.
+
+- **Quadrant scatter** — bubble per ad, area ∝ spend, X = spend (log), Y = CRR %. Click a
+  zone to filter the table; click a bubble (or tick a row) to select across both views.
+- **Time slider** — replays the window day by day; every bubble animates to its cumulative
+  position as of that day. Day / Week / Month granularity, plus a date-range calendar with
+  presets. Picking a range restarts accumulation at the range start. On a first visit the
+  thumb pulses with a hint, dismissed for good after the first drag.
+- **Aggregate tiles** — Spend, Revenue and CRR (with ROAS) for whatever is in focus:
+  selection > clicked bucket > everything shown. CRR is spend ÷ revenue weighted, never an
+  average of per-ad CRRs.
+- **Spend distribution bar** — what share of budget sits in each bucket. Usually the fastest
+  read on the page.
+- **Filters** — campaign / ad set / ad (cascading), status, and an Active-only toggle
+  (= spent money on the selected day).
+- **Table** — thumbnail + name, spend, revenue, purchases, CRR (with ▲▼ vs the previous
+  snapshot), ROAS, last-3-day spend and CRR, CTR, active days. Sortable; ads with no CRR
+  always sort last. Click a thumbnail for a lightbox; `←` `→` step through the current sort.
+
+## Sharing it with a password
+
+```bash
+npm run meta:buckets-lock -- "your-password"
+```
+
+Writes `buckets-matrix-locked.html` next to the original: the page is AES-encrypted and asks
+for the password before rendering. Good enough to stop a passer-by following a shared link —
+the ciphertext is public, so do not treat it as confidential.
+
+## Two API details worth knowing
+
+**Currency is read from the API, never assumed.** An account named "… CZ" may well bill in
+EUR. Inferring a currency from the account name was once wrong by a factor of ~25.
+
+**Revenue uses the named `7d_click` sub-field** of `action_values`, not Meta's plain `value`.
+`value` is the account's default attribution (click + view) and can overstate revenue by
+roughly a third, which would silently understate CRR.
+
+## Rate limiting
+
+Meta counts API calls **per account over a rolling window**, so the size of the account
+matters more than the size of the window you asked for. Three defences are built in:
+
+1. **Creative metadata is fetched by id, only for the ads in the window.** An account
+   accumulates every ad ever created — 8,000+ is ordinary — while a 30-day window usually has
+   a couple of hundred with spend. Paging the whole `/ads` edge to reach those few hundred
+   spends the limit on ads that will never appear in the output, and then the creative call
+   that carries the thumbnails gets refused. So the fetch reads the insights first, collects
+   the ids that actually spent, and looks those up in batches of 40.
+2. **The fetch degrades instead of failing.** A refused creative pass leaves
+   `media_type: 'unknown'` and no preview, rather than discarding the expensive daily
+   insights. If the bulk insights range is refused, it falls back to fetching day by day.
+3. **`npm run meta:buckets-creatives` is a repair pass** — re-run it later to patch media
+   types and previews into the existing JSON without re-fetching insights. Rarely needed now
+   that the main fetch is narrow, but useful if you were already near the limit.
+
+Raise `META_API_RATE_LIMIT_DELAY` in `.env` (default 400 ms) if you keep hitting it, and give
+the account a quiet 15-30 minutes before retrying — consecutive runs keep the window full.
+The bucket maths never depended on creative metadata, so a run without it is still correct.
+
+## Per-ad revenue does not sum to the account total (expected)
+
+Summing revenue across ads gives a **higher** number than the same period read at account
+level — typically **+8–12%**. This is Meta's **cross-ad deduplication**, not a bug: one
+purchase touched by two ads is credited to both in ad-level rows, but counted once at
+account level. Any per-ad report has this property.
+
+In practice:
+
+- **Per-ad CRR is sound for ranking creatives against each other** — that is what this
+  dashboard is for.
+- The **aggregate CRR tile is slightly optimistic** versus Ads Manager's account view. Do
+  not quote it as the account's true blended CRR; read that at account level.
+- The gap grows with retargeting overlap.
+
+## Optional extras
+
+`scripts/optional/` holds two scripts that add promo labels and creative thumbnails from a
+Meta Ad Library scrape. They need a scraping and classification pipeline this skill does not
+include — see the README in that folder for the file format if you want to wire up your own.
+The dashboard works fine without them.
+
+## When explaining results to the user
+
+Use MEDIUM-SIMPLE language, in the user's language.
+
+Explain **CRR** plainly: how much you spend on ads to earn 100 € of sales. CRR 38% means 38 €
+of ads per 100 € of revenue, so **lower is better**. It is ROAS upside down (CRR 38% = ROAS 2.6).
+
+Say plainly how many ads sit in **Not enough data**. On most accounts that is the majority,
+because spend concentrates in a handful of creatives. That is a finding, not a gap: the
+question "should I spread budget wider?" follows directly from it.
+
+Quote **CRR and spend together**. A creative can look excellent on a small budget; the
+interesting question is what happens to CRR as spend rises, which the matrix answers by
+position, not the table by sorting.
+
+Do not present the aggregate CRR tile as the account's blended CRR — per-ad revenue
+double-counts (see above). Read the real one at account level.

package/buckets.config.example.json

@@ -0,0 +1,8 @@
+{
+  "_comment": "Copy to buckets.config.json in your PROJECT ROOT (not this folder). Every field is optional — with no config file at all the dashboard uses the client slug 'default', takes its title from the account name Meta reports, and renders no logo.",
+
+  "client": "acme-cz",
+  "accountName": "Acme s.r.o.",
+  "logo": "public/acme-logo.png",
+  "agencyLogo": "public/my-agency-logo.png"
+}

package/env.example

@@ -0,0 +1,29 @@
+# Meta Creative Buckets — credentials
+#
+# Copy the lines you need into your project's .env (or .env.local) in the project root.
+# Never commit the real values — .env belongs in .gitignore.
+
+# --- Single account -----------------------------------------------------------
+# The simplest setup. Works with the default client slug, no config file needed.
+
+META_ACCESS_TOKEN=your-access-token-here
+META_AD_ACCOUNT_ID=act_1234567890
+
+# --- Several accounts ---------------------------------------------------------
+# Suffix each pair with the client slug, upper-cased and non-alphanumerics turned
+# into underscores: --client acme-cz  ->  _ACME_CZ
+#
+# META_ACCESS_TOKEN_ACME_CZ=...
+# META_AD_ACCOUNT_ID_ACME_CZ=act_1234567890
+# META_ACCESS_TOKEN_OTHER_CLIENT=...
+# META_AD_ACCOUNT_ID_OTHER_CLIENT=act_9876543210
+
+# --- Optional tuning ----------------------------------------------------------
+# Raise the delay if the account keeps tripping Meta's rate limit (error 80004).
+
+# META_API_VERSION=v25.0
+# META_API_PAGE_SIZE=500
+# META_API_RATE_LIMIT_DELAY=400
+
+# Default client when no --client flag is passed.
+# BUCKETS_CLIENT=acme-cz

package/install-to-claude.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'meta-creative-buckets';
+const target = path.join(os.homedir(), '.claude', 'skills', SKILL_NAME);
+const source = __dirname;
+
+try {
+  fs.mkdirSync(target, { recursive: true });
+
+  // env.example and the config sample travel with the skill: the first thing a new
+  // user needs is to know which two values go where, and they are easier to find
+  // next to SKILL.md than inside a node_modules folder.
+  ['SKILL.md', 'README.md', 'env.example', 'buckets.config.example.json'].forEach(f => {
+    const src = path.join(source, f);
+    if (fs.existsSync(src)) fs.copyFileSync(src, path.join(target, f));
+  });
+
+  ['scripts'].forEach(d => {
+    const src = path.join(source, d);
+    if (fs.existsSync(src)) fs.cpSync(src, path.join(target, d), { recursive: true });
+  });
+
+  console.log(`\n✅ Skill installed to ${target}`);
+  console.log(`   Restart Claude Code to pick it up.`);
+  console.log(`   Next: add META_ACCESS_TOKEN and META_AD_ACCOUNT_ID to a .env file`);
+  console.log(`   in your project (see env.example in the folder above).`);
+  console.log(`   Updates: npm update -g @ads-repo/meta-creative-buckets`);
+  console.log(`   More skills: https://adsrepo.com\n`);
+} catch (err) {
+  console.error(`\n❌ Install failed: ${err.message}`);
+  console.error(`   Try running manually: install-meta-creative-buckets\n`);
+  process.exit(0);
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ads-repo/meta-creative-buckets",
+  "version": "1.0.0",
+  "description": "Sort your Meta creatives into Scale, Wait and Kill on a spend vs CRR grid — drop-in Claude Code skill",
+  "keywords": [
+    "claude-code",
+    "skill",
+    "meta-ads",
+    "creative-testing",
+    "crr",
+    "roas",
+    "adsrepo"
+  ],
+  "homepage": "https://adsrepo.com/products/meta-creative-buckets",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "adsrepo",
+  "files": [
+    "LICENSE",
+    "SKILL.md",
+    "README.md",
+    "env.example",
+    "buckets.config.example.json",
+    "scripts/",
+    "install-to-claude.js"
+  ],
+  "bin": {
+    "install-meta-creative-buckets": "install-to-claude.js"
+  },
+  "scripts": {
+    "postinstall": "node ./install-to-claude.js",
+    "buckets": "node scripts/fetch-buckets-data.cjs 30 && node scripts/build-buckets-matrix.cjs",
+    "buckets-chart": "node scripts/build-buckets-matrix.cjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}