@anyformat/sdk 0.2.2 → 0.2.3

package/dist/index.js

@@ -1,3 +1,46 @@
+// 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";
@@ -62,10 +105,14 @@ var Result = class {
    * 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;
   }
 };
 
@@ -82,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);
   }
@@ -927,9 +980,24 @@ 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/",
@@ -963,6 +1031,11 @@ var v2GetFileResults = (options) => (options.client ?? client).get({
   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" }],
@@ -973,6 +1046,16 @@ 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 {
@@ -1000,11 +1083,49 @@ 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) {
@@ -1016,29 +1137,36 @@ var Workflow = class {
   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'
-        );
-      }
-    }
+  async run(file = null) {
+    validateDocument(file, "run");
     const submitted = await v2RunWorkflow({
       client: this.client,
       path: { workflow_id: this.id },
-      body: { file, text: opts.text ?? null }
+      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);
+  }
 };
 
 // src/builder.ts
@@ -1067,13 +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,
-      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.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;
   }
@@ -1120,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;
@@ -1219,6 +1358,7 @@ var WorkflowBuilder = class {
 };
 
 // src/client.ts
+var SDK_USER_AGENT = `anyformat-typescript-sdk-${package_default.version}`;
 var Anyformat = class {
   /** @internal */
   _client;
@@ -1228,8 +1368,12 @@ 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
+        }
       })
     );
   }
@@ -1252,6 +1396,42 @@ var Anyformat = class {
     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
@@ -1276,16 +1456,23 @@ export {
   Anyformat,
   AnyformatError,
   BadRequest,
+  BadRequestError,
   Forbidden,
+  ForbiddenError,
   NotFound,
+  NotFoundError,
   ParseView,
   RateLimited,
+  RateLimitedError,
   Result,
   Run,
   SDKTimeout,
+  SDKTimeoutError,
   Schema,
   ServerError,
   Unauthorized,
+  UnauthorizedError,
+  Upload,
   Workflow,
   WorkflowBuilder,
   WorkflowBuilderError