@anyformat/sdk 0.2.2 → 1.0.0-rc.2

package/dist/index.cjs

@@ -23,23 +23,75 @@ __export(index_exports, {
   APIError: () => APIError,
   Anyformat: () => Anyformat,
   AnyformatError: () => AnyformatError,
-  BadRequest: () => BadRequest,
-  Forbidden: () => Forbidden,
-  NotFound: () => NotFound,
+  BadRequestError: () => BadRequestError,
+  DatasetUpload: () => DatasetUpload,
+  ExtractionCancelledError: () => ExtractionCancelledError,
+  ExtractionFailedError: () => ExtractionFailedError,
+  ForbiddenError: () => ForbiddenError,
+  InsufficientScopeError: () => InsufficientScopeError,
+  NotFoundError: () => NotFoundError,
   ParseView: () => ParseView,
-  RateLimited: () => RateLimited,
+  PaymentRequiredError: () => PaymentRequiredError,
+  RateLimitedError: () => RateLimitedError,
   Result: () => Result,
   Run: () => Run,
-  SDKTimeout: () => SDKTimeout,
+  RunFailedError: () => RunFailedError,
+  SDKTimeoutError: () => SDKTimeoutError,
   Schema: () => Schema,
   ServerError: () => ServerError,
-  Unauthorized: () => Unauthorized,
+  TermsAcceptanceRequiredError: () => TermsAcceptanceRequiredError,
+  UnauthorizedError: () => UnauthorizedError,
+  Upload: () => Upload,
   Workflow: () => Workflow,
   WorkflowBuilder: () => WorkflowBuilder,
-  WorkflowBuilderError: () => WorkflowBuilderError
+  WorkflowBuilderError: () => WorkflowBuilderError,
+  WorkflowNameConflictError: () => WorkflowNameConflictError
 });
 module.exports = __toCommonJS(index_exports);
 
+// package.json
+var package_default = {
+  name: "@anyformat/sdk",
+  version: "1.0.0-rc.2",
+  description: "TypeScript SDK for the AnyFormat API",
+  license: "MIT",
+  author: "Anyformat <info@anyformat.ai>",
+  type: "module",
+  main: "./dist/index.cjs",
+  module: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js",
+      require: "./dist/index.cjs"
+    }
+  },
+  files: [
+    "dist"
+  ],
+  engines: {
+    node: ">=18"
+  },
+  scripts: {
+    "gen:spec": 'ROOT=$(unset GIT_DIR && git rev-parse --show-toplevel) && cd "$ROOT/anyformat/services/api" && uv run python "$ROOT/anyformat/libs/public/sdk-js/scripts/dump_openapi.py" "$ROOT/anyformat/libs/public/sdk-js/openapi/v2.json" --surface v2 && uv run python "$ROOT/anyformat/libs/public/sdk-js/scripts/dump_openapi.py" "$ROOT/anyformat/libs/public/sdk-js/openapi/v3.json" --surface v3',
+    "gen:client": "openapi-ts",
+    gen: "bun run gen:spec && bun run gen:client",
+    "gen:check": "bun run gen && git diff --exit-code -- openapi src/sdk",
+    build: "tsup",
+    typecheck: "tsc --noEmit",
+    test: "vitest run",
+    prepublishOnly: "bun run build"
+  },
+  devDependencies: {
+    "@hey-api/openapi-ts": "^0.99.0",
+    "@types/node": "^25.9.1",
+    tsup: "^8.3.0",
+    typescript: "^5.6.0",
+    vitest: "^4.1.7"
+  }
+};
+
 // src/builder.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
@@ -83,8 +135,8 @@ var Result = class {
   }
   raw;
   _parse;
-  get collectionId() {
-    return this.raw.collection_id;
+  get documentPacketId() {
+    return this.raw.document_packet_id;
   }
   get extractions() {
     return this.raw.extractions ?? [];
@@ -101,13 +153,22 @@ var Result = class {
     return this._parse;
   }
   /**
-   * Convenience accessor for a top-level scalar field on the first
-   * extraction (linear workflows). Returns `undefined` for missing fields
-   * or list-valued fields — read `extractions` directly for those.
+   * Convenience accessor for a top-level field on the untagged (linear)
+   * extraction. Returns the scalar `ExtractedField` for a scalar field, or
+   * the array of row records (`ExtractedRows`) for a list/object field such
+   * as `line_items`. `undefined` only when the field is absent.
+   *
+   * Parameterise with the declared schema type to type a scalar's `.value`:
+   * `result.field<number>("total").value` is `number | null`.
    */
   field(name) {
-    const value = this.extractions[0]?.fields?.[name];
-    return value !== void 0 && !Array.isArray(value) ? value : void 0;
+    const untagged = this.extractions.find(
+      (e) => e.split_name == null && e.partition == null
+    );
+    const value = untagged?.fields?.[name];
+    if (value === void 0) return void 0;
+    if (Array.isArray(value)) return value;
+    return value;
   }
 };
 
@@ -120,39 +181,116 @@ var APIError = class extends AnyformatError {
     this.status = status;
     this.body = body;
     this.name = new.target.name;
+    if (body && typeof body === "object") {
+      const envelope = body;
+      if (typeof envelope.error_code === "string") this.errorCode = envelope.error_code;
+      if (envelope.detail !== void 0) this.detail = envelope.detail;
+      if (typeof envelope.retryable === "boolean") this.retryable = envelope.retryable;
+      if (typeof envelope.request_id === "string") this.requestId = envelope.request_id;
+      if (envelope.params && typeof envelope.params === "object") {
+        this.params = envelope.params;
+      }
+    }
   }
   status;
   body;
+  /** Stable identifier for programmatic handling, e.g. `PAYMENT_REQUIRED`. */
+  errorCode;
+  /** Developer-facing explanation; not surfaced in `message` (ADR platform/0053 §2). Often a `ValidationItem[]`. */
+  detail;
+  /** Named substitutions the `error` summary refers to, e.g. `{ required_scope }`. */
+  params;
+  /** Whether the API says retrying the same request can succeed. */
+  retryable;
+  /** Correlation id to quote in support requests. */
+  requestId;
 };
