unstructured-transform-client 0.18.27 → 0.18.28

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.18.28
+
+- Add a 60 second per-request timeout for ordinary requests, with per-client
+  and per-call overrides.
+- Keep `GET` and `DELETE` retryable after a timeout while preserving the
+  non-idempotent `POST` rule: writes are not retried after a timeout because
+  the service may have received them.
+- Ask Node's default fetch to close `POST` connections so non-idempotent
+  submits do not reuse stale pooled sockets.
+- Keep `jobs.stream` long-lived; callers still stop it with an `AbortSignal`.

package/README.md

@@ -32,6 +32,19 @@ naming `UNSTRUCTURED_API_KEY`.
 
 Requires Node 22 or newer, for native `fetch` and `FormData`.
 
+Ordinary request/response calls have a 60 second per-request timeout. Override
+it per client or per call with `timeoutMs`:
+
+```ts
+const client = new TransformClient({ timeoutMs: 120_000 });
+await client.jobs.get(jobId, { timeoutMs: 30_000 });
+```
+
+`jobs.stream` is long-lived and opts out of the SDK request timeout, including
+the initial connection. Pass an `AbortSignal` when you want to stop it.
+Large uploads and downloads also share the same 60 second default; raise
+`timeoutMs` for slow links.
+
 ## The three flows
 
 **Parse a document.**
@@ -164,6 +177,17 @@ connection or a DNS failure. A read timeout or a `5xx` on a write is not
 retried, because the service may have acted on it already and a second attempt
 could duplicate the effect.
 
+The retry budget is separate from the in-flight request timeout, so a timed-out
+`GET` or `DELETE` still gets its configured retry attempts while total backoff
+time remains bounded. With the default policy, three 60 second attempts are
+allowed.
+
+When the SDK uses Node's default `fetch`, non-idempotent `POST` requests include
+`Connection: close` so the server closes the connection after the response. This
+limits reuse after a write, but it cannot guarantee which pooled socket Node
+selects for the current request. If you provide `fetchApi`, the SDK leaves
+connection management to that implementation.
+
 ## Documents need a filename
 
 Pass a `File`, or `{ data, filename }`. A bare `Blob` is refused:

package/dist/client.d.ts

@@ -38,9 +38,15 @@ export interface TransformClientOptions {
     userAgentSuffix?: string;
     /** Override the fetch implementation, e.g. for tests or a proxy agent. */
     fetchApi?: typeof fetch;
+    /** Per-request timeout for ordinary request/response calls. Defaults to 60s. */
+    timeoutMs?: number;
     /** Per-client retries; pass `false` to disable them. */
     retries?: RetryConfig | false;
 }
