@docmana/sdk 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.22.0 - 2026-08-06
+
+- Expose the complete Consumer Edge fraud-analysis telemetry: global totals,
+  preprocessing, verdict, and per-layer duration, token usage, LLM calls, model
+  usage, cost, and errors.
+- Keep model usage Mongo-safe as `modelUsage[]` and continue excluding the
+  sensitive Fraud `document` payload.
+
+## 0.21.0 - 2026-08-05
+
+- Relay the native Fraud job identifier through Consumer Edge while preserving
+  the existing high-level polling workflow.
+- Add local file, named byte, and readable stream inputs to `detectFraud` and
+  `detectFraudAsync` through the existing `FileInput` contract.
+- Stop sending organization correlation on Fraud requests. The deprecated
+  organization arguments remain accepted and ignored for source compatibility.
+- Expose Consumer Edge's BI-friendly Fraud result contract: aggregate `summary`,
+  referenced `findings`, and detection `layers` keyed by their unique names.
+
 ## 0.20.0 - 2026-08-04
 
 - Add `detectFraud` to start a Consumer Edge fraud-detection job, poll its

package/README.md

@@ -38,13 +38,12 @@ result:
 
 ```ts
 const fraud = await docmana.detectFraud({
-  documentUrl: "https://downloads.example.com/claim.pdf?token=...",
-  filename: "claim.pdf",
+  file: "./claim.pdf",
   analystContext: "Travel claim; verify the invoice total.",
-  organization: "acme",
 });
 
-console.log(fraud.verdict, fraud.confidence, fraud.findings);
+console.log(fraud.verdict, fraud.summary.highestSeverity);
+console.log(fraud.layers.pixel?.findingReferences, fraud.findings);
 ```
 
 ## Authentication
@@ -143,21 +142,41 @@ 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.
+- `detectFraud(params, options?)` starts fraud detection from either `documentUrl`
+  plus `filename`, or a local `file` using the standard `FileInput` contract. It polls
+  Consumer until `COMPLETED` or `FAILED` and returns the normalized verdict, aggregate
+  `summary`, `findings` with job-local references, and detection `layers` keyed by name.
+  The completed result also exposes global, preprocessing, verdict, and per-layer
+  telemetry (`durationMs`, token counts, LLM calls, `modelUsage`, and `cost`). The
+  sensitive Fraud `document` payload is intentionally never exposed by Consumer or SDK.
 - `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.
+- `getFraudDetectionStatus(jobId, signal?)` and
+  `getFraudDetectionResult(jobId, signal?)` 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.
+The SDK does not log or return `documentUrl` or uploaded file contents. Signed
+query parameters are sent only in the JSON request body to Consumer Edge. Fraud
+jobs are not organization-scoped; the legacy `organization` inputs are accepted
+but ignored for compatibility with SDK 0.20 callers.
+
+URL and local-file inputs use the same methods:
+
+```ts
+const fromUrl = await docmana.detectFraudAsync({
+  documentUrl: "https://downloads.example.com/claim.pdf?token=...",
+  filename: "claim.pdf",
+});
+
+const fromFile = await docmana.detectFraudAsync({
+  file: { path: "./claim.pdf" },
+  analystContext: "Check the invoice total.",
+});
+```
 
 ```ts
 const partial = await docmana.runPartialFlow("<flow-id>", {

package/dist/cli.mjs

@@ -379,8 +379,19 @@ async function getResult(http, executionResultId, signal, language, organization
 
 // src/sdk/api/fraud-detection.ts
 async function startFraudDetection(http, params, signal) {
+  if (params.file !== void 0) {
+    const [part] = await resolveInputs({ files: [params.file] });
+    const form = new FormData();
+    form.append("file", new File([part.data], part.filename, { type: part.contentType }));
+    if (params.analystContext !== void 0) {
+      form.append("analystContext", params.analystContext);
+    }
+    return http.requestJson("POST", "/fraud-detections", {
+      body: form,
+      signal
+    });
+  }
   return http.requestJson("POST", "/fraud-detections", {
-    query: organizationQuery(params.organization),
     headers: { "content-type": "application/json" },
     body: JSON.stringify({
       documentUrl: params.documentUrl,
@@ -391,11 +402,11 @@ async function startFraudDetection(http, params, signal) {
   });
 }
 async function getFraudDetectionStatus(http, jobId, signal, organization) {
+  void organization;
   const res = await http.requestRaw(
     "GET",
     `/fraud-detections/${encodeURIComponent(jobId)}/status`,
     {
-      query: organizationQuery(organization),
       signal
     }
   );
@@ -409,14 +420,11 @@ async function getFraudDetectionStatus(http, jobId, signal, organization) {
   return pollAfterMs === void 0 ? normalized : { ...normalized, pollAfterMs };
 }
 async function getFraudDetectionResult(http, jobId, signal, organization) {
+  void 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);
@@ -644,11 +652,7 @@ var Docmana = class {
       check: async () => {
         attempt += 1;
         try {
-          const statusResult = await this.getFraudDetectionStatus(
-            jobId,
-            options.signal,
-            params.organization
-          );
+          const statusResult = await this.getFraudDetectionStatus(jobId, options.signal);
           const nextPollAfterMs = isTerminalStatus(statusResult.status) ? void 0 : statusResult.pollAfterMs;
           options.onPoll?.({
             jobId,
@@ -676,7 +680,7 @@ var Docmana = class {
       signal: options.signal,
       shouldRetryError: isTransientPollingError
     });
-    const result = await this.getFraudDetectionResult(jobId, options.signal, params.organization);
+    const result = await this.getFraudDetectionResult(jobId, options.signal);
     if (isFailedStatus(result.status)) {
       throw new DocmanaFraudDetectionError(
         result.error?.message ?? `Fraud detection ${jobId} failed`,