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.
1---2name: connected-provider-integration3description: 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.4---56# Connected Provider Integration78Implement the full provider lifecycle: secure connection, idempotent ingestion or delivery, safe persistence, useful product states, and clean removal.910## Read First1112Read `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.1314## Product Contract1516Define 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.1718## Implementation Checklist19201. Implement OAuth identity and token lifecycle with callback validation, least-privilege scopes, and no credential logging.212. Authenticate webhook requests and make history and webhook ingestion idempotent. Queue durable work instead of holding long provider calls in request handlers.223. 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.234. Cover disconnect, subscription changes, provider errors, retries, account deletion, and queued-work deletion guards.245. Add the frontend connection/status/error states, help content, and an intentional `/integrations/<provider>` page when it has product or search value.256. Update the provider matrix, lifecycle guidance, operational coverage, pitfalls, and release checklist in `docs/provider-integration-guide.md`.2627## Verify2829Run 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.3031## Guardrails3233- Do not call real provider APIs, deploy, publish, or change cloud configuration during implementation.34- Do not expose secrets, provider payloads containing personal data, or token values in fixtures or logs.35- Do not add a provider as "connected" until the corresponding disconnect and failure states work.
jimmykane