@docmana/sdk 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.3.0
+- Relocated mapper logic and tests to `src/mappers/`.
+- Renamed SDK models to `DocmanaX` and API models to `DocmanaApiX` to distinguish raw backend types from clean public SDK types.
+- Pluralized `classification` results into a `classifications` key-value record on document results.
+- Nested dynamic extraction fields inside a dedicated `data` record on node results to prevent property name collisions.
+- Restructured node result interfaces to remove `score` and `feedback` from `DocmanaExtractionResult` and `DocmanaMetadataExtractionResult` (via new `DocmanaScoreNodeResult` interface).
+- Excluded internal fields `result` and `documentType` from mapped SDK results.
+
+## 0.2.2
+- Fix `package-lock.json`.
+
 ## 0.2.1
 - 400 responses now throw `DocmanaRequestError` (was `DocmanaAuthError`); add `Incompleted` to `ExecutionStatus`.
 

package/dist/cli.mjs

@@ -44,9 +44,11 @@ var DocmanaRequestError = class extends DocmanaError {
 };
 var DocmanaExecutionError = class extends DocmanaError {
   errors;
-  constructor(message, errors = []) {
+  result;
+  constructor(message, errors = [], result) {
     super(message, { code: "execution_failed" });
     this.errors = errors;
+    this.result = result;
   }
 };
 var DocmanaTimeoutError = class extends DocmanaError {
@@ -356,6 +358,156 @@ async function pollUntilTerminal(opts) {
   }
 }
 
+// src/mappers/mapper.ts
+function extractNodeFields(rawNode, targetLanguage) {
+  const metadataFields = /* @__PURE__ */ new Set([
+    "node_id",
+    "node_name",
+    "node_type",
+    "feature_name",
+    "running_time",
+    "status",
+    "score",
+    "feedback",
+    "translations",
+    "tokens",
+    "input_tokens",
+    "output_tokens",
+    "errors",
+    "mana",
+    "model",
+    "tool_calls",
+    "prompt_id",
+    "prompt",
+    "prompt_name",
+    "label",
+    "scoreDescription",
+    "score_description",
+    "result",
+    "documentType"
+  ]);
+  let sourceObj = rawNode;
+  if (targetLanguage) {
+    const translations = rawNode.translations;
+    if (!translations || !translations[targetLanguage]) {
+      throw new DocmanaError(
+        `Translation for language '${targetLanguage}' is missing on node '${rawNode.node_name || rawNode.node_id}'`,
+        { code: "translation_missing", status: 400 }
+      );
+    }
+    sourceObj = translations[targetLanguage];
+  }
+  const dynamicFields = {};
+  for (const [key, value] of Object.entries(sourceObj)) {
+    if (!metadataFields.has(key)) {
+      dynamicFields[key] = value;
+    }
+  }
+  const sdkNode = {
+    status: rawNode.status || "Unknown"
+  };
+  if (rawNode.errors && rawNode.errors.length > 0) {
+    sdkNode.errors = rawNode.errors;
+  }
+  const nodeType = rawNode.node_type || "";
+  const isScoreNode = /^(Validation|Classification|CrossValidation|Conclusion)$/i.test(nodeType);
+  if (isScoreNode) {
+    if (rawNode.score !== void 0 && rawNode.score !== null) {
+      sdkNode.score = rawNode.score;
+    }
+    if (rawNode.feedback !== void 0 && rawNode.feedback !== null) {
+      sdkNode.feedback = rawNode.feedback;
+    }
+  }
+  if (Object.keys(dynamicFields).length > 0) {
+    sdkNode.data = dynamicFields;
+  }
+  return sdkNode;
+}
+function mapExecutionResult(raw, targetLanguage) {
+  const sdkResult = {
+    status: raw.status || "Unknown",
+    executionId: String(raw.execution_id || raw.executionResultId || raw.execution_result_id || ""),
+    documents: {
+      mappings: []
+    }
+  };
+  if (raw.errors && raw.errors.length > 0) {
+    sdkResult.errors = raw.errors;
+  }
+  const results = raw.results || [];
+  for (const item of results) {
+    const isDocSpecific = !!item.document;
+    if (isDocSpecific && item.document) {
+      const docReq = item.document;
+      const docKey = docReq.doc_key || "unknown_doc";
+      const docName = docReq.name || "";
+      sdkResult.documents.mappings.push({
+        name: docName,
+        reference: docKey
+      });
+      const docResult = {
+        status: item.status || docReq.status || "Unknown",
+        extractions: {},
+        validations: {}
+      };
+      const nodeResults = item.node_results || [];
+      for (const node of nodeResults) {
+        const nodeType = node.node_type || "";
+        const nodeName = node.node_name || node.node_id || "unknown_node";
+        if (/^Classification$/i.test(nodeType)) {
+          const mappedNode = extractNodeFields(node, targetLanguage);
+          if (!docResult.classifications) {
+            docResult.classifications = {};
+          }
+          docResult.classifications[nodeName] = mappedNode;
+        } else if (/^MetadataExtraction$/i.test(nodeType)) {
+          docResult.metadataExtraction = extractNodeFields(node, targetLanguage);
+        } else if (/^Extraction$/i.test(nodeType)) {
+          if (docResult.extractions) {
+            docResult.extractions[nodeName] = extractNodeFields(node, targetLanguage);
+          }
+        } else if (/^Validation$/i.test(nodeType)) {
+          if (docResult.validations) {
+            docResult.validations[nodeName] = extractNodeFields(node, targetLanguage);
+          }
+        }
+      }
+      if (docResult.extractions && Object.keys(docResult.extractions).length === 0) {
+        delete docResult.extractions;
+      }
+      if (docResult.validations && Object.keys(docResult.validations).length === 0) {
+        delete docResult.validations;
+      }
+      sdkResult.documents[docKey] = docResult;
+    } else {
+      const nodeResults = item.node_results || [];
+      for (const node of nodeResults) {
+        const nodeType = node.node_type || "";
+        const nodeName = node.node_name || node.node_id || "unknown_node";
+        if (/^CrossValidation$/i.test(nodeType)) {
+          if (!sdkResult.crossValidations) {
+            sdkResult.crossValidations = {};
+          }
+          sdkResult.crossValidations[nodeName] = extractNodeFields(
+            node,
+            targetLanguage
+          );
+        } else if (/^(Conclusion|Finish)$/i.test(nodeType)) {
+          if (!sdkResult.conclusions) {
+            sdkResult.conclusions = {};
+          }
+          sdkResult.conclusions[nodeName] = extractNodeFields(
+            node,
+            targetLanguage
+          );
+        }
+      }
+    }
+  }
+  return sdkResult;
+}
+
 // src/client.ts
 var Docmana = class {
   config;
@@ -392,8 +544,9 @@ var Docmana = class {
   async getStatus(executionResultId, signal) {
     return getStatus(this.http, executionResultId, signal);
   }
-  async getResult(executionResultId, signal) {
-    return getResult(this.http, executionResultId, signal);
+  async getResult(executionResultId, signal, language) {
+    const rawResult = await getResult(this.http, executionResultId, signal);
+    return mapExecutionResult(rawResult, language);
   }
   async runFlow(flowId, input) {
     const { executionResultId } = await this.runFlowAsync(flowId, input);
@@ -403,9 +556,13 @@ var Docmana = class {
       timeoutMs: input.timeoutMs ?? this.config.timeoutMs,
       signal: input.signal
     });
-    const result = await this.getResult(executionResultId, input.signal);
+    const result = await this.getResult(executionResultId, input.signal, input.language);
     if (result.status === "Failed") {
-      throw new DocmanaExecutionError(`Flow ${flowId} execution failed`, result.errors ?? []);
+      throw new DocmanaExecutionError(
+        `Flow ${flowId} execution failed`,
+        result.errors ?? [],
+        result
+      );
     }
     return result;
   }
@@ -418,6 +575,15 @@ var CliUsageError = class extends Error {
     this.name = "CliUsageError";
   }
 };
+var CliSilentError = class extends Error {
+  exitCode;
+  constructor(exitCode = 1) {
+    super();
+    this.name = "CliSilentError";
+    this.exitCode = exitCode;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
 var HELP = {
   root: "Run Docmana document-analysis flows.",
   flow: "Manage and run Docmana flows.",
@@ -441,6 +607,9 @@ async function runCli(argv = process.argv.slice(2), env = process.env, io = {
     await program.parseAsync(argv, { from: "user" });
     return 0;
   } catch (err) {
+    if (err instanceof CliSilentError) {
+      return err.exitCode;
+    }
     if (err instanceof CliUsageError) {
       io.stderr(`Error: ${err.message}
 `);
@@ -467,7 +636,7 @@ function buildProgram(env, io, clientFactory, deps) {
   const flow = program.command("flow").description(HELP.flow).action(() => {
     io.stdout(flow.helpInformation());
   });
-  flow.command("run").description(HELP.run).argument("<flow-id>", "Docmana flow id").requiredOption("--files <csv>", "Comma-separated file paths to upload").option("--client-id <id>", "OAuth2 client id; defaults to DOCMANA_CLIENT_ID").option("--client-secret <secret>", "OAuth2 client secret; defaults to DOCMANA_CLIENT_SECRET").option("--api-url <url>", "Docmana API base URL; defaults to DOCMANA_API_URL").option("--token-url <url>", "OAuth2 token endpoint; defaults to DOCMANA_TOKEN_URL").option("--scope <scope>", "OAuth2 scope; defaults to DOCMANA_SCOPE").option("--organisation <id>", "Docmana organisation id; defaults to DOCMANA_ORGANISATION").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").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("--client-id <id>", "OAuth2 client id; defaults to DOCMANA_CLIENT_ID").option("--client-secret <secret>", "OAuth2 client secret; defaults to DOCMANA_CLIENT_SECRET").option("--api-url <url>", "Docmana API base URL; defaults to DOCMANA_API_URL").option("--token-url <url>", "OAuth2 token endpoint; defaults to DOCMANA_TOKEN_URL").option("--scope <scope>", "OAuth2 scope; defaults to DOCMANA_SCOPE").option("--organisation <id>", "Docmana organisation id; defaults to DOCMANA_ORGANISATION").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").action(async (flowId, options) => {
     await runFlowCommand(flowId, options, env, io, clientFactory, deps);
   });
   const config = program.command("config").description(HELP.config).action(() => {
@@ -479,50 +648,77 @@ function buildProgram(env, io, clientFactory, deps) {
   return program;
 }
 async function runFlowCommand(flowId, options, env, io, clientFactory, deps) {
-  const files = parseFiles(options.files);
-  const cliConfig = await loadCliConfig(options.config, getCwd(deps), Boolean(options.config));
-  const clientId = firstNonEmpty(options.clientId, env.DOCMANA_CLIENT_ID, cliConfig.clientId);
-  const clientSecret = firstNonEmpty(
-    options.clientSecret,
-    env.DOCMANA_CLIENT_SECRET,
-    cliConfig.clientSecret
-  );
-  const organisation = firstNonEmpty(
-    options.organisation,
-    env.DOCMANA_ORGANISATION,
-    cliConfig.organisation
-  );
-  const apiBaseUrl = firstNonEmpty(options.apiUrl, env.DOCMANA_API_URL, cliConfig.apiBaseUrl);
-  const tokenEndpoint = firstNonEmpty(
-    options.tokenUrl,
-    env.DOCMANA_TOKEN_URL,
-    cliConfig.tokenEndpoint
-  );
-  const scope = firstNonEmpty(options.scope, env.DOCMANA_SCOPE, cliConfig.scope);
-  if (!clientId)
-    throw new CliUsageError("Missing client id. Use --client-id or DOCMANA_CLIENT_ID.");
-  if (!clientSecret) {
-    throw new CliUsageError("Missing client secret. Use --client-secret or DOCMANA_CLIENT_SECRET.");
-  }
-  if (!organisation) {
-    throw new CliUsageError("Missing organisation. Use --organisation or DOCMANA_ORGANISATION.");
-  }
-  const client = clientFactory({
-    clientId,
-    clientSecret,
-    apiBaseUrl,
-    tokenEndpoint,
-    scope,
-    headers: { "X-Selected-Organization": organisation },
-    tokenCache: createFileTokenCache(resolveTokenCachePath(options.tokenCache, getCwd(deps)))
-  });
-  const result = await client.runFlow(flowId, { files: files.map((path) => ({ path })) });
-  if (options.json) {
-    io.stdout(`${JSON.stringify(result, null, 2)}
+  try {
+    const files = parseFiles(options.files);
+    const cliConfig = await loadCliConfig(options.config, getCwd(deps), Boolean(options.config));
+    const clientId = firstNonEmpty(options.clientId, env.DOCMANA_CLIENT_ID, cliConfig.clientId);
+    const clientSecret = firstNonEmpty(
+      options.clientSecret,
+      env.DOCMANA_CLIENT_SECRET,
+      cliConfig.clientSecret
+    );
+    const organisation = firstNonEmpty(
+      options.organisation,
+      env.DOCMANA_ORGANISATION,
+      cliConfig.organisation
+    );
+    const apiBaseUrl = firstNonEmpty(options.apiUrl, env.DOCMANA_API_URL, cliConfig.apiBaseUrl);
+    const tokenEndpoint = firstNonEmpty(
+      options.tokenUrl,
+      env.DOCMANA_TOKEN_URL,
+      cliConfig.tokenEndpoint
+    );
+    const scope = firstNonEmpty(options.scope, env.DOCMANA_SCOPE, cliConfig.scope);
+    if (!clientId)
+      throw new CliUsageError("Missing client id. Use --client-id or DOCMANA_CLIENT_ID.");
+    if (!clientSecret) {
+      throw new CliUsageError(
+        "Missing client secret. Use --client-secret or DOCMANA_CLIENT_SECRET."
+      );
+    }
+    if (!organisation) {
+      throw new CliUsageError("Missing organisation. Use --organisation or DOCMANA_ORGANISATION.");
+    }
+    const client = clientFactory({
+      clientId,
+      clientSecret,
+      apiBaseUrl,
+      tokenEndpoint,
+      scope,
+      headers: { "X-Selected-Organization": organisation },
+      tokenCache: createFileTokenCache(resolveTokenCachePath(options.tokenCache, getCwd(deps)))
+    });
+    const result = await client.runFlow(flowId, {
+      files: files.map((path) => ({ path })),
+      language: options.language
+    });
+    if (options.json) {
+      io.stdout(`${JSON.stringify(result, null, 2)}
+`);
+      return;
+    }
+    io.stdout(formatHumanResult(result));
+  } catch (err) {
+    if (options.json) {
+      if (err instanceof DocmanaExecutionError && err.result) {
+        io.stdout(`${JSON.stringify(err.result, null, 2)}
+`);
+      } else {
+        const errorPayload = {
+          error: err instanceof Error ? err.message : String(err)
+        };
+        if (err instanceof DocmanaError) {
+          errorPayload.code = err.code;
+          if (err.status !== void 0) errorPayload.status = err.status;
+          if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
+        }
+        io.stdout(`${JSON.stringify(errorPayload, null, 2)}
 `);
-    return;
+      }
+      throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
+    }
+    throw err;
   }
-  io.stdout(formatHumanResult(result));
 }
 async function loginCommand(options, env, io, deps) {
   const auth = await resolveAuthConfig(options, env, deps);
@@ -726,31 +922,141 @@ function firstNonEmpty(...values) {
 }
 function formatHumanResult(result) {
   const lines = ["Docmana flow completed", `Status: ${String(result.status ?? "Unknown")}`];
-  const executionId = result.execution_id ?? result.executionResultId ?? result.execution_result_id;
+  const executionId = result.executionId;
   if (executionId) lines.push(`Execution id: ${String(executionId)}`);
-  if (Array.isArray(result.results)) lines.push(`Results: ${result.results.length}`);
-  if (Array.isArray(result.errors)) lines.push(`Errors: ${result.errors.length}`);
-  const preview = formatResultsPreview(result.results);
+  if (result.documents && result.documents.mappings) {
+    lines.push(`Results: ${result.documents.mappings.length}`);
+  }
+  if (result.errors && result.errors.length > 0) {
+    lines.push(`Errors: ${result.errors.length}`);
+  }
+  const previewData = {};
+  if (result.documents && result.documents.mappings) {
+    for (const mapping of result.documents.mappings.slice(0, 3)) {
+      const docKey = mapping.reference;
+      previewData[mapping.name] = result.documents[docKey];
+    }
+  }
+  const preview = formatResultsPreview(previewData);
   if (preview) lines.push("", "Result preview:", preview);
   lines.push("", "Use --json to print the complete result payload.");
   return `${lines.join("\n")}
 `;
 }
 function formatResultsPreview(results) {
-  if (!Array.isArray(results) || results.length === 0) return void 0;
-  const preview = JSON.stringify(results.slice(0, 3), null, 2);
+  if (!results) return void 0;
+  const preview = JSON.stringify(results, null, 2);
   if (!preview) return void 0;
   return preview.length > 2e3 ? `${preview.slice(0, 2e3)}
 ...` : preview;
 }
 function formatRuntimeError(err) {
+  return formatHumanError(err);
+}
+function formatHumanError(err) {
   if (err instanceof DocmanaExecutionError) {
-    const details = err.errors.length > 0 ? ` (${err.errors.length} error(s))` : "";
-    return `${err.message}${details}`;
+    const lines = [`Error: ${err.message}`];
+    if (err.errors && err.errors.length > 0) {
+      lines.push("Global errors:");
+      for (const e of err.errors) {
+        lines.push(`  - ${formatSingleError(e)}`);
+      }
+    }
+    const result = err.result;
+    if (result) {
+      if (result.documents && result.documents.mappings && result.documents.mappings.length > 0) {
+        lines.push("Document execution results:");
+        for (const mapping of result.documents.mappings) {
+          const docKey = mapping.reference;
+          const docName = mapping.name;
+          const docResult = result.documents[docKey];
+          if (docResult) {
+            const status = docResult.status || "Unknown";
+            const nodes = [];
+            if (docResult.classifications) nodes.push(...Object.values(docResult.classifications));
+            if (docResult.metadataExtraction) nodes.push(docResult.metadataExtraction);
+            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
+            );
+            if (docResult.status === "Failed" || hasNodeFailures) {
+              lines.push(`  - Document: ${docName} (Status: ${status})`);
+              if (docResult.classifications) {
+                for (const [nodeName, node] of Object.entries(docResult.classifications)) {
+                  if (node.errors && node.errors.length > 0) {
+                    lines.push(`    Classification: ${nodeName} (Status: ${node.status})`);
+                    for (const nodeErr of node.errors) {
+                      lines.push(`      - ${nodeErr}`);
+                    }
+                  }
+                }
+              }
+              if (docResult.metadataExtraction?.errors && docResult.metadataExtraction.errors.length > 0) {
+                lines.push(
+                  `    MetadataExtraction: (Status: ${docResult.metadataExtraction.status})`
+                );
+                for (const nodeErr of docResult.metadataExtraction.errors) {
+                  lines.push(`      - ${nodeErr}`);
+                }
+              }
+              if (docResult.extractions) {
+                for (const [nodeName, node] of Object.entries(docResult.extractions)) {
+                  if (node.status === "Failed" || 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}`);
+                      }
+                    }
+                  }
+                }
+              }
+              if (docResult.validations) {
+                for (const [nodeName, node] of Object.entries(docResult.validations)) {
+                  if (node.status === "Failed" || 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}`);
+                      }
+                    }
+                  }
+                }
+              }
+            } else {
+              lines.push(`  - Document: ${docName} (Status: ${status})`);
+            }
+          } else {
+            lines.push(`  - Document: ${docName} (Status: Unknown)`);
+          }
+        }
+      }
+    }
+    return lines.join("\n");
+  }
+  if (err instanceof DocmanaError) {
+    return `Error: ${err.message} (Code: ${err.code})`;
+  }
+  if (err instanceof Error) {
+    return `Error: ${err.message}`;
+  }
+  return `Error: ${String(err)}`;
+}
+function formatSingleError(e) {
+  if (typeof e === "string") return e;
+  if (e && typeof e === "object") {
+    const obj = e;
+    if (typeof obj.msg === "string") return obj.msg;
+    if (typeof obj.message === "string") return obj.message;
+    if (typeof obj.error === "string") return obj.error;
+    try {
+      return JSON.stringify(e);
+    } catch {
+      return String(e);
+    }
   }
-  if (err instanceof DocmanaError) return err.message;
-  if (err instanceof Error) return err.message;
-  return "Unexpected error";
+  return String(e);
 }
 function isDirectRun() {
   const entry = process.argv[1];