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

package/CHANGELOG.md

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

package/README.md

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# @crvouga/mockingbird-service-fitbit
 
-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 Fitbit legacy Web API emulator: OAuth 2.0 authorization code with PKCE, refresh rotation and revoke, the profile, the activity log list, the sleep log by date and the daily activity summary, over synthetic data. Fitbit announced the end of support for the legacy Web API on 2026-09-30 and its shutdown on 2026-10-30 (migration target: the Google Health API); this emulator keeps the documented legacy contract testable after that.
+
+## Install
+
+`bun add @crvouga/mockingbird-service-fitbit`
+
+## Usage
+
+```ts
+import { createServer } from "@crvouga/mockingbird-service-fitbit/server"
+
+// Test setup: a local Fitbit. One origin serves the API, token, revoke and authorize routes, so it
+// replaces https://api.fitbit.com and https://www.fitbit.com in the application.
+const server = await createServer({
+  activityLogs: [
+    {
+      userId: "ABC123",
+      log: { logId: 1, activityName: "Walk", startTime: "2026-09-02T06:00:00.000-07:00", steps: 3000 },
+    },
+  ],
+})
+const baseUrl = server.url
+
+// Application code: the requests it sends to Fitbit (default synthetic user ABC123 and its token).
+const response = await fetch(
+  `${baseUrl}/1/user/-/activities/list.json?afterDate=2026-09-01&sort=asc&limit=20&offset=0`,
+  { headers: { authorization: "Bearer mock_fitbit_token", accept: "application/json" } },
+)
+const { activities, pagination } = await response.json()
+
+await server.close()
+```
+
+Run `mockingbird-fitbit serve --port 12141`. Fitbit publishes no JS SDK and the consumer uses raw HTTP, so inject the emulator origin as the API origin, the token origin, the revoke origin and the authorize page origin (one local origin serves all four). A browser or simulator reaches the authorize page over HTTP, so use the served emulator rather than in-process `fetch` for the consent step.
+
+## Routes
+
+| Route | What it does |
+| --- | --- |
+| `GET /oauth2/authorize` | The consent page. Validates `client_id`, `redirect_uri`, `response_type=code`, `scope`, and the S256 `code_challenge`, then redirects (302) to the redirect URI with `code` and `state`, or with `error`, `error_description` and `state`. An unregistered client or redirect URI cannot be redirected and answers 400 HTML. |
+| `POST /oauth2/token` | Basic client auth, form body. `authorization_code` (with `redirect_uri` and `code_verifier`) and `refresh_token` grants. Answers `access_token`, `refresh_token`, `expires_in: 28800`, `token_type: "Bearer"`, `scope`, `user_id`. |
+| `POST /oauth2/revoke` | Basic client auth, form `token=<access or refresh token>`. 200; every token of that user for the client is gone. |
+| `GET /1/user/{-\|encodedId}/profile.json` | `{ user: { encodedId, displayName, ... } }`. Scope `profile`. |
+| `GET /1/user/-/activities/list.json` | `afterDate` (with `sort=asc`) or `beforeDate` (with `sort=desc`), `limit` (1 to 100), `offset`. Scope `activity`. |
+| `GET /1/user/-/activities/date/{date}.json` | `{ activities, goals, summary }`. Scope `activity`. |
+| `GET /1/user/-/sleep/date/{date}.json` and `/1.2/...` | `{ sleep, summary }`. Scope `sleep`. Both path versions serve the same data. |
+
+Authorization codes are single use and last 10 minutes; access tokens last 28800 seconds on the emulator clock. A refresh issues a new access and refresh token for the same user and scopes and removes the previous pair (single-use rotation, so the old access token answers 401 and the old refresh token answers `invalid_grant`). A failed code exchange (wrong verifier, wrong redirect URI) does not consume the code. The default client is `mock_client` / `mock_client_secret` (any redirect URI unless `redirectUris` is seeded); the default user is `ABC123` with bearer `mock_fitbit_token` and refresh token `mock_fitbit_refresh`, all scopes, never expiring until the clock passes year 2100.
+
+Data semantics: activity logs are filtered and ordered by the local wall-clock part of `startTime` (`afterDate` includes, `beforeDate` excludes); `pagination.next` is a full URL on the emulator origin with the next `offset` and is an empty string on the last page; `previous` likewise. A sleep log belongs to the day in `dateOfSleep` (else the date of `endTime`), so a log that began the previous evening is returned on the day it ended; `summary` totals `minutesAsleep` and `timeInBed` and sums `levels.summary.{deep,light,rem,wake}.minutes` into `summary.stages` when any log carries them. A day with no sleep logs is 200 with `{ sleep: [], summary: { totalMinutesAsleep: 0, totalSleepRecords: 0, totalTimeInBed: 0 } }`; a day with no activity data is 200 with zeroed `summary`, default `goals` and `activities: []`. Dates are `YYYY-MM-DD` (real calendar dates) or `today`. Logs are pass-through: every field you seed comes back.
+
+## Test controls
+
+Seed with `createRuntime`/`createServer` options (`users`, `clients`, `grants`, `codes`, `activityLogs`, `sleepLogs`, `dailySummaries`, `consent`) or the admin routes below (all relative to `/__admin`, relocatable via `adminPrefix`):
+
+| Admin route | Does |
+| --- | --- |
+| `PUT /consent` `{ mode: "approve" \| "deny" \| "error", userId? }` / `GET /consent` | What the authorize page does next, and which seeded user the code belongs to. |
+| `POST /users` `{ encodedId, profile? }` | Seed a user; `profile` fields come back on the profile route. |
+| `POST /activity-logs` / `POST /sleep-logs` `{ userId?, logs: [...] }` | Seed logs (`logId` and `startTime` are required; sleep also `endTime`). A repeated `logId` replaces the log. |
+| `POST /daily-summaries` `{ userId?, date, activities?, goals?, summary? }` | Seed one day; fields merge over the defaults. |
+| `POST /tokens/expire` `{ userId }` | Expire the user's access tokens now, without moving the clock; refresh tokens still work. |
+| `POST /tokens/revoke` `{ userId }` | Revoke every token of the user, so the next refresh is `invalid_grant`. |
+
+`POST /clock {"advance": ms}` moves the namespace clock: an access token older than 28800 seconds then answers 401 `expired_token`, and a code older than 10 minutes is refused. Standard `/__admin/health`, `/state` (collections `users`, `clients`, `grants`, `codes`, `activity_logs`, `sleep_logs`, `daily_summaries`, `settings`), `/reset`, `/requests`, Timeline checkpoints and faults are available. The header `x-mockingbird-namespace`, `/__admin/ns/<name>` paths and credential mappings (bearer token or Basic client id) isolate data. Journals contain metadata, never token or health payloads.
+
+Presets (`POST /__admin/faults {"preset": "<name>", "count": n}`): `unauthorized` (401 `expired_token`), `forbidden` (403 `insufficient_scope`), `rate_limited` (429 with `Retry-After: 2` and `fitbit-rate-limit-*` headers), `rate_limited_no_retry_after`, `server_error` (500), `connection_drop`. No webhooks: the Subscription API is not modelled.
+
+## Evidence and best guesses
+
+Nothing here was observed against a live Fitbit account (the legacy API has no sandbox and needs a consenting user). The contract follows the vendor reference at <https://dev.fitbit.com/build/reference/web-api/> (authorize, token, refresh, revoke, activity list, sleep by date, profile). Everything below is a **best guess, not oracle-verified** and is tracked in the issue as `needs-oracle-check`:
+
+- the `{"errors":[{"errorType","message","fieldName"?}],"success":false}` envelope and the `errorType` names (`invalid_client`, `invalid_grant`, `invalid_request`, `unsupported_grant_type`, `invalid_token`, `expired_token`, `insufficient_scope`, `insufficient_permissions`, `validation`, `too_many_requests`), and their messages and statuses (401 for bad client credentials and bad or expired bearer tokens, 400 for bad grants and parameters, 403 for scope or another user's id);
+- single-use refresh rotation killing the previous access token, and not consuming an authorization code on a failed exchange;
+- `offset` above 0 being honored (the reference documents `Supported: 0` and builds `next` for the following page), `next` being an empty string on the last page, and `next` using the next `offset` rather than a moved `afterDate`;
+- the `afterDate`/`sort` pairing rules and the `limit` 1 to 100 bound being enforced as 400 `validation`;
+- `/1/` and `/1.2/` sleep serving identical data, including `levels.summary` stage totals;
+- revoke answering 200 `{}` and an unknown token also 200 (RFC 7009), an unknown user id in the path answering 403;
+- the 429 body and header set, and the defaults for profile, goals and an empty day.
+
+## Oracle and tests
+
+`bun test` runs the acceptance tests (one per numbered behavior of the service request, through `test/consumer.ts`, a port of the consumer's httpx client) and every-operation self-parity with divergence detection. `bun run parity` needs `FITBIT_ACCESS_TOKEN`, performs safe read-only profile and activity-list envelope checks, and never prints health data or credentials.
+
+## Deliberately not modelled
+
+Intraday time series, heart-rate and SpO2 time series, devices, friends, subscriptions and webhooks, writes (create log, goals), the implicit and client-credentials grants, public (secretless) PKCE clients, `GET /1/user/-/activities/{id}.json` (not a documented per-user route), the TCX download, the Google Health API, a consent UI (consent is decided by the `consent` control and the browser is only redirected), the `#_=_` fragment the vendor appends to the redirect, rate-limit accounting (limits are only scripted through presets), real health data and device pairing.
+
+## API
+
+Root runtime exports: `FitbitAPI`, `FITBIT_NAMESPACE`, `FITBIT_SCOPES`, `ACCESS_TOKEN_SECONDS`, `CODE_SECONDS`, `fitbitError`, `createRuntime`, `FITBIT_PRESETS`, `document`, `operationIds`, `supportedOperationIds`. Types include `FitbitAPIOptions`, `Client`, `User`, `Grant`, `OAuthCode`, `ActivityLog`, `ActivityLogEntry`, `SleepLog`, `SleepLogEntry`, `DailySummary`, `Consent`, `FitbitRuntimeOptions`, `FitbitRuntime`, `OperationId`, `SupportedOperationId`.
+
+`/server` exports `createServer`, `serveTarget`, `DEFAULT_PORT` and types `FitbitServerOptions`, `FitbitServer`.

package/SUPPORT.md

@@ -0,0 +1,18 @@
+# Fitbit legacy Web API emulator — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **8**
+- supported by the emulator: **8**
+- parity enabled: **7**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `Authorize` | `GET /oauth2/authorize` | ✅ supported | ❌ disabled | Interactive consent redirects are exercised by the acceptance tests through the consumer. |
+| `OAuthToken` | `POST /oauth2/token` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `RevokeToken` | `POST /oauth2/revoke` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `GetProfile` | `GET /1/user/{userId}/profile.json` | ✅ supported | ✅ |  |
+| `ListActivityLogs` | `GET /1/user/{userId}/activities/list.json` | ✅ supported | ✅ |  |
+| `GetDailyActivitySummary` | `GET /1/user/{userId}/activities/date/{date}.json` | ✅ supported | ✅ |  |
+| `GetSleepByDate` | `GET /1/user/{userId}/sleep/date/{date}.json` | ✅ supported | ✅ |  |
+| `GetSleepByDateV12` | `GET /1.2/user/{userId}/sleep/date/{date}.json` | ✅ supported | ✅ |  |