Skip to content

Commit 24f5796

Browse files
hive-botclaude
andcommitted
fix: read absent usage report totals and speech-to-speech minutes as null
AdminUsageReport.getTotalUsage() is now null when the report has no total_usage object, instead of a breakdown of zeros, and AdminUsageBreakdown.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>
1 parent 503d52a commit 24f5796

6 files changed

Lines changed: 77 additions & 22 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -148,8 +148,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
148148
The analytics functions take `LocalDate`, `"YYYY-MM-DD"` strings, or `Date`
149149
and `Instant` values, of which the UTC day is sent; both the start and the
150150
end day are included. Report dates are `Date` values at midnight UTC.
151-
`DeveloperKey.getLabel()`, `DeveloperKey.getUsageLimits()` and
152-
`KeyUsage.getApiKeyLabel()` return `null` when the API sends no value.
151+
`DeveloperKey.getLabel()`, `DeveloperKey.getUsageLimits()`,
152+
`KeyUsage.getApiKeyLabel()`, `AdminUsageReport.getTotalUsage()` and
153+
`AdminUsageBreakdown.getSpeechToSpeechMinutes()` (a `Double`) return `null`
154+
when the API sends no value.
153155
`setDeveloperKeyUsageLimits()` takes a `DeveloperKeyUsageLimitsUpdate` and
154156
changes only the limits set in it, including the speech-to-speech limit.
155157
- Added the API Pro fields of `GET /v2/usage` to `Usage`:

‎README.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1767,6 +1767,8 @@ empty if the report uses a different grouping. `KeyUsage.getApiKeyLabel()` is
17671767
`getGroupBy()` returns the grouping as the API sends it, for example `"key"` or
17681768
`"keyAndDay"`. Each usage breakdown has the characters used in total and per
17691769
product, `getSpeechToTextMinutes()` and `getSpeechToSpeechMinutes()`.
1770+
`getTotalUsage()` and `getSpeechToSpeechMinutes()` (a `Double`) are `null` if
1771+
the report does not include them.
17701772

