feat: align translation memory jobs and imports with the SDK interface

Add waitUntilTranslationMemoryJobDone() (deprecating
isTranslationMemoryJobComplete()), accept a TranslationMemoryJob in the
job methods and WaitOptions next to the positional timeout, add result,
status, done() and ok() to TranslationMemoryJob, add the import option
types with extraBodyParameters, and accept a Buffer or ReadStream in
importTranslationMemoryFromFilepath().

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

Author: hive-bot

CHANGELOG.md

@@ -6,6 +6,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
+- Added `waitUntilTranslationMemoryJobDone()`, which replaces
+  `isTranslationMemoryJobComplete()`. It accepts the job as an ID or a
+  `TranslationMemoryJob`, and `WaitOptions` or the timeout in milliseconds, and
+  rejects with the job's error message if the job fails or expires.
+  `getTranslationMemoryJob()` also accepts a `TranslationMemoryJob`.
+- Added `result`, `status`, `done()` and `ok()` to `TranslationMemoryJob`:
+  the single entry of `results`, its status, whether the job completed, and
+  whether it has not failed or expired.
+- Added the `CreateTranslationMemoryImportOptions` and
+  `ImportTranslationMemoryOptions` types, with `extraBodyParameters` merged last
+  into the import request body.
+- `importTranslationMemoryFromFilepath()` accepts a `Buffer` or `ReadStream`, with
+  the new `fileName` option (or `displayName`) as the file name.
+- `isTranslationMemoryJobComplete()` also accepts `WaitOptions`.
 - The style rule methods `getStyleRule()`, `updateStyleRuleName()`,
   `updateStyleRuleConfiguredRules()`, `deleteStyleRule()` and the four custom
   instruction methods accept the style rule as an ID or a `StyleRuleInfo`
@@ -185,6 +199,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   limit and links to the DeepL API usage limits instead.
 
 ### Deprecated
+- `isTranslationMemoryJobComplete()`: use `waitUntilTranslationMemoryJobDone()`
+  instead.
 - The `'downloaded'` member of `TranslationMemoryJobStatus`: the API does not
   report it for translation memory jobs.
 - `uploadDocument()`, `getDocumentStatus()` and `downloadDocument()` are

README.md

@@ -913,10 +913,20 @@ const job = await deeplClient.importTranslationMemoryFromFilepath('/path/to/lega
     displayName: 'Legal TM',
     timeoutMs: 300000,
 });
-console.log(`Created translation memory ${job.results[0].translationMemoryId}`);
-console.log(`Skipped segments: ${job.results[0].skippedSegmentCount}`);
+console.log(`Created translation memory ${job.result?.translationMemoryId}`);
+console.log(`Skipped segments: ${job.result?.skippedSegmentCount}`);
 ```
 
+The input may also be a `Buffer` or `ReadStream`; then pass the `fileName`
+option (otherwise `displayName` is used as the file name). The options
+(`ImportTranslationMemoryOptions`) are:
+
+-   `displayName`: name of the new translation memory; defaults to the file name.
+-   `contentType`: MIME type of the file; defaults to `'application/xml'`.
+-   `fileName`: file name sent to the API; defaults to the base name of the path.
+-   `timeoutMs`: maximum time to wait for the import, in milliseconds.
+-   `extraBodyParameters`: extra fields added last to the JSON request body.
+
 The three steps are also available separately, for example to upload the file
 yourself or to poll for progress. `createTranslationMemoryImport()` returns an
 upload URL that the file must be uploaded to, then `getTranslationMemoryJob()`
@@ -929,15 +939,32 @@ const created = await deeplClient.createTranslationMemoryImport('legal.tmx', fil
 });
 await deeplClient.uploadTranslationMemoryFile(created, fileBuffer);
 
-const job = await deeplClient.isTranslationMemoryJobComplete(created.jobId, 300000);
+const job = await deeplClient.waitUntilTranslationMemoryJobDone(created.jobId, {
+    timeoutMs: 300000,
+});
 ```
 
+`createTranslationMemoryImport()` accepts `CreateTranslationMemoryImportOptions`:
+`contentType`, `displayName` and `extraBodyParameters`.
+
+`getTranslationMemoryJob()` and `waitUntilTranslationMemoryJobDone()` accept the
+job ID or a `TranslationMemoryJob`. `waitUntilTranslationMemoryJobDone()` takes
+`WaitOptions` (`{ timeoutMs }`) or the timeout in milliseconds as a number,
+resolves with the job once its status is `'completed'`, and rejects with a
+`DeepLError` carrying the job's error message if it fails or expires.
+`isTranslationMemoryJobComplete()` is deprecated in its favour.
+
+A `TranslationMemoryJob` has `result` (the single entry of `results`), `status`
+(the status of `result`), `done()` (true once the status is `'completed'`) and
+`ok()` (false once the status is `'failed'` or `'expired'`, true while the job
+is in progress). `status` may also be a status this library does not know.
+
 The job status is `'awaiting_input'` until the file is uploaded, and stays
 `'awaiting_input'` for a while afterwards because the API detects the upload
-asynchronously. `isTranslationMemoryJobComplete()` polls through that status
-like any other non-terminal one. A job whose file is never uploaded does not
-finish on its own, so pass a timeout in milliseconds when that is a
-possibility.
+asynchronously. `waitUntilTranslationMemoryJobDone()` polls through that status
+like any other status that is not final, including statuses it does not know.
+A job whose file is never uploaded does not finish on its own, so pass a
+timeout when that is a possibility.
 
 #### Exporting a translation memory
 
@@ -957,7 +984,9 @@ indicated by `reusedExisting`.
 
 ```javascript
 const created = await deeplClient.createTranslationMemoryExport('YOUR_TM_ID');
-const job = await deeplClient.isTranslationMemoryJobComplete(created.jobId, 300000);
+const job = await deeplClient.waitUntilTranslationMemoryJobDone(created.jobId, {
+    timeoutMs: 300000,
+});
 await deeplClient.downloadTranslationMemoryExport(job, '/path/to/exported.tmx');
 ```
 

src/deeplClient.ts

@@ -39,6 +39,9 @@ import {
     TranslationMemoryJob,
     TranslationMemorySegments,
     TranslationMemorySegmentsOptions,
+    CreateTranslationMemoryImportOptions,
+    ImportTranslationMemoryOptions,
+    WaitOptions,
     LanguageResource,
     LanguageResourceName,
     GetLanguagesForResourceOptions,
@@ -80,6 +83,7 @@ import {
     extractStyleProfileId,
     extractTranslationMemoryId,
     isString,
+    streamToBuffer,
     logInfo,
     resolveExtraBodyParameters,
     setExtraBodyParameters,
@@ -1289,16 +1293,17 @@ export class DeepLClient extends Translator {
      *
      * @param fileName: Name of the TMX file to import, for example 'legal.tmx'.
      * @param contentLength: Size of the TMX file in bytes.
-     * @param options: Optional contentType (defaults to 'application/xml') and displayName for the
-     * resulting translation memory (defaults to the file name).
+     * @param options: Optional contentType (defaults to 'application/xml'), displayName for the
+     * resulting translation memory (defaults to the file name) and extraBodyParameters, see
+     * {@link CreateTranslationMemoryImportOptions}.
      * @returns {Promise<TranslationMemoryImport>} The job ID and upload URL.
      *
      * @throws {DeepLError} If any error occurs while communicating with the DeepL API.
      */
     async createTranslationMemoryImport(
         fileName: string,
         contentLength: number,
-        options?: { contentType?: string; displayName?: string },
+        options?: CreateTranslationMemoryImportOptions,
     ): Promise<TranslationMemoryImport> {
         if (!fileName) {
             throw new ArgumentError('fileName must not be empty');
@@ -1322,7 +1327,7 @@ export class DeepLClient extends Translator {
         const { statusCode, content } = await this.httpClient.sendRequestWithBackoff<string>(
             'POST',
             '/v3/translation_memories/import',
-            { jsonBody },
+            { jsonBody: addExtraBodyParametersToJson(jsonBody, options) },
         );
 
         await checkStatusCode(statusCode, content);
@@ -1403,12 +1408,15 @@ export class DeepLClient extends Translator {
     /**
      * Retrieves the status of a translation memory import or export job.
      *
-     * @param jobId: ID of the job to query.
+     * @param job: ID of the job to query, or a TranslationMemoryJob object.
      * @returns {Promise<TranslationMemoryJob>} The current status of the job.
      *
      * @throws {DeepLError} If any error occurs while communicating with the DeepL API.
      */
-    async getTranslationMemoryJob(jobId: string): Promise<TranslationMemoryJob> {
+    async getTranslationMemoryJob(
+        job: string | TranslationMemoryJob,
+    ): Promise<TranslationMemoryJob> {
+        const jobId = typeof job === 'string' ? job : job?.jobId;
         if (!jobId) {
             throw new ArgumentError('jobId must not be empty');
         }
@@ -1422,30 +1430,31 @@ export class DeepLClient extends Translator {
     }
 
     /**
-     * Polls a translation memory job until it finishes, sleeping between requests, and resolves
-     * with the final status.
+     * Polls a translation memory job every 5 seconds until it completes, and resolves with the
+     * completed job.
      *
      * Note that an import job keeps reporting 'awaiting_input' for a while after its file has been
      * uploaded, because the API detects the upload asynchronously. That status, and statuses this
      * library does not know, are polled through. A job whose file is never uploaded does not finish
-     * on its own, so pass timeoutMs when that is a possibility.
+     * on its own, so set a timeout when that is a possibility.
      *
-     * @param jobId: ID of the job to wait for.
-     * @param timeoutMs: (Optional) Maximum time to wait in milliseconds before rejecting. Note that
-     * this is not accurate to the millisecond, as the job is only polled every 5 seconds.
-     * @returns {Promise<TranslationMemoryJob>} The job once it has finished.
+     * @param job: ID of the job to wait for, or a TranslationMemoryJob object.
+     * @param options: (Optional) WaitOptions with timeoutMs, or the timeout in milliseconds as a
+     * number: maximum time to wait before rejecting. Note that this is not accurate to the
+     * millisecond, as the job is only polled every 5 seconds.
+     * @returns {Promise<TranslationMemoryJob>} The completed job.
      *
-     * @throws {DeepLError} If the job fails, the timeout is exceeded, or any error occurs while
-     * communicating with the DeepL API.
+     * @throws {DeepLError} If the job fails or expires (with the job's error message), the timeout
+     * is exceeded, or any error occurs while communicating with the DeepL API.
      */
-    async isTranslationMemoryJobComplete(
-        jobId: string,
-        timeoutMs?: number,
+    async waitUntilTranslationMemoryJobDone(
+        job: string | TranslationMemoryJob,
+        options?: WaitOptions | number,
     ): Promise<TranslationMemoryJob> {
+        const timeoutMs = typeof options === 'number' ? options : options?.timeoutMs;
         const deadline = timeoutMs !== undefined ? Date.now() + timeoutMs : undefined;
-        let job = await this.getTranslationMemoryJob(jobId);
-        // Unknown statuses and a missing result are polled through; the timeout bounds the wait.
-        while (!DeepLClient.isJobFinished(job)) {
+        let current = await this.getTranslationMemoryJob(job);
+        while (!current.done() && current.ok()) {
             let sleepMs = 5000;
             if (deadline !== undefined) {
                 const remainingMs = deadline - Date.now();
@@ -1458,13 +1467,25 @@ export class DeepLClient extends Translator {
             }
             await timeout(sleepMs);
             logInfo(`Rechecking translation memory job status after sleeping for ${sleepMs} ms.`);
-            job = await this.getTranslationMemoryJob(jobId);
+            current = await this.getTranslationMemoryJob(current.jobId);
         }
-        const result = job.results[0];
-        if (result.status !== 'completed') {
-            throw new DeepLError(result.errorMessage || `Job ${result.status}`);
+        if (!current.ok()) {
+            throw new DeepLError(current.result?.errorMessage || `Job ${current.status}`);
         }
-        return job;
+        return current;
+    }
+
+    /**
+     * Polls a translation memory job until it completes, and resolves with the completed job.
+     *
+     * @deprecated Use {@link waitUntilTranslationMemoryJobDone} instead. Will be removed in the
+     * next major version.
+     */
+    async isTranslationMemoryJobComplete(
+        job: string | TranslationMemoryJob,
+        timeoutMs?: number | WaitOptions,
+    ): Promise<TranslationMemoryJob> {
+        return this.waitUntilTranslationMemoryJobDone(job, timeoutMs);
     }
 
     /**
@@ -1476,7 +1497,7 @@ export class DeepLClient extends Translator {
      * @throws {DeepLError} If the job has no download URL, or any error occurs while downloading.
      */
     async downloadTranslationMemoryExport(
-        job: TranslationMemoryJob,
+        job: Omit<TranslationMemoryJob, 'done' | 'ok'>,
         outputFile: string | fs.WriteStream,
     ): Promise<void> {
         const downloadUrl = job.results[0]?.downloadUrl;
@@ -1563,32 +1584,47 @@ export class DeepLClient extends Translator {
      * Note that the API detects the upload asynchronously, so the job keeps reporting
      * 'awaiting_input' for a while (usually well under a minute) before it completes.
      *
-     * @param inputPath: Path of the TMX file to import.
+     * @param input: Path of the TMX file to import, or a Buffer or ReadStream with its content.
      * @param options: Optional displayName for the resulting translation memory (defaults to the
-     * file name), contentType (defaults to 'application/xml'), and timeoutMs limiting how long to
-     * wait for the import to finish.
+     * file name), contentType (defaults to 'application/xml'), fileName (required for a Buffer or
+     * stream unless displayName is set), extraBodyParameters, and timeoutMs limiting how long to
+     * wait for the import to finish, see {@link ImportTranslationMemoryOptions}.
      * @returns {Promise<TranslationMemoryJob>} The completed import job; its result carries the
      * new translation memory ID.
      *
      * @throws {DeepLError} If the import fails, the timeout is exceeded, or any error occurs while
      * communicating with the DeepL API.
      */
     async importTranslationMemoryFromFilepath(
-        inputPath: string,
-        options?: { displayName?: string; contentType?: string; timeoutMs?: number },
+        input: string | Buffer | fs.ReadStream,
+        options?: ImportTranslationMemoryOptions,
     ): Promise<TranslationMemoryJob> {
-        const fileBuffer = await fs.promises.readFile(inputPath);
-        const created = await this.createTranslationMemoryImport(
-            path.basename(inputPath),
-            fileBuffer.length,
-            { displayName: options?.displayName, contentType: options?.contentType },
-        );
+        let fileBuffer: Buffer;
+        let fileName: string | undefined;
+        if (isString(input)) {
+            fileBuffer = await fs.promises.readFile(input);
+            fileName = options?.fileName ?? path.basename(input);
+        } else {
+            fileName = options?.fileName ?? options?.displayName;
+            if (!fileName) {
+                throw new ArgumentError(
+                    'options.fileName or options.displayName must be specified unless using an input file path',
+                );
+            }
+            fileBuffer = input instanceof fs.ReadStream ? await streamToBuffer(input) : input;
+        }
+        const created = await this.createTranslationMemoryImport(fileName, fileBuffer.length, {
+            displayName: options?.displayName,
+            contentType: options?.contentType,
+            extraBodyParameters: options?.extraBodyParameters,
+            extraRequestParameters: options?.extraRequestParameters,
+        });
         await this.uploadTranslationMemoryFile(
             created,
             fileBuffer,
             options?.contentType ?? 'application/xml',
         );
-        return this.isTranslationMemoryJobComplete(created.jobId, options?.timeoutMs);
+        return this.waitUntilTranslationMemoryJobDone(created.jobId, options);
     }
 
     /**
@@ -1597,7 +1633,8 @@ export class DeepLClient extends Translator {
      *
      * @param translationMemory: Translation memory ID, or TranslationMemoryInfo object.
      * @param outputFile: String containing output file path, or a WriteStream to store file data.
-     * @param options: Optional timeoutMs limiting how long to wait for the export to finish.
+     * @param options: Optional WaitOptions with timeoutMs limiting how long to wait for the export
+     * to finish.
      * @returns {Promise<TranslationMemoryJob>} The completed export job.
      *
      * @throws {DeepLError} If the export fails, the timeout is exceeded, or any error occurs while
@@ -1606,23 +1643,14 @@ export class DeepLClient extends Translator {
     async exportTranslationMemoryToFilepath(
         translationMemory: TranslationMemoryId | TranslationMemoryInfo,
         outputFile: string | fs.WriteStream,
-        options?: { timeoutMs?: number },
+        options?: WaitOptions,
     ): Promise<TranslationMemoryJob> {
         const created = await this.createTranslationMemoryExport(translationMemory);
-        const job = await this.isTranslationMemoryJobComplete(created.jobId, options?.timeoutMs);
+        const job = await this.waitUntilTranslationMemoryJobDone(created.jobId, options);
         await this.downloadTranslationMemoryExport(job, outputFile);
         return job;
     }
 
-    /**
-     * True once the job has completed, failed or expired.
-     * @private
-     */
-    private static isJobFinished(job: TranslationMemoryJob): boolean {
-        const status = job.results[0]?.status;
-        return status === 'completed' || status === 'failed' || status === 'expired';
-    }
-
     /**
      * Creates a new style rule.
      *

src/parsing.ts

@@ -1062,6 +1062,8 @@ export function parseTranslationMemoryJob(json: string): TranslationMemoryJob {
             translationMemoryId: result.translation_memory_id,
             skippedSegmentCount: result.skipped_segment_count,
         }));
+        const result = results[0];
+        const status = result?.status;
         return {
             jobId: obj.job_id,
             operation: (obj.operation ?? '') as 'import' | 'export',
@@ -1073,6 +1075,10 @@ export function parseTranslationMemoryJob(json: string): TranslationMemoryJob {
             displayName: obj.parameters?.display_name,
             sourceContentType: obj.source_file?.content_type,
             sourceContentLength: obj.source_file?.content_length,
+            result,
+            status,
+            done: () => status === 'completed',
+            ok: () => status !== 'failed' && status !== 'expired',
         };
     } catch (error) {
         throw new DeepLError(`Error parsing response JSON: ${error}`);