feat: wire Speak V2 (Flux) streaming into DeepgramClient + cover new regen surface

Speak V2 (Flux streaming TTS, /v2/speak) shipped in the 2026-07-09 regen but
was not usable via DeepgramClient: it was not wrapped by CustomClient, and the
generated V2 socket parses every frame as JSON (which drops binary audio).

- CustomClient: add WrappedSpeakV2Client + binary-aware WrappedSpeakV2Socket,
  a speak.v2 getter, the SpeakV2ConnectionArgs type and SpeakV2ClientWithWebSocket
  interface — mirrors the speak.v1 pair so auth/session/custom-transport apply.
- transport.ts: add "speak.v2" to the streaming service union.
- examples: 37 (Flux streaming TTS), 38 (listen v2 end-of-turn tuning); registered
  in the Makefile (targets, run list, TOTAL, help).
- tests: speak-v2-tts wire test (binary audio + control messages), agent
  UpdateListen/ListenUpdated wire test, speak.v2 accessor unit test, and
  regen-constraints coverage for the new eot_* provider fields, agent listen
  update types, and Speak V2 types.
- AGENTS.md: document the CustomClient/transport streaming-wrapper rule and
  correct the stale ListenV2CloseStream.Type note (keeps deprecated members).

Author: GregHolmes

AGENTS.md

@@ -22,9 +22,9 @@ How to identify:
 - The file lives **outside `src/api/`** in a hand-maintained location (e.g., `.claude/`, `docs/`, `scripts/`)
 
 Current permanently frozen files:
-- `src/CustomClient.ts` — entirely custom wrapper with WebSocket management, auth providers, session ID handling, `transportFactory` plumbing, and the `reconnect` flag (auto-disabled when a custom transport is in use); no Fern equivalent
+- `src/CustomClient.ts` — entirely custom wrapper with WebSocket management, auth providers, session ID handling, `transportFactory` plumbing, and the `reconnect` flag (auto-disabled when a custom transport is in use); no Fern equivalent. **Wraps every streaming client** (`agent.v1`, `listen.v1`, `listen.v2`, `speak.v1`, `speak.v2`) so connections route through `createWebSocketConnection` (auth/session/custom transport) and so binary audio frames are handled correctly. When the generator adds a new streaming resource (e.g. the 2026-07-09 `speak.v2` Flux TTS API), add a matching `Wrapped…Client` + binary-aware `Wrapped…Socket`, a getter on the parent `Wrapped…Client`, and the `…WithWebSocket` interface here — mirror the existing `speak.v1` pair.
 - `src/index.ts` — curated re-export file with custom namespace handling
-- `src/transport.ts` — hand-maintained pluggable transport interface for SageMaker and other custom streaming transports
+- `src/transport.ts` — hand-maintained pluggable transport interface for SageMaker and other custom streaming transports. The `service` union enumerates every streaming resource (`agent.v1` | `listen.v1` | `listen.v2` | `speak.v1` | `speak.v2`); extend it when `CustomClient.ts` gains a new wrapped streaming client.
 - `scripts/fix-wire-test-imports.js`, `scripts/revert-wire-test-imports.js` — post-generation import fixup scripts
 - `scripts/proxy-server.js` — development proxy server
 - `scripts/validate-esm-build.mjs` — ESM build validation
@@ -66,7 +66,7 @@ Current temporarily frozen files:
 - `src/api/types/CreateKeyV1Request.ts` — preserve the old exported `CreateKeyV1RequestOne` alias alongside `CreateKeyV1Request` so existing type imports keep compiling.
 - `src/api/resources/agent/resources/v1/types/AgentV1Settings.ts` — backward-compat patch for the `AgentV1Settings.Agent` namespace. The 2026-05-06 regen restructured `Agent` from an interface with named sub-types into a union with anonymous shapes plus a string variant (`{...} | string`) for the new agent-by-ID-string flow. We restore the original interface form so existing imports of the sub-types (`Agent.Context`, `Agent.Listen`, `Agent.Think`, `Agent.Speak`, `Agent.Context.Messages.Item`) AND direct field reads (`settings.agent.context`, `.greeting`, etc.) keep compiling in TS strict mode without a `typeof` narrowing guard. The new agent-by-ID-string variant is surfaced as the opt-in `AgentReference = Agent | string` alias for callers who want to pass a string ID at the type level. Mirrors the Python SDK's compat shims for the same regen. Regression coverage in `tests/unit/compat-aliases.test.ts`.
 - `src/api/types/DeepgramListenProviderV2.ts` — backward-compat shim recreating the `DeepgramListenProviderV2.LanguageHint` (`string | string[]`) namespace type that the 2026-06-16 regen removed when it replaced the `language_hint` field with `language_hints?: string[]`. The nested `AgentV1SettingsAgentContextListenProviderV2.LanguageHint` alias (below) and the `tests/unit/compat-aliases.test.ts` regression test still reference it, so we recreate the namespace via declaration merge in this generated file and freeze it. Mirrors the Python SDK's `DeepgramListenProviderV2LanguageHint` shim. **Also** re-adds the deprecated optional `language_hint` field (the regen renamed it to `language_hints`) so existing call sites keep compiling — avoids a major-version break. The singular field was never honored by the API, so this is compile-compat only.
