@anyformat/sdk 0.2.1 → 0.2.3

package/dist/index.js

@@ -1,27 +1,118 @@
+// package.json
+var package_default = {
+  name: "@anyformat/sdk",
+  version: "0.2.3",
+  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"',
+    "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",
+    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
 import { readFileSync } from "fs";
 import { basename } from "path";
 
+// src/parse-view.ts
+var ParseView = class {
+  /** @internal */
+  constructor(parse) {
+    this.parse = parse;
+  }
+  parse;
+  get markdown() {
+    return this.parse.markdown ?? null;
+  }
+  get text() {
+    return this.parse.text ?? null;
+  }
+  get blocks() {
+    return this.parse.blocks ?? [];
+  }
+  /**
+   * Document-level confidence (0-100) in the parsed content. May be `null` for
+   * some parse modes — fall back to `layoutConfidence`.
+   */
+  get parseConfidence() {
+    return this.parse.parse_confidence ?? null;
+  }
+  /**
+   * Document-level confidence (0-100) in the page layout (block positions).
+   * `null` when not available.
+   */
+  get layoutConfidence() {
+    return this.parse.layout_confidence ?? null;
+  }
+};
+
 // src/result.ts
 var Result = class {
   constructor(raw) {
     this.raw = raw;
   }
   raw;
+  _parse;
   get collectionId() {
     return this.raw.collection_id;
   }
   get extractions() {
     return this.raw.extractions ?? [];
   }
+  /**
+   * Typed view over the parse node's output, or `null` when the workflow has
+   * no parse node. Cached so repeated access doesn't re-wrap.
+   */
+  get parse() {
+    if (this._parse === void 0) {
+      const raw = this.raw.parse;
+      this._parse = raw ? new ParseView(raw) : null;
+    }
+    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.
+   *
+   * Parameterise with the declared schema type to type `.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;
+    if (value === void 0 || Array.isArray(value)) return void 0;
+    return value;
   }
 };
 
@@ -38,35 +129,41 @@ var APIError = class extends AnyformatError {
   status;
   body;
 };
-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 ForbiddenError = class extends APIError {
 };
-var NotFound = class extends APIError {
+var NotFoundError = class extends APIError {
 };
-var RateLimited = class extends APIError {
+var RateLimitedError = class extends APIError {
 };
 var ServerError = class extends APIError {
 };
-var SDKTimeout = class extends AnyformatError {
+var BadRequest = BadRequestError;
+var Unauthorized = UnauthorizedError;
+var Forbidden = ForbiddenError;
+var NotFound = NotFoundError;
+var RateLimited = RateLimitedError;
+var SDKTimeoutError = class extends AnyformatError {
 };
+var SDKTimeout = SDKTimeoutError;
 var WorkflowBuilderError = class extends AnyformatError {
 };
 function toApiError(status, body) {
   const message = `AnyFormat API error (${status})`;
   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 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);
     default:
       return status >= 500 ? new ServerError(status, message, body) : new APIError(status, message, body);
   }
@@ -883,9 +980,29 @@ 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 v2Parse = (options) => (options.client ?? client).post({
+  ...formDataBodySerializer,
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v2/operations/parse",
+  ...options,
+  headers: {
+    "Content-Type": null,
+    ...options.headers
+  }
+});
+var v2ParseResult = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v2/operations/parse/{job_id}",
+  ...options
+});
+var v2ListWorkflows = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v2/workflows/",
+  ...options
+});
 var v2CreateWorkflow = (options) => (options.client ?? client).post({
   security: [{ scheme: "bearer", type: "http" }],
   url: "/v2/workflows/",
@@ -895,11 +1012,30 @@ var v2CreateWorkflow = (options) => (options.client ?? client).post({
     ...options.headers
   }
 });
+var v2DeleteWorkflow = (options) => (options.client ?? client).delete({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v2/workflows/{workflow_id}/",
+  ...options
+});
+var v2UpdateWorkflow = (options) => (options.client ?? client).put({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v2/workflows/{workflow_id}/",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
 var v2GetFileResults = (options) => (options.client ?? client).get({
   security: [{ scheme: "bearer", type: "http" }],
   url: "/v2/workflows/{workflow_id}/files/{collection_id}/results/",
   ...options
 });
+var v2RunFile = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v2/workflows/{workflow_id}/files/{file_id}/run/",
+  ...options
+});
 var v2RunWorkflow = (options) => (options.client ?? client).post({
   ...formDataBodySerializer,
   security: [{ scheme: "bearer", type: "http" }],
@@ -910,48 +1046,36 @@ var v2RunWorkflow = (options) => (options.client ?? client).post({
     ...options.headers
   }
 });
+var v2UploadFile = (options) => (options.client ?? client).post({
+  ...formDataBodySerializer,
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/v2/workflows/{workflow_id}/upload/",
+  ...options,
+  headers: {
+    "Content-Type": null,
+    ...options.headers
+  }
+});
 
 // src/run.ts
 var Run = class {
-  constructor(client2, request, file, text) {
+  /** @internal */
+  constructor(client2, workflowId, id) {
     this.client = client2;
-    this.request = request;
-    this.file = file;
-    this.text = text;
+    this.workflowId = workflowId;
+    this.id = id;
   }
   client;
-  request;
-  file;
-  text;
-  workflowId = null;
-  collectionId = null;
-  /**
-   * Create the workflow and submit the document — exactly once per `Run`.
-   * Memoized so that retrying `wait()` after an `SDKTimeout` resumes polling
-   * the in-flight run instead of creating a duplicate workflow + submission.
-   */
-  async submit() {
-    if (this.collectionId !== null) return;
-    const created = await v2CreateWorkflow({ client: this.client, body: this.request });
-    if (created.error) throw toApiError(created.response?.status ?? 500, created.error);
-    this.workflowId = created.data.id;
-    const submitted = await v2RunWorkflow({
-      client: this.client,
-      path: { workflow_id: this.workflowId },
-      body: { file: this.file, text: this.text }
-    });
-    if (submitted.error) throw toApiError(submitted.response?.status ?? 500, submitted.error);
-    this.collectionId = submitted.data.id;
-  }
+  workflowId;
+  id;
   async wait(opts = {}) {
-    const timeoutMs = opts.timeoutMs ?? 12e4;
-    const pollMs = opts.pollMs ?? 2e3;
-    await this.submit();
+    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.collectionId }
+        path: { workflow_id: this.workflowId, collection_id: this.id }
       });
       if (!results.error) return new Result(results.data);
       if (results.response?.status !== 412) {
@@ -959,7 +1083,89 @@ var Run = class {
       }
       await new Promise((resolve) => setTimeout(resolve, pollMs));
     }
-    throw new SDKTimeout(`Extraction did not complete within ${timeoutMs}ms`);
+    throw new SDKTimeoutError(`Extraction did not complete within ${timeoutMs}ms`);
+  }
+};
+
+// src/upload.ts
+var Upload = class {
+  /** @internal */
+  constructor(client2, workflowId, collectionId, fileId) {
+    this.client = client2;
+    this.workflowId = workflowId;
+    this.collectionId = collectionId;
+    this.fileId = fileId;
+  }
+  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({
+      client: this.client,
+      path: { workflow_id: this.workflowId, file_id: this.fileId }
+    });
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error);
+    return new Run(this.client, this.workflowId, res.data.id ?? this.collectionId);
+  }
+};
+
+// 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 Workflow = class {
+  /** @internal */
+  constructor(client2, id, name) {
+    this.client = client2;
+    this.id = id;
+    this.name = name;
+  }
+  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({
+      client: this.client,
+      path: { workflow_id: this.id },
+      body: { file }
+    });
+    if (submitted.error) throw toApiError(submitted.response?.status ?? 500, submitted.error);
+    return new Run(this.client, this.id, submitted.data.id);
+  }
+  /**
+   * Stage a document in this workflow 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({
+      client: this.client,
+      path: { workflow_id: this.id },
+      body: { file }
+    });
+    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"
+      );
+    }
+    return new Upload(this.client, this.id, collectionId, staged.data.file_id ?? null);
   }
 };
 
@@ -989,12 +1195,21 @@ 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
+      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.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 } : {}
     };
     return this;
   }
@@ -1041,9 +1256,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;
@@ -1125,30 +1343,22 @@ var WorkflowBuilder = class {
     }
     return { name: this.name, description: this.description, nodes, edges };
   }
-  /** Persist the workflow and return its id. */
+  /** Persist the workflow and return a handle you can `.run(file)` on. */
   async create() {
     const res = await v2CreateWorkflow({ client: this.client, body: this.build() });
     if (res.error) throw toApiError(res.response?.status ?? 500, res.error);
-    return res.data.id;
+    return new Workflow(this.client, res.data.id, res.data.name);
   }
-  /** Create the workflow, submit a document, and return a pending `Run`. */
-  run(file = null, opts = {}) {
-    this.require(
-      !(file === null && opts.text === void 0),
-      "run() requires a document \u2014 pass a file or opts.text"
-    );
-    if (file !== null) {
-      const filename = file.name;
-      this.require(
-        typeof filename === "string" && filename.length > 0,
-        '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'
-      );
-    }
-    return new Run(this.client, this.build(), file, opts.text ?? null);
+  /** Replace an existing workflow's definition and return a handle you can `.run(file)` 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);
+    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;
@@ -1156,13 +1366,72 @@ var Anyformat = class {
     this._client = createClient(
       createConfig({
         baseUrl: opts.baseUrl ?? "https://api.anyformat.ai",
-        auth: opts.apiKey
+        auth: opts.apiKey,
+        // Identifies the caller in our logs (Datadog facet). Plain HTTP callers
+        // 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({
+      client: this._client,
+      query: { page: opts?.page, page_size: opts?.pageSize, status: opts?.status }
+    });
+    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 ?? ""));
+  }
+  async deleteWorkflow(workflowId) {
+    const res = await v2DeleteWorkflow({
+      client: this._client,
+      path: { workflow_id: workflowId }
+    });
+    if (res.error) throw toApiError(res.response?.status ?? 500, res.error);
+    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));
+    }
+    return runs;
+  }
+  /**
+   * Parse a document with the platform's atomic `/parse` operation (fast lite
+   * parse). Returns an opaque `jobId`; poll `getParseMarkdown(jobId)` 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;
+  }
+  /**
+   * Poll a parse job. Returns the parsed markdown once the job is done, or
+   * `null` while it is still processing.
+   */
+  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;
+  }
 };
 
 // src/schema.ts
@@ -1187,15 +1456,24 @@ export {
   Anyformat,
   AnyformatError,
   BadRequest,
+  BadRequestError,
   Forbidden,
+  ForbiddenError,
   NotFound,
+  NotFoundError,
+  ParseView,
   RateLimited,
+  RateLimitedError,
   Result,
   Run,
   SDKTimeout,
+  SDKTimeoutError,
   Schema,
   ServerError,
   Unauthorized,
+  UnauthorizedError,
+  Upload,
+  Workflow,
   WorkflowBuilder,
   WorkflowBuilderError
 };