feat: type DocumentStatus.documentId and TranslationMemoryJob times as required

The API always returns document_id in the document status response and
creation_time and updated_time in a translation memory job. A missing or
malformed value gives an empty documentId or an invalid Date instead of
undefined, never a throw. downloadTranslationMemoryExport() still accepts
a job without the timestamps.

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

Author: hive-bot

CHANGELOG.md

@@ -37,8 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `translateDocumentUpload()`, `translateDocumentGetStatus()` and
   `translateDocumentDownload()`, which replace `uploadDocument()`,
   `getDocumentStatus()` and `downloadDocument()` and behave the same.
-- Added `documentId` to `DocumentStatus`, parsed from the response field
-  `document_id`; `undefined` when absent or not a string.
+- Added `documentId` to `DocumentStatus`, parsed from the required response
+  field `document_id`.
 - Added the `timeoutMs` option to `DocumentTranslateOptions`: the maximum time
   `translateDocument()` waits for the translation between upload and download.
   When it expires, `translateDocument()` rejects with a `DocumentTranslationError`.
@@ -176,6 +176,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   as a glossary ID.
 
 ### Changed
+- `TranslationMemoryJob.creationTime` and `updatedTime` are typed as required
+  `Date`, as the API always returns them.
 - `translateText()` accepts the `glossary` and `glossaryIds` options without a
   source language; the API detects the source language and uses the glossary's
   dictionary for the detected language pair. Document translation with a

src/deeplClient.ts

