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

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog — @crvouga/mockingbird-service-suunto
+
+## 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-suunto discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@crvouga/mockingbird-service-suunto/`; 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, workouts and 24/7 sleep, activity and daily samples**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- suunto`.
+- 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: `suunto`.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# @crvouga/mockingbird-service-suunto
 
-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 Suunto Cloud API emulator: the OAuth 2.0 authorization-code flow, workouts, and the 24/7 sleep, activity and daily-statistics samples, behind the API management gateway's subscription key.
+
+**Evidence.** The public onboarding page ([apizone.suunto.com/how-to-start](https://apizone.suunto.com/how-to-start)) documents the authorize and token exchange (Basic client authentication), the JWT access token with its `user` claim, and the `Ocp-Apim-Subscription-Key` header. Everything else (every data path, field, status, error body, window limit and `since` rule) comes from the consumer request in issue #547, whose per-operation schemas are not public. It is a **best guess, not oracle-verified**; each such choice is marked below. Nothing here has been observed against a live Suunto account.
+
+## Install
+
+`bun add @crvouga/mockingbird-service-suunto`
+
+## Usage
+
+```ts
+import { createServer } from "@crvouga/mockingbird-service-suunto/server"
+
+// Test setup: a local Suunto. Its URL replaces both https://cloudapi.suunto.com (data) and
+// https://cloudapi-oauth.suunto.com (authorize and token) in the application.
+const server = await createServer({
+  workouts: [
+    { workoutId: 1001, activityId: 3, startTime: 1788307200000, stopTime: 1788310800000, totalTime: 3600 },
+  ],
+  settings: { subscriptionKey: "my-subscription-key" },
+})
+
+// Application code: the OAuth redirect, then the requests it sends to Suunto.
+const consent = await fetch(
+  `${server.url}/oauth/authorize?response_type=code&client_id=mock_client&redirect_uri=http://localhost:8000/callback&state=abc`,
+  { redirect: "manual" },
+)
+const code = new URL(consent.headers.get("location") ?? "").searchParams.get("code") ?? ""
+const token = (await (
+  await fetch(`${server.url}/oauth/token`, {
+    method: "POST",
+    headers: {
+      authorization: `Basic ${btoa("mock_client:mock_client_secret")}`,
+      "content-type": "application/x-www-form-urlencoded",
+    },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: "http://localhost:8000/callback",
+    }),
+  })
+).json()) as { access_token: string }
+const response = await fetch(`${server.url}/v3/workouts/?since=0&limit=100&offset=0`, {
+  headers: {
+    authorization: `Bearer ${token.access_token}`,
+    "ocp-apim-subscription-key": "my-subscription-key",
+  },
+})
+const { payload } = (await response.json()) as { payload: { workoutId: number }[] }
+
+await server.close()
+```
+
+Run `mockingbird-suunto serve --port 12141`. The consumer hard-codes both origins; give it a setting for the data origin, the authorize URL and the token URL and point all three at this server (`/oauth/authorize`, `/oauth/token`, everything else on the same origin). Serve it over HTTP on a loopback port when a browser must reach the authorize page. `test/consumer.ts` is a port of the consumer's httpx client (Basic token calls, JWT claim reads, one refresh on 401, one wait on 429, a top-level `code`/`error` read as a failure); the acceptance tests run through it.
+
+## Routes
+
+| Route | Behavior |
+| --- | --- |
+| `GET /oauth/authorize` | Needs `client_id` and `redirect_uri` (an unregistered client or URI is a 400 JSON error, never a redirect). Redirects to `redirect_uri?code=<one-time code>&state=<state unchanged>`. `scope` and PKCE are ignored. Consent mode `deny` redirects with `error=access_denied`, mode `error` with `error=server_error` (both with `error_description` and the state). A `response_type` other than `code` redirects with `error=unsupported_response_type`. |
+| `POST /oauth/token` | Form body, `Authorization: Basic base64(client_id:client_secret)`. Wrong or missing credentials are a 401 `invalid_client`. `authorization_code` needs `code` and the same `redirect_uri`; a reused, expired or other client's code is a 400 `invalid_grant`. `refresh_token` returns a new access token. Answers `{access_token, token_type: "bearer", refresh_token, expires_in: 86400, scope: "workout"}`. Access and refresh tokens are JWTs; the access token carries `sub` (subject id), `user` (Suunto username), `client_id`, `scope`, `iat`, `exp` and `jti`. The signature is a deterministic stand-in: consumers decode, never verify. |
+| `GET /v3/workouts/` | `{"error": null, "payload": [...]}` for the token's user, oldest first, with `since`, `limit` (default 100), `offset` and `filter-by-modification-time`. Each item is the seeded workout plus `workoutKey`. |
+| `GET /v3/workouts/{workoutKey}` | `{"error": null, "payload": {...}}`; an unknown key or another user's is a 404 `{"error", "code": 404}`. |
+| `GET /247samples/sleep`, `GET /247samples/activity` | `from` and `to` (epoch milliseconds, `from` inclusive, `to` exclusive). A top-level array of `{timestamp, entryData}` in timestamp order. |
+| `GET /247/daily-activity-statistics` | `startdate` and `enddate` (`YYYY-MM-DDTHH:MM:SS`, read as UTC; same window rule). A top-level array with one entry per `Name`, each with `Aggregation` and `Sources[].Samples[]` of `{Value, TimeISO8601}`. |
+
+Data routes go through the gateway first. With a `subscriptionKey` set, a missing or wrong `Ocp-Apim-Subscription-Key` (or `subscription-key` query parameter) is a 401 `{"statusCode": 401, "message": "Access denied due to ... subscription key ..."}` before the token is looked at. Without one configured the key is not required. An unknown, expired or missing token is a 401 `{"statusCode": 401, "message": "Unauthorized. Access token is missing or invalid."}`. The token is read with or without the word `Bearer` (the vendor's own curl example omits it). An unknown path is a gateway-style 404. The workouts list is served at `/v3/workouts/` with the trailing slash only.
+
+API errors (a malformed or missing window, `since`, `limit`, `offset`) are `{"error": "<message>", "code": 400, "payload": null}`, so the consumer's read of a top-level `code` and `error` sees them.
+
+### Best guesses (not oracle-verified)
+
+- The gateway wording (`statusCode`/`message` bodies) is Azure API Management's usual form, taken from its documentation, not from a Suunto response.
+- `since` is epoch seconds as the consumer sends it; a value of 1e11 or more (a millisecond timestamp, which the `/v2` documentation is believed to use) is read as milliseconds. `since=0` or omitted means all; otherwise a workout is returned when it is strictly after `since`. With `filter-by-modification-time=true` the compared time is the workout's `modifiedAt` (default: its `stopTime`), otherwise its `startTime`. Results are ordered by that time, then `workoutId`, and `limit`/`offset` slice that order.
+- The 24/7 routes reject a window longer than `maxWindowDays` (default 28; the consumer chunks at 20 and 14 days) with a 400 `{"error": "The time range must not be longer than 28 days", "code": 400}`. `to` is exclusive so consecutive chunks never repeat a sample.
+- The refresh token is reusable and returned unchanged by default; set `rotateRefreshTokens` to spend it and issue a new one on each refresh.
+- `error_in_body` answers a 200 with `{"error": "rate_limited", "code": 429}`; whether the real gateway ever does is unknown.
+- A daily statistic's `Aggregation` defaults to `Sum` and its source to `Suunto`.
+
+## Test setup
+
+Everything below is the test's, not the application's.
+
+- **Seed.** Constructor options and `createServer` take `users` (`{subject, username}`; default `mock_user`), `clients` (`{clientId, clientSecret, redirectUris}`; default `mock_client` / `mock_client_secret`, any redirect URI), `workouts` (`workoutId`, `activityId`, `startTime`, `stopTime`, `totalTime` required, any other field passed through; optional `subject`, `modifiedAt`, `workoutKey`), `sleepSamples` and `activitySamples` (`{subject?, timestamp, entryData}`), `dailyStatistics` (`{subject?, name, time, value, aggregation?, source?}`) and `settings`. Seeds without a `subject` belong to the first user. At runtime: `POST /__admin/users`, `/workouts`, `/samples/sleep`, `/samples/activity`, `/daily-statistics` with the same bodies.
+- **Tokens.** `mock_suunto_token` (refresh `mock_suunto_refresh`) belongs to the first user and does not expire, so a test needs no OAuth round trip. `POST /__admin/tokens {username?, subject?, clientId?}` mints a JWT pair for a user. `POST /__admin/tokens/expire {accessToken?}` expires one token, or all, now; the clock controls expiry otherwise (`expires_in` is `accessTokenTtlSeconds`).
+- **Settings.** `GET` and `PUT /__admin/settings`: `subscriptionKey` (`null` accepts requests without one), `accessTokenTtlSeconds`, `codeTtlSeconds`, `consent` (`approve`, `deny`, `error`), `consentUser` (the username consent approves as; default the first user), `scope`, `rotateRefreshTokens`, `maxWindowDays`.
+- **Presets** (`POST /__admin/faults {"preset": "<name>", "count": N}`, on the workouts and 24/7 routes only): `unauthorized` (401), `invalid_subscription_key` (401), `rate_limited` (429 with `Retry-After: 2`, API Management body `Rate limit is exceeded. Try again in 2 seconds.`), `rate_limited_no_retry_after`, `server_error` (500), `error_in_body` (200 with `{"error": "rate_limited", "code": 429}`), `connection_drop`. Generic faults add latency. The 429 and 500 bodies are scripted fixtures.
+- **Standard controls.** `/__admin/health`, `/state`, `/reset`, `/requests`, `/clock`, Timeline checkpoints and faults live under `/__admin` (relocatable with `adminPrefix`). `x-mockingbird-namespace`, `/__admin/ns/<name>` and credential mappings isolate users, tokens, workouts, samples and settings. The journal holds metadata only, never tokens, codes or secrets.
+
+## Oracle and tests
+
+`bun test` runs the acceptance tests (every numbered behavior of issue #547, through `test/consumer.ts`) and every-operation self-parity with divergence detection. `bun run parity` needs `SUUNTO_ACCESS_TOKEN` and `SUUNTO_SUBSCRIPTION_KEY` (an approved API Zone subscription and a Suunto App account with synced watch data), reads one workouts page, checks only the envelope and never prints data; without them it exits 2.
+
+## Deliberately not modelled
+
+Webhook notifications (Suunto documents them for new workouts; the consumer does not receive them), route and FIT file downloads, `/247samples/recovery`, SuuntoPlus, writes, and the `/v2/workouts` family (not served, not aliased). Also not modelled: a consent page UI (consent is a redirect decided by `consent`), `scope` negotiation, PKCE, refresh-token expiry, per-subscription rate limits, and Suunto's field validation of workout and sample content (records are synthetic pass-through fixtures). No claim that the private consumer itself was exercised.
+
+## API
+
+Root runtime exports: `SuuntoAPI`, `SUUNTO_NAMESPACE`, `DEFAULT_ACCESS_TOKEN`, `DEFAULT_REFRESH_TOKEN`, `DEFAULT_USER`, `DEFAULT_CLIENT`, `DEFAULT_SETTINGS`, `accessToken`, `parseDate`, `gatewayError`, `apiError`, `oauthError`, `createRuntime`, `SUUNTO_PRESETS`, `document`, `operationIds`, `supportedOperationIds`. Types include `SuuntoAPIOptions`, `User`, `Client`, `Settings`, `Grant`, `RefreshGrant`, `AuthorizationCode`, `Workout`, `WorkoutFields`, `SeedWorkout`, `Sample`, `SeedSample`, `DailyStatistic`, `SeedDailyStatistic`, `SuuntoRuntimeOptions`, `SuuntoRuntime`, `OperationId`, `SupportedOperationId`.
+
+`/server` exports `createServer`, `serveTarget`, `DEFAULT_PORT` and types `SuuntoServerOptions`, `SuuntoServer`.

package/SUPPORT.md

@@ -0,0 +1,17 @@
+# Suunto Cloud API (Mockingbird subset) — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **7**
+- supported by the emulator: **7**
+- parity enabled: **6**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `Authorize` | `GET /oauth/authorize` | ✅ supported | ❌ disabled | Browser redirect flow whose one-time codes only the acceptance tests can redeem. |
+| `OAuthToken` | `POST /oauth/token` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `ListWorkouts` | `GET /v3/workouts/` | ✅ supported | ✅ |  |
+| `GetWorkout` | `GET /v3/workouts/{workoutKey}` | ✅ supported | ✅ |  |
+| `ListSleepSamples` | `GET /247samples/sleep` | ✅ supported | ✅ |  |
+| `ListActivitySamples` | `GET /247samples/activity` | ✅ supported | ✅ |  |
+| `ListDailyActivityStatistics` | `GET /247/daily-activity-statistics` | ✅ supported | ✅ |  |