| name | connected-provider-integration |
| description | Add or materially change a connected fitness-provider integration in Quantified Self. Use for Garmin, Suunto, COROS, Wahoo, or new-provider OAuth, webhooks, activity/history/route/sleep ingestion, delivery, disconnect, provider UI, documentation, and operational coverage. |
Connected Provider Integration
Implement the full provider lifecycle: secure connection, idempotent ingestion or delivery, safe persistence, useful product states, and clean removal.
Read First
Read docs/provider-integration-guide.md completely. Read the closest existing provider implementation and the relevant queue, event-writer, route, and Firestore Rules code before introducing a new pattern.
Product Contract
Define the supported resources and lifecycle before coding: activities, routes, sleep, history, outbound delivery, entitlement, disconnect behavior, and user-visible limitations. Choose explicitly between direct delivery, webhook delivery, history backfill, or a combination.
Implementation Checklist
- Implement OAuth identity and token lifecycle with callback validation, least-privilege scopes, and no credential logging.
- Authenticate webhook requests and make history and webhook ingestion idempotent. Queue durable work instead of holding long provider calls in request handlers.
- Preserve original-file provenance and provider attribution. Sanitize every event/activity write with the shared Firestore sanitizer helpers; never persist streams or top-level event activities.
- Cover disconnect, subscription changes, provider errors, retries, account deletion, and queued-work deletion guards.
- Add the frontend connection/status/error states, help content, and an intentional
/integrations/<provider> page when it has product or search value.
- Update the provider matrix, lifecycle guidance, operational coverage, pitfalls, and release checklist in
docs/provider-integration-guide.md.
Verify
Run the narrowest frontend and Functions specs, Firestore/Storage Rules tests when access changes, and npm --prefix functions run build for backend work. Build the frontend for changed user-facing flows.
Guardrails
- Do not call real provider APIs, deploy, publish, or change cloud configuration during implementation.
- Do not expose secrets, provider payloads containing personal data, or token values in fixtures or logs.
- Do not add a provider as "connected" until the corresponding disconnect and failure states work.
