feat: accept an options object in rephraseText()

Add RephraseTextOptions with writingStyle, tone and extraBodyParameters,
accepted as the third argument of rephraseText(). Passing the writing
style and tone positionally is deprecated.

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

Author: hive-bot

CHANGELOG.md

@@ -61,6 +61,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `translateDocumentWaitUntilDone()`, which polls a document translation
   until it is done and resolves with the final `DocumentStatus`, or rejects with
   a `DeepLError` if the translation fails.
+- Added the `RephraseTextOptions` type with `writingStyle`, `tone` and
+  `extraBodyParameters`. `rephraseText()` accepts it as its third argument.
+  `extraBodyParameters` are added to the request body and override parameters
+  of the same name.
 
 ### Changed
 - `getSourceLanguages()`, `getTargetLanguages()`, and `getGlossaryLanguagePairs()` now call the
@@ -83,6 +87,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `isDocumentTranslationComplete()` is deprecated; use
   `translateDocumentWaitUntilDone()` instead. It will be removed in the next
   major version.
+- Passing the writing style and tone of `rephraseText()` as positional
+  arguments is deprecated; pass a `RephraseTextOptions` object as the third
+  argument instead. The positional form will be removed in the next major
+  version.
 
 ### Fixed
 - `downloadTranslationMemoryExport()` no longer hangs on Node 16 and 17 when the output file

README.md

@@ -1129,7 +1129,12 @@ To rephrase text, call `rephraseText()`. The first argument is a string containi
 
 The second argument is the target language code. Language codes are **case-insensitive** strings, for example, `'de'`, `'fr'`, `'en'`. The target language code can also be `null` to enable auto-detection of the target language.
 
-The last two arguments, `writingStyle` and `tone`, are optional and specify the writing style and tone of the rephrased text. Possible values are defined in the `WritingStyle` and `WritingTone` enums.
+The third argument is optional and is a `RephraseTextOptions` object with the following properties:
+-   `writingStyle`: the writing style of the rephrased text. Possible values are defined in the `WritingStyle` enum.
+-   `tone`: the tone of the rephrased text. Possible values are defined in the `WritingTone` enum. The API accepts either `writingStyle` or `tone` in a request, not both.
+-   `extraBodyParameters`: extra parameters to add to the request body. They can override parameters set by the library.
+
+Passing the writing style and tone as the third and fourth arguments, for example `rephraseText(text, 'en', WritingStyle.ACADEMIC)`, is deprecated and will be removed in the next major version.
 
 `rephraseText()` returns a Promise that fulfills with an `Improvement` object or an array of `Improvement` objects corresponding to your input text(s). The `Improvement` object has the following properties:
 - `text`: the rephrased text,