17711773
```java
17721774
import com.deepl.api.*;
@@ -1777,8 +1779,10 @@ class AdminExample { // Continuing class AdminExample from above
17771779
AdminUsageReport report = adminClient.getUsageAnalytics(
17781780
LocalDate.of(2026, 6, 1), LocalDate.of(2026, 7, 1),
17791781
AdminUsageGroupBy.Key);
1780-
System.out.printf("Total characters: %d%n",
1781-
report.getTotalUsage().getTotalCharacters());
1782+
if (report.getTotalUsage() != null) {
1783+
System.out.printf("Total characters: %d%n",
1784+
report.getTotalUsage().getTotalCharacters());
1785+
}
17821786
for (KeyUsage keyUsage : report.getKeyUsages()) {
17831787
System.out.printf("%s: %d%n",
17841788
keyUsage.getApiKeyLabel(),

‎deepl-java/src/main/java/com/deepl/api/AdminUsageBreakdown.java‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
package com.deepl.api;
55

66
import com.google.gson.annotations.*;
7+
import org.jetbrains.annotations.*;
78

89
/** Usage totals in a usage analytics report, see {@link AdminUsageReport}. */
910
public class AdminUsageBreakdown {
@@ -23,7 +24,7 @@ public class AdminUsageBreakdown {
2324
private final double speechToTextMinutes;
2425

2526
@SerializedName(value = "speech_to_speech_minutes")
26-
private final double speechToSpeechMinutes;
27+
private final @Nullable Double speechToSpeechMinutes;
2728

2829
/**
2930
* Initializes a new {@link AdminUsageBreakdown}.
@@ -33,15 +34,16 @@ public class AdminUsageBreakdown {
3334
* @param documentTranslationCharacters Number of characters used for document translation.
3435
* @param textImprovementCharacters Number of characters used for text improvement.
3536
* @param speechToTextMinutes Number of speech-to-text minutes used.
36-
* @param speechToSpeechMinutes Number of speech-to-speech minutes used.
37+
* @param speechToSpeechMinutes Number of speech-to-speech minutes used, or <code>null</code> if
38+
* the report does not include it.
3739
*/
3840
public AdminUsageBreakdown(
3941
long totalCharacters,
4042
long textTranslationCharacters,
4143
long documentTranslationCharacters,
4244
long textImprovementCharacters,
4345
double speechToTextMinutes,
44-
double speechToSpeechMinutes) {
46+
@Nullable Double speechToSpeechMinutes) {
4547
this.totalCharacters = totalCharacters;
4648
this.textTranslationCharacters = textTranslationCharacters;
4749
this.documentTranslationCharacters = documentTranslationCharacters;
@@ -75,8 +77,11 @@ public double getSpeechToTextMinutes() {
7577
return speechToTextMinutes;
7678
}
7779

78-
/** @return Number of speech-to-speech minutes used. */
79-
public double getSpeechToSpeechMinutes() {
80+
/**
81+
* @return Number of speech-to-speech minutes used, or <code>null</code> if the report does not
82+
* include it.
83+
*/
84+
public @Nullable Double getSpeechToSpeechMinutes() {
8085
return speechToSpeechMinutes;
8186
}
8287
}

‎deepl-java/src/main/java/com/deepl/api/AdminUsageReport.java‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
/** Usage analytics report for a date range, see {@link DeepLAdminClient#getUsageAnalytics}. */
1111
public class AdminUsageReport {
1212
@SerializedName(value = "total_usage")
13-
private final AdminUsageBreakdown totalUsage;
13+
private final @Nullable AdminUsageBreakdown totalUsage;
1414

1515
@SerializedName(value = "start_date")
1616
private final @Nullable Date startDate;
@@ -30,15 +30,16 @@ public class AdminUsageReport {
3030
/**
3131
* Initializes a new {@link AdminUsageReport}.
3232
*
33-
* @param totalUsage Usage totals over the whole date range.
33+
* @param totalUsage Usage totals over the whole date range, or <code>null</code> if the report
34+
* does not include them.
3435
* @param startDate Start day of the report period, as midnight UTC.
3536
* @param endDate End day of the report period, as midnight UTC.
3637
* @param groupBy Grouping used for the report, if any.
3738
* @param keyUsages Usage per key, present when grouped by key.
3839
* @param keyAndDayUsages Usage per key and day, present when grouped by key and day.
3940
*/
4041
public AdminUsageReport(
41-
AdminUsageBreakdown totalUsage,
42+
@Nullable AdminUsageBreakdown totalUsage,
4243
@Nullable Date startDate,
4344
@Nullable Date endDate,
4445
@Nullable String groupBy,
@@ -52,8 +53,11 @@ public AdminUsageReport(
5253
this.keyAndDayUsages = keyAndDayUsages;
5354
}
5455

55-
/** @return Usage totals over the whole date range. */
56-
public AdminUsageBreakdown getTotalUsage() {
56+
/**
57+
* @return Usage totals over the whole date range, or <code>null</code> if the report does not
58+
* include them.
59+
*/
60+
public @Nullable AdminUsageBreakdown getTotalUsage() {
5761
return totalUsage;
5862
}
5963

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

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@
1212

1313
/**
1414
* Parses Admin API responses tolerantly: entries that are not objects or have no key_id are
15-
* skipped, missing optional fields (labels, usage limits, dates) are null, and other missing or
16-
* malformed fields get neutral defaults. A response of the wrong overall shape, or a single key
17-
* without key_id, is an error.
15+
* skipped, missing optional fields (labels, usage limits, dates, a report's total usage and
16+
* speech-to-speech minutes) are null, and other missing or malformed fields get neutral defaults. A
17+
* response of the wrong overall shape, or a single key without key_id, is an error.
1818
*
1919
* <p>This class is internal; you should not use this class directly.
2020
*/
@@ -84,7 +84,7 @@ private static JsonObject requireObject(@Nullable JsonElement json, String what)
8484
AdminUsageReport parseUsageReport(JsonElement json) {
8585
JsonObject report = asObject(requireObject(json, "Usage report").get("usage_report"));
8686
return new AdminUsageReport(
87-
parseBreakdown(report.get("total_usage")),
87+
breakdownOrNull(report.get("total_usage")),
8888
utcDay(report, "start_date"),
8989
utcDay(report, "end_date"),
9090
stringOrNull(report, "group_by"),
@@ -135,7 +135,11 @@ private AdminUsageBreakdown parseBreakdown(@Nullable JsonElement json) {
135135
count(object, "document_translation_characters"),
136136
count(object, "text_improvement_characters"),
137137
number(object, "speech_to_text_minutes"),
138-
number(object, "speech_to_speech_minutes"));
138+
numberOrNull(object, "speech_to_speech_minutes"));
139+
}
140+
141+
private @Nullable AdminUsageBreakdown breakdownOrNull(@Nullable JsonElement json) {
142+
return json != null && json.isJsonObject() ? parseBreakdown(json) : null;
139143
}
140144

141145
private CustomTagUsageBreakdown parseCustomTagBreakdown(@Nullable JsonElement json) {
@@ -199,11 +203,16 @@ private static long count(JsonObject object, String name) {
199203
}
200204

201205
private static double number(JsonObject object, String name) {
206+
Double value = numberOrNull(object, name);
207+
return value != null ? value : 0;
208+
}
209+
210+
private static @Nullable Double numberOrNull(JsonObject object, String name) {
202211
JsonElement element = object.get(name);
203212
try {
204-
return element == null || element.isJsonNull() ? 0 : element.getAsDouble();
213+
return element == null || element.isJsonNull() ? null : element.getAsDouble();
205214
} catch (RuntimeException e) {
206-
return 0;
215+
return null;
207216
}
208217
}
209218

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

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,6 @@ void parsesMalformedValuesTolerantly() throws Exception {
121121
assertEquals(0, report.getTotalUsage().getTotalCharacters());
122122
assertEquals(0, report.getTotalUsage().getSpeechToTextMinutes());
123123
assertEquals(2.5, report.getTotalUsage().getSpeechToSpeechMinutes());
124-
assertEquals(0, report.getKeyUsages().get(1).getUsage().getSpeechToSpeechMinutes());
125124
assertNull(report.getStartDate());
126125
assertEquals(utcMidnight("2025-10-01"), report.getEndDate());
127126
assertEquals(2, report.getKeyUsages().size());
@@ -134,6 +133,38 @@ void parsesMalformedValuesTolerantly() throws Exception {
134133
assertEquals(4, tagReport.getUsage().get(0).getBreakdown().getTotalCharacters());
135134
}
136135

136+
@Test
137+
void readsAbsentSpeechToSpeechMinutesAsNull() throws Exception {
138+
wm.stubFor(
139+
get("/v2/admin/analytics?start_date=2025-09-29&end_date=2025-10-01&group_by=key")
140+
.willReturn(
141+
okJson(
142+
"{\"usage_report\":{\"total_usage\":{\"total_characters\":9,"
143+
+ "\"speech_to_speech_minutes\":0},"
144+
+ "\"key_usages\":[{\"api_key\":\"a\",\"usage\":{\"total_characters\":9}}]}}")));
145+
146+
AdminUsageReport report =
147+
client.getUsageAnalytics(
148+
LocalDate.of(2025, 9, 29), LocalDate.of(2025, 10, 1), AdminUsageGroupBy.Key);
149+
assertEquals(0.0, report.getTotalUsage().getSpeechToSpeechMinutes());
150+
assertNull(report.getKeyUsages().get(0).getUsage().getSpeechToSpeechMinutes());
151+
}
152+
153+
@Test
154+
void readsAbsentTotalUsageAsNull() throws Exception {
155+
wm.stubFor(
156+
get("/v2/admin/analytics?start_date=2025-09-29&end_date=2025-10-01")
157+
.willReturn(okJson("{\"usage_report\":{\"start_date\":\"2025-09-29T00:00:00\"}}")));
158+
wm.stubFor(
159+
get("/v2/admin/analytics?start_date=2025-09-29&end_date=2025-10-01&group_by=key")
160+
.willReturn(okJson("{\"usage_report\":{\"total_usage\":\"x\"}}")));
161+
162+
LocalDate start = LocalDate.of(2025, 9, 29);
163+
LocalDate end = LocalDate.of(2025, 10, 1);
164+
assertNull(client.getUsageAnalytics(start, end).getTotalUsage());
165+
assertNull(client.getUsageAnalytics(start, end, AdminUsageGroupBy.Key).getTotalUsage());
166+
}
167+
137168
@Test
138169
void throwsDeepLExceptionIfAKeyResponseHasNoKeyId() {
139170
wm.stubFor(post("/v2/admin/developer-keys").willReturn(okJson("{\"label\":\"l\"}")));

0 commit comments

Comments
 (0)