feat: add missing fields in usage response

src/Usage.php

@@ -23,6 +23,11 @@ class Usage
      */
     public $character;
 
+    /**
+     * @var UsageDetail|null Usage details for characters used by this API key only.
+     */
+    public $apiKeyCharacter;
+
     /**
      * @var UsageDetail|null Usage details for documents.
      */
@@ -33,22 +38,67 @@ class Usage
      */
     public $teamDocument;
 
+    /**
+     * @var UsageDetail|null Usage details for speech-to-text, in minutes.
+     */
+    public $speechToTextMinutes;
+
+    /**
+     * @var UsageDetail|null Usage details for speech-to-text, in milliseconds.
+     */
+    public $speechToTextMilliseconds;
+
+    /**
+     * @var UsageDetail|null Usage details for speech-to-speech, in minutes.
+     */
+    public $speechToSpeechMinutes;
+
+    /**
+     * @var UsageProduct[] Usage broken down per product, empty if the account does not report it.
+     */
+    public $products;
+
+    /**
+     * @var string|null Start of the billing period, as an ISO 8601 timestamp.
+     */
+    public $startTime;
+
+    /**
+     * @var string|null End of the billing period, as an ISO 8601 timestamp.
+     */
+    public $endTime;
+
     /**
      * @return bool True if any usage type limit has been reached or passed, otherwise false.
      */
     public function anyLimitReached(): bool
     {
-        return ($this->character !== null && $this->character->limitReached()) ||
-            ($this->document !== null && $this->document->limitReached()) ||
-            ($this->teamDocument !== null && $this->teamDocument->limitReached());
+        $details = [
+            $this->apiKeyCharacter,
+            $this->character,
+            $this->document,
+            $this->teamDocument,
+            $this->speechToTextMinutes,
+            $this->speechToSpeechMinutes,
+        ];
+        /** @var UsageDetail|null $detail */
+        foreach ($details as $detail) {
+            if ($detail !== null && $detail->limitReached()) {
+                return true;
+            }
+        }
+        return false;
     }
 
     public function __toString(): string
     {
         $list = [
+            'API key characters' => $this->apiKeyCharacter,
             'Characters' => $this->character,
             'Documents' => $this->document,
             'Team documents' => $this->teamDocument,
+            'Speech-to-text minutes' => $this->speechToTextMinutes,
+            'Speech-to-speech minutes' => $this->speechToSpeechMinutes,
         ];
         $result = 'Usage this billing period:';
         foreach ($list as $label => $detail) {
@@ -71,8 +121,20 @@ public function __construct(string $content)
         }
 
         $this->character = $this->buildUsageDetail('character', $json);
+        $this->apiKeyCharacter = $this->buildUsageDetail('api_key_character', $json);
         $this->document = $this->buildUsageDetail('document', $json);
         $this->teamDocument = $this->buildUsageDetail('team_document', $json);
+        $this->speechToTextMinutes = $this->buildUsageDetail('speech_to_text_minutes', $json);
+        $this->speechToTextMilliseconds = $this->buildUsageDetail('speech_to_text_milliseconds', $json);
+        $this->speechToSpeechMinutes = $this->buildUsageDetail('speech_to_speech_minutes', $json);
+        $this->products = array_map(
+            function (array $product): UsageProduct {
+                return new UsageProduct($product);
+            },
+            $json['products'] ?? []
+        );
+        $this->startTime = $json['start_time'] ?? null;
+        $this->endTime = $json['end_time'] ?? null;
     }
 
     private function buildUsageDetail(string $prefix, array $json): ?UsageDetail

src/UsageProduct.php

@@ -0,0 +1,53 @@
+<?php
+
+// Copyright 2022 DeepL SE (https://www.deepl.com)
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+
+namespace DeepL;
+
+/**
+ * Usage for one product, as reported in the products field of the usage response.
+ */
+class UsageProduct
+{
+    /**
+     * @var string The product this usage refers to, for example 'translate' or 'speechToText'.
+     */
+    public $productType;
+
+    /**
+     * @var string The unit the product is billed in, for example 'characters' or 'minutes'.
+     */
+    public $billingUnit;
+
+    /**
+     * @var int The amount used by this API key, expressed in the billing unit.
+     */
+    public $apiKeyUnitCount;
+
+    /**
+     * @var int The amount used by the whole account, expressed in the billing unit.
+     */
+    public $accountUnitCount;
+
+    /**
+     * @var int The characters used by this API key, 0 for products not billed in characters.
+     */
+    public $apiKeyCharacterCount;
+
+    /**
+     * @var int The characters used by the whole account, 0 for products not billed in characters.
+     */
+    public $characterCount;
+
+    public function __construct(array $json)
+    {
+        $this->productType = $json['product_type'] ?? '';
+        $this->billingUnit = $json['billing_unit'] ?? '';
+        $this->apiKeyUnitCount = $json['api_key_unit_count'] ?? 0;
+        $this->accountUnitCount = $json['account_unit_count'] ?? 0;
+        $this->apiKeyCharacterCount = $json['api_key_character_count'] ?? 0;
+        $this->characterCount = $json['character_count'] ?? 0;
+    }
+}

