feat: streaming upload, populated task.type, new postStream API (2.1.0)

- FilesAPI.upload streams chunked multipart instead of buffering the entire
  file in memory (eliminates the ~200 MB OOM cliff)
- HttpClient.postStream: new public method for streaming POSTs (no retry
  because consumed ReadableStream bodies cannot be replayed)
- client.getTask now uses response.type from /v1/tasks/{id} (api 1.38.5+);
  falls back to "" on older deployments
- TaskStatusResponse.type? added to the public types
- New named exports: buildMultipartStream, sanitizeFilename
- Upload retries no longer happen on transient network errors (stream bodies
  can't be replayed); non-upload operations retain retry behaviour
- 12 new streaming tests (90 total, all passing)
- Minor bump: additive public API + behaviour change in upload retry semantics

Author: drdmitry

CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to the `conversiontools` package are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Release announcements with extended notes also live at
+<https://github.com/conversiontools/conversiontools-node/releases>.
+
+## [Unreleased]
+
+## [2.1.0] - 2026-05-20
+
+### Added
+- **Streaming upload.** `FilesAPI.upload()` now sends the file as a chunked
+  `multipart/form-data` body and no longer buffers the entire payload in memory.
+  Safe for arbitrarily large files; eliminates the OOM cliff previous versions
+  hit at ~200 MB.
+- `HttpClient.postStream(path, body, contentType, extraHeaders?)` — new public
+  method for streaming POSTs. Skips the retry wrapper because a consumed
+  `ReadableStream` body cannot be replayed.
+- New named exports: `buildMultipartStream`, `sanitizeFilename`.
+- Optional `type?: string` field on `TaskStatusResponse` to match the new API
+  response shape (api 1.38.5+).
+
+### Fixed
+- `client.getTask(id)` no longer hardcodes `task.type = ""`. When the API
+  returns `type` (api 1.38.5+), it is populated on the returned `Task`
+  instance. Older API deployments still fall back to `""`.
+
+### Changed
+- Upload retries: prior versions could retry an upload up to 3 times after
+  transient network failures because the body was a fully-buffered `FormData`.
+  Streamed uploads cannot be replayed, so a failed upload now surfaces the
+  error immediately. Non-upload operations retain the existing retry behaviour
+  (3 retries, exponential backoff on 408/500/502/503/504).
+
+### Notes
+- 12 new tests cover streaming behaviour: binary byte preservation, chunk
+  boundaries, large-input streaming (no buffering), source-stream error
+  propagation, sanitized filename, multipart envelope structure.
+
+## [2.0.4] - 2026-03-31
+
+### Changed
+- Update dependencies (minimatch, rollup, flatted, picomatch).
+
+## [2.0.3] - 2026-02-21
+
+### Added
+- `onProgress` callback in `downloadTo()` — track download progress with
+  `loaded`, `total`, `percent` events.
+- `onDownloadProgress` config option now wired through `convert()` →
+  `task.downloadTo()`.
+
+### Fixed
+- SDK version in the `User-Agent` header is now injected at build time from
+  `package.json` (previously hardcoded as `2.0.0`).
+
+## [2.0.2] - 2026-02-21
+
+### Added
+- Config option to override the User-Agent.
+
+## [2.0.1] - 2025-12-02
+
+### Changed
+- Dependency bumps (glob and others).
+
+## [2.0.0] - 2025-11-12
+
+### Added
+- Complete rewrite with full TypeScript support (typed methods + options).
+- Native ESM + CommonJS dual module support.
+- Streaming download via `task.downloadStream()` / `task.downloadTo()`.
+- Real-time progress callbacks (upload, conversion, download).
+- Smart retry with exponential backoff for transient failures.
+- Modern stack: native `fetch`, Node 18+, zero heavy dependencies.
+- Webhook support for async task completion notifications.
+- Sandbox mode (`sandbox: true`) for testing without consuming quota.
+- Typed error classes for specific failure modes.
+
+[Unreleased]: https://github.com/conversiontools/conversiontools-node/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/conversiontools/conversiontools-node/compare/v2.0.4...v2.1.0
+[2.0.4]: https://github.com/conversiontools/conversiontools-node/compare/v2.0.3...v2.0.4
+[2.0.3]: https://github.com/conversiontools/conversiontools-node/compare/v2.0.2...v2.0.3
+[2.0.2]: https://github.com/conversiontools/conversiontools-node/compare/v2.0.1...v2.0.2
+[2.0.1]: https://github.com/conversiontools/conversiontools-node/compare/v2.0.0...v2.0.1
+[2.0.0]: https://github.com/conversiontools/conversiontools-node/releases/tag/v2.0.0

dist/index.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var crypto = require('crypto');
 var fs = require('fs');
 var path = require('path');
 var stream = require('stream');
@@ -339,6 +340,69 @@ var HttpClient = class {
       ...options
     });
   }
