@crvouga/mockingbird-service-polar 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog — @crvouga/mockingbird-service-polar
+
+## 0.2.0 (2026-10-21)
+
+### Features
+
+- add manual response controls ([4599960](https://github.com/crvouga/mockingbird/commit/45999603e8b860c633181367afc7baa906ba486b))
+
+## 0.1.0 (2026-10-21)
+
+Initial release.

package/DISCOVERY.md

@@ -0,0 +1,78 @@
+# @crvouga/mockingbird-service-polar discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@crvouga/mockingbird-service-polar/`; no repository checkout is needed to discover the emulator'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 code exchange, user registration and exercise windows**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- polar`.
+- 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/controls`
+- `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.
+
+## Admin controls
+
+Every HTTP emulator takes the same controls, and each means the same thing at boot
+(`createRuntime({ adminControls })`, `serve --admin-controls`), over `/__admin`, and in a request header:
+
+| Control | Admin API | Request header | Interface |
+| --- | --- | --- | --- |
+| Isolate state by key | `GET /__admin/namespaces` | `x-mockingbird-namespace: <key>` | [Namespaces](https://mockingbird.chrisvouga.dev/docs/admin-controls/namespaces) |
+| Reset to boot | `POST /__admin/reset` | `x-mockingbird-reset: true` | [Reset](https://mockingbird.chrisvouga.dev/docs/admin-controls/reset) |
+| Snapshot and restore | `POST /__admin/snapshots`, `POST /__admin/snapshots/<id>/restore` | `x-mockingbird-snapshot: <name>`, `x-mockingbird-restore: <name>` | [Snapshot and restore](https://mockingbird.chrisvouga.dev/docs/admin-controls/snapshot-and-restore) |
+| Move the clock | `POST /__admin/clock` | `x-mockingbird-time: <instant>`, `x-mockingbird-advance: <duration>` | [Clock](https://mockingbird.chrisvouga.dev/docs/admin-controls/clock) |
+| Read or branch from old state | `GET /__admin/timeline` | `x-mockingbird-at: <checkpoint>`, `x-mockingbird-branch: <name>` | [Checkpoints and branches](https://mockingbird.chrisvouga.dev/docs/admin-controls/checkpoints-and-branches) |
+| Inject a fault | `POST /__admin/faults` | `x-mockingbird-fault: <fault>` | [Faults](https://mockingbird.chrisvouga.dev/docs/admin-controls/faults) |
+| Latency and timeouts | `PUT /__admin/latency` | `x-mockingbird-delay: <duration>`, `x-mockingbird-timeout: <duration>` | [Latency and timeouts](https://mockingbird.chrisvouga.dev/docs/admin-controls/latency-and-timeouts) |
+| Replay from a seed | `PUT /__admin/controls` | `x-mockingbird-seed: <seed>` | [Seed and determinism](https://mockingbird.chrisvouga.dev/docs/admin-controls/seed-and-determinism) |
+| See what happened | `GET /__admin/requests`, `GET /__admin/state` | | [Journal, metrics and state](https://mockingbird.chrisvouga.dev/docs/admin-controls/journal-and-state) |
+
+`GET /__admin` lists every route and header with a one-line summary, and `GET /__admin/controls`
+is the namespace's current control document. The same seed and the same requests give the same
+bytes. Setting controls as an emulator starts is [Boot](https://mockingbird.chrisvouga.dev/docs/admin-controls/boot); every route and header is in
+the [Reference](https://mockingbird.chrisvouga.dev/docs/admin-controls/reference). The full guide: <https://mockingbird.chrisvouga.dev/docs/admin-controls>.
+
+## 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 emulator 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: `polar`.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @crvouga/mockingbird-service-polar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Local emulators. Real API contracts. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
+
+WIP Polar AccessLink v3 emulator: OAuth 2.0 authorization code, user registration and the exercise endpoints, with the 30-day visibility window.
+
+## Install
+
+`bun add @crvouga/mockingbird-service-polar`
+
+## Usage
+
+```ts
+import { createServer } from "@crvouga/mockingbird-service-polar/server"
+
+// Test setup: a local Polar. The user is registered with the client ten days ago and has an
+// exercise uploaded afterwards. Seeds, presets and the clock are the only emulator-specific lines.
+const now = Date.now()
+const server = await createServer({
+  registrations: [
+    { xUserId: 1001, memberId: "m-1", registeredAt: new Date(now - 10 * 86_400_000).toISOString() },
+  ],
+  exercises: [
+    {
+      xUserId: 1001,
+      id: "2AC312F",
+      upload_time: new Date(now - 86_400_000).toISOString(),
+      start_time: "2026-01-30T08:00:00",
+      duration: "PT2H44M",
+    },
+  ],
+})
+
+// Application code: the same three origins, each pointed at the emulator.
+const apiOrigin = server.url
+const tokenUrl = `${server.url}/v2/oauth2/token`
+const authorizeUrl = `${server.url}/oauth2/authorization`
+
+const consent = await fetch(
+  `${authorizeUrl}?response_type=code&client_id=mock_client&redirect_uri=https://app.example.com/cb&state=s1&scope=accesslink.read_all`,
+  { redirect: "manual" },
+)
+const code = new URL(consent.headers.get("location") ?? "").searchParams.get("code") ?? ""
+const tokenResponse = await fetch(tokenUrl, {
+  method: "POST",
+  headers: {
+    "content-type": "application/x-www-form-urlencoded",
+    authorization: `Basic ${btoa("mock_client:mock_client_secret")}`,
+  },
+  body: new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: "https://app.example.com/cb",
+  }),
+})
+const { access_token } = (await tokenResponse.json()) as { access_token: string }
+const exercises = await fetch(`${apiOrigin}/v3/exercises?samples=false&zones=false&route=false`, {
+  headers: { authorization: `Bearer ${access_token}`, accept: "application/json" },
+})
+console.log(await exercises.json())
+
+await server.close()
+```
+
+Run `mockingbird-polar serve --port 12157`. The consumer has three origin settings: set the API origin, the token URL (`<origin>/v2/oauth2/token`) and the authorize URL (`<origin>/oauth2/authorization`) to the emulator. One emulator serves all three route sets, so they share the origin. The consent page is a browser redirect, so a browser cannot send `x-mockingbird-namespace`: use the `/__admin/ns/<name>` prefix (`<origin>/__admin/ns/<name>/oauth2/authorization`) to pick a namespace for it.
+
+## Routes and state
+
+Defaults: client `mock_client` / `mock_client_secret` (any redirect URI unless the client lists `redirectUris`), user `x_user_id` 1001 (not registered), and the access token `mock_polar_token` for that user. `GET /oauth2/authorization` redirects to `redirect_uri?code=<code>&state=<state>` as the first (or `consentUser`) user; the code is one-time and good for ten minutes on the emulator clock. `POST /v2/oauth2/token` takes a form body and Basic client auth and answers `{access_token, token_type: "bearer", expires_in: 31535999, x_user_id}` (integers; no `refresh_token`, no `scope`). Tokens never expire; they stop working only when revoked. A second use of a code, a different client's code or a mismatched `redirect_uri` is 400 `invalid_grant`; an unknown client or wrong secret is 400 `invalid_client`; a non-form body, a missing `grant_type`, or any grant other than `authorization_code` (including `refresh_token`) is 400 `invalid_request`.
+
+`POST /v3/users` with `{"member-id": "..."}` registers the token's user with the token's client at the emulator clock's instant and answers 200 with the profile (`polar-user-id`, `member-id`, `registration-date`, `first-name`, ...). A user already registered, or a `member-id` another user of that client holds, is 409. A body without `member-id` is 400; a non-JSON body is 415.
+
+`GET /v3/exercises` returns a JSON array of the token user's exercises that were uploaded at or after registration and no more than 30 days before the emulator clock (an exact 30 days is still returned), oldest upload first; `[]` when there are none. `GET /v3/exercises/{id}` returns one, or 404 for an unknown id, another user's exercise, or one outside that window. `samples`, `zones` and `route` default to false and must read `true` or `false` (else 400); when true the item gains `samples`, `heart_rate_zones` or `route` (from the seed, `[]` when none). A token whose user is not registered with the client gets 403 on both. Items always carry `id`, `upload_time`, `polar_user`, `device`, `sport`, `start_time`, `start_time_utc_offset` and `duration`; a seed that omits `device`, `device_id`, `sport`, `detailed_sport_info`, `start_time_utc_offset`, `duration`, `calories`, `distance`, `heart_rate` or `has_route` gets synthetic defaults (a Polar Vantage V, a 30 minute run).
+
+Every API route answers a missing, unknown or revoked token with 401.
+
+## Test controls
+
+Seed through options (`clients`, `users`, `registrations`, `exercises`, `tokens`, `codes`, `settings`) or the admin routes below; all state shows under `GET /__admin/state`. Admin routes (relocatable with the admin prefix):
+
+- `GET|PUT /__admin/settings`: `{consent: "approve" | "deny" | "error", consentUser: <x_user_id> | null}`. `deny` redirects with `error=access_denied`, `error` with `error=server_error`, both carrying the `state`.
+- `POST /__admin/users` `{xUserId, firstName?, lastName?, birthdate?, gender?, weight?, height?}`.
+- `POST /__admin/registrations` `{xUserId, memberId, registeredAt, clientId?}` (ISO 8601).
+- `POST /__admin/exercises` `{xUserId, id, upload_time, start_time, ...fields}`. Seed one uploaded before registration and one older than 30 days to see them excluded.
+- `POST /__admin/tokens/revoke` `{token}`: that token answers 401 from then on.
+- The clock (`POST /__admin/clock`) moves the 30-day window and the code lifetime.
+
+Presets (`POST /__admin/faults {"preset": ..., "count": n}`): `unauthorized` (401), `rate_limited` (429 with `RateLimit-Usage`, `RateLimit-Limit`, `RateLimit-Reset`, no `Retry-After`), `rate_limited_retry_after` (the same plus `Retry-After: 5`), `server_error` (500) and `connection_drop`. Generic faults add any other status, headers or latency. Header namespaces (`x-mockingbird-namespace`), `/__admin/ns/<name>` paths and bearer-token mappings (`PUT /__admin/credentials`) isolate users, registrations, exercises and tokens. Journals record metadata, not bodies. No webhooks.
+
+## Oracle and tests
+
+Derived from the [AccessLink reference](https://www.polar.com/accesslink-api/) and the consumer's wire shapes (issue #546). **No live credentials were used; nothing here is oracle-verified.** The following are a best guess, not oracle-verified: the `invalid_request` error for `grant_type=refresh_token`; 403 for an unregistered user's exercise calls; 200 and `[]` for a registered user with no exercises; 404 for an unknown exercise id; the JSON shape of API error bodies (`{"error": {"timestamp", "status", "errorType", "message"}}`); redirect-based `invalid_scope`, `unsupported_response_type` and `server_error` on the consent page; the ten-minute code lifetime; omitting `redirect_uri` at the token endpoint being accepted; the `RateLimit-*` values on the 429 presets (the documented default limits of 500 per 15 minutes and 5000 per 24 hours, exhausted) and no `Retry-After` on the default 429 (`rate_limited_retry_after` is the variant). Successful responses never carry `RateLimit-*` headers.
+
+`bun test` runs the acceptance tests (every numbered behavior of the request, through `test/consumer.ts`), all-operation self-parity (the consent page is a browser redirect and is excluded from random walks) and divergence detection. `bun run parity` requires `POLAR_ACCESS_TOKEN` of an already registered user and performs a read-only exercise list envelope check without printing data.
+
+## Deliberately not modelled
+
+The deprecated transaction API (create transaction, commit), daily activity, continuous heart rate, cardio load, sleep, Nightly Recharge, SleepWise and Elixir data, FIT/TCX/GPX downloads, webhooks, user deletion and the v4 Dynamic API. Also: a real login or consent UI (the consent page decides from the `consent` setting), Polar Flow accounts and devices, rate-limit accounting (the `RateLimit-*` headers appear only on forced 429s), the `training_load`, `fat_percentage`-style optional exercise fields (seed them if needed; they pass through), and token expiry (`expires_in` is a constant).
+
+## API
+
+Root runtime exports: `PolarAPI`, `POLAR_NAMESPACE`, `POLAR_SCOPE`, `EXPIRES_IN`, `EXERCISE_WINDOW_MS`, `CODE_TTL_MS`, `DEFAULT_SETTINGS`, `createRuntime`, `POLAR_PRESETS`, `document`, `operationIds`, `supportedOperationIds`. Types: `PolarAPIOptions`, `Client`, `User`, `RegistrationSeed`, `Registration`, `TokenGrant`, `OAuthCode`, `ExerciseSeed`, `ExerciseRow`, `ConsentMode`, `Settings`, `PolarRuntimeOptions`, `PolarRuntime`, `OperationId`, `SupportedOperationId`.
+
+`/server`: `createServer`, `serveTarget`, `DEFAULT_PORT`; types `PolarServerOptions`, `PolarServer`.

package/SUPPORT.md

@@ -0,0 +1,15 @@
+# Polar AccessLink API v3 (Mockingbird subset) — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **5**
+- supported by the emulator: **5**
+- parity enabled: **4**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `Authorize` | `GET /oauth2/authorization` | ✅ supported | ❌ disabled | Browser redirect flow; covered by acceptance tests. |
+| `OAuthToken` | `POST /v2/oauth2/token` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `RegisterUser` | `POST /v3/users` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `ListExercises` | `GET /v3/exercises` | ✅ supported | ✅ |  |
+| `GetExercise` | `GET /v3/exercises/{id}` | ✅ supported | ✅ |  |