v5.0.0-alpha.1

This is the first alpha release of Deepgram JavaScript SDK v5, a complete rebuild of the SDK using Fern for auto-generation. This release introduces significant architectural improvements, better TypeScript support, and a more structured API.

🚀 Major Changes

Complete SDK Regeneration with Fern

• Auto-generated SDK: The entire SDK is now auto-generated from our API definition using Fern
• Better maintainability: SDK automatically stays in sync with API changes
• Improved type safety: Full TypeScript support across all API methods
• Consistent structure: Versioned endpoints (v1, v2) with clear namespaces

Breaking Changes

Client Initialization

• Changed: createClient() function → new DeepgramClient() constructor
• Changed: key property → apiKey property in options
• Removed: Support for passing API key as first parameter (must use options object)
• Migration: See MIGRATION_GUIDE_V4_TO_V5.md for details

API Structure

• Changed: All API methods now require version namespaces
  • deepgram.listen.transcribeUrl() → deepgram.listen.v1.media.transcribeUrl()
  • deepgram.manage.projects.list() → deepgram.manage.v1.projects.list()
  • deepgram.speak.generate() → deepgram.speak.v1.audio.generate()
• Changed: Additional resource namespaces for better organization (e.g., media, audio, projects)

Error Handling

• Changed: No longer returns { result, error } wrapper
• Changed: Errors are now thrown as exceptions (use try/catch)
• Added: Error objects include statusCode, body, and rawResponse properties

WebSocket API

• Changed: listen.transcription.live() → listen.v1.connect() (async)
• Changed: transcript event → message event with type checking
• Changed: Must explicitly call connect() and waitForOpen()
• Changed: Boolean-like options now use string values ("true" instead of true)

✨ New Features

V2 WebSocket API Support

• Added: Support for Deepgram's V2 WebSocket API (listen.v2.connect())
• Added: New message types: Connected, TurnInfo, CloseStream
• Added: Example demonstrating V2 WebSocket usage (examples/26-transcription-live-websocket-v2.js)

Enhanced TypeScript Support

• Added: Full type definitions for all API methods
• Added: Separate type definitions for CommonJS (.d.ts) and ES Modules (.d.mts)
• Added: Better IntelliSense and autocomplete support
• Added: Type-safe event handling for WebSocket connections

Improved Package Structure

• Added: Dual module support (CommonJS and ES Modules)
• Added: Proper exports field in package.json for better module resolution
• Added: reference.md with comprehensive API documentation

📚 Documentation

New Documentation

• Added: Comprehensive migration guide (MIGRATION_GUIDE_V4_TO_V5.md)
  • Step-by-step migration instructions
  • Code examples for all major API changes
  • Migration checklist
• Added: Complete API reference (reference.md)
• Updated: README with v5 examples and migration information

Examples

• Added: 26 comprehensive examples covering all SDK functionality:
  • Authentication (API key, access token, proxy)
  • Prerecorded transcription (URL, file, callback)
  • Live transcription (WebSocket v1 and v2)
  • Voice Agent
  • Text-to-Speech (single and streaming)
  • Text Intelligence
  • Management API (projects, keys, members, invites, usage, billing, models)
  • On-premises credentials
  • Configuration options
  • Error handling
  • Binary responses
• Removed: Old browser-based examples (replaced with Node.js examples)

🔧 Infrastructure & Tooling

Build System

• Changed: Build process now generates both CommonJS and ES Module outputs
• Added: Separate TypeScript configs for CJS (tsconfig.cjs.json) and ESM (tsconfig.esm.json)
• Added: Script to rename ESM files to .mjs extension (scripts/rename-to-esm-files.js)

Code Quality

• Changed: ESLint → Biome for linting and formatting
• Added: Biome configuration (biome.json)
• Removed: ESLint, Prettier, and related configuration files

Testing

• Changed: Jest → Vitest for testing
• Added: Vitest configuration (vitest.config.mts)
• Added: Separate test projects for unit and wire tests

CI/CD

• Updated: GitHub Actions workflow (ci.yml)
• Removed: Old CI workflows (consolidated into single workflow)

Package Management

• Added: pnpm-workspace.yaml for workspace support
• Updated: Package manager to [email protected]
• Updated: .npmignore with comprehensive exclusion rules

🐛 Bug Fixes & Improvements

WebSocket Improvements

• Fixed: WebSocket connection issues in auto-generated code
• Fixed: Custom client implementation to resolve WebSocket problems
• Improved: WebSocket event handling and type safety

