@superdoc/sdk 2.26.0-next.9 → 2.27.0-next.4

package/README.md

@@ -1,6 +1,12 @@
 # @superdoc/sdk
 
-Node.js SDK for reading and editing DOCX files with SuperDoc.
+Node.js SDK for reading and editing DOCX files with SuperDoc, without a
+browser. Query, edit, comment, and review tracked changes from your server,
+or give an LLM SuperDoc tools with the agent toolkit. Edits write back to
+OOXML, so the output opens in Word. For an interactive editor, use
+[`superdoc`](https://www.npmjs.com/package/superdoc).
+
+[Documentation](https://docs.superdoc.dev/agents/automation/node-sdk) · [GitHub](https://github.com/superdoc/docx-editor)
 
 ## Install
 
@@ -8,23 +14,37 @@ Node.js SDK for reading and editing DOCX files with SuperDoc.
 npm install @superdoc/sdk
 ```
 
+The SDK embeds the SuperDoc runtime for your platform. You do not need a
+separate CLI installation.
+
 ## Quick start
 
 ```js
 import { SuperDocClient } from '@superdoc/sdk';
 
-const client = new SuperDocClient();
-await client.connect();
+const client = new SuperDocClient({ user: { name: 'Contract bot', email: 'bot@example.com' } });
 
-const document = await client.open({ doc: './contract.docx' });
-const markdown = await document.getMarkdown();
+try {
+  await client.connect();
+  const doc = await client.open({ doc: './contract.docx' });
 
-console.log(markdown);
+  try {
+    const receipt = await doc.trackChanges.decide({ decision: 'accept', target: { kind: 'all' } });
+    if (!receipt.success) throw new Error('Accepting tracked changes failed.');
 
-await document.close();
-await client.dispose();
+    await doc.save({ out: './contract.accepted.docx', force: true });
+  } finally {
+    await doc.close({ discard: true });
+  }
+} finally {
+  await client.dispose();
+}
 ```
 
+Save to a new path so the source stays unchanged. `force: true` lets the save
+replace an earlier output. `close({ discard: true })` then closes the session
+without writing over the source.
+
 ## Client lifetime
 
 One client owns one SuperDoc host process. `connect()` starts it once; every
@@ -37,6 +57,97 @@ room sync on every call. To cut round trips further, batch related edits with
 `document.mutations.apply()` or arbitrary operations with
 `document.plan.execute()`.
 
+## Common tasks
+
+### Read the document
+
+```js
+const markdown = await doc.getMarkdown();
+const text = await doc.getText({});
+```
+
+### Find and replace text as a tracked change
+
+`query.match` returns a complete target. Pass it to the mutation instead of
+building one yourself:
+
+```js
+const match = await doc.query.match({
+  select: { type: 'text', pattern: 'termination' },
+  require: 'first',
+});
+const item = match.items[0];
+if (!item || item.matchKind !== 'text') throw new Error('Text not found.');
+
+const operation = await doc.replace({
+  target: item.target,
+  text: 'cancellation',
+  changeMode: 'tracked',
+});
+const receipt = 'receipt' in operation ? operation.receipt : operation;
+if (!receipt.success) throw new Error('Creating the tracked change failed.');
+```
+
+### Give an LLM SuperDoc tools
+
+`createAgentToolkit` returns tool definitions, a matching system prompt, and a
+`dispatch` function, so the three cannot disagree:
+
+```js
+import { createAgentToolkit } from '@superdoc/sdk';
+
+const { tools, systemPrompt, dispatch } = await createAgentToolkit({
+  provider: 'openai', // 'openai' | 'anthropic' | 'vercel' | 'generic'
+  preset: 'core',
+  enforceChangeMode: 'tracked',
+});
+
+// For each tool call in an OpenAI Chat Completions reply:
+const result = await dispatch(doc, call.function.name, JSON.parse(call.function.arguments));
+```
+
+OpenAI sends tool arguments as a JSON string, so parse them before calling
+`dispatch`. Anthropic and Vercel pass an object already.
+
+`enforceChangeMode: 'tracked'` hides actions that cannot record a tracked
+change and records every other edit as tracked. See
+[build an agent](https://docs.superdoc.dev/agents/build/build-an-agent) for the
+full loop.
+
+## Common mistakes
+
+| Wrong | Right |
+| --- | --- |
+| Creating a client per operation | Create one per service and keep document handles open |
+| Passing OpenAI's JSON-string arguments to `dispatch` | `JSON.parse` them first. `dispatch` takes an object |
+| Omitting `preset` in `createAgentToolkit` | Pass `preset: 'core'`. Omitting it selects the older `legacy` tools |
+| Omitting `user` | Name the workflow so tracked changes show who proposed them |
+| Reusing a `query.match` target after an edit | Query again. Targets are bound to the revision that produced them |
+| Building targets from OOXML IDs such as `w14:paraId` | Use the address or target the API returns |
+| Saving over the source while testing | Save to a new path with `out` |
+| Retrying a failed receipt automatically | Inspect `executedOperations` first. Part of the edit may have committed |
+| Importing `superdoc` in Node.js | Use this package. `superdoc` is the browser editor |
+
+## Related packages
+
+- [`superdoc`](https://www.npmjs.com/package/superdoc): browser DOCX editor for reviewing the SDK's output.
+- [`@superdoc/mcp`](https://www.npmjs.com/package/@superdoc/mcp): the same tools for an existing MCP client, without writing an agent loop.
+- [`@superdoc/cli`](https://www.npmjs.com/package/@superdoc/cli): the same operations from a terminal or script.
+- [`superdoc-sdk`](https://pypi.org/project/superdoc-sdk/) on PyPI and [`superdoc-sdk`](https://crates.io/crates/superdoc-sdk) on crates.io: Python and Rust SDKs.
+
+## Documentation
+
+- [Node.js SDK guide](https://docs.superdoc.dev/agents/automation/node-sdk)
+- [Build an agent](https://docs.superdoc.dev/agents/build/build-an-agent)
+- [Document API mental model](https://docs.superdoc.dev/document-api/mental-model)
+- [Document comparison](https://docs.superdoc.dev/document-api/document-comparison)
+- [Agent safety](https://docs.superdoc.dev/agents/operate/safety)
+- [`llms.txt`](https://docs.superdoc.dev/llms.txt): machine-readable index of the documentation for coding agents.
+
+## Advanced
+
+### State directory
+
 For read-only hosts and containers, configure a writable state directory:
 
 ```js
@@ -73,6 +184,8 @@ the SDK parent can leave temporary state behind; the operating system or host
 operator must reclaim it. A new client gets a separate private root and does
 not sweep another client's state.
 
+### Authenticated collaboration rooms
+
 For token-authenticated Hocuspocus or y-websocket rooms, pass the credential as
 an option on that document's open request:
 
@@ -94,9 +207,41 @@ The credential applies only to that open request. It is not part of the
 collaboration profile or command-line arguments. Per-open token authentication
 is not supported for Liveblocks.
 
-See the [Node.js SDK guide](https://docs.superdoc.dev/agents/automation/node-sdk) for a complete workflow.
+### Attributed change records
 
-## Discover footer paragraphs
+Give each session a stable actor id with `userId`. Pass an application-signed
+claim, if you have one, as the `identityClaim` open option; like the
+collaboration token, it is sent only with that open request and is never
+written to arguments or state. SuperDoc records the claim but does not verify
+it.
+
+```js
+const document = await client.open(
+  { doc: './contract.docx', userId: 'user-42', collaboration },
+  { collaborationAuth: { type: 'token', token: userToken }, identityClaim: signedClaim },
+);
+```
+
+Every local and remote edit produces a change record. Read them with
+`document.changes.list({ after, waitMs })`; `waitMs` waits on the host without
+blocking other requests. To be told about new records, subscribe to host
+notifications:
+
+```js
+const notifications = client.subscribe();
+for await (const notification of notifications) {
+  if (notification.method === 'event.change') handle(notification.params.records);
+}
+```
+
+Each subscription holds up to `capacity` notifications (default 64). If you
+fall behind, the next read rejects with `NOTIFICATIONS_LAGGED`; resynchronize
+with `changes.list({ after })` from the last cursor you processed, then keep
+iterating. A host disconnect rejects one read with `HOST_DISCONNECTED`.
+`notifications.close()` unsubscribes and `client.dispose()` ends every
+subscription.
+
+### Discover footer paragraphs
 
 `blocks.list({ in: story })` lists top-level blocks. To discover paragraphs
 inside footer tables, including tables wrapped in block content controls, use
@@ -132,7 +277,47 @@ if (matches.total === 1) {
 }
 ```
 
-## Tracked comparison with direct style definitions
+### Inspecting textbox sections
+
+`superdoc_inspect` includes discovered text-bearing textbox stories in `textboxes` when
+block inspection is enabled. Each entry contains its explicit `story` locator,
+its story-local `total`, and normalized `blocks` with text, identities, and list
+markers. The top-level `blocks` array and its ordinals continue to refer to the
+body; textbox block ordinals belong to their containing story.
+
+The block offset, limit, text cap, and block filters also apply within each
+textbox. Count-only inspections and inspections excluding the blocks domain do
+not collect textbox text. Check `diagnostics` for incomplete story discovery or
+reads. To edit a discovered heading, use `query.match` with its story locator
+and pass the returned reference to `replace`; a textbox ordinal is not a body
+action selector.
+
+### Rejectable comparison styles
+
+For standalone V2 comparisons, use the tracked style policy when reviewers need to
+reject proposed styling as well as text:
+
+```js
+const diff = await older.diff.compare({ targetSnapshot, styleChangeMode: 'tracked' });
+const result = await older.diff.apply({ diff, changeMode: 'tracked', styleChangeMode: 'tracked' });
+await older.save({ out: 'comparison.docx' });
+```
+
+The saved file contains separate proposed style definitions and tracked references
+that Word can accept or reject. Rejection restores the original text and effective
+styling. Unused definitions may remain after a decision, and proposed styles retain
+their distinct names. Inspect `result.styleChanges` and `result.diagnostics`.
+
+This policy supports non-default paragraph and character styles in the main body,
+including inherited styles and outline-based TOCs. TOCs that select an affected style
+by identity (`\o`) or name (`\t`) are refused. Defaults, table styles, affected styles in other stories,
+combined table topology changes, pre-existing revisions, and definitions that activate already-used unresolved style
+references are refused. Numbering
+and settings retain their restrictions. Versioned suggest-only review sessions have
+a separate policy and refuse this option. Read eligibility before applying and
+handle apply-time refusals without saving a result.
+
+### Tracked comparison with direct style definitions
 
 For standalone V2 comparisons, `styleChangeMode: 'direct'` lets you explicitly
 carry the target style definitions while applying body edits as tracked changes:
@@ -147,12 +332,12 @@ await older.save({ out: 'comparison.docx' });
 Set the policy on both calls: compare reports eligibility for that policy;
 apply requires its own explicit consent. Style definitions are applied directly
 and remain if the body revisions are rejected in Word. A style-only comparison
-creates no body revisions. Without this option, changed style definitions still
+creates no body revisions. Without an explicit style policy, changed definitions still
 block tracked apply. Unsupported numbering, settings, and other package changes
 retain their existing restrictions. Suggest-only versioned review sessions
 refuse this direct-style option.
 
-## Tracked comparison with exact-file review
+### 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
@@ -216,7 +401,7 @@ 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
+### Agent execution evidence
 
 The core preset's `agent_apply`, `agent_verify`, and supported named actions
 collect the facts their targets and checks need. CLI-backed sessions
@@ -262,19 +447,7 @@ automatically replay the write.
 
 ## License
 
-AGPL-3.0. Commercial licenses are available from [SuperDoc](https://www.superdoc.dev).
-
-## Inspecting textbox sections
+AGPL-3.0. [Commercial licenses](https://www.superdoc.dev/#pricing) are
+available for proprietary deployments.
 
-`superdoc_inspect` includes discovered text-bearing textbox stories in `textboxes` when
-block inspection is enabled. Each entry contains its explicit `story` locator,
-its story-local `total`, and normalized `blocks` with text, identities, and list
-markers. The top-level `blocks` array and its ordinals continue to refer to the
-body; textbox block ordinals belong to their containing story.
-
-The block offset, limit, text cap, and block filters also apply within each
-textbox. Count-only inspections and inspections excluding the blocks domain do
-not collect textbox text. Check `diagnostics` for incomplete story discovery or
-reads. To edit a discovered heading, use `query.match` with its story locator
-and pass the returned reference to `replace`; a textbox ordinal is not a body
-action selector.
+The retained legacy comparison adapter refuses tracked style policy with `CAPABILITY_UNSUPPORTED`; use the current typed engine through the standalone SDK.

package/dist/agent/catalog.d.ts

@@ -388,10 +388,6 @@ export interface ResolveActionPolicyOptions {
     ignoreUnknownActions?: boolean;
 }
 export declare function resolveActionPolicy(options?: ListAgentToolsOptions, resolveOptions?: ResolveActionPolicyOptions): ResolvedActionPolicy;
-/** @deprecated Use {@link resolveActionPolicy}; kept for callers that only need the union. */
-export declare function validateExclusions(options?: ListAgentToolsOptions): {
-    excludedActions: Set<string>;
-};
 /**
  * Tools advertised to the LLM. Only PUBLIC_AGENT_TOOL_NAMES (currently
  * superdoc_inspect + superdoc_perform_action) are returned; the remaining

package/dist/agent/catalog.js

@@ -614,10 +614,6 @@ export function resolveActionPolicy(options, resolveOptions) {
         allowDirectActions,
     };
 }
-/** @deprecated Use {@link resolveActionPolicy}; kept for callers that only need the union. */
-export function validateExclusions(options) {
-    return { excludedActions: resolveActionPolicy(options).excludedActions };
-}
 /**
  * Tools advertised to the LLM. Only PUBLIC_AGENT_TOOL_NAMES (currently
  * superdoc_inspect + superdoc_perform_action) are returned; the remaining

package/dist/generated/client.cjs

@@ -2,7 +2,6 @@
 
 var contract = require('./contract.cjs');
 
-/* eslint-disable */
 // Auto-generated by packages/sdk/codegen/src/generate-node.mjs
 // ---------------------------------------------------------------------------
 // Raw API (all operations — internal use only)
@@ -303,6 +302,13 @@ function createDocApi(runtime) {
             undo: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.history.undo"], params, options),
             redo: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.history.redo"], params, options),
         },
+        changes: {
+            list: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.changes.list"], params, options),
+            get: (params, options) => runtime.invoke(contract.CONTRACT.operations["doc.changes.get"], params, options),
+            resolve: (params, options) => runtime.invoke(contract.CONTRACT.operations["doc.changes.resolve"], params, options),
+            actors: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.changes.actors"], params, options),
+            snapshot: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.changes.snapshot"], params, options),
+        },
         images: {
             list: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.images.list"], params, options),
             get: (params, options) => runtime.invoke(contract.CONTRACT.operations["doc.images.get"], params, options),
@@ -891,6 +897,13 @@ function createBoundDocApi(runtime) {
             undo: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.history.undo"], params, options),
             redo: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.history.redo"], params, options),
         },
+        changes: {
+            list: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.changes.list"], params, options),
+            get: (params, options) => runtime.invoke(contract.CONTRACT.operations["doc.changes.get"], params, options),
+            resolve: (params, options) => runtime.invoke(contract.CONTRACT.operations["doc.changes.resolve"], params, options),
+            actors: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.changes.actors"], params, options),
+            snapshot: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.changes.snapshot"], params, options),
+        },
         images: {
             list: (params = {}, options) => runtime.invoke(contract.CONTRACT.operations["doc.images.list"], params, options),
             get: (params, options) => runtime.invoke(contract.CONTRACT.operations["doc.images.get"], params, options),