@crvouga/mockingbird-service-whoop 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,5 @@
1
+ # Changelog — @crvouga/mockingbird-service-whoop
2
+
3
+ ## 0.1.0 (2026-10-05)
4
+
5
+ Initial release.
package/DISCOVERY.md ADDED
@@ -0,0 +1,55 @@
1
+ # @crvouga/mockingbird-service-whoop discovery
2
+
3
+ This is the installed-package index for coding agents and tooling. All relative links resolve
4
+ inside `node_modules/@crvouga/mockingbird-service-whoop/`; no repository checkout is needed to discover the mock's
5
+ supported surface or documented behavior.
6
+
7
+ ## Capability and behavior sources
8
+
9
+ | Question | Authoritative file | What it contains |
10
+ | --- | --- | --- |
11
+ | Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
12
+ | Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
13
+ | Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
14
+ | Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
15
+ | Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `mockingbird.discovery`. |
16
+
17
+ Read these together: the contract/capability matrix says *what* is available, while the README
18
+ defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
19
+ If prose and an executable surface disagree, report a parity mismatch instead of adding a
20
+ consumer-side workaround.
21
+
22
+ ## Parity and oracle
23
+
24
+ - Declared parity surface: **OAuth refresh and wearable collection windows**.
25
+ - Parity tier: **cold** (the repository controls when live checks run).
26
+ - Oracle: **Live vendor API or sandbox**.
27
+ - Repository command: `bun run parity:service -- whoop`.
28
+ - Evidence model: Run from a Mockingbird checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
29
+
30
+ The npm package contains evidence summaries and the exact contract, not credentials or the
31
+ repository-only parity harness. Self-parity/property and acceptance tests run in the Mockingbird
32
+ repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
33
+
34
+ ## Runtime introspection
35
+
36
+ - `GET /__admin/health`
37
+ - `GET /__admin`
38
+ - `GET /__admin/state`
39
+ - `GET /__admin/requests`
40
+ - `GET /__admin/metrics`
41
+ - `GET /__admin/faults/presets`
42
+ - `GET /__admin/ui`
43
+
44
+ For HTTP services, use `x-mockingbird-namespace` (or the documented credential/path carrier) so
45
+ parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
46
+ designed for assertions and diagnosis by consuming test suites.
47
+
48
+ ## Report a mismatch or missing capability
49
+
50
+ Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
51
+ operation/command, a minimal redacted request, actual mock result, expected oracle result or vendor
52
+ documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
53
+ customer data, prompts, PHI, card data, or unredacted recordings.
54
+
55
+ Service key: `whoop`.
package/README.md ADDED
@@ -0,0 +1,49 @@
1
+ # @crvouga/mockingbird-service-whoop
2
+
3
+ > Familiar calls. Faithful echoes. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
4
+
5
+ WIP WHOOP v2 mock for synthetic workout, sleep, recovery and cycle synchronization.
6
+
7
+ ## Install
8
+
9
+ `bun add @crvouga/mockingbird-service-whoop`
10
+
11
+ ## Usage
12
+
13
+ ```ts
14
+ import { createRuntime } from "@crvouga/mockingbird-service-whoop"
15
+ const runtime = createRuntime()
16
+ const response = await runtime.fetch(new Request("http://whoop.test/developer/v2/activity/workout", {
17
+ headers: { authorization: "Bearer mock_whoop_token" },
18
+ }))
19
+ ```
20
+
21
+ 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 mock.
22
+
23
+ ## Routes and state
24
+
25
+ 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 mock 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.
26
+
27
+ 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 mock 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`.
28
+
29
+ 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.
30
+
31
+ ## Test controls
32
+
33
+ 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.
34
+
35
+ ## Oracle and tests
36
+
37
+ Derived from the official [OpenAPI](https://api.prod.whoop.com/developer/doc/openapi.json), [OAuth reference](https://developer.whoop.com/docs/developing/oauth/), and [refresh example](https://developer.whoop.com/docs/tutorials/refresh-token-javascript/). The contract retains the official collection response schemas. Authorized live data and OAuth success were not probed; no live credentials used.
38
+
39
+ `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.
40
+
41
+ ## Deliberately not modelled
42
+
43
+ No real users, device pairing, sensors, consent UI, hardware SDK, webhook delivery, profile/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.
44
+
45
+ ## API
46
+
47
+ Root runtime exports: `WhoopAPI`, `WHOOP_NAMESPACE`, `COLLECTION_SCOPES`, `createRuntime`, `WHOOP_PRESETS`, `document`, `operationIds`, `supportedOperationIds`. Types: `WhoopAPIOptions`, `Grant`, `OAuthCode`, `Client`, `DataRecord`, `CollectionName`, `WhoopRuntimeOptions`, `WhoopRuntime`, `OperationId`, `SupportedOperationId`.
48
+
49
+ `/server`: `createServer`, `serveTarget`, `DEFAULT_PORT`; types `WhoopServerOptions`, `WhoopServer`.
package/SUPPORT.md ADDED
@@ -0,0 +1,15 @@
1
+ # WHOOP v2 mock — operation support
2
+
3
+ Generated from `openapi.yaml`; do not edit by hand.
4
+
5
+ - operations in spec: **5**
6
+ - supported by the mock: **5**
7
+ - parity enabled: **5**
8
+
9
+ | operationId | route | mock | parity | notes |
10
+ | --- | --- | --- | --- | --- |
11
+ | `ListWorkout` | `GET /developer/v2/activity/workout` | ✅ supported | ✅ | |
12
+ | `ListSleep` | `GET /developer/v2/activity/sleep` | ✅ supported | ✅ | |
13
+ | `ListRecovery` | `GET /developer/v2/recovery` | ✅ supported | ✅ | |
14
+ | `ListCycle` | `GET /developer/v2/cycle` | ✅ supported | ✅ | |
15
+ | `OAuthToken` | `POST /oauth/oauth2/token` | ✅ supported | ⚠️ unsafe (opt-in) | |