@docmana/sdk 0.32.0 → 0.36.0-hitl.2

package/dist/client.d.ts

@@ -1,7 +1,11 @@
 import { FormulaAuthoring } from "./authoring.js";
+import { Reviews } from "./reviews.js";
+import { ExecutionEvents } from "./execution-events.js";
 import type { AccessibleOrganization, DocmanaConfig, DocmanaExecutionResult, DownloadedOrganizationDocument, ExecutionStatus, FraudDetectionAccepted, FraudDetectionAsyncOptions, FraudDetectionOptions, FraudDetectionParams, FraudDetectionResult, FraudDetectionStatusResult, FlowDefinition, FlowListItem, FlowMetadata, OrganizationDocumentsPayload, RunFlowAsyncParams, RunFlowAsyncOptions, RunFlowOptions, RunFlowParams, RunPartialFlowAsyncParams, RunPartialFlowOptions, RunPartialFlowParams } from "./types.js";
 export declare class Docmana {
     readonly authoring: FormulaAuthoring;
+    readonly reviews: Reviews;
+    readonly executionEvents: ExecutionEvents;
     private readonly config;
     private readonly http;
     constructor(config: DocmanaConfig);

package/dist/errors.d.ts

@@ -6,6 +6,11 @@ export declare class DocmanaError extends Error {
     readonly code: string;
     /** Public API business code; `code` retains the SDK's existing error category. */
     readonly apiCode?: string;
+    readonly reviewConflict?: {
+        version: number | null;
+        submittedBy: string | null;
+        submittedAt: string | null;
+    };
     constructor(message: string, opts?: {
         status?: number;
         requestId?: string;

package/dist/execution-events.d.ts

@@ -0,0 +1,47 @@
+import type { HttpClient } from "./http/http-client.js";
+import type { ExecutionStatus } from "./models/execution-status.enum.js";
+import { type ReviewEventCallback, type verifyReviewEventCallback } from "./review-events.js";
+export declare const EXECUTION_NODE_EVENT_TYPES: readonly ["execution.node.started", "execution.node.completed", "execution.node.failed", "execution.node.reused"];
+export interface ExecutionNodeEvent {
+    schemaVersion: 1;
+    eventId: string;
+    type: (typeof EXECUTION_NODE_EVENT_TYPES)[number];
+    organization: string;
+    executionResultId: string;
+    sequence: number;
+    occurredAt: string;
+    /** Broker publication instant, present only on event callbacks. */
+    publishedAt?: string;
+    flowId?: string;
+    flowVersion?: number;
+    nodeId: string;
+    nodeType: string;
+    documentKeys: string[];
+    revision: number;
+    attemptId: string;
+}
+export type ExecutionEventCallback = ExecutionNodeEvent | ReviewEventCallback;
+export interface ExecutionEventsPage {
+    executionResultId: string;
+    executionStatus: ExecutionStatus;
+    flowId?: string;
+    flowVersion?: number | null;
+    events: ExecutionNodeEvent[];
+    nextAfter: number | null;
+    lastSequence: number;
+    truncated: boolean;
+}
+export declare function parseExecutionEventCallback(value: unknown): ExecutionEventCallback;
+/** Expanded signature verifier. Existing review-only parser/verifier keep their contract. */
+export declare function verifyExecutionEventCallback(options: Parameters<typeof verifyReviewEventCallback>[0]): ExecutionEventCallback;
+export declare class ExecutionEvents {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** One bounded page; never polls for completion or consumes a final result. */
+    list(id: string, options: {
+        organization: string;
+        after?: number;
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<ExecutionEventsPage>;
+}

package/dist/http/http-client.d.ts

@@ -9,6 +9,8 @@ export interface HttpClientOptions {
 }
 type FetchBody = NonNullable<Parameters<typeof fetch>[1]>["body"];
 export interface RequestOptions {
+    /** Conditional document reads can legitimately return 304 or 416. */
+    acceptStatuses?: readonly number[];
     query?: Record<string, string>;
     body?: FetchBody;
     headers?: Record<string, string>;

package/dist/index.d.ts

@@ -1,6 +1,12 @@
 export { Docmana } from "./client.js";
+export { REVIEW_EVENT_TYPES, parseReviewEventCallback, verifyReviewEventCallback, ReviewEventVerificationError, } from "./review-events.js";
+export type { ReviewEventCallback, ReviewEventType } from "./review-events.js";
 export { FormulaAuthoring } from "./authoring.js";
 export type { AuthoringDocumentTrialNode, AuthoringDocumentTrialSpec, AuthoringDocumentTrialReport, AuthoringSource, AuthoringGitPublication, AuthoringGitProjection, AuthoringPublication, AuthoringConversation, AuthoringConversationInput, AuthoringConversationContext, AuthoringConversationTurn, AuthoringData, AuthoringNode, AuthoringEdge, AuthoringRevisions, AuthoringFlowSummary, AuthoringSnapshot, AuthoringChanges, AuthoringDraft, AuthoringCreate, AuthoringReceipt, AuthoringOptions, AuthoringEditorCatalog, AuthoringPageOptions, } from "./authoring.js";
 export { DocmanaError, DocmanaAuthError, DocmanaRequestError, DocmanaPayloadTooLargeError, DocmanaPermissionError, DocmanaNotFoundError, DocmanaExecutionError, DocmanaFraudDetectionError, DocmanaTimeoutError, DocmanaAbortError, DocmanaServiceUnavailableError, } from "./errors.js";
 export type { AccessibleOrganization, DownloadedOrganizationDocument, DocmanaConfig, FlowDefinition, FlowDefinitionField, FlowDefinitionNode, FlowDefinitionNodeMetadata, FlowDocumentRequirement, FlowListItem, FlowMetadata, FraudDetectionAccepted, FraudDetectionAsyncOptions, FraudDetectionBaseParams, FraudDetectionError, FraudDetectionFileParams, FraudDetectionOptions, FraudDetectionParams, FraudDetectionProcessor, FraudDetectionResult, FraudDetectionStatus, FraudDetectionStatusResult, FraudDetectionSummary, FraudDetectionUrlParams, FraudDetectionVerdict, FraudFinding, FraudFindingLocation, FraudFindingSeverity, FraudSeverityCounts, OrganizationDocument, OrganizationDocumentsPayload, PartialExecutionFlowVersion, PartialExecutionMetadata, PartialExecutionScope, RunFlowAsyncParams, RunFlowAsyncOptions, RunFlowOptions, RunFlowParams, RunPartialFlowAsyncParams, RunPartialFlowOptions, RunPartialFlowParams, FileInput, NamedFileInput, PathFileInput, DocmanaExecutionResult, DocmanaExecutionVerdict, ExecutionStatus, DocmanaDocumentMapping, DocmanaSourceDocument, DocmanaDocumentResult, DocmanaNodeResult, DocmanaScoreNodeResult, DocmanaCrossValidationResult, DocmanaConclusionResult, DocmanaClassificationResult, DocmanaMetadataExtractionResult, DocmanaExtractionResult, DocmanaValidationResult, DocmanaPreprocessingResult, } from "./types.js";
 export type { ExecutionProgress, VirtualDocument, PhysicalDocument, DocumentContent, FlowNodeType, FlowConfigs, FlowNode, FlowEdge, Flow, NodeTranslationResult, DocmanaApiExecutionResult, DocmanaApiNodeResult, DocmanaApiDocumentExecutionResult, DocmanaApiDocumentRequest, DocmanaApiPreprocessDocumentResult, } from "./models/index.js";
+export { Reviews } from "./reviews.js";
+export { ExecutionEvents, EXECUTION_NODE_EVENT_TYPES, parseExecutionEventCallback, verifyExecutionEventCallback, } from "./execution-events.js";
+export type { ExecutionNodeEvent, ExecutionEventCallback, ExecutionEventsPage, } from "./execution-events.js";
+export type { ReviewCalculation, ReviewFlowOutline, ReviewItem, DocumentPreviewManifest, ReviewDocument, ReviewAssessment, ReviewFinding, ReviewTask, ReviewSummary, ReviewDecision, ReviewReadOptions, ReviewDocumentOptions, } from "./reviews.js";

package/dist/index.js

@@ -32,7 +32,16 @@ __export(sdk_exports, {
   DocmanaRequestError: () => DocmanaRequestError,
   DocmanaServiceUnavailableError: () => DocmanaServiceUnavailableError,
   DocmanaTimeoutError: () => DocmanaTimeoutError,
-  FormulaAuthoring: () => FormulaAuthoring
+  EXECUTION_NODE_EVENT_TYPES: () => EXECUTION_NODE_EVENT_TYPES,
+  ExecutionEvents: () => ExecutionEvents,
+  FormulaAuthoring: () => FormulaAuthoring,
+  REVIEW_EVENT_TYPES: () => REVIEW_EVENT_TYPES,
+  ReviewEventVerificationError: () => ReviewEventVerificationError,
+  Reviews: () => Reviews,
+  parseExecutionEventCallback: () => parseExecutionEventCallback,
+  parseReviewEventCallback: () => parseReviewEventCallback,
+  verifyExecutionEventCallback: () => verifyExecutionEventCallback,
+  verifyReviewEventCallback: () => verifyReviewEventCallback
 });
 module.exports = __toCommonJS(sdk_exports);
 
@@ -201,6 +210,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
+var import_node_crypto2 = require("crypto");
+
+// src/sdk/review-events.ts
+var import_node_crypto = require("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 = (0, import_node_crypto.createHmac)("sha256", secret).update(`${timestamp}.${body}`).digest();
+  if (!(0, import_node_crypto.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 = (0, import_node_crypto2.createHmac)("sha256", secret).update(`${timestamp}.${body}`).digest();
+  if (!(0, import_node_crypto2.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 = 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;
@@ -208,6 +487,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;
@@ -333,7 +613,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(
@@ -345,6 +625,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;
@@ -846,6 +1135,8 @@ function fullJitterDelay(intervalMs, maxIntervalMs, attempt, random) {
 // src/sdk/client.ts
 var Docmana = class {
   authoring;
+  reviews;
+  executionEvents;
   config;
   http;
   constructor(config) {
@@ -858,6 +1149,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);
@@ -1044,6 +1337,15 @@ function isTransientPollingError(error) {
   DocmanaRequestError,
   DocmanaServiceUnavailableError,
   DocmanaTimeoutError,
-  FormulaAuthoring
+  EXECUTION_NODE_EVENT_TYPES,
+  ExecutionEvents,
+  FormulaAuthoring,
+  REVIEW_EVENT_TYPES,
+  ReviewEventVerificationError,
+  Reviews,
+  parseExecutionEventCallback,
+  parseReviewEventCallback,
+  verifyExecutionEventCallback,
+  verifyReviewEventCallback
 });
 //# sourceMappingURL=index.js.map