@docmana/sdk 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -1,13 +1,24 @@
 # Changelog
 
-## Unreleased
-
-## 0.24.0 - 2026-08-20
-
-- Preserve the exact numeric flow version when mapping raw execution results.
-- Expose each processing step's LLM model and immutable prompt identifier without
-  reintroducing token or cost telemetry.
-- Update vulnerable HTTP and build-tool transitive dependencies to patched versions.
+## Unreleased
+
+## 0.26.0 - 2026-09-07
+
+- Expose the exact numeric version that a new flow execution would use through
+  `getFlowMetadata`.
+
+## 0.25.0 - 2026-08-24
+
+- Stream file-path inputs from disk instead of loading them completely into memory.
+- Expose typed `413` and `503` upload errors, preserve `Retry-After`, and retry one
+  multipart admission `503` carrying that header with a fresh request body.
+
+## 0.24.0 - 2026-08-20
+
+- Preserve the exact numeric flow version when mapping raw execution results.
+- Expose each processing step's LLM model and immutable prompt identifier without
+  reintroducing token or cost telemetry.
+- Update vulnerable HTTP and build-tool transitive dependencies to patched versions.
 
 ## 0.23.0 - 2026-08-07
 

package/README.md

@@ -117,7 +117,9 @@ 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?, jsonContextSchema, languages, minScore?, documents }`.
+  `{ flowId, name?, version?, jsonContextSchema, languages, minScore?, documents }`.
+  `version` is the exact published or draft flow version that a new execution
+  would use.
 - `getFlowDefinition(flowId)` calls `GET /v1/flows/:flowId/definition` and
   returns the normalized flow definition `{ flowId, name?, languages, minScore?, nodes }`.
 - `listOrganizationDocuments({ prefix? })` calls
@@ -160,6 +162,12 @@ 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.
 
+Path inputs are streamed from disk instead of being loaded completely into memory.
+For multipart submissions only, the SDK retries one `503 Service Unavailable`
+response carrying `Retry-After` with a fresh request body, respecting that delay
+up to 30 seconds. A downstream `503` without `Retry-After` is not retried.
+Payloads rejected with `413 Payload Too Large` are never retried.
+
 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
@@ -202,7 +210,7 @@ console.log(organizations.map((org) => `${org.id}: ${org.name}`).join("\n"));
 
 ```ts
 const metadata = await docmana.getFlowMetadata("<flow-id>");
-console.log(metadata.jsonContextSchema);
+console.log(metadata.version, metadata.jsonContextSchema);
 
 const definition = await docmana.getFlowDefinition("<flow-id>");
 console.log(definition.nodes.map((node) => node.label).join("\n"));
@@ -322,16 +330,18 @@ 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`.                  |
-| `DocmanaFraudDetectionError` | Fraud detection finished with status `"FAILED"`. Carries `.jobId`, `.error`, and `.result`. |
-| `DocmanaTimeoutError`        | Polling exceeded `timeoutMs`.                                                               |
-| `DocmanaAbortError`          | The provided `AbortSignal` fired.                                                           |
+| Error                            | Thrown when                                                                                     |
+| -------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `DocmanaRequestError`            | `400` bad request.                                                                              |
+| `DocmanaPayloadTooLargeError`    | `413` multipart payload exceeds a Consumer limit.                                               |
+| `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.                                                               |
+| `DocmanaServiceUnavailableError` | `503` Consumer upload capacity is unavailable after the bounded retry. Carries `.retryAfterMs`. |
 
 ## Local development with yalc
 

package/dist/api/multipart-request.d.ts

@@ -0,0 +1,2 @@
+import type { HttpClient } from "../http/http-client.js";
+export declare function requestMultipartJson<T>(http: HttpClient, path: string, createForm: () => FormData, signal?: AbortSignal): Promise<T>;

package/dist/cli.mjs

@@ -70,6 +70,11 @@ var DocmanaRequestError = class extends DocmanaError {
     super(message, { ...opts, code: "bad_request" });
   }
 };
+var DocmanaPayloadTooLargeError = class extends DocmanaError {
+  constructor(message, opts = {}) {
+    super(message, { ...opts, code: "payload_too_large" });
+  }
+};
 var DocmanaExecutionError = class extends DocmanaError {
   errors;
   result;
@@ -107,6 +112,13 @@ var DocmanaRateLimitError = class extends DocmanaError {
     this.retryAfterMs = opts.retryAfterMs;
   }
 };
