@crvouga/mockingbird-service-aws-speech 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog — @crvouga/mockingbird-service-aws-speech
+
+## 0.1.0 (2026-09-22)
+
+Initial release.

package/README.md

@@ -0,0 +1,132 @@
+# @crvouga/mockingbird-service-aws-speech
+
+Stateful mock of **Amazon Polly** and **Amazon Transcribe** for test suites: Polly
+`SynthesizeSpeech` and `StartSpeechSynthesisStream` (HTTP/2 duplex event stream), Transcribe
+Streaming `StartStreamTranscription` (HTTP/2 duplex) and Transcribe batch
+`StartTranscriptionJob` / `GetTranscriptionJob`. Chat voice turns run end to end with no audio
+leaving the machine: Transcribe "hears" what a test scripts, Polly answers with deterministic
+synthetic audio whose length follows the text.
+
+- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/aws-speech/SUPPORT.md)
+- Proven with the official clients our consumer pins: `@aws-sdk/client-polly`,
+  `@aws-sdk/client-transcribe-streaming`, `@aws-sdk/client-transcribe` (3.1132.0), and the MP3
+  decoder our backend uses (`mpg123-decoder@1.0.3`).
+
+## Install
+
+```bash
+npm install -D @crvouga/mockingbird-service-aws-speech
+```
+
+ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with
+`npx mockingbird-aws-speech serve` (h2c + HTTP/1.1 on one port), `createServer` from
+`./server`, or `createRuntime` with any Fetch server (HTTP/1.1 only).
+
+## Usage
+
+```bash
+npx mockingbird-aws-speech serve --port 8797
+export AWS_ENDPOINT_URL_POLLY=http://127.0.0.1:8797
+export AWS_ENDPOINT_URL_TRANSCRIBE_STREAMING=http://127.0.0.1:8797
+export AWS_ENDPOINT_URL_TRANSCRIBE=http://127.0.0.1:8797
+```
+
+```ts
+import { createServer } from "@crvouga/mockingbird-service-aws-speech/server"
+
+const speech = await createServer({ port: 8797 })
+// What the next voice session "hears": partials while audio streams in, then the final.
+await fetch(`${speech.url}/__admin/transcripts`, {
+  method: "PUT",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ match: { any: true }, partials: ["I have", "I have a headache"], final: "I have a headache." }),
+})
+// …the backend's /v2/chatbot/voice turn transcribes, replies, and speaks through Polly…
+await speech.close()
+```
+
+### Protocols
+
+Polly and Transcribe Streaming clients default to `NodeHttp2Handler`: against an `http://`
+endpoint they speak **h2c** (cleartext HTTP/2, prior knowledge), and their bidirectional
+operations need HTTP/2 duplex. Transcribe batch uses HTTP/1.1. `mockingbird-aws-speech serve`
+and `createServer` sniff each connection and serve both on one port (`serve --config` from
+another service's CLI, and `createRuntime` behind a plain Fetch server, speak HTTP/1.1 only).
+
+### Routes
+
+| Route | Behaviour |
+| --- | --- |
+| `POST /v1/speech` | Polly `SynthesizeSpeech`. `OutputFormat: pcm` → raw PCM s16le mono 440 Hz tone (`audio/pcm`, even byte count, `SampleRate` 8000/16000, default 16000); `mp3` → valid MPEG-2 Layer III frames (`audio/mpeg`, 8000/16000/22050/24000). 60 ms of audio per character, byte-identical on every run; `x-amzn-RequestCharacters`. Errors: `ValidationException` (unknown voice or engine), `InvalidSampleRateException`, `TextLengthExceededException` (> 3000 characters). |
+| `POST /v1/synthesisStream` | Polly `StartSpeechSynthesisStream` (HTTP/2 duplex, parameters in `x-amzn-Engine` / `x-amzn-VoiceId` / `x-amzn-OutputFormat` / `x-amzn-SampleRate`; generative engine only). Each `TextEvent` answers `AudioEvent`s (24 kHz MP3 frames mpg123 decodes); `CloseStreamEvent` (or the end of input) answers `StreamClosedEvent {RequestCharacters}`. |
+| `POST /stream-transcription` | Transcribe `StartStreamTranscription` (HTTP/2 duplex). Validates the `x-amzn-transcribe-*` parameters (400 `BadRequestException`), echoes them in the response headers with `x-amzn-transcribe-session-id`. Sends one scripted partial (`IsPartial: true`) per `AudioEvent` received, the rest when the audio ends, then the final result, then closes. Audio bytes are counted, never kept. |
+| `POST /` | Transcribe batch (AWS JSON 1.1, `X-Amz-Target`). `StartTranscriptionJob` → `IN_PROGRESS` (`ConflictException` for a repeated name); `GetTranscriptionJob` → `COMPLETED` once `jobDurationMs` (2 s) have passed on the mock clock, with `Transcript.TranscriptFileUri` = `https://s3.<region>.amazonaws.com/<OutputBucketName>/<OutputKey>`; `BadRequestException` for an unknown job. |
+
+### Transcripts (`PUT /__admin/transcripts`)
+
+`{match?, partials?, final, times?}` (or `{"transcripts": [...]}`). `match` is
+`{sessionIndex}` (0-based count of streaming sessions in the namespace), `{jobName}` (a batch
+job), or `{any: true}`; an exact match wins over `any`. Unscripted sessions and jobs hear
+`defaultTranscript` (`"Hello."`, `PUT /__admin/settings`) and count as `unscripted`
+(`GET /__admin/transcripts` → `stats`).
+
+### Admin (beyond the standard contract)
+
+| Route | Effect |
+| --- | --- |
+| `PUT` / `POST` / `GET` / `DELETE /__admin/transcripts` | Replace, add, list (with `stats`), remove (`?id=`). |
+| `GET /__admin/jobs` | Batch jobs (advanced on the mock clock). |
+| `POST /__admin/jobs/:name/complete` | Complete now, optionally with `{transcript}`. |
+| `POST /__admin/jobs/:name/fail` | Fail with `{reason}` (`FailureReason`). |
+| `GET /__admin/jobs/:name/transcript` | The transcript JSON Transcribe would write to S3. |
+| `GET /__admin/speech` | Metadata of every synthesis / transcription (voice, engine, format, characters, bytes, script id — never text). |
+| `GET/PUT /__admin/settings` | `defaultTranscript`, `jobDurationMs`. |
+
+With `--s3-endpoint <url>` (`transcriptStore` in code) a completed job's transcript JSON is also
+written to that S3 (the stack's s3rver) at `OutputBucketName/OutputKey`, so the app's own
+`GetObject` on `TranscriptFileUri` finds it.
+
+Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`):
+`polly_throttling` (429 `ThrottlingException`), `polly_service_failure` (500),
+`polly_stream_throttling` / `polly_stream_validation` / `polly_stream_quota` (an exception
+event before any audio: our adapter falls back to `SynthesizeSpeech`), `polly_stream_failure`
+(`ServiceFailureException` after audio), `polly_stream_no_close` (no `StreamClosedEvent`),
+`transcribe_bad_request` (400), `transcribe_limit_exceeded` (429), `transcribe_service_unavailable`
+(503), `transcribe_mid_stream_failure` (`InternalFailureException` after the first partial),
+`transcribe_job_limit` (`LimitExceededException`), `transcribe_job_failed` (next job `FAILED`).
+
+### Namespaces
+
+`x-mockingbird-namespace`, a `/ns/<name>` prefix on the endpoint URL, or the SigV4 access key id:
+`PUT /__admin/credentials {"credentials": {"<AWS_ACCESS_KEY_ID>": "<namespace>"}}`. The journal
+records voice, engine, format, character counts and script ids — never text.
+
+### Deliberately not modelled
+
+- Real speech: Polly audio is a tone (PCM) or silent-but-valid MP3 frames (a tone needs a real
+  MP3 encoder); Transcribe never listens — words come only from scripts.
+- `ogg_vorbis`, `ogg_opus`, `mulaw`, `alaw` and speech-mark (`json`) output, SSML semantics (tags
+  are stripped for length), lexicons, per-voice engine availability.
+- Transcribe language identification, speaker labels, custom vocabularies (accepted and echoed,
+  not applied), Call Analytics and Medical variants, batch jobs reading their media from S3.
+- SigV4 signatures and event signatures are not verified; the access key id only selects a
+  namespace.
+
+## API
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `SpeechAPI` | class | The in-process mock: `fetch`, `reset`, `jobs()`, `complete(name, transcript?)`, `fail(name, reason)`, `transcriptDocument(job)`, `speechLog()`, `stats()`. Options: `sqlite`, `now`, `namespace`, `settings`, `transcripts`, `transcriptStore`. |
+| `createRuntime` | function | The mock with the full service contract. Options: `settings`, `transcripts`, `transcriptStore`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
+| `SPEECH_PRESETS` | object | Every named fault preset. |
+| `SPEECH_NAMESPACE` | string | The service name, `"aws-speech"`. |
+| `POLLY_VOICES` | array | Every Polly voice id the mock accepts. |
+| `speechError` | function | A restJson1 error response (`x-amzn-ErrorType` + `{message}`). |
+| `accessKeyCredential` | function | The SigV4 access key id of a request (how credentials map to namespaces). |
+| `pcmTone`, `mp3Audio`, `mp3Frame`, `durationFor`, `MS_PER_CHARACTER`, `MP3_SAMPLE_RATES`, `MP3_SAMPLES_PER_FRAME` | audio | The deterministic synthetic audio. |
+| `DEFAULT_SETTINGS` | value | Default settings. |
+| `encodeMessage`, `decodeMessage`, `FrameReader`, `readFrames`, `eventFrame`, `exceptionFrame`, `unwrapSigned`, `crc32`, `EventStreamError` | codec | The event-stream codec (exact prelude, headers and CRC32s), in both directions. |
+| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
+| `createServer`, `serveTarget`, `DEFAULT_PORT`, `listenH2c` (`./server`) | Node | Serve h2c + HTTP/1.1 on one port; the `serve` CLI target; port 8797; the dual-protocol listener. |
+
+Part of [mockingbird](https://github.com/crvouga/mockingbird).