+export interface RequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
 export declare class TransformClient {
     readonly parse: ParseNamespace;
     readonly extract: ExtractNamespace;
@@ -50,10 +56,11 @@ export declare class TransformClient {
     /** @internal */ readonly requestHeaders: Record<string, string>;
     /** @internal */ readonly configuration: Configuration;
     /** @internal */ readonly fetchApi?: typeof fetch;
+    /** @internal */ readonly timeoutMs: number;
     /** @internal */ readonly retries: Required<RetryConfig> | undefined;
     constructor(options?: TransformClientOptions);
 }
-export interface ParseOptions {
+export interface ParseOptions extends RequestOptions {
     input?: FileInput;
     fileId?: string;
     schema?: Record<string, unknown> | string;
@@ -75,13 +82,13 @@ declare class ParseNamespace {
      */
     run(options: ParseOptions): Promise<Outcome<ParseResult>>;
 }
-export interface ExtractOptions {
+export interface ExtractOptions extends RequestOptions {
     parseId: string;
     schema: Record<string, unknown>;
     prompt?: string;
     waitSeconds?: number;
 }
-export interface ExtractFromDocumentOptions {
+export interface ExtractFromDocumentOptions extends RequestOptions {
     input?: FileInput;
     fileId?: string;
     /** The original filename to attach when extracting from an already-uploaded file. */
@@ -104,11 +111,11 @@ declare class ExtractNamespace {
      */
     fromDocument(options: ExtractFromDocumentOptions): Promise<Outcome<ParseResult>>;
 }
-export interface JobsGetOptions {
+export interface JobsGetOptions extends RequestOptions {
     output?: OutputFormat;
     include?: string[];
 }
-export interface JobsListOptions {
+export interface JobsListOptions extends RequestOptions {
     cursor?: string;
     limit?: number;
     status?: JobStatus;
@@ -125,8 +132,8 @@ declare class JobsNamespace {
     get(jobId: string, options?: JobsGetOptions): Promise<JobResult>;
     list(options?: JobsListOptions): Promise<JobPage>;
     iterate(options?: JobsListOptions): AsyncGenerator<JobPage["jobs"][number], void, undefined>;
-    cancel(jobId: string): Promise<JobResult>;
-    delete(jobId: string): Promise<void>;
+    cancel(jobId: string, options?: RequestOptions): Promise<JobResult>;
+    delete(jobId: string, options?: RequestOptions): Promise<void>;
     /**
      * Progress events for a running job, as they happen.
      *
@@ -139,8 +146,8 @@ declare class JobsNamespace {
 declare class UploadNamespace {
     private readonly client;
     constructor(client: TransformClient);
-    run(input: FileInput): Promise<UploadResult>;
-    get(fileId: string): Promise<Blob>;
-    delete(fileId: string): Promise<void>;
+    run(input: FileInput, options?: RequestOptions): Promise<UploadResult>;
+    get(fileId: string, options?: RequestOptions): Promise<Blob>;
+    delete(fileId: string, options?: RequestOptions): Promise<void>;
 }
 export {};

package/dist/client.js

@@ -29,7 +29,7 @@ import { asFile } from "./files.js";
 import * as hostHeaders from "./hostHeaders.js";
 import { postMultipart } from "./multipart.js";
 import { resolveOutcome } from "./outcome.js";
-import { fetchWithRetries, normalizeRetries } from "./retry.js";
+import { DEFAULT_TIMEOUT_MS, fetchWithRetries, normalizeRetries, } from "./retry.js";
 import { streamJobEvents } from "./sse.js";
 export const DEFAULT_SERVER_URL = "https://transform.unstructured.io";
 /** Matches the service's `securitySchemes`; see openapi.yaml. */
@@ -51,6 +51,7 @@ export class TransformClient {
     /** @internal */ requestHeaders;
     /** @internal */ configuration;
     /** @internal */ fetchApi;
+    /** @internal */ timeoutMs;
     /** @internal */ retries;
     constructor(options = {}) {
         const apiKey = options.apiKey ??
@@ -64,7 +65,8 @@ export class TransformClient {
         }
         this.serverUrl = (options.serverUrl ?? DEFAULT_SERVER_URL).replace(/\/+$/, "");
         this.fetchApi = options.fetchApi;
-        this.retries = normalizeRetries(options.retries);
+        this.timeoutMs = validateTimeoutMs(options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        this.retries = normalizeRetries(options.retries, this.timeoutMs);
         const auth = hasApiKey
             ? { [API_KEY_HEADER]: apiKey }
             : { Authorization: `Bearer ${options.bearerToken}` };
@@ -84,6 +86,7 @@ export class TransformClient {
                 url: String(url),
                 init: init ?? {},
                 fetchApi: options.fetchApi,
+                timeoutMs: this.timeoutMs,
             }),
         });
         this.parse = new ParseNamespace(this);
@@ -96,6 +99,21 @@ export class TransformClient {
 function prefer(waitSeconds) {
     return waitSeconds === undefined ? undefined : `wait=${waitSeconds}`;
 }
+function requestInit(options) {
+    const init = {};
+    if (options.signal !== undefined)
+        init.signal = options.signal;
+    if (options.timeoutMs !== undefined) {
+        init.timeoutMs = validateTimeoutMs(options.timeoutMs);
+    }
+    return init.signal !== undefined || init.timeoutMs !== undefined ? init : undefined;
+}
+function validateTimeoutMs(timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new RangeError("timeoutMs must be a positive finite number of milliseconds");
+    }
+    return timeoutMs;
+}
 class ParseNamespace {
     client;
     constructor(client) {
@@ -125,7 +143,7 @@ class ParseNamespace {
                 : options.schema,
             prompt: options.prompt,
             profile: options.profile,
-        }));
+        }, requestInit(options)));
     }
 }
 class ExtractNamespace {
@@ -142,7 +160,7 @@ class ExtractNamespace {
                 prompt: options.prompt,
             },
             prefer: prefer(options.waitSeconds),
-        }));
+        }, requestInit(options)));
     }
     /**
      * Extract directly from a raw document, in one call.
@@ -174,6 +192,8 @@ class ExtractNamespace {
                 profile: options.profile,
             },
             waitSeconds: options.waitSeconds,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs === undefined ? undefined : validateTimeoutMs(options.timeoutMs),
             fromJSON: ParseResultFromJSON,
         });
     }
@@ -188,7 +208,7 @@ class JobsNamespace {
             jobId,
             output: options.output,
             include: options.include,
-        });
+        }, requestInit(options));
     }
     async list(options = {}) {
         return new JobsApi(this.client.configuration).jobsList({
@@ -196,7 +216,7 @@ class JobsNamespace {
             limit: options.limit,
             status: options.status,
             operation: options.operation,
-        });
+        }, requestInit(options));
     }
     async *iterate(options = {}) {
         let cursor = options.cursor;
@@ -210,11 +230,11 @@ class JobsNamespace {
                 return;
         }
     }
-    async cancel(jobId) {
-        return new JobsApi(this.client.configuration).jobsCancel({ jobId });
+    async cancel(jobId, options = {}) {
+        return new JobsApi(this.client.configuration).jobsCancel({ jobId }, requestInit(options));
     }
-    async delete(jobId) {
-        await new JobsApi(this.client.configuration).jobsDelete({ jobId });
+    async delete(jobId, options = {}) {
+        await new JobsApi(this.client.configuration).jobsDelete({ jobId }, requestInit(options));
     }
     /**
      * Progress events for a running job, as they happen.
@@ -240,6 +260,7 @@ class JobsNamespace {
             signal: options.signal,
             fetchApi: this.client.fetchApi,
             retries: this.client.retries,
+            timeoutMs: null,
         });
     }
 }
@@ -248,13 +269,13 @@ class UploadNamespace {
     constructor(client) {
         this.client = client;
     }
-    async run(input) {
-        return new UploadApi(this.client.configuration).uploadRun({ file: asFile(input) });
+    async run(input, options = {}) {
+        return new UploadApi(this.client.configuration).uploadRun({ file: asFile(input) }, requestInit(options));
     }
-    async get(fileId) {
-        return new UploadApi(this.client.configuration).uploadGet({ fileId });
+    async get(fileId, options = {}) {
+        return new UploadApi(this.client.configuration).uploadGet({ fileId }, requestInit(options));
     }
-    async delete(fileId) {
-        await new UploadApi(this.client.configuration).uploadDelete({ fileId });
+    async delete(fileId, options = {}) {
+        await new UploadApi(this.client.configuration).uploadDelete({ fileId }, requestInit(options));
     }
 }

package/dist/index.d.ts

@@ -13,8 +13,8 @@
  * response types this SDK returns, so a caller needs to be able to name them.
  */
 export { DEFAULT_SERVER_URL, TransformClient } from "./client.js";
