unstructured-transform-client 0.18.18

package/dist/client.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The public surface: `client.parse.run(...)`, `client.extract.run(...)`.
+ *
+ * openapi-generator produces `new ParseApi(config).parseRun(...)` across four
+ * unrelated Api classes. openapi.yaml declares a different surface — `tags`
+ * plus `x-sdk-method-name` per operation, so the call reads
+ * `client.parse.run(document)` (decision N1, API v2 Surface Proposal) — and no
+ * generator reads those fields. This module is where that becomes real, and
+ * `tests/facade.test.ts` holds it to the contract.
+ *
+ * It also supplies what the generator cannot:
+ *
+ *   - `extract.fromDocument(...)`. POST /api/v2/extract declares BOTH an
+ *     application/json body and a multipart/form-data one; the generator emits
+ *     only the first and drops ExtractDocumentRequest from the models
+ *     entirely. One of the three launch flows, silently uncallable.
+ *   - `jobs.stream(...)`. The SSE progress stream.
+ *   - `schema` as an object on both flows. The wire format is a JSON *string*
+ *     on parse and a JSON *object* on extract — an inconsistency in the
+ *     contract that callers should not have to know.
+ */
+import type { ParseRunProfileEnum } from "./_generated/apis/ParseApi.js";
+import { Configuration } from "./_generated/runtime.js";
+import type { JobPage, JobResult, JobStatus, OutputFormat, ParseResult, UploadResult } from "./_generated/models/index.js";
+import { type FileInput } from "./files.js";
+import { type Outcome } from "./outcome.js";
+import { type RetryConfig } from "./retry.js";
+import { type JobEvent } from "./sse.js";
+export declare const DEFAULT_SERVER_URL = "https://platform.unstructuredapp.io";
+export interface TransformClientOptions {
+    /** Pass an API key, or leave credentials out to use UNSTRUCTURED_API_KEY. */
+    apiKey?: string;
+    bearerToken?: string;
+    serverUrl?: string;
+    /** Suppress the X-Unstructured-Client-* headers. The User-Agent remains. */
+    sendHostHeaders?: boolean;
+    /** Appended to the User-Agent, for a caller wrapping this SDK. */
+    userAgentSuffix?: string;
+    /** Override the fetch implementation, e.g. for tests or a proxy agent. */
+    fetchApi?: typeof fetch;
+    /** Per-client retries; pass `false` to disable them. */
+    retries?: RetryConfig | false;
+}
+export declare class TransformClient {
+    readonly parse: ParseNamespace;
+    readonly extract: ExtractNamespace;
+    readonly jobs: JobsNamespace;
+    readonly upload: UploadNamespace;
+    /** @internal */ readonly serverUrl: string;
+    /** @internal */ readonly requestHeaders: Record<string, string>;
+    /** @internal */ readonly configuration: Configuration;
+    /** @internal */ readonly fetchApi?: typeof fetch;
+    /** @internal */ readonly retries: Required<RetryConfig> | undefined;
+    constructor(options?: TransformClientOptions);
+}
+export interface ParseOptions {
+    input?: FileInput;
+    fileId?: string;
+    schema?: Record<string, unknown> | string;
+    prompt?: string;
+    output?: OutputFormat;
+    include?: string[];
+    profile?: ParseRunProfileEnum;
+    waitSeconds?: number;
+}
+declare class ParseNamespace {
+    private readonly client;
+    constructor(client: TransformClient);
+    /**
+     * Parse a document. Supplying `schema` extracts in the same job.
+     *
+     * Returns either the finished result (200) or a job handle (202) — the
+     * latter is what `waitSeconds: 0` always produces. Discriminate with
+     * `isAccepted`.
+     */
+    run(options: ParseOptions): Promise<Outcome<ParseResult>>;
+}
+export interface ExtractOptions {
+    parseId: string;
+    schema: Record<string, unknown>;
+    prompt?: string;
+    waitSeconds?: number;
+}
+export interface ExtractFromDocumentOptions {
+    input?: FileInput;
+    fileId?: string;
+    /** The original filename to attach when extracting from an already-uploaded file. */
+    filename?: string;
+    schema: Record<string, unknown>;
+    prompt?: string;
+    profile?: ParseRunProfileEnum;
+    waitSeconds?: number;
+}
+declare class ExtractNamespace {
+    private readonly client;
+    constructor(client: TransformClient);
+    /** Extract against an existing parse. The document is not parsed again. */
+    run(options: ExtractOptions): Promise<Outcome<ParseResult>>;
+    /**
+     * Extract directly from a raw document, in one call.
+     *
+     * The multipart variant of POST /api/v2/extract, reconstructed because
+     * openapi-generator emits only the JSON body for this path.
+     */
+    fromDocument(options: ExtractFromDocumentOptions): Promise<Outcome<ParseResult>>;
+}
+export interface JobsGetOptions {
+    output?: OutputFormat;
+    include?: string[];
+}
+export interface JobsListOptions {
+    cursor?: string;
+    limit?: number;
+    status?: JobStatus;
+}
+export interface JobsStreamOptions {
+    signal?: AbortSignal;
+    output?: OutputFormat;
+    include?: string[];
+}
+declare class JobsNamespace {
+    private readonly client;
+    constructor(client: TransformClient);
+    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>;
+    /**
+     * Progress events for a running job, as they happen.
+     *
+     * The same resource as `get(jobId)`, selected by Accept — not a second
+     * route. Yields `status` events and then exactly one terminal `result` or
+     * `error`, after which the stream ends.
+     */
+    stream(jobId: string, options?: JobsStreamOptions): AsyncGenerator<JobEvent>;
+}
+declare class UploadNamespace {
+    private readonly client;
+    constructor(client: TransformClient);
+    run(input: FileInput): Promise<UploadResult>;
+    get(fileId: string): Promise<Blob>;
+    delete(fileId: string): Promise<void>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,259 @@
+/**
+ * The public surface: `client.parse.run(...)`, `client.extract.run(...)`.
+ *
+ * openapi-generator produces `new ParseApi(config).parseRun(...)` across four
+ * unrelated Api classes. openapi.yaml declares a different surface — `tags`
+ * plus `x-sdk-method-name` per operation, so the call reads
+ * `client.parse.run(document)` (decision N1, API v2 Surface Proposal) — and no
+ * generator reads those fields. This module is where that becomes real, and
+ * `tests/facade.test.ts` holds it to the contract.
+ *
+ * It also supplies what the generator cannot:
+ *
+ *   - `extract.fromDocument(...)`. POST /api/v2/extract declares BOTH an
+ *     application/json body and a multipart/form-data one; the generator emits
+ *     only the first and drops ExtractDocumentRequest from the models
+ *     entirely. One of the three launch flows, silently uncallable.
+ *   - `jobs.stream(...)`. The SSE progress stream.
+ *   - `schema` as an object on both flows. The wire format is a JSON *string*
+ *     on parse and a JSON *object* on extract — an inconsistency in the
+ *     contract that callers should not have to know.
+ */
+import { ExtractApi } from "./_generated/apis/ExtractApi.js";
+import { JobsApi } from "./_generated/apis/JobsApi.js";
+import { ParseApi } from "./_generated/apis/ParseApi.js";
+import { UploadApi } from "./_generated/apis/UploadApi.js";
+import { Configuration } from "./_generated/runtime.js";
+import { ParseResultFromJSON } from "./_generated/models/index.js";
+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 { streamJobEvents } from "./sse.js";
+export const DEFAULT_SERVER_URL = "https://platform.unstructuredapp.io";
+/** Matches the service's `securitySchemes`; see openapi.yaml. */
+const API_KEY_HEADER = "unstructured-api-key";
+const API_KEY_ENV_VAR = "UNSTRUCTURED_API_KEY";
+function apiKeyFromEnvironment() {
+    // The package supports Node, but keeping this guarded also makes importing
+    // the client safe in browser bundles where `process` is not defined.
+    if (typeof process === "undefined")
+        return undefined;
+    return process.env[API_KEY_ENV_VAR] || undefined;
+}
+export class TransformClient {
+    parse;
+    extract;
+    jobs;
+    upload;
+    /** @internal */ serverUrl;
+    /** @internal */ requestHeaders;
+    /** @internal */ configuration;
+    /** @internal */ fetchApi;
+    /** @internal */ retries;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ??
+            (options.bearerToken === undefined ? apiKeyFromEnvironment() : undefined);
+        const hasApiKey = apiKey !== undefined;
+        const hasBearer = options.bearerToken !== undefined;
+        if (hasApiKey === hasBearer) {
+            throw new Error("pass exactly one of apiKey or bearerToken, or set " +
+                `${API_KEY_ENV_VAR} — they are different identities, not ` +
+                "interchangeable spellings of one credential");
+        }
+        this.serverUrl = (options.serverUrl ?? DEFAULT_SERVER_URL).replace(/\/+$/, "");
+        this.fetchApi = options.fetchApi;
+        this.retries = normalizeRetries(options.retries);
+        const auth = hasApiKey
+            ? { [API_KEY_HEADER]: apiKey }
+            : { Authorization: `Bearer ${options.bearerToken}` };
+        // NOTE: in a browser, `User-Agent` is a forbidden header name and is
+        // dropped silently by fetch. That is acceptable degradation rather than a
+        // bug to work around — the X-Unstructured-Client-* headers still arrive,
+        // and spoofing a UA past the browser's own is not something to attempt.
+        const identification = hostHeaders.build({
+            sendHostHeaders: options.sendHostHeaders,
+            userAgentSuffix: options.userAgentSuffix,
+        });
+        this.requestHeaders = { ...auth, ...identification };
+        this.configuration = new Configuration({
+            basePath: this.serverUrl,
+            headers: this.requestHeaders,
+            fetchApi: (url, init) => fetchWithRetries(this.retries, {
+                url: String(url),
+                init: init ?? {},
+                fetchApi: options.fetchApi,
+            }),
+        });
+        this.parse = new ParseNamespace(this);
+        this.extract = new ExtractNamespace(this);
+        this.jobs = new JobsNamespace(this);
+        this.upload = new UploadNamespace(this);
+    }
+}
+/** `Prefer: wait=N`. `0` is meaningful, so the check is against undefined. */
+function prefer(waitSeconds) {
+    return waitSeconds === undefined ? undefined : `wait=${waitSeconds}`;
+}
+class ParseNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Parse a document. Supplying `schema` extracts in the same job.
+     *
+     * Returns either the finished result (200) or a job handle (202) — the
+     * latter is what `waitSeconds: 0` always produces. Discriminate with
+     * `isAccepted`.
+     */
+    async run(options) {
+        if ((options.input === undefined) === (options.fileId === undefined)) {
+            throw new Error("pass exactly one of input or fileId");
+        }
+        return resolveOutcome(await new ParseApi(this.client.configuration).parseRunRaw({
+            prefer: prefer(options.waitSeconds),
+            include: options.include,
+            input: options.input === undefined ? undefined : asFile(options.input),
+            fileId: options.fileId,
+            output: options.output,
+            // A string is passed through so a caller holding a pre-serialized schema
+            // is not forced to round-trip it through JSON.parse.
+            schema: typeof options.schema === "object" && options.schema !== null
+                ? JSON.stringify(options.schema)
+                : options.schema,
+            prompt: options.prompt,
+            profile: options.profile,
+        }));
+    }
+}
+class ExtractNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Extract against an existing parse. The document is not parsed again. */
+    async run(options) {
+        return resolveOutcome(await new ExtractApi(this.client.configuration).extractRunRaw({
+            extractRequest: {
+                parseId: options.parseId,
+                schema: options.schema,
+                prompt: options.prompt,
+            },
+            prefer: prefer(options.waitSeconds),
+        }));
+    }
+    /**
+     * Extract directly from a raw document, in one call.
+     *
+     * The multipart variant of POST /api/v2/extract, reconstructed because
+     * openapi-generator emits only the JSON body for this path.
+     */
+    async fromDocument(options) {
+        // A document OR the id of one already uploaded, exactly as parse.run
+        // takes: ExtractDocumentRequest declares both, so requiring the bytes
+        // would make an already-uploaded file unusable here.
+        if ((options.input === undefined) === (options.fileId === undefined)) {
+            throw new Error("pass exactly one of input or fileId");
+        }
+        if (options.input !== undefined && options.filename !== undefined) {
+            throw new Error("filename only applies to fileId; input already carries its name");
+        }
+        const file = options.input === undefined ? undefined : asFile(options.input);
+        return postMultipart(this.client, {
+            path: "/api/v2/extract",
+            fileField: "input",
+            file,
+            filename: file?.name,
+            fields: {
+                file_id: options.fileId,
+                filename: options.filename,
+                schema: JSON.stringify(options.schema),
+                prompt: options.prompt,
+                profile: options.profile,
+            },
+            waitSeconds: options.waitSeconds,
+            fromJSON: ParseResultFromJSON,
+        });
+    }
+}
+class JobsNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async get(jobId, options = {}) {
+        return new JobsApi(this.client.configuration).jobsGet({
+            jobId,
+            output: options.output,
+            include: options.include,
+        });
+    }
+    async list(options = {}) {
+        return new JobsApi(this.client.configuration).jobsList({
+            cursor: options.cursor,
+            limit: options.limit,
+            status: options.status,
+        });
+    }
+    async *iterate(options = {}) {
+        let cursor = options.cursor;
+        for (;;) {
+            const page = await this.list({ ...options, cursor });
+            for (const job of page.jobs) {
+                yield job;
+            }
+            cursor = page.nextCursor ?? undefined;
+            if (cursor === undefined)
+                return;
+        }
+    }
+    async cancel(jobId) {
+        return new JobsApi(this.client.configuration).jobsCancel({ jobId });
+    }
+    async delete(jobId) {
+        await new JobsApi(this.client.configuration).jobsDelete({ jobId });
+    }
+    /**
+     * Progress events for a running job, as they happen.
+     *
+     * The same resource as `get(jobId)`, selected by Accept — not a second
+     * route. Yields `status` events and then exactly one terminal `result` or
+     * `error`, after which the stream ends.
+     */
+    stream(jobId, options = {}) {
+        // The terminal `result` event carries the same representation the JSON
+        // path would return, so these belong on the stream too — otherwise it
+        // could only ever deliver the server default, making it a second-class way
+        // to read the same resource.
+        const query = new URLSearchParams();
+        if (options.output !== undefined)
+            query.set("output", options.output);
+        for (const value of options.include ?? [])
+            query.append("include", value);
+        const suffix = query.size > 0 ? `?${query}` : "";
+        return streamJobEvents({
+            url: `${this.client.serverUrl}/api/v2/jobs/${encodeURIComponent(jobId)}${suffix}`,
+            headers: this.client.requestHeaders,
+            signal: options.signal,
+            fetchApi: this.client.fetchApi,
+            retries: this.client.retries,
+        });
+    }
+}
+class UploadNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async run(input) {
+        return new UploadApi(this.client.configuration).uploadRun({ file: asFile(input) });
+    }
+    async get(fileId) {
+        return new UploadApi(this.client.configuration).uploadGet({ fileId });
+    }
+    async delete(fileId) {
+        await new UploadApi(this.client.configuration).uploadDelete({ fileId });
+    }
+}

