fix: read missing usage product fields as undefined

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

Author: hive-bot

CHANGELOG.md

@@ -86,7 +86,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added the API Pro fields of `GET /v2/usage` to `Usage`: `apiKeyCharacter`,
   `speechToTextMinutes` and `speechToSpeechMinutes` (`UsageDetail`), `products`
   (array of the new `UsageProduct` type), and `startTime` and `endTime`
-  (`Date`). They are `undefined` when the response does not contain them.
+  (`Date`). They are `undefined` when the response does not contain them, as
+  are the `UsageProduct` fields missing from a `products` entry.
   `anyLimitReached()` still checks only the character, document and team
   document usage.
 - Added the `DeepLAdminClient` class for the Admin API. It must be created with

README.md

@@ -1091,7 +1091,8 @@ For API Pro accounts, the `Usage` object also contains:
 - `products`: an array of per-product usage, each with `productType` (for
   example `'translate'`, `'write'`, `'speechToText'`), `billingUnit` (for
   example `'characters'`, `'minutes'`), `apiKeyUnitCount` (this API key) and
-  `accountUnitCount` (the whole account).
+  `accountUnitCount` (the whole account). Each of these four fields is
+  `undefined` when the API omits it.
 
 These fields are `undefined` when the response does not contain them, for
 example for API Free accounts. `anyLimitReached()` does not check

src/parsing.ts

@@ -584,15 +584,18 @@ function parseOptionalDate(value: unknown): Date | undefined {
 }
 
 /**
- * Parses the products array of the usage API response; missing or malformed values get defaults.
+ * Parses the products array of the usage API response; missing or malformed values are undefined.
  * @private
  */
 function parseUsageProducts(products: unknown): UsageProduct[] | undefined {
     if (!Array.isArray(products)) return undefined;
-    const str = (value: unknown) => (typeof value === 'string' ? value : '');
-    const num = (value: unknown) => (typeof value === 'number' ? value : 0);
+    const str = (value: unknown) => (typeof value === 'string' ? value : undefined);
+    const num = (value: unknown) => (typeof value === 'number' ? value : undefined);
     return products.map((product) => {
-        const p = (product ?? {}) as Record<string, unknown>;
+        const p = (typeof product === 'object' && product !== null ? product : {}) as Record<
+            string,
+            unknown
+        >;
         return {
             productType: str(p.product_type),
             billingUnit: str(p.billing_unit),

src/types.ts

@@ -645,14 +645,23 @@ export interface UsageDetail {
  * Usage of one product in the current billing period, part of the Usage object.
  */
 export interface UsageProduct {
-    /** The product, for example 'translate', 'write', 'speechToText' or 'speechToSpeech'. */
-    readonly productType: string;
-    /** The unit the product is billed in, for example 'characters' or 'minutes'. */
-    readonly billingUnit: string;
-    /** Units used for this product by this API key. */
-    readonly apiKeyUnitCount: number;
-    /** Units used for this product by the whole account. */
-    readonly accountUnitCount: number;
+    /**
+     * The product, for example 'translate', 'write', 'speechToText' or 'speechToSpeech';
+     * undefined if the response does not contain it.
+     */
+    readonly productType?: string;
+    /**
+     * The unit the product is billed in, for example 'characters' or 'minutes'; undefined if the
+     * response does not contain it.
+     */
+    readonly billingUnit?: string;
+    /** Units used for this product by this API key; undefined if the response does not contain it. */
+    readonly apiKeyUnitCount?: number;
+    /**
+     * Units used for this product by the whole account; undefined if the response does not
+     * contain it.
+     */
+    readonly accountUnitCount?: number;
 }
 
 /**

tests/offline/usage.test.ts

@@ -143,15 +143,26 @@ describe('Translator.getUsage', () => {
                 character_limit: 100,
                 start_time: 'not a timestamp',
                 end_time: 42,
-                products: [{ product_type: 'translate' }],
+                products: [{ product_type: 'translate', api_key_unit_count: '5' }, {}],
             });
 
         const usage = await makeTranslator().getUsage();
 
         expect(usage.character).toMatchObject({ count: 10, limit: 100 });
         expect([usage.startTime, usage.endTime]).toEqual([undefined, undefined]);
         expect(usage.products).toEqual([
-            { productType: 'translate', billingUnit: '', apiKeyUnitCount: 0, accountUnitCount: 0 },
+            {
+                productType: 'translate',
+                billingUnit: undefined,
+                apiKeyUnitCount: undefined,
+                accountUnitCount: undefined,
+            },
+            {
+                productType: undefined,
+                billingUnit: undefined,
+                apiKeyUnitCount: undefined,
+                accountUnitCount: undefined,
+            },
         ]);
     });
 });