WHOOP

Local emulators. Real API contracts. Part of Mockingbird.

WIP WHOOP v2 emulator for synthetic workout, sleep, recovery and cycle synchronization.

#Install

bun add @crvouga/mockingbird-service-whoop

#Usage

import { createServer } from "@crvouga/mockingbird-service-whoop/server"

// Test setup: a local WHOOP. The application's API base is its URL plus /developer.
const server = await createServer()
const baseUrl = `${server.url}/developer`

// Application code: the request it sends to WHOOP.
const response = await fetch(`${baseUrl}/v2/activity/workout`, {
  headers: { authorization: "Bearer mock_whoop_token" },
})
const { records } = await response.json()

await server.close()

Run mockingbird-whoop serve --port 12129. Inject the local origin plus /developer as the consumer API base, and the origin alone as OAuth base. Consumer endpoint wiring is separate from this emulator.

#Routes and state

POST /oauth/oauth2/token accepts form-encoded authorization-code or refresh-token grants with client credentials. Seed clients, codes, and grants via options or admin state. Default emulator client: mock_client / mock_client_secret; default bearer mock_whoop_token and refresh mock_whoop_refresh. The default grant has all four read scopes and offline. Codes bind client, optional redirect and optional S256 PKCE challenge. Codes are single-use, including concurrent exchanges. New tokens expire after 3600 seconds (tokenTtlSeconds is configurable). Refresh invalidates both old access and refresh tokens, keeps the same user/scopes, and issues a refresh token only for an offline grant.

GET /oauth/oauth2/auth is the authorization endpoint a browser visits to connect a member. There is no consent page: the request is validated, then the consents collection answers for the user and the browser is redirected (302) to redirect_uri with code and state, or error, error_description and state. The code is stored in codes bound to the client, the exact redirect_uri, the granted scopes (so the token's scope is what was requested, and refresh_token appears only with offline) and an optional S256 code_challenge; POST /oauth/oauth2/token redeems it once. An unknown client (401 invalid_client), a missing client_id or redirect_uri, or a redirect_uri the client did not register (400 invalid_request, JSON {error,error_description}) is answered in place and never redirected to. Clients take optional redirectUris (exact match; omitted accepts any absolute http(s) URI so the default mock_client works as is) and scopes (omitted allows the documented WHOOP scopes). Redirected errors: invalid_request (no response_type, or a code_challenge_method other than S256), unsupported_response_type, invalid_scope, invalid_state (missing or under 8 characters). A longer state is echoed unchanged.

Consent controls: rows {id, decision: "approve"|"deny"|"error", userId?, codeTtlSeconds?, error?, errorDescription?} where id is a client id or * (every client without its own row). Seed with the consents option or POST /__admin/state/consents {"id":"*","value":{"id":"*","decision":"deny"}}. No row means approve for synthetic-user with a 600 second code. deny redirects access_denied and error redirects server_error (override with error/errorDescription), both with the unchanged state and no code. Issued codes are listed at GET /__admin/state/codes.

GET /developer/v2/user/profile/basic returns the token user's {user_id,email,first_name,last_name}: seed a records row with collection: "profile", userId the token's user and data the profile (fake values only). Scope read:profile is required (403 {detail:"Access forbidden."} like the collections, 401 for an unknown or expired token, 404 {detail:"Not Found"} when the user has no profile row). The default grant does not carry read:profile.

GET /developer/v2/activity/workout, /developer/v2/activity/sleep, /developer/v2/recovery, /developer/v2/cycle return {records,next_token}. limit defaults to 10, maximum 25; nextToken continues pages. Results sort newest start first; start includes equal timestamps, end excludes equal starts and defaults to emulate now. The collection time-window implementation uses start timestamps, including activities spanning the end instant. Scope names are read:workout, read:sleep, read:recovery, read:cycles.

Seed records: [{key,userId,collection,data}]; data is a synthetic provider-shaped record. Recovery has cycle_id and sleep_id, not id, start, or end: seed a matching sleep record to supply its time window. This corrects the issue's generic recovery field list using the official schema. Missing related-sleep fixtures are excluded. Cycle ids remain numbers; workout/sleep ids remain UUIDs. Metrics and score states are passed through, preserving null or absent metrics. Distinct storage keys can model duplicate vendor records. Cursor internals are local stand-ins; consumers must retain the same query while paginating.

#Test controls

Standard relocatable /__admin health/state/reset/clock/journal/Timeline/fault routes. State collections contain only synthetic fixtures. Header namespaces, /__admin/ns/<name> paths and bearer-credential mappings isolate state. Journals record metadata, not OAuth or health bodies. Presets unauthorized, rate_limited, server_error, connection_drop support deterministic failures; generic faults add latency. Preset error bodies are scripted local fixtures, not claims of exact quota/error wording. No webhooks are required.

#Oracle and tests

Derived from the official OpenAPI, OAuth reference, and refresh example. The contract retains the official collection response schemas. Authorized live data and OAuth success were not probed; no live credentials used.

Best guess, not oracle-verified: the authorization endpoint and the profile route are not observed live. /oauth/oauth2/auth and /oauth/oauth2/token are Ory Hydra paths, so redirect status (302), the error/error_description/state redirect shape, the 8 character state minimum, and the error codes follow Hydra and its fosite library plus the WHOOP OAuth page. The statuses and JSON bodies for an unknown client or unregistered redirect_uri (Hydra renders an error page on the live service), the invalid_scope allow-list, treating a missing scope as an empty grant, S256-only PKCE, access_denied/server_error for consent controls, and the 403 for a missing read:profile scope are the emulator's choices, not observed vendor responses. The profile shape is the official UserBasicProfile schema.

bun test runs acceptance, all-operation self-parity and divergence detection. bun scripts/python-smoke.ts uses uv to run actual requests 2.32.5 and httpx 0.28.1 against local HTTP. It is not the private consumer itself. bun run parity requires WHOOP_ACCESS_TOKEN and performs a safe collection-envelope probe without printing health data.

#Deliberately not modelled

No real users, device pairing, sensors, a consent page (the consents rows stand in for the user's answer), hardware SDK, webhook delivery, body measurements, partner APIs or scoring computation. No cursor-format parity, real quota enforcement, concurrent refresh grace period or private-client integration claim. Partial synthetic records can be seeded deliberately; validate production fixtures against the supplied official schemas. Recovery relies on matching synthetic sleep fixtures.

#API

Root runtime exports: WhoopAPI, WHOOP_NAMESPACE, COLLECTION_SCOPES, KNOWN_SCOPES, MIN_STATE_LENGTH, createRuntime, WHOOP_PRESETS, document, operationIds, supportedOperationIds. Types: WhoopAPIOptions, Grant, OAuthCode, Client, Consent, DataRecord, CollectionName, WhoopRuntimeOptions, WhoopRuntime, OperationId, SupportedOperationId.

/server: createServer, serveTarget, DEFAULT_PORT; types WhoopServerOptions, WhoopServer.