@iann29/rastro 0.9.0 → 0.10.0

package/docs/meta-ads.md

@@ -0,0 +1,746 @@
+# Meta ads: spend, return and conversions
+
+Rastro already counts the leads a host's server reports and files them by origin
+and by campaign → ad set → ad (the README's "Leads from the host's server"). The
+Meta ads layer puts money next to those counts. For each site it reads from the
+Meta Marketing API what the linked ad accounts spent per ad and per day, with
+impressions and clicks, and the campaign, ad set and ad names, status and
+creative. With spend beside the leads, a screen shows what each campaign, ad and
+site cost per lead, per qualified lead and per sale, and what it returned. In
+the other direction, Rastro sends the host's sales, and the leads that reach the
+board columns the host maps to an event, to the site's Meta pixel as
+conversions, so Meta can optimize the ads for sales rather than for
+conversations.
+
+Everything stays in the host's deployment, like the rest of Rastro: the
+encrypted tokens, the spend, the catalog and the conversion queue live in the
+host's Rastro component, and a federated dashboard reads them through the host's
+grant.
+
+## Availability
+
+The Meta connection and the Conversions API sender ship in 0.10.0:
+
+| Part                                                                   | Now                                                       |
+| ---------------------------------------------------------------------- | --------------------------------------------------------- |
+| `metaAds` capability, `leads.daily`, `meta.status`, `meta.conversions` | Served; spend and status from the linked ad accounts      |
+| Spend fields and `bySite` in `leads.report`                            | Spend per row; ads that spent without leads listed        |
+| Connecting Meta, linking ad accounts, the pixel                        | Host-side `Rastro` methods; federated with `configure`    |
+| Facebook Login for Business, board columns and the event map           | Served; a mapped column queues its event                  |
+| Spend and catalog sync                                                 | One scheduler chain for every linked ad account           |
+| `RASTRO_SECRETS_KEY`, `RASTRO_META_FAKE`, `RASTRO_META_APP_ID/SECRET`  | Optional env bindings                                     |
+| Conversions sent to the pixel                                          | Sales and new leads from the lead methods; mapped columns |
+
+## Turn on the `metaAds` capability
+
+A host opts in where it builds its federated surface, beside `leads`, and
+re-exports the three new reads from `convex/rastroFederation.ts`:
+
+```ts
+const federated = exposeFederatedAnalyticsApi(components.rastroAnalytics, {
+  issuer: federationIssuer,
+  resolveConnection,
+  leads: true,
+  metaAds: true,
+});
+
+export const {
+  // ...the functions the module already exports
+  leadsReport,
+  listLeads,
+  leadJourney,
+  leadsDaily,
+  metaStatus,
+  metaConversions,
+} = federated;
+```
+
+Deploy, then use **Verificar novamente** in the dashboard's Conexões so the
+connection records the new capability.
+
+- `leadsDaily` rides the `leads` capability: any host with `leads: true` serves
+  it.
+- `metaStatus` and `metaConversions` need `metaAds: true`. Without it they fail
+  with `FEDERATION_INVALID_SCOPE` ("This host does not connect Meta ads") and
+  the manifest neither advertises `metaAds` nor names them, so a dashboard knows
+  to hide spend for that host.
+- The spend fields of `leadsReport` need no flag. They stay `null` until a site
+  links an ad account. Spend only reaches readers through the lead reports, so a
+  host that turns on `metaAds` also passes `leads: true`.
+- All of them are reads for any reader (`analytics:read`), inside the sites of
+  the host's grant. A public link's token is refused with
+  `FEDERATION_PUBLIC_FORBIDDEN`.
+
+A host's own dashboard gets the same reads from `exposeAnalyticsApi`, whose
+authorizer sees them as the operations `lead.daily`, `meta.status` and
+`meta.conversions`. Server code calls the component through the `Rastro` class:
+`leadsDaily`, `metaStatus` and `metaConversions`, typed as `LeadsDaily`,
+`MetaStatus` and `MetaConversion`.
+
+## Reads
+
+`null` means unknown, never zero. A spend of `null` says no synced ad account
+covers that row: the site links none, its accounts are still in their first
+backfill ("syncing"), the origin is organic, the accounts bill in two
+currencies, or the host predates the field. A spend of `0` says a synced account
+covered the row and spent nothing. The new fields are optional in the types so a
+reader handles hosts on older releases; treat an absent field like `null`.
+
+Money is in integer cents: Meta reports spend as a decimal string in the ad
+account's currency, and Rastro stores it rounded to cents. All times are Unix
+epoch milliseconds and ranges are inclusive, as in every other report.
+
+### `leads.report` (`leadsReport`)
+
+The arguments are unchanged: one to ten unique `siteIds` and an inclusive
+`from`/`to` of at most 366 UTC days. The answer gains:
+
+- `spendCents`, `impressions` and `clicks` (`number | null`) on `totals`, on
+  each `origins` item and on every campaign, ad set and ad row. Among the
+  origins only `ctwa_ad`, the leads that came from an ad, can carry spend; the
+  organic ones stay `null`.
+- On ad rows: `siteId`, the site the ad brought leads to, for multi-site
+  reports; `creativeType` (`"video"`, `"image"`, `"carousel"` or `"other"`) and
+  `adStatus` (Meta's effective status, such as `"ACTIVE"` or `"PAUSED"`), both
+  `null` until the catalog sync fills them. `thumbnailUrl` is served from the
+  host's storage, because the URLs Meta hands out expire.
+- `bySite`: one row per requested site, in request order, with the site's
+  `leads`, `qualified`, `won` and `revenueCents`, its `spendCents`, and `paid`,
+  the same four counters for the site's `ctwa_ad` leads alone. `paid` is what
+  the spend bought. Each row also says, for that site alone, `spendCurrency`
+  (its synced accounts' currency, `null` without one) and `currencyMismatch`
+  (`true` when that currency is not the site's, or when its accounts bill in two
+  currencies, in which case its `spendCents` is `null`).
+- `spendCurrency`: the currency of the spend in `totals` and the `ctwa_ad`
+  origin, `null` without spend. `currency` stays the sites' currency, the one
+  revenue is in. Spend adds up only in one currency: when the sites' accounts
+  bill in more than one, `totals`, the origins and the campaign tree carry
+  `null` spend, `spendCurrency` is `null` and each site's spend is still in its
+  `bySite` row.
+- `currencyMismatch`: `true` when any site's spend is not comparable with its
+  revenue, or the sites' accounts bill in two currencies. Show the spend, and
+  compute no return from it.
+- `spendIncomplete`: `true` when Meta's rows ran past their own read budget
+  (12,000 per-ad rows for the campaign tree, 12,000 site-day rows for the rest).
+  The campaign, ad set and ad spend is then `null` (all spend, in the far rarer
+  second case). Leads, revenue and, in the first case, the site totals stay
+  exact: linking Meta never makes a report fail.
+
+An ad that spent in the range without bringing a lead is listed too, with zero
+leads, which is how a screen finds the ads that burn budget. An ad of a synced
+account that spent nothing in the range reports `0`; an ad no synced account
+covers reports `null`. Spend reads on budgets of its own (see
+`spendIncomplete`); only the lead rollups count against the report's 12,000 rows
+and `REPORT_INCOMPLETE`.
+
+### `leads.daily` (`leadsDaily`)
+
+The lead funnel per cohort day, for sparklines and "sales × spend per day"
+charts.
+
+- Arguments: one to ten unique `siteIds`, an inclusive `from`/`to` covering at
+  most 92 UTC days, and at most one filter: `adId` for one ad's leads, or
+  `origin` for one origin's (`"ctwa_ad"` for the leads the ads bought). Passing
+  both fails with `INVALID_ARGUMENT`. Without a filter the series counts every
+  lead.
+- Answer: every UTC day the range touches, oldest first, empty days included
+  with zeros: `{ dayStart, leads, qualified, won, revenueCents, spendCents }`.
+- Counting is by cohort, like `leads.report`: a qualification or sale lands on
+  the day its lead first arrived.
+- `spendCents` is that day's spend for the same scope: the site's ads, one ad,
+  or, with `origin: "ctwa_ad"`, the ads again. It is `null` for an organic
+  origin and for sites no linked ad account covers. Spend keeps the ad account's
+  local date while cohorts use the UTC day, so a daily chart may show a day of
+  skew; totals over a week or more agree.
+
+### `meta.status` (`metaStatus`)
+
+Where each site stands with Meta.
+
+- Arguments: one to ten unique `siteIds`, and optionally `now`, the reader's
+  clock in milliseconds (a query never reads the clock), for the sent counts. A
+  host from before this field refuses an unknown argument, so a dashboard passes
+  `now` only to hosts on this version.
+- Answer, one entry per site:
+
+```ts
+{
+  siteId: string;
+  linked: boolean;
+  adAccounts: Array<{
+    adAccountId: string; // "act_…"
+    name: string;
+    currency: string;
+    timezone: string;
+    syncState: "backfill" | "live" | "error";
+    lastSyncAt: number | null;
+    lastError: string | null;
+    // The first backfill: 30-day blocks read of the total (3 for 90 days).
+    // null once the account has synced.
+    backfill?: { done: number; total: number } | null;
+  }>;
+  pixel: {
+    enabled: boolean;
+    pixelId: string | null;
+    source?: "connection" | "token" | null;
+    name?: string | null;
+    lastError?: string | null;
+    own?: boolean; // asked with an owner: whether that owner set the pixel
+    testMode?: boolean; // a test event code is set
+  }
+  conversions: {
+    pending: number;
+    sent: number;
+    failed: number;
+    // Accepted by Meta in the last 30 UTC days (today and the 29 before), by
+    // event, and today alone. null without `now`.
+    last30d?: {
+      Purchase: number;
+      QualifiedLead: number;
+      Lead: number;
+      Schedule: number;
+    } | null;
+    sentToday?: number | null;
+  }
+}
+```
+
+It never carries a token. `lastError` starts with a code: `META_TOKEN_INVALID`
+(Meta refused the token; every account it fed stops until the host pastes a new
+one), `RATE_LIMITED` (the sync is backing off), `META_UNAVAILABLE`,
+`META_TRUNCATED`, `RUN_TIMEOUT` or `SECRETS_KEY_MISSING`. The `conversions`
+counters count the site's whole send queue by status (see
+[Conversions](#conversions)); a removed lead leaves them, and its sends leave
+`last30d` and `sentToday`. Those two come from per-day counters, read through an
+index (at most 31 days times 8 shards), never from a scan of the queue.
+`backfill` reads the sync's own cursor: a blocked or slow backfill shows where
+it stopped. With `testMode` the pixel has a `testEventCode`: its events reach
+only Events Manager's Test Events, never the ads' optimization, so a screen
+should say so ("modo de teste: as vendas vão só para o Test Events").
+
+### `meta.conversions` (`metaConversions`)
+
+The conversions queued for or sent to the site's pixel, newest first, for a
+"sent back to Meta" list.
+
+- Arguments: one `siteId`, `limit` from 1 to 50 (default 50), and the cursor:
+  the last row's `createdAt` as `before` and its `eventId` as `beforeEventId`.
+  One call can queue two events in the same millisecond (a sale moved into a
+  mapped column), so pass both; `before` alone pages strictly before that time.
+- Answer:
+
+```ts
+Array<{
+  eventId: string;
+  eventName: "Lead" | "QualifiedLead" | "Schedule" | "Purchase";
+  leadId: string | null;
+  leadLabel: string | null;
+  adId: string | null;
+  adName: string | null; // from the ad catalog, when synced or named
+  valueCents: number | null;
+  status: "pending" | "sent" | "failed";
+  createdAt: number;
+  sentAt: number | null;
+}>;
+```
+
+It never carries the hashed user data a conversion was sent with. `leadLabel`
+and `adId` are the lead's as it is now; `valueCents` is set on `Purchase` only.
+
+## Derived metrics
+
+Rastro stores totals and never a ratio. Cost per lead, per qualified lead and
+per sale, and the return on spend, come from the helpers in `@iann29/rastro/ui`,
+so the dashboard and every host that embeds the screens compute them one way:
+
+```ts
+import { formatReturn, returnBand, rowMetrics } from "@iann29/rastro/ui";
+
+const site = report.bySite?.find((row) => row.siteId === siteId);
+if (site && !report.currencyMismatch) {
+  const metrics = rowMetrics({ ...site.paid, spendCents: site.spendCents });
+  // { costPerLeadCents, costPerQualifiedCents, costPerSaleCents, returnOnSpend }
+  const label = formatReturn(metrics.returnOnSpend); // "9,3x" or "—"
+  const band = returnBand(metrics.returnOnSpend); // "strong", "ok", "weak" or null
+}
+```
+
+The helpers are pure and null-safe: without spend every figure is `null`, a
+count of zero gives a `null` cost, and a spend of zero gives a `null` return.
+`returnBand` starts `strong` at 8x and `ok` at 4x. `formatMoney` and
+`formatReturn` print an em dash for an unknown value, never `R$ 0`.
+
+Compute a cost or a return from counters the spend bought: an ad, ad set or
+campaign row, the `ctwa_ad` origin, or a site's `paid`. The totals and a site's
+own counters include organic leads, which cost nothing, so they would flatter
+the ads. With `currencyMismatch` compute neither.
+
+## Host environment
+
+Four optional env bindings come with the Meta connection. The host declares them
+in its app env and passes them to the component the same way as GeoIP:
+
+```ts
+// convex/convex.config.ts
+const app = defineApp({
+  env: {
+    RASTRO_SECRETS_KEY: v.optional(v.string()),
+    RASTRO_META_FAKE: v.optional(v.literal("true")),
+    RASTRO_META_APP_ID: v.optional(v.string()),
+    RASTRO_META_APP_SECRET: v.optional(v.string()),
+  },
+});
+app.use(rastro, {
+  env: {
+    RASTRO_SECRETS_KEY: app.env.RASTRO_SECRETS_KEY,
+    RASTRO_META_FAKE: app.env.RASTRO_META_FAKE,
+    RASTRO_META_APP_ID: app.env.RASTRO_META_APP_ID,
+    RASTRO_META_APP_SECRET: app.env.RASTRO_META_APP_SECRET,
+  },
+});
+```
+
+- `RASTRO_SECRETS_KEY` encrypts the Meta tokens at rest: 32 random bytes,
+  base64-encoded, for example from `openssl rand -base64 32`. Store it as a
+  deployment secret, a new one per deployment, never in code or chat. Without
+  it, connecting Meta or a pixel is refused with `SECRETS_KEY_MISSING`, and
+  everything else keeps working. A new key cannot read the tokens stored under
+  the old one: connect again after a rotation.
+- `RASTRO_META_FAKE=true` replaces the Meta Graph API with deterministic
+  fixtures, for the example host, demos and tests. Never set it on a customer
+  deployment.
+- `RASTRO_META_APP_ID` and `RASTRO_META_APP_SECRET` are the Meta app behind
+  Facebook Login for Business (the "Amage Rastro" app). The secret lives only
+  here, in each host's env, as a deployment secret; the frontends carry the app
+  id and the login configuration id, which are public. Without both, the login
+  fails with `META_LOGIN_UNAVAILABLE` and a pasted token still connects.
+
+## Security invariants
+
+- Tokens are encrypted at rest with the host's key (AES-GCM), and only the
+  component's actions decrypt them. No query returns a token, `meta.status`
+  included. To replace a token, paste the new one.
+- Rastro never holds a phone number in plain text. To match a conversion, the
+  host sends SHA-256 hashes of the phone, and optionally of its own contact id,
+  with the lead or its stage change. They live only in the send queue, are
+  erased once delivery ends, sent or failed, and no read returns them.
+- Federated writes need two keys. A dashboard connects Meta, links accounts,
+  sets the pixel and maps events only with `metaAds` on the host and
+  `analytics:configure` on both the token and the host's grant (owners and
+  admins), like goals. It always acts as its own Meta owner on the host,
+  `rastro:connection:<connectionId>`, derived from the authorized connection; no
+  argument names an owner. Board columns (`setPipeline`) stay host-only. The
+  writes over the whole owner (`connectMeta`, `refreshMetaAccounts`,
+  `disconnectMeta`) are refused with `FEDERATION_SITE_DENIED`, naming the sites,
+  while the owner still feeds a site the grant no longer covers.
+- What leaves the host's server, exactly, when someone logs in:
+  - the two token exchanges (`POST /oauth/access_token`, the code's and the
+    long-lived trade's) carry the app id, the app secret and the code or the
+    short-lived token **in a form body**, never in a URL;
+  - `GET /debug_token`, only when an exchange did not say how long its token
+    lives: the app's token (`<app id>|<app secret>`) in the `Authorization`
+    header, and the token being inspected in the query, where Meta requires it;
+  - every other call carries the connection's token in the `Authorization`
+    header.
+
+  Nothing of it is logged or returned, and the authorization code is used once
+  and never stored.
+
+- On the federated path a dashboard never takes or undoes what another owner on
+  the host made: linking an account another owner linked to the site, unlinking
+  another owner's link, and replacing or removing another owner's pixel are each
+  `CONFLICT`. The host's own `Rastro` methods can do all of it.
+- A lead's ad click id stays in the host's deployment, as before; no report
+  returns it.
+- Each conversion carries an `eventId` derived from the lead and the event, so a
+  retry never counts twice at Meta.
+
+## The Meta connection
+
+Host-side methods of the `Rastro` class. With `metaAds: true` the federated
+surface serves its own versions to the Rastro dashboard, acting for the
+dashboard connection's owner (see
+[Federated Meta functions](#federated-meta-functions)). Every call to Meta pins
+the Graph API version `v25.0` and sends the token in a header, never in a URL.
+
+```ts
+// An action: validates the token and stores it sealed.
+const { adAccounts } = await rastro.setMetaConnection(ctx, {
+  ownerKey: `uzeai:affiliate:${affiliateId}`,
+  accessToken, // a system user token with ads_read
+});
+// A mutation: the account must be in that listing.
+await rastro.linkSiteAdAccount(ctx, {
+  siteId,
+  ownerKey: `uzeai:affiliate:${affiliateId}`,
+  adAccountId: "act_1029384756",
+});
+```
+
+- `setMetaConnection` (action) validates a Meta token for an opaque `ownerKey`
+  of the host's choosing (`GET /me`), lists its ad accounts
+  (`GET /me/adaccounts`) and stores the token encrypted. The first release takes
+  a system user token with `ads_read` from the owner's own Meta app. Pasting a
+  new token for the same owner replaces the old one and resumes the accounts a
+  dead token had stopped. It fails with `SECRETS_KEY_MISSING` without the key
+  and `META_TOKEN_INVALID` when Meta refuses the token.
+- `listMetaAdAccounts` (action) reads the accounts from Meta again and refreshes
+  the listing a link is checked against. `removeMetaConnection` forgets the
+  token and unlinks every account it fed.
+- `linkSiteAdAccount` (mutation) links a site to one of the listed accounts, at
+  most 20 per site and 500 per connection. **An ad account feeds one site**: its
+  spend is that client's, so linking it to a second site fails with `CONFLICT`
+  (unlink it first). `unlinkSiteAdAccount` stops the account feeding the site
+  and deletes its spend there in scheduled batches, so its spend leaves the
+  reports; a sync in flight writes nothing more once the link is gone.
+  `syncMetaNow` asks for a sync of the site's accounts at once, or right after
+  the one running.
+- `setSitePixel` (action) checks the Conversions API token reaches the pixel
+  (dataset) and stores it sealed; `removeSitePixel` forgets it. `sendLeadEvent`
+  (off by default) decides whether a new lead is sent as `Lead`.
+
+### The sync
+
+Components have no crons, so a single scheduler chain syncs every linked
+account. It takes the accounts whose next sync has come, four at a time, and
+stops by itself when no account is linked; a link, a new token or `syncMetaNow`
+starts it again. Per account, in the account's own timezone:
+
+| When                          | Spend read                      | Catalog                     |
+| ----------------------------- | ------------------------------- | --------------------------- |
+| Right after linking           | 90 days, one 30-day block a run | Every ad, with the last one |
+| Every 45 minutes              | Today and yesterday             | Only ads with leads unnamed |
+| Once a day, from 04:00        | The last 7 days                 | Every ad                    |
+| Once a week, at the daily run | The last 28 days (Meta settles) | Every ad                    |
+
+- Spend comes from `GET /act_…/insights?level=ad&time_increment=1` and is stored
+  per ad and account-local date, in integer cents. A resynced range replaces
+  what Meta no longer lists, so a day corrected to zero disappears.
+- The catalog (`GET /act_…/ads`) fills names, `adStatus` and `creativeType`, and
+  copies each creative's thumbnail (320 px) into the host's storage once.
+- The backfill resumes from its last finished block after a failure, and an
+  account back from a pause of more than 27 days backfills the gap first. Until
+  its first backfill ends, an account's spend reads as unknown.
+- Rate limits: when any of Meta's usage headers passes 75%, or Meta throttles a
+  call, the account's next sync waits at least an hour (longer if Meta says so).
+  Other failures retry after 15 minutes, doubling up to 6 hours.
+- A token Meta refuses stops every account it fed, unless the host pasted a new
+  one meanwhile. A missing `RASTRO_SECRETS_KEY` only delays the sync.
+- A day with more rows than one call reads is read in smaller ranges, down to
+  single days; a day still over the cap keeps what came and the account shows
+  `META_TRUNCATED` in `lastError`.
+- Each run holds its account under its own id: a run that outlives its 15-minute
+  lease is replaced (`RUN_TIMEOUT`) and its late writes are dropped.
+
+### Demos and tests
+
+With `RASTRO_META_FAKE=true` the component answers from the sample agency of
+`@iann29/rastro/ui/sample` instead of calling Meta: four ad accounts
+(`act_1029384756` and three more), their catalog and the spend of every ad day
+by day. Any token works except one containing `invalid`, which is refused like
+an expired token. A token `rastro-fake-sample-token:<days>` moves every date by
+that many whole days. The example host's `seedDemo` moves the whole sample so
+its last day is yesterday (or the day before the `now` it is given), writes the
+leads, and connects, links and syncs the agency through these same methods with
+the matching token, so its demo dashboard shows the sample's numbers as its last
+30 days, sync after sync. `seedDemo({ agency: false })` seeds the web demo
+alone, for tests that do not need the agency.
+
+## Facebook Login for Business
+
+The way in for a manager: a Meta window asks them to choose the business, ad
+accounts and pixels to share with the "Amage Rastro" app, and the screen gets
+the connection without anyone copying a token. The pasted token
+(`setMetaConnection`) stays as the fallback, and a pixel's own Conversions API
+token as plan B.
+
+1. The frontend opens a popup on
+   `https://www.facebook.com/v25.0/dialog/oauth?client_id=<app id>&config_id=<login configuration id>&redirect_uri=<origin>/meta/retorno&response_type=code&state=<random>`.
+2. The callback page posts `{ code, state }` to the opener and closes. The
+   opener checks `state` against the one it drew.
+3. The opener sends `code` and the same `redirectUri` to the host, which calls
+   `connectMetaWithCode` (or, from the Rastro dashboard, the federated
+   `connectMeta`).
+
+```ts
+// An action on the host: the owner is the host's to choose.
+const { adAccounts, pixels } = await rastro.connectMetaWithCode(ctx, {
+  ownerKey: `uzeai:affiliate:${affiliateId}`,
+  code,
+  redirectUri: "https://app.example.com/meta/retorno",
+});
+```
+
+- `connectMetaWithCode` (action) trades the code for a token
+  (`POST /oauth/access_token`, the app id and secret in the form body). How long
+  the token lives comes from the answer (`expires_in`) or, when it says nothing,
+  from Meta (`GET /debug_token`). A **system user token** (Login for Business
+  with a system user configuration) never expires and is kept as it is. A token
+  with **under 7 days** left (a user token from a login without a system user
+  configuration lives for hours) is traded at once for a long-lived one
+  (`grant_type=fb_exchange_token`, about 60 days). If that trade fails, the
+  login still succeeds: the token that came is kept with its expiry, so
+  `expiringSoon` is up at once and the screen asks for a new login in time, and
+  the connection's `lastError` says `TOKEN_EXCHANGE_FAILED` (with nothing of
+  Meta's answer in it). Meta refusing the app's id or secret is
+  `META_LOGIN_UNAVAILABLE`, like a missing env. Then it takes the same path as a
+  pasted token: `/me`, the ad accounts, sealed with `RASTRO_SECRETS_KEY`. It
+  records who authorized (`/me`'s id and name), when, and when the token
+  expires. A code Meta refuses (used, expired, another redirect) fails with
+  `META_TOKEN_INVALID`; without the app env, `META_LOGIN_UNAVAILABLE`. The
+  redirect must be https (http only on `localhost`).
+- Every connect and `listMetaAdAccounts` also lists the **pixels** the accounts
+  own (`GET /act_…/adspixels?fields=id,name`, for the first 100 accounts,
+  deduplicated). An account the token cannot read pixels for is skipped; when
+  Meta throttles or fails on one, the pixels already known are kept.
+- Reconnecting, possibly with another business's token, lines the links and
+  pixels up with what the new token lists: a link to an account it does not list
+  stops with `AD_ACCOUNT_NOT_GRANTED` in `lastError`, a pixel it does not list
+  says `PIXEL_NOT_GRANTED` in `metaStatus` and sends nothing, and both resume as
+  soon as a connect or a refresh lists them again. Only the links of listed
+  accounts resume after a dead token.
+- `metaConnection({ ownerKey })` (query) is what a screen reads: `null`, or the
+  status, `authorizedBy: { name }` (null for a pasted token), `authorizedAt`,
+  `invalidSince` (when Meta first refused the token), `lastError`, `expiresAt`
+  (null when the token never expires, or for a pasted token, whose expiry is not
+  asked), `expiringSoon` (fewer than 7 days left: the screen asks for a new
+  login; a scheduled run sets it, since a query reads no clock), the listed ad
+  accounts each with `linkedSiteId` (the site it already feeds, whoever linked
+  it: one account feeds one site) and the listed pixels. Never a token.
+- `setSitePixel` takes either `{ ownerKey }`, a pixel from that connection's
+  listing that sends with the connection's token (a reconnect carries over), or
+  `{ accessToken }` as before. A pixel outside the listing fails with
+  `NOT_FOUND`. `metaStatus` reports `pixel.source` (`"connection"` or `"token"`)
+  and `pixel.name`. A connection Meta refuses stops its pixels; a token-sourced
+  pixel keeps sending. Removing the connection removes its links and pixels, in
+  scheduled batches. With `ownerKey`, `metaStatus` says for each link and the
+  pixel whether that owner made them (`own`), so a screen can lock the rest.
+- `metaUnlinkPreview({ siteId, adAccountId })` (query) answers what unlinking
+  takes out of the site's reports:
+  `{ spendCents, currency, days, campaigns, partial }`, for the dialog that asks
+  before unlinking. `partial` means a read cap was hit and the figures are a
+  lower bound.
+
+With `RASTRO_META_FAKE=true` any code logs in without the app env, except one
+containing `invalid`, refused like an expired token. A code containing
+`user-token` yields a short-lived user token that is traded for a 60-day one;
+any other, a system user token that never expires; the sample agency lists the
+pixels of Loja X and Pet Mania.
+
+### Board columns and the event map
+
+Conversions follow the host's real board, not Rastro's four stages. The host
+declares its columns; an owner picks which Meta event each one sends.
+
+```ts
+await rastro.setPipeline(ctx, {
+  siteId,
+  columns: [
+    { key: "novo", name: "Novo lead", group: "Prospecção" },
+    {
+      key: "agendado",
+      name: "Agendado",
+      group: "Hora do Show",
+      color: "#f97316",
+    },
+  ],
+});
+await rastro.setLeadStage(ctx, {
+  siteId,
+  leadKey,
+  column: "agendado", // where the lead is now; `stage` may be left out
+  eventId,
+  occurredAt,
+});
+await rastro.setEventMap(ctx, {
+  siteId,
+  columns: { agendado: "Schedule", novo: null },
+  sendLeadEvent: false,
+});
+const map = await rastro.eventMap(ctx, { siteId, now: Date.now() });
+```
+
+- `setPipeline` (mutation): at most 40 columns, in order, with a stable `key`,
+  the pt-BR `name` the host shows, and optional `color` and `group` (the block
+  the board shows it in). Declaring again replaces names and order; a column
+  that is gone leaves the map, one that stays keeps its event. Host-only: the
+  host owns its board.
+- `recordLead` and `setLeadStage` take an optional `column`. A key the pipeline
+  does not declare is ignored, never an error, and so is a move into the column
+  the lead is already in or one older than the lead's last move: a late retry
+  never moves a lead back. `setLeadStage` accepts the column alone, for a move
+  that changes no stage, idempotent by its `eventId` like a stage change. Only
+  an accepted move counts and reaches the event map.
+- `setEventMap` replaces the whole map: each declared column maps to `Lead`,
+  `QualifiedLead`, `Schedule` or null. A key the pipeline does not declare is
+  `INVALID_ARGUMENT`. `sendLeadEvent` turns `Lead` on for every new lead and is
+  kept on the pixel too.
+- `eventMap({ siteId, now? })` answers the columns with `key`, `name`, `color`,
+  `group`, `event` and `monthCount`: the distinct leads that entered the column
+  in the 30 UTC days up to `now` (a lead that leaves and comes back counts
+  once). Pass the caller's clock (queries do not read one), rounded to the start
+  of the day as the dashboard does, so the subscription stays cached all day;
+  without `now`, or before the host sent any column, the count is null. Then
+  `sendLeadEvent`, and `purchase.enabled` (an enabled pixel).
+- **`Purchase` never comes from a column.** It is sent when the host records the
+  sale (`setLeadStage` with `won` and its value). Screens show it as a fixed
+  row, "Venda registrada (com valor) → Compra".
+- A lead entering a mapped column queues its event once per lead per event
+  (`eventId = sha256(leadId + ":" + eventName)`) through the Conversions API
+  queue below, when the move carries `meta`.
+
+### Federated Meta functions
+
+With `metaAds: true`, the federated surface serves the same screen to the Rastro
+dashboard. Every function acts for the dashboard connection's own owner,
+`rastro:connection:<connectionId>`.
+
+| Function              | Kind     | Needs     |
+| --------------------- | -------- | --------- |
+| `metaConnection`      | query    | reader    |
+| `metaEventMap`        | query    | reader    |
+| `metaUnlinkPreview`   | query    | reader    |
+| `connectMeta`         | action   | configure |
+| `refreshMetaAccounts` | action   | configure |
+| `setMetaPixel`        | action   | configure |
+| `disconnectMeta`      | mutation | configure |
+| `linkMetaAdAccount`   | mutation | configure |
+| `unlinkMetaAdAccount` | mutation | configure |
+| `removeMetaPixel`     | mutation | configure |
+| `setMetaEventMap`     | mutation | configure |
+| `syncMetaNow`         | mutation | configure |
+
+The three actions authorize through `authorizeMetaAction`, an internal query the
+host exports from the same `convex/rastroFederation.ts` (an action has no
+database for `resolveConnection`; the caller's identity travels with it). Add
+all of them to the module's exports:
+
+```ts
+export const {
+  // ...
+  metaConnection,
+  metaEventMap,
+  metaUnlinkPreview,
+  connectMeta,
+  disconnectMeta,
+  refreshMetaAccounts,
+  linkMetaAdAccount,
+  unlinkMetaAdAccount,
+  setMetaPixel,
+  removeMetaPixel,
+  setMetaEventMap,
+  syncMetaNow,
+  authorizeMetaAction,
+} = federated;
+```
+
+In `metaConnection`, an account linked to a site outside the grant answers
+`linkedSiteId: null` with `linkedOutsideScope: true`, so the screen greys it out
+without learning the site. `setMetaPixel` uses the connection's listing unless
+it is given an `accessToken`, and enables the pixel unless told otherwise. The
+federated `metaStatus` marks each link and the pixel with `own`: whether this
+dashboard connection made them.
+
+When the host revokes or deletes a dashboard connection's grant, it forgets the
+Meta owner that connection acted as, in the same mutation:
+
+```ts
+await rastro.removeFederatedMetaConnection(ctx, { connectionId });
+// = rastro.removeMetaConnection(ctx, {
+//     ownerKey: federatedMetaOwnerKey(connectionId),
+//   })
+```
+
+### Conversions
+
+`recordLead` and `setLeadStage` accept an optional `meta`: what the host knows
+of the contact, every value already a SHA-256 hex digest (`sha256Hex` below is
+the host's own helper).
+
+```ts
+await rastro.setLeadStage(ctx, {
+  siteId,
+  leadKey: conversation._id,
+  stage: "won",
+  revenueCents: 45_990,
+  eventId: activity._id,
+  occurredAt: activity.createdAt,
+  meta: {
+    ph: [await sha256Hex(phoneE164Digits)], // "5511999991234"
+    externalId: await sha256Hex(contact._id),
+  },
+});
+```
+
+Hash the phone as Meta normalizes it: digits only, with the country code and no
+`+`. `meta` never fails the call: anything but that shape with 64-character hex
+digests (a plain phone number, more than 10 phones, a wrong type) is ignored as
+a whole, the lead is recorded as usual and no conversion is queued. The
+component never stores it, and the warning it logs never repeats it. The hash of
+an empty string matches nobody and is left out.
+
+With an enabled pixel whose token Meta has not refused, a call with `meta`
+queues one conversion:
+
+| Event                               | When                                                                       |
+| ----------------------------------- | -------------------------------------------------------------------------- |
+| `Purchase`                          | `setLeadStage` with `won` and a value; `value` and `currency` (the site's) |
+| `Lead`                              | `recordLead` creating the lead, only with `sendLeadEvent` on the pixel     |
+| `Lead`, `QualifiedLead`, `Schedule` | The lead enters a board column the site's event map points at              |
+
+`Purchase` never comes from a column: only a recorded sale sends it. And
+`setLeadStage` with `qualified` sends nothing by itself: `QualifiedLead` comes
+only from a board column the host's event map points at, because the host's
+columns, not Rastro's four stages, say what "qualified" means for that business.
+Without `meta`, without a pixel, or with the pixel off, nothing is queued and
+the call succeeds as before.
+
+Each event goes **once per lead**: its `eventId` is
+`sha256(leadId + ":" + eventName)`, so a lead that comes back to a column, or a
+`Lead` reached both as a new lead and through a column, is not sent twice. This
+holds for `Purchase` too: its value is the lead's sale total as Rastro has it,
+so a corrected value or a second sale of the same lead sent again would count
+the money twice at Meta. A repeat purchase is a new lead for the host to record.
+
+"Once" means queued or delivered. An event that **failed** for good is opened
+again, with its attempts back to zero and the new hashes, when the host sends
+`meta` for it again (the next stage change or column move that reaches it).
+Inside the component, the column path is the exported
+`enqueueColumnEvent(ctx, { siteId, leadId, eventName, at, meta })` in
+`metaCapi.ts`.
+
+The send starts at once (`POST /{pixelId}/events`, Graph API `v25.0`, the
+pixel's token in the `Authorization` header) with `action_source: "chat"`,
+`event_time` in seconds, `user_data.ph`, `user_data.external_id`, `country` (the
+hash of `br`), `custom_data.value` and `currency` on `Purchase`, and the pixel's
+`test_event_code` when set. Then:
+
+- A failure retries after 1 minute and then 10 minutes: three attempts in all. A
+  permission error fails at once. Anything else that goes wrong in a send (not
+  an answer from Meta) counts as an attempt too, and the last one fails with
+  `lastError` starting `UNEXPECTED`.
+- No event stays pending: while any is, a scheduler chain (no cron) checks every
+  15 minutes or so for one whose attempt was due more than 15 minutes ago, a
+  send lost on the way, and sends it again, counting the lost attempt. Each send
+  takes a 15-minute lease on its attempt, so the chain never counts one that may
+  still be in flight. It keeps the limit of three attempts and the 7-day cap,
+  reads 25 rows at a time through an index, and stops by itself when nothing is
+  pending.
+- A token Meta refuses stops whoever owns it, and only if it is still the stored
+  one: a token pasted (or a connection renewed) meanwhile keeps sending.
+- A pixel's own token Meta refuses fails the event and stops the pixel: nothing
+  more is queued for the site until `setSitePixel` stores a token again. A
+  connection's token refused marks the connection invalid, which stops its
+  pixels and ad accounts until it is connected again.
+- An event older than 7 days when its turn comes is not sent: it fails with
+  `EVENT_TOO_OLD`. A pixel removed or turned off before the send fails it with
+  `PIXEL_UNAVAILABLE`.
+- Sent or failed, the event's hashes are erased; the row stays, without them, as
+  the site's conversion history (`meta.conversions`, the counters of
+  `meta.status`).
+- `removeLead` deletes the lead's conversions with it.
+- With the pixel's `testEventCode` set, every event carries it and Meta keeps it
+  in Test Events only; `meta.status` reports `pixel.testMode`.
+
+Under `RASTRO_META_FAKE=true` every send is accepted (a token containing
+`invalid` is refused like an expired one) and nothing leaves the deployment.