@docmana/sdk 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,8 +1,22 @@
-# Changelog
-
-## 0.10.0
-- Add an optional `organization` to flow selection, emitted as a
-  `?organization=<org>` query param on the request to
+# Changelog
+
+## 0.12.0
+- Add `--context <json>` to `docmana flow run`, parsed as a JSON object and
+  passed through to `runFlow` as `RunFlowParams.context`.
+- Return CLI usage errors when `--context` is invalid JSON or is not a JSON
+  object.
+
+## 0.11.0
+- Normalize execution statuses to uppercase SDK values:
+  `PENDING`, `RUNNING`, `INCOMPLETED`, `COMPLETED`, and `FAILED`.
+- Normalize raw API and polling statuses before checking terminal or failed
+  states, so legacy mixed-case values still map consistently.
+- Rename flow metadata `contextSchema` to `jsonContextSchema` in the public
+  `FlowMetadata` shape and README examples.
+
+## 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.

package/README.md

@@ -103,7 +103,7 @@ use `RunFlowParams` for request data:
 - `listOrganizations()` calls `GET /v1/organizations` and returns
   `{ id, name }[]` for the organizations available to the Bearer token.
 - `getFlowMetadata(flowId)` calls `GET /v1/flows/:flowId/metadata` and returns
-  `{ flowId, name?, contextSchema, languages, minScore?, documents }`.
+  `{ flowId, name?, jsonContextSchema, languages, minScore?, documents }`.
 - `getFlowDefinition(flowId)` calls `GET /v1/flows/:flowId/definition` and
   returns the normalized flow definition `{ flowId, name?, languages, minScore?, nodes }`.
 - `listOrganizationDocuments({ prefix? })` calls
@@ -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
@@ -140,14 +140,14 @@ console.log(organizations.map((org) => `${org.id}: ${org.name}`).join("\n"));
 
 ```ts
 const metadata = await docmana.getFlowMetadata("<flow-id>");
-console.log(metadata.contextSchema);
+console.log(metadata.jsonContextSchema);
 
 const definition = await docmana.getFlowDefinition("<flow-id>");
 console.log(definition.nodes.map((node) => node.label).join("\n"));
 ```
 
 ```ts
-const depot = await docmana.listOrganizationDocuments({ prefix: "dossier/" });
+const depot = await docmana.listOrganizationDocuments({ prefix: "folder/" });
 if (depot.configured) {
   const file = await docmana.downloadOrganizationDocument(depot.documents[0].path);
   console.log(file.filename, file.bytes.byteLength);
@@ -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));
 }
@@ -217,9 +217,9 @@ docmana organization list
 
 ```bash
 DOCMANA_API_URL="https://consumer.example.com/v1"
-docmana organization document list --prefix "dossier/"
-docmana organization document download "dossier/facture.pdf"
-docmana organization document download "dossier/facture.pdf" --output "./facture.pdf"
+docmana organization document list --prefix "folder/"
+docmana organization document download "folder/invoice.pdf"
+docmana organization document download "folder/invoice.pdf" --output "./invoice.pdf"
 ```
 
 ```bash
@@ -239,12 +239,14 @@ You can also run without the cache:
 docmana flow run "<flow-id>" \
   --api-url "https://consumer.example.com/v1" \
   --access-token "$DOCMANA_ACCESS_TOKEN" \
-  --files "./contract.pdf,./annexe.pdf" \
+  --files "./contract.pdf,./appendix.pdf" \
+  --context '{"contract":{"destination":"Canada"}}' \
   --draft \
   --json
 ```
 
 Use `--draft` to run the current draft flow version.
+Use `--context` to pass business context as a JSON object.
 Use `docmana flow list --json` to print the raw flow list returned by Consumer.
 Use `docmana organization list --json` to print the organization list as JSON.
 Use `docmana organization document list --json` for raw organization document JSON.
@@ -264,7 +266,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/cli.mjs

@@ -282,13 +282,29 @@ async function runFlow(http, flowId, parts, signal, useDraftVersion = false, con
   );
 }
 
+// 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;
@@ -430,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;
@@ -451,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`);
     }
@@ -547,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 ?? [],
@@ -578,7 +593,7 @@ var Docmana = class {
     return downloadOrganizationDocuments(this.http, paths);
   }
   isTerminalStatus(status) {
-    return status === "Completed" || status === "Failed";
+    return isTerminalStatus(status);
   }
 };
 
@@ -686,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) {
@@ -706,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}`);
@@ -716,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}`);
@@ -1255,11 +1270,13 @@ async function listOrganizationsCommand(options, env, io, clientFactory, deps) {
 async function runFlowCommand(flowId, options, env, io, clientFactory, deps) {
   try {
     const files = parseFiles(options.files);
+    const context = parseContext(options.context);
     const client = await resolveApiClient(options, env, io, clientFactory, deps);
     const result = await client.runFlow(
       flowId,
       {
         files: files.map((path) => ({ path })),
+        context,
         language: options.language,
         useDraftVersion: options.draft === true
       },
@@ -1307,6 +1324,19 @@ async function runFlowCommand(flowId, options, env, io, clientFactory, deps) {
     throw err;
   }
 }
+function parseContext(raw) {
+  if (raw === void 0) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CliUsageError("--context must be valid JSON.");
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CliUsageError("--context must be a JSON object.");
+  }
+  return parsed;
+}
 
 // src/cli/commands/login.ts
 async function loginCommand(options, env, io, deps) {
@@ -1385,7 +1415,7 @@ function buildProgram(env, io, clientFactory, deps) {
   flow.command("list").description(HELP.list).option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--json", "Print the raw JSON flow list").action(async (options) => {
     await listFlowsCommand(options, env, io, clientFactory, deps);
   });
-  flow.command("run").description(HELP.run).argument("<flow-id>", "Docmana flow id").requiredOption("--files <csv>", "Comma-separated file paths to upload").option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--json", "Print the raw JSON result").option("--language <lang>", "Translate output to specified language").option("--draft", "Run the current draft flow version").action(async (flowId, options) => {
+  flow.command("run").description(HELP.run).argument("<flow-id>", "Docmana flow id").requiredOption("--files <csv>", "Comma-separated file paths to upload").option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--json", "Print the raw JSON result").option("--context <json>", "Business context as a JSON object").option("--language <lang>", "Translate output to specified language").option("--draft", "Run the current draft flow version").action(async (flowId, options) => {
     await runFlowCommand(flowId, options, env, io, clientFactory, deps);
   });
   flow.command("metadata").description(HELP.metadata).argument("<flow-id>", "Docmana flow id").option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).action(async (flowId, options) => {