@docmana/sdk 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,12 +1,21 @@
-# Changelog
-
-## 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.
+# 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

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`.
@@ -128,12 +143,22 @@ 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"],
@@ -277,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/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" });
@@ -366,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";
@@ -510,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);
@@ -568,6 +627,64 @@ 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);
@@ -664,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 {