+var DocmanaServiceUnavailableError = class extends DocmanaError {
+  retryAfterMs;
+  constructor(message, opts = {}) {
+    super(message, { ...opts, code: "service_unavailable" });
+    this.retryAfterMs = opts.retryAfterMs;
+  }
+};
 function errorFromResponse(status, message, requestId, retryAfterMs) {
   const opts = { status, requestId };
   switch (status) {
@@ -118,8 +130,12 @@ function errorFromResponse(status, message, requestId, retryAfterMs) {
       return new DocmanaPermissionError(message, opts);
     case 404:
       return new DocmanaNotFoundError(message, opts);
+    case 413:
+      return new DocmanaPayloadTooLargeError(message, opts);
     case 429:
       return new DocmanaRateLimitError(message, { ...opts, retryAfterMs });
+    case 503:
+      return new DocmanaServiceUnavailableError(message, { ...opts, retryAfterMs });
     default:
       return new DocmanaError(message, opts);
   }
@@ -215,7 +231,7 @@ function parseRetryAfterMs(value) {
 }
 
 // src/sdk/files/resolve-input.ts
-import { readFile } from "fs/promises";
+import { openAsBlob } from "fs";
 import { basename } from "path";
 var CONTENT_TYPES = {
   ".pdf": "application/pdf",
@@ -255,16 +271,18 @@ function toBlobBytes(bytes) {
 async function resolveOne(input) {
   if (typeof input === "string" || isPathInput(input)) {
     const path = typeof input === "string" ? input : input.path;
-    const data = await readFile(path);
     const filename = basename(path);
-    return { data: new Blob([toBlobBytes(data)]), filename, contentType: contentTypeFor(filename) };
+    const contentType = contentTypeFor(filename);
+    const data = await openAsBlob(path, { type: contentType });
+    return { data, filename, contentType };
   }
   if (isNamedFileInput(input)) {
     const bytes = input.data instanceof Uint8Array ? input.data : await streamToBuffer(input.data);
+    const contentType = input.contentType ?? contentTypeFor(input.filename);
     return {
-      data: new Blob([toBlobBytes(bytes)]),
+      data: new Blob([toBlobBytes(bytes)], { type: contentType }),
       filename: input.filename,
-      contentType: input.contentType ?? contentTypeFor(input.filename)
+      contentType
     };
   }
   throw new Error("Unsupported file input type");
@@ -275,55 +293,98 @@ async function resolveInputs(input) {
   return Promise.all(list.map((item) => resolveOne(item)));
 }
 
+// src/sdk/api/multipart-request.ts
+var MAX_ATTEMPTS = 2;
+var MAX_RETRY_DELAY_MS = 3e4;
+async function requestMultipartJson(http, path, createForm, signal) {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await http.requestJson("POST", path, {
+        body: createForm(),
+        signal
+      });
+    } catch (error) {
+      if (!(error instanceof DocmanaServiceUnavailableError) || error.retryAfterMs === void 0 || attempt >= MAX_ATTEMPTS) {
+        throw error;
+      }
+      await waitForRetry(Math.min(error.retryAfterMs, MAX_RETRY_DELAY_MS), signal);
+    }
+  }
+}
+async function waitForRetry(delayMs, signal) {
+  if (signal?.aborted) throw new DocmanaAbortError("Upload retry aborted");
+  await new Promise((resolve3, reject) => {
+    let settled = false;
+    const finish = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      if (error) reject(error);
+      else resolve3();
+    };
+    const onAbort = () => finish(new DocmanaAbortError("Upload retry aborted"));
+    const timer = setTimeout(() => finish(), delayMs);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
 // src/sdk/api/run-flow.ts
 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 }));
-  }
-  if (context !== void 0) form.append("jsonContext", JSON.stringify(context));
-  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",
+  return requestMultipartJson(
+    http,
     organization ? `${path}?organization=${encodeURIComponent(organization)}` : path,
-    { body: form, signal }
+    () => {
+      const form = new FormData();
+      for (const part of parts) form.append("files", part.data, part.filename);
+      if (context !== void 0) form.append("jsonContext", JSON.stringify(context));
+      if (callbackUrl !== void 0) form.append("callbackUrl", callbackUrl);
+      if (language !== void 0) form.append("language", language);
+      if (useDraftVersion) form.append("useDraftVersion", "true");
+      return form;
+    },
+    signal
   );
 }
 
 // src/sdk/api/run-partial-flow.ts
 function buildRequest(flowId, parts, params, asyncMode) {
-  const form = new FormData();
-  for (const part of parts) {
-    form.append("files", new File([part.data], part.filename, { type: part.contentType }));
-  }
-  if (params.context !== void 0) form.append("jsonContext", JSON.stringify(params.context));
-  form.append("executionScope", params.executionScope);
-  if (params.flowVersion !== void 0) form.append("flowVersion", params.flowVersion);
-  for (const name of params.classificationNodeNames ?? []) {
-    form.append("classificationNodeNames", name);
-  }
   const suffix = asyncMode ? "partial-execute-async" : "partial-execute";
   const path = `/flows/${flowId}/${suffix}`;
   return {
     path: params.organization ? `${path}?organization=${encodeURIComponent(params.organization)}` : path,
-    form
+    createForm: () => {
+      const form = new FormData();
+      for (const part of parts) form.append("files", part.data, part.filename);
+      if (params.context !== void 0) form.append("jsonContext", JSON.stringify(params.context));
+      form.append("executionScope", params.executionScope);
+      if (params.flowVersion !== void 0) form.append("flowVersion", params.flowVersion);
+      for (const name of params.classificationNodeNames ?? []) {
+        form.append("classificationNodeNames", name);
+      }
+      if (asyncMode && "callbackUrl" in params && params.callbackUrl !== void 0) {
+        form.append("callbackUrl", params.callbackUrl);
+      }
+      if (asyncMode && "language" in params && params.language !== void 0) {
+        form.append("language", params.language);
+      }
+      return form;
+    }
   };
 }
 async function runPartialFlow(http, flowId, parts, params, signal) {
-  const { path, form } = buildRequest(flowId, parts, params, false);
-  return http.requestJson("POST", path, { body: form, signal });
+  const { path, createForm } = buildRequest(flowId, parts, params, false);
+  return requestMultipartJson(http, path, createForm, signal);
 }
 async function runPartialFlowAsync(http, flowId, parts, params, signal) {
-  const { path, form } = buildRequest(flowId, parts, params, true);
-  if (params.callbackUrl !== void 0) form.append("callbackUrl", params.callbackUrl);
-  if (params.language !== void 0) form.append("language", params.language);
-  return http.requestJson("POST", path, {
-    body: form,
+  const { path, createForm } = buildRequest(flowId, parts, params, true);
+  return requestMultipartJson(
+    http,
+    path,
+    createForm,
     signal
-  });
+  );
 }
 
 // src/sdk/status.ts