tests/UsageTest.php

@@ -0,0 +1,95 @@
+<?php
+
+// Copyright 2022 DeepL SE (https://www.deepl.com)
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+
+namespace DeepL;
+
+use PHPUnit\Framework\TestCase;
+
+class UsageTest extends TestCase
+{
+    private const PRO_RESPONSE = <<<'JSON'
+{
+  "character_count": 5947223,
+  "character_limit": 1000000000000,
+  "products": [
+    {
+      "product_type": "translate",
+      "billing_unit": "characters",
+      "api_key_unit_count": 636,
+      "account_unit_count": 5941580,
+      "api_key_character_count": 636,
+      "character_count": 5941580
+    },
+    {
+      "product_type": "speechToText",
+      "billing_unit": "minutes",
+      "api_key_unit_count": 30,
+      "account_unit_count": 30,
+      "api_key_character_count": 0,
+      "character_count": 0
+    }
+  ],
+  "api_key_character_count": 636,
+  "api_key_character_limit": 1000000000000,
+  "speech_to_text_milliseconds_count": 0,
+  "speech_to_text_milliseconds_limit": 0,
+  "speech_to_text_minutes_count": 30,
+  "speech_to_text_minutes_limit": 600,
+  "speech_to_speech_minutes_count": 12,
+  "speech_to_speech_minutes_limit": 600,
+  "start_time": "2025-05-13T09:18:42Z",
+  "end_time": "2025-06-13T09:18:42Z"
+}
+JSON;
+
+    public function testProAccountFields()
+    {
+        $usage = new Usage(self::PRO_RESPONSE);
+
+        $this->assertEquals(636, $usage->apiKeyCharacter->count);
+        $this->assertEquals(30, $usage->speechToTextMinutes->count);
+        $this->assertEquals(600, $usage->speechToSpeechMinutes->limit);
+        $this->assertEquals(0, $usage->speechToTextMilliseconds->limit);
+        $this->assertNull($usage->document);
+        $this->assertEquals('2025-05-13T09:18:42Z', $usage->startTime);
+        $this->assertEquals('speechToText', $usage->products[1]->productType);
+        $this->assertEquals('minutes', $usage->products[1]->billingUnit);
+        $this->assertEquals(30, $usage->products[1]->apiKeyUnitCount);
+        // Milliseconds are reported with a limit of 0, they must not count as a reached limit.
+        $this->assertFalse($usage->anyLimitReached());
+        $this->assertStringContainsString('Speech-to-text minutes: 30 of 600', strval($usage));
+    }
+
+    public function testSpeechLimitReached()
+    {
+        $json = str_replace('"speech_to_speech_minutes_count": 12', '"speech_to_speech_minutes_count": 600', self::PRO_RESPONSE);
+        $this->assertNotEquals($json, self::PRO_RESPONSE);
+        $this->assertTrue((new Usage($json))->anyLimitReached());
+    }
+
+    public function testApiKeyAndAccountLimitReached()
+    {
+        $usage = new Usage(
+            '{"character_count":500001,"character_limit":500000,"api_key_character_count":500001,"api_key_character_limit":500000}'
+        );
+
+        $this->assertTrue($usage->character->limitReached());
+        $this->assertTrue($usage->apiKeyCharacter->limitReached());
+        $this->assertTrue($usage->anyLimitReached());
+    }
+
+    public function testFreeAccountResponseUnchanged()
+    {
+        $usage = new Usage('{"character_count":180,"character_limit":500000}');
+
+        $this->assertEquals(180, $usage->character->count);
+        $this->assertNull($usage->apiKeyCharacter);
+        $this->assertNull($usage->speechToTextMinutes);
+        $this->assertSame([], $usage->products);
+        $this->assertNull($usage->startTime);
+        $this->assertFalse($usage->anyLimitReached());
+    }
+}