@docmana/sdk 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -1,11 +1,28 @@
-# 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.17.0
+# Changelog
+
+## 0.20.0 - 2026-08-04
+
+- Add `detectFraud` to start a Consumer Edge fraud-detection job, poll its
+  status, and return the normalized verdict and findings.
+- Add `detectFraudAsync`, `getFraudDetectionStatus`, and
+  `getFraudDetectionResult` for callers that manage polling themselves.
+- Respect `X-Poll-After` and `Retry-After`, retry transient status failures,
+  and expose typed failure, timeout, and cancellation errors.
+
+## 0.19.0 - 2026-08-04
+
+- 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

@@ -32,6 +32,21 @@ const result = await docmana.runFlow("<flow-id>", {
 console.log(result.status, result.executionId);
 ```
 
+Fraud detection follows the same asynchronous Consumer Edge pattern. The
+high-level call starts the job, polls Consumer, and returns the normalized
+result:
+
+```ts
+const fraud = await docmana.detectFraud({
+  documentUrl: "https://downloads.example.com/claim.pdf?token=...",
+  filename: "claim.pdf",
+  analystContext: "Travel claim; verify the invoice total.",
+  organization: "acme",
+});
+
+console.log(fraud.verdict, fraud.confidence, fraud.findings);
+```
+
 ## Authentication
 
 The public SDK is Bearer-only. It does not acquire OAuth tokens and it never
@@ -53,16 +68,16 @@ static `accessToken`, `401` is returned as an auth error without retry.
 
 ## Configuration
 
-| Field               | Type                                                                  | Required | Description                                                  |
-| ------------------- | --------------------------------------------------------------------- | -------- | ------------------------------------------------------------ |
-| `apiBaseUrl`        | `string`                                                              | Yes      | Base URL of Consumer API, including version when applicable. |
-| `accessToken`       | `string`                                                              | One of   | Static Bearer token sent to Consumer.                        |
-| `getAccessToken`    | `(options?: { forceRefresh?: boolean }) => string \| Promise<string>` | One of   | Token provider for renewable Bearer tokens.                  |
-| `timeoutMs`         | `number`                                                              | No       | Maximum polling time for `runFlow`. Default: 5 minutes.      |
-| `pollIntervalMs`    | `number`                                                              | No       | Fallback minimum delay between status polls. Default: 2s.    |
-| `pollMaxIntervalMs` | `number`                                                              | No       | Fallback maximum polling delay. Default: 10s.                |
-| `fetch`             | `typeof fetch`                                                        | No       | Custom fetch implementation.                                 |
-| `headers`           | `Record<string, string>`                                              | No       | Extra headers sent on every Consumer request.                |
+| Field               | Type                                                                  | Required | Description                                                               |
+| ------------------- | --------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------- |
+| `apiBaseUrl`        | `string`                                                              | Yes      | Base URL of Consumer API, including version when applicable.              |
+| `accessToken`       | `string`                                                              | One of   | Static Bearer token sent to Consumer.                                     |
+| `getAccessToken`    | `(options?: { forceRefresh?: boolean }) => string \| Promise<string>` | One of   | Token provider for renewable Bearer tokens.                               |
+| `timeoutMs`         | `number`                                                              | No       | Maximum polling time for `runFlow` and `detectFraud`. Default: 5 minutes. |
+| `pollIntervalMs`    | `number`                                                              | No       | Fallback minimum delay between status polls. Default: 2s.                 |
+| `pollMaxIntervalMs` | `number`                                                              | No       | Fallback maximum polling delay. Default: 10s.                             |
+| `fetch`             | `typeof fetch`                                                        | No       | Custom fetch implementation.                                              |
+| `headers`           | `Record<string, string>`                                              | No       | Extra headers sent on every Consumer request.                             |
 
 `apiBaseUrl` is required so a migrated SDK cannot accidentally call
 `https://api.docmana.ai`.
@@ -115,6 +130,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
@@ -123,12 +143,33 @@ use `RunFlowParams` for request data:
 - `runFlow(flowId, params, options?)` starts async execution, polls status, fetches the
   result, respects `X-Poll-After` and `429 Retry-After` while polling, and throws
   `DocmanaExecutionError` if the result status is `FAILED`.
+- `detectFraud(params, options?)` starts fraud detection from `documentUrl`, polls
+  Consumer until `COMPLETED` or `FAILED`, and returns the normalized verdict and findings.
+- `detectFraudAsync(params, options?)` starts fraud detection and immediately returns
+  `{ jobId, status }` without polling.
+- `getFraudDetectionStatus(jobId, signal?, organization?)` and
+  `getFraudDetectionResult(jobId, signal?, organization?)` provide the lower-level
+  polling workflow.
 
 Consumer is the polling authority. When `GET /status` returns `X-Poll-After`,
 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.
 
+The SDK does not log or return `documentUrl`. Signed query parameters are sent
+only in the JSON request body to Consumer Edge.
+
+```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"));
@@ -261,15 +302,16 @@ from the Bearer token.
 Every SDK error extends `DocmanaError`, which carries `.status`, `.code`, and an
 optional `.requestId` when available.
 
-| Error                    | Thrown when                                                                |
-| ------------------------ | -------------------------------------------------------------------------- |
-| `DocmanaRequestError`    | `400` bad request.                                                         |
-| `DocmanaAuthError`       | `401` rejected or expired Bearer token.                                    |
-| `DocmanaPermissionError` | `403` missing permission.                                                  |
-| `DocmanaNotFoundError`   | `404` flow or execution not found.                                         |
-| `DocmanaExecutionError`  | The flow finished with status `"FAILED"`. Carries `.errors` and `.result`. |
-| `DocmanaTimeoutError`    | Polling exceeded `timeoutMs`.                                              |
-| `DocmanaAbortError`      | The provided `AbortSignal` fired.                                          |
+| Error                        | Thrown when                                                                                 |
+| ---------------------------- | ------------------------------------------------------------------------------------------- |
+| `DocmanaRequestError`        | `400` bad request.                                                                          |
+| `DocmanaAuthError`           | `401` rejected or expired Bearer token.                                                     |
+| `DocmanaPermissionError`     | `403` missing permission.                                                                   |
+| `DocmanaNotFoundError`       | `404` flow or execution not found.                                                          |
+| `DocmanaExecutionError`      | The flow finished with status `"FAILED"`. Carries `.errors` and `.result`.                  |
+| `DocmanaFraudDetectionError` | Fraud detection finished with status `"FAILED"`. Carries `.jobId`, `.error`, and `.result`. |
+| `DocmanaTimeoutError`        | Polling exceeded `timeoutMs`.                                                               |
+| `DocmanaAbortError`          | The provided `AbortSignal` fired.                                                           |
 
 ## Local development with yalc
 

package/dist/api/fraud-detection.d.ts

@@ -0,0 +1,5 @@
+import type { HttpClient } from "../http/http-client.js";
+import type { FraudDetectionAccepted, FraudDetectionParams, FraudDetectionResult, FraudDetectionStatusResult } from "../types.js";
+export declare function startFraudDetection(http: HttpClient, params: FraudDetectionParams, signal?: AbortSignal): Promise<FraudDetectionAccepted>;
+export declare function getFraudDetectionStatus(http: HttpClient, jobId: string, signal?: AbortSignal, organization?: string): Promise<FraudDetectionStatusResult>;
+export declare function getFraudDetectionResult(http: HttpClient, jobId: string, signal?: AbortSignal, organization?: string): Promise<FraudDetectionResult>;

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

@@ -79,6 +79,17 @@ var DocmanaExecutionError = class extends DocmanaError {
     this.result = result;
   }
 };
+var DocmanaFraudDetectionError = class extends DocmanaError {
+  jobId;
+  error;
+  result;
+  constructor(message, result) {
+    super(message, { code: "fraud_detection_failed" });
+    this.jobId = result.jobId;
+    this.error = result.error;
+    this.result = result;
+  }
+};
 var DocmanaTimeoutError = class extends DocmanaError {
   constructor(message) {
     super(message, { code: "timeout" });
@@ -282,6 +293,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;
@@ -333,6 +377,52 @@ async function getResult(http, executionResultId, signal, language, organization
   });
 }
 
+// src/sdk/api/fraud-detection.ts
+async function startFraudDetection(http, params, signal) {
+  return http.requestJson("POST", "/fraud-detections", {
+    query: organizationQuery(params.organization),
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      documentUrl: params.documentUrl,
+      filename: params.filename,
+      ...params.analystContext === void 0 ? {} : { analystContext: params.analystContext }
+    }),
+    signal
+  });
+}
+async function getFraudDetectionStatus(http, jobId, signal, organization) {
+  const res = await http.requestRaw(
+    "GET",
+    `/fraud-detections/${encodeURIComponent(jobId)}/status`,
+    {
+      query: organizationQuery(organization),
+      signal
+    }
+  );
+  const text = await res.text();
+  const body = text ? JSON.parse(text) : { jobId, status: "" };
+  const normalized = {
+    ...body,
+    status: normalizeStatus(body.status)
+  };
+  const pollAfterMs = parsePositiveInt2(res.headers.get("x-poll-after"));
+  return pollAfterMs === void 0 ? normalized : { ...normalized, pollAfterMs };
+}
+async function getFraudDetectionResult(http, jobId, signal, organization) {
+  return http.requestJson("GET", `/fraud-detections/${encodeURIComponent(jobId)}/result`, {
+    query: organizationQuery(organization),
+    signal
+  });
+}
+function organizationQuery(organization) {
+  return organization ? { organization } : void 0;
+}
+function parsePositiveInt2(value) {
+  if (!value) return void 0;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : void 0;
+}
+
 // src/sdk/api/list-flows.ts
 async function listFlows(http, organization) {
   const path = organization ? `/flows?organization=${encodeURIComponent(organization)}` : "/flows";
@@ -477,11 +567,13 @@ async function pollUntilTerminal(opts) {
     try {
       result = normalizePollResult(await opts.check());
     } catch (err) {
-      if (!(err instanceof DocmanaRateLimitError)) throw err;
+      const retryAfterMs = err instanceof DocmanaRateLimitError ? err.retryAfterMs ?? opts.intervalMs : opts.shouldRetryError?.(err) ? fullJitterDelay(opts.intervalMs, opts.maxIntervalMs, fallbackAttempt, random) : void 0;
+      if (retryAfterMs === void 0) throw err;
       if (elapsed() >= opts.timeoutMs) {
         throw new DocmanaTimeoutError(`Execution did not finish within ${opts.timeoutMs}ms`);
       }
-      await sleep(err.retryAfterMs ?? opts.intervalMs);
+      fallbackAttempt += 1;
+      await sleep(retryAfterMs);
       continue;
     }
     const status = normalizeStatus(result.status);
@@ -535,6 +627,72 @@ var Docmana = class {
       params.organization
     );
   }
+  async detectFraudAsync(params, options = {}) {
+    return startFraudDetection(this.http, params, options.signal);
+  }
+  async getFraudDetectionStatus(jobId, signal, organization) {
+    return getFraudDetectionStatus(this.http, jobId, signal, organization);
+  }
+  async getFraudDetectionResult(jobId, signal, organization) {
+    return getFraudDetectionResult(this.http, jobId, signal, organization);
+  }
+  async detectFraud(params, options = {}) {
+    const { jobId } = await this.detectFraudAsync(params, { signal: options.signal });
+    let attempt = 0;
+    const startedAt = Date.now();
+    await pollUntilTerminal({
+      check: async () => {
+        attempt += 1;
+        try {
+          const statusResult = await this.getFraudDetectionStatus(
+            jobId,
+            options.signal,
+            params.organization
+          );
+          const nextPollAfterMs = isTerminalStatus(statusResult.status) ? void 0 : statusResult.pollAfterMs;
+          options.onPoll?.({
+            jobId,
+            status: statusResult.status,
+            attempt,
+            elapsedMs: Date.now() - startedAt,
+            nextPollAfterMs
+          });
+          return { status: statusResult.status, nextDelayMs: nextPollAfterMs };
+        } catch (err) {
+          if (err instanceof DocmanaRateLimitError) {
+            options.onRateLimit?.({
+              jobId,
+              attempt,
+              elapsedMs: Date.now() - startedAt,
+              retryAfterMs: err.retryAfterMs ?? options.pollIntervalMs ?? this.config.pollIntervalMs
+            });
+          }
+          throw err;
+        }
+      },
+      intervalMs: options.pollIntervalMs ?? this.config.pollIntervalMs,
+      maxIntervalMs: options.pollMaxIntervalMs ?? this.config.pollMaxIntervalMs,
+      timeoutMs: options.timeoutMs ?? this.config.timeoutMs,
+      signal: options.signal,
+      shouldRetryError: isTransientPollingError
+    });
+    const result = await this.getFraudDetectionResult(jobId, options.signal, params.organization);
+    if (isFailedStatus(result.status)) {
+      throw new DocmanaFraudDetectionError(
+        result.error?.message ?? `Fraud detection ${jobId} failed`,
+        result
+      );
+    }
+    return result;
+  }
+  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);
   }
@@ -623,6 +781,13 @@ var Docmana = class {
     return isTerminalStatus(status);
   }
 };
+function isTransientPollingError(error) {
+  if (error instanceof DocmanaRateLimitError) return false;
+  if (error instanceof DocmanaError) {
+    return error.status !== void 0 && error.status >= 500;
+  }
+  return error instanceof TypeError;
+}
 
 // src/cli/errors.ts
 var CliUsageError = class extends Error {