package/dist/files.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Turning what a caller has into a part the service will accept.
+ *
+ * THE FILENAME IS NOT DECORATION. The service validates an upload's extension
+ * against a published allowlist, so a part with no filename is rejected as
+ * "Unsupported file type" — for a document that is fine.
+ *
+ * `FormData.append(name, blob)` labels the part `blob`. That is what the
+ * GENERATED code does for `parse.run` and `upload.run`
+ * (`formParams.append('input', requestParameters['input'])`), so passing a
+ * plain `Blob` to either would have been rejected by the real service while
+ * passing every test against a stub that does not validate extensions.
+ *
+ * A `File` carries its own name and FormData uses it, so normalizing to `File`
+ * fixes the generated paths without patching generated code.
+ *
+ * The Python SDK refuses a nameless document for the same reason and with the
+ * same wording; the two SDKs should not disagree about what is a valid call.
+ */
+/** A document, in any of the shapes a caller reasonably has one. */
+export type FileInput = File | {
+    data: Blob | Uint8Array | ArrayBuffer;
+    filename: string;
+};
+/**
+ * Normalize to a `File`, or throw with the reason.
+ *
+ * A bare `Blob` is refused rather than given a made-up name: guessing a
+ * filename means guessing the extension the service validates, and being wrong
+ * produces a rejection that points at the document instead of at the call.
+ */
+export declare function asFile(input: FileInput): File;