@@ -1138,15 +1143,16 @@ The last two arguments, `writingStyle` and `tone`, are optional and specify the
 
 ```javascript
 // Rephrasing a text in academic style:
-const rephrasedResult = await deepLClient.rephraseText('This is an example text.', 'en', WritingStyle.ACADEMIC);
+const rephrasedResult = await deepLClient.rephraseText('This is an example text.', 'en', {
+    writingStyle: WritingStyle.ACADEMIC,
+});
 console.log(rephrasedResult.text); // The rephrased text in academic style
 
 // Rephrasing multiple texts in a friendly tone:
 const rephrasedTexts = await deepLClient.rephraseText(
     ['How are you?', 'What are you doing today?'],
     'de',
-    null,
-    WritingTone.FRIENDLY,
+    { tone: WritingTone.FRIENDLY },
 );
 console.log(rephrasedTexts[0].text); // The rephrased text for "How are you?" in a friendly tone
 console.log(rephrasedTexts[1].text); // The rephrased text for "What are you doing today?" in a friendly tone

src/deeplClient.ts

@@ -35,6 +35,8 @@ import {
     LanguageResourceName,
     GetLanguagesForResourceOptions,
     LanguageSupport,
+    RephraseTextOptions,
+    RequestParameters,
 } from './types';
 import {
     parseMultilingualGlossaryDictionaryInfo,
@@ -145,12 +147,64 @@ export class DeepLClient extends Translator {
         super(authKey, options);
     }
 
+    /**
+     * @deprecated Pass the writing style in a {@link RephraseTextOptions} object as the third
+     * argument instead. The positional parameters will be removed in the next major version.
+     */
+    async rephraseText<T extends string | string[]>(
+        texts: T,
+        targetLang: string | null | undefined,
+        writingStyle: string,
+        tone?: string | null,
+    ): Promise<T extends string ? WriteResult : WriteResult[]>;
+    /**
+     * Rephrases the given text(s), optionally in a writing style or tone.
+     * @param texts Text to rephrase, or an array of texts.
+     * @param targetLang Target language code, or `null` to keep the language of the input text.
+     * @param options Rephrasing options, see {@link RephraseTextOptions}. Passing the writing
+     *     style as a string here is deprecated.
+     * @param tone Deprecated, use {@link RephraseTextOptions.tone}.
+     * @return Promise of a {@link WriteResult}, or an array of them if `texts` is an array.
+     * @throws {ArgumentError} If an options object is combined with a `tone` argument.
+     * @throws {DeepLError} If any error occurs while communicating with the DeepL API.
+     */
+    async rephraseText<T extends string | string[]>(
+        texts: T,
+        targetLang?: string | null,
+        // string and the undefined tone keep subclass overrides with the old positional
+        // signature compiling; a null tone would make string styles skip the deprecated overload
+        options?: RephraseTextOptions | string | null,
+        tone?: undefined,
+    ): Promise<T extends string ? WriteResult : WriteResult[]>;
+    /**
+     * @deprecated Pass the writing style and tone in a {@link RephraseTextOptions} object as the
+     * third argument instead. The positional parameters will be removed in the next major version.
+     */
     async rephraseText<T extends string | string[]>(
         texts: T,
         targetLang?: string | null,
         writingStyle?: string | null,
         tone?: string | null,
+    ): Promise<T extends string ? WriteResult : WriteResult[]>;
+    async rephraseText<T extends string | string[]>(
+        texts: T,
+        targetLang?: string | null,
+        writingStyleOrOptions?: string | RephraseTextOptions | null,
+        tone?: string | null,
     ): Promise<T extends string ? WriteResult : WriteResult[]> {
+        let writingStyle: string | null | undefined;
+        let extraBodyParameters: RequestParameters | undefined;
+        if (typeof writingStyleOrOptions === 'object' && writingStyleOrOptions !== null) {
+            if (tone !== undefined && tone !== null) {
+                throw new ArgumentError(
+                    'tone cannot be passed as a separate argument together with an options object',
+                );
+            }
+            ({ writingStyle, tone, extraBodyParameters } = writingStyleOrOptions);
+        } else {
+            writingStyle = writingStyleOrOptions;
+        }
+
         const data = new URLSearchParams();
         if (targetLang) {
             data.append('target_lang', targetLang);
@@ -165,6 +219,11 @@ export class DeepLClient extends Translator {
         }
 
         const singular = appendTextsAndReturnIsSingular(data, texts);
+        if (extraBodyParameters !== undefined) {
+            for (const paramName in extraBodyParameters) {
+                data.set(paramName, extraBodyParameters[paramName]);
+            }
+        }
         const { statusCode, content } = await this.httpClient.sendRequestWithBackoff<string>(
             'POST',
             '/v2/write/rephrase',

src/types.ts

@@ -787,6 +787,22 @@ export interface TextResult {
     readonly modelTypeUsed?: string;
 }
 
+/**
+ * Options that can be specified when rephrasing text with `rephraseText()`.
+ */
+export interface RephraseTextOptions {
+    /** Writing style of the rephrased text, see `WritingStyle`. Cannot be combined with `tone`. */
+    writingStyle?: string;
+    /** Tone of the rephrased text, see `WritingTone`. Cannot be combined with `writingStyle`. */
+    tone?: string;
+    /**
+     * Extra parameters to be added to the request body.
+     * Keys in this object will be added to the request body, and can override built-in parameters.
+     * This is mostly used by DeepL employees to test functionality, or for beta programs.
+     */
+    extraBodyParameters?: RequestParameters;
+}
+
 /**
  * Holds the result of a text rephrasing request.
  */

tests/offline/rephraseText.test.ts

@@ -5,6 +5,7 @@
 import nock from 'nock';
 
 import { WritingStyle, WritingTone } from '../../src/deeplClient';
+import { ArgumentError } from '../../src/errors';
 import { makeDeeplClient, serverUrl } from './client';
 
 const rephrased = {
@@ -49,6 +50,45 @@ describe('DeepLClient.rephraseText', () => {
         },
     );
 
+    it('sends the writing style, tone and extra body parameters of an options object', async () => {
+        nock(serverUrl)
+            .post('/v2/write/rephrase', {
+                text: 'abc',
+                target_lang: 'en',
+                writing_style: 'business',
+                tone: 'confident',
+                extra: 'x',
+            })
+            .reply(200, rephrased);
+
+        await makeDeeplClient().rephraseText('abc', 'en', {
+            writingStyle: WritingStyle.BUSINESS,
+            tone: WritingTone.CONFIDENT,
+            extraBodyParameters: { extra: 'x' },
+        });
+    });
+
+    it('lets extra body parameters override built-in parameters', async () => {
+        nock(serverUrl)
+            .post('/v2/write/rephrase', { text: 'abc', target_lang: 'fr' })
+            .reply(200, rephrased);
+
+        await makeDeeplClient().rephraseText('abc', 'en', {
+            extraBodyParameters: { target_lang: 'fr' },
+        });
+    });
+
+    it('throws ArgumentError when an options object is combined with a tone argument', async () => {
+        const client = makeDeeplClient();
+        // The overloads reject this at compile time; JavaScript callers can still pass it
+        const rephraseText = client.rephraseText.bind(client) as (
+            ...args: unknown[]
+        ) => Promise<unknown>;
+        await expect(rephraseText('abc', 'en', {}, WritingTone.FRIENDLY)).rejects.toThrow(
+            ArgumentError,
+        );
+    });
+
     it('sends every text of an array and returns an array of results', async () => {
         nock(serverUrl)
             .post('/v2/write/rephrase', { text: ['a', 'b'], target_lang: 'de' })