@anyformat/sdk 0.2.3 → 1.0.0

package/dist/index.js

@@ -1,7 +1,7 @@
 // package.json
 var package_default = {
   name: "@anyformat/sdk",
-  version: "0.2.3",
+  version: "1.0.0",
   description: "TypeScript SDK for the AnyFormat API",
   license: "MIT",
   author: "Anyformat <info@anyformat.ai>",
@@ -23,10 +23,10 @@ var package_default = {
     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"',
+    "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/v2.json src/sdk",
+    "gen:check": "bun run gen && git diff --exit-code -- openapi src/sdk",
     build: "tsup",
     typecheck: "tsc --noEmit",
     test: "vitest run",
@@ -84,8 +84,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 ?? [];
@@ -102,16 +102,21 @@ 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 `.value`:
+   * 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];
-    if (value === void 0 || Array.isArray(value)) return 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;
   }
 };
@@ -125,45 +130,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 BadRequestError = class extends APIError {
 };
 var UnauthorizedError = class extends APIError {
 };
+var PaymentRequiredError = class extends APIError {
+};
 var ForbiddenError = 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 BadRequest = BadRequestError;
-var Unauthorized = UnauthorizedError;
-var Forbidden = ForbiddenError;
-var NotFound = NotFoundError;
-var RateLimited = RateLimitedError;
+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 SDKTimeout = SDKTimeoutError;
+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 BadRequestError(status, message, body);
     case 401:
       return new UnauthorizedError(status, message, body);
+    case 402:
+      return new PaymentRequiredError(status, message, body);
     case 403:
       return new ForbiddenError(status, message, body);
     case 404:
       return new NotFoundError(status, message, body);
     case 429:
-      return new RateLimitedError(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);
   }
@@ -223,7 +299,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;
@@ -327,7 +403,7 @@ function createSseClient({
           break;
         }
         const backoff = Math.min(retryDelay * 2 ** (attempt - 1), sseMaxRetryDelay ?? 3e4);
-        await sleep(backoff);
+        await sleep2(backoff);
       }
     }
   };