@@ -381,15 +442,19 @@ async function getResult(http, executionResultId, signal, language, organization
 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,
+    return requestMultipartJson(
+      http,
+      "/fraud-detections",
+      () => {
+        const form = new FormData();
+        form.append("file", part.data, part.filename);
+        if (params.analystContext !== void 0) {
+          form.append("analystContext", params.analystContext);
+        }
+        return form;
+      },
       signal
-    });
+    );
   }
   return http.requestJson("POST", "/fraud-detections", {
     headers: { "content-type": "application/json" },
@@ -992,7 +1057,7 @@ var HELP = {
 
 // src/cli/config-store.ts
 import { existsSync } from "fs";
-import { mkdir, readFile as readFile2, rm, writeFile } from "fs/promises";
+import { mkdir, readFile, rm, writeFile } from "fs/promises";
 import { dirname, resolve } from "path";
 import { createInterface } from "readline/promises";
 
@@ -1023,7 +1088,7 @@ async function loadCliConfig(configPathOption, cwd, requireExisting) {
   }
   let raw;
   try {
-    raw = await readFile2(configPath, "utf8");
+    raw = await readFile(configPath, "utf8");
   } catch {
     throw new CliUsageError(`Unable to read config file: ${configPath}`);
   }
@@ -1057,7 +1122,7 @@ function createFileTokenCache(path) {
     async read() {
       if (!existsSync(path)) return null;
       try {
-        const parsed = JSON.parse(await readFile2(path, "utf8"));
+        const parsed = JSON.parse(await readFile(path, "utf8"));
         if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
         const value = parsed;
         if (typeof value.accessToken !== "string" || typeof value.expiresAt !== "number" || typeof value.clientId !== "string" || typeof value.tokenEndpoint !== "string" || typeof value.scope !== "string") {