@docmana/sdk 0.9.1 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.10.0
+- Add an optional `organization` to flow selection, emitted as a
+  `?organization=<org>` query param on the request to
+  `docmana-consumer-edge-api`. Purely additive — existing calls are unchanged.
+  - `listFlows({ organization })`, `getFlowMetadata(flowId, { organization })`,
+    and `getFlowDefinition(flowId, { organization })` accept the option.
+  - `RunFlowParams` (and therefore `runFlow` / `runFlowAsync`) gains
+    `organization`, threaded onto the `execute-async` request URL.
+- Expose `organization` on `FlowListItem`: when the consumer-edge tags a flow
+  with its organization, `listFlows()` now carries it through on each item.
+
 ## 0.8.1
 - Rename the multipart wire fields sent to `docmana-consumer-edge-api` from
   `json_context` / `callback_url` to `jsonContext` / `callbackUrl`, matching the

package/README.md

@@ -121,7 +121,7 @@ use `RunFlowParams` for request data:
   `GET /v1/executions/:executionResultId/result`.
 - `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`.
+  `DocmanaExecutionError` if the result status is `FAILED`.
 
 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
@@ -159,8 +159,8 @@ const { executionResultId } = await docmana.runFlowAsync("<flow-id>", {
   files: ["./contract.pdf"],
 });
 