@@ -983,73 +1059,112 @@ var createClient = (config = {}) => {
 var client = createClient(createConfig({ baseUrl: "https://api.anyformat.dev" }));
 
 // src/sdk/sdk.gen.ts
-var v2Parse = (options) => (options.client ?? client).post({
+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: "/v3/document-packets/{document_packet_id}/run/",
+  ...options
+});
+var v3Parse = (options) => (options.client ?? client).post({
   ...formDataBodySerializer,
   security: [{ scheme: "bearer", type: "http" }],
-  url: "/v2/operations/parse",
+  url: "/v3/parse/",
   ...options,
   headers: {
     "Content-Type": null,
     ...options.headers
   }
 });
-var v2ParseResult = (options) => (options.client ?? client).get({
+var v3GetRun = (options) => (options.client ?? client).get({
   security: [{ scheme: "bearer", type: "http" }],
-  url: "/v2/operations/parse/{job_id}",
+  url: "/v3/runs/{run_id}/",
   ...options
 });
-var v2ListWorkflows = (options) => (options?.client ?? client).get({
+var v3ListWorkflows = (options) => (options?.client ?? client).get({
   security: [{ scheme: "bearer", type: "http" }],
-  url: "/v2/workflows/",
+  url: "/v3/workflows/",
   ...options
 });
-var v2CreateWorkflow = (options) => (options.client ?? client).post({
+var v3CreateWorkflow = (options) => (options.client ?? client).post({
   security: [{ scheme: "bearer", type: "http" }],
-  url: "/v2/workflows/",
+  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: "/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: "/v2/workflows/{workflow_id}/files/{collection_id}/results/",
+  url: "/v3/workflows/{workflow_id}/document-packets/",
   ...options
 });
-var v2RunFile = (options) => (options.client ?? client).post({
+var v3ListWorkflowRuns = (options) => (options.client ?? client).get({
   security: [{ scheme: "bearer", type: "http" }],
-  url: "/v2/workflows/{workflow_id}/files/{file_id}/run/",
+  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 v2UploadFile = (options) => (options.client ?? client).post({
+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: "/v2/workflows/{workflow_id}/upload/",
+  url: "/v3/workflows/{workflow_id}/upload/run/",
   ...options,
   headers: {
     "Content-Type": null,
@@ -1058,73 +1173,128 @@ var v2UploadFile = (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);
+      }
+      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 new Promise((resolve) => setTimeout(resolve, pollMs));
+      await sleep(pollMs);
     }
-    throw new SDKTimeoutError(`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, collectionId, fileId) {
+  constructor(client2, workflowId, documentPacketId, files) {
     this.client = client2;
     this.workflowId = workflowId;
-    this.collectionId = collectionId;
-    this.fileId = fileId;
+    this.documentPacketId = documentPacketId;
+    this.files = files;
   }
   client;
   workflowId;
-  collectionId;
-  fileId;
-  /** Trigger extraction on the staged file and return a pending `Run`. */
-  async run() {
-    if (!this.fileId) {
-      throw new WorkflowBuilderError("This upload has no file_id \u2014 cannot run it");
-    }
-    const res = await v2RunFile({
+  documentPacketId;
+  files;
+  /** Trigger extraction on the staged packet and return a pending `Run`. */
+  async run(opts = {}) {
+    const res = await v3RunDocumentPacket({
       client: this.client,
-      path: { workflow_id: this.workflowId, file_id: this.fileId }
+      path: { document_packet_id: this.documentPacketId },
+      ...opts.idempotencyKey ? { headers: { "Idempotency-Key": opts.idempotencyKey } } : {}
     });
-    if (res.error) throw toApiError(res.response?.status ?? 500, res.error);
-    return new Run(this.client, this.workflowId, res.data.id ?? this.collectionId);
+    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
-function validateDocument(file, op) {
-  if (file === null) {
-    throw new WorkflowBuilderError(`${op}() requires a named file`);
-  }
-  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`
-    );
+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 */
@@ -1136,36 +1306,90 @@ var Workflow = class {
   client;
   id;
   name;
-  /** Submit a document against this workflow and return a pending `Run`. */
-  async run(file = null) {
-    validateDocument(file, "run");
-    const submitted = await v2RunWorkflow({
+  /** 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: { file }
+      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);
-    return new Run(this.client, this.id, submitted.data.id);
+    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 a document in this workflow WITHOUT running it (no credits spent).
-   * Returns an `Upload`; call `.run()` on it to start extraction.
+   * 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(file = null) {
-    validateDocument(file, "upload");
-    const staged = await v2UploadFile({
+  async upload(files = null, opts = {}) {
+    const list = normalizeFiles(files, "upload");
+    const staged = await v3UploadToWorkflow({
       client: this.client,
       path: { workflow_id: this.id },
-      body: { file }
+      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);
-    const collectionId = staged.data.file_collection_id;
-    if (!collectionId) {
-      throw new WorkflowBuilderError(
-        "Upload succeeded but the server did not return a file_collection_id \u2014 cannot build an Upload handle"
+    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
+        })
       );
     }
-    return new Upload(this.client, this.id, collectionId, staged.data.file_id ?? null);
+    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: { urls, ...opts.onConflict ? { on_conflict: opts.onConflict } : {} }
+    });
+    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);
   }
 };
 
@@ -1204,12 +1428,7 @@ var WorkflowBuilder = class {
       figure_enhancement: o.figureEnhancement ?? false,
       cache: o.cache ?? true,
       ...o.effort !== void 0 ? { effort: o.effort } : {},
-      ...o.ocrEffort !== void 0 ? { ocr_effort: o.ocrEffort } : {},
-      ...o.region !== void 0 ? { region: o.region } : {},
-      ...o.skipRoutingReview !== void 0 ? { skip_routing_review: o.skipRoutingReview } : {},
-      ...o.figures !== void 0 ? { figures: o.figures } : {},
-      ...o.textFormatting !== void 0 ? { text_formatting: o.textFormatting } : {},
-      ...o.routingEffort !== void 0 ? { routing_effort: o.routingEffort } : {}
+      ...o.scannedPages !== void 0 ? { scanned_pages: o.scannedPages } : {}
     };
     return this;
   }
@@ -1343,16 +1562,16 @@ 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);
   }
 };
@@ -1380,101 +1599,222 @@ var Anyformat = class {
   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 a document in a workflow without running it. Returns an `Upload`. */
-  upload(workflowId, file = null) {
-    return new Workflow(this._client, workflowId, "").upload(file);
-  }
-  /** Trigger extraction on already-uploaded files. Returns a pending `Run` per file_id. */
-  async runWorkflow(workflowId, fileIds) {
-    const runs = [];
-    for (const fileId of fileIds) {
-      const res = await v2RunFile({
-        client: this._client,
-        path: { workflow_id: workflowId, file_id: fileId }
-      });
-      if (res.error) throw toApiError(res.response?.status ?? 500, res.error);
-      runs.push(new Run(this._client, workflowId, res.data.id ?? fileId));
+  /** 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;
     }
-    return runs;
+  }
+  /** 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 an opaque `jobId`; poll `getParseMarkdown(jobId)` for the
-   * parsed markdown.
+   * 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 v2Parse({ client: this._client, body: { file } });
-    if (res.error) throw toApiError(res.response?.status ?? 500, res.error);
-    return res.data.job_id;
+    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 job. Returns the parsed markdown once the job is done, or
-   * `null` while it is still processing.
+   * 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(jobId) {
-    const res = await v2ParseResult({ client: this._client, path: { job_id: jobId } });
-    if (res.error) throw toApiError(res.response?.status ?? 500, res.error);
-    return res.data.status === "done" ? res.data.markdown ?? "" : null;
+  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 })
 };
 export {
   APIError,
   Anyformat,
   AnyformatError,
-  BadRequest,
   BadRequestError,
-  Forbidden,
+  DatasetUpload,
+  ExtractionCancelledError,
+  ExtractionFailedError,
   ForbiddenError,
-  NotFound,
+  InsufficientScopeError,
   NotFoundError,
   ParseView,
-  RateLimited,
+  PaymentRequiredError,
   RateLimitedError,
   Result,
   Run,
-  SDKTimeout,
+  RunFailedError,
   SDKTimeoutError,
   Schema,
   ServerError,
-  Unauthorized,
+  TermsAcceptanceRequiredError,
   UnauthorizedError,
   Upload,
   Workflow,
   WorkflowBuilder,
-  WorkflowBuilderError
+  WorkflowBuilderError,
+  WorkflowNameConflictError
 };
 //# sourceMappingURL=index.js.map