Authentication

• Fixed: Documentation discrepancy for auth tokens
• Improved: Authentication examples and documentation

Configuration

• Improved: Scoped configuration support
• Improved: Base URL configuration (baseUrl option)

📦 Package Details

• Version: 5.0.0-alpha.1
• Node.js: Requires Node.js >= 18.0.0
• Dependencies:
  • ws: ^8.16.0 (for WebSocket support)
• TypeScript: ~5.7.2

🔄 Migration Path

For detailed migration instructions, see MIGRATION_GUIDE_V4_TO_V5.md.

Quick migration checklist:

1. Update client initialization: createClient() → new DeepgramClient()
2. Change key → apiKey in options
3. Add version namespaces to all API calls (v1, v2)
4. Update error handling to use try/catch
5. Update WebSocket connections to use async connect() and waitForOpen()

⚠️ Alpha Release Notes

This is an alpha release and may contain breaking changes in future alpha/beta releases. We recommend:

• Testing thoroughly before using in production
• Providing feedback on any issues or improvements needed
• Reviewing the migration guide before upgrading

📝 Files Changed

Added

• MIGRATION_GUIDE_V4_TO_V5.md - Comprehensive migration guide
• reference.md - Complete API reference documentation
• biome.json - Biome configuration
• pnpm-workspace.yaml - pnpm workspace configuration
• scripts/rename-to-esm-files.js - ESM file renaming script
• src/BaseClient.ts - Base client implementation
• 26 example files in examples/ directory
• .fernignore and .fern/metadata.json - Fern configuration

Removed

• ESLint configuration files
• Prettier configuration files
• Old browser-based examples
• Jest configuration
• Various GitHub templates and workflows (consolidated)

Modified

• package.json - Updated dependencies, scripts, and package structure
• README.md - Updated with v5 documentation and examples
• .npmignore - Comprehensive exclusion rules
• .gitignore - Updated ignore patterns
• CONTRIBUTING.md - Updated contribution guidelines

🙏 Acknowledgments

This release represents a significant effort to modernize the SDK and provide better developer experience. Thank you to all contributors and users who provided feedback during development.

---

For questions or issues, please visit:

• GitHub Issues
• Deepgram Documentation
• API Reference

v4.11.2

4.11.2 (2025-08-06)

Bug Fixes

• typo to kick off release (6ba50f6)
• fix agent timing issue(b487172)

v4.11.1

4.11.1 (2025-07-25)

Bug Fixes

• fixes mips_opt_out placement (c342789)

v4.11.0

4.11.0 (2025-07-21)

Features

• adds support for agent mip_opt_out (#421) (76f9653)

v4.10.0

4.10.0 (2025-07-21)

Features

• adds ttl_seconds support (#420) (5ed8004)

v4.9.1

4.9.1 (2025-07-09)

Bug Fixes

• use type-only imports for Node.js stream module (de726ef)

v4.9.0

4.9.0 (2025-07-08)

Features

• adds support for speak fallback (#414) (8e59b55)

v4.8.0

4.8.0 (2025-07-08)

Features

• agent – the SDK now supports the Insert User Message message ([aa6cee2](aa6cee2))
• tests – waitForConnection now times out if the socket never opens ([a663956](a663956))
• tests – all example files are simpler and follow one style (81689db)
• tests – transcribeUrl integration (f730d83)
• tests – TTS (d308561)
• tests – WebSockets e2e + unit (5d85b4b)
• tests – Other API e2e tests (28d33f8)
• tests – General unit tests & fixture-based e2e requests (6093bb7, 028d44f, 8c017c0)
• tests – Offline runs now use mock API responses (2b004d0)

Bug Fixes

• Docs – add missing language tag to markdown code block (249cf40)
• Build – include Node.js polyfills in the webpack UMD bundle (5cb550b)
• Helpers – guard against null injection (f16d74f)
• Tests – fix ESLint directive in test-offline.js (bdfa175)
• CI – workflow, fetchWithAuth call style, and live-client error-event handling (30328b3, d6e09b7, 44b0472, 9350dbf)

v4.7.0

4.7.0 (2025-06-25)

Features

• errors: enhance WebSocket error output and abstract connection setup (36778e9)

v4.6.0

4.6.0 (2025-06-24)

Features

• auth: add support for DEEPGRAM_ACCESS_TOKEN as per the other SDKs (7924959)