feat: Add more info to user-agent string

Author: JanEbbing

CHANGELOG.md

@@ -6,6 +6,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 ## [Unreleased]
+### Added
+* Added platform and node version information to the user-agent string that is sent with API calls, along with an opt-out.
+* Added method for applications that use this library to identify themselves in API requests they make.
 ### Fixed
 * Fixed proxy example code in README
 

README.md

@@ -367,6 +367,19 @@ for (let i = 0; i < glossaryLanguages.length; i++) {
 }
 ```
 
+### Writing a Plugin
+
+If you use this library in an application, please identify the application with
+the `appInfo` field in the `TranslatorOptions`, which takes the name and version of the app:
+
+```javascript
+const options = {appInfo: { appName: 'sampleNodeTranslationApp', appVersion: '1.2.3' },};
+const deepl = new deepl.Translator('YOUR_AUTH_KEY', options);
+```
+
+This information is passed along when the library makes calls to the DeepL API.
+Both name and version are required.
+
 ### Configuration
 
 The `Translator` constructor accepts configuration options as a second argument,
@@ -422,6 +435,20 @@ const deepl = new deepl.Translator('YOUR_AUTH_KEY', options);
 The proxy argument is passed to the underlying `axios` request, see the
 [documentation for axios][axios-proxy-docs].
 
+#### Anonymous platform information
+
+By default, we send some basic information about the platform the client library
+is running on with each request, see [here for an explanation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent).
+This data is completely anonymous and only used to improve our product, not track
+any individual users. If you do not wish to send this data, you can opt-out when
+creating your `Translator` object by setting the `sendPlatformInfo` flag in
+the `TranslatorOptions` to `false` like so:
+
+```javascript
+const options = {sendPlatformInfo: false};
+const deepl = new deepl.Translator('YOUR_AUTH_KEY', options);
+```
+
 ### Request retries
 
 Requests to the DeepL API that fail due to transient conditions (for example,

package-lock.json

@@ -37,6 +37,7 @@
         "eslint-plugin-promise": "^6.0.0",
         "jest": "^27.4.3",
         "jest-junit": "^13.0.0",
+        "nock": "^13.3.0",
         "prettier": "^2.5.1",
         "ts-jest": "^27.1.1",
         "typescript": "^4.5.3",

package.json

@@ -24,6 +24,7 @@ import {
     parseUsage,
 } from './parsing';
 import {
+    AppInfo,
     DocumentTranslateOptions,
     Formality,
     GlossaryId,
@@ -44,6 +45,7 @@ import { isString, logInfo, streamToBuffer, streamToString, timeout, toBoolStrin
 import * as fs from 'fs';
 import { IncomingMessage, STATUS_CODES } from 'http';
 import path from 'path';
+import * as os from 'os';
 import { URLSearchParams } from 'url';
 import * as util from 'util';
 
@@ -469,7 +471,10 @@ export class Translator {
         }
         const headers = {
             Authorization: `DeepL-Auth-Key ${authKey}`,
-            'User-Agent': 'deepl-node/1.8.0',
+            'User-Agent': this.constructUserAgentString(
+                options?.sendPlatformInfo === false ? false : true,
+                options?.appInfo,
+            ),
             ...(options?.headers ?? {}),
         };
 
@@ -981,6 +986,23 @@ export class Translator {
         return parseGlossaryInfo(content);
     }
 
+    private constructUserAgentString(
+        sendPlatformInfo: boolean,
+        appInfo: AppInfo | undefined,
+    ): string {
+        let libraryInfoString = 'deepl-node/1.8.0';
+        if (sendPlatformInfo) {
+            const systemType = os.type();
+            const systemVersion = os.version();
+            const nodeVersion = process.version.substring(1); // Drop the v in the version number
+            libraryInfoString += ` (${systemType} ${systemVersion}) node/${nodeVersion}`;
+        }
+        if (appInfo) {
+            libraryInfoString += ` ${appInfo.appName}/${appInfo.appVersion}`;
+        }
+        return libraryInfoString;
+    }
+
     /**
      * HttpClient implements all HTTP requests and retries.
      * @private

src/index.ts

@@ -16,6 +16,16 @@ export interface ProxyConfig {
     protocol?: string;
 }
 
+/**
+ * Optional identifier for the app that is using this library, may be specified
+ * as appInfo in TranslatorOptions.
+ * @see TranslatorOptions.appInfo
+ */
+export interface AppInfo {
+    appName: string;
+    appVersion: string;
+}
+
 /**
  * Options that can be specified when constructing a Translator.
  */
@@ -49,6 +59,18 @@ export interface TranslatorOptions {
      * Define the host, port and protocol of the proxy server.
      */
     proxy?: ProxyConfig;
+
+    /**
+     * Define if the library is allowed to send more detailed information about which platform
+     * it is running on with each API call. Defaults to true if undefined. Overriden by
+     * the `customUserAgent` option.
+     */
+    sendPlatformInfo?: boolean;
+
+    /**
+     * Identifies the application using this client library, will be sent in the `User-Agent` header
+     */
+    appInfo?: AppInfo;
 }
 
 export type Formality = 'less' | 'more' | 'default' | 'prefer_less' | 'prefer_more';

src/types.ts

@@ -61,6 +61,7 @@ export function isString(arg: any): arg is string {
  * Returns '1' if the given arg is truthy, '0' otherwise.
  * @param arg Argument to check.
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function toBoolString(arg: any): string {
     return arg ? '1' : '0';
 }

src/utils.ts

@@ -90,6 +90,8 @@ export interface TestTranslatorOptions {
     maxRetries?: number;
     minTimeout?: number;
     proxy?: deepl.ProxyConfig;
+    sendPlatformInfo?: boolean;
+    appInfo?: deepl.AppInfo;
 
     mockServerNoResponseTimes?: number;
     mockServer429ResponseTimes?: number;
@@ -108,7 +110,7 @@ export interface TestTranslatorOptions {
  * session settings.
  * @param options Options controlling Translator behaviour and mock-server sessions settings.
  */
-export function makeTranslator(options?: TestTranslatorOptions) {
+export function makeTranslator(options?: TestTranslatorOptions): deepl.Translator {
     if (!usingMockServer && process.env.DEEPL_AUTH_KEY === undefined) {
         throw Error('DEEPL_AUTH_KEY environment variable must be defined unless using mock-server');
     }
@@ -168,6 +170,8 @@ export function makeTranslator(options?: TestTranslatorOptions) {
         minTimeout: options?.minTimeout,
         maxRetries: options?.maxRetries,
         proxy: options?.proxy,
+        sendPlatformInfo: options?.sendPlatformInfo,
+        appInfo: options?.appInfo,
     });
 }