@crvouga/mockingbird-service-oura 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog — @crvouga/mockingbird-service-oura
+
+## 0.1.0 (2026-10-05)
+
+Initial release.

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @crvouga/mockingbird-service-oura discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@crvouga/mockingbird-service-oura/`; no repository checkout is needed to discover the mock's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `mockingbird.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **OAuth refresh and wearable collection windows**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- oura`.
+- Evidence model: Run from a Mockingbird checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Mockingbird
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-mockingbird-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual mock result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `oura`.

package/README.md

@@ -0,0 +1,49 @@
+# @crvouga/mockingbird-service-oura
+
+> Familiar calls. Faithful echoes. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
+
+WIP Oura v2 collection and OAuth mock for synthetic wearable synchronization tests.
+
+## Install
+
+`bun add @crvouga/mockingbird-service-oura`
+
+## Usage
+
+```ts
+import { createRuntime } from "@crvouga/mockingbird-service-oura"
+const runtime = createRuntime({ pageSize: 2 })
+const response = await runtime.fetch(new Request("http://oura.test/v2/usercollection/workout", {
+  headers: { authorization: "Bearer mock_oura_token" },
+}))
+```
+
+Run `mockingbird-oura serve --port 12128`; inject this origin into the consumer's API and OAuth configuration (the issue's provider strategies otherwise hard-code production). Acceptance tests use a Fetch port. `bun scripts/python-smoke.ts` (requires `uv`) additionally exercises the actual requests 2.32.5 and httpx 0.28.1 libraries over local HTTP, including token refresh and error handling; it does not exercise private consumer source.
+
+## Routes and state
+
+POST `/oauth/token` accepts URL-encoded authorization code or refresh grants, Basic or body client credentials. Seed `clients`, `codes`, `grants` with constructor options or standard state admin routes. Default local client is `mock_client` / `mock_client_secret`; bearer `mock_oura_token` belongs to `synthetic-user`. Codes bind client, redirect, expiry and optional S256 PKCE challenge. Refresh tokens rotate once, retaining user/scopes; clock controls access expiry.
+
+GET `/v2/usercollection/{workout,sleep,heartrate,daily_activity,daily_spo2,daily_readiness,daily_sleep}` returns `{data,next_token}`. Heart rate uses `start_datetime/end_datetime`; others use `start_date/end_date` against `day`. Fixture windows include both endpoints, omitted bounds are unbounded. These boundary/default choices are deterministic local fixture semantics, not verified live edge-case parity. Never invent an id for heart-rate samples. Fixtures retain every supplied metric, including nulls. Scope checks use `workout`, `daily`, `heartrate`, `spo2`.
+
+Seed `records` rows `{key,userId,collection,data}`. Keys identify storage rows, not vendor ids; distinct keys can deliberately carry duplicate provider data. `pageSize` controls deterministic insertion-order pages. Consumers must retain the same collection/window while paginating; the mock's row-key cursors do not bind or validate the query. No promised vendor cursor format/order. Set `tokenTtlSeconds` for newly issued tokens.
+
+## Test controls
+
+Standard `/__admin/health`, `/state`, `/reset`, `/requests`, `/clock`, Timeline checkpoints and faults are available under `/__admin` (relocatable via `adminPrefix`). Header `x-mockingbird-namespace`, `/__admin/ns/<name>` paths and credential mappings isolate data. Journals contain metadata, never OAuth bodies or wearable payloads. Presets: `unauthorized`, `rate_limited`, `server_error`, `connection_drop`; generic faults add latency. Quota and server-error bodies are explicitly scripted fixtures, not live quota simulations. No webhooks in this surface.
+
+## Oracle and tests
+
+Contract: [official Oura OpenAPI 1.41](https://cloud.ouraring.com/v2/static/json/openapi-1.41.json) and [OAuth documentation](https://cloud.ouraring.com/docs/authentication). Synthetic invalid credentials were checked live: token endpoint returned HTTP 400 `invalid_client`, collection endpoint HTTP 401 with the documented detail. Authorized collection data and refresh were not checked live.
+
+`bun test` runs acceptance and every-operation self-parity including divergence detection. `bun run parity` needs `OURA_ACCESS_TOKEN`, performs safe read-only envelope checks, and never prints health data or credentials.
+
+## Deliberately not modelled
+
+No real health data, account signup, consent UI, device pairing, sensor simulation, hardware SDK, webhooks, subscription lifecycle, field projection, statistical computation or full vendor metric validation. Records are synthetic pass-through fixtures; partial metrics can be seeded deliberately. Date boundary/default behavior, cursor internals and quota-body details are local stand-ins, not claims of exact vendor edge-case parity. No Python runtime dependency or claim that the private consumer itself was exercised.
+
+## API
+
+Root runtime exports: `OuraAPI`, `OURA_NAMESPACE`, `COLLECTION_SCOPES`, `createRuntime`, `OURA_PRESETS`, `document`, `operationIds`, `supportedOperationIds`. Types include `OuraAPIOptions`, `Grant`, `OAuthCode`, `Client`, `DataRecord`, `CollectionName`, `OuraRuntimeOptions`, `OuraRuntime`, `OperationId`, `SupportedOperationId`.
+
+`/server` exports `createServer`, `serveTarget`, `DEFAULT_PORT` and types `OuraServerOptions`, `OuraServer`.

package/SUPPORT.md

@@ -0,0 +1,18 @@
+# Oura v2 mock — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **8**
+- supported by the mock: **8**
+- parity enabled: **8**
+
+| operationId | route | mock | parity | notes |
+| --- | --- | --- | --- | --- |
+| `ListWorkout` | `GET /v2/usercollection/workout` | ✅ supported | ✅ |  |
+| `ListSleep` | `GET /v2/usercollection/sleep` | ✅ supported | ✅ |  |
+| `ListHeartrate` | `GET /v2/usercollection/heartrate` | ✅ supported | ✅ |  |
+| `ListDailyActivity` | `GET /v2/usercollection/daily_activity` | ✅ supported | ✅ |  |
+| `ListDailySpo2` | `GET /v2/usercollection/daily_spo2` | ✅ supported | ✅ |  |
+| `ListDailyReadiness` | `GET /v2/usercollection/daily_readiness` | ✅ supported | ✅ |  |
+| `ListDailySleep` | `GET /v2/usercollection/daily_sleep` | ✅ supported | ✅ |  |
+| `OAuthToken` | `POST /oauth/token` | ✅ supported | ⚠️ unsafe (opt-in) |  |