package/dist/files.js

@@ -0,0 +1,46 @@
+/**
+ * Turning what a caller has into a part the service will accept.
+ *
+ * THE FILENAME IS NOT DECORATION. The service validates an upload's extension
+ * against a published allowlist, so a part with no filename is rejected as
+ * "Unsupported file type" — for a document that is fine.
+ *
+ * `FormData.append(name, blob)` labels the part `blob`. That is what the
+ * GENERATED code does for `parse.run` and `upload.run`
+ * (`formParams.append('input', requestParameters['input'])`), so passing a
+ * plain `Blob` to either would have been rejected by the real service while
+ * passing every test against a stub that does not validate extensions.
+ *
+ * A `File` carries its own name and FormData uses it, so normalizing to `File`
+ * fixes the generated paths without patching generated code.
+ *
+ * The Python SDK refuses a nameless document for the same reason and with the
+ * same wording; the two SDKs should not disagree about what is a valid call.
+ */
+/**
+ * Normalize to a `File`, or throw with the reason.
+ *
+ * A bare `Blob` is refused rather than given a made-up name: guessing a
+ * filename means guessing the extension the service validates, and being wrong
+ * produces a rejection that points at the document instead of at the call.
+ */
+export function asFile(input) {
+    if (typeof File !== "undefined" && input instanceof File) {
+        if (!input.name) {
+            throw new TypeError("this File has no name, so the extension the service validates is " +
+                'unknown. Pass { data, filename: "invoice.pdf" } instead.');
+        }
+        return input;
+    }
+    if (input && typeof input === "object" && "data" in input && "filename" in input) {
+        const { data, filename } = input;
+        if (!filename) {
+            throw new TypeError("filename must not be empty");
+        }
+        return new File([data], filename);
+    }
+    throw new TypeError("pass a File, or { data, filename }. A bare Blob is refused because the " +
+        "service validates the upload's extension against an allowlist, and a " +
+        "Blob has no filename to validate — it would be rejected as an " +
+        "unsupported file type.");
+}

