@docmana/sdk 0.32.0 → 0.36.0-hitl.2

package/dist/index.mjs

@@ -163,6 +163,276 @@ var FormulaAuthoring = class {
   }
 };
 
+// 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;
+}
+function verifyReviewEventCallback(options) {
+  const { body, signature, timestamp, secret } = options;
+  if (!timestamp || !/^\d{10,13}$/.test(timestamp))
+    throw new ReviewEventVerificationError("timestamp");
+  const age = Math.abs((options.nowMs ?? Date.now()) / 1e3 - Number(timestamp));
+  if (age > (options.toleranceSeconds ?? 300)) throw new ReviewEventVerificationError("timestamp");
+  if (secret.length < 32 || !signature || !/^v1=[a-f0-9]{64}$/.test(signature))
+    throw new ReviewEventVerificationError("signature");
+  const expected = createHmac("sha256", secret).update(`${timestamp}.${body}`).digest();
+  if (!timingSafeEqual(expected, Buffer.from(signature.slice(3), "hex")))
+    throw new ReviewEventVerificationError("signature");
+  let value;
+  try {
+    value = JSON.parse(body);
+  } catch {
+    throw new ReviewEventVerificationError("payload");
+  }
+  const event = parseReviewEventCallback(value);
+  if (options.organization !== void 0 && event.organization !== options.organization)
+    throw new ReviewEventVerificationError("organization");
+  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;
+}
+function verifyExecutionEventCallback(options) {
+  const { body, signature, timestamp, secret } = options;
+  if (!timestamp || !/^\d{10,13}$/.test(timestamp) || Math.abs((options.nowMs ?? Date.now()) / 1e3 - Number(timestamp)) > (options.toleranceSeconds ?? 300))
+    throw new ReviewEventVerificationError("timestamp");
+  if (secret.length < 32 || !signature || !/^v1=[a-f0-9]{64}$/.test(signature))
+    throw new ReviewEventVerificationError("signature");
+  const expected = createHmac2("sha256", secret).update(`${timestamp}.${body}`).digest();
+  if (!timingSafeEqual2(expected, Buffer.from(signature.slice(3), "hex")))
+    throw new ReviewEventVerificationError("signature");
+  let value;
+  try {
+    value = JSON.parse(body);
+  } catch {
+    throw new ReviewEventVerificationError("payload");
+  }
+  const event = parseExecutionEventCallback(value);
+  if (options.organization !== void 0 && event.organization !== options.organization)
+    throw new ReviewEventVerificationError("organization");
+  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;
@@ -170,6 +440,7 @@ var DocmanaError = class extends Error {
   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;
@@ -295,7 +566,7 @@ 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);
       const error = errorFromResponse(
@@ -307,6 +578,15 @@ var HttpClient = class {
       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;
@@ -808,6 +1088,8 @@ function fullJitterDelay(intervalMs, maxIntervalMs, attempt, random) {
 // src/sdk/client.ts
 var Docmana = class {
   authoring;
+  reviews;
+  executionEvents;
   config;
   http;
   constructor(config) {
@@ -820,6 +1102,8 @@ var Docmana = class {
       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);
@@ -1005,6 +1289,15 @@ export {
   DocmanaRequestError,
   DocmanaServiceUnavailableError,
   DocmanaTimeoutError,
-  FormulaAuthoring
+  EXECUTION_NODE_EVENT_TYPES,
+  ExecutionEvents,
+  FormulaAuthoring,
+  REVIEW_EVENT_TYPES,
+  ReviewEventVerificationError,
+  Reviews,
+  parseExecutionEventCallback,
+  parseReviewEventCallback,
+  verifyExecutionEventCallback,
+  verifyReviewEventCallback
 };
 //# sourceMappingURL=index.mjs.map