-export type { ExtractFromDocumentOptions, ExtractOptions, JobsGetOptions, JobsListOptions, JobsStreamOptions, ParseOptions, TransformClientOptions, } from "./client.js";
-export type { RetryConfig } from "./retry.js";
+export type { ExtractFromDocumentOptions, ExtractOptions, JobsGetOptions, JobsListOptions, JobsStreamOptions, ParseOptions, RequestOptions, TransformClientOptions, } from "./client.js";
+export { RequestTimeoutError, type RetryConfig } from "./retry.js";
 export { isTerminal, type JobEvent } from "./sse.js";
 export { asFile, type FileInput } from "./files.js";
 export { isAccepted, type Outcome } from "./outcome.js";

package/dist/index.js

@@ -13,6 +13,7 @@
  * response types this SDK returns, so a caller needs to be able to name them.
  */
 export { DEFAULT_SERVER_URL, TransformClient } from "./client.js";
+export { RequestTimeoutError } from "./retry.js";
 export { isTerminal } from "./sse.js";
 export { asFile } from "./files.js";
 export { isAccepted } from "./outcome.js";

package/dist/multipart.d.ts

@@ -35,6 +35,8 @@ export interface MultipartRequest<TResult> {
     filename?: string;
     fields: Record<string, string | undefined>;
     waitSeconds?: number;
+    signal?: AbortSignal;
+    timeoutMs?: number;
     /**
      * The generated mapper for the 200 body.
      *

package/dist/multipart.js

@@ -47,10 +47,12 @@ export async function postMultipart(client, request) {
     const response = await fetchWithRetries(client.retries, {
         url: `${client.serverUrl}${request.path}`,
         fetchApi: client.fetchApi,
+        timeoutMs: request.timeoutMs ?? client.timeoutMs,
         init: {
             method: "POST",
             headers,
             body: form,
+            signal: request.signal,
         },
     });
     if (!response.ok) {

package/dist/retry.d.ts

@@ -3,6 +3,10 @@ export interface RetryConfig {
     maxAttempts?: number;
     initialDelayMs?: number;
     maxDelayMs?: number;
+    /**
+     * Total retry budget, excluding the time spent waiting for each in-flight
+     * request to answer or hit its own timeout.
+     */
     maxElapsedMs?: number;
     retryAfterMaxMs?: number;
 }