package/dist/hostHeaders.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Host and client identification headers (TRNSFRM-91).
+ *
+ * The TypeScript half of the same contract the Python SDK implements. Keep the
+ * two in step: a consumer correlating traffic from both languages should not
+ * have to special-case either.
+ *
+ * WHAT IS SENT: SDK name and version, language, runtime version, OS family,
+ * OS release, CPU architecture.
+ *
+ * NOT SENT, deliberately: hostname, username, working directory, environment
+ * variables, local IP or MAC address, or anything read from the document being
+ * parsed. `hostHeaders.test.ts` asserts the exclusions against this machine's
+ * real values rather than trusting this comment.
+ *
+ * Nothing here sets `X-Unstructured-Request-Source`. That header is trusted
+ * (TRNSFRM-113) — the edge owns it, the values are ui/mcp/api, and a public
+ * caller must not be able to claim `ui` or `mcp`. An SDK is a public caller.
+ * A wrapping caller identifies itself with `userAgentSuffix` instead, which is
+ * advisory and carries no privilege.
+ */
+export declare const CLIENT_NAME = "@utic/transform-client";
+export declare const HEADER_NAME = "X-Unstructured-Client-Name";
+export declare const HEADER_VERSION = "X-Unstructured-Client-Version";
+export declare const HEADER_LANGUAGE = "X-Unstructured-Client-Language";
+export declare const HEADER_RUNTIME = "X-Unstructured-Client-Runtime";
+export declare const HEADER_PLATFORM = "X-Unstructured-Client-Platform";
+export declare const DISABLE_ENV_VAR = "UNSTRUCTURED_TRANSFORM_DISABLE_HOST_HEADERS";
+/** `@utic/transform-client/0.18.0 (node/22.4.0; darwin/arm64)` */
+export declare function userAgent(suffix?: string): string;
+export interface HostHeaderOptions {
+    sendHostHeaders?: boolean;
+    userAgentSuffix?: string;
+}
+/** The headers to merge into every request. */
+export declare function build(options?: HostHeaderOptions): Record<string, string>;

