@iann29/rastro 0.9.0 → 0.10.0

package/docs/federation.md

@@ -62,6 +62,21 @@ The exact generated surface is:
   `listFunnels`, `upsertFunnel`, `removeFunnel`, `listAffiliates`,
   `upsertAffiliate`, `removeAffiliate`, `retentionStatus`, `setRetentionPolicy`,
   and `disableRetentionPolicy`
+- the tracked links (optional capability `trackedLinks`, hosts from `0.5.0`):
+  `listTrackedLinks` for any reader, and `createTrackedLink`,
+  `updateTrackedLink`, and `deleteTrackedLink`, which need `analytics:configure`
+- `getVisitorProfile` and `listPeople` (optional capabilities `visitorProfiles`
+  and `people`, hosts from `0.6.0`); see
+  [Identified visitor profiles](#identified-visitor-profiles)
+- `transferConnection` (optional capability `transfer`, hosts from `0.2.0` that
+  pass the callback); see
+  [`federation-setup.md`](federation-setup.md#transfer-a-connection-to-another-organization)
+- the lead reads (opt-in capability `leads`, hosts from `0.8.0` that pass
+  `leads: true`): `leadsReport`, `listLeads`, `leadJourney`, and, from `0.10.0`,
+  `leadsDaily`
+- the Meta reads (opt-in capability `metaAds`, hosts from `0.10.0` that pass
+  `metaAds: true`): `metaStatus` and `metaConversions`; see
+  [Leads and Meta ads](#leads-and-meta-ads)
 
 Hosts from `alpha.11` also advertise the optional capability `localDays`: their
 `overview` answers a daily range that covers whole calendar days in the site's
@@ -338,7 +353,7 @@ the dashboard never calls them for a read-only connection.
 | `FEDERATION_ISSUER_MISMATCH`     | Identity came from another issuer                                   |
 | `FEDERATION_INVALID_CLAIMS`      | Required bounded claims or permission absent                        |
 | `FEDERATION_CONNECTION_DENIED`   | Connection missing, revoked, or malformed                           |
-| `FEDERATION_INVALID_SCOPE`       | Requested site list violates public limits                          |
+| `FEDERATION_INVALID_SCOPE`       | Requested site list violates limits, or capability not opted in     |
 | `FEDERATION_SITE_DENIED`         | Requested site is outside the connection                            |
 | `FEDERATION_CONFIGURE_FORBIDDEN` | Token or grant lacks `analytics:configure`                          |
 | `FEDERATION_PUBLIC_FORBIDDEN`    | Public token outside its surface, or grant lacks `analytics:public` |
@@ -354,6 +369,9 @@ Consumers should branch on `ConvexError.data.code`, not human-readable messages.
 - A public token runs only the public surface, and only when the grant lists
   `analytics:public`; `rastro_site_ids` narrows every token to the granted sites
   it names.
+- A lead or Meta read runs only on a host that opted into its capability
+  (`leads`, `metaAds`); connecting Meta ad accounts or a pixel is never part of
+  the surface.
 - Report queries must request one through ten unique, bounded site IDs.
 - The resolved connection ID and organization must match the token.
 - Revoked, missing, malformed, empty, or duplicate-site connections are denied.
@@ -429,3 +447,30 @@ to one site and filter. This query requires `analytics:read`; public tokens
 cannot list people. Profile writes and the bounded `backfillVisitorProfiles`
 upgrade remain host-authorized operations outside federation. See
 [the directory contract and upgrade steps](identity.md#project-defined-attributes-and-the-people-directory).
+
+## Leads and Meta ads
+
+Two opt-in capabilities carry what a host's server reports rather than what the
+tracker sees. The host turns each on in `exposeFederatedAnalyticsApi`:
+
+- `leads: true` (hosts from `0.8.0`) advertises `leads` and serves
+  `leadsReport`, `listLeads`, `leadJourney` and, from `0.10.0`, `leadsDaily`:
+  the leads its server records, counted by cohort per origin, per campaign → ad
+  set → ad, and per day.
+- `metaAds: true` (hosts from `0.10.0`) advertises `metaAds` and serves
+  `metaStatus` and `metaConversions`: the Meta ad accounts and pixel each site
+  links, and the conversions sent to the pixel.
+
+Without the option a host refuses those functions with
+`FEDERATION_INVALID_SCOPE` before it examines the connection, and its manifest
+neither advertises the capability nor names them, so a dashboard hides what they
+feed. Both are reads for any reader (`analytics:read`) inside the grant's sites;
+a public link's token is refused with `FEDERATION_PUBLIC_FORBIDDEN`. The Meta
+spend inside `leadsReport` and `leadsDaily` needs no flag: it is `null`, meaning
+unknown, until a site links an ad account. With `metaAds: true` the surface also
+serves the dashboard's own Meta setup (connecting Meta, linking ad accounts, the
+pixel and the event map) as `analytics:configure` writes that act for the
+dashboard connection's owner, and the host exports `authorizeMetaAction` for its
+actions. No function of the surface returns a token or the hashed user data of a
+conversion. See [Meta ads](meta-ads.md) for the shapes, the host environment,
+and the security invariants.