meta-implement

name	meta-implement
description	Drive the end-to-end implementation of the Meta (Facebook + Instagram) Graph API module into a React + TypeScript + Supabase project, sprint by sprint, enforcing the acceptance gate of each phase before moving on. Use when starting a Meta Ads or Instagram integration from scratch, resuming a partial one, or when asked to install, implement, port or set up Facebook OAuth, campaign sync, campaign creation, audiences, pixels or Instagram publishing.
license	MIT
compatibility	Target project needs React 18+, TypeScript, a Supabase project (Postgres, Edge Functions) and the Supabase CLI. A Meta app of type Business with the Marketing API and Instagram products is required to pass the sprint 1 gate; production scopes need App Review.
metadata	{"version":"1.0.0","part-of":"meta-graph-api"}

Implement the Meta Graph API module

Executes a six-sprint plan. Each sprint ends in a gate — an observable outcome, usually confirmed in Meta's own tooling (Ads Manager, Events Manager). A failed gate stops the run.

Source material is in the sibling skill directory:

../meta-graph-api/references/   the plan (ORQUESTRADOR + sprint-0 … sprint-5)
../meta-graph-api/assets/       migrations, edge functions, hooks, components

In Claude Code that resolves under ${CLAUDE_SKILL_DIR}/../meta-graph-api/. If the relative path fails:

find ~ -type d -path "*skills/meta-graph-api/assets" 2>/dev/null | head -3

Copy the packaged artifacts. Never retype an edge function or a migration — they carry the 18 corrections listed in the orchestrator, and a rewrite silently reintroduces the defects they fix.

---

Before sprint 0 — decide four things

Ask the user; record the answers in the project's CLAUDE.md / AGENTS.md.

1. Tenancy. The artifacts use company_id + get_user_company_ids(uuid). What is the equivalent — org_id, workspace_id, or single-tenant? Decide now: it renames a column across 17 migrations, every RLS policy and most of the 30 functions.
2. The client level. The origin links each client to one ad account, one Facebook page and one Instagram account. If your product has no such entity, decide whether assets link straight to the tenant — and apply that consistently, because the whole sync pipeline resolves assets through it.
3. Scope. Sprints 0–2 are the minimum useful product (connect + sync + read). Sprint 3 (creation), 4 (audiences/pixels) and 5 (Instagram) are independent — confirm which are actually wanted.
4. The Meta app. Type Business, with the Marketing API and Instagram products added, the redirect URI registered, and — for production — App Review for ads_management, ads_read, business_management, pages_* and instagram_*. Review takes days to weeks. If the app is not ready, build sprints 0–1 against a Development-mode app with the developer as a test user, and say so rather than faking the gate.

Also confirm the host-app adapter points in ../meta-graph-api/SKILL.md §4.

How to run each phase

1. Read the phase document in ../meta-graph-api/references/ (one folder per sprint, sprint-0 through sprint-5). It lists prerequisites, tasks, artifacts and the gate. The ordering constraints are not obvious from the code.
2. Check the prerequisites it names. Missing one → go back; do not improvise.
3. Copy the artifacts, adapting only: the tenancy column/function, the @/ import paths, and the adapter hooks. Nothing else.
4. Apply and deploy:

   supabase db push
   supabase functions deploy <function-name>
   

   Deploying and db push act on the user's real project — ask before the first one of a session, then proceed.
5. Run the gate and report the observed result, not the expected one.
6. Report in one short block: created, adapted, gate result.

The sprints

Sprint 0 — Foundation

Phases: connection schema · campaign schema · RLS, GRANTs and config.

Applies the migrations from assets/migrations/ (read INDEX.md first — it explains each file and the FK order), the tenancy helper, policies, GRANTs, .env and config.toml.

Gate: migrations apply; select * from facebook_integrations returns an empty result and not a permission error. An error here means the GRANT or the helper is wrong — every later sprint depends on it.

Sprint 1 — OAuth connection

Phases: edge functions (_shared/meta-graph.ts, oauth, scope check, pages) · hooks · connection UI.

Three things the origin got wrong and this plan fixes — verify each:

• the long-lived token exchange (grant_type=fb_exchange_token) actually runs and expires_at is stored;
• the App ID comes from VITE_FACEBOOK_APP_ID, never a literal:

  grep -rnE 'facebookAppId\s*=\s*"[0-9]{10,}"' src/    # must return nothing
  

• the redirect URI allowlist is env-driven and works on localhost.

Gate: connect a real account → ad accounts, pages and Instagram accounts appear in the UI, and check-meta-scopes lists the granted scopes.

Sprint 2 — Sync and tree

Phases: sync engine · scheduler · tree hooks · tree UI.

The sync is an async job (sync_jobs), not a request that blocks. Insights come nested in the campaign/adset/ad queries with the attribution window set.

Gate: for the same period, the numbers in the app match Ads Manager. If they do not, it is almost always the attribution window (action_attribution_windows(["7d_click","1d_view"])), not a sync bug.

Sprint 3 — Creation and editing

Phases: creation edge functions · builder wizard · unified editors.

Remember: Marketing API creation POSTs use application/x-www-form-urlencoded, and an adset's ad account must match its campaign's.

Gate: a campaign created from the app appears in Ads Manager with the right objective, budget and targeting. Create it paused.

Sprint 4 — Audiences and pixels

Phases: audiences (7 actions) · pixels + Conversions API · interest search.

CAPI payloads must hash email and phone with SHA-256, lowercase and trimmed, before sending. Sending raw PII to Meta is both a bug and a compliance problem.

Gate: a test event sent through CAPI appears in Events Manager; a custom audience created from the app appears in Audiences.

Sprint 5 — Instagram

Phases: publishing + scheduler · AI auto-post · DM webhook, inbox and automation.

Two non-negotiables:

• publishing is container → publish, two calls;
• the DM webhook validates x-hub-signature-256 (HMAC with the app secret) and deduplicates by message id — without dedup, a Meta redelivery duplicates the message and re-fires the automation.

Gate: a post publishes to Instagram; a DM sent to the account appears in the inbox without a refresh and fires its keyword automation exactly once.

Rules for this run

• A failed gate stops the run. Report what failed and what the user must decide. Do not carry a broken foundation forward.
• Never invent Graph API fields or endpoints. If something is missing from the contract in ../meta-graph-api/SKILL.md §2 and the examples, say so and check Meta's documentation.
• Never commit or log credentials. App Secret is an Edge Function secret; user and page tokens live in the database and never reach the browser.
• One Graph API version, from _shared/meta-graph.ts. A hardcoded version anywhere else is the defect this plan exists to avoid.
• Create ad entities paused while testing. A live campaign spends real money.

When the run finishes

1. Run the checks: npx tsc --noEmit, lint, build, and deno check supabase/functions/<name>/index.ts on every function touched.
2. Write the module's context into the project's CLAUDE.md / AGENTS.md:

## Meta module (Graph API)

Facebook + Instagram through the Graph API. One version constant in
`supabase/functions/_shared/meta-graph.ts`. User tokens in
`facebook_integrations`, page tokens in `facebook_pages` — never in the browser.
App Secret is an Edge Function secret only. The Instagram DM webhook is public
(`verify_jwt = false`) and validates HMAC.

Before changing anything here, load the `meta-graph-api` skill. Non-negotiable:
no inline Graph API version; no `TO anon` policies; every new table gets a GRANT;
Instagram publishing is container → publish; dedupe DMs by message id.

3. Report: sprints completed, gates passed, what was skipped, and what the user still needs from Meta (App Review, scopes, a linked Instagram account).