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

package/dist/index.cjs

@@ -13,6 +13,7 @@ var v2PresetCompat = require('./agent/v2-preset-compat.cjs');
 var actions = require('./agent/actions.cjs');
 var operationCatalog = require('./agent/operation-catalog.cjs');
 var define = require('./actions/define.cjs');
+var trackedReviewRoute = require('./tracked-review-route.cjs');
 var presets = require('./presets.cjs');
 
 // ---------------------------------------------------------------------------
@@ -221,6 +222,7 @@ exports.wrapV2PresetCompat = v2PresetCompat.wrapV2PresetCompat;
 exports.getActionDispositions = actions.getActionDispositions;
 exports.getOperationInputAliases = operationCatalog.getOperationInputAliases;
 exports.defineAction = define.defineAction;
+exports.runTrackedComparisonReview = trackedReviewRoute.runTrackedComparisonReview;
 exports.DEFAULT_PRESET = presets.DEFAULT_PRESET;
 exports.getPreset = presets.getPreset;
 exports.listPresets = presets.listPresets;

package/dist/index.d.ts

@@ -103,5 +103,7 @@ export type { AgentToolkit, CreateAgentToolkitInput } from './tools.js';
 export { defineAction } from './actions/define.js';
 export type { ActionSpec, ActionStep, DefineActionInput, JSONSchemaObject } from './actions/define.js';
 export { SuperDocCliError } from './runtime/errors.js';
+export { runTrackedComparisonReview } from './tracked-review-route.js';
+export type { TrackedReviewSession, TrackedComparisonReviewInput } from './tracked-review-route.js';
 export type { CollaborationAuth, DocOpenOptions, InvokeOptions, OperationSpec, OperationParamSpec, RuntimeInvoker, SuperDocClientOptions, } from './runtime/process.js';
 export type { DocOpenResult } from './generated/client.js';

package/dist/index.js

@@ -203,3 +203,4 @@ export { createAgentToolkit } from './tools.js';
 // run tier); hand the specs to `createAgentToolkit({ actions })`.
 export { defineAction } from './actions/define.js';
 export { SuperDocCliError } from './runtime/errors.js';
+export { runTrackedComparisonReview } from './tracked-review-route.js';

package/dist/runtime/sdk-version.generated.cjs

@@ -3,6 +3,6 @@
 // AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
 // Source of truth: package.json. Regenerated on every SDK build so the
 // SDK retains its own version identity when bundled into another package.
-const SDK_VERSION = '2.15.1-next.5';
+const SDK_VERSION = '2.16.0-next.1';
 
 exports.SDK_VERSION = SDK_VERSION;

package/dist/runtime/sdk-version.generated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.15.1-next.5";
+export declare const SDK_VERSION = "2.16.0-next.1";

package/dist/runtime/sdk-version.generated.js

@@ -1,4 +1,4 @@
 // AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
 // Source of truth: package.json. Regenerated on every SDK build so the
 // SDK retains its own version identity when bundled into another package.
-export const SDK_VERSION = '2.15.1-next.5';
+export const SDK_VERSION = '2.16.0-next.1';

package/dist/tracked-review-route.cjs

