@crvouga/mockingbird-service-google-calendar 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -1,15 +1,21 @@
 # Changelog — @crvouga/mockingbird-service-google-calendar
 
-## 3.2.0 (2026-10-09)
+## 3.3.0 (2026-10-12)
 
 ### Features
 
-- match Emulate provider coverage ([16b65ce](https://github.com/crvouga/mockingbird/commit/16b65ce791fa216f28ec1521df636f57771d9c5e))
+- unify the emulator control plane ([2068547](https://github.com/crvouga/mockingbird/commit/2068547bedde4e2e2331c1657c1a78120e84428b))
 
 ### Dependencies
 
 - `@crvouga/mockingbird-service-sqlite`
 
+## 3.2.0 (2026-10-08)
+
+### Features
+
+- match Emulate provider coverage ([16b65ce](https://github.com/crvouga/mockingbird/commit/16b65ce791fa216f28ec1521df636f57771d9c5e))
+
 ## 3.1.0 (2026-10-08)
 
 ### Features

package/DISCOVERY.md

@@ -35,6 +35,7 @@ repository; live parity is an additional oracle check, not a substitute for the
 
 - `GET /__admin/health`
 - `GET /__admin`
+- `GET /__admin/controls`
 - `GET /__admin/state`
 - `GET /__admin/requests`
 - `GET /__admin/metrics`
@@ -45,6 +46,28 @@ For HTTP services, use `x-mockingbird-namespace` (or the documented credential/p
 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,

package/README.md

@@ -38,19 +38,21 @@ posts pushes to whatever `address` the app registers (http is allowed unless
 npx mockingbird-google-calendar serve --port 8820 --client "$GOOGLE_CLIENT_ID:$GOOGLE_CLIENT_SECRET"
 ```
 
-```js
+```ts
 import { auth, calendar } from "@googleapis/calendar"
 import { OAuth2Client } from "google-auth-library"
 import { createServer } from "@crvouga/mockingbird-service-google-calendar/server"
 
 const google = await createServer()
+
+// The application's OAuth and Calendar clients. Only their URLs change.
 const oauth = new OAuth2Client({
   clientId: "c",
   clientSecret: "s",
   redirectUri: "postmessage",
   endpoints: { oauth2TokenUrl: `${google.url}/token`, oauth2RevokeUrl: `${google.url}/revoke` },
 })
-// Authorization code "4/emulator-<name>" signs in <name>@example.com ("4/emulator-<email>" for others).
+// Authorization code "4/mock-<name>" signs in <name>@example.com ("4/mock-<email>" for others).
 const { tokens } = await oauth.getToken("4/mock-dr.house")
 const client = new auth.OAuth2()
 client.setCredentials({ access_token: tokens.access_token ?? null })
@@ -59,14 +61,20 @@ await cal.events.insert({
   calendarId: "primary",
   requestBody: { summary: "Rounds", start: { dateTime: "2026-10-01T15:00:00Z" }, end: { dateTime: "2026-10-01T16:00:00Z" } },
 })
+
+await google.close()
 ```
 
 An event created "in Google's UI" (admin route) is what the app then lists and syncs:
 
 ```ts
+import { auth, calendar } from "@googleapis/calendar"
+import { OAuth2Client } from "google-auth-library"
 import { createServer } from "@crvouga/mockingbird-service-google-calendar/server"
 
 const google = await createServer()
+
+// Test control: the practitioner adds an event in Google's UI.
 await fetch(`${google.url}/__admin/events`, {
   method: "POST",
   headers: { "content-type": "application/json" },
@@ -75,7 +83,21 @@ await fetch(`${google.url}/__admin/events`, {
     event: { summary: "Rounds", start: { dateTime: "2026-10-01T15:00:00Z" }, end: { dateTime: "2026-10-01T16:00:00Z" } },
   }),
 })
-const stored = await (await fetch(`${google.url}/__admin/events?email=dr.house@example.com`)).json()
+
+// The application lists it through the Calendar client.
+const oauth = new OAuth2Client({
+  clientId: "c",
+  clientSecret: "s",
+  redirectUri: "postmessage",
+  endpoints: { oauth2TokenUrl: `${google.url}/token` },
+})
+const { tokens } = await oauth.getToken("4/mock-dr.house")
+const client = new auth.OAuth2()
+client.setCredentials({ access_token: tokens.access_token ?? null })
+const cal = calendar({ version: "v3", auth: client, rootUrl: `${google.url}/` })
+const { data } = await cal.events.list({ calendarId: "primary" })
+console.log(data.items?.map((event) => event.summary)) // ["Rounds"]
+
 await google.close()
 ```