feat: Add support for style_id and get all style rules endpoint

Author: BriannaDelgado

README.md

@@ -175,6 +175,8 @@ console.log(await deeplClient.translateText('How are you?', null, 'de', { formal
 -   `glossary`: specifies a glossary to use with translation, either as a string
     containing the glossary ID, or a `MultilingualGlossaryInfo`/`GlossaryInfo` as returned by
     `getMultilingualGlossary()`/`getGlossary()`.
+-   `styleRule`: specifies a style rule to use with translation, either as a string
+    containing the style rule ID, or a `StyleRuleInfo` as returned by `getAllStyleRules()`.
 -   `context`: specifies additional context to influence translations, that is not
     translated itself. Characters in the `context` parameter are not counted toward billing.
     See the [API documentation][api-docs-context-param] for more information and
@@ -261,6 +263,7 @@ directly:
 
 -   `formality`: same as in [Text translation options](#text-translation-options).
 -   `glossary`: same as in [Text translation options](#text-translation-options).
+-   `styleRule`: same as in [Text translation options](#text-translation-options).
 -   `filename`: if the input file is not provided as file path, this option is
     needed to specify the file extension.
 -   `extraRequestParameters`: same as in [Text translation options](#text-translation-options).
@@ -482,6 +485,42 @@ console.log(entriesObj.entries.toTsv()); // {'artist': 'Maler', 'hello': 'hallo'
 
 For examples for the other methods please see [this migration guide](upgrade_to_multilingual_glossaries.md)
 
+### Style Rules
+
+Style rules allow you to customize your translations using a managed, shared list
+of rules for style, formatting, and more. Multiple style rules can be stored with 
+your account, each with a user-specified name and a uniquely-assigned ID.
+
+#### Creating and managing style rules
+
+Currently style rules must be created and managed in the DeepL UI via
+https://www.deepl.com/en/custom-rules. Full CRUD functionality via the APIs will
+come shortly.
+
+#### Listing all style rules
+
+`getAllStyleRules()` returns a list of `StyleRuleInfo` objects
+corresponding to all of your stored style rules. The method accepts optional
+parameters: `page` (page number for pagination, 0-indexed), `pageSize` (number
+of items per page), and `detailed` (whether to include detailed configuration
+rules in the `configuredRules` property).
+
+```javascript
+// Get all style rules
+const styleRules = await deeplClient.getAllStyleRules();
+for (const rule of styleRules) {
+    console.log(`${rule.name} (${rule.styleId})`);
+}
+
+// Get style rules with detailed configuration
+const styleRules = await deeplClient.getAllStyleRules({ detailed: true });
+for (const rule of styleRules) {
+    if (rule.configuredRules) {
+        console.log(`  Number formatting: ${rule.configuredRules.numbers}`);
+    }
+}
+```
+
 ### Checking account usage
 
 To check account usage, use the `getUsage()` function.

src/deeplClient.ts

@@ -13,13 +13,15 @@ import {
     MultilingualGlossaryDictionaryEntriesApiResponse,
     GlossaryId,
     ListMultilingualGlossaryApiResponse,
+    StyleRuleInfo,
 } from './types';
 import {
     parseMultilingualGlossaryDictionaryInfo,
     parseMultilingualGlossaryInfo,
     parseWriteResultArray,
     parseMultilingualGlossaryDictionaryEntries,
     parseListMultilingualGlossaries,
+    parseStyleRuleInfoList,
 } from './parsing';
 import {
     appendCsvDictionaryEntries,
@@ -542,4 +544,40 @@ export class DeepLClient extends Translator {
         await checkStatusCode(statusCode, content, true /* usingGlossary */);
         return parseMultilingualGlossaryInfo(content);
     }
+
+    /**
+     * Retrieves a list of all style rules available for the authenticated user.
+     *
+     * @param page: Page number for pagination, 0-indexed (optional).
+     * @param pageSize: Number of items per page (optional).
+     * @param detailed: Whether to include detailed configuration rules in the `configuredRules` property (optional).
+     * @returns {Promise<StyleRuleInfo[]>} An array of objects containing details about each style rule.
+     *
+     * @throws {DeepLError} If any error occurs while communicating with the DeepL API.
+     */
+    async getAllStyleRules(
+        page?: number,
+        pageSize?: number,
+        detailed?: boolean,
+    ): Promise<StyleRuleInfo[]> {
+        const queryParams = new URLSearchParams();
+        if (page !== undefined) {
+            queryParams.append('page', String(page));
+        }
+        if (pageSize !== undefined) {
+            queryParams.append('page_size', String(pageSize));
+        }
+        if (detailed !== undefined) {
+            queryParams.append('detailed', String(detailed).toLowerCase());
+        }
+
+        const { statusCode, content } = await this.httpClient.sendRequestWithBackoff<string>(
+            'GET',
+            '/v3/style_rules',
+            { data: queryParams },
+        );
+
+        await checkStatusCode(statusCode, content);
+        return parseStyleRuleInfoList(content);
+    }
 }

src/parsing.ts

@@ -24,6 +24,11 @@ import {
     MultilingualGlossaryDictionaryApiResponse,
     MultilingualGlossaryDictionaryEntriesApiResponse,
     ListMultilingualGlossaryApiResponse,
+    StyleRuleInfo,
+    StyleRuleInfoApiResponse,
+    ListStyleRuleApiResponse,
+    ConfiguredRules,
+    CustomInstruction,
 } from './types';
 import { standardizeLanguageCode } from './utils';
 
@@ -527,3 +532,80 @@ export function parseDocumentHandle(json: string): DocumentHandle {
         throw new DeepLError(`Error parsing response JSON: ${error}`);
     }
 }
+
+/**
+ * Parses the given style rule API response to a ConfiguredRules object.
+ * @private
+ */
+function parseConfiguredRules(
+    configuredRulesData?: StyleRuleInfoApiResponse['configured_rules'],
+): ConfiguredRules | undefined {
+    if (!configuredRulesData) {
+        return undefined;
+    }
+    return {
+        datesAndTimes: configuredRulesData.dates_and_times,
+        formatting: configuredRulesData.formatting,
+        numbers: configuredRulesData.numbers,
+        punctuation: configuredRulesData.punctuation,
+        spellingAndGrammar: configuredRulesData.spelling_and_grammar,
+        styleAndTone: configuredRulesData.style_and_tone,
+        vocabulary: configuredRulesData.vocabulary,
+    };
+}
+
+/**
+ * Parses the given custom instruction API response to a CustomInstruction object.
+ * @private
+ */
+function parseCustomInstruction(instruction: {
+    label: string;
+    prompt: string;
+    source_language?: string;
+}): CustomInstruction {
+    return {
+        label: instruction.label,
+        prompt: instruction.prompt,
+        sourceLanguage: instruction.source_language,
+    };
+}
+
+/**
+ * Parses the given style rule API response to a StyleRuleInfo object.
+ * @private
+ */
+function parseStyleRuleInfo(styleRule: StyleRuleInfoApiResponse): StyleRuleInfo {
+    try {
+        const customInstructions = styleRule.custom_instructions
+            ? styleRule.custom_instructions.map(parseCustomInstruction)
+            : undefined;
+
+        return {
+            styleId: styleRule.style_id,
+            name: styleRule.name,
+            creationTime: new Date(styleRule.creation_time),
+            updatedTime: new Date(styleRule.updated_time),
+            language: styleRule.language,
+            version: styleRule.version,
+            configuredRules: parseConfiguredRules(styleRule.configured_rules),
+            customInstructions,
+        };
+    } catch (error) {
+        throw new DeepLError(`Error parsing response JSON: ${error}`);
+    }
+}
+
+/**
+ * Parses the given JSON string to an array of StyleRuleInfo objects.
+ * @private
+ */
+export function parseStyleRuleInfoList(json: string): StyleRuleInfo[] {
+    try {
+        const obj = JSON.parse(json) as ListStyleRuleApiResponse;
+        return obj.style_rules.map((styleRule: StyleRuleInfoApiResponse) =>
+            parseStyleRuleInfo(styleRule),
+        );
+    } catch (error) {
+        throw new DeepLError(`Error parsing response JSON: ${error}`);
+    }
+}

src/types.ts

@@ -86,6 +86,7 @@ export type SentenceSplittingMode = 'off' | 'on' | 'nonewlines' | 'default';
 export type TagHandlingMode = 'html' | 'xml';
 export type ModelType = 'quality_optimized' | 'latency_optimized' | 'prefer_quality_optimized';
 export type GlossaryId = string;
+export type StyleId = string;
 export type TagList = string | string[];
 
 /**
@@ -154,6 +155,11 @@ export interface TranslateTextOptions extends BaseRequestOptions {
      */
     glossary?: GlossaryId | GlossaryInfo | MultilingualGlossaryInfo;
 
+    /** Specifies the ID of a style rule to use with translation, or
+     * a StyleRuleInfo object as returned by getAllStyleRules().
+     */
+    styleRule?: StyleId | StyleRuleInfo;
+
     /** Type of tags to parse before translation, options are 'html' and 'xml'. */
     tagHandling?: TagHandlingMode;
 
@@ -194,6 +200,11 @@ export interface DocumentTranslateOptions extends BaseRequestOptions {
      */
     glossary?: GlossaryId | GlossaryInfo | MultilingualGlossaryInfo;
 
+    /** Specifies the ID of a style rule to use with translation, or
+     * a StyleRuleInfo object as returned by getAllStyleRules().
+     */
+    styleRule?: StyleId | StyleRuleInfo;
+
     /** Filename including extension, only required when translating documents as streams. */
     filename?: string;
 
@@ -569,3 +580,92 @@ export interface ListMultilingualGlossaryApiResponse {
         },
     ];
 }
+
+/**
+ * Custom instruction for a style rule.
+ */
+export interface CustomInstruction {
+    /** Label for the custom instruction. */
+    readonly label: string;
+    /** Prompt text for the custom instruction. */
+    readonly prompt: string;
+    /** Optional source language code for the custom instruction. */
+    readonly sourceLanguage?: string;
+}
+
+/**
+ * Configuration rules for a style rule list.
+ */
+export interface ConfiguredRules {
+    /** Date and time formatting rules. */
+    readonly datesAndTimes?: Record<string, string>;
+    /** Text formatting rules. */
+    readonly formatting?: Record<string, string>;
+    /** Number formatting rules. */
+    readonly numbers?: Record<string, string>;
+    /** Punctuation rules. */
+    readonly punctuation?: Record<string, string>;
+    /** Spelling and grammar rules. */
+    readonly spellingAndGrammar?: Record<string, string>;
+    /** Style and tone rules. */
+    readonly styleAndTone?: Record<string, string>;
+    /** Vocabulary rules. */
+    readonly vocabulary?: Record<string, string>;
+}
+
+/**
+ * Information about a style rule list.
+ */
+export interface StyleRuleInfo {
+    /** Unique ID assigned to the style rule list. */
+    readonly styleId: StyleId;
+    /** User-defined name assigned to the style rule list. */
+    readonly name: string;
+    /** Time when the style rule list was created. */
+    readonly creationTime: Date;
+    /** Time when the style rule list was last updated. */
+    readonly updatedTime: Date;
+    /** Language code for the style rule list. */
+    readonly language: string;
+    /** Version number of the style rule list. */
+    readonly version: number;
+    /** The predefined rules that have been enabled. */
+    readonly configuredRules?: ConfiguredRules;
+    /** Optional list of custom instructions. */
+    readonly customInstructions?: CustomInstruction[];
+}
+
+/**
+ * Type used during JSON parsing of API response for style rule info.
+ * @private
+ */
+export interface StyleRuleInfoApiResponse {
+    style_id: string;
+    name: string;
+    creation_time: string;
+    updated_time: string;
+    language: string;
+    version: number;
+    configured_rules?: {
+        dates_and_times?: Record<string, string>;
+        formatting?: Record<string, string>;
+        numbers?: Record<string, string>;
+        punctuation?: Record<string, string>;
+        spelling_and_grammar?: Record<string, string>;
+        style_and_tone?: Record<string, string>;
+        vocabulary?: Record<string, string>;
+    };
+    custom_instructions?: Array<{
+        label: string;
+        prompt: string;
+        source_language?: string;
+    }>;
+}
+
+/**
+ * Type used during JSON parsing of API response for listing style rules.
+ * @private
+ */
+export interface ListStyleRuleApiResponse {
+    style_rules: StyleRuleInfoApiResponse[];
+}

src/utils.ts

@@ -12,10 +12,12 @@ import {
     NonRegionalLanguageCode,
     RequestParameters,
     SentenceSplittingMode,
+    StyleId,
     TagList,
     TranslateTextOptions,
     MultilingualGlossaryInfo,
     MultilingualGlossaryDictionaryEntries,
+    StyleRuleInfo,
 } from './types';
 
 const logger = loglevel.getLogger('deepl');
@@ -273,6 +275,16 @@ export function validateAndAppendTextOptions(
     if (options.ignoreTags !== undefined) {
         data.append('ignore_tags', joinTagList(options.ignoreTags));
     }
+    if (options.styleRule !== undefined) {
+        if (!isString(options.styleRule)) {
+            if (options.styleRule.styleId === undefined) {
+                throw new DeepLError(
+                    'styleRule option should be a StyleId (string) containing the Style Rule ID or a StyleRuleInfo object.',
+                );
+            }
+            data.append('style_id', options.styleRule.styleId);
+        }
+    }
 }
 
 /**