@@ -10,7 +14,19 @@ export interface RetryRequest {
     url: string;
     init: RequestInit;
     fetchApi?: typeof fetch;
+    /**
+     * Per-request timeout. `null` means no SDK timeout, which is used by the
+     * long-lived SSE stream after the initial request is accepted.
+     */
+    timeoutMs?: number | null;
 }
 export type RetryOption = RetryConfig | false | undefined;
-export declare function normalizeRetries(retries: RetryOption): Required<RetryConfig> | undefined;
+export declare const DEFAULT_TIMEOUT_MS = 60000;
+export declare class RequestTimeoutError extends Error {
+    name: string;
+    readonly timeoutMs: number;
+    cause?: unknown;
+    constructor(timeoutMs: number, cause?: unknown);
+}
+export declare function normalizeRetries(retries: RetryOption, timeoutMs?: number): Required<RetryConfig> | undefined;
 export declare function fetchWithRetries(retries: Required<RetryConfig> | undefined, request: RetryRequest): Promise<Response>;

package/dist/retry.js

@@ -1,9 +1,10 @@
 /** Retry policy for the hand-written SDK facade. */
+export const DEFAULT_TIMEOUT_MS = 60000;
 const DEFAULT_RETRIES = {
     maxAttempts: 3,
     initialDelayMs: 250,
     maxDelayMs: 2000,
-    maxElapsedMs: 10000,
+    maxElapsedMs: 3 * DEFAULT_TIMEOUT_MS,
     retryAfterMaxMs: 2000,
 };
 // Errors that prove the request never left this process, identified by their
@@ -32,38 +33,60 @@ const BEFORE_SEND_CODES = new Set([
 ]);
 const SAFE_METHODS = new Set(["GET", "DELETE"]);
 const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
