@docmana/sdk 0.32.0 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 0.36.0 - 2026-10-30
+
+- Promote the additive review and execution-event client APIs to a stable release.
+  Unused review APIs require no additional backend configuration.
+- Align native pending-list envelopes (documents are read on task detail), and
+  support confirmations, correction reasons and human review duration.
+- Preserve DOC-2558 review conflict metadata through Consumer Edge: `decidedBy`,
+  `decidedAt` and `currentVersion`, with the exported `ReviewConflictDetails` type.
+  Keep deprecated legacy aliases and bounded metadata; decision conflicts are
+  never retried automatically. Normal executions and final callbacks are unchanged.
+
+## 0.36.0-hitl.2 - 2026-10-23 (HITL prerelease)
+
+- Add `executionEvents.list()` and typed, non-consuming sequence-paged node
+  history for formulas with or without human review. Add the expanded
+  `verifyExecutionEventCallback` / `parseExecutionEventCallback` while retaining
+  the existing strict review-only helpers and final callback behavior.
+- Publish pilot versions under the explicit `hitl` npm distribution tag;
+  other prereleases use `next` and stable releases use `latest`.
+
+## 0.36.0-hitl.1 - 2026-10-23 (local POC)
+
+- Add `reviews.calculation()` and exported `ReviewCalculation` for non-consuming
+  provisional calculation state, coherent/target revisions, review counts and
+  per-revision node reuse. Preserve legacy null metadata, organization scope,
+  versioned decisions, assignment and final callback behavior.
+
+## 0.35.0-hitl.3 - 2026-10-22 (local POC)
+
+- Add optional `ReviewTask.findings` and exported `ReviewFinding` for explicit,
+  review-scoped field signals. Preserve missing/empty findings and existing
+  corrections, assignment, global confirmation and final callbacks.
+
+## 0.35.0-hitl.2 - 2026-10-22 (local POC)
+
+- Add optional read-only frozen review assessments (node score, description, feedback, explanation and reasoning). No per-field findings or decision/callback change.
+
+## 0.35.0-hitl.1 - 2026-10-22 (local POC)
+
+- Preserve optional native review lifecycle timestamps for Live's human-wait and activity display. No final result fetch, pipeline or callback contract change.
+
+## 0.34.0 - 2026-10-22
+
+- Add `reviews.document(id, docKey, "preview", options)` and exported
+  `DocumentPreviewManifest` for progressive import-time WebP preparation.
+  Existing document streams, review decisions and final callbacks are unchanged.
+
+## 0.33.0 - 2026-10-21
+
+- Add typed review event callbacks and raw-body HMAC signature verification for
+  Consumer's separate review event relay. Existing execution callbacks are unchanged.
+- Add `Docmana.reviews` for organization-scoped queues, task details, versioned
+  decisions and streaming page/content/location reads. Preserve range/cache
+  statuses and safe conflict metadata; never automatically retry decisions.
+- Expose `AWAITING_REVIEW` as a non-terminal execution status.
+
 ## Unreleased
 
 ## 0.32.0 - 2026-10-19
@@ -257,3 +313,7 @@ consu## 0.16.0
 - Typed error hierarchy (`DocmanaError`, `DocmanaExecutionError`, …).
 - Flexible file inputs: path, `Buffer`, `Stream`, and multi-file uploads.
 - Dual ESM + CJS distribution with bundled type definitions.
+
+### Local HITL outline addition
+
+- Add reviews.outline with typed published formula steps, edges and review marks. Existing execution, decision and final callback contracts are unchanged.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Docmana
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Docmana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,68 @@
 # @docmana/sdk
 