package/dist/hostHeaders.js

@@ -0,0 +1,133 @@
+/**
+ * Host and client identification headers (TRNSFRM-91).
+ *
+ * The TypeScript half of the same contract the Python SDK implements. Keep the
+ * two in step: a consumer correlating traffic from both languages should not
+ * have to special-case either.
+ *
+ * WHAT IS SENT: SDK name and version, language, runtime version, OS family,
+ * OS release, CPU architecture.
+ *
+ * NOT SENT, deliberately: hostname, username, working directory, environment
+ * variables, local IP or MAC address, or anything read from the document being
+ * parsed. `hostHeaders.test.ts` asserts the exclusions against this machine's
+ * real values rather than trusting this comment.
+ *
+ * Nothing here sets `X-Unstructured-Request-Source`. That header is trusted
+ * (TRNSFRM-113) — the edge owns it, the values are ui/mcp/api, and a public
+ * caller must not be able to claim `ui` or `mcp`. An SDK is a public caller.
+ * A wrapping caller identifies itself with `userAgentSuffix` instead, which is
+ * advisory and carries no privilege.
+ */
+import { VERSION } from "./version.js";
+export const CLIENT_NAME = "@utic/transform-client";
+export const HEADER_NAME = "X-Unstructured-Client-Name";
+export const HEADER_VERSION = "X-Unstructured-Client-Version";
+export const HEADER_LANGUAGE = "X-Unstructured-Client-Language";
+export const HEADER_RUNTIME = "X-Unstructured-Client-Runtime";
+export const HEADER_PLATFORM = "X-Unstructured-Client-Platform";
+export const DISABLE_ENV_VAR = "UNSTRUCTURED_TRANSFORM_DISABLE_HOST_HEADERS";
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+/**
+ * Where this is running. Returns `unknown` values rather than throwing.
+ *
+ * The SDK is expected to run in a browser as well as in Node, and `process` is
+ * simply absent there — reading it unguarded would make importing this module
+ * throw in a bundler's output. A browser deliberately gets no OS or
+ * architecture: that information is not reliably available, and the values
+ * that ARE available are fingerprinting surface we have no reason to collect.
+ */
+/**
+ * The OS release, resolved once at load and only where it exists.
+ *
+ * `node:os` is the only source of it and does not exist in a browser, so a
+ * static import would break any browser bundle of this package. A guarded
+ * top-level dynamic import gets the value under Node and leaves it "unknown"
+ * everywhere else — `require` is not an option, this package is ESM.
+ */
+let osRelease = "unknown";
+try {
+    osRelease = (await import("node:os")).release();
+}
+catch {
+    // Not Node, or bundled without it. Family and architecture still ship.
+}
+/**
+ * Node's architecture name, spelled the way Python spells it.
+ *
+ * `process.arch` says `x64` where `platform.machine()` says `x86_64` for the
+ * same physical CPU, so the two SDKs bucketed the same architecture under two
+ * different labels — which defeats the point of a header consumers group by.
+ * Python's spelling wins because it is the uname value the rest of the world
+ * reports.
+ */
+const ARCH_ALIASES = {
+    x64: "x86_64",
+    ia32: "i386",
+    arm: "armv7l",
+    ppc64: "ppc64le",
+};
+/**
+ * `arm64` is the case a flat alias map gets wrong, in both directions.
+ *
+ * Python reports whatever uname says, and uname disagrees with itself across
+ * operating systems: Linux says `aarch64`, macOS says `arm64`. Node says
+ * `arm64` on both. So mapping arm64 -> aarch64 unconditionally would fix
+ * Graviton and BREAK macOS, where the two SDKs currently agree.
+ *
+ * Hence the OS check. Adding this to ARCH_ALIASES instead would have traded
+ * one mismatch for another and looked like a fix.
+ */
+function architecture(platform, arch) {
+    if (arch === "arm64") {
+        return platform === "linux" ? "aarch64" : "arm64";
+    }
+    return ARCH_ALIASES[arch] ?? arch;
+}
+function environment() {
+    const proc = globalThis.process;
+    if (proc?.versions?.node) {
+        // `<family>/<release>/<arch>`, the same three-part shape the Python SDK
+        // sends. An earlier version omitted the release, so the two SDKs disagreed
+        // about the format of a header consumers are meant to group by.
+        return {
+            runtime: `node/${proc.versions.node}`,
+            platform: `${proc.platform}/${osRelease}/${architecture(proc.platform, proc.arch)}`,
+        };
+    }
+    return { runtime: "browser", platform: "unknown" };
+}
+function disabled(explicit) {
+    // An explicit argument wins over the environment, so a caller can force the
+    // headers ON where they are disabled by default. Only `undefined` defers —
+    // `false` is a decision, and treating it as absence would make an explicit
+    // `true` unable to override.
+    if (explicit !== undefined) {
+        return !explicit;
+    }
+    const proc = globalThis.process;
+    const value = proc?.env?.[DISABLE_ENV_VAR]?.trim().toLowerCase() ?? "";
+    return TRUTHY.has(value);
+}
+/** `@utic/transform-client/0.18.0 (node/22.4.0; darwin/arm64)` */
+export function userAgent(suffix) {
+    const { runtime, platform } = environment();
+    const agent = `${CLIENT_NAME}/${VERSION} (${runtime}; ${platform})`;
+    return suffix ? `${agent} ${suffix}` : agent;
+}
+/** The headers to merge into every request. */
+export function build(options = {}) {
+    const headers = {
+        "User-Agent": userAgent(options.userAgentSuffix),
+    };
+    if (disabled(options.sendHostHeaders)) {
+        return headers;
+    }
+    const { runtime, platform } = environment();
+    headers[HEADER_NAME] = CLIENT_NAME;
+    headers[HEADER_VERSION] = VERSION;
+    headers[HEADER_LANGUAGE] = "typescript";
+    headers[HEADER_RUNTIME] = runtime;
+    headers[HEADER_PLATFORM] = platform;
+    return headers;
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * TypeScript client for the Unstructured Transform v2 API.
+ *
+ *     import { TransformClient } from "@utic/transform-client";
+ *
+ *     const client = new TransformClient({ apiKey: "..." });
+ *     const result = await client.parse.run({ input: file });
+ *
+ * Everything exported here is public. The `_generated` directory is not — it
+ * is produced from openapi.yaml at build time and its layout is the
+ * generator's business, so importing from it directly will break without
+ * notice. The models re-exported below are the exception: they are the
+ * 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 { isTerminal, type JobEvent } from "./sse.js";
+export { asFile, type FileInput } from "./files.js";
+export { isAccepted, type Outcome } from "./outcome.js";
+export { VERSION } from "./version.js";
+export { FetchError, RequiredError, ResponseError } from "./_generated/runtime.js";
+export type { ModelError as TransformErrorBody } from "./_generated/models/index.js";
+export { ErrorCode, JobStatus, OutputFormat, } from "./_generated/models/index.js";
+export { ParseRunProfileEnum as Profile } from "./_generated/apis/ParseApi.js";
+export type { Element, ExtractionResult, JobAccepted, JobPage, JobResult, JobSummary, ParseResult, UploadResult, } from "./_generated/models/index.js";