feat: preserve SDK compatibility after regen

Restore the projects.keys.create compatibility patch and legacy CreateKeyV1RequestOne alias, and keep generated browser artifacts out of lint while cleaning hand-maintained examples so the regenerated branch remains source-compatible and releasable.

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
 

.fernignore

@@ -52,3 +52,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

@@ -51,7 +51,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>
-

examples/browser/04-transcription-prerecorded-url.html

@@ -67,7 +67,7 @@ <h1>Transcribe Audio from URL</h1>
   <div class="container">
     <label for="audioUrl">Audio URL:</label>
     <input type="text" id="audioUrl" placeholder="https://dpgr.am/spacewalk.wav" value="https://dpgr.am/spacewalk.wav">
-    <button id="runExample">Transcribe</button>
+    <button type="button" id="runExample">Transcribe</button>
   </div>
 
   <div id="output"></div>
@@ -139,4 +139,3 @@ <h1>Transcribe Audio from URL</h1>
   </script>
 </body>
 </html>
-