+  /**
+   * POST a streaming body (e.g. multipart upload).
+   *
+   * Bypasses the retry wrapper because a consumed ReadableStream cannot be
+   * replayed. Use this for chunked uploads where buffering the whole body
+   * in memory is unacceptable.
+   */
+  async postStream(path2, body, contentType, extraHeaders) {
+    const url = `${this.config.baseURL}${path2}`;
+    const headers = {
+      Authorization: `Bearer ${this.config.apiToken}`,
+      "Content-Type": contentType,
+      ...extraHeaders
+    };
+    if (this.config.userAgent) {
+      headers["User-Agent"] = this.config.userAgent;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(
+      () => controller.abort(),
+      this.config.timeout
+    );
+    try {
+      let response;
+      try {
+        response = await fetch(url, {
+          method: "POST",
+          headers,
+          body,
+          signal: controller.signal,
+          // `duplex: "half"` is required by fetch for streaming request bodies
+          duplex: "half"
+        });
+      } catch (error) {
+        if (error.name === "AbortError") {
+          throw new TimeoutError(
+            `Request timed out after ${this.config.timeout}ms`,
+            this.config.timeout
+          );
+        }
+        throw new NetworkError(
+          `Network request failed: ${error.message}`,
+          error
+        );
+      }
+      this.extractRateLimits(response.headers);
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+      const data = await response.json();
+      if (data.error) {
+        throw new ConversionToolsError(
+          data.error,
+          "API_ERROR",
+          response.status,
+          data
+        );
+      }
+      return data;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
 };
 
 // src/utils/validation.ts
@@ -449,7 +513,10 @@ var FilesAPI = class {
     this.http = http;
   }
   /**
-   * Upload a file from various sources
+   * Upload a file from various sources.
+   *
+   * Streams the upload chunked to the API — never buffers the entire file
+   * in memory. Safe for arbitrarily large inputs.
    */
   async upload(input, options) {
     let stream$1;
@@ -475,20 +542,24 @@ var FilesAPI = class {
     if (options?.onProgress) {
       stream$1 = trackStreamProgress(stream$1, options.onProgress, fileSize);
     }
-    const formData = new FormData();
-    const chunks = [];
-    for await (const chunk of stream$1) {
-      if (typeof chunk === "string") {
-        chunks.push(new TextEncoder().encode(chunk));
-      } else if (chunk instanceof Buffer) {
-        chunks.push(new Uint8Array(chunk));
-      } else {
-        chunks.push(chunk);
-      }
-    }
-    const blob = new Blob(chunks);
-    formData.append("file", blob, filename || "file");
-    const response = await this.http.post("/files", formData);
+    const boundary = `----conversiontools-${crypto.randomUUID()}`;
+    const head = Buffer.from(
+      `--${boundary}\r
+Content-Disposition: form-data; name="file"; filename="${sanitizeFilename(filename || "file")}"\r
+Content-Type: application/octet-stream\r
+\r
+`,
+      "utf8"
+    );
+    const tail = Buffer.from(`\r
+--${boundary}--\r
+`, "utf8");
+    const body = buildMultipartStream(head, stream$1, tail);
+    const response = await this.http.postStream(
+      "/files",
+      body,
+      `multipart/form-data; boundary=${boundary}`
+    );
     if (response.error) {
       throw new ValidationError(response.error);
     }
@@ -569,6 +640,30 @@ var FilesAPI = class {
     return filename;
   }
 };
+function buildMultipartStream(head, source, tail) {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(new Uint8Array(head));
+      source.on("data", (chunk) => {
+        const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        controller.enqueue(new Uint8Array(buf));
+      });
+      source.on("end", () => {
+        controller.enqueue(new Uint8Array(tail));
+        controller.close();
+      });
+      source.on("error", (err) => {
+        controller.error(err);
+      });
+    },
+    cancel() {
+      source.destroy?.();
+    }
+  });
+}
+function sanitizeFilename(name) {
+  return name.replace(/[\r\n"\\]/g, "_");
+}
 
 // src/api/tasks.ts
 var TasksAPI = class {
@@ -849,7 +944,7 @@ var Task = class {
 };
 
 // src/client.ts
-var VERSION = "2.0.4";
+var VERSION = "2.1.0";
 var ConversionToolsClient = class {
   constructor(config) {
     validateApiToken(config.apiToken);
@@ -977,8 +1072,7 @@ var ConversionToolsClient = class {
     return new Task(
       {
         id: taskId,
-        type: "",
-        // Type not available from status response
+        type: response.type ?? "",
         status: response.status,
         fileId: response.file_id,
         error: response.error,

dist/index.cjs.map

@@ -538,6 +538,8 @@ interface WaitOptions {
  */
 interface TaskStatusResponse {
     error: string | null;
+    /** Conversion type (added in API 1.38.5; absent on older deployments) */
+    type?: string;
     status: TaskStatus;
     file_id: string | null;
     conversionProgress: number;
@@ -658,6 +660,14 @@ declare class HttpClient {
      * Make a POST request
      */
     post<T = any>(path: string, body?: any, options?: Partial<RequestOptions>): Promise<T>;
+    /**
+     * POST a streaming body (e.g. multipart upload).
+     *
+     * Bypasses the retry wrapper because a consumed ReadableStream cannot be
+     * replayed. Use this for chunked uploads where buffering the whole body
+     * in memory is unacceptable.
+     */
+    postStream<T = any>(path: string, body: ReadableStream<Uint8Array>, contentType: string, extraHeaders?: Record<string, string>): Promise<T>;
 }
 
 /**
@@ -682,7 +692,10 @@ declare class FilesAPI {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Upload a file from various sources
+     * Upload a file from various sources.
+     *
+     * Streams the upload chunked to the API — never buffers the entire file
+     * in memory. Safe for arbitrarily large inputs.
      */
     upload(input: string | NodeJS.ReadableStream | Buffer, options?: FileUploadOptions): Promise<string>;
     /**

dist/index.d.cts

@@ -538,6 +538,8 @@ interface WaitOptions {
  */
 interface TaskStatusResponse {
     error: string | null;
+    /** Conversion type (added in API 1.38.5; absent on older deployments) */
+    type?: string;
     status: TaskStatus;
     file_id: string | null;
     conversionProgress: number;
@@ -658,6 +660,14 @@ declare class HttpClient {
      * Make a POST request
      */
     post<T = any>(path: string, body?: any, options?: Partial<RequestOptions>): Promise<T>;
+    /**
+     * POST a streaming body (e.g. multipart upload).
+     *
+     * Bypasses the retry wrapper because a consumed ReadableStream cannot be
+     * replayed. Use this for chunked uploads where buffering the whole body
+     * in memory is unacceptable.
+     */
+    postStream<T = any>(path: string, body: ReadableStream<Uint8Array>, contentType: string, extraHeaders?: Record<string, string>): Promise<T>;
 }
 
 /**
@@ -682,7 +692,10 @@ declare class FilesAPI {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Upload a file from various sources
+     * Upload a file from various sources.
+     *
+     * Streams the upload chunked to the API — never buffers the entire file
+     * in memory. Safe for arbitrarily large inputs.
      */
     upload(input: string | NodeJS.ReadableStream | Buffer, options?: FileUploadOptions): Promise<string>;
     /**