A starter project for your fitness API integration

• package.json
• src/vendors.mjs
• src/oauth.mjs
• src/tokenStore.mjs
• src/webhooks.mjs
• src/server.mjs
• .env.example
• .gitignore
• README.md

# fitness-integration

A Node.js + Express skeleton for Oura, WHOOP, generated by https://aifitnessapi.com/tools/starter-scaffold on the facts the site had verified as of 2026-11-05. Every endpoint, header and signing rule below links the page that sources it; re-check them before you ship, because vendors change.

## Run it

```sh
npm install
cp .env.example .env   # fill it in
npm start   # http://localhost:3000
```

## Routes

| Route | What it does |
|---|---|
| `GET /oauth/{vendor}/start?user=<your user id>` | Redirects to the vendor's authorize URL with a state (and a PKCE challenge where the vendor documents PKCE) |
| `GET /oauth/{vendor}/callback` | Checks state, exchanges the code, saves the grant through the token store |
| `GET/HEAD/POST /webhooks/{vendor}` | Answers the vendor's handshake, checks its signature or token, acknowledges fast and hands the event to `handleEvent` |

## Per vendor

### Oura

- Authorize: `https://cloud.ouraring.com/oauth/authorize`; token: `https://api.ouraring.com/oauth/token` (client credentials in the form body).
- Oura marks PKCE as recommended; the skeleton sends an S256 code_challenge and the code_verifier on the exchange.
- Oura's refresh token is single-use: store the new pair after every refresh.
- Webhooks: HMAC-SHA256, keyed by your client secret, over the x-oura-timestamp value followed by JSON.stringify(body); hex, upper-case, in x-oura-signature.
- Respond quickly (under 10 seconds) with a 2xx status, and process the event asynchronously.
- Oura retries failed deliveries 10 times each for 4xx responses, 5xx responses and timeouts, for about an hour.
- A 410 response cancels the subscription.
- Sources: https://aifitnessapi.com/integrate/oura-api and https://cloud.ouraring.com/v2/static/json/openapi-1.43.json

### WHOOP

- Authorize: `https://api.prod.whoop.com/oauth/oauth2/auth`; token: `https://api.prod.whoop.com/oauth/oauth2/token` (client credentials in the form body).
- WHOOP issues a refresh token only when you request the offline scope.
- WHOOP says a state you generate must be eight characters long.
- A refresh invalidates the previous tokens, and two simultaneous refreshes for one member fail: refresh on a schedule, one at a time.
- Webhooks: HMAC-SHA256, keyed by your app's client secret, over the X-WHOOP-Signature-Timestamp value followed by the raw body; base64, in X-WHOOP-Signature.
- Return a successful 2XX; WHOOP recommends doing so within a second and processing asynchronously.
- WHOOP retries failed deliveries five times over about one hour; anything other than a 2XX, or no response before timing out, counts as failed.
- Duplicates are possible: use trace_id to detect them.
- Sources: https://aifitnessapi.com/integrate/whoop-api and https://developer.whoop.com/docs/developing/webhooks/

## Before production

- **Replace the in-memory stores.** `TokenStore` and the OAuth state store keep data in process memory so the skeleton runs with no database. Implement the interface against your database, and encrypt tokens at rest: https://aifitnessapi.com/cookbook/token-vault.
- **Wire `user` to your own auth.** The start route takes the user id as a query parameter only so the skeleton is self-contained.
- **Make `handleEvent` enqueue, not fetch.** Acknowledge first; fetch the record the event points to from a worker: https://aifitnessapi.com/cookbook/webhook-receiver.
- **Refresh tokens one at a time per user**, and store every rotated refresh token: https://aifitnessapi.com/cookbook/refresh-rotation.

Checked by: node --check, and the test starts the server.