-export function normalizeRetries(retries) {
+export class RequestTimeoutError extends Error {
+    name = "TimeoutError";
+    timeoutMs;
+    cause;
+    constructor(timeoutMs, cause) {
+        super(`request timed out after ${timeoutMs}ms`);
+        this.timeoutMs = timeoutMs;
+        this.cause = cause;
+    }
+}
+export function normalizeRetries(retries, timeoutMs = DEFAULT_TIMEOUT_MS) {
     if (retries === false)
         return undefined;
-    return { ...DEFAULT_RETRIES, ...(retries ?? {}) };
+    const defaults = {
+        ...DEFAULT_RETRIES,
+        maxElapsedMs: Math.max(DEFAULT_RETRIES.maxElapsedMs, DEFAULT_RETRIES.maxAttempts * timeoutMs),
+    };
+    return { ...defaults, ...(retries ?? {}) };
 }
 export async function fetchWithRetries(retries, request) {
     const fetchApi = request.fetchApi ?? fetch;
+    const init = extractInternalInit(request.init);
+    const timeoutMs = init.timeoutMs ??
+        (request.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : request.timeoutMs);
     if (retries === undefined || retries.maxAttempts <= 1) {
-        return fetchApi(request.url, request.init);
+        return fetchOnce(fetchApi, request.url, init.init, timeoutMs, request.fetchApi === undefined, false);
     }
-    const method = (request.init.method ?? "GET").toUpperCase();
-    const signal = request.init.signal ?? undefined;
+    const method = (init.init.method ?? "GET").toUpperCase();
     const started = Date.now();
+    let elapsedMs = 0;
     let attempt = 1;
     for (;;) {
+        const attemptStarted = Date.now();
         try {
-            const response = await fetchApi(request.url, cloneInit(request.init));
-            if (!shouldRetryStatus(method, response.status) || !canRetry(retries, attempt, started)) {
+            const response = await fetchOnce(fetchApi, request.url, cloneInit(init.init), timeoutMs, request.fetchApi === undefined, SAFE_METHODS.has(method));
+            elapsedMs += Date.now() - attemptStarted;
+            if (!shouldRetryStatus(method, response.status) ||
+                !canRetry(retries, attempt, started, elapsedMs)) {
                 return response;
             }
             await drain(response);
-            await sleepFor(retries, attempt, response.headers.get("Retry-After"), started, signal);
-            if (!canRetry(retries, attempt, started)) {
+            await sleepFor(retries, attempt, response.headers.get("Retry-After"), started, elapsedMs, init.init.signal ?? undefined);
+            if (!canRetry(retries, attempt, started, elapsedMs)) {
                 return response;
             }
         }
         catch (error) {
-            if (!shouldRetryError(method, error, signal) || !canRetry(retries, attempt, started)) {
+            elapsedMs += Date.now() - attemptStarted;
+            if (!shouldRetryError(method, error, init.init.signal ?? undefined) ||
+                !canRetry(retries, attempt, started, elapsedMs)) {
                 throw error;
             }
-            await sleepFor(retries, attempt, undefined, started, signal);
-            if (!canRetry(retries, attempt, started)) {
+            await sleepFor(retries, attempt, undefined, started, elapsedMs, init.init.signal ?? undefined);
+            if (!canRetry(retries, attempt, started, elapsedMs)) {
                 throw error;
             }
         }
@@ -122,16 +145,87 @@ function isBeforeSendError(error) {
     }
     return false;
 }
-function canRetry(retries, attempt, started) {
-    return attempt < retries.maxAttempts && Date.now() - started < retries.maxElapsedMs;
+async function fetchOnce(fetchApi, url, init, timeoutMs, defaultFetch, readBodyBeforeReturn) {
+    const callerSignal = init.signal ?? undefined;
+    let timeoutSignal;
+    let signal = callerSignal;
+    if (timeoutMs !== null) {
+        timeoutSignal = AbortSignal.timeout(timeoutMs);
+        signal = signal === undefined ? timeoutSignal : AbortSignal.any([signal, timeoutSignal]);
+    }
+    try {
+        const response = await fetchApi(url, prepareInit(init, signal, defaultFetch));
+        // SSE bodies are read incrementally by the caller as the job runs, not
+        // buffered up front — pre-reading one here would block `jobs.stream` from
+        // yielding any event until the stream closes. Buffer once (no clone) and
+        // return a response backed by that buffer rather than leaving the
+        // original's body unread, which would otherwise double transient memory
+        // for a large result.
+        if (readBodyBeforeReturn && !isEventStream(response)) {
+            const buffer = await response.arrayBuffer();
+            return new Response(isNullBodyStatus(response.status) ? null : buffer, {
+                status: response.status,
+                statusText: response.statusText,
+                headers: response.headers,
+            });
+        }
+        return response;
+    }
+    catch (error) {
+        if (timeoutSignal?.aborted && !callerSignal?.aborted) {
+            throw new RequestTimeoutError(timeoutMs, error);
+        }
+        throw error;
+    }
+}
+function isNullBodyStatus(status) {
+    return status === 204 || status === 205 || status === 304;
+}
+function isEventStream(response) {
+    return (response.headers.get("content-type") ?? "")
+        .toLowerCase()
+        .startsWith("text/event-stream");
+}
+function prepareInit(init, signal, defaultFetch) {
+    const next = { ...init, signal };
+    if (defaultFetch &&
+        isNodeRuntime() &&
+        (next.method ?? "GET").toUpperCase() === "POST") {
+        next.headers = headersWith(next.headers, "Connection", "close");
+    }
+    return next;
+}
+function isNodeRuntime() {
+    return typeof process !== "undefined" && process.versions?.node !== undefined;
+}
+function headersWith(headers, name, value) {
+    if (headers instanceof Headers) {
+        const next = new Headers(headers);
+        next.set(name, value);
+        return next;
+    }
+    if (Array.isArray(headers)) {
+        const next = new Headers(headers);
+        next.set(name, value);
+        return next;
+    }
+    return { ...(headers ?? {}), [name]: value };
+}
+function extractInternalInit(init) {
+    const { timeoutMs, ...cleanInit } = init;
+    return { init: cleanInit, timeoutMs };
+}
+function canRetry(retries, attempt, started, elapsedMs) {
+    const retryBudgetMs = Date.now() - started - elapsedMs;
+    return attempt < retries.maxAttempts && retryBudgetMs < retries.maxElapsedMs;
 }
-async function sleepFor(retries, attempt, retryAfter, started, signal) {
+async function sleepFor(retries, attempt, retryAfter, started, elapsedMs, signal) {
     const parsed = retryAfterDelayMs(retryAfter);
     const delay = parsed === undefined
         ? Math.min(retries.maxDelayMs, retries.initialDelayMs * 2 ** (attempt - 1)) *
             (1 + Math.random() * 0.2)
         : Math.min(parsed, retries.retryAfterMaxMs);
-    const remaining = retries.maxElapsedMs - (Date.now() - started);
+    const remaining = retries.maxElapsedMs - (Date.now() - started - elapsedMs);
     const boundedDelay = Math.max(0, Math.min(delay, remaining));
     if (!signal) {
         await new Promise((resolve) => setTimeout(resolve, boundedDelay));

package/dist/sse.d.ts

@@ -38,6 +38,7 @@ export interface StreamOptions {
     signal?: AbortSignal;
     fetchApi?: typeof fetch;
     retries?: Required<RetryConfig>;
+    timeoutMs?: number | null;
 }
 /**
  * Yield events until the stream closes.

package/dist/sse.js

@@ -39,6 +39,7 @@ export async function* streamJobEvents(options) {
     const response = await fetchWithRetries(options.retries, {
         url: options.url,
         fetchApi: options.fetchApi,
+        timeoutMs: options.timeoutMs,
         init: {
             method: "GET",
             headers: { ...options.headers, Accept: "text/event-stream" },

package/dist/version.d.ts

@@ -7,4 +7,4 @@
  * runtime, because importing JSON differs across module systems and bundlers
  * and would make this module's behaviour depend on how it was built.
  */
-export declare const VERSION = "0.18.27";
+export declare const VERSION = "0.18.28";

package/dist/version.js

@@ -7,4 +7,4 @@
  * runtime, because importing JSON differs across module systems and bundlers
  * and would make this module's behaviour depend on how it was built.
  */
-export const VERSION = "0.18.27";
+export const VERSION = "0.18.28";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unstructured-transform-client",
-  "version": "0.18.27",
+  "version": "0.18.28",
   "description": "TypeScript client for the Unstructured Transform v2 API — one document in, structured output back.",
   "license": "MIT",
   "author": "Unstructured",
@@ -16,6 +16,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {