Maintaining the Deepgram JavaScript / TypeScript SDK

This SDK is generated by Fern. Most files under src/ are auto-generated and should not be edited directly. Some files are hand-written or protected in .fernignore so Fern does not overwrite them.

When a new Fern generator release is available, prepare the repo so Fern can replace generated output, then re-apply any still-needed manual work after reviewing the diff.

Freeze classification rules

Every entry in .fernignore falls into one of two categories. The comment above the entry is the first clue, but use these rules when in doubt.

Never unfreeze (permanently frozen)

These files are entirely hand-written or repo-maintained. Fern should never own them.

How to identify:

• The file was created by Deepgram, not by Fern (src/CustomClient.ts, curated exports, helper scripts, hand-written tests).
• The file is documentation, tooling, config, or examples managed outside generator output.
• The file lives outside src/api/ or deliberately wraps generated code.

Current permanently frozen entries from .fernignore / AGENTS.md:

• src/CustomClient.ts — custom wrapper for auth prefixing, session ID propagation, browser/Node WebSocket handling, reconnect behavior, binary message fixes, and createConnection() aliases
• src/index.ts — curated re-exports with backwards-compatible namespace behavior
• scripts/fix-wire-test-imports.js, scripts/revert-wire-test-imports.js — post-generation import fixups
• scripts/proxy-server.js — development proxy
• scripts/validate-esm-build.mjs — ESM build validation
• webpack.config.js — browser bundle config
• tests/browser/ — browser-specific suite
• tests/esm-build.test.ts — ESM validation test
• tests/unit/* — hand-written unit tests
• tests/wire/websocket/ — hand-written websocket wire tests
• tests/wire/listen/v1/transcription.test.ts — hand-written wire test
• vitest.config.mts — test config
• Makefile — developer command runner
• MIGRATION_GUIDE_V4_TO_V5.md — migration docs
• README.md, CHANGELOG.md, docs/, examples/ — repo docs and examples
• .npmignore, .gitignore, .npmrc, .github/ — package/repo config
• CLAUDE.md, AGENTS.md, .claude/, .agents/, .mcp.json — agent/tooling files

Unfreeze for regen (temporarily frozen)

These are generated files with local patches. They stay frozen between regens, but should be temporarily swapped to .bak during a regen prep so Fern can overwrite the original path.

How to identify:

• Fern would recreate the file if it were removed.
• Your current copy is a patched version of generator output, not a fully hand-written file.

Current temporarily frozen entries:

• None right now. AGENTS.md explicitly says all current .fernignore entries are permanently frozen.

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.

Prepare repo for regeneration

1. Create a branch from main named lo/sdk-gen-<YYYY-MM-DD>.
2. Push it and open a PR titled chore: SDK regeneration <YYYY-MM-DD>.
3. Read .fernignore and classify every entry.
4. For each temporarily frozen file only:
   • copy it to <filename>.bak beside the original
   • replace the original path in .fernignore with the .bak path
5. Leave permanently frozen entries untouched.
6. Commit as chore: unfreeze files pending regen and push.

After regeneration

1. Diff each .bak file against the newly generated original.
2. Re-apply only the patches that are still needed.
3. Change .fernignore entries from .bak back to the original path for files that still need freezing.
4. Remove .fernignore entries entirely for files where the generator is now correct.
5. Delete the .bak files.
6. Run verification.
7. Commit as chore: re-apply manual patches after regen and push.

Verification commands

Repo guidance in AGENTS.md says:

make build && make test && make lint

Package scripts in package.json resolve to:

pnpm build
pnpm test
pnpm lint
pnpm check

Relevant underlying commands today:

• pnpm build → tsc --project ./tsconfig.cjs.json + tsc --project ./tsconfig.esm.json + ESM rename script
• pnpm test → vitest
• pnpm lint / pnpm check → Biome lint/check

JS-specific maintainer notes

1. Do not edit most generated files under src/api/ directly. Prefer Fern input changes or post-regen patch review.
2. src/CustomClient.ts is the highest-risk permanent wrapper. It carries auth prefixing, browser subprotocol auth, custom websocket startup, binary handling, and the user-facing createConnection() aliases used by examples.
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.

Source-of-truth note

AGENTS.md is the maintainer source of truth in this repo. Keep this skill aligned with it whenever the regeneration workflow or frozen-file list changes.