@crvouga/mockingbird-service-elevenlabs 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog — @crvouga/mockingbird-service-elevenlabs
 
-## 0.1.0 (2026-10-11)
+## 0.3.0 (2026-10-15)
+
+### Features
+
+- 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
+
+- correlate cross-namespace operations ([3457a4b](https://github.com/crvouga/mockingbird/commit/3457a4b7dbfd9ad9c8a10671a5744b7c8425d000))
+- harden HTTP stream handling ([674307a](https://github.com/crvouga/mockingbird/commit/674307a869f57907567d462c4f506c3b0a237e13))
+
+## 0.2.0 (2026-10-12)
+
+### Features
+
+- unify the emulator control plane ([2068547](https://github.com/crvouga/mockingbird/commit/2068547bedde4e2e2331c1657c1a78120e84428b))
+
+## 0.1.0 (2026-10-10)
 
 Initial release.

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

@@ -35,9 +35,10 @@ npx mockingbird-elevenlabs serve --port 8841 \
   --models eleven_multilingual_v2,eleven_flash_v2_5
 ```
 
-In-process, pass `runtime.fetch` as the adapter's `fetch`:
+In-process, pass the emulator as the `fetch` of the official SDK (`@elevenlabs/elevenlabs-js`):
 
 ```ts
+import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"
 import {
   createRuntime,
   DEFAULT_API_KEY,
@@ -45,32 +46,31 @@ import {
   mp3Audio,
 } from "@crvouga/mockingbird-service-elevenlabs"
 
-// A reply the test controls: exact bytes for one text. Here they are a valid MP3, but any
-// bytes are returned as given.
+// Test setup. A reply the test controls: exact bytes for one text. Here they are a valid MP3,
+// but any bytes are returned as given.
 const scripted = mp3Audio(44_100, 128, 500, 9)
-const elevenlabs = createRuntime({
+const emulator = createRuntime({
   scripts: [{ match: { text: "Welcome back." }, audio: scripted }],
 })
 
-const speak = (text: string, outputFormat: string) =>
-  elevenlabs.fetch(
-    new Request(
-      `http://elevenlabs.test/v1/text-to-speech/${DEFAULT_VOICES[0]?.voice_id}?output_format=${outputFormat}`,
-      {
-        method: "POST",
-        headers: { "content-type": "application/json", "xi-api-key": DEFAULT_API_KEY },
-        body: JSON.stringify({ text, model_id: "eleven_multilingual_v2" }),
-      },
-    ),
-  )
-
-const welcome = await speak("Welcome back.", "mp3_44100_128")
-console.log(welcome.status, welcome.headers.get("content-type")) // 200 audio/mpeg
-console.log(new Uint8Array(await welcome.arrayBuffer()).length === scripted.length) // true
+// The ElevenLabs SDK your application already uses. Only its fetch changes: requests reach
+// the emulator in this process instead of api.elevenlabs.io.
+const elevenlabs = new ElevenLabsClient({
+  apiKey: DEFAULT_API_KEY,
+  fetch: ((url: RequestInfo | URL, init?: RequestInit) =>
+    emulator.fetch(new Request(url, init))) as typeof fetch,
+})
+const voiceId = DEFAULT_VOICES[0]?.voice_id ?? ""
+
+const welcome = await elevenlabs.textToSpeech
+  .convert(voiceId, { text: "Welcome back.", modelId: "eleven_multilingual_v2", outputFormat: "mp3_44100_128" })
+  .withRawResponse()
+console.log(welcome.rawResponse.status, welcome.rawResponse.headers.get("content-type")) // 200 audio/mpeg
+console.log((await new Response(welcome.data).arrayBuffer()).byteLength === scripted.length) // true
 
 // Unscripted requests get generated audio: raw 16-bit mono samples for pcm_44100.
-const pcm = await speak("Anything else.", "pcm_44100")
-console.log(pcm.headers.get("content-type"), (await pcm.arrayBuffer()).byteLength) // audio/pcm 61740
+const pcm = await elevenlabs.textToSpeech.convert(voiceId, { text: "Anything else.", outputFormat: "pcm_44100" })
+console.log((await new Response(pcm).arrayBuffer()).byteLength) // 61740
 ```
 
 ### Routes