@anyformat/sdk 0.2.2 → 0.2.3

package/README.md

@@ -24,6 +24,22 @@ const result = await af
 result.field("vendor")?.value; // -> "Acme Corp"
 ```
 
+## Quick parse: one call → markdown
+
+`af.parse()` runs the platform's atomic `/parse` operation (a fast lite parse)
+and returns an opaque `jobId`. Poll `getParseMarkdown(jobId)` for the markdown —
+no workflow to author or manage.
+
+```ts
+const jobId = await af.parse(file); // File | Blob
+let markdown = await af.getParseMarkdown(jobId);
+while (markdown === null) {
+  await new Promise((r) => setTimeout(r, 3000));
+  markdown = await af.getParseMarkdown(jobId); // null until done
+}
+console.log(markdown);
+```
+
 ## Managing workflows
 
 ```ts
@@ -33,6 +49,29 @@ for (const wf of workflows) console.log(wf.id, wf.name);
 await af.deleteWorkflow(workflows[0].id); // -> the deleted id
 ```
 
+## Smart lookup
+
+Resolve a field by matching the document against a reference file (CSV/catalog) instead of
+reading it off the page — flag the field with `{ lookup: true }` and pass the file via
+`lookupFiles`:
+
+```ts
+await af
+  .workflow("Invoice + vendor lookup")
+  .parse()
+  .extract(
+    [
+      Schema.string("vendor_name", "Vendor as printed on the invoice."),
+      Schema.string("vendor_id", "Canonical vendor code from the catalog, joined on vendor_name.", { lookup: true }),
+    ],
+    { lookupFiles: ["vendor_catalog.csv"], lookupSuggestion: "Join vendor_name → vendor_id." },
+  )
+  .run(file)
+  .wait();
+```
+
+Full runnable example: [`examples/smart-lookup.mjs`](examples/smart-lookup.mjs).
+
 ## How it's built
 
 The wire types and the low-level HTTP client are **generated** from the API's
@@ -43,8 +82,8 @@ ergonomic layer (`Schema`, `WorkflowBuilder`, `Result`, `Anyformat`) wraps it.
 ## Regenerating (and the drift guard)
 
 ```bash
-npm run gen          # dump the v2 OpenAPI offline + regenerate src/sdk
-npm run gen:check    # regenerate and fail if the committed output drifted
+bun run gen          # dump the v2 OpenAPI offline + regenerate src/sdk
+bun run gen:check    # regenerate and fail if the committed output drifted
 ```
 
 `gen:check` runs in CI and as a pre-commit hook (scoped to changes under
@@ -55,10 +94,30 @@ caught as a type error, not just a diff.
 
 ## Scripts
 
+Install deps with `bun install --frozen-lockfile` (matches CI + the frontend
+toolchain). Then:
+
 | script | what |
 | --- | --- |
-| `npm run gen` | dump spec + regenerate `src/sdk` |
-| `npm run gen:check` | regenerate + assert no drift |
-| `npm run build` | bundle to `dist/` (ESM + CJS + types) via tsup |
-| `npm run typecheck` | `tsc --noEmit` |
-| `npm test` | vitest |
+| `bun run gen` | dump spec + regenerate `src/sdk` |
+| `bun run gen:check` | regenerate + assert no drift |
+| `bun run build` | bundle to `dist/` (ESM + CJS + types) via tsup |
+| `bun run typecheck` | `tsc --noEmit` |
+| `bun run test` | vitest |
+
+## Releasing
+
+Cut on demand — a maintainer bumps the version in a PR, then pushes a `sdk-js-vX.Y.Z` tag on the release commit. Full flow + one-time setup: [`../RELEASING.md`](../RELEASING.md). Break-glass: `./publish.sh [--build-only|--dry-run]`.
+
+## Node configuration knobs
+
+Every knob is an option on `.parse({...})` / `.extract(fields, {...})`. `parse` options are a
+`mode`-discriminated union, so a wrong-mode knob is a compile-time error.
+
+**`.parse({...})`** — `mode` (`"standard"`/`"agentic"`/`"lite"`), `promptHint`, `figureEnhancement`,
+`cache`; **agentic-only** `effort` (`"low"`/`"mid"`/`"accurate"`); **lite-only** `ocrEffort`
+(`"medium"`/`"high"`), `region` (`"eu"`/`"global"`), `skipRoutingReview`, `figures`,
+`textFormatting`, `routingEffort`.
+
+**`.extract(fields, {...})`** — `mode` (`"standard"`/`"agentic"`/`"max"`/`"lite"`), `useImages`,
+`lookupSuggestion`, `lookupReasoningEffort` (`"minimal"`/`"low"`/`"medium"`/`"high"`), `lookupFiles`.

package/dist/index.cjs

@@ -24,22 +24,72 @@ __export(index_exports, {
   Anyformat: () => Anyformat,
   AnyformatError: () => AnyformatError,
   BadRequest: () => BadRequest,
+  BadRequestError: () => BadRequestError,
   Forbidden: () => Forbidden,
+  ForbiddenError: () => ForbiddenError,
   NotFound: () => NotFound,
+  NotFoundError: () => NotFoundError,
   ParseView: () => ParseView,
   RateLimited: () => RateLimited,
+  RateLimitedError: () => RateLimitedError,
   Result: () => Result,
   Run: () => Run,
   SDKTimeout: () => SDKTimeout,
+  SDKTimeoutError: () => SDKTimeoutError,
   Schema: () => Schema,
   ServerError: () => ServerError,
   Unauthorized: () => Unauthorized,
+  UnauthorizedError: () => UnauthorizedError,
+  Upload: () => Upload,
   Workflow: () => Workflow,
   WorkflowBuilder: () => WorkflowBuilder,
   WorkflowBuilderError: () => WorkflowBuilderError
 });
 module.exports = __toCommonJS(index_exports);
 
+// 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
 var import_node_fs = require("fs");
 var import_node_path = require("path");
@@ -104,10 +154,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;
   }
 };
 
@@ -124,35 +178,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);
   }
@@ -969,9 +1029,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/",
@@ -1005,6 +1080,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" }],
@@ -1015,6 +1095,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 {
@@ -1042,11 +1132,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) {
@@ -1058,29 +1186,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
@@ -1109,13 +1244,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;
   }
@@ -1162,9 +1305,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;
@@ -1261,6 +1407,7 @@ var WorkflowBuilder = class {
 };
 
 // src/client.ts
+var SDK_USER_AGENT = `anyformat-typescript-sdk-${package_default.version}`;
 var Anyformat = class {
   /** @internal */
   _client;
@@ -1270,8 +1417,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
+        }
       })
     );
   }
@@ -1294,6 +1445,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
@@ -1319,16 +1506,23 @@ var Schema = {
   Anyformat,
   AnyformatError,
   BadRequest,
+  BadRequestError,
   Forbidden,
+  ForbiddenError,
   NotFound,
+  NotFoundError,
   ParseView,
   RateLimited,
+  RateLimitedError,
   Result,
   Run,
   SDKTimeout,
+  SDKTimeoutError,
   Schema,
   ServerError,
   Unauthorized,
+  UnauthorizedError,
+  Upload,
   Workflow,
   WorkflowBuilder,
   WorkflowBuilderError