Partner sharing: reading an athlete's fueling profile, profile_sharing and the two sharing webhooks

[DrAlexHarrison]

Depends-On: SaturdayInc/fuel-backend#1759

What changes for a partner reading the docs

Before. The onboarding guide and the onboarding journey said an athlete's Saturday app answers are "never exposed through the API" and that the athlete can share "from app settings", with no route, field or webhook behind it. The freemium page said email matches link automatically.

After.

• New page Reading an athlete's fueling profile (guides/fueling-profile, Core Guides, after Onboarding Journey). LLM-first: the three sharing states (not_linked, off, on), every move between them with the webhook it sends, what the athlete sees (a switch per connected partner app in Preferences; the hosted finish-screen choice confirmed from an email; nothing under 18; no expiry), a narrated journey with "your code" at each beat, then the reference for GET /v1/athletes/{athlete_id}/fueling-profile: Python and TypeScript samples, full JSON for on, off and not_linked, every field, calculations_use, errors.
• profile_sharing on GET /v1/athletes/{id} (Athletes page, and its own section on the new page).
• Webhooks: athlete.profile_sharing_changed and athlete.fueling_profile_updated in the events table, the data table, and a payload section. Both carry the athlete record as GET returns it (profile_sharing included); the second adds changed_fields, names only. Event ids for these two are evt_ + 32 hex, stable across a redelivery.
• MCP: get_fueling_profile in the tool catalog, partner connections only; the Claude connector page notes it is absent there.
• Onboarding guide line 79 and onboarding journey line 51 now describe what ships, and link the new page. Freemium Model: an email match links once the athlete confirms Saturday's email; profile data reaches a partner only by sharing.
• llms.txt: both GET routes, a short Athlete Profile Sharing section, the guide link.

Fixed along the way

• Webhooks said every event id is a UUID. An athlete.deleted for a deleted Saturday account is athlete_deleted_{athlete_id} (since Webhooks: athlete.deleted on an account deletion, and on the coach lane #63), and the sharing events are evt_…; the page now says to treat ids as opaque.
• Webhooks said athlete.created / updated / profile_completed carry the record "as GET returns it"; they lack the two fields computed on read (subscription_status, profile_sharing). Now stated.

Verified against fuel-backend #1759 head cbc1bcea

Every claim checked against the diff: pkg/api/fueling_profile.go (states, messages, ownership 404, consumer 404, calculations_use from the calculation's manifest precedence), pkg/partner/sharing.go (per-partner key only, all ignored, the aiage under-18 rule reading as off), pkg/partner/appprofile.go (value formats and ranges), pkg/partner/sharing_watch.go (when each webhook fires, one per linked athlete record, the record read at send time), pkg/partner/sharing_confirmation.go (verified address, 7-day link, 10-minute resend gap, three sends), pkg/mcp (partnerOnlyTools), pkg/gateway (athlete_scope for a delegated token naming another athlete).

Checks

• scripts/check-docs-drift.py --backend <fuel-backend at #1759 head>: clean (128 operations, 18 events). Against fuel-backend main it fails until #1759 lands, which is why this waits on it: the hourly Docs Drift run would go red.
• test-response-examples.py: the new page's Python and TypeScript samples run against the page's three response examples (and fail when the sample is broken).
• check-engine-constants.py, check-app-claims.py, mint validate, mint broken-links --check-anchors: clean.
• Renders, 375 and 1440, headless: /home/claude-tmp/claude-1000/psharing-docs/renders/.

Landing order

After fuel-backend #1759 lands. The page also describes saturday #3691 (the app switch) and sweb #664 (the hosted finish screen); both are open.

🤖 Generated with Claude Code