@docmana/sdk 0.28.1 → 0.36.0-hitl.2

package/dist/cli.mjs

@@ -36,11 +36,377 @@ function normalizeApiBaseUrl(value) {
   return /\/v\d+$/i.test(trimmed) ? trimmed : `${trimmed}/v1`;
 }
 
+// src/sdk/authoring.ts
+function identity(id) {
+  if (!/^[A-Za-z0-9_-]{1,200}$/.test(id)) throw new Error("Invalid formula identifier");
+  return encodeURIComponent(id);
+}
+var FormulaAuthoring = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Read-only, revision-pinned definitions. Assisted execution belongs to the server-side Flows POC. */
+  documentTrialDefinitions(spec, options) {
+    identity(spec.flowId);
+    if (Boolean(spec.node) === (spec.allNodes === true))
+      throw new Error("Select one node or all nodes");
+    if (spec.node) identity(spec.node);
+    return this.request("POST", "document-trial/definitions", options, spec);
+  }
+  /** Native manual execution through Consumer Edge; assisted trials use definitions plus server-side Flows. */
+  async trialDocument(file, filename, spec, options) {
+    if (!options.organization.trim()) throw new Error("Organization is required");
+    if (!file.size || file.size > 20 * 1024 * 1024 || !/\.(pdf|jpeg|jpg|png|bmp|tiff|tif|heic)$/i.test(filename))
+      throw new Error("Invalid trial document");
+    if ("flowId" in spec) {
+      identity(spec.flowId);
+      if (Boolean(spec.node) === (spec.allNodes === true))
+        throw new Error("Select one node or all nodes");
+      if (spec.node) identity(spec.node);
+    } else if (!Array.isArray(spec.nodes) || !spec.nodes.length || spec.nodes.length > 100)
+      throw new Error("Invalid trial nodes");
+    const body = new FormData();
+    body.set("file", file, filename);
+    body.set("spec", JSON.stringify(spec));
+    return this.http.requestJson("POST", "/authoring/document-trial", {
+      query: { organization: options.organization },
+      signal: options.signal,
+      body
+    });
+  }
+  editorCatalog(options) {
+    return this.request("GET", "editor-catalog", options);
+  }
+  generateMapping(body, options) {
+    return this.request("POST", "generate-mapping", options, body);
+  }
+  openConversation(body, options) {
+    identity(body.flow_id);
+    if (body.node_id) identity(body.node_id);
+    return this.request("POST", "conversations", options, body);
+  }
+  sendConversationMessage(id, content, options) {
+    return this.request("POST", `conversations/${identity(id)}/messages`, options, { content });
+  }
+  confirmConversation(id, body, options) {
+    return this.request("POST", `conversations/${identity(id)}/confirm`, options, body);
+  }
+  request(method, path, options, body) {
+    if (!options.organization.trim()) throw new Error("Organization is required");
+    return this.http.requestJson(method, `/authoring/${path}`, {
+      query: { organization: options.organization },
+      signal: options.signal,
+      ...body === void 0 ? {} : {
+        body: JSON.stringify(body),
+        headers: { "content-type": "application/json" }
+      }
+    });
+  }
+  list(options) {
+    const offset = options.offset ?? 0, limit = options.limit ?? 50;
+    if (!Number.isInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 1 || limit > 200)
+      throw new Error("Invalid authoring pagination");
+    return this.request(
+      "GET",
+      `flows?offset=${offset}&limit=${limit}&sort=${encodeURIComponent(options.sort ?? "id")}`,
+      options
+    );
+  }
+  remove(id, options) {
+    return this.request("DELETE", `flows/${identity(id)}`, options);
+  }
+  async exportArchive(id, options) {
+    if (!options.organization.trim()) throw new Error("Organization is required");
+    return (await this.http.requestBytes("GET", `/authoring/flows/${identity(id)}/export`, {
+      query: { organization: options.organization },
+      signal: options.signal
+    })).bytes;
+  }
+  importArchive(file, filename, options) {
+    if (!options.organization.trim()) throw new Error("Organization is required");
+    if (!/\.(zip|docmana)$/i.test(filename) || file.size > 10 * 1024 * 1024)
+      throw new Error("Invalid formula archive");
+    const body = new FormData();
+    body.append("file", file, filename);
+    return this.http.requestJson("POST", "/authoring/flows/import", {
+      query: {
+        organization: options.organization,
+        confirmOverwrite: String(options.confirmOverwrite === true)
+      },
+      body,
+      signal: options.signal
+    });
+  }
+  get(id, options) {
+    return this.request("GET", `flows/${identity(id)}`, options);
+  }
+  create(body, options) {
+    return this.request("POST", "flows", options, body);
+  }
+  save(id, body, options) {
+    return this.request("PATCH", `flows/${identity(id)}/draft`, options, body);
+  }
+  validate(id, revisions, options) {
+    return this.request("POST", `flows/${identity(id)}/validate`, options, {
+      expectedRevisions: revisions
+    });
+  }
+  publish(id, body, options) {
+    return this.request("POST", `flows/${identity(id)}/publish`, options, body);
+  }
+  history(id, kind, options) {
+    if (kind !== "snapshots" && kind !== "published") throw new Error("Invalid history kind");
+    const offset = options.offset ?? 0, limit = options.limit ?? 20;
+    if (!Number.isInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 1 || limit > 100)
+      throw new Error("Invalid history pagination");
+    return this.request(
+      "GET",
+      `flows/${identity(id)}/history/${kind}?offset=${offset}&limit=${limit}`,
+      options
+    );
+  }
+  flags(options) {
+    return this.request("GET", "feature-flags", options);
+  }
+};
+
+// src/sdk/reviews.ts
+function segment(value) {
+  if (!value || value === "." || value === ".." || /[\\/]/.test(value) || [...value].some((char) => char.charCodeAt(0) < 32))
+    throw new Error("Invalid review identifier");
+  return encodeURIComponent(value);
+}
+var Reviews = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Repeatable metadata read: never consumes the final execution result. */
+  calculation(executionId, options) {
+    return this.http.requestJson("GET", `/executions/${segment(executionId)}/review/calculation`, {
+      signal: options.signal,
+      query: { organization: options.organization }
+    });
+  }
+  /** Published formula structure only. Compare its version with the review's flowVersion. */
+  outline(flowId, options) {
+    return this.http.requestJson("GET", `/flows/${segment(flowId)}/outline`, {
+      signal: options.signal,
+      query: { organization: options.organization }
+    });
+  }
+  list(options) {
+    return this.http.requestJson("GET", "/reviews", {
+      signal: options.signal,
+      query: {
+        organization: options.organization,
+        ...options.status ? { status: options.status } : {},
+        ...options.cursor ? { cursor: options.cursor } : {},
+        ...options.limit ? { limit: String(options.limit) } : {}
+      }
+    });
+  }
+  get(executionId, options) {
+    return this.http.requestJson("GET", `/executions/${segment(executionId)}/review`, {
+      signal: options.signal,
+      query: { organization: options.organization }
+    });
+  }
+  decide(executionId, decision, options) {
+    return this.http.requestJson("POST", `/executions/${segment(executionId)}/review`, {
+      signal: options.signal,
+      query: { organization: options.organization },
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(decision)
+    });
+  }
+  /** Streaming Response: callers own consumption/cancellation. Never buffers the PDF. */
+  document(executionId, docKey, resource, options) {
+    if (typeof resource === "object" && (!Number.isSafeInteger(resource.page) || resource.page < 1 || resource.page > 999999))
+      throw new Error("Invalid page number");
+    const path = typeof resource === "object" ? `pages/${resource.page}` : resource;
+    const headers = Object.fromEntries(
+      Object.entries({
+        range: options.range,
+        "if-range": options.ifRange,
+        "if-none-match": options.ifNoneMatch,
+        "if-modified-since": options.ifModifiedSince
+      }).filter((entry) => typeof entry[1] === "string")
+    );
+    return this.http.requestRaw(
+      "GET",
+      `/executions/${segment(executionId)}/review/documents/${segment(docKey)}/${path}`,
+      {
+        signal: options.signal,
+        headers,
+        acceptStatuses: [304, 416],
+        query: {
+          organization: options.organization,
+          ...options.version ? { v: options.version } : {},
+          ...options.size ? { size: options.size } : {}
+        }
+      }
+    );
+  }
+};
+
+// src/sdk/execution-events.ts
+import { createHmac as createHmac2, timingSafeEqual as timingSafeEqual2 } from "crypto";
+
+// src/sdk/review-events.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var REVIEW_EVENT_TYPES = [
+  "execution.awaiting_review",
+  "execution.review_done",
+  "execution.review_closed",
+  "execution.review_expired"
+];
+var ReviewEventVerificationError = class extends Error {
+  constructor(reason) {
+    super(`Invalid review event ${reason}`);
+    this.reason = reason;
+    this.name = "ReviewEventVerificationError";
+  }
+  reason;
+};
+function parseReviewEventCallback(value) {
+  const fail = () => {
+    throw new ReviewEventVerificationError("payload");
+  };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return fail();
+  const raw = value;
+  const text = (key) => {
+    const v = raw[key];
+    if (typeof v !== "string" || !v.trim() || v.length > 512 || [...v].some((char) => char.charCodeAt(0) < 32))
+      return fail();
+    return v;
+  };
+  if (raw.schemaVersion !== 1 || !REVIEW_EVENT_TYPES.includes(raw.type))
+    return fail();
+  const event = {
+    schemaVersion: 1,
+    eventId: text("eventId"),
+    type: raw.type,
+    organization: text("organization"),
+    executionResultId: text("executionResultId"),
+    reviewId: text("reviewId"),
+    publishedAt: text("publishedAt")
+  };
+  if (!Number.isFinite(Date.parse(event.publishedAt))) return fail();
+  for (const key of ["flowId", "nodeId"])
+    if (raw[key] !== void 0) event[key] = text(key);
+  for (const key of ["flowVersion", "reviewVersion"]) {
+    if (raw[key] === void 0) continue;
+    if (!Number.isSafeInteger(raw[key]) || Number(raw[key]) < 1) return fail();
+    event[key] = Number(raw[key]);
+  }
+  if (raw.documentKeys !== void 0) {
+    if (!Array.isArray(raw.documentKeys) || raw.documentKeys.length > 1e3 || raw.documentKeys.some((v) => typeof v !== "string" || !v || v.length > 512))
+      return fail();
+    event.documentKeys = raw.documentKeys;
+  }
+  if (raw.decision !== void 0) {
+    if (!["continue", "exclude", "rerun", "reject"].includes(String(raw.decision))) return fail();
+    event.decision = raw.decision;
+  }
+  if (raw.reviewStatus !== void 0) {
+    if (!["completed", "rejected", "failed"].includes(String(raw.reviewStatus))) return fail();
+    event.reviewStatus = raw.reviewStatus;
+  }
+  if (event.type === "execution.review_done" && (!event.decision || !event.reviewVersion))
+    return fail();
+  if (event.type === "execution.review_closed" && !event.reviewStatus) return fail();
+  return event;
+}
+
+// src/sdk/execution-events.ts
+var EXECUTION_NODE_EVENT_TYPES = [
+  "execution.node.started",
+  "execution.node.completed",
+  "execution.node.failed",
+  "execution.node.reused"
+];
+function parseExecutionEventCallback(value) {
+  const raw = value;
+  if (!raw || !EXECUTION_NODE_EVENT_TYPES.includes(raw.type))
+    return parseReviewEventCallback(value);
+  const fail = () => {
+    throw new ReviewEventVerificationError("payload");
+  };
+  const text = (key) => {
+    const v = raw[key];
+    return typeof v === "string" && v.length > 0 && v.length <= 512 && [...v].every((c) => c.charCodeAt(0) >= 32) ? v : fail();
+  };
+  const integer = (key) => Number.isSafeInteger(raw[key]) && Number(raw[key]) >= 1 ? Number(raw[key]) : fail();
+  if (raw.schemaVersion !== 1) return fail();
+  const event = {
+    schemaVersion: 1,
+    eventId: text("eventId"),
+    type: raw.type,
+    organization: text("organization"),
+    executionResultId: text("executionResultId"),
+    sequence: integer("sequence"),
+    occurredAt: text("occurredAt"),
+    nodeId: text("nodeId"),
+    nodeType: text("nodeType"),
+    revision: integer("revision"),
+    attemptId: text("attemptId"),
+    documentKeys: []
+  };
+  if (!Number.isFinite(Date.parse(event.occurredAt))) return fail();
+  if (!Array.isArray(raw.documentKeys) || !raw.documentKeys.length || raw.documentKeys.length > 1e3 || raw.documentKeys.some(
+    (v) => typeof v !== "string" || !v || v.length > 512 || [...v].some((c) => c.charCodeAt(0) < 32)
+  ))
+    return fail();
+  event.documentKeys = raw.documentKeys;
+  if (raw.flowId !== void 0) event.flowId = text("flowId");
+  if (raw.flowVersion !== void 0) event.flowVersion = integer("flowVersion");
+  if (raw.publishedAt !== void 0) {
+    event.publishedAt = text("publishedAt");
+    if (!Number.isFinite(Date.parse(event.publishedAt))) return fail();
+  }
+  return event;
+}
+var ExecutionEvents = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** One bounded page; never polls for completion or consumes a final result. */
+  async list(id, options) {
+    const after = options.after ?? 0, limit = options.limit ?? 100;
+    if (!id || id.length > 512 || id === "." || id === ".." || /[\\/]/.test(id) || [...id].some((c) => c.charCodeAt(0) < 32) || !options.organization?.trim() || !Number.isSafeInteger(after) || after < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+      throw new Error("Invalid execution event query");
+    const page = await this.http.requestJson(
+      "GET",
+      `/executions/${encodeURIComponent(id)}/events`,
+      {
+        signal: options.signal,
+        query: { organization: options.organization, after: String(after), limit: String(limit) }
+      }
+    );
+    if (page.executionResultId !== id || !Array.isArray(page.events) || page.events.length > limit || !Number.isSafeInteger(page.lastSequence) || page.lastSequence < 0 || typeof page.truncated !== "boolean")
+      throw new ReviewEventVerificationError("payload");
+    const events = page.events.map((value) => parseExecutionEventCallback(value));
+    if (events.some(
+      (event, i) => !("sequence" in event) || event.executionResultId !== id || event.organization !== options.organization || event.sequence <= (i ? events[i - 1].sequence : after) || event.sequence > page.lastSequence
+    ))
+      throw new ReviewEventVerificationError("payload");
+    if (page.nextAfter !== null && (!Number.isSafeInteger(page.nextAfter) || page.nextAfter <= after || page.nextAfter !== events.at(-1)?.sequence))
+      throw new ReviewEventVerificationError("payload");
+    return { ...page, events };
+  }
+};
+
 // src/sdk/errors.ts
 var DocmanaError = class extends Error {
   status;
   requestId;
   code;
+  /** Public API business code; `code` retains the SDK's existing error category. */
+  apiCode;
+  reviewConflict;
   constructor(message, opts = {}) {
     super(message);
     this.name = new.target.name;
@@ -166,15 +532,28 @@ var HttpClient = class {
     if (res.status === 401 && this.opts.getAccessToken) {
       res = await this.send(method, path, options, true);
     }
-    if (!res.ok) {
+    if (!res.ok && !options.acceptStatuses?.includes(res.status)) {
       const requestId = res.headers.get("x-request-id") ?? void 0;
       const message = await this.extractMessage(res);
-      throw errorFromResponse(
+      const error = errorFromResponse(
         res.status,
         message,
         requestId,
         parseRetryAfterMs(res.headers.get("retry-after"))
       );
+      const data = await res.clone().json().catch(() => null);
+      if (typeof data?.code === "string" && /^[A-Za-z][A-Za-z0-9_]{0,99}$/.test(data.code))
+        Object.defineProperty(error, "apiCode", { value: data.code, enumerable: true });
+      if (res.status === 409 && data?.details)
+        Object.defineProperty(error, "reviewConflict", {
+          value: {
+            version: Number.isInteger(data.details.version) ? data.details.version : null,
+            submittedBy: typeof data.details.submittedBy === "string" ? data.details.submittedBy.slice(0, 200) : null,
+            submittedAt: typeof data.details.submittedAt === "string" ? data.details.submittedAt.slice(0, 40) : null
+          },
+          enumerable: true
+        });
+      throw error;
     }
     return res;
   }
@@ -674,6 +1053,9 @@ function fullJitterDelay(intervalMs, maxIntervalMs, attempt, random) {
 
 // src/sdk/client.ts
 var Docmana = class {
+  authoring;
+  reviews;
+  executionEvents;
   config;
   http;
   constructor(config) {
@@ -685,6 +1067,9 @@ var Docmana = class {
       getAccessToken: this.config.getAccessToken,
       headers: this.config.headers
     });
+    this.authoring = new FormulaAuthoring(this.http);
+    this.reviews = new Reviews(this.http);
+    this.executionEvents = new ExecutionEvents(this.http);
   }
   async runFlowAsync(flowId, params, options = {}) {
     const parts = await resolveInputs(params);