+The HITL pilot uses the explicit prerelease `0.36.0-hitl.2` and the npm `hitl`
+distribution tag. Install the exact version for reproducible pilot builds:
+
+```sh
+npm install --save-exact @docmana/sdk@0.36.0-hitl.2
+```
+
+The stable default remains on `latest`; the prerelease does not select a native
+API. Configure the SDK's Consumer base URL on the application server.
+
+## Real formula node progress (local HITL pilot)
+
+`sdk.executionEvents.list(executionId, { organization, after: 0, limit: 100, signal })`
+reads a non-consuming metadata journal, including formulas without human review.
+Follow `nextAfter` while non-null; order by `sequence`, deduplicate `eventId`, and
+honor `truncated` when the cursor predates retained history. The native journal
+keeps at most 2,000 events with the execution. No PDF or final-result retention
+is added. Older APIs can return 404; show confirmed status without inventing
+progress. Never turn a journal failure into a call to another backend.
+
+The four new names are `execution.node.started`, `execution.node.completed`,
+`execution.node.failed`, and `execution.node.reused`. Events identify a node,
+document keys, revision and attempt. A reused output does not imply a new LLM
+call. Completion of a node is technical completion, not a positive business
+verdict or final execution completion. `occurredAt` is the real action time;
+`publishedAt` is optional broker time, present on signed callbacks.
+
+`verifyExecutionEventCallback` and `parseExecutionEventCallback` accept both the
+new node metadata and the four existing review events. Existing review-only
+verification helpers remain strict and unchanged. Final execution callbacks and
+result ownership keep their existing contract; there are no pipeline events.
+
+## Review event callbacks
+
+SDK 0.33.0 adds server-side `verifyReviewEventCallback`, `parseReviewEventCallback`
+and the `ReviewEventCallback` type for Consumer's opt-in review event relay.
+This is independent from `runFlowAsync({ callbackUrl })`, which still receives only
+the final result. No Service Bus connection is required in your application.
+
+```ts
+import { verifyReviewEventCallback } from "@docmana/sdk";
+const event = verifyReviewEventCallback({
+  body: rawUtf8Body,
+  signature: request.headers.get("x-docmana-event-signature"),
+  timestamp: request.headers.get("x-docmana-event-timestamp"),
+  secret: serverConfiguredSecret, // at least 32 characters; never sent to a browser
+  organization: expectedOrganization,
+});
+await persistOnce(event.organization, event.eventId, event);
+// Only now return 2xx. Never finalize an execution from a review notification.
+```
+
+Supported types are `execution.awaiting_review`, `execution.review_done`,
+`execution.review_closed` and `execution.review_expired`. `review_done` means the
+decision is recorded, not that the execution is finished. `review_closed` also
+describes the review rather than the execution. `publishedAt` is the broker's
+publication time. The metadata excludes document names, values, notes and results.
+Signatures use HMAC-SHA256 over `timestamp + "." + rawBody` with header `v1=<hex>`;
+verification accepts a five-minute clock difference. Broker retries are re-signed
+but retain the event ID; store it durably for deduplication. An event notification
+never consumes the final result. Source publication is best-effort: reconcile
+current review state separately after a missed notification.
+
 Official Docmana SDK for calling `docmana-consumer-edge-api`.
 
 SDK 0.32.0 adds native formula authoring, assisted conversations and revision-pinned
