Cookbook
The Fitness API Cookbook
Runnable reference implementations of the patterns the rest of this site documents in prose: rotation-safe token refresh, webhook ingestion that survives duplicates and reordering, and rate-limit handling that degrades instead of hammering. Every recipe is dependency-free JavaScript with an injected clock, fetch, and store, ships with a node:test suite, and runs in CI on every change — the code on each page is a byte-verbatim copy of the file that passed. Read the theory on the linked pages; take the working version from here.
The theory lives in Troubleshooting, Architecture, and Testing — each recipe links its source pages. MIT-licensed; adapt freely.
Auth & API clients
The failure modes that break every user at once.
- Recipe: Single-Flight Refresh-Token RotationA dependency-free, tested token client: one refresh per user, the rotated token persisted atomically, one retry on 401, a dead grant on invalid_grant.UpdatedVerified August 12, 2026
- Recipe: A Rate-Limit-Aware Fetch WrapperA tested, dependency-free fetch wrapper: per-user budgets, Retry-After in both forms, full-jitter backoff, a breaker that degrades, and no unsafe retries.UpdatedVerified August 12, 2026
Data ingestion
Webhooks and backfills that survive duplicates, reordering, and outages.
- Recipe: A Replay-Safe Health Webhook ReceiverA tested, dependency-free ingest function: signature over raw bytes, delivery dedupe, thin pointer jobs, versioned replace, and a DLQ that still acks.UpdatedVerified August 12, 2026
- Backfill Checkpointer: A Resumable Window WalkerRunnable JavaScript for a newest-first backfill: checkpoint after each window, retry the same window on 429, and record gaps instead of skipping.UpdatedVerified August 12, 2026
Correctness & motion
The rollup that survives DST, and the rep counter that earns its counts.
- Day-Boundary Rollup: Grouping Samples by Civil DateRunnable, dependency-free JavaScript that stamps a civil date at ingest and rolls up on it, so 23- and 25-hour days and travel days stay correct.UpdatedVerified August 12, 2026
- Rep Counter: A State Machine and the Scorer That Guards ItRunnable JavaScript rep counter: EMA smoothing, hysteresis, debounce and rep events, plus a per-clip precision and recall scorer with no aggregates.UpdatedVerified August 12, 2026
Frequently asked questions
- How is the cookbook code tested?
- Every recipe ships with a node:test suite in the same directory, and a CI workflow runs the full suite on every change to the cookbook — the code you see on a recipe page is a byte-verbatim copy of the file that passed. Tests inject fakes for the clock, fetch, and storage, so they exercise the logic (races, rotations, retries, DST transitions) without any network or provider account.
- Can I use these recipes in a commercial product?
- Yes — the cookbook files are MIT-licensed, stated in each file's header. They are deliberately dependency-free and built around injected interfaces (store, fetch, clock), so adapting one usually means implementing a small store interface against your database and deleting the in-memory reference version. Attribution is appreciated, not required.
- Why does the cookbook avoid npm dependencies entirely?
- Because reference code you can read end-to-end in one file is worth more than a cleverer implementation you cannot audit. Zero dependencies means no supply-chain surface, no version drift against your stack, and no framework assumptions — every recipe is plain modern JavaScript on Node 20+, portable into TypeScript or another runtime by hand without untangling a dependency tree.