fix: URL-encode document IDs in request paths

The document status and download requests put the document ID into the
path unencoded.

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

Author: hive-bot

CHANGELOG.md

@@ -190,6 +190,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - An HTTP 503 response to `translateDocumentGetStatus()` and `getDocumentStatus()`
   now throws `DeepLError`; before it threw `DocumentNotReadyError`, which is meant
   for document downloads only.
+- The document ID is now URL-encoded in the request paths of the document
+  status and download methods.
 - `extraBodyParameters` (and `extraRequestParameters`) of `translateText()` and
   `uploadDocument()`/`translateDocument()` now replace every parameter of the same
   name set by the library. Before, parameters appended after the languages and

src/translator.ts

@@ -473,7 +473,7 @@ export class Translator {
         const data = new URLSearchParams({ document_key: handle.documentKey });
         const { statusCode, content } = await this.httpClient.sendRequestWithBackoff<string>(
             'POST',
-            `/v2/document/${handle.documentId}`,
+            `/v2/document/${encodeURIComponent(handle.documentId)}`,
             { data },
         );
         await checkStatusCode(statusCode, content);
@@ -751,7 +751,7 @@ export class Translator {
         const { statusCode, content } =
             await this.httpClient.sendRequestWithBackoff<IncomingMessage>(
                 'POST',
-                `/v2/document/${handle.documentId}/result`,
+                `/v2/document/${encodeURIComponent(handle.documentId)}/result`,
                 { data },
                 true,
             );

tests/offline/translateDocument.test.ts

@@ -219,6 +219,17 @@ describe('Translator.translateDocumentGetStatus', () => {
         expect([status.status, status.ok(), status.done()]).toEqual([expected, true, false]);
     });
 
+    it('URL-encodes the document ID in the path', async () => {
+        nock(serverUrl).post('/v2/document/a%2Fb%3F', keyBody).reply(200, { status: 'done' });
+
+        const status = await makeDeeplClient().translateDocumentGetStatus({
+            documentId: 'a/b?',
+            documentKey: handle.documentKey,
+        });
+
+        expect(status.done()).toBe(true);
+    });
+
     it('throws DeepLError, not DocumentNotReadyError, when the server answers 503', async () => {
         nock(serverUrl).post('/v2/document/doc-id').reply(503);
 
@@ -370,11 +381,14 @@ describe('Translator.downloadDocument', () => {
 });
 
 describe('Translator.translateDocumentDownload', () => {
-    it('sends the document key and streams the result to a file', async () => {
-        nock(serverUrl).post('/v2/document/doc-id/result', keyBody).reply(200, 'result');
+    it('sends the document key to the URL-encoded result path and writes the file', async () => {
+        nock(serverUrl).post('/v2/document/a%2Fb/result', keyBody).reply(200, 'result');
         const [, outputPath] = createTextDocument();
 
-        await makeDeeplClient().translateDocumentDownload(handle, outputPath);
+        await makeDeeplClient().translateDocumentDownload(
+            { documentId: 'a/b', documentKey: handle.documentKey },
+            outputPath,
+        );
 
         expect(fs.readFileSync(outputPath, 'utf8')).toBe('result');
     });