@@ -18,6 +81,17 @@ status, and returns the mapped Consumer execution DTO.
 npm install @docmana/sdk
 ```
 
+### GitHub release recovery
+
+The Release workflow publishes an existing `v<version>` tag. GitHub Actions are
+pinned to full commit SHAs to satisfy the enterprise policy. If a tag-triggered
+run fails before starting, merge the workflow correction first, then manually
+run **Release** from `main` with that existing tag. The workflow checks out the
+tag and verifies its package version before publishing; do not move a release
+tag to repair a pipeline. Publication requires the existing npm publisher
+credential or trusted-publishing configuration. Verify the version is available
+in npm before updating a consumer's lockfile.
+
 Requires Node.js 20+.
 
 ## Quickstart
@@ -450,6 +524,98 @@ user confirmation before submitting the same file with `confirmOverwrite: true`.
 `remove(id, options)` permanently deletes the formula and its authoring data;
 confirm that action with the user. Import and deletion do not use operation IDs.
 
+## Human review of formula executions
+
+The native pending queue omits documents: load the selected task with `reviews.get()`
+before displaying its values and documents. Decided tasks leave this queue; resume
+progress belongs to the execution. `ReviewDecision` also supports `confirmations`,
+per-correction `reason`, and `durationSeconds`. Conflict details identify an already
+submitted decision or the current version; no decision is retried automatically.
+
+Read calculation metadata repeatedly with
+`client.reviews.calculation(executionId, { organization })`. It returns
+`executionResultId`, normalized `executionStatus` and `calculation` (null for
+legacy/unmarked runs). Calculation includes `status`, coherent `revision`
+(0 before the first calculation), optional `targetRevision`, `provisional`,
+review counts and computed/reused node counts for that revision. Node counts
+are not individual model-call counts. Calculation revision is distinct from
+`ReviewTask.version`, which remains required for decisions. A completed
+calculation stays provisional until the persisted execution is terminal.
+This read is available before the first review and after final callback delivery;
+it never consumes the single-use final result or triggers pipelines/callbacks.
+
+Requires Consumer's review routes and the compatible HITL Document API branch.
+No pipelines are required. Start published manual formulas with `runFlowAsync`;
+`AWAITING_REVIEW` is non-terminal. `runFlow` still waits for final completion and
+retains its configured timeout, so do not hold an HTTP request open for human work.
+
+```ts
+const scope = { organization: "your-organization", signal: controller.signal };
+const { reviews, nextCursor } = await docmana.reviews.list({
+  ...scope,
+  status: "pending",
+  limit: 50,
+});
+const task = await docmana.reviews.get(reviews[0].executionResultId, scope);
+await docmana.reviews.decide(
+  task.executionResultId,
+  {
+    decision: "continue",
+    version: task.version,
+    reviewer: authenticatedServerActor, // Never trust an identity from the browser.
+    corrections: [{ itemId: task.documents[0].items![0].itemId, value: false }],
+  },
+  scope,
+);
+// Preparation starts at import. Poll queued/processing; other states are terminal.
+const preparation = await docmana.reviews.document(
+  task.executionResultId,
+  task.documents[0].docKey,
+  "preview",
+  {
+    ...scope,
+    version: task.reviewId,
+  },
+);
+const manifest = await preparation.json(); // DocumentPreviewManifest
+// Only fetch numbers present in manifest.pages; page 1 precedes later batches.
+// Original content remains available as the PDF fallback.
+const page = await docmana.reviews.document(
+  task.executionResultId,
+  "doc01",
+  { page: 1 },
+  {
+    ...scope,
+    version: task.reviewId,
+    size: "thumb",
+  },
+);
+// page is a streaming Fetch Response. Consume or cancel its body; do not buffer a large PDF.
+```
+
+`list` accepts `pending`, `submitted`, `resuming` and an opaque `cursor`. It lists
+open tasks only. The `"*"` dossier entry is not a file. Use the returned item IDs
+unchanged; JSON values preserve `null`, `false`, `0`, objects and arrays.
+`document` also accepts `"content"` or `"locations"`, Range/If-Range and ETag
+options. It returns 200/206/304/416 without consuming the body.
+
+A decision receipt means **recorded and resume queued**, never final completion.
+On 409 inspect `DocmanaError.reviewConflict` and `apiCode`, then re-read the task.
+`REVIEW_ALREADY_SUBMITTED` can include `reviewConflict.decidedBy` (`id`, `name`,
+`source: "integrator" | "token"`) and `decidedAt`.
+`REVIEW_VERSION_STALE` can include `reviewConflict.currentVersion`.
+Missing metadata remains `null`; only bounded, whitelisted fields are retained.
+The previous `version`, `submittedBy` and `submittedAt` properties remain as
+deprecated compatibility aliases. Never replace the submitted version with the
+new version and retry automatically: let the user inspect the refreshed task.
+On 503 re-read first: the decision may already be recorded. The SDK does not retry
+a decision after a conflict, 503 or uncertain transport outcome. The standard one-time
+401 token-refresh retry still applies. Keep the existing final callback/polling result owner;
+opening a review must not consume the single-use execution result.
+
+Release order: compatible Document API, Consumer, published SDK, then Arcana's
+exact pinned dependency. Preparing this change does not publish or deploy it.
+
 ## License
 
 MIT
@@ -476,3 +642,20 @@ Use `authoring.trialDocument(fileBlob, filename, spec, { organization, signal })
 For assisted Mongo nodes, call `authoring.documentTrialDefinitions({ flowId, expectedRevisions, node | allNodes }, { organization, signal })`. This read-only preparation pins active node-owned rules and settings to the coherent native snapshot, checking revisions again after resolution. Pass the returned definition and uploaded file to the server-side `runAssistedDocumentTrial` library in `@docmana/docmana-flows`. Git callers use Flows' `prepareDocumentTrial` directly. Neither path requires `/extract/test-assisted` or a modified DocMana API. Calling the old native trial method with assisted nodes now fails before upload with HTTP 422.
 
 Flows owns assisted IDP/model calls and requires its server-side provider configuration. It analyzes the file once and tries up to 100 compatible classification/extraction nodes independently, retaining evidence envelopes. Files are nonempty PDF/images up to 20 MiB. Definitions and uploads use disposable local storage, cleaned after completion; no formula, rule, reference expectation or publication is saved. These trials do not execute production routing, translate results, compare expectations or produce release approval evidence. Missing upstream context is rejected. Native API accounting and PromptShield are not implied by the Flows executor. No new CLI command is introduced.