@@ -0,0 +1,75 @@
+'use strict';
+
+var promises = require('node:fs/promises');
+var os = require('node:os');
+var path = require('node:path');
+var errors = require('./runtime/errors.cjs');
+
+async function runTrackedComparisonReview(input) {
+    if (!(input.baseBytes instanceof Uint8Array) ||
+        !(input.targetBytes instanceof Uint8Array) ||
+        input.baseBytes.byteLength === 0 ||
+        input.targetBytes.byteLength === 0) {
+        throw new errors.SuperDocCliError('Tracked review requires the exact base and target DOCX bytes.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (!input.documentId ||
+        !input.actor ||
+        input.reviewSession.documentId !== input.documentId ||
+        input.reviewSession.actor !== input.actor) {
+        throw new errors.SuperDocCliError('The versioned review session is bound to another document or actor.', {
+            code: 'REVIEW_SESSION_MISMATCH',
+        });
+    }
+    const current = await input.currentReviewDocument(input.documentId);
+    if (current.version !== input.reviewSession.boundVersion ||
+        !Buffer.from(current.bytes).equals(Buffer.from(input.baseBytes))) {
+        throw new errors.SuperDocCliError('The exact base DOCX does not match the versioned review baseline.', {
+            code: 'REVIEW_BASE_MISMATCH',
+            details: {
+                documentId: input.documentId,
+                boundVersion: input.reviewSession.boundVersion,
+                currentVersion: current.version,
+            },
+        });
+    }
+    let stagingRoot;
+    let baseDocument;
+    let targetDocument;
+    let diff = null;
+    let comparisonError;
+    try {
+        stagingRoot = await promises.mkdtemp(path.join(os.tmpdir(), 'superdoc-tracked-review-'));
+        const basePath = path.join(stagingRoot, 'base.docx');
+        const targetPath = path.join(stagingRoot, 'target.docx');
+        await promises.writeFile(basePath, input.baseBytes, { flag: 'wx', mode: 0o600 });
+        await promises.writeFile(targetPath, input.targetBytes, { flag: 'wx', mode: 0o600 });
+        baseDocument = await input.client.open({ doc: basePath, runtime: 'v2' });
+        targetDocument = await input.client.open({ doc: targetPath, runtime: 'v2' });
+        const snapshot = await targetDocument.diff.capture({}, input.options);
+        diff = await baseDocument.diff.compare({ targetSnapshot: snapshot }, input.options);
+    }
+    catch (error) {
+        comparisonError = { message: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        const closes = await Promise.allSettled([targetDocument?.close(), baseDocument?.close()]);
+        if (stagingRoot)
+            await promises.rm(stagingRoot, { recursive: true, force: true });
+        const failed = closes.find((result) => result.status === 'rejected');
+        if (failed?.status === 'rejected') {
+            const message = failed.reason instanceof Error ? failed.reason.message : String(failed.reason);
+            comparisonError = {
+                message: comparisonError ? `${comparisonError.message}; SDK close: ${message}` : `SDK close: ${message}`,
+            };
+            diff = null;
+        }
+    }
+    const result = await input.reviewSession.applyTarget(input.targetBytes, 'tracked');
+    return comparisonError
+        ? { kind: 'versioned-review', diff: null, comparisonError, result }
+        : { kind: 'versioned-review', diff, result };
+}
+
+exports.runTrackedComparisonReview = runTrackedComparisonReview;

package/dist/tracked-review-route.d.ts

@@ -0,0 +1,39 @@
+import type { DocDiffCompareResult } from './generated/client.js';
+import type { InvokeOptions } from './runtime/process.js';
+import type { SuperDocClient } from './index.js';
+export interface TrackedReviewSession<TResult extends {
+    kind: string;
+}> {
+    readonly boundVersion: string;
+    readonly documentId: string;
+    readonly actor: string;
+    applyTarget(targetBytes: Uint8Array, changeMode: 'tracked'): Promise<TResult>;
+}
+export interface TrackedComparisonReviewInput<TResult extends {
+    kind: string;
+}> {
+    readonly client: Pick<SuperDocClient, 'open'>;
+    readonly baseBytes: Uint8Array;
+    readonly targetBytes: Uint8Array;
+    readonly documentId: string;
+    readonly actor: string;
+    readonly currentReviewDocument: (documentId: string) => Promise<{
+        version: string;
+        bytes: Uint8Array;
+    }>;
+    readonly reviewSession: TrackedReviewSession<TResult>;
+    readonly options?: InvokeOptions;
+}
+export interface TrackedComparisonReviewResult<TResult extends {
+    kind: string;
+}> {
+    readonly kind: 'versioned-review';
+    readonly diff: DocDiffCompareResult | null;
+    readonly comparisonError?: {
+        readonly message: string;
+    };
+    readonly result: TResult;
+}
+export declare function runTrackedComparisonReview<TResult extends {
+    kind: string;
+}>(input: TrackedComparisonReviewInput<TResult>): Promise<TrackedComparisonReviewResult<TResult>>;

package/dist/tracked-review-route.js

@@ -0,0 +1,70 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SuperDocCliError } from './runtime/errors.js';
+export async function runTrackedComparisonReview(input) {
+    if (!(input.baseBytes instanceof Uint8Array) ||
+        !(input.targetBytes instanceof Uint8Array) ||
+        input.baseBytes.byteLength === 0 ||
+        input.targetBytes.byteLength === 0) {
+        throw new SuperDocCliError('Tracked review requires the exact base and target DOCX bytes.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (!input.documentId ||
+        !input.actor ||
+        input.reviewSession.documentId !== input.documentId ||
+        input.reviewSession.actor !== input.actor) {
+        throw new SuperDocCliError('The versioned review session is bound to another document or actor.', {
+            code: 'REVIEW_SESSION_MISMATCH',
+        });
+    }
+    const current = await input.currentReviewDocument(input.documentId);
+    if (current.version !== input.reviewSession.boundVersion ||
+        !Buffer.from(current.bytes).equals(Buffer.from(input.baseBytes))) {
+        throw new SuperDocCliError('The exact base DOCX does not match the versioned review baseline.', {
+            code: 'REVIEW_BASE_MISMATCH',
+            details: {
+                documentId: input.documentId,
+                boundVersion: input.reviewSession.boundVersion,
+                currentVersion: current.version,
+            },
+        });
+    }
+    let stagingRoot;
+    let baseDocument;
+    let targetDocument;
+    let diff = null;
+    let comparisonError;
+    try {
+        stagingRoot = await mkdtemp(join(tmpdir(), 'superdoc-tracked-review-'));
+        const basePath = join(stagingRoot, 'base.docx');
+        const targetPath = join(stagingRoot, 'target.docx');
+        await writeFile(basePath, input.baseBytes, { flag: 'wx', mode: 0o600 });
+        await writeFile(targetPath, input.targetBytes, { flag: 'wx', mode: 0o600 });
+        baseDocument = await input.client.open({ doc: basePath, runtime: 'v2' });
+        targetDocument = await input.client.open({ doc: targetPath, runtime: 'v2' });
+        const snapshot = await targetDocument.diff.capture({}, input.options);
+        diff = await baseDocument.diff.compare({ targetSnapshot: snapshot }, input.options);
+    }
+    catch (error) {
+        comparisonError = { message: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        const closes = await Promise.allSettled([targetDocument?.close(), baseDocument?.close()]);
+        if (stagingRoot)
+            await rm(stagingRoot, { recursive: true, force: true });
+        const failed = closes.find((result) => result.status === 'rejected');
+        if (failed?.status === 'rejected') {
+            const message = failed.reason instanceof Error ? failed.reason.message : String(failed.reason);
+            comparisonError = {
+                message: comparisonError ? `${comparisonError.message}; SDK close: ${message}` : `SDK close: ${message}`,
+            };
+            diff = null;
+        }
+    }
+    const result = await input.reviewSession.applyTarget(input.targetBytes, 'tracked');
+    return comparisonError
+        ? { kind: 'versioned-review', diff: null, comparisonError, result }
+        : { kind: 'versioned-review', diff, result };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/sdk",
-  "version": "2.15.1-next.5",
+  "version": "2.16.0-next.1",
   "description": "Node SDK for SuperDoc, wrapping the SuperDoc CLI to read and edit .docx files from JavaScript and TypeScript.",
   "private": false,
   "license": "AGPL-3.0",
@@ -38,11 +38,11 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@superdoc/sdk-darwin-arm64": "2.15.1-next.5",
-    "@superdoc/sdk-darwin-x64": "2.15.1-next.5",
-    "@superdoc/sdk-linux-x64": "2.15.1-next.5",
-    "@superdoc/sdk-linux-arm64": "2.15.1-next.5",
-    "@superdoc/sdk-windows-x64": "2.15.1-next.5"
+    "@superdoc/sdk-darwin-arm64": "2.16.0-next.1",
+    "@superdoc/sdk-darwin-x64": "2.16.0-next.1",
+    "@superdoc/sdk-linux-x64": "2.16.0-next.1",
+    "@superdoc/sdk-linux-arm64": "2.16.0-next.1",
+    "@superdoc/sdk-windows-x64": "2.16.0-next.1"
   },
   "publishConfig": {
     "access": "public"
@@ -51,9 +51,9 @@
     "build": "rm -rf dist && node scripts/embed-version.mjs && node scripts/embed-prompts.mjs && node scripts/embed-tools.mjs && tsc && pnpm run typecheck:consumer && rollup -c rollup.cjs.config.mjs && rm -rf dist/prompts && mkdir -p dist/prompts && cp src/prompts/*.md dist/prompts/ && pnpm run audit:publish",
     "audit:publish": "node ../../../../scripts/audit-publish-artifact.mjs dist --label sdk-node-dist",
     "typecheck": "tsc --noEmit",
-    "typecheck:consumer": "tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext ../../../../tests/consumer-typecheck/src/sdk-per-open-collaboration-auth.mts ../../../../tests/consumer-typecheck/src/sdk-replace-file.mts ../../../../tests/consumer-typecheck/src/sdk-agent-evidence.mts ../../../../tests/consumer-typecheck/src/sdk-custom-actions.mts ../../../../tests/consumer-typecheck/src/sd4807-sdk-inspect.mts ../../../../tests/consumer-typecheck/src/sdk-tracked-only-policy.mts",
+    "typecheck:consumer": "tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext ../../../../tests/consumer-typecheck/src/sdk-per-open-collaboration-auth.mts ../../../../tests/consumer-typecheck/src/sdk-replace-file.mts ../../../../tests/consumer-typecheck/src/sdk-agent-evidence.mts ../../../../tests/consumer-typecheck/src/sdk-custom-actions.mts ../../../../tests/consumer-typecheck/src/sd4807-sdk-inspect.mts ../../../../tests/consumer-typecheck/src/sdk-tracked-only-policy.mts ../../../../tests/consumer-typecheck/src/sdk-tracked-review-route.mts",
     "test:agent-actions": "bun test src/__tests__/actions.test.ts src/__tests__/agent-runtime.test.ts src/__tests__/custom-actions.test.ts src/__tests__/textbox-snapshot.test.ts",
-    "test:document-host": "bun test src/runtime/__tests__/host-spawn-args.test.ts src/runtime/__tests__/document-rpc.test.ts src/__tests__/structured-document-rpc.e2e.test.ts src/__tests__/request-timeout-ms.e2e.test.ts src/__tests__/agent-evidence.e2e.test.ts src/__tests__/agent-apply.e2e.test.ts src/__tests__/find-text.e2e.test.ts src/__tests__/custom-actions.e2e.test.ts",
+    "test:document-host": "bun test src/runtime/__tests__/host-spawn-args.test.ts src/runtime/__tests__/document-rpc.test.ts src/__tests__/tracked-review-route.test.ts src/__tests__/structured-document-rpc.e2e.test.ts src/__tests__/request-timeout-ms.e2e.test.ts src/__tests__/agent-evidence.e2e.test.ts src/__tests__/agent-apply.e2e.test.ts src/__tests__/find-text.e2e.test.ts src/__tests__/custom-actions.e2e.test.ts",
     "smoke:product-action": "node scripts/product-action-smoke.mjs"
   }
 }

package/tools/tools-policy.json

@@ -43,5 +43,5 @@
       "mutates": true
     }
   ],
-  "contractHash": "a954798cd1c7ecb966430095bb4ade42585b2fc194228a951a499a7e72ffc1fd"
+  "contractHash": "1954c56d3b5bad5bc3d8760a9d205bfd5f0c1dd9357892333e5a356d36d58eb6"
 }