@docmana/sdk 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,11 +1,19 @@
 # Changelog
 
-## 0.18.0
-- Expose the optional aggregate `verdict` on `DocmanaExecutionResult`, preserving
-  the `VALID`, `PARTIAL`, `WARNING`, `FAILED`, or `UNKNOWN` value computed by
-  Docmana API and returned by consumer-edge.
+## 0.19.0 - 2026-08-04
 
-## 0.17.0
+- Add synchronous and asynchronous V2 partial flow execution through Consumer Edge.
+- Use `executionScope`, `flowVersion`, and `classificationNodeNames` in the
+  multipart body, leaving only `organization` in the query string.
+- Return the standard `DocmanaExecutionResult` shape with optional
+  `partialExecution` metadata.
+
+## 0.18.0
+- Expose the optional aggregate `verdict` on `DocmanaExecutionResult`, preserving
+  the `VALID`, `PARTIAL`, `WARNING`, `FAILED`, or `UNKNOWN` value computed by
+  Docmana API and returned by consumer-edge.
+
+## 0.17.0
 - Expose the optional `flowVersion` on `DocmanaExecutionResult`, preserving the
   exact Docmana flow version used by an execution in polling and callback results.
 

package/README.md

@@ -115,6 +115,11 @@ use `RunFlowParams` for request data:
 - `runFlowAsync(flowId, params, options?)` posts multipart files to
   `POST /v1/flows/:flowId/execute-async` and returns
   `{ executionResultId, fileIds }`.
+- `runPartialFlow(flowId, params, options?)` executes classification, extraction,
+  or extraction with validation synchronously through Consumer Edge. It returns
+  the standard `DocmanaExecutionResult` with `partialExecution` metadata.
+- `runPartialFlowAsync(flowId, params, options?)` starts the same partial execution
+  asynchronously and returns `{ executionResultId, fileIds }` for standard polling.
 - `getStatus(executionResultId)` calls
   `GET /v1/executions/:executionResultId/status`.
 - `getResult(executionResultId, signal?, language?)` calls
@@ -129,6 +134,17 @@ the SDK waits that many milliseconds before the next status call. If the header
 is absent, the SDK falls back to capped exponential full jitter between
 `pollIntervalMs` and `pollMaxIntervalMs`. `Retry-After` on `429` always wins.
 
+```ts
+const partial = await docmana.runPartialFlow("<flow-id>", {
+  files: ["./contract.pdf"],
+  executionScope: "extraction_and_validation",
+  flowVersion: "published",
+  classificationNodeNames: ["classificationContract"],
+});
+
+console.log(partial.documents, partial.partialExecution);
+```
+
 ```ts
 const flows = await docmana.listFlows();
 console.log(flows.map((flow) => `${flow.id}: ${flow.name} (${flow.state})`).join("\n"));

package/dist/api/run-partial-flow.d.ts

@@ -0,0 +1,8 @@
+import type { ResolvedPart } from "../files/resolve-input.js";
+import type { HttpClient } from "../http/http-client.js";
+import type { DocmanaExecutionResult, RunPartialFlowAsyncParams, RunPartialFlowParams } from "../types.js";
+export declare function runPartialFlow(http: HttpClient, flowId: string, parts: ResolvedPart[], params: RunPartialFlowParams, signal?: AbortSignal): Promise<DocmanaExecutionResult>;
+export declare function runPartialFlowAsync(http: HttpClient, flowId: string, parts: ResolvedPart[], params: RunPartialFlowAsyncParams, signal?: AbortSignal): Promise<{
+    executionResultId: string;
+    fileIds: string[];
+}>;

package/dist/cli.mjs

@@ -282,6 +282,39 @@ async function runFlow(http, flowId, parts, signal, useDraftVersion = false, con
   );
 }
 
+// src/sdk/api/run-partial-flow.ts
+function buildRequest(flowId, parts, params, asyncMode) {
+  const form = new FormData();
+  for (const part of parts) {
+    form.append("files", new File([part.data], part.filename, { type: part.contentType }));
+  }
+  if (params.context !== void 0) form.append("jsonContext", JSON.stringify(params.context));
+  form.append("executionScope", params.executionScope);
+  if (params.flowVersion !== void 0) form.append("flowVersion", params.flowVersion);
+  for (const name of params.classificationNodeNames ?? []) {
+    form.append("classificationNodeNames", name);
+  }
+  const suffix = asyncMode ? "partial-execute-async" : "partial-execute";
+  const path = `/flows/${flowId}/${suffix}`;
+  return {
+    path: params.organization ? `${path}?organization=${encodeURIComponent(params.organization)}` : path,
+    form
+  };
+}
+async function runPartialFlow(http, flowId, parts, params, signal) {
+  const { path, form } = buildRequest(flowId, parts, params, false);
+  return http.requestJson("POST", path, { body: form, signal });
+}
+async function runPartialFlowAsync(http, flowId, parts, params, signal) {
+  const { path, form } = buildRequest(flowId, parts, params, true);
+  if (params.callbackUrl !== void 0) form.append("callbackUrl", params.callbackUrl);
+  if (params.language !== void 0) form.append("language", params.language);
+  return http.requestJson("POST", path, {
+    body: form,
+    signal
+  });
+}
+
 // src/sdk/status.ts
 function normalizeStatus(status, fallback = "UNKNOWN") {
   if (typeof status !== "string") return fallback;
@@ -535,6 +568,14 @@ var Docmana = class {
       params.organization
     );
   }
+  async runPartialFlow(flowId, params, options = {}) {
+    const parts = await resolveInputs(params);
+    return runPartialFlow(this.http, flowId, parts, params, options.signal);
+  }
+  async runPartialFlowAsync(flowId, params, options = {}) {
+    const parts = await resolveInputs(params);
+    return runPartialFlowAsync(this.http, flowId, parts, params, options.signal);
+  }
   async getStatus(executionResultId, signal, organization) {
     return getStatus(this.http, executionResultId, signal, organization);
   }