Meta integration via Graph API

A complete Meta module — Facebook Ads plus Instagram — extracted from a production ad-management platform: 17 migrations, 30 edge functions, 17 hooks, 71 components, plus a six-sprint plan with acceptance gates.

The plan does not replicate the origin system's defects: it lists 18 concrete corrections (unified API version, missing GRANTs, absent foreign keys, anon policies leaking every tenant's rows, a DM webhook with no HMAC validation, no message deduplication…) and the artifacts implement them.

Reference docs are in Brazilian Portuguese (references/), UI strings in the components are pt-BR. Code identifiers are English.

0. Orient yourself before touching anything

# Is the module already here?
ls supabase/functions | grep -E "meta-|facebook-|instagram-"
grep -rl "facebook_integrations" supabase/migrations | head

• Nothing → fresh implementation: use meta-implement, which walks the sprints with gates. The order is not negotiable — OAuth before sync, sync before creation.
• Partially → find the last passed gate (§6) and resume there.
• Broken → use meta-debug. Meta failures are almost always a token, a scope, or an ID belonging to the wrong account.
• Just a question → the contract below usually answers it.

1. Architecture

FRONTEND (React + React Query)
  Settings → Meta: connection card · ad accounts · pages · IG accounts · scopes
  Client → Campaigns: campaign tree (campaign → adset → ad), inline edit, bulk
  Client → Audiences · Pixels · Auto-posts · DM inbox
        │ supabase-js (RLS)              │ invoke()
        ▼                                ▼
SUPABASE (Postgres)
  facebook_integrations · facebook_ad_accounts · facebook_pages
  instagram_accounts · campaigns · ad_sets · ads · sync_jobs
  facebook_sync_schedules · _execution_logs
  meta_audiences · meta_pixels · pixel_events_log
  instagram_auto_post_configs · _posts · _schedules · knowledge
  instagram_conversations · _messages · _flows · _triggers
        │
        ▼
EDGE FUNCTIONS (Deno) — all Graph calls go through _shared/meta-graph.ts
  meta-oauth · check-meta-scopes · fetch-facebook-pages
  sync-meta-campaigns (async job) · meta-sync-scheduler
  create-meta-campaign-full · create/update-meta-adset · -ad · manage-campaign
  manage-meta-audiences · manage-meta-pixels · send-pixel-event
  publish-instagram-post · instagram-post-scheduler · generate-instagram-auto-post
  instagram-messaging-webhook (PUBLIC, HMAC) · instagram-automation-executor
        │
        ▼
  🌐 Graph API v21.0

2. Graph API contract — get this right first

Base: https://graph.facebook.com/v21.0, as a single constant in _shared/meta-graph.ts. Never inline a version anywhere else — the origin system had five versions living side by side (v18 → v22), which is correction #1.

Three token types, and using the wrong one is the most common failure:

The OAuth exchange returns a short-lived token. You must exchange it again with grant_type=fb_exchange_token to get the 60-day one — the origin system skipped this and simply assumed 60 days (correction #3).

Content-Type: application/x-www-form-urlencoded on Marketing API creation POSTs; JSON elsewhere. This trips people up: a JSON body on /campaigns fails with an unhelpful error.

Endpoints in use

Attribution window on sync — omit it and your numbers will not match Ads Manager:

.action_report_time(conversion).action_attribution_windows(["7d_click","1d_view"])

Full request/response samples: assets/examples/graph-api-insights.md, criacao-campanha-requests.md, instagram-publish-requests.md, escopos-oauth.md.

3. Things about Meta that bite

• Instagram publishing is two calls, not one: create a media container (/{igUser}/media), then publish it (/media_publish). Carousels are N containers plus one parent. A container expires in ~24h.
• An adset's ad account must match its campaign's. Mixing them produces errors that name neither — the origin system needed a dedicated check-adset-account-mismatches function to find these.
• insights{} comes back empty, not as an error, when the token lacks ads_read or the account has no delivery in the period. Empty ≠ broken.
• Scopes are granted per user, not per app. debug_token tells you what was actually granted; never assume the requested list.
• The DM webhook must validate x-hub-signature-256 (HMAC with the app secret). Without it, anyone can post fake messages into the inbox (correction #9).
• The DM webhook redelivers. Deduplicate by message mid with a UNIQUE constraint, or a redelivery duplicates the message and re-fires the automation (correction #15).
• redirect_uri is compared string for string between the auth dialog and the token exchange. One trailing slash apart and Meta returns "URL blocked".

4. Adapter points — what "any application" means

The artifacts came from a multi-tenant ad platform. Six integration points are host-app specific; everything else is self-contained.

The UI components assume shadcn/ui + Tailwind. Hooks and edge functions port unchanged to any UI kit.

5. Conventions that keep it working

1. One Graph API version, in _shared/meta-graph.ts. Every call imports it.
2. App Secret never leaves the backend. Not in .env of the frontend, not in a component, not in a log.
3. RLS through the SECURITY DEFINER helper only. A direct subquery on an RLS-protected table inside a policy fails silently — empty array, no error.
4. GRANT ... TO authenticated on every new table. The origin system had none, which is why data "disappeared" from the UI with no error (correction #2).
5. No TO anon policies. A public dashboard is served by an Edge Function with the service role that resolves the token — not by opening the table (correction #13).
6. verify_jwt = false only for Meta webhooks. Action endpoints stay authenticated (correction #8).
7. Foreign keys declared, with ON DELETE CASCADE. ad_sets/ads in the origin had loose UUIDs (correction #6), and company_id was nullable, so a row written without a tenant vanished from the UI (correction #14).
8. React Query for all server state — no useState mirrors of remote data.
9. Never log a token, not even truncated. Log the entity id and the error code.

6. Roadmap (six sprints, each with a gate)

Each sprint has one document per phase in references/, with tasks, artifacts and its own gate. references/ORQUESTRADOR.md is the master plan and lists all 18 corrections.

Use meta-implement to execute it, meta-debug when it breaks.

7. Failure modes worth memorizing

8. File map

SKILL.md                     this file
references/
  ORQUESTRADOR.md            master plan: scope, 18 corrections, contract, gates
  sprint-0…5/                one document per phase — tasks, artifacts, gate
assets/
  migrations/                17 SQL files, numbered in apply order (+ INDEX.md)
  edge-functions/            30 Deno functions + _shared/meta-graph.ts + config.toml
  frontend/hooks/            17 React Query hooks
  frontend/components/       71 components (connection, tree, builder, audiences,
                             pixels, Instagram, DM inbox)
  frontend/pages/            8 pages
  examples/                  Graph payloads, insights contract, OAuth scopes,
                             IG publishing, webhook payloads, .env.example

Companion skills: meta-implement (builds it, sprint by sprint) and meta-debug (isolates what broke).

9. Security and policy

• App Secret is backend-only. A leaked secret lets someone impersonate your app against every user who authorized it.
• User tokens are credentials with money attached — they can spend ad budget. Never log them, never return them to the browser, encrypt at rest if your platform supports it.
• The DM webhook is a public, unauthenticated endpoint. HMAC validation is not optional.
• Meta's Platform Terms apply to what you build. Ad data belongs to the advertiser; do not aggregate it across tenants. Production scopes require App Review, and automated messaging must respect Instagram's 24-hour messaging window. Building bulk unsolicited DMs is how apps get banned.
• Pixel/CAPI payloads carry personal data. Emails and phones must be SHA-256 hashed, lowercase and trimmed, before they reach Meta.