Skip to content

v5.0.0-alpha.1

Pre-release
Pre-release

Choose a tag to compare

View all tags
@naomi-deepgram naomi-deepgram released this 16 Dec 00:19
v5.0.0-alpha.1
0291ebe
This commit was signed with the committer’s verified signature.
naomi-deepgram Naomi Carrigan
GPG key ID: 501DEC4A3B2958C9
Verified
Learn about vigilant mode.

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 pnpm@10.20.0
  • 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:

Assets 2
Loading