@docmana/sdk 0.36.0-hitl.2 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.37.0 - 2026-11-05
+
+- Support upstream field and classification corrections through the existing `continue` decision.
+  The backend recalculates dependent steps and selects the next checkpoint.
+- Type correction provenance (`origin`, `originalValue`), document downstream steps, and
+  dossier context and results. `reviews.get()` returns an empty `documents` array when a
+  decided review's held data has been released.
+
+## 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

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

@@ -526,6 +526,25 @@ 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.
+
+To correct an upstream result, read the current task and select the `itemId`
+of a field or classification in `documents[].context`. Submit
+`decision: "continue"` with the current review version and
+`corrections: [{ itemId, value }]`. Confirmations name current `items` only.
+DocMana API validates eligibility, recalculates dependent steps and selects the
+next checkpoint. After the accepted response, read the current task again.
+
+`documents[].downstream` and `dossierResults` expose read-only calculated steps.
+`dossierContext` carries the captured JSON context. `origin` and `originalValue`
+describe applied human changes. These fields are optional for older backends.
+When the backend releases a decided task's held data, `reviews.get()` returns
+`documents: []` with the remaining task metadata.
+
 Read calculation metadata repeatedly with
 `client.reviews.calculation(executionId, { organization })`. It returns
 `executionResultId`, normalized `executionStatus` and `calculation` (null for
@@ -595,13 +614,20 @@ 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. This local 0.33.0 candidate is not published by these steps.
+exact pinned dependency. Preparing this change does not publish or deploy it.
 
 ## License
 

package/dist/cli.mjs

@@ -211,6 +211,11 @@ var Reviews = class {
     return this.http.requestJson("GET", `/executions/${segment(executionId)}/review`, {
       signal: options.signal,
       query: { organization: options.organization }
+    }).then((task) => {
+      if (typeof task?.status === "string" && task.status !== "pending" && task.documents === void 0) {
+        return { ...task, documents: [] };
+      }
+      return task;
     });
   }
   decide(executionId, decision, options) {
@@ -544,13 +549,9 @@ 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)
+      if (res.status === 409 && isRecord(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
-          },
+          value: reviewConflictDetails(data.details),
           enumerable: true
         });
       throw error;
@@ -596,6 +597,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);