diff --git a/docs/Migrating-v0.5-to-v0.6.md b/docs/Migrating-v0.5-to-v0.6.md new file mode 100644 index 0000000..aeb9d46 --- /dev/null +++ b/docs/Migrating-v0.5-to-v0.6.md @@ -0,0 +1,186 @@ +# v0.5 to v0.6 Migration Guide + +This guide helps you migrate from Deepgram Java SDK v0.5.0 to v0.6.0. The `0.6.0` release is still pre-`1.0`, and it ships breaking source changes from the June 15 SDK regeneration along with several additive features. + +The breaking changes are all **source/compile-time** changes for SDK users. The on-the-wire payloads are unchanged — your requests and responses still serialize the same way; only the Java API surface moved. + +The biggest changes are: + +1. `ListenV2CloseStream` no longer takes a `type` — build it with `ListenV2CloseStream.builder().build()`, and `ListenV2CloseStreamType` was removed +2. `DeepgramListenProviderV2` renamed `language_hint` to `language_hints` and made it a list — `getLanguageHint()` became `getLanguageHints()` returning `Optional>`, and `DeepgramListenProviderV2LanguageHint` was removed +3. `ListenV2TurnInfoWordsItem.getStart()` / `getEnd()` now return `Optional` instead of `double` (Flux word timestamps) + +## Table of Contents + +- [Installation](#installation) +- [Configuration Changes](#configuration-changes) +- [Authentication Changes](#authentication-changes) +- [API Method Changes](#api-method-changes) + - [Listen V2 (WebSocket)](#listen-v2-websocket) +- [Type Changes](#type-changes) + - [Close Stream Type](#close-stream-type) + - [Listen Provider V2 Language Hints](#listen-provider-v2-language-hints) + - [Flux Word Timestamps](#flux-word-timestamps) + - [Other Additive Types](#other-additive-types) +- [Breaking Changes Summary](#breaking-changes-summary) + +## Installation + +Upgrade to `0.6.0` with Gradle or Maven. + +**Gradle** + +```groovy +dependencies { + implementation 'com.deepgram:deepgram-java-sdk:0.6.0' +} +``` + +**Maven** + +```xml + + com.deepgram + deepgram-java-sdk + 0.6.0 + +``` + +## Configuration Changes + +No required client-construction changes. Existing `DeepgramClient.builder()` usage still works. + +## Authentication Changes + +No changes. API key, access token, and session ID configuration all work the same as in `0.5.0`. + +## API Method Changes + +### Listen V2 (WebSocket) + +No breaking client-method changes. The breaking changes are all on the request/response **types** used with the V2 WebSocket client (see [Type Changes](#type-changes)). + +`0.6.0` adds an optional `profanity_filter` query parameter to the V2 WebSocket connection via `V2ConnectOptions`, and a `diarize_model` option on streaming requests (with `diarize` now documented as deprecated). Both are additive. + +## Type Changes + +### Close Stream Type + +`ListenV2CloseStream` is now a fixed control message. The `type` field was removed, `getType()` always returns the constant `"CloseStream"`, and the `ListenV2CloseStreamType` enum (with its `CLOSE_STREAM` / `KEEP_ALIVE` / `FINALIZE` values) was deleted. The builder no longer has a `.type(...)` stage. + +**v0.5.0** + +```java +import com.deepgram.resources.listen.v2.types.ListenV2CloseStream; +import com.deepgram.resources.listen.v2.types.ListenV2CloseStreamType; + +wsClient.sendCloseStream(ListenV2CloseStream.builder() + .type(ListenV2CloseStreamType.CLOSE_STREAM) + .build()); +``` + +**v0.6.0** + +```java +import com.deepgram.resources.listen.v2.types.ListenV2CloseStream; + +wsClient.sendCloseStream(ListenV2CloseStream.builder().build()); +``` + +Remove any imports of `ListenV2CloseStreamType` and any `.type(...)` calls on the close-stream builder. If you read the discriminator, `getType()` still works and returns `"CloseStream"` as a `String`. + +### Listen Provider V2 Language Hints + +`DeepgramListenProviderV2` renamed its single-value `language_hint` to a multi-value `language_hints` list, and the `DeepgramListenProviderV2LanguageHint` enum was deleted. + +| v0.5.0 | v0.6.0 | +|---|---| +| `getLanguageHint() : Optional` | `getLanguageHints() : Optional>` | +| `builder().languageHint(...)` | `builder().languageHints(List.of(...))` | +| `DeepgramListenProviderV2LanguageHint` enum | removed — use plain `String` values | + +**v0.5.0** + +```java +import com.deepgram.types.DeepgramListenProviderV2; +import com.deepgram.types.DeepgramListenProviderV2LanguageHint; + +DeepgramListenProviderV2 provider = DeepgramListenProviderV2.builder() + .languageHint(DeepgramListenProviderV2LanguageHint.valueOf("en")) + .build(); +``` + +**v0.6.0** + +```java +import com.deepgram.types.DeepgramListenProviderV2; +import java.util.List; + +DeepgramListenProviderV2 provider = DeepgramListenProviderV2.builder() + .languageHints(List.of("en", "es")) + .build(); +``` + +Note: this is the `DeepgramListenProviderV2` type only. The unrelated `V2ConnectOptions.languageHint(...)` / `ListenV2LanguageHint` on the WebSocket query-param path is unchanged. + +### Flux Word Timestamps + +`ListenV2TurnInfoWordsItem` gains Flux word-level `start` and `end` timestamps (in seconds). They are modeled as `Optional`, so the getter return types changed from `double` to `Optional`. Existing call sites that read these fields must adapt. + +**v0.5.0** + +```java +double start = word.getStart(); +double end = word.getEnd(); +``` + +**v0.6.0** + +```java +import java.util.Optional; + +Optional start = word.getStart(); +Optional end = word.getEnd(); + +// e.g. with a default when absent: +double startSeconds = word.getStart().orElse(0.0); +``` + +On the builder, `start`/`end` accept either a `Double` or an `Optional` and default to empty when omitted. + +### Other Additive Types + +`0.6.0` also adds new generated types and fields that do not require migration unless you want to use them: + +- `DiarizeModel` (`v1` / `latest`) and a `diarizeModel` option on streaming requests (`diarize` is now deprecated) +- `ListenV2ProfanityFilter` and the `profanity_filter` V2 WebSocket query parameter (`V2ConnectOptions.profanityFilter(...)`) +- `DateTimeDeserializer` now also accepts space-separated timestamps (e.g. `"2025-02-15 10:30:00+00:00"`) + +## Breaking Changes Summary + +### Major Changes + +1. **Close stream narrowing**: `ListenV2CloseStream.builder().type(...)` removed; build with `ListenV2CloseStream.builder().build()`. `ListenV2CloseStreamType` deleted. +2. **Language hints rename**: `DeepgramListenProviderV2.getLanguageHint()` → `getLanguageHints()` (`Optional>`); `languageHint(...)` builder stage → `languageHints(...)`. `DeepgramListenProviderV2LanguageHint` deleted. +3. **Flux word timestamps**: `ListenV2TurnInfoWordsItem.getStart()` / `getEnd()` return type `double` → `Optional`. + +### Removed or Renamed Features + +- `ListenV2CloseStreamType` (and its `type` field on `ListenV2CloseStream`) +- `DeepgramListenProviderV2LanguageHint` +- `DeepgramListenProviderV2.getLanguageHint()` / `languageHint(...)` + +### New Features in v0.6.0 + +- **Flux word timestamps**: `ListenV2TurnInfoWordsItem` `start` / `end` +- **Diarize model selection**: `DiarizeModel` and `diarizeModel` on streaming requests +- **Profanity filter**: `ListenV2ProfanityFilter` and the `profanity_filter` V2 WebSocket query parameter +- **Multi-value language hints**: `DeepgramListenProviderV2.languageHints(List)` + +### Migration Checklist + +- [ ] Upgrade to `com.deepgram:deepgram-java-sdk:0.6.0` +- [ ] Replace `ListenV2CloseStream.builder().type(...)` with `ListenV2CloseStream.builder().build()` and remove `ListenV2CloseStreamType` imports +- [ ] Replace `DeepgramListenProviderV2.languageHint(...)` with `languageHints(List.of(...))` and remove `DeepgramListenProviderV2LanguageHint` imports +- [ ] Update reads of `ListenV2TurnInfoWordsItem.getStart()` / `getEnd()` to handle `Optional` +- [ ] Rebuild your project and fix any remaining imports referencing removed or renamed generated types