+
+### Formula steps during human review
+
+Task detail also preserves optional native `createdAt`, `submittedAt`, `resumingAt` and `closedAt` timestamps. Human waiting is bounded by task creation and native decision acceptance; review closure does not prove final execution completion. Older backends can omit these fields; clients must show an unavailable duration rather than infer it from callback delivery time.
+
+Use client.reviews.outline(flowId, { organization }) to read the published nodes, edges, ordering and human-review marks through Consumer. Compare outline.version with the review flowVersion before displaying progress. This read never consumes an execution result and does not introduce pipelines.
+
+### Frozen review evidence (local HITL pilot)
+
+`reviews.get()` optionally returns `documents[].assessments`: the stored node score (0–100), `scoreDescription`, `feedback`, `explanation` and `reasoning` from the same frozen snapshot as the items. These are read-only node-level evidence, not uncertain-field findings. Older backends may omit assessments or scores; do not infer missing scores. Decisions still send only editable item corrections through Consumer.
+
+`ReviewTask.findings?: ReviewFinding[]` separately carries explicit field signals:
+stable review-scoped `id`, `code`, `message`, resolved `itemIds`, and optional
+`source` (`model` or `rule`). Consumers must not infer fields from node scores or
+explanation text. Missing or empty findings preserve the existing presentation.
+These are frozen evidence, not per-field decisions; editing a value does not
+erase its finding. Continue using the same global, versioned decision call.

package/dist/cli.mjs

@@ -171,6 +171,234 @@ 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;
+}
+
+// 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;
@@ -178,6 +406,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;
@@ -303,7 +532,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(
@@ -315,6 +544,11 @@ 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 && isRecord(data?.details))
+        Object.defineProperty(error, "reviewConflict", {
+          value: reviewConflictDetails(data.details),
+          enumerable: true
+        });
       throw error;
     }
     return res;
@@ -358,6 +592,32 @@ var HttpClient = class {
     }
   }
 };
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function reviewConflictDetails(raw) {
+  const text = (value, limit) => typeof value === "string" ? value.slice(0, limit) : null;
+  const version = (value) => Number.isSafeInteger(value) && Number(value) >= 1 ? value : null;
+  const actor = isRecord(raw.decidedBy) ? raw.decidedBy : {};
+  const id = text(actor.id, 200);
+  const name = text(actor.name, 200);
+  const source = actor.source === "integrator" || actor.source === "token" ? actor.source : null;
+  const decidedBy = id !== null || name !== null || source !== null ? {
+    ...id !== null ? { id } : {},
+    ...name !== null ? { name } : {},
+    ...source ? { source } : {}
+  } : null;
+  const currentVersion = version(raw.currentVersion) ?? version(raw.version);
+  const decidedAt = text(raw.decidedAt, 40) ?? text(raw.submittedAt, 40);
+  return {
+    currentVersion,
+    decidedBy,
+    decidedAt,
+    version: currentVersion,
+    submittedBy: id ?? name ?? text(raw.submittedBy, 200),
+    submittedAt: decidedAt
+  };
+}
 function parseRetryAfterMs(value) {
   if (!value) return void 0;
   const seconds = Number(value);
@@ -816,6 +1076,8 @@ function fullJitterDelay(intervalMs, maxIntervalMs, attempt, random) {
 // src/sdk/client.ts
 var Docmana = class {
   authoring;
+  reviews;
+  executionEvents;
   config;
   http;
   constructor(config) {
@@ -828,6 +1090,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);