feat: sdk regeneration 2026-04-30 (#491)

## Summary
- regenerate the JavaScript SDK to `5.1.1` with the updated Fern
generator output
- add the regenerated public API surface for `listen.v2.language_hint`
and voice-agent inject `behavior`, and serialize repeated `listen.v2`
array query params correctly
- restore JavaScript/TypeScript source compatibility for
`manage.v1.projects.keys.create(projectId)` and the legacy
`CreateKeyV1RequestOne` type alias, and document/freeze those manual
patches for future regens
- make Biome honor `.gitignore` and clean up the hand-maintained browser
examples so generated browser artifacts do not fail lint
- fix flaky browser example tests that logged immediate placeholder
output before the final success state was rendered

## Verification
- `pnpm build` ✅
- `pnpm lint` ✅ (`353` warnings, `3` infos, no error-level diagnostics)
- `DEEPGRAM_PROJECT_ID=3d8f1f2b-92d0-4663-8b7a-6ae230fb2a20 pnpm test` ✅
(`674/674` tests passing)

Author: GregHolmes

.agents/skills/deepgram-js-maintaining-sdk/SKILL.md

@@ -54,7 +54,16 @@ How to identify:
 
 Current temporarily frozen entries:
 
-- **None right now.** `AGENTS.md` explicitly says all current `.fernignore` entries are permanently frozen.
+- `package.json` — Fern's generator produces a minimal `devDependencies` set; we add the following:
+  - `@commitlint/cli`, `@commitlint/config-conventional` — used by `.github/workflows/pr-title-check.yml`
+  - `tsx` — used by `make examples` / `make example-N`
+  - `playwright` — used by `make browser`
+  - `vite`, `terser` — pinned not because we use them directly, but because `.npmrc` sets `minimum-release-age=14400` (10 days) + `strict-peer-dependencies=true`. Without an explicit pin, pnpm tries to satisfy `vitest`'s and `webpack`'s wide peer ranges by picking the latest, which is often too new and the install fails. Pinning forces mature versions. Update the pins (and bump comments below) when you want to move forward.
+  - `@types/node` pinned forward to `^20.17.57` to match the Node features the SDK uses (relax this if Fern's default ever advances past Node 20).
+
+  `pnpm-lock.yaml` is **not** frozen — let Fern regenerate it, then run `pnpm install` after re-applying the `package.json` patch and the lockfile rebuilds correctly.
+- `src/api/resources/manage/resources/v1/resources/projects/resources/keys/client/Client.ts` — keep `manage.v1.projects.keys.create(projectId, request?)` source-compatible with older callers that omit the request body, while still allowing the regenerated request form.
+- `src/api/types/CreateKeyV1Request.ts` — preserve the old exported `CreateKeyV1RequestOne` alias alongside `CreateKeyV1Request` so existing type imports keep compiling.
 
 If you patch a generated file in the future, add it to `.fernignore` with a comment explaining the patch and update this skill plus `AGENTS.md`.
 
@@ -109,6 +118,7 @@ Relevant underlying commands today:
 3. **The repo ships both CJS and ESM.** Validate both outputs after generator changes.
 4. **Browser behavior matters.** The wrapper intentionally diverges for browser WebSocket auth because browsers cannot send arbitrary socket headers.
 5. **`.agents/` is permanently frozen in `.fernignore`.** Treat these skills as hand-written documentation during regeneration; Fern will not touch the folder. Keep this note aligned with `AGENTS.md` whenever the frozen-file list changes.
+6. **`biome.json` should honor `.gitignore`.** Generated browser artifacts like `examples/browser/deepgram.js` are produced by `make browser-serve`; keep them gitignored and let Biome's VCS ignore integration exclude them from linting.
 
 ## Source-of-truth note
 

.fern/metadata.json

@@ -1,7 +1,7 @@
 {
-    "cliVersion": "4.92.0",
+    "cliVersion": "4.107.0",
     "generatorName": "fernapi/fern-typescript-sdk",
-    "generatorVersion": "3.65.5",
+    "generatorVersion": "3.66.4",
     "generatorConfig": {
         "enableInlineTypes": true,
         "namespaceExport": "Deepgram",
@@ -11,10 +11,8 @@
         "shouldGenerateWebsocketClients": true,
         "enableForwardCompatibleEnums": true
     },
-    "originGitCommit": "0d16d3b0d2f3da69dc058ea78f235b2b11288371",
+    "originGitCommit": "05bd7add608b322a6278fa20da22f2ed501d50ef",
     "originGitCommitIsDirty": true,
     "invokedBy": "manual",
-    "requestedVersion": null,
-    "ciProvider": null,
-    "sdkVersion": "5.1.0"
+    "sdkVersion": "5.1.1"
 }

.fernignore

@@ -15,9 +15,11 @@ webpack.config.js
 # Tests
 tests/browser
 tests/esm-build.test.ts
+tests/manual
 tests/unit/agent-providers.test.ts
 tests/unit/async-send-finalize.test.ts
 tests/unit/baseurl-priority.test.ts
+tests/unit/compat-aliases.test.ts
 tests/unit/custom-baseurl.test.ts
 tests/unit/custom-client.test.ts
 tests/unit/error-handling.test.ts
@@ -52,3 +54,21 @@ AGENTS.md
 .claude
 .agents
 .mcp.json
+
+# Unfreeze for regen (temporarily frozen — see AGENTS.md)
+# package.json: Fern's generator produces a minimal devDependencies set; we add
+# @commitlint/cli, @commitlint/config-conventional (PR title workflow), tsx (make
+# examples), playwright (make browser), vite + terser (pinned for the .npmrc
+# minimum-release-age + strict-peer-deps policy, not used directly), and bump
+# @types/node forward to ^20. Swap to package.json.bak before regen.
+package.json
+
+# src/api/resources/manage/resources/v1/resources/projects/resources/keys/client/Client.ts:
+# keep manage.v1.projects.keys.create(request?) source-compatible with older
+# callers that omit the request body. Swap to .bak before regen.
+src/api/resources/manage/resources/v1/resources/projects/resources/keys/client/Client.ts
+
+# src/api/types/CreateKeyV1Request.ts: preserve the old exported
+# CreateKeyV1RequestOne alias alongside CreateKeyV1Request. Swap to .bak before
+# regen.
+src/api/types/CreateKeyV1Request.ts

AGENTS.md

@@ -30,7 +30,8 @@ Current permanently frozen files:
 - `webpack.config.js` — browser build configuration
 - `tests/browser` — browser-specific test suite
 - `tests/esm-build.test.ts` — ESM build validation test
-- `tests/unit/*` — hand-written unit tests
+- `tests/manual` — hand-written manual smoke scripts (e.g. `tests/manual/compat.ts` for the legacy `CreateKeyV1RequestOne` alias). Not picked up by vitest; run with `pnpm tsx`.
+- `tests/unit/*` — hand-written unit tests (includes `compat-aliases.test.ts`, the regression test that proves the legacy `CreateKeyV1RequestOne` type still resolves to `CreateKeyV1Request`)
 - `tests/wire/websocket` — hand-written WebSocket wire tests
 - `tests/wire/listen/v1/transcription.test.ts` — hand-written wire test
 - `vitest.config.mts` — test configuration
@@ -51,7 +52,16 @@ How to identify:
 - Our version is a **modified copy** of what Fern generates (e.g., fixed types, added optional defaults, broadened a union type)
 
 Current temporarily frozen files:
-- _(none currently — all `.fernignore` entries are permanently frozen)_
+- `package.json` — Fern's generator produces a minimal `devDependencies` set; we add the following:
+  - `@commitlint/cli`, `@commitlint/config-conventional` — used by `.github/workflows/pr-title-check.yml`
+  - `tsx` — used by `make examples` / `make example-N`
+  - `playwright` — used by `make browser`
+  - `vite`, `terser` — pinned not because we use them directly, but because `.npmrc` sets `minimum-release-age=14400` (10 days) + `strict-peer-dependencies=true`. Without an explicit pin, pnpm tries to satisfy `vitest`'s and `webpack`'s wide peer ranges by picking the latest, which is often too new and the install fails. Pinning forces mature versions. Update the pins (and bump comments below) when you want to move forward.
+  - `@types/node` pinned forward to `^20.17.57` to match the Node features the SDK uses (relax this if Fern's default ever advances past Node 20).
+
+  `pnpm-lock.yaml` is **not** frozen — let Fern regenerate it, then run `pnpm install` after re-applying the `package.json` patch and the lockfile rebuilds correctly.
+- `src/api/resources/manage/resources/v1/resources/projects/resources/keys/client/Client.ts` — keep `manage.v1.projects.keys.create(projectId, request?)` source-compatible with older callers that omit the request body, while still allowing the regenerated request form.
+- `src/api/types/CreateKeyV1Request.ts` — preserve the old exported `CreateKeyV1RequestOne` alias alongside `CreateKeyV1Request` so existing type imports keep compiling.
 
 **Note:** If you need to patch a Fern-generated file, add it to `.fernignore` with a comment describing the patch, and add it to the "temporarily frozen" list above.
 

biome.json

@@ -2,7 +2,9 @@
     "$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
     "root": true,
     "vcs": {
-        "enabled": false
+        "clientKind": "git",
+        "enabled": true,
+        "useIgnoreFile": true
     },
     "files": {
         "ignoreUnknown": true,

examples/09-voice-agent.ts

@@ -53,7 +53,7 @@ async function voiceAgent() {
       console.error("Error:", error);
     });
 
-    let keepAliveInterval;
+    let keepAliveInterval: ReturnType<typeof setInterval> | undefined;
     deepgramConnection.on("close", () => {
       console.log("Connection closed");
       if (keepAliveInterval) {

examples/36-agent-inject-message.ts

@@ -78,7 +78,7 @@ async function agentInjectMessage() {
       console.error("Error:", error);
     });
 
-    let keepAliveInterval;
+    let keepAliveInterval: ReturnType<typeof setInterval> | undefined;
     deepgramConnection.on("close", () => {
       console.log("Connection closed");
       if (keepAliveInterval) {

examples/browser/01-authentication-api-key.html

@@ -65,7 +65,7 @@ <h1>Authentication with API Key</h1>
   <p>This example demonstrates authentication through the proxy server. The API key is configured via the DEEPGRAM_API_KEY environment variable on the proxy server.</p>
 
   <div class="container">
-    <button id="runExample">Run Example</button>
+    <button type="button" id="runExample">Run Example</button>
   </div>
 
   <div id="output"></div>
@@ -121,4 +121,3 @@ <h1>Authentication with API Key</h1>
   </script>
 </body>
 </html>
-

examples/browser/02-authentication-access-token.html

@@ -65,7 +65,7 @@ <h1>Authentication with Access Token</h1>
   <p>Access tokens are temporary (30-second TTL) and must be obtained using an API key. The API key is configured via the DEEPGRAM_API_KEY environment variable on the proxy server. Uses Bearer scheme in Authorization header.</p>
 
   <div class="container">
-    <button id="runExample">Run Example</button>
+    <button type="button" id="runExample">Run Example</button>
   </div>
 
   <div id="output"></div>
@@ -165,4 +165,3 @@ <h1>Authentication with Access Token</h1>
   </script>
 </body>
 </html>
-

examples/browser/03-authentication-proxy.html

@@ -69,7 +69,7 @@ <h1>Proxy Authentication</h1>
   <p class="warning"><strong>Important:</strong> The proxy server sets the Authorization header and forwards requests to Deepgram's API.</p>
 
   <div class="container">
-    <button id="runExample">Run Example</button>
+    <button type="button" id="runExample">Run Example</button>
   </div>
 
   <div id="output"></div>
@@ -120,4 +120,3 @@ <h1>Proxy Authentication</h1>
   </script>
 </body>
 </html>
-