@superdoc/sdk 2.15.1-next.5 → 2.16.0-next.10

package/README.md

@@ -60,6 +60,71 @@ is not supported for Liveblocks or the standalone document host.
 
 See the [Node.js SDK guide](https://docs.superdoc.dev/agents/automation/node-sdk) for a complete workflow.
 
+## Tracked comparison with exact-file review
+
+The SDK's `diff.capture` and `diff.compare` describe a snapshot comparison. A
+blocked tracked `diff.apply` cannot turn that snapshot into a complete review
+proposal: the host must provide the exact base and target DOCX bytes, a durable
+review store, a document ID, and an authenticated actor. For a Node host using
+the V2 document runtime, `runTrackedComparisonReview` connects those steps:
+
+```js
+import { readFile } from 'node:fs/promises';
+import { createSuperDocClient, runTrackedComparisonReview } from '@superdoc/sdk';
+import {
+  createDocumentProposalManager,
+  createFileDocumentReviewStore,
+  openVersionedDocumentReviewSession,
+} from '@superdoc/docx-engine/document-runtime';
+
+const baseBytes = new Uint8Array(await readFile(basePath));
+const targetBytes = new Uint8Array(await readFile(targetPath));
+const actor = authenticatedUser.name; // Set by the host's authentication layer.
+const store = createFileDocumentReviewStore(durableReviewDirectory);
+const manager = createDocumentProposalManager(store);
+if (!(await store.read(documentId))) {
+  const initial = await manager.initialize({ documentId, bytes: baseBytes, savePolicy: 'suggest-only' });
+  if (initial.kind !== 'initialized' && initial.kind !== 'stale') throw new Error(initial.kind);
+}
+
+const session = await openVersionedDocumentReviewSession({ store, documentId, actor });
+const client = createSuperDocClient({
+  user: { name: actor },
+  requestTimeoutMs: 120_000,
+  env: { SUPERDOC_SDK_DOCUMENT_HOST_BIN: 'embedded' },
+});
+try {
+  const { diff, comparisonError, result } = await runTrackedComparisonReview({
+    client, baseBytes, targetBytes, documentId, actor,
+    currentReviewDocument: (id) => manager.current(id),
+    reviewSession: session,
+    options: { timeoutMs: 120_000 },
+  });
+  console.log(diff?.applyEligibility?.tracked, comparisonError);
+  if (result.kind === 'prepared') {
+    const preview = await session.preview(result.id);
+    // Present the whole-document proposal and its exact base/target files to a reviewer.
+    // Call session.decide(result.id, 'accept' or 'reject') after their decision.
+  } else if (result.kind !== 'native-revisions-applied') {
+    throw new Error(`Tracked review did not proceed: ${result.kind}`);
+  }
+  // manager.current(documentId) supplies export bytes; manager.history(documentId) supplies audit events.
+} finally {
+  await client.dispose();
+  await session.close();
+}
+```
+
+The helper stages private copies of the exact bytes for SDK capture and compare,
+checks the store's current base and the review session's version, document, and
+actor binding, then calls the versioned session's `applyTarget` in tracked mode.
+If SDK import or comparison is unavailable, `comparisonError` explains why
+`diff` is null and exact-file review still runs.
+That session chooses native Word revisions only after proving accept and reject
+endpoints; other supported changes become one whole-document proposal. A stale
+base or invalid DOCX returns a refusal without a partial apply. The host owns
+authorization, durable storage, reviewer presentation, and decisions.
+
 ## Agent execution evidence
 
 The core preset's `agent_apply`, `agent_verify`, and supported named actions

package/dist/generated/client.cjs

@@ -213,6 +213,7 @@ function createDocApi(runtime) {
         },
         selection: {
             current: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.selection.current"], params, options),
+            extractOoxml: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.selection.extractOoxml"], params, options),
         },
         mutations: {
             preview: (params, options) => runtime.invoke(contract.CONTRACT.operations["doc.mutations.preview"], params, options),
@@ -347,6 +348,7 @@ function createDocApi(runtime) {
             },
         },
         watermarks: {
+            apply: (params, options) => runtime.invoke(contract.CONTRACT.operations["doc.watermarks.apply"], params, options),
             list: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.watermarks.list"], params, options),
             insert: (params, options) => runtime.invoke(contract.CONTRACT.operations["doc.watermarks.insert"], params, options),
             replace: (params, options) => runtime.invoke(contract.CONTRACT.operations["doc.watermarks.replace"], params, options),
@@ -785,6 +787,7 @@ function createBoundDocApi(runtime) {
         },
         selection: {
             current: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.selection.current"], params, options),
+            extractOoxml: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.selection.extractOoxml"], params, options),
         },
         mutations: {
             preview: (params, options) => runtime.invoke(contract.CONTRACT.operations["doc.mutations.preview"], params, options),
@@ -919,6 +922,7 @@ function createBoundDocApi(runtime) {
             },
         },
         watermarks: {
+            apply: (params, options) => runtime.invoke(contract.CONTRACT.operations["doc.watermarks.apply"], params, options),
             list: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.watermarks.list"], params, options),
             insert: (params, options) => runtime.invoke(contract.CONTRACT.operations["doc.watermarks.insert"], params, options),
             replace: (params, options) => runtime.invoke(contract.CONTRACT.operations["doc.watermarks.replace"], params, options),