-let status = "Pending";
-while (status !== "Completed" && status !== "Failed") {
+let status = "PENDING";
+while (status !== "COMPLETED" && status !== "FAILED") {
   await new Promise((r) => setTimeout(r, 2000));
   ({ status } = await docmana.getStatus(executionResultId));
 }
@@ -264,7 +264,7 @@ optional `.requestId` when available.
 | `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`. |
+| `DocmanaExecutionError`  | The flow finished with status `"FAILED"`. Carries `.errors` and `.result`. |
 | `DocmanaTimeoutError`    | Polling exceeded `timeoutMs`.                                              |
 | `DocmanaAbortError`      | The provided `AbortSignal` fired.                                          |
 

package/dist/api/flow-definition.d.ts

@@ -1,3 +1,3 @@
 import type { HttpClient } from "../http/http-client.js";
 import type { FlowDefinition } from "../types.js";
-export declare function getFlowDefinition(http: HttpClient, flowId: string): Promise<FlowDefinition>;
+export declare function getFlowDefinition(http: HttpClient, flowId: string, organization?: string): Promise<FlowDefinition>;

package/dist/api/flow-metadata.d.ts

@@ -1,3 +1,3 @@
 import type { HttpClient } from "../http/http-client.js";
 import type { FlowMetadata } from "../types.js";
-export declare function getFlowMetadata(http: HttpClient, flowId: string): Promise<FlowMetadata>;
+export declare function getFlowMetadata(http: HttpClient, flowId: string, organization?: string): Promise<FlowMetadata>;

package/dist/api/list-flows.d.ts

@@ -1,3 +1,3 @@
 import type { HttpClient } from "../http/http-client.js";
 import type { FlowListItem } from "../types.js";
-export declare function listFlows(http: HttpClient): Promise<FlowListItem[]>;
+export declare function listFlows(http: HttpClient, organization?: string): Promise<FlowListItem[]>;

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

@@ -1,6 +1,6 @@
 import type { ResolvedPart } from "../files/resolve-input.js";
 import type { HttpClient } from "../http/http-client.js";
-export declare function runFlow(http: HttpClient, flowId: string, parts: ResolvedPart[], signal?: AbortSignal, useDraftVersion?: boolean, context?: Record<string, unknown>, callbackUrl?: string, language?: string): Promise<{
+export declare function runFlow(http: HttpClient, flowId: string, parts: ResolvedPart[], signal?: AbortSignal, useDraftVersion?: boolean, context?: Record<string, unknown>, callbackUrl?: string, language?: string, organization?: string): Promise<{
     executionResultId: string;
     fileIds: string[];
 }>;

package/dist/cli.mjs

@@ -265,7 +265,7 @@ async function resolveInputs(input) {
 }
 
 // src/sdk/api/run-flow.ts
-async function runFlow(http, flowId, parts, signal, useDraftVersion = false, context, callbackUrl, language) {
+async function runFlow(http, flowId, parts, signal, useDraftVersion = false, context, callbackUrl, language, organization) {
   const form = new FormData();
   for (const part of parts) {
     form.append("files", new File([part.data], part.filename, { type: part.contentType }));
@@ -274,20 +274,37 @@ async function runFlow(http, flowId, parts, signal, useDraftVersion = false, con
   if (callbackUrl !== void 0) form.append("callbackUrl", callbackUrl);
   if (language !== void 0) form.append("language", language);
   if (useDraftVersion) form.append("useDraftVersion", "true");
+  const path = `/flows/${flowId}/execute-async`;
   return http.requestJson(
     "POST",
-    `/flows/${flowId}/execute-async`,
+    organization ? `${path}?organization=${encodeURIComponent(organization)}` : path,
     { body: form, signal }
   );
 }
 
+// src/sdk/status.ts
+function normalizeStatus(status, fallback = "UNKNOWN") {
+  if (typeof status !== "string") return fallback;
+  const trimmed = status.trim();
+  if (!trimmed) return fallback;
+  return trimmed.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[\s-]+/g, "_").toUpperCase();
+}
+function isFailedStatus(status) {
+  return normalizeStatus(status) === "FAILED";
+}
+function isTerminalStatus(status) {
+  const normalized = normalizeStatus(status);
+  return normalized === "COMPLETED" || normalized === "FAILED";
+}
+
 // src/sdk/api/execution-status.ts
 async function getStatus(http, executionResultId, signal) {
   const res = await http.requestRaw("GET", `/executions/${executionResultId}/status`, { signal });
   const text = await res.text();
   const body = text ? JSON.parse(text) : { status: "" };
+  const normalizedBody = { ...body, status: normalizeStatus(body.status) };
   const pollAfterMs = parsePositiveInt(res.headers.get("x-poll-after"));
-  return pollAfterMs === void 0 ? body : { ...body, pollAfterMs };
+  return pollAfterMs === void 0 ? normalizedBody : { ...normalizedBody, pollAfterMs };
 }
 function parsePositiveInt(value) {
   if (!value) return void 0;
@@ -304,17 +321,22 @@ async function getResult(http, executionResultId, signal, language) {
 }
 
 // src/sdk/api/list-flows.ts
-async function listFlows(http) {
-  const flows = await http.requestJson("GET", "/flows");
+async function listFlows(http, organization) {
+  const path = organization ? `/flows?organization=${encodeURIComponent(organization)}` : "/flows";
+  const flows = await http.requestJson("GET", path);
   return Array.isArray(flows) ? flows.map(toFlowListItem) : [];
 }
 function toFlowListItem(flow) {
   const value = flow && typeof flow === "object" ? flow : {};
-  return {
+  const item = {
     id: toStringValue(value.id),
     name: toStringValue(value.name),
     state: toStateValue(value.state)
   };
+  if (typeof value.organization === "string") {
+    item.organization = value.organization;
+  }
+  return item;
 }
 function toStringValue(value) {
   return typeof value === "string" ? value : "";
@@ -346,13 +368,21 @@ function toStringValue2(value) {
 }
 
 // src/sdk/api/flow-metadata.ts
-async function getFlowMetadata(http, flowId) {
-  return http.requestJson("GET", `/flows/${encodeURIComponent(flowId)}/metadata`);
+async function getFlowMetadata(http, flowId, organization) {
+  const path = `/flows/${encodeURIComponent(flowId)}/metadata`;
+  return http.requestJson(
+    "GET",
+    organization ? `${path}?organization=${encodeURIComponent(organization)}` : path
+  );
 }
 
 // src/sdk/api/flow-definition.ts
-async function getFlowDefinition(http, flowId) {
-  return http.requestJson("GET", `/flows/${encodeURIComponent(flowId)}/definition`);
+async function getFlowDefinition(http, flowId, organization) {
+  const path = `/flows/${encodeURIComponent(flowId)}/definition`;
+  return http.requestJson(
+    "GET",
+    organization ? `${path}?organization=${encodeURIComponent(organization)}` : path
+  );
 }
 
 // src/sdk/api/organization-documents.ts
@@ -416,7 +446,6 @@ function toNumberValue(value) {
 }
 
 // src/sdk/polling/poll.ts
-var TERMINAL = /* @__PURE__ */ new Set(["Completed", "Failed"]);
 var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 async function pollUntilTerminal(opts) {
   const sleep = opts.sleep ?? defaultSleep;
@@ -437,8 +466,8 @@ async function pollUntilTerminal(opts) {
       await sleep(err.retryAfterMs ?? opts.intervalMs);
       continue;
     }
-    const { status } = result;
-    if (TERMINAL.has(status)) return status;
+    const status = normalizeStatus(result.status);
+    if (isTerminalStatus(status)) return status;
     if (elapsed() >= opts.timeoutMs) {
       throw new DocmanaTimeoutError(`Execution did not finish within ${opts.timeoutMs}ms`);
     }
@@ -484,7 +513,8 @@ var Docmana = class {
       params.useDraftVersion ?? false,
       params.context,
       params.callbackUrl,
-      params.language
+      params.language,
+      params.organization
     );
   }
   async getStatus(executionResultId, signal) {
@@ -532,7 +562,7 @@ var Docmana = class {
       signal: options.signal
     });
     const result = await this.getResult(executionResultId, options.signal, params.language);
-    if (result.status === "Failed") {
+    if (isFailedStatus(result.status)) {
       throw new DocmanaExecutionError(
         `Flow ${flowId} execution failed`,
         result.errors ?? [],
@@ -541,17 +571,17 @@ var Docmana = class {
     }
     return result;
   }
-  async listFlows() {
-    return listFlows(this.http);
+  async listFlows(options = {}) {
+    return listFlows(this.http, options.organization);
   }
   async listOrganizations() {
     return listOrganizations(this.http);
   }
-  async getFlowMetadata(flowId) {
-    return getFlowMetadata(this.http, flowId);
+  async getFlowMetadata(flowId, options = {}) {
+    return getFlowMetadata(this.http, flowId, options.organization);
   }
-  async getFlowDefinition(flowId) {
-    return getFlowDefinition(this.http, flowId);
+  async getFlowDefinition(flowId, options = {}) {
+    return getFlowDefinition(this.http, flowId, options.organization);
   }
   async listOrganizationDocuments(options = {}) {
     return listOrganizationDocuments(this.http, options);
@@ -563,7 +593,7 @@ var Docmana = class {
     return downloadOrganizationDocuments(this.http, paths);
   }
   isTerminalStatus(status) {
-    return status === "Completed" || status === "Failed";
+    return isTerminalStatus(status);
   }
 };
 
@@ -671,10 +701,10 @@ function formatHumanError(err) {
         if (docResult.extractions) nodes.push(...Object.values(docResult.extractions));
         if (docResult.validations) nodes.push(...Object.values(docResult.validations));
         const hasNodeFailures = nodes.some(
-          (n) => n.status === "Failed" || n.errors && n.errors.length > 0
+          (n) => isFailedStatus(n.status) || n.errors && n.errors.length > 0
         );
         lines.push(`  - Document: ${docName} (Status: ${status})`);
-        if (docResult.status !== "Failed" && !hasNodeFailures) continue;
+        if (!isFailedStatus(docResult.status) && !hasNodeFailures) continue;
         if (docResult.classifications) {
           for (const [nodeName, node] of Object.entries(docResult.classifications)) {
             if (node.errors && node.errors.length > 0) {
@@ -691,7 +721,7 @@ function formatHumanError(err) {
         }
         if (docResult.extractions) {
           for (const [nodeName, node] of Object.entries(docResult.extractions)) {
-            if (node.status === "Failed" || node.errors && node.errors.length > 0) {
+            if (isFailedStatus(node.status) || node.errors && node.errors.length > 0) {
               lines.push(`    Extraction: ${nodeName} (Status: ${node.status})`);
               if (node.errors) {
                 for (const nodeErr of node.errors) lines.push(`      - ${nodeErr}`);
@@ -701,7 +731,7 @@ function formatHumanError(err) {
         }
         if (docResult.validations) {
           for (const [nodeName, node] of Object.entries(docResult.validations)) {
-            if (node.status === "Failed" || node.errors && node.errors.length > 0) {
+            if (isFailedStatus(node.status) || node.errors && node.errors.length > 0) {
               lines.push(`    Validation: ${nodeName} (Status: ${node.status})`);
               if (node.errors) {
                 for (const nodeErr of node.errors) lines.push(`      - ${nodeErr}`);