fix: read absent custom tag speech-to-speech minutes as null

CustomTagUsageBreakdown.getSpeechToSpeechMinutes() is now a nullable
Double that is null when speech_to_speech_minutes is absent, instead
of 0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: hive-bot

CHANGELOG.md

@@ -150,8 +150,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   end day are included. Report dates are `Date` values at midnight UTC.
   `DeveloperKey.getLabel()`, `DeveloperKey.getUsageLimits()`,
   `KeyUsage.getApiKeyLabel()`, `AdminUsageReport.getTotalUsage()` and
-  `AdminUsageBreakdown.getSpeechToSpeechMinutes()` (a `Double`) return `null`
-  when the API sends no value.
+  `AdminUsageBreakdown.getSpeechToSpeechMinutes()` and
+  `CustomTagUsageBreakdown.getSpeechToSpeechMinutes()` (both a `Double`) return
+  `null` when the API sends no value.
   `setDeveloperKeyUsageLimits()` takes a `DeveloperKeyUsageLimitsUpdate` and
   changes only the limits set in it, including the speech-to-speech limit.
 - Added the API Pro fields of `GET /v2/usage` to `Usage`:

README.md

@@ -1798,6 +1798,8 @@ chooses between the whole period (`CustomTagUsageAggregateBy.Period`, the
 default) and per-day usage (`CustomTagUsageAggregateBy.Day`); a string is sent
 as given. The results are paginated: pass the `getNextPage()` value of a report
 as the `page` argument to get the next page.
+`CustomTagUsageBreakdown.getSpeechToSpeechMinutes()` (a `Double`) is `null` if
+the report does not include it.
 
 ```java
 import com.deepl.api.*;

deepl-java/src/main/java/com/deepl/api/CustomTagUsageBreakdown.java

@@ -4,6 +4,7 @@
 package com.deepl.api;
 
 import com.google.gson.annotations.*;
+import org.jetbrains.annotations.*;
 
 /** Usage totals for a custom tag, see {@link CustomTagUsage}. */
 public class CustomTagUsageBreakdown {
@@ -20,7 +21,7 @@ public class CustomTagUsageBreakdown {
   private final double speechToTextMinutes;
 
   @SerializedName(value = "speech_to_speech_minutes")
-  private final double speechToSpeechMinutes;
+  private final @Nullable Double speechToSpeechMinutes;
 
   /**
    * Initializes a new {@link CustomTagUsageBreakdown}.
@@ -29,14 +30,15 @@ public class CustomTagUsageBreakdown {
    * @param textTranslationCharacters Number of characters used for text translation.
    * @param textImprovementCharacters Number of characters used for text improvement.
    * @param speechToTextMinutes Number of speech-to-text minutes used.
-   * @param speechToSpeechMinutes Number of speech-to-speech minutes used.
+   * @param speechToSpeechMinutes Number of speech-to-speech minutes used, or <code>null</code> if
+   *     the report does not include it.
    */
   public CustomTagUsageBreakdown(
       long totalCharacters,
       long textTranslationCharacters,
       long textImprovementCharacters,
       double speechToTextMinutes,
-      double speechToSpeechMinutes) {
+      @Nullable Double speechToSpeechMinutes) {
     this.totalCharacters = totalCharacters;
     this.textTranslationCharacters = textTranslationCharacters;
     this.textImprovementCharacters = textImprovementCharacters;
@@ -64,8 +66,11 @@ public double getSpeechToTextMinutes() {
     return speechToTextMinutes;
   }
 
-  /** @return Number of speech-to-speech minutes used. */
-  public double getSpeechToSpeechMinutes() {
+  /**
+   * @return Number of speech-to-speech minutes used, or <code>null</code> if the report does not
+   *     include it.
+   */
+  public @Nullable Double getSpeechToSpeechMinutes() {
     return speechToSpeechMinutes;
   }
 }

deepl-java/src/main/java/com/deepl/api/parsing/AdminResponseParser.java

@@ -149,7 +149,7 @@ private CustomTagUsageBreakdown parseCustomTagBreakdown(@Nullable JsonElement js
         count(object, "text_translation_characters"),
         count(object, "text_improvement_characters"),
         number(object, "speech_to_text_minutes"),
-        number(object, "speech_to_speech_minutes"));
+        numberOrNull(object, "speech_to_speech_minutes"));
   }
 
   private static JsonObject asObject(@Nullable JsonElement json) {

deepl-java/src/offlineTest/java/com/deepl/api/AdminClientTest.java

@@ -150,6 +150,24 @@ void readsAbsentSpeechToSpeechMinutesAsNull() throws Exception {
     assertNull(report.getKeyUsages().get(0).getUsage().getSpeechToSpeechMinutes());
   }
 
+  @Test
+  void readsAbsentCustomTagSpeechToSpeechMinutesAsNull() throws Exception {
+    wm.stubFor(
+        get("/v2/admin/analytics/custom-tags?start_date=2025-09-29&end_date=2025-10-01")
+            .willReturn(
+                okJson(
+                    "{\"custom_tag_usage_report\":{\"usage\":["
+                        + "{\"custom_tag\":\"a\",\"breakdown\":{\"speech_to_speech_minutes\":0}},"
+                        + "{\"custom_tag\":\"b\",\"breakdown\":{\"total_characters\":4}}]}}")));
+
+    List<CustomTagUsage> usage =
+        client
+            .getCustomTagUsageAnalytics(LocalDate.of(2025, 9, 29), LocalDate.of(2025, 10, 1))
+            .getUsage();
+    assertEquals(0.0, usage.get(0).getBreakdown().getSpeechToSpeechMinutes());
+    assertNull(usage.get(1).getBreakdown().getSpeechToSpeechMinutes());
+  }
+
   @Test
   void readsAbsentTotalUsageAsNull() throws Exception {
     wm.stubFor(