@crvouga/mockingbird-service-google-maps 3.2.0 → 3.4.0

package/CHANGELOG.md

@@ -1,14 +1,28 @@
 # Changelog — @crvouga/mockingbird-service-google-maps
 
-## 3.2.0 (2026-10-09)
+## 3.4.0 (2026-10-15)
 
 ### Features
 
-- match Emulate provider coverage ([16b65ce](https://github.com/crvouga/mockingbird/commit/16b65ce791fa216f28ec1521df636f57771d9c5e))
+- finish durable run lifecycle ([725ea1a](https://github.com/crvouga/mockingbird/commit/725ea1a966dac65434e98f06a9c33aca0d6f32d7))
+- add management and portable archives ([0d2a6dd](https://github.com/crvouga/mockingbird/commit/0d2a6dd0f9fecb3a1ea7c1638f6639787395c2f4))
+
+### Fixes and improvements
 
-### Dependencies
+- correlate cross-namespace operations ([3457a4b](https://github.com/crvouga/mockingbird/commit/3457a4b7dbfd9ad9c8a10671a5744b7c8425d000))
+- harden HTTP stream handling ([674307a](https://github.com/crvouga/mockingbird/commit/674307a869f57907567d462c4f506c3b0a237e13))
+
+## 3.3.0 (2026-10-12)
+
+### Features
 
-- `@crvouga/mockingbird-service-sqlite`
+- unify the emulator control plane ([2068547](https://github.com/crvouga/mockingbird/commit/2068547bedde4e2e2331c1657c1a78120e84428b))
+
+## 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)
 

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

@@ -41,22 +41,29 @@ npx mockingbird-google-maps serve --port 8814 --api-key "$PLACES_KEY"
 ```
 
 ```ts
+import { Client, PlaceAutocompleteType } from "@googlemaps/google-maps-services-js"
 import { createRuntime } from "@crvouga/mockingbird-service-google-maps"
 
-const maps = createRuntime()
-const get = async (path: string) =>
-  (await maps.fetch(new Request(`http://maps.test${path}`))).json()
-
-const { predictions } = await get(
-  "/maps/api/place/autocomplete/json?input=1625%20N%20Central&types=address&components=country:us&key=k",
-)
-const details = await get(
-  `/maps/api/place/details/json?place_id=${predictions[0].place_id}&fields=address_component&key=k`,
-)
-// details.result.address_components → 1625 / N Central Ave / Phoenix / AZ / 85004
-
-// Make the next two autocomplete calls fail, as QA's manual-entry fallback expects.
-maps.applyPreset("autocomplete_over_query_limit", "default", { count: 2 })
+// The Maps client your application already uses. Only its HTTP layer changes: axios's
+// fetch adapter reaches the emulator in this process instead of maps.googleapis.com.
+const emulator = createRuntime()
+const maps = new Client({
+  config: {
+    adapter: "fetch",
+    env: { fetch: (url: string | URL | Request, init?: RequestInit) => emulator.fetch(new Request(url, init)) },
+  },
+})
+
+const { data } = await maps.placeAutocomplete({
+  params: { input: "1625 N Central", types: PlaceAutocompleteType.address, components: ["country:us"], key: "k" },
+})
+const details = await maps.placeDetails({
+  params: { place_id: data.predictions[0]?.place_id ?? "", fields: ["address_component"], key: "k" },
+})
+// details.data.result.address_components → 1625 / N Central Ave / Phoenix / AZ / 85004
+
+// Test control: make the next two autocomplete calls fail, as QA's manual-entry fallback expects.
+emulator.applyPreset("autocomplete_over_query_limit", "default", { count: 2 })
 ```
 
 ### Address Validation
@@ -66,30 +73,37 @@ not collide, so one emulator serves both. Point the server-side client's Address
 at the emulator (or at `<emulator>/__admin/ns/<namespace>`), with the key as `?key=` (or `X-Goog-Api-Key`).
 
 ```ts
-import { createRuntime } from "@crvouga/mockingbird-service-google-maps"
-
-const maps = createRuntime()
-const response = await maps.fetch(
-  new Request("http://maps.test/v1:validateAddress?key=k", {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      address: {
-        regionCode: "US",
-        addressLines: ["1625 N Central Ave"],
-        locality: "Phoenix",
-        administrativeArea: "AZ",
-        postalCode: "85004",
-      },
-      enableUspsCass: true,
-    }),
-  }),
-)
-const { result } = await response.json()
-// result.verdict → PREMISE / addressComplete / ACCEPT; result.uspsData.dpvConfirmation → "Y"
-
-// Force the USPS "not deliverable" answer on the next call.
-maps.applyPreset("address_validation_dpv_n", "default", { count: 1 })
+import { AddressValidationClient } from "@googlemaps/addressvalidation"
+import { createServer } from "@crvouga/mockingbird-service-google-maps/server"
+
+const server = await createServer()
+const { hostname, port } = new URL(server.url)
+
+// The application's client, in REST mode. Only the endpoint changes.
+const client = new AddressValidationClient({
+  fallback: true,
+  protocol: "http",
+  apiEndpoint: hostname,
+  port: Number(port),
+  apiKey: "k",
+})
+const [{ result }] = await client.validateAddress({
+  address: {
+    regionCode: "US",
+    addressLines: ["1625 N Central Ave"],
+    locality: "Phoenix",
+    administrativeArea: "AZ",
+    postalCode: "85004",
+  },
+  enableUspsCass: true,
+})
+// result.verdict → PREMISE / addressComplete; result.uspsData.dpvConfirmation → "Y"
+
+// Test control: force the USPS "not deliverable" answer on the next call.
+server.runtime.applyPreset("address_validation_dpv_n", "default", { count: 1 })
+
+await client.close()
+await server.close()
 ```
 
 On web, load `<emulator>/maps/api/js?key=…&libraries=places` exactly as the app loads Google's