feat: add billedCharacters to translate text response

CHANGELOG.md

@@ -5,6 +5,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [Unreleased]
+### Added
+* Added `billedCharacters` field to text translation response.
+
+
 ## [1.13.1] - 2024-08-14
 ### Added
 * Added supported glossary languages: Danish (`'da'`), Norwegian (bokmål)
@@ -250,6 +255,7 @@ client library took over this package name. Thanks to
 ownership.
 
 
+[Unreleased]: https://github.com/DeepLcom/deepl-node/compare/v1.13.1...HEAD
 [1.13.1]: https://github.com/DeepLcom/deepl-node/compare/v1.13.0...v1.13.1
 [1.13.0]: https://github.com/DeepLcom/deepl-node/compare/v1.12.0...v1.13.0
 [1.12.0]: https://github.com/DeepLcom/deepl-node/compare/v1.11.1...v1.12.0

README.md

@@ -122,9 +122,11 @@ translation options, see [Text translation options](#text-translation-options)
 below.
 
 `translateText()` returns a Promise that fulfills with a `TextResult`, or an
-array of `TextResult`s corresponding to your input text(s). `TextResult` has two
-properties: `text` is the translated text, and `detectedSourceLang` is the
-detected source language code.
+array of `TextResult`s corresponding to your input text(s). `TextResult` has the
+following properties:
+- `text` is the translated text,
+- `detectedSourceLang` is the detected source language code,
+- `billedCharacters` is the number of characters billed for the text.
 
 ```javascript
 // Translate text into a target language, in this case, French:
@@ -139,8 +141,10 @@ const translations = await translator.translateText(
 );
 console.log(translations[0].text); // 'How are you?'
 console.log(translations[0].detectedSourceLang); // 'ja'
+console.log(translations[0].billedCharacters); // 7 - the number of characters in the source text "お元気ですか？"
 console.log(translations[1].text); // 'How are you?'
 console.log(translations[1].detectedSourceLang); // 'es'
+console.log(translations[1].billedCharacters); // 12 - the number of characters in the source text "¿Cómo estás?"
 
 // Translate into German with less and more Formality:
 console.log(await translator.translateText('How are you?', null, 'de', { formality: 'less' })); // 'Wie geht es dir?'

src/index.ts

@@ -223,6 +223,11 @@ export interface TextResult {
      * Language code of the detected source language.
      */
     readonly detectedSourceLang: SourceLanguageCode;
+
+    /**
+     * Number of characters billed for this text.
+     */
+    readonly billedCharacters: number;
 }
 
 /**
@@ -576,6 +581,8 @@ export class Translator {
             options?.glossary,
             options?.extraRequestParameters,
         );
+        // Always send show_billed_characters=1, remove when the API default is changed to true
+        data.append('show_billed_characters', '1');
         const singular = appendTextsAndReturnIsSingular(data, texts);
         validateAndAppendTextOptions(data, options);
 

src/parsing.ts

@@ -60,6 +60,7 @@ interface UsageApiResponse {
 interface TextResultApiResponse {
     text: string;
     detected_source_language: string;
+    billed_characters: number;
 }
 
 /**
@@ -310,6 +311,7 @@ export function parseTextResultArray(json: string): TextResult[] {
                 detectedSourceLang: standardizeLanguageCode(
                     translation.detected_source_language,
                 ) as SourceLanguageCode,
+                billedCharacters: translation.billed_characters,
             };
         });
     } catch (error) {

tests/general.test.ts

@@ -44,6 +44,7 @@ describe('general', () => {
                 // eslint-disable-next-line @typescript-eslint/no-loop-func, promise/always-return
                 .then((result: deepl.TextResult) => {
                     expect(result.text.toLowerCase()).toContain('proton');
+                    expect(result.billedCharacters).toBe(inputText.length);
                 });
             promises.push(promise);
         }

tests/translateText.test.ts

@@ -22,6 +22,7 @@ describe('translate text', () => {
         const result = await translator.translateText(exampleText.en, null, 'de');
         expect(result.text).toBe(exampleText.de);
         expect(result.detectedSourceLang).toBe('en');
+        expect(result.billedCharacters).toBe(exampleText.en.length);
     });
 
     it('should translate an array of texts', async () => {