@docmana/sdk 0.3.4 → 0.4.0

package/dist/index.mjs

@@ -1,28 +1,32 @@
 // src/config.ts
 var DEFAULTS = {
-  apiBaseUrl: "https://api.docmana.ai",
   tokenEndpoint: "https://4fe70f5b-e013-4f65-9fa7-3109a33beba5.ciamlogin.com/4fe70f5b-e013-4f65-9fa7-3109a33beba5/oauth2/v2.0/token",
   scope: "api://d781e6ba-cc08-4618-8099-ad968abd2b9e/.default",
   timeoutMs: 3e5,
-  pollIntervalMs: 2e3
+  pollIntervalMs: 2e3,
+  pollMaxIntervalMs: 1e4
 };
 function resolveConfig(config) {
-  if (!config.clientId) throw new Error("DocmanaConfig.clientId is required");
-  if (!config.clientSecret) throw new Error("DocmanaConfig.clientSecret is required");
-  const apiBaseUrl = (config.apiBaseUrl ?? DEFAULTS.apiBaseUrl).replace(/\/+$/, "");
+  if (!config.apiBaseUrl) throw new Error("DocmanaConfig.apiBaseUrl is required");
+  if (!config.accessToken && !config.getAccessToken) {
+    throw new Error("DocmanaConfig.accessToken or DocmanaConfig.getAccessToken is required");
+  }
+  const apiBaseUrl = normalizeApiBaseUrl(config.apiBaseUrl);
   return {
-    clientId: config.clientId,
-    clientSecret: config.clientSecret,
     apiBaseUrl,
-    tokenEndpoint: config.tokenEndpoint ?? DEFAULTS.tokenEndpoint,
-    scope: config.scope ?? DEFAULTS.scope,
+    accessToken: config.accessToken,
+    getAccessToken: config.getAccessToken,
     timeoutMs: config.timeoutMs ?? DEFAULTS.timeoutMs,
     pollIntervalMs: config.pollIntervalMs ?? DEFAULTS.pollIntervalMs,
+    pollMaxIntervalMs: config.pollMaxIntervalMs ?? DEFAULTS.pollMaxIntervalMs,
     fetchImpl: config.fetch ?? fetch,
-    headers: config.headers ?? {},
-    tokenCache: config.tokenCache
+    headers: config.headers ?? {}
   };
 }
+function normalizeApiBaseUrl(value) {
+  const trimmed = value.replace(/\/+$/, "");
+  return /\/v\d+$/i.test(trimmed) ? trimmed : `${trimmed}/v1`;
+}
 
 // src/errors.ts
 var DocmanaError = class extends Error {
@@ -77,7 +81,14 @@ var DocmanaAbortError = class extends DocmanaError {
     super(message, { code: "aborted" });
   }
 };
