feat(regen)!: speak v2 interrupt/configure, listen v2 redact; retype provider + google version

[GregHolmes]

Regenerates the SDK against the latest Fern generator (4.10.1 → 4.16.0) and API spec (ff8fd2b → 03f0677), reconciles the hand-maintained patches, and documents the resulting breaking changes with a migration guide. Supersedes the reverted #89.

Base

Stacked on the revert branch (#91). Until that merges, this PR's diff includes the revert commit; merge #91 first (or it rides along).

⛔ Blocked / do not merge yet

Regenerated from an unmerged spec branch: .fern/metadata.json originGitCommit 03f0677 lives only on origin/jherlihy/flux-tts-ga, not on deepgram-docs main. The launch surface here (breaks_applied, ConfigureFailure, expressivity, speed, redact) exists only on that branch. Kept as a draft until it lands.

• Blocked-on: deepgram-docs#1094 (Flux TTS copy) + the jherlihy/flux-tts-ga spec branch merging to deepgram-docs main.

Breaking changes (pre-1.0, source/compile-time only)

All three follow the API definition; on-the-wire payloads for existing requests are unchanged. Full before/after in docs/Migrating-v0.7-to-v0.8.md.

1. AgentV1UpdateListenListen.provider retyped DeepgramListenProviderV2 → AgentV1UpdateListenListenProvider (V1/V2 union). Wrap with AgentV1UpdateListenListenProvider.v2(...); read via getV2().
2. Google.version retyped Optional<String> → Optional<GoogleThinkProviderVersion>. Use the enum constants (V1BETA, AI_STUDIO_V1BETA, GEMINI_ENTERPRISE_AGENT_V1).
3. SpeakV2SpeechMetadataControlsApplied gains a required breaksApplied field (new builder step; new getBreaksApplied()). Read paths unaffected.

Origin verified: #2 and #3 are new in the latest spec; #1's union shape existed in #89 but was previously hidden behind an in-SDK shim we intentionally did not carry forward.

Reconciliation (post-regen review)

Diffed each of the 17 .bak patches against the freshly generated originals — all 17 still needed, none dropped. .fernignore restored to its pre-prep state; all .bak files deleted.

• 13 restored verbatim (generator produced no other changes): the 11 fields-less hashCode() types, ReconnectingWebSocketListener (override hook / connectionTimeoutMs / maxRetries(0) semantics), and the listen/v1 + speak/v1 websocket clients (query-param repeats + additionalProperties).
• 2 surgically merged (listen/v2 + speak/v2 websocket clients): re-applied QueryStringMapper array-param serialization, the additionalProperties escape hatch, and the forward-compat unknown-message no-op, while keeping the generator's new features (speak/v2 sendInterrupt/sendConfigure + onSpeechInterrupted/onConfigureSuccess/onConfigureFailure; listen/v2 redact).
• ClientOptions: kept the new retry-tuning options + ResponseDecompressionInterceptor; re-applied only the two // x-release-please-version header lines (colon SDK-name form), removed the generator's getSdkVersion() helper (build does not stamp the JAR manifest, so it would drift).

Additive highlights

Speak V2 interrupt/configure, Listen V2 redact, Speak V2 speed/expressivity, new Deepgram Flux TTS voices, client retry tuning, automatic response decompression.

Tests added

• ListenV2ConnectWireTest: new redact connect param (present as wire numbers, omitted when absent).
• RegenTypesTest → "2026-08-11 regen type shapes": the three breaking shapes (provider union v2 factory/getV2/serialization, Google.version enum wire value, ListenV2Redact wire values).

Verification

• ./gradlew unitTest ✅ · spotlessCheck ✅ · compileExamples ✅
• ./gradlew integrationTest ✅ (Tier 1 + Tier 2 against a live key); opt-in Speak V2 WS integration ✅ (returned audio over the new v2 WS path)
• Ran all non-manage examples: 19 pass, 7 long-running streaming/agent examples connected and worked, 4 environmental (proxy / file-arg / callback URL / SageMaker) — no SDK regressions.

Post-review additions (from #91 review)

• Re-applied the union default-variant fix the feat(regen): add diarize_info, Flux force-end-turn, update-listen, word speaker confidence #89 revert forfeited (issue Forfeited by #89 revert: union defaultImpl fix + UpdateListen return-type shim + 2 regression tests #93): defaultImpl = V2Value on AgentV1UpdateListenListenProvider, AgentV1SettingsAgentListenProvider, AgentV1SettingsAgentContextListenProvider, so a provider payload omitting the optional version discriminator (what 0.7.x emits) deserializes as V2 instead of dropping to {"provider":null}. Frozen in .fernignore + AGENTS.md, guarded by the re-added AgentSettingsProviderDefaultTest. The getProvider() return-type shim is intentionally not re-applied — that retype is a deliberate breaking change (see the migration guide).

Core behavior changes (generator 4.10.1 → 4.16.0)

Beyond the spec features, the generator upgrade changes core HTTP-client behavior worth calling out in the release notes:

• Automatic response decompression is now installed by default (ResponseDecompressionInterceptor): gzip/deflate-encoded HTTP responses are transparently decoded. No API change; transparent to callers.
• New optional retry tuning on ClientOptions.Builder: initialRetryDelayMillis, maxRetryDelayMillis, retryJitterFactor. All defaulted — existing behavior is unchanged unless set.

Follow-ups

• Once this lands, release-please cuts a fresh release at 0.8.0 (breaking feat!).
• Changelog needs a manual edit before releasing. 5b6323a (feat(regen): add diarize_info, Flux force-end-turn, update-listen, word speaker confidence #89 feat(regen)) is still in release-please's range since v0.7.1, and release-please can't pair a revert with the commit it reverts — so the generated 0.8.0 notes will re-list the reverted feat(regen): add diarize_info, Flux force-end-turn, update-listen, word speaker confidence #89 features (diarize_info, force-end-turn) under Features. Hand-edit the release PR's CHANGELOG.md to drop them before merging it.

BREAKING CHANGE: AgentV1UpdateListenListen.provider is now AgentV1UpdateListenListenProvider (V1/V2 union); Google.version is now Optional<GoogleThinkProviderVersion>; SpeakV2SpeechMetadataControlsApplied has a new required breaksApplied field. See docs/Migrating-v0.7-to-v0.8.md.

[dg-coreylweathers]

Content approved — holding merge until the spec branch lands. Three fixes are needed first, and none of them depend on the gate.

The regen itself is clean, and I verified it mechanically rather than from the body: removed public members vs released 0.7.1 come to exactly three, and they are exactly the three declared. Zero deleted types, zero renames, zero narrowed enums. All 17 hand patches survive, the additionalProperties escape hatch reaches the wire on all four WS clients, and compileJava compileExamples unitTest spotlessCheck is BUILD SUCCESSFUL locally in Docker. The apparent deletions against main — diarize types, ListenV2TurnInfo.trigger, channel-word speaker_confidence — are all unreleased #89 additions, so non-breaking against the released baseline.

The new barge-in README section and example are the strongest developer-facing work here. Every API call checks out against the tree (including the easy-to-get-wrong bit: getTextSpoken()/getTextRemaining() are on the event, not nested in metadata), and every behavioral claim traces to spec.

Blocking

[B1] Merge gate — regenerated from an unmerged spec branch. originGitCommit 03f0677 is not on deepgram-docs main; git branch -r --contains returns only origin/jherlihy/flux-tts-ga. breaks_applied — declared breaking change #3 — has 0 occurrences on merged main and 2 on the branch, as do ConfigureFailure and expressivity. Maven releases are immutable, and this PR declares a 0.8.0 release plan. Python #758 and JS #532 both name the branch in their first sentence and are both drafts. Please mark this draft, name the branch in the body, and add a Blocked-on line for the branch's docs PR and deepgram-docs#1094.

[B3] Migration guide's retry-tuning snippet doesn't produce a DeepgramClient. docs/Migrating-v0.7-to-v0.8.md:57-64. Compiled it: error: incompatible types: DeepgramApiClient cannot be converted to DeepgramClient. The three knobs live only on the base DeepgramApiClientBuilder; DeepgramClientBuilder narrows ten inherited setters but not these three, so the chain degrades and build() returns the wrong client. As printed (no assignment) it compiles and silently builds a DeepgramApiClient. Fix by restoring the three covariant overrides on both DeepgramClientBuilder and AsyncDeepgramClientBuilder — verified that makes the snippet compile unchanged:

    @Override
    public DeepgramClientBuilder initialRetryDelayMillis(long initialRetryDelayMillis) {
        super.initialRetryDelayMillis(initialRetryDelayMillis);
        return this;
    }

    @Override
    public DeepgramClientBuilder maxRetryDelayMillis(long maxRetryDelayMillis) {
        super.maxRetryDelayMillis(maxRetryDelayMillis);
        return this;
    }

    @Override
    public DeepgramClientBuilder retryJitterFactor(double retryJitterFactor) {
        super.retryJitterFactor(retryJitterFactor);
        return this;
    }

[B4] Both Google snippets omit the required model() stage. docs/Migrating-v0.7-to-v0.8.md:138-141,151-155. Google.builder() returns ModelStage; version(...) is on _FinalStage. Compiled: cannot find symbol: method version(GoogleThinkProviderVersion), location: interface ModelStage. True of the "before" snippet too — builder() returned ModelStage in 0.7.1 as well. Insert .model(GoogleThinkProviderModel.GEMINI25FLASH) in both (constants are GEMINI25FLASH / GEMINI20FLASH / GEMINI20FLASH_LITE, not GEMINI_2_5_FLASH). Same applies to the provider-union snippets at :102/:119, where DeepgramListenProviderV2.builder() also needs .model("flux-general-en").

[B5] 71cbe4e and 2cfc3d5 hand-edit generated files that aren't frozen. src/main/java/com/deepgram/types/Deepgram.java and src/main/java/com/deepgram/resources/speak/v2/audio/requests/SpeakV2Request.java — twelve javadoc edits, and neither path is in .fernignore or AGENTS.md, so the next regen reverts all twelve silently with no test to catch it. Deepgram.java used to be frozen; this PR's own .fernignore diff removes the type-rename block that listed it. Since both edits pre-apply copy from the unmerged deepgram-docs#1094 — and the strings come from spec description fields — the cleanest fix is to drop both commits and let the copy arrive by regeneration once #1094 merges. If it has to ship now, freeze both paths properly with a matching AGENTS.md entry and an unfreeze condition.

[B6] The 0.8.0 changelog will advertise the reverted #89 features. 5b6323a ("feat(regen): add diarize_info, Flux force-end-turn, update-listen, word speaker confidence") is still in release-please's range since the v0.7.1 tag, and release-please can't pair a revert with the commit it reverts. So 0.8.0's notes will list diarize_info and force-end-turn under Features — re-asserting in the release notes exactly what c55725f correctly removed from the migration guide. Needs a human edit of the generated release PR's changelog before merging it; worth adding as an explicit Follow-ups step.

Should-fix

[S1] pom.xml:169 — dropping addDefaultImplementationEntries strips Implementation-Title/Implementation-Version from the published jar. The Gradle half of the revert is right (nothing reads getSdkVersion() any more), but the Maven half only removes artifact metadata and can't cause the drift it guards against. Suggest restoring just the pom.xml hunk.

[S2] No wire test for speed, expressivity, sendInterrupt, or sendConfigure — the four symbols sourced from the unmerged branch, so the highest-churn surface here. SpeakV2ConnectWireTest has only the two tag cases. Mirror the two redact cases you added on the listen side, and add a send-frame test including an Interrupt with a playback_offset.

[S3] examples/speak/StreamingTtsV2.java:41,162 — BYTES_PER_SECOND = 32000 is correct only for the LINEAR16 @ 16 kHz set 100 lines away, and the comment above that builder invites changing it. The offset is load-bearing server-side (it drives the text_spoken/text_remaining split and must advance monotonically), so derive it from a shared sample-rate constant.

Nits

• .fern/metadata.json:18 — sdkVersion is 0.7.2 while all five other markers and the latest release say 0.7.1.
• .fern/metadata.json:2 — cliVersion goes backwards 5.89.0 → 5.44.6 while the body says "latest Fern generator". Accurate for generatorVersion, but worth naming the CLI pin so the next reviewer doesn't chase it as I did.
• .fern/metadata.json:13 — runtime-version: true remains after getSdkVersion() was stripped, so every regen re-emits a helper someone must remove by hand.
• examples/speak/StreamingTtsV2.java:147-160 — the barge-in rewrite dropped the multi-chunk send loop, but the class javadoc still says "Sends text chunks". Splitting the long utterance across two or three sendSpeak calls restores it and keeps the barge-in demo intact.

Worth noting

The README is clean across two review passes because ReadmeSnippetsCompileTest extracts and compiles every ```java fence at test time. docs/*.md has no equivalent gate, and B3/B4 have now survived two passes as a direct result. Pointing the same machinery at `docs/Migrating-*.md` would have caught both and will catch the next guide's — I built that harness to find these, so it's a small change.

[dg-coreylweathers]

Content approved — hold merge until the spec branch lands.

Re-reviewed at cc219b9. The two items actioned this round are correct, and I verified both are verbatim the branch-tip spec text rather than paraphrases:

• B8 — speed error codes now scoped to the WebSocket path; the REST javadoc matches the tip's openapi wording exactly, across all four occurrences.
• B5 premise — spot-checked every hand-applied javadoc string against deepgram-docs@4170ce5: 9 of 11 prose blocks are verbatim matches. SpeakV2Warning was synced to the branch tip, not to #1094. Freeze question settled on that basis.

f354ef6 went further than asked, propagating the "not applied at launch / always 0" reality into seven generated types including the reserved-warning-codes paragraph. That's the honest launch surface and the strongest work in this pass.

Build gate: compileJava compileExamples unitTest spotlessCheck BUILD SUCCESSFUL locally in Docker.

Before merge (not blocking this approval):

1. Blocked-on line needs both gates. deepgram-docs#1090 and #1096 — the latter carries the agent speak-provider copy and the full 39-voice enum, per ca6c569.
2. Paste the drift note into this body under ## Known follow-up. It is currently in none of the three SDK PR bodies, and it is the entire basis of the document-the-drift approach. Per-repo cost, verified against each recorded sdkVersion: java 0.9.0 absorbs it; python needs 8.0.0, js needs 6.0.0.
3. Revert b647486. ca6c569 deliberately reverted speak-providers/deepgram.yml to main, so the tip still marks Flux TTS "Early Access" in four places. As it stands the SDK javadoc asserts GA against its own spec, and the next regen silently reverts the edit anyway.
4. Expressivity needs the spec's Beta sentence on SpeakV2Request (:146, :322, :484, :494) — hallucination risk and the EXPRESSIVITY_* 400 codes, both confirmed against the live API.
5. 0.8.0 changelog still needs a hand-edit at release time: 5b6323a is in release-please's range since v0.7.1, so the generated notes will re-list the reverted #89 features.

Full detail in the review notes.