-var BadRequest = class extends APIError {
+var BadRequestError = class extends APIError {
 };
-var Unauthorized = class extends APIError {
+var UnauthorizedError = class extends APIError {
 };
-var Forbidden = class extends APIError {
+var PaymentRequiredError = class extends APIError {
 };
-var NotFound = class extends APIError {
+var ForbiddenError = class extends APIError {
 };
-var RateLimited = class extends APIError {
+var NotFoundError = class extends APIError {
+};
+var RateLimitedError = class extends APIError {
+  constructor(status, message, body, retryAfter) {
+    super(status, message, body);
+    this.retryAfter = retryAfter;
+  }
+  retryAfter;
 };
 var ServerError = class extends APIError {
 };
-var SDKTimeout = class extends AnyformatError {
+function parseRetryAfter(raw) {
+  if (raw == null || raw.trim() === "") return void 0;
+  const seconds = Number(raw);
+  if (!Number.isNaN(seconds)) return seconds;
+  const when = Date.parse(raw);
+  if (Number.isNaN(when)) return void 0;
+  return Math.max((when - Date.now()) / 1e3, 0);
+}
+var InsufficientScopeError = class extends ForbiddenError {
+};
+var TermsAcceptanceRequiredError = class extends ForbiddenError {
+};
+var WorkflowNameConflictError = class extends APIError {
+};
+var SDKTimeoutError = class extends AnyformatError {
+};
+var RunFailedError = class extends AnyformatError {
+  constructor(runId, status) {
+    super(`Run ${runId} ended with status "${status}"`);
+    this.runId = runId;
+    this.status = status;
+    this.name = new.target.name;
+  }
+  runId;
+  status;
+};
+var ExtractionFailedError = class extends RunFailedError {
+  constructor(runId) {
+    super(runId, "error");
+  }
+};
+var ExtractionCancelledError = class extends RunFailedError {
+  constructor(runId) {
+    super(runId, "cancelled");
+  }
 };
 var WorkflowBuilderError = class extends AnyformatError {
 };
-function toApiError(status, body) {
-  const message = `AnyFormat API error (${status})`;
+function messageFrom(status, body) {
+  const fallback = `AnyFormat API error (${status})`;
+  if (!body || typeof body !== "object") return fallback;
+  const envelope = body;
+  return typeof envelope.error === "string" && envelope.error ? envelope.error : fallback;
+}
+var BY_ERROR_CODE = {
+  insufficient_api_key_scope: InsufficientScopeError,
+  terms_acceptance_required: TermsAcceptanceRequiredError,
+  WORKFLOW_NAME_CONFLICT: WorkflowNameConflictError
+};
+function toApiError(status, body, headers) {
+  const message = messageFrom(status, body);
+  const errorCode = body && typeof body === "object" && typeof body.error_code === "string" ? body.error_code : void 0;
+  const ByCode = errorCode ? BY_ERROR_CODE[errorCode] : void 0;
+  if (ByCode) return new ByCode(status, message, body);
   switch (status) {
     case 400:
-      return new BadRequest(status, message, body);
+      return new BadRequestError(status, message, body);
     case 401:
-      return new Unauthorized(status, message, body);
+      return new UnauthorizedError(status, message, body);
+    case 402:
+      return new PaymentRequiredError(status, message, body);
     case 403:
-      return new Forbidden(status, message, body);
+      return new ForbiddenError(status, message, body);
     case 404:
-      return new NotFound(status, message, body);
+      return new NotFoundError(status, message, body);
     case 429:
-      return new RateLimited(status, message, body);
+      return new RateLimitedError(status, message, body, parseRetryAfter(headers?.get("Retry-After")));
     default:
       return status >= 500 ? new ServerError(status, message, body) : new APIError(status, message, body);
   }
@@ -212,7 +350,7 @@ function createSseClient({
   ...options
 }) {
   let lastEventId;
-  const sleep = sseSleepFn ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const sleep2 = sseSleepFn ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
   const createStream = async function* () {
     let retryDelay = sseDefaultRetryDelay ?? 3e3;
     let attempt = 0;
@@ -316,7 +454,7 @@ function createSseClient({
           break;
         }
         const backoff = Math.min(retryDelay * 2 ** (attempt - 1), sseMaxRetryDelay ?? 3e4);
-        await sleep(backoff);
+        await sleep2(backoff);
       }
     }
   };
@@ -969,46 +1107,115 @@ var createClient = (config = {}) => {
 };
 
 // src/sdk/client.gen.ts
-var client = createClient(createConfig({ baseUrl: "https://api-dev.anyformat.ai" }));
+var client = createClient(createConfig({ baseUrl: "https://api.anyformat.dev" }));
 
 // src/sdk/sdk.gen.ts
-var v2ListWorkflows = (options) => (options?.client ?? client).get({
+var v3DeleteDocumentPacket = (options) => (options.client ?? client).delete({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v3/document-packets/{document_packet_id}/",
+  ...options
+});
+var v3GetDocumentPacket = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v3/document-packets/{document_packet_id}/",
+  ...options
+});
+var v3RunDocumentPacket = (options) => (options.client ?? client).post({
   security: [{ scheme: "bearer", type: "http" }],
-  url: "/v2/workflows/",
+  url: "/v3/document-packets/{document_packet_id}/run/",
   ...options
 });
-var v2CreateWorkflow = (options) => (options.client ?? client).post({
+var v3Parse = (options) => (options.client ?? client).post({
+  ...formDataBodySerializer,
   security: [{ scheme: "bearer", type: "http" }],
-  url: "/v2/workflows/",
+  url: "/v3/parse/",
+  ...options,
+  headers: {
+    "Content-Type": null,
+    ...options.headers
+  }
+});
+var v3GetRun = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v3/runs/{run_id}/",
+  ...options
+});
+var v3ListWorkflows = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v3/workflows/",
+  ...options
+});
+var v3CreateWorkflow = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v3/workflows/",
   ...options,
   headers: {
     "Content-Type": "application/json",
     ...options.headers
   }
 });
-var v2DeleteWorkflow = (options) => (options.client ?? client).delete({
+var v3DeleteWorkflow = (options) => (options.client ?? client).delete({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v3/workflows/{workflow_id}/",
+  ...options
+});
+var v3GetWorkflow = (options) => (options.client ?? client).get({
   security: [{ scheme: "bearer", type: "http" }],
-  url: "/v2/workflows/{workflow_id}/",
+  url: "/v3/workflows/{workflow_id}/",
   ...options
 });
-var v2UpdateWorkflow = (options) => (options.client ?? client).put({
+var v3UpdateWorkflow = (options) => (options.client ?? client).patch({
   security: [{ scheme: "bearer", type: "http" }],
-  url: "/v2/workflows/{workflow_id}/",
+  url: "/v3/workflows/{workflow_id}/",
   ...options,
   headers: {
     "Content-Type": "application/json",
     ...options.headers
   }
 });
-var v2GetFileResults = (options) => (options.client ?? client).get({
+var v3UploadToDataset = (options) => (options.client ?? client).post({
+  ...formDataBodySerializer,
   security: [{ scheme: "bearer", type: "http" }],
-  url: "/v2/workflows/{workflow_id}/files/{collection_id}/results/",
+  url: "/v3/workflows/{workflow_id}/dataset/upload/",
+  ...options,
+  headers: {
+    "Content-Type": null,
+    ...options.headers
+  }
+});
+var v3ListWorkflowDocumentPackets = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v3/workflows/{workflow_id}/document-packets/",
+  ...options
+});
+var v3ListWorkflowRuns = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v3/workflows/{workflow_id}/runs/",
   ...options
 });
-var v2RunWorkflow = (options) => (options.client ?? client).post({
+var v3UploadToWorkflow = (options) => (options.client ?? client).post({
   ...formDataBodySerializer,
   security: [{ scheme: "bearer", type: "http" }],
-  url: "/v2/workflows/{workflow_id}/run/",
+  url: "/v3/workflows/{workflow_id}/upload/",
+  ...options,
+  headers: {
+    "Content-Type": null,
+    ...options.headers
+  }
+});
+var v3UploadFromUrl = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v3/workflows/{workflow_id}/upload/from-url/",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var v3UploadAndRunWorkflow = (options) => (options.client ?? client).post({
+  ...formDataBodySerializer,
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v3/workflows/{workflow_id}/upload/run/",
   ...options,
   headers: {
     "Content-Type": null,
@@ -1017,36 +1224,129 @@ var v2RunWorkflow = (options) => (options.client ?? client).post({
 });
 
 // src/run.ts
+function isTransientStatus(status) {
+  return status === 429 || status >= 500;
+}
+var RETRY_BASE_MS = 1e3;
+var RETRY_MAX_MS = 3e4;
+function retryDelayMs(response, attempt) {
+  const retryAfter = parseRetryAfter(response?.headers?.get("Retry-After"));
+  if (retryAfter !== void 0) return Math.min(retryAfter * 1e3, RETRY_MAX_MS);
+  const base = Math.min(RETRY_BASE_MS * 2 ** attempt, RETRY_MAX_MS);
+  return base * (0.75 + Math.random() * 0.5);
+}
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var Run = class {
   /** @internal */
-  constructor(client2, workflowId, id) {
+  constructor(client2, id, workflowId, documentPacketId, status = "queued") {
     this.client = client2;
-    this.workflowId = workflowId;
     this.id = id;
+    this.workflowId = workflowId;
+    this.documentPacketId = documentPacketId;
+    this.status = status;
   }
   client;
-  workflowId;
   id;
+  workflowId;
+  documentPacketId;
+  /** Status at trigger time, refreshed on every `wait()` poll. */
+  status;
   async wait(opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 3e5;
     const pollMs = opts.pollMs ?? 3e3;
     const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-      const results = await v2GetFileResults({
-        client: this.client,
-        path: { workflow_id: this.workflowId, collection_id: this.id }
-      });
-      if (!results.error) return new Result(results.data);
-      if (results.response?.status !== 412) {
-        throw toApiError(results.response?.status ?? 500, results.error);
+    let transientFailures = 0;
+    for (; ; ) {
+      const res = await v3GetRun({ client: this.client, path: { run_id: this.id } });
+      if (res.error) {
+        const status = res.response?.status ?? 500;
+        if (!isTransientStatus(status)) throw toApiError(status, res.error, res.response?.headers);
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+          throw new SDKTimeoutError(`Extraction did not complete within ${timeoutMs}ms`);
+        }
+        await sleep(Math.min(retryDelayMs(res.response, transientFailures), remainingMs));
+        transientFailures += 1;
+        continue;
+      }
+      transientFailures = 0;
+      const detail = res.data;
+      this.status = detail.status;
+      if (detail.status === "processed") {
+        if (!detail.results) {
+          throw new AnyformatError(`Run ${this.id} is processed but the API returned no results`);
+        }
+        return new Result(detail.results);
       }
-      await new Promise((resolve) => setTimeout(resolve, pollMs));
+      if (detail.status === "error") throw new ExtractionFailedError(this.id);
+      if (detail.status === "cancelled") throw new ExtractionCancelledError(this.id);
+      if (Date.now() >= deadline) {
+        throw new SDKTimeoutError(`Extraction did not complete within ${timeoutMs}ms`);
+      }
+      await sleep(pollMs);
     }
-    throw new SDKTimeout(`Extraction did not complete within ${timeoutMs}ms`);
+  }
+};
+
+// src/upload.ts
+var DatasetUpload = class {
+  /** @internal */
+  constructor(workflowId, documentPacketId, files, groundTruthSaved) {
+    this.workflowId = workflowId;
+    this.documentPacketId = documentPacketId;
+    this.files = files;
+    this.groundTruthSaved = groundTruthSaved;
+  }
+  workflowId;
+  documentPacketId;
+  files;
+  groundTruthSaved;
+};
+var Upload = class {
+  /** @internal */
+  constructor(client2, workflowId, documentPacketId, files) {
+    this.client = client2;
+    this.workflowId = workflowId;
+    this.documentPacketId = documentPacketId;
+    this.files = files;
+  }
+  client;
+  workflowId;
+  documentPacketId;
+  files;
+  /** Trigger extraction on the staged packet and return a pending `Run`. */
+  async run(opts = {}) {
+    const res = await v3RunDocumentPacket({
+      client: this.client,
+      path: { document_packet_id: this.documentPacketId },
+      ...opts.idempotencyKey ? { headers: { "Idempotency-Key": opts.idempotencyKey } } : {}
+    });
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error, res.response?.headers);
+    const data = res.data;
+    return new Run(this.client, data.run_id, data.workflow_id, data.document_packet_id, data.status);
   }
 };
 
 // src/workflow.ts
+var MAX_FILES_PER_PACKET = 100;
+function normalizeFiles(files, op) {
+  const list = files == null ? [] : Array.isArray(files) ? files : [files];
+  if (list.length === 0) {
+    throw new WorkflowBuilderError(`${op}() requires at least one named file`);
+  }
+  if (list.length > MAX_FILES_PER_PACKET) {
+    throw new WorkflowBuilderError(`${op}() accepts at most ${MAX_FILES_PER_PACKET} files per document packet`);
+  }
+  for (const file of list) {
+    const filename = file.name;
+    if (typeof filename !== "string" || filename.length === 0) {
+      throw new WorkflowBuilderError(
+        `${op}() needs a named file so the server can detect its type \u2014 pass a File, e.g. new File([bytes], "invoice.pdf"), not a bare Blob`
+      );
+    }
+  }
+  return list;
+}
 var Workflow = class {
   /** @internal */
   constructor(client2, id, name) {
@@ -1057,29 +1357,90 @@ var Workflow = class {
   client;
   id;
   name;
-  /** Submit a document against this workflow and return a pending `Run`. */
-  async run(file = null, opts = {}) {
-    if (file === null && !opts.text) {
-      throw new WorkflowBuilderError("run() requires a document \u2014 pass a file or non-empty opts.text");
-    }
-    if (file !== null && opts.text !== void 0) {
-      throw new WorkflowBuilderError("run() accepts either a file or text, not both");
-    }
-    if (file !== null) {
-      const filename = file.name;
-      if (typeof filename !== "string" || filename.length === 0) {
-        throw new WorkflowBuilderError(
-          'run() needs a named file so the server can detect its type \u2014 pass a File, e.g. new File([bytes], "invoice.pdf"), not a bare Blob'
-        );
-      }
+  /** Upload 1..100 files as one document packet and run it. Returns a pending `Run`. */
+  async run(files = null, opts = {}) {
+    const list = normalizeFiles(files, "run");
+    const submitted = await v3UploadAndRunWorkflow({
+      client: this.client,
+      path: { workflow_id: this.id },
+      body: { files: list, ...opts.onConflict ? { on_conflict: opts.onConflict } : {} },
+      ...opts.idempotencyKey ? { headers: { "Idempotency-Key": opts.idempotencyKey } } : {}
+    });
+    if (submitted.error) throw toApiError(submitted.response?.status ?? 500, submitted.error, submitted.response?.headers);
+    const data = submitted.data;
+    return new Run(this.client, data.run_id, data.workflow_id, data.document_packet_id, data.status);
+  }
+  /**
+   * Stage 1..100 files as one document packet WITHOUT running it (no credits
+   * spent). Returns an `Upload`; call `.run()` on it to start extraction.
+   */
+  async upload(files = null, opts = {}) {
+    const list = normalizeFiles(files, "upload");
+    const staged = await v3UploadToWorkflow({
+      client: this.client,
+      path: { workflow_id: this.id },
+      body: { files: list, ...opts.onConflict ? { on_conflict: opts.onConflict } : {} },
+      ...opts.idempotencyKey ? { headers: { "Idempotency-Key": opts.idempotencyKey } } : {}
+    });
+    if (staged.error) throw toApiError(staged.response?.status ?? 500, staged.error, staged.response?.headers);
+    const data = staged.data;
+    return new Upload(this.client, data.workflow_id, data.document_packet_id, data.files);
+  }
+  /**
+   * Upload 1..100 files as ONE document (+ optional ground truth) into the
+   * workflow's dataset, as one document packet. Atomic: any rejected file or a
+   * ground-truth failure fails the call and stores nothing. By default a
+   * colliding filename fails with `409`; pass `onConflict: "rename"` to
+   * auto-rename instead.
+   */
+  async uploadToDataset(files = null, opts = {}) {
+    const list = normalizeFiles(files, "uploadToDataset");
+    const registered = await v3UploadToDataset({
+      client: this.client,
+      path: { workflow_id: this.id },
+      body: {
+        files: list,
+        ...opts.groundTruth != null ? { ground_truth: JSON.stringify(opts.groundTruth) } : {},
+        ...opts.onConflict ? { on_conflict: opts.onConflict } : {}
+      },
+      ...opts.idempotencyKey ? { headers: { "Idempotency-Key": opts.idempotencyKey } } : {}
+    });
+    if (registered.error) throw toApiError(registered.response?.status ?? 500, registered.error, registered.response?.headers);
+    const data = registered.data;
+    return new DatasetUpload(this.id, data.document_packet_id, data.files, data.ground_truth_saved);
+  }
+  /**
+   * Client-orchestrated bulk dataset upload: one atomic call per document,
+   * in order. There is no batch endpoint — each document is bounded and
+   * independently retryable. On failure the call rejects; documents already
+   * uploaded stay registered.
+   */
+  async uploadDocumentsToDataset(documents) {
+    const uploaded = [];
+    for (const doc of documents) {
+      uploaded.push(
+        await this.uploadToDataset(doc.files, {
+          groundTruth: doc.groundTruth,
+          idempotencyKey: doc.idempotencyKey,
+          onConflict: doc.onConflict
+        })
+      );
     }
-    const submitted = await v2RunWorkflow({
+    return uploaded;
+  }
+  /**
+   * Import 1..10 HTTPS URLs server-side into one document packet, atomically.
+   * Returns an `Upload`; call `.run()` on it to start extraction.
+   */
+  async uploadFromUrls(urls, opts = {}) {
+    const staged = await v3UploadFromUrl({
       client: this.client,
       path: { workflow_id: this.id },
-      body: { file, text: opts.text ?? null }
+      body: { urls, ...opts.onConflict ? { on_conflict: opts.onConflict } : {} }
     });
-    if (submitted.error) throw toApiError(submitted.response?.status ?? 500, submitted.error);
-    return new Run(this.client, this.id, submitted.data.id);
+    if (staged.error) throw toApiError(staged.response?.status ?? 500, staged.error, staged.response?.headers);
+    const data = staged.data;
+    return new Upload(this.client, data.workflow_id, data.document_packet_id, data.files);
   }
 };
 
@@ -1109,13 +1470,16 @@ var WorkflowBuilder = class {
   }
   parse(opts = {}) {
     this.require(this.parseNode === null, "parse() can only be called once");
+    const o = opts;
     this.parseNode = {
       type: "parse",
-      id: opts.id ?? this.nextId("parse"),
-      mode: opts.mode ?? "standard",
-      ...opts.promptHint !== void 0 ? { prompt_hint: opts.promptHint } : {},
-      figure_enhancement: opts.figureEnhancement ?? false,
-      cache: opts.cache ?? true
+      id: o.id ?? this.nextId("parse"),
+      mode: o.mode ?? "standard",
+      ...o.promptHint !== void 0 ? { prompt_hint: o.promptHint } : {},
+      figure_enhancement: o.figureEnhancement ?? false,
+      cache: o.cache ?? true,
+      ...o.effort !== void 0 ? { effort: o.effort } : {},
+      ...o.scannedPages !== void 0 ? { scanned_pages: o.scannedPages } : {}
     };
     return this;
   }
@@ -1162,9 +1526,12 @@ var WorkflowBuilder = class {
     const node = {
       type: "extract",
       id: opts.id ?? this.nextId("extract"),
+      ...opts.mode !== void 0 ? { mode: opts.mode } : {},
       extraction_schema: { fields },
       ...lookupFileUploads.length > 0 ? { lookup_file_uploads: lookupFileUploads } : {},
-      ...opts.lookupSuggestion !== void 0 ? { lookup_suggestion: opts.lookupSuggestion } : {}
+      ...opts.lookupSuggestion !== void 0 ? { lookup_suggestion: opts.lookupSuggestion } : {},
+      ...opts.lookupReasoningEffort !== void 0 ? { lookup_reasoning_effort: opts.lookupReasoningEffort } : {},
+      ...opts.useImages !== void 0 ? { use_images: opts.useImages } : {}
     };
     this.extracts.push([node, branchId]);
     return this;
@@ -1246,21 +1613,22 @@ var WorkflowBuilder = class {
     }
     return { name: this.name, description: this.description, nodes, edges };
   }
-  /** Persist the workflow and return a handle you can `.run(file)` on. */
+  /** Persist the workflow and return a handle you can `.run(files)` on. */
   async create() {
-    const res = await v2CreateWorkflow({ client: this.client, body: this.build() });
-    if (res.error) throw toApiError(res.response?.status ?? 500, res.error);
+    const res = await v3CreateWorkflow({ client: this.client, body: this.build() });
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error, res.response?.headers);
     return new Workflow(this.client, res.data.id, res.data.name);
   }
-  /** Replace an existing workflow's definition and return a handle you can `.run(file)` on. */
+  /** Replace an existing workflow's typed graph and return a handle you can `.run(files)` on. */
   async update(workflowId) {
-    const res = await v2UpdateWorkflow({ client: this.client, path: { workflow_id: workflowId }, body: this.build() });
-    if (res.error) throw toApiError(res.response?.status ?? 500, res.error);
+    const res = await v3UpdateWorkflow({ client: this.client, path: { workflow_id: workflowId }, body: this.build() });
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error, res.response?.headers);
     return new Workflow(this.client, res.data.id, res.data.name);
   }
 };
 
 // src/client.ts
+var SDK_USER_AGENT = `anyformat-typescript-sdk-${package_default.version}`;
 var Anyformat = class {
   /** @internal */
   _client;
@@ -1270,47 +1638,206 @@ var Anyformat = class {
         baseUrl: opts.baseUrl ?? "https://api.anyformat.ai",
         auth: opts.apiKey,
         // Identifies the caller in our logs (Datadog facet). Plain HTTP callers
-        // send no such header and are logged as origin "api".
-        headers: { "x-anyformat-origin": "js-sdk" }
+        // send no such header and are logged as origin "api". User-Agent is
+        // ignored by browsers (forbidden header) but used by Node fetch.
+        headers: {
+          "x-anyformat-origin": "js-sdk",
+          "User-Agent": SDK_USER_AGENT
+        }
       })
     );
   }
   workflow(name, description) {
     return new WorkflowBuilder(this._client, name, description);
   }
-  async listWorkflows(opts) {
-    const res = await v2ListWorkflows({
+  async listWorkflows(opts = {}) {
+    const res = await v3ListWorkflows({
+      client: this._client,
+      query: { limit: opts.limit, cursor: opts.cursor }
+    });
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error, res.response?.headers);
+    return {
+      items: res.data.items.map((r) => new Workflow(this._client, r.id, r.name)),
+      nextCursor: res.data.next_cursor ?? null
+    };
+  }
+  /** Retrieve a workflow with its complete typed graph inline (round-trippable into `updateWorkflow`). */
+  async getWorkflow(workflowId) {
+    const res = await v3GetWorkflow({ client: this._client, path: { workflow_id: workflowId } });
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error, res.response?.headers);
+    return res.data;
+  }
+  /**
+   * Replace a workflow's typed graph (atomic). Accepts the shape `getWorkflow`
+   * returns — echo each field's `persistent_id` unchanged (including across
+   * renames) to keep the field's identity; omit it for new fields.
+   */
+  async updateWorkflow(workflowId, definition) {
+    const res = await v3UpdateWorkflow({
       client: this._client,
-      query: { page: opts?.page, page_size: opts?.pageSize, status: opts?.status }
+      path: { workflow_id: workflowId },
+      // The PATCH body forbids unknown keys, so a fetched detail's read-only
+      // fields (id, timestamps) must not be forwarded.
+      body: {
+        name: definition.name,
+        description: definition.description,
+        nodes: definition.nodes,
+        edges: definition.edges
+      }
     });
-    if (res.error) throw toApiError(res.response?.status ?? 500, res.error);
-    return res.data.results.map((r) => new Workflow(this._client, r.id, r.name ?? ""));
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error, res.response?.headers);
+    return res.data;
   }
   async deleteWorkflow(workflowId) {
-    const res = await v2DeleteWorkflow({
+    const res = await v3DeleteWorkflow({
       client: this._client,
       path: { workflow_id: workflowId }
     });
-    if (res.error) throw toApiError(res.response?.status ?? 500, res.error);
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error, res.response?.headers);
     return workflowId;
   }
+  /** Stage 1..100 files as one document packet without running it. Returns an `Upload`. */
+  upload(workflowId, files, opts = {}) {
+    return new Workflow(this._client, workflowId, "").upload(files, opts);
+  }
+  /** Upload 1..100 files (+ optional ground truth) as one dataset collection. Returns a `DatasetUpload`. */
+  uploadToDataset(workflowId, files, opts = {}) {
+    return new Workflow(this._client, workflowId, "").uploadToDataset(files, opts);
+  }
+  /** Bulk-upload documents into a workflow's dataset, one atomic call per document. */
+  uploadDocumentsToDataset(workflowId, documents) {
+    return new Workflow(this._client, workflowId, "").uploadDocumentsToDataset(documents);
+  }
+  async getDocumentPacket(documentPacketId) {
+    const res = await v3GetDocumentPacket({
+      client: this._client,
+      path: { document_packet_id: documentPacketId }
+    });
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error, res.response?.headers);
+    return res.data;
+  }
+  /** Delete a document packet and all its files. Irreversible. */
+  async deleteDocumentPacket(documentPacketId) {
+    const res = await v3DeleteDocumentPacket({
+      client: this._client,
+      path: { document_packet_id: documentPacketId }
+    });
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error, res.response?.headers);
+    return documentPacketId;
+  }
+  /** Run (or re-run) a document packet on the latest version of its workflow. */
+  async runDocumentPacket(documentPacketId, opts = {}) {
+    const res = await v3RunDocumentPacket({
+      client: this._client,
+      path: { document_packet_id: documentPacketId },
+      ...opts.idempotencyKey ? { headers: { "Idempotency-Key": opts.idempotencyKey } } : {}
+    });
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error, res.response?.headers);
+    const data = res.data;
+    return new Run(this._client, data.run_id, data.workflow_id, data.document_packet_id, data.status);
+  }
+  async listDocumentPackets(workflowId, opts = {}) {
+    const res = await v3ListWorkflowDocumentPackets({
+      client: this._client,
+      path: { workflow_id: workflowId },
+      query: { limit: opts.limit, cursor: opts.cursor }
+    });
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error, res.response?.headers);
+    return { items: res.data.items, nextCursor: res.data.next_cursor ?? null };
+  }
+  async listRuns(workflowId, opts = {}) {
+    const res = await v3ListWorkflowRuns({
+      client: this._client,
+      path: { workflow_id: workflowId },
+      query: { limit: opts.limit, cursor: opts.cursor }
+    });
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error, res.response?.headers);
+    return { items: res.data.items, nextCursor: res.data.next_cursor ?? null };
+  }
+  /**
+   * Every workflow, following `nextCursor` across pages so no rows are silently
+   * truncated. Lazy — each page is fetched on demand as the iterator advances.
+   */
+  async *iterWorkflows(opts = {}) {
+    let cursor;
+    for (; ; ) {
+      const page = await this.listWorkflows({ limit: opts.limit, cursor });
+      yield* page.items;
+      if (page.nextCursor === null) return;
+      cursor = page.nextCursor;
+    }
+  }
+  /** Every document packet of a workflow, following `nextCursor` across pages. Lazy. */
+  async *iterDocumentPackets(workflowId, opts = {}) {
+    let cursor;
+    for (; ; ) {
+      const page = await this.listDocumentPackets(workflowId, { limit: opts.limit, cursor });
+      yield* page.items;
+      if (page.nextCursor === null) return;
+      cursor = page.nextCursor;
+    }
+  }
+  /** Every run of a workflow, following `nextCursor` across pages. Lazy. */
+  async *iterRuns(workflowId, opts = {}) {
+    let cursor;
+    for (; ; ) {
+      const page = await this.listRuns(workflowId, { limit: opts.limit, cursor });
+      yield* page.items;
+      if (page.nextCursor === null) return;
+      cursor = page.nextCursor;
+    }
+  }
+  /** Retrieve one run: lifecycle status plus results inline once `processed`. */
+  async getRun(runId) {
+    const res = await v3GetRun({ client: this._client, path: { run_id: runId } });
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error, res.response?.headers);
+    return res.data;
+  }
+  /**
+   * Parse a document with the platform's atomic parse operation (fast lite
+   * parse). Returns the run id; poll `getParseMarkdown(runId)` for the parsed
+   * markdown.
+   */
+  async parse(file) {
+    const res = await v3Parse({ client: this._client, body: { file } });
+    if (res.error !== void 0) throw toApiError(res.response?.status ?? 500, res.error, res.response?.headers);
+    return res.data.run_id;
+  }
+  /**
+   * Poll a parse run. Returns the parsed markdown once the run is `processed`,
+   * or `null` while it is still queued or in progress.
+   */
+  async getParseMarkdown(runId) {
+    const run = await this.getRun(runId);
+    if (run.status === "processed") {
+      const markdown = run.results?.parse?.markdown;
+      if (markdown == null) throw new AnyformatError(`Run ${runId} is processed but the API returned no results`);
+      return markdown;
+    }
+    if (run.status === "error") throw new ExtractionFailedError(runId);
+    if (run.status === "cancelled") throw new ExtractionCancelledError(runId);
+    return null;
+  }
 };
 
 // src/schema.ts
-function withLookup(base, opts) {
-  if (opts?.lookup) return { ...base, lookup: true };
-  return base;
+function withOpts(base, opts) {
+  return {
+    ...base,
+    ...opts?.source && opts.source !== "extraction" ? { source: opts.source } : {},
+    ...opts?.persistentId !== void 0 ? { persistent_id: opts.persistentId } : {}
+  };
 }
 var Schema = {
-  string: (name, description, opts) => withLookup({ data_type: "string", name, description }, opts),
-  integer: (name, description, opts) => withLookup({ data_type: "integer", name, description }, opts),
-  float: (name, description, opts) => withLookup({ data_type: "float", name, description }, opts),
-  boolean: (name, description, opts) => withLookup({ data_type: "boolean", name, description }, opts),
-  date: (name, description, opts) => withLookup({ data_type: "date", name, description }, opts),
-  datetime: (name, description, opts) => withLookup({ data_type: "datetime", name, description }, opts),
-  enum: (name, description, options, opts) => withLookup({ data_type: "enum", name, description, enum_options: options }, opts),
-  multiSelect: (name, description, options, opts) => withLookup({ data_type: "multi_select", name, description, enum_options: options }, opts),
-  object: (name, description, fields, opts) => withLookup({ data_type: "object", name, description, nested_fields: fields }, opts),
+  string: (name, description, opts) => withOpts({ data_type: "string", name, description }, opts),
+  integer: (name, description, opts) => withOpts({ data_type: "integer", name, description }, opts),
+  float: (name, description, opts) => withOpts({ data_type: "float", name, description }, opts),
+  boolean: (name, description, opts) => withOpts({ data_type: "boolean", name, description }, opts),
+  date: (name, description, opts) => withOpts({ data_type: "date", name, description }, opts),
+  datetime: (name, description, opts) => withOpts({ data_type: "datetime", name, description }, opts),
+  enum: (name, description, options, opts) => withOpts({ data_type: "enum", name, description, enum_options: options }, opts),
+  multiSelect: (name, description, options, opts) => withOpts({ data_type: "multi_select", name, description, enum_options: options }, opts),
+  object: (name, description, fields, opts) => withOpts({ data_type: "object", name, description, nested_fields: fields }, opts),
   option: (name, description) => ({ name, description })
 };
 // Annotate the CommonJS export names for ESM import in node:
@@ -1318,19 +1845,28 @@ var Schema = {
   APIError,
   Anyformat,
   AnyformatError,
-  BadRequest,
-  Forbidden,
-  NotFound,
+  BadRequestError,
+  DatasetUpload,
+  ExtractionCancelledError,
+  ExtractionFailedError,
+  ForbiddenError,
+  InsufficientScopeError,
+  NotFoundError,
   ParseView,
-  RateLimited,
+  PaymentRequiredError,
+  RateLimitedError,
   Result,
   Run,
-  SDKTimeout,
+  RunFailedError,
+  SDKTimeoutError,
   Schema,
   ServerError,
-  Unauthorized,
+  TermsAcceptanceRequiredError,
+  UnauthorizedError,
+  Upload,
   Workflow,
   WorkflowBuilder,
-  WorkflowBuilderError
+  WorkflowBuilderError,
+  WorkflowNameConflictError
 });
 //# sourceMappingURL=index.cjs.map