-function errorFromResponse(status, message, requestId) {
+var DocmanaRateLimitError = class extends DocmanaError {
+  retryAfterMs;
+  constructor(message, opts = {}) {
+    super(message, { ...opts, code: "rate_limited" });
+    this.retryAfterMs = opts.retryAfterMs;
+  }
+};
+function errorFromResponse(status, message, requestId, retryAfterMs) {
   const opts = { status, requestId };
   switch (status) {
     case 400:
@@ -88,91 +99,13 @@ function errorFromResponse(status, message, requestId) {
       return new DocmanaPermissionError(message, opts);
     case 404:
       return new DocmanaNotFoundError(message, opts);
+    case 429:
+      return new DocmanaRateLimitError(message, { ...opts, retryAfterMs });
     default:
       return new DocmanaError(message, opts);
   }
 }
 
-// src/auth/token-manager.ts
-var SAFETY_MARGIN_MS = 6e4;
-var TokenManager = class {
-  constructor(opts) {
-    this.opts = opts;
-  }
-  opts;
-  token = null;
-  expiresAt = 0;
-  inflight = null;
-  invalidate() {
-    this.token = null;
-    this.expiresAt = 0;
-    void this.opts.tokenCache?.clear().catch(() => void 0);
-  }
-  async getToken() {
-    if (this.token && Date.now() < this.expiresAt) return this.token;
-    const cached = await this.readCachedToken();
-    if (cached) return cached;
-    if (this.inflight) return this.inflight;
-    this.inflight = this.acquire().finally(() => {
-      this.inflight = null;
-    });
-    return this.inflight;
-  }
-  async acquire() {
-    const body = new URLSearchParams({
-      grant_type: "client_credentials",
-      client_id: this.opts.clientId,
-      client_secret: this.opts.clientSecret,
-      scope: this.opts.scope
-    });
-    const res = await this.opts.fetchImpl(this.opts.tokenEndpoint, {
-      method: "POST",
-      headers: { "content-type": "application/x-www-form-urlencoded" },
-      body: body.toString()
-    });
-    if (!res.ok) {
-      throw new DocmanaAuthError("Failed to acquire Docmana access token", { status: res.status });
-    }
-    const json = await res.json();
-    if (typeof json.access_token !== "string" || json.access_token.length === 0 || typeof json.expires_in !== "number" || !Number.isFinite(json.expires_in)) {
-      throw new DocmanaAuthError("Malformed token response from Docmana CIAM", {
-        status: res.status
-      });
-    }
-    this.token = json.access_token;
-    this.expiresAt = Date.now() + json.expires_in * 1e3 - SAFETY_MARGIN_MS;
-    await this.writeCachedToken().catch(() => void 0);
-    return this.token;
-  }
-  async readCachedToken() {
-    if (!this.opts.tokenCache) return null;
-    let entry;
-    try {
-      entry = await this.opts.tokenCache.read();
-    } catch {
-      return null;
-    }
-    if (!entry) return null;
-    if (entry.clientId !== this.opts.clientId || entry.tokenEndpoint !== this.opts.tokenEndpoint || entry.scope !== this.opts.scope || Date.now() >= entry.expiresAt) {
-      await this.opts.tokenCache.clear().catch(() => void 0);
-      return null;
-    }
-    this.token = entry.accessToken;
-    this.expiresAt = entry.expiresAt;
-    return this.token;
-  }
-  async writeCachedToken() {
-    if (!this.opts.tokenCache || !this.token) return;
-    await this.opts.tokenCache.write({
-      accessToken: this.token,
-      expiresAt: this.expiresAt,
-      clientId: this.opts.clientId,
-      tokenEndpoint: this.opts.tokenEndpoint,
-      scope: this.opts.scope
-    });
-  }
-};
-
 // src/http/http-client.ts
 var HttpClient = class {
   constructor(opts) {
@@ -191,19 +124,23 @@ var HttpClient = class {
   }
   async requestRaw(method, path, options = {}) {
     let res = await this.send(method, path, options);
-    if (res.status === 401) {
-      this.opts.tokenManager.invalidate();
-      res = await this.send(method, path, options);
+    if (res.status === 401 && this.opts.getAccessToken) {
+      res = await this.send(method, path, options, true);
     }
     if (!res.ok) {
       const requestId = res.headers.get("x-request-id") ?? void 0;
       const message = await this.extractMessage(res);
-      throw errorFromResponse(res.status, message, requestId);
+      throw errorFromResponse(
+        res.status,
+        message,
+        requestId,
+        parseRetryAfterMs(res.headers.get("retry-after"))
+      );
     }
     return res;
   }
-  async send(method, path, options) {
-    const token = await this.opts.tokenManager.getToken();
+  async send(method, path, options, forceRefresh = false) {
+    const token = await this.resolveToken(forceRefresh);
     const url = new URL(this.opts.apiBaseUrl + path);
     for (const [k, v] of Object.entries(options.query ?? {})) url.searchParams.set(k, v);
     const headers = {
@@ -225,6 +162,13 @@ var HttpClient = class {
       throw err;
     }
   }
+  async resolveToken(forceRefresh) {
+    const token = this.opts.getAccessToken ? await this.opts.getAccessToken(forceRefresh ? { forceRefresh: true } : void 0) : this.opts.accessToken;
+    if (!token) {
+      throw new DocmanaError("Missing Docmana access token", { code: "auth_missing" });
+    }
+    return token;
+  }
   async extractMessage(res) {
     try {
       const data = await res.clone().json();
@@ -234,6 +178,18 @@ var HttpClient = class {
     }
   }
 };
+function parseRetryAfterMs(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return seconds * 1e3;
+  }
+  const retryAt = Date.parse(value);
+  if (!Number.isNaN(retryAt)) {
+    return Math.max(0, retryAt - Date.now());
+  }
+  return void 0;
+}
 
 // src/files/resolve-input.ts
 import { readFile } from "fs/promises";
@@ -265,16 +221,19 @@ async function streamToBuffer(stream) {
   for await (const chunk of stream) chunks.push(Buffer.from(chunk));
   return Buffer.concat(chunks);
 }
+function toBlobBytes(bytes) {
+  return new Uint8Array(bytes);
+}
 async function resolveOne(input, fallbackName) {
   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([data]), filename, contentType: contentTypeFor(filename) };
+    return { data: new Blob([toBlobBytes(data)]), filename, contentType: contentTypeFor(filename) };
   }
   if (input instanceof Uint8Array) {
     return {
-      data: new Blob([input]),
+      data: new Blob([toBlobBytes(input)]),
       filename: fallbackName,
       contentType: contentTypeFor(fallbackName)
     };
@@ -282,7 +241,7 @@ async function resolveOne(input, fallbackName) {
   if (isReadable(input)) {
     const buf = await streamToBuffer(input);
     return {
-      data: new Blob([buf]),
+      data: new Blob([toBlobBytes(buf)]),
       filename: fallbackName,
       contentType: contentTypeFor(fallbackName)
     };
@@ -296,38 +255,43 @@ async function resolveInputs(input) {
   return Promise.all(list.map((item) => resolveOne(item, fallback)));
 }
 
-// src/api/upload.ts
-async function uploadFiles(http, parts, signal) {
+// src/api/run-flow.ts
+async function runFlow(http, flowId, parts, signal, useDraftVersion = false, context, callbackUrl, language) {
   const form = new FormData();
   for (const part of parts) {
     form.append("files", new File([part.data], part.filename, { type: part.contentType }));
   }
-  const res = await http.requestJson("POST", "/upload", { body: form, signal });
-  return [res.id];
-}
-
-// src/api/run-flow.ts
-async function runFlow(http, flowId, uuidFiles, signal, once = false, context) {
-  const path = once ? `/flows/run_once_flow/${flowId}` : `/flows/run_flow/${flowId}`;
-  const body = { uuid_files: uuidFiles };
-  if (context !== void 0) body.json_context = context;
-  const res = await http.requestJson("POST", path, {
-    query: { async_mode: "true" },
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify(body),
-    signal
-  });
-  return res.execution_result_id;
+  if (context !== void 0) form.append("json_context", JSON.stringify(context));
+  if (callbackUrl !== void 0) form.append("callback_url", callbackUrl);
+  if (language !== void 0) form.append("language", language);
+  if (useDraftVersion) form.append("useDraftVersion", "true");
+  return http.requestJson(
+    "POST",
+    `/flows/${flowId}/execute-async`,
+    { body: form, signal }
+  );
 }
 
 // src/api/execution-status.ts
 async function getStatus(http, executionResultId, signal) {
-  return http.requestJson("GET", `/flows/execution-status/${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 pollAfterMs = parsePositiveInt(res.headers.get("x-poll-after"));
+  return pollAfterMs === void 0 ? body : { ...body, pollAfterMs };
+}
+function parsePositiveInt(value) {
+  if (!value) return void 0;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : void 0;
 }
 
 // src/api/execution-result.ts
-async function getResult(http, executionResultId, signal) {
-  return http.requestJson("GET", `/flows/execution-result/${executionResultId}`, { signal });
+async function getResult(http, executionResultId, signal, language) {
+  return http.requestJson("GET", `/executions/${executionResultId}/result`, {
+    query: language ? { language } : void 0,
+    signal
+  });
 }
 
 // src/polling/poll.ts
@@ -337,166 +301,42 @@ async function pollUntilTerminal(opts) {
   const sleep = opts.sleep ?? defaultSleep;
   const start = Date.now();
   const elapsed = opts.elapsed ?? (() => Date.now() - start);
+  const random = opts.random ?? Math.random;
+  let fallbackAttempt = 0;
   for (; ; ) {
     if (opts.signal?.aborted) throw new DocmanaAbortError("Polling aborted");
-    const status = await opts.check();
+    let result;
+    try {
+      result = normalizePollResult(await opts.check());
+    } catch (err) {
+      if (!(err instanceof DocmanaRateLimitError)) throw err;
+      if (elapsed() >= opts.timeoutMs) {
+        throw new DocmanaTimeoutError(`Execution did not finish within ${opts.timeoutMs}ms`);
+      }
+      await sleep(err.retryAfterMs ?? opts.intervalMs);
+      continue;
+    }
+    const { status } = result;
     if (TERMINAL.has(status)) return status;
     if (elapsed() >= opts.timeoutMs) {
       throw new DocmanaTimeoutError(`Execution did not finish within ${opts.timeoutMs}ms`);
     }
-    await sleep(opts.intervalMs);
+    const fallbackDelay = fullJitterDelay(
+      opts.intervalMs,
+      opts.maxIntervalMs,
+      fallbackAttempt,
+      random
+    );
+    fallbackAttempt += 1;
+    await sleep(result.nextDelayMs ?? fallbackDelay);
   }
 }
-
-// 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|Finish)$/i.test(
-    nodeType
-  );
-  if (isScoreNode && rawNode.score !== void 0 && rawNode.score !== null) {
-    sdkNode.score = rawNode.score;
-  }
-  const feedback = sourceObj.feedback ?? rawNode.feedback;
-  if (feedback !== void 0 && feedback !== null) {
-    sdkNode.feedback = feedback;
-  }
-  if (Object.keys(dynamicFields).length > 0) {
-    sdkNode.data = dynamicFields;
-  }
-  return sdkNode;
+function normalizePollResult(result) {
+  return typeof result === "string" ? { status: result } : result;
 }
-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;
+function fullJitterDelay(intervalMs, maxIntervalMs, attempt, random) {
+  const capDelay = Math.min(maxIntervalMs, intervalMs * 2 ** attempt);
+  return Math.round(intervalMs + random() * (capDelay - intervalMs));
 }
 
 // src/client.ts
@@ -505,46 +345,79 @@ var Docmana = class {
   http;
   constructor(config) {
     this.config = resolveConfig(config);
-    const tokenManager = new TokenManager({
-      clientId: this.config.clientId,
-      clientSecret: this.config.clientSecret,
-      tokenEndpoint: this.config.tokenEndpoint,
-      scope: this.config.scope,
-      fetchImpl: this.config.fetchImpl,
-      tokenCache: this.config.tokenCache
-    });
     this.http = new HttpClient({
       apiBaseUrl: this.config.apiBaseUrl,
       fetchImpl: this.config.fetchImpl,
-      tokenManager,
+      accessToken: this.config.accessToken,
+      getAccessToken: this.config.getAccessToken,
       headers: this.config.headers
     });
   }
   async runFlowAsync(flowId, input) {
     const parts = await resolveInputs(input);
-    const fileIds = await uploadFiles(this.http, parts, input.signal);
-    const executionResultId = await runFlow(
+    return runFlow(
       this.http,
       flowId,
-      fileIds,
+      parts,
       input.signal,
-      input.once ?? false,
-      input.context
+      input.useDraftVersion ?? false,
+      input.context,
+      void 0,
+      input.language
+    );
+  }
+  async runFlowWithCallback(flowId, input) {
+    const parts = await resolveInputs(input);
+    return runFlow(
+      this.http,
+      flowId,
+      parts,
+      input.signal,
+      input.useDraftVersion ?? false,
+      input.context,
+      input.callbackUrl,
+      input.language
     );
-    return { executionResultId, fileIds };
   }
   async getStatus(executionResultId, signal) {
     return getStatus(this.http, executionResultId, signal);
   }
   async getResult(executionResultId, signal, language) {
-    const rawResult = await getResult(this.http, executionResultId, signal);
-    return mapExecutionResult(rawResult, language);
+    return getResult(this.http, executionResultId, signal, language);
   }
   async runFlow(flowId, input) {
     const { executionResultId } = await this.runFlowAsync(flowId, input);
+    let attempt = 0;
+    const startedAt = Date.now();
     await pollUntilTerminal({
-      check: async () => (await this.getStatus(executionResultId, input.signal)).status,
+      check: async () => {
+        attempt += 1;
+        try {
+          const statusResult = await this.getStatus(executionResultId, input.signal);
+          const status = statusResult.status;
+          const nextPollAfterMs = this.isTerminalStatus(status) ? void 0 : statusResult.pollAfterMs;
+          input.onPoll?.({
+            executionResultId,
+            status,
+            attempt,
+            elapsedMs: Date.now() - startedAt,
+            nextPollAfterMs
+          });
+          return { status, nextDelayMs: nextPollAfterMs };
+        } catch (err) {
+          if (err instanceof DocmanaRateLimitError) {
+            input.onRateLimit?.({
+              executionResultId,
+              attempt,
+              elapsedMs: Date.now() - startedAt,
+              retryAfterMs: err.retryAfterMs ?? input.pollIntervalMs ?? this.config.pollIntervalMs
+            });
+          }
+          throw err;
+        }
+      },
       intervalMs: input.pollIntervalMs ?? this.config.pollIntervalMs,
+      maxIntervalMs: input.pollMaxIntervalMs ?? this.config.pollMaxIntervalMs,
       timeoutMs: input.timeoutMs ?? this.config.timeoutMs,
       signal: input.signal
     });
@@ -558,6 +431,9 @@ var Docmana = class {
     }
     return result;
   }
+  isTerminalStatus(status) {
+    return status === "Completed" || status === "Failed";
+  }
 };
 export {
   Docmana,