-- `src/api/resources/listen/resources/v2/types/ListenV2CloseStream.ts` — backward-compat shim. The 2026-06-16 regen corrected the `type` field to the literal `"CloseStream"` and dropped the `ListenV2CloseStream.Type` namespace, which wrongly included `"Finalize"`/`"KeepAlive"` (copied from v1's control-message enum). We restore the `Type` namespace with **only** the valid `"CloseStream"` value so existing `ListenV2CloseStream.Type` references keep compiling, without resurrecting the invalid values — avoids a major-version break.
+- `src/api/resources/listen/resources/v2/types/ListenV2CloseStream.ts` — backward-compat shim. The 2026-06-16 regen corrected the `type` field to the literal `"CloseStream"` and dropped the `ListenV2CloseStream.Type` namespace. We restore the `Type` namespace so existing `ListenV2CloseStream.Type` references keep compiling. The namespace keeps `"Finalize"` and `"KeepAlive"` as **deprecated** members (marked `@deprecated`, valid value is `"CloseStream"`) rather than removing them outright — dropping them would break existing references, so they're retained for one more major and the shim also widens the `type` field to `ListenV2CloseStream.Type` to preserve assignability. Regression coverage in `tests/unit/regen-constraints.test.ts` (asserts `CloseStream` plus the deprecated `Finalize`/`KeepAlive` members).
   - **Note:** `src/api/resources/agent/resources/v1/types/AgentV1SettingsAgentListenProvider.ts` was *unfrozen* in the 2026-06-16 regen — the generator now emits a type structurally equal to `AgentV1SettingsAgentContextListenProvider` (verified by the `Equals<…>` assertion in `tests/unit/compat-aliases.test.ts`), so the hand-written alias is no longer needed and Fern owns the file again.
 - `biome.json` — Fern's generator emits `"vcs": { "enabled": false }`, which makes biome lint every tracked-or-untracked file under the repo, including `examples/browser/deepgram.js` (the bundle produced by `make browser-serve`, which is `.gitignore`d but not biome-ignored). We restore `clientKind: "git"`, `enabled: true`, `useIgnoreFile: true` so generated browser artifacts stay out of lint.
 - `src/api/resources/agent/resources/v1/types/AgentV1SettingsAgentContextListenProvider.ts` — backward-compat shim for the listen-provider dedup in the 2026-05-14 regen. The new spec consolidated 5 PascalCase listen-provider types into top-level `DeepgramListenProviderV1` / `DeepgramListenProviderV2` and dropped the nested `AgentV1SettingsAgentContextListenProviderV2.LanguageHint` namespace path. We restore the nested namespace as a one-line alias `type LanguageHint = DeepgramListenProviderV2.LanguageHint` inside the outer namespace so deep import paths keep resolving. Regression coverage in `tests/unit/compat-aliases.test.ts`.

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help examples example-1 example-2 example-3 example-4 example-5 example-6 example-7 example-8 example-9 example-10 example-11 example-12 example-13 example-14 example-15 example-16 example-17 example-18 example-19 example-20 example-21 example-22 example-23 example-24 example-25 example-26 example-27 example-28 example-29 example-30 example-31 example-32 example-33 example-34 example-35 example-36 test test-esm typecheck-tests lint build browser browser-serve
+.PHONY: help examples example-1 example-2 example-3 example-4 example-5 example-6 example-7 example-8 example-9 example-10 example-11 example-12 example-13 example-14 example-15 example-16 example-17 example-18 example-19 example-20 example-21 example-22 example-23 example-24 example-25 example-26 example-27 example-28 example-29 example-30 example-31 example-32 example-33 example-34 example-35 example-36 example-37 example-38 test test-esm typecheck-tests lint build browser browser-serve
 
 # Default target
 help:
@@ -11,7 +11,7 @@ help:
 	@printf "  \033[1;32mmake test-esm\033[0m          - Run ESM build validation tests\n"
 	@echo ""
 	@printf "\033[1;33mExample Commands:\033[0m\n"
-	@printf "  \033[1;32mmake examples\033[0m          - Run all example scripts (1-32) sequentially\n"
+	@printf "  \033[1;32mmake examples\033[0m          - Run all example scripts (1-38) sequentially\n"
 	@printf "  \033[1;32mmake example-N\033[0m         - Run a specific example by number (e.g., make example-1)\n"
 	@printf "  \033[1;32mmake browser\033[0m           - Run browser tests\n"
 	@printf "  \033[1;32mmake browser-serve\033[0m     - Serve the browser examples for manual testing\n"
@@ -57,7 +57,7 @@ help:
 # Run all examples
 examples:
 	@printf "\033[1;36mRunning all examples...\033[0m\n\n"; \
-	TOTAL=36; \
+	TOTAL=38; \
 	PASS_COUNT=0; \
 	FAIL_COUNT=0; \
 	PASSED_LIST=""; \
@@ -136,6 +136,8 @@ examples:
 	run_example 34 "examples/34-agent-custom-providers.ts" "Agent Custom Providers"; \
 	run_example 35 "examples/35-agent-provider-combinations.ts" "Agent Provider Combinations"; \
 	run_example 36 "examples/36-agent-inject-message.ts" "Agent Inject Message"; \
+		run_example 37 "examples/37-text-to-speech-streaming-flux.ts" "Text-to-Speech Streaming Flux (v2)"; \
+		run_example 38 "examples/38-transcription-flux-eot.ts" "Transcription Flux End-of-Turn"; \
 	\
 	printf "\n\033[1;36m=========================================\033[0m\n"; \
 	printf "\033[1;36mSummary Report\033[0m\n"; \
@@ -280,6 +282,12 @@ example-35:
 example-36:
 	pnpm exec tsx examples/36-agent-inject-message.ts
 
+example-37:
+	pnpm exec tsx examples/37-text-to-speech-streaming-flux.ts
+
+example-38:
+	pnpm exec tsx examples/38-transcription-flux-eot.ts
+
 lint:
 	pnpm exec biome lint --skip-parse-errors --no-errors-on-unmatched --max-diagnostics=none
 	pnpm exec biome format --skip-parse-errors --no-errors-on-unmatched --max-diagnostics=none

examples/37-text-to-speech-streaming-flux.ts

@@ -0,0 +1,121 @@
+/**
+ * Example: Text-to-Speech Streaming with Flux (WebSocket, /v2/speak)
+ *
+ * Connect to Deepgram's v2 streaming TTS websocket (Flux voices) and send text
+ * to synthesize speech. Flux uses the v2 message set: Speak / Flush / Close, and
+ * emits Connected, SpeechStarted, SpeechMetadata, Flushed and SessionMetadata
+ * control messages alongside binary audio frames.
+ *
+ * Note: Flux models use the `flux-{voice}-{language}` naming (e.g. flux-alexis-en).
+ * Aura voices are not valid on /v2/speak — use speak.v1 for Aura.
+ */
+
+const { DeepgramClient } = require("../dist/cjs/index.js");
+
+const deepgramClient = new DeepgramClient({
+    apiKey: process.env.DEEPGRAM_API_KEY,
+});
+
+async function textToSpeechStreamingFlux() {
+    try {
+        // Create a connection object with Flux TTS options (not yet connected)
+        const deepgramConnection = await deepgramClient.speak.v2.createConnection({
+            model: "flux-alexis-en",
+            encoding: "linear16",
+            sample_rate: "24000",
+        });
+
+        // Set up event handlers before connecting
+        deepgramConnection.on("open", () => {
+            console.log("Connection opened");
+        });
+
+        let flushed = false;
+
+        deepgramConnection.on("message", (data) => {
+            // Binary audio frames arrive as ArrayBuffer/Blob (or string in some runtimes)
+            if (typeof data === "string" || data instanceof ArrayBuffer || data instanceof Blob) {
+                console.log(
+                    "Audio received (length):",
+                    data instanceof ArrayBuffer ? data.byteLength : data instanceof Blob ? data.size : data.length,
+                );
+                // Process audio data here
+                return;
+            }
+
+            switch (data.type) {
+                case "Connected":
+                    console.log("Connected:", data.request_id, data.model_name);
+                    break;
+                case "SpeechStarted":
+                    console.log("Speech started:", data.speech_id);
+                    break;
+                case "SpeechMetadata":
+                    console.log("Speech metadata:", data);
+                    break;
+                case "Flushed":
+                    console.log("Flushed:", data.speech_id);
+                    flushed = true;
+                    // Wait a moment for any remaining audio, then close
+                    setTimeout(() => {
+                        deepgramConnection.close();
+                    }, 1000);
+                    break;
+                case "SessionMetadata":
+                    console.log("Session metadata:", data);
+                    break;
+                case "Warning":
+                    console.warn("Warning:", data.code, data.description);
+                    break;
+                case "Error":
+                    console.error("Error:", data.code, data.description);
+                    break;
+                default:
+                    console.log("Unknown message type:", data);
+            }
+        });
+
+        deepgramConnection.on("error", (error) => {
+            console.error("Error:", error);
+        });
+
+        deepgramConnection.on("close", () => {
+            console.log("Connection closed");
+        });
+
+        // Connect to the websocket
+        deepgramConnection.connect();
+
+        // Wait for connection to open before sending data
+        try {
+            await deepgramConnection.waitForOpen();
+
+            const text = "Hello, this is a test of Deepgram's Flux streaming text-to-speech API.";
+
+            // Send text for synthesis (type: "Speak"), then Flush to finish the turn
+            deepgramConnection.sendSpeak({ type: "Speak", text });
+            deepgramConnection.sendFlush({ type: "Flush" });
+
+            // Fallback close in case Flushed never comes
+            setTimeout(() => {
+                if (!flushed) {
+                    console.log("Timeout waiting for Flushed message, closing connection");
+                    deepgramConnection.close();
+                }
+            }, 10000);
+
+            // Kill websocket after 1 minute, so we can run these in CI
+            setTimeout(() => {
+                deepgramConnection.close();
+                process.exit(0);
+            }, 60000);
+        } catch (error) {
+            console.error("Error waiting for connection:", error);
+            deepgramConnection.close();
+        }
+    } catch (error) {
+        console.error("Error setting up connection:", error);
+    }
+}
+
+textToSpeechStreamingFlux();

examples/38-transcription-flux-eot.ts

@@ -0,0 +1,101 @@
+/**
+ * Example: Live Transcription (V2 / Flux) with End-of-Turn tuning
+ *
+ * Flux exposes end-of-turn (EOT) controls on the /v2/listen websocket that let
+ * you tune how eagerly a turn is finalized:
+ *
+ *   - eot_threshold:       EOT confidence required to finish a turn (0.5 - 0.9, default 0.7)
+ *   - eager_eot_threshold: EOT confidence to fire an *eager* end-of-turn event, enabling
+ *                          EagerEndOfTurn / TurnResumed events (0.3 - 0.9)
+ *   - eot_timeout_ms:      a turn is finished this many ms after speech regardless of
+ *                          EOT confidence (default 5000)
+ *
+ * These are sent as query parameters on the connection.
+ */
+
+const { DeepgramClient } = require("../dist/cjs/index.js");
+const { createReadStream } = require("fs");
+
+const deepgramClient = new DeepgramClient({
+    apiKey: process.env.DEEPGRAM_API_KEY,
+});
+
+async function liveTranscriptionFluxEot() {
+    try {
+        const deepgramConnection = await deepgramClient.listen.v2.createConnection({
+            model: "flux-general-en",
+            // End-of-turn tuning for Flux
+            eot_threshold: 0.8,
+            eager_eot_threshold: 0.5,
+            eot_timeout_ms: 4000,
+        });
+
+        deepgramConnection.on("open", () => {
+            console.log("Connection opened (Flux with EOT tuning)");
+        });
+
+        deepgramConnection.on("message", (data) => {
+            switch (data.type) {
+                case "Connected":
+                    console.log("Connected:", data);
+                    break;
+                case "TurnInfo":
+                    console.log("Turn Info:", data);
+                    break;
+                case "EagerEndOfTurn":
+                    console.log("Eager end-of-turn:", data);
+                    break;
+                case "TurnResumed":
+                    console.log("Turn resumed:", data);
+                    break;
+                case "FatalError":
+                    console.error("Fatal Error:", data);
+                    deepgramConnection.close();
+                    break;
+                default:
+                    console.log("Message:", data);
+            }
+        });
+
+        deepgramConnection.on("error", (error) => {
+            console.error("Error:", error);
+        });
+
+        deepgramConnection.on("close", () => {
+            console.log("Connection closed");
+        });
+
+        deepgramConnection.connect();
+
+        try {
+            await deepgramConnection.waitForOpen();
+
+            const audioStream = createReadStream("./examples/spacewalk.wav");
+
+            audioStream.on("data", (chunk) => {
+                deepgramConnection.sendMedia(chunk);
+            });
+
+            audioStream.on("end", () => {
+                console.log("Audio stream ended");
+                setTimeout(() => {
+                    deepgramConnection.sendCloseStream({ type: "CloseStream" });
+                }, 3000);
+            });
+
+            // Kill websocket after 60 seconds so this can run in CI
+            setTimeout(() => {
+                console.log("Timeout reached, closing connection");
+                deepgramConnection.close();
+                process.exit(0);
+            }, 60000);
+        } catch (error) {
+            console.error("Error waiting for connection:", error);
+            deepgramConnection.close();
+        }
+    } catch (error) {
+        console.error("Error setting up connection:", error);
+    }
+}
+
+liveTranscriptionFluxEot();