@@ -1528,7 +1528,7 @@ export class DeepLClient extends Translator {
      * never one of its subclasses.
      */
     async downloadTranslationMemoryExport(
-        job: Omit<TranslationMemoryJob, 'done' | 'ok'>,
+        job: Omit<TranslationMemoryJob, 'done' | 'ok' | 'creationTime' | 'updatedTime'>,
         outputFile: string | fs.WriteStream,
     ): Promise<void> {
         const downloadUrl = job.results[0]?.downloadUrl;

src/parsing.ts

@@ -292,14 +292,14 @@ class DocumentStatusImpl implements DocumentStatus {
     public secondsRemaining?: number;
     public billedCharacters?: number;
     public errorMessage?: string;
-    public documentId?: string;
+    public documentId: string;
 
     constructor(
         status: DocumentStatusCode,
+        documentId: string,
         secondsRemaining?: number,
         billedCharacters?: number,
         errorMessage?: string,
-        documentId?: string,
     ) {
         this.status = status;
         this.secondsRemaining = secondsRemaining;
@@ -542,10 +542,11 @@ export function parseDocumentStatus(json: string): DocumentStatus {
         const obj = JSON.parse(json) as DocumentStatusApiResponse;
         return new DocumentStatusImpl(
             obj.status as DocumentStatusCode,
+            // Required on the wire; a missing or malformed value gives '', never a throw
+            parseOptionalString(obj.document_id) ?? '',
             obj.seconds_remaining,
             obj.billed_characters,
             obj.error_message,
-            parseOptionalString(obj.document_id),
         );
     } catch (error) {
         throw new DeepLError(`Error parsing response JSON: ${error}`);
@@ -1062,8 +1063,9 @@ export function parseTranslationMemoryJob(json: string): TranslationMemoryJob {
             operation: (obj.operation ?? '') as 'import' | 'export',
             product: obj.product ?? 'translation_memory',
             results,
-            creationTime: parseOptionalTimestamp(obj.creation_time),
-            updatedTime: parseOptionalTimestamp(obj.updated_time),
+            // Required on the wire; a missing or malformed value gives an invalid Date, never a throw
+            creationTime: new Date(parseOptionalString(obj.creation_time) ?? NaN),
+            updatedTime: new Date(parseOptionalString(obj.updated_time) ?? NaN),
             translationMemoryId: obj.parameters?.translation_memory_id,
             displayName: obj.parameters?.display_name,
             sourceContentType: obj.source_file?.content_type,

src/types.ts

@@ -835,9 +835,9 @@ export interface WaitOptions {
  */
 export interface DocumentStatus {
     /**
-     * ID of the document, or undefined if the response does not contain it.
+     * ID of the document.
      */
-    readonly documentId?: string;
+    readonly documentId: string;
 
     /**
      * One of the status values defined in DocumentStatusCode.
@@ -1309,8 +1309,10 @@ export interface TranslationMemoryJob {
     readonly product: string;
     /** Results of the job; the API returns exactly one. */
     readonly results: TranslationMemoryJobResult[];
-    readonly creationTime?: Date;
-    readonly updatedTime?: Date;
+    /** Time the job was created. */
+    readonly creationTime: Date;
+    /** Time the job was last updated. */
+    readonly updatedTime: Date;
     /** Translation memory an export job reads from. */
     readonly translationMemoryId?: string;
     /** Display name an import job assigns to the new translation memory. */

tests/offline/translateDocument.test.ts

@@ -222,14 +222,14 @@ describe('Translator.translateDocumentGetStatus', () => {
         ]);
     });
 
-    it('leaves documentId undefined when document_id is not a string', async () => {
+    it('gives an empty documentId when document_id is not a string', async () => {
         nock(serverUrl)
             .post('/v2/document/doc-id', keyBody)
             .reply(200, { document_id: 42, status: 'done', billed_characters: 11 });
 
         const status = await makeDeeplClient().translateDocumentGetStatus(handle);
 
-        expect(status.documentId).toBeUndefined();
+        expect(status.documentId).toBe('');
         expect([status.done(), status.billedCharacters]).toEqual([true, 11]);
     });
 

tests/offline/translationMemories.test.ts

@@ -29,6 +29,8 @@ function jobReply(status: string, extra: Record<string, unknown> = {}) {
         job_id: 'job-1',
         operation: 'import',
         product: 'translation_memory',
+        creation_time: '2025-01-02T03:04:05Z',
+        updated_time: '2025-01-03T03:04:05Z',
         results: [{ status, ...extra }],
     };
 }
@@ -314,7 +316,12 @@ describe('DeepLClient.getTranslationMemoryJob', () => {
 
         const job = await makeDeeplClient().getTranslationMemoryJob('job-1');
 
-        expect(job).toMatchObject({ jobId: 'job-1', operation: 'import' });
+        expect(job).toMatchObject({
+            jobId: 'job-1',
+            operation: 'import',
+            creationTime: new Date('2025-01-02T03:04:05Z'),
+            updatedTime: new Date('2025-01-03T03:04:05Z'),
+        });
         expect(job.results).toEqual([
             {
                 status: 'completed',
@@ -379,6 +386,21 @@ describe('DeepLClient.getTranslationMemoryJob', () => {
         ]);
     });
 
+    it('gives an invalid Date for a missing or malformed creation or update time', async () => {
+        const { updated_time: updatedTime, ...withoutUpdatedTime } = jobReply('processing');
+        void updatedTime;
+        nock(serverUrl)
+            .get('/v3/translation_memories/jobs/job-1')
+            .reply(200, { ...withoutUpdatedTime, creation_time: 'not a timestamp' });
+
+        const job = await makeDeeplClient().getTranslationMemoryJob('job-1');
+
+        expect(job.creationTime).toBeInstanceOf(Date);
+        expect(job.creationTime.getTime()).toBeNaN();
+        expect(job.updatedTime).toBeInstanceOf(Date);
+        expect(job.updatedTime.getTime()).toBeNaN();
+    });
+
     it('throws ArgumentError when the job ID is empty', async () => {
         await expect(makeDeeplClient().getTranslationMemoryJob('')).rejects.toThrow(
             deepl.ArgumentError,
@@ -472,7 +494,10 @@ describe('DeepLClient.createTranslationMemoryExport', () => {
 });
 
 describe('DeepLClient.downloadTranslationMemoryExport', () => {
-    const job = (downloadUrl?: string): Omit<deepl.TranslationMemoryJob, 'done' | 'ok'> => ({
+    // A hand-built job without done(), ok() or the timestamps, as callers may pass one
+    const job = (
+        downloadUrl?: string,
+    ): Omit<deepl.TranslationMemoryJob, 'done' | 'ok' | 'creationTime' | 'updatedTime'> => ({
         jobId: 'job-2',
         operation: 'export',
         product: 'translation_memory',