@superdoc/sdk 2.1.0 → 2.2.0

package/README.md

@@ -1,155 +1,32 @@
-# @superdoc-dev/sdk
+# @superdoc/sdk
 
-Programmatic SDK for deterministic DOCX operations through SuperDoc's Document API.
+Node.js SDK for reading and editing DOCX files with SuperDoc.
 
 ## Install
 
 ```bash
-npm install @superdoc-dev/sdk
+npm install @superdoc/sdk
 ```
 
-The package automatically installs a native CLI binary for your platform via optionalDependencies. Supported platforms:
+## Quick start
 
-| Platform | Package |
-|----------|---------|
-| macOS (Apple Silicon) | `@superdoc-dev/sdk-darwin-arm64` |
-| macOS (Intel) | `@superdoc-dev/sdk-darwin-x64` |
-| Linux (x64) | `@superdoc-dev/sdk-linux-x64` |
-| Linux (ARM64) | `@superdoc-dev/sdk-linux-arm64` |
-| Windows (x64) | `@superdoc-dev/sdk-windows-x64` |
+```js
+import { SuperDocClient } from '@superdoc/sdk';
 
-## Quick Start
-
-Both ESM and CommonJS are supported.
-
-```ts
-// ESM
-import { createSuperDocClient } from '@superdoc-dev/sdk';
-
-// CJS
-const { createSuperDocClient } = require('@superdoc-dev/sdk');
-```
-
-```ts
-import { createSuperDocClient } from '@superdoc-dev/sdk';
-
-const client = createSuperDocClient();
+const client = new SuperDocClient();
 await client.connect();
 
-const doc = await client.open({ doc: './contract.docx' });
-
-const info = await doc.info();
-console.log(info.counts);
+const document = await client.open({ doc: './contract.docx' });
+const markdown = await document.getMarkdown();
 
-const match = await doc.query.match({
-  select: { type: 'text', pattern: 'termination' },
-  require: 'first',
-});
+console.log(markdown);
 
-const target = match.items?.[0]?.target;
-if (target) {
-  await doc.replace({
-    target,
-    text: 'expiration',
-  });
-}
-
-await doc.save({ inPlace: true });
-await doc.close();
+await document.close();
 await client.dispose();
 ```
 
-## Encrypted Documents
-
-Pass `password` when opening a password-protected `.docx`:
-
-```ts
-const doc = await client.open({ doc: './secret.docx', password: 'mypassword' });
-```
-
-The password is forwarded only for the initial open and is not persisted. If the password is missing or wrong, the error includes a machine-readable code (`DOCX_PASSWORD_REQUIRED`, `DOCX_PASSWORD_INVALID`).
-
-## API
-
-### Client
-
-```ts
-import { SuperDocClient, createSuperDocClient } from '@superdoc-dev/sdk';
-
-const client = createSuperDocClient(options?);
-await client.connect();    // start the host process
-await client.dispose();    // shut down gracefully
-```
-
-Open documents from the client, then operate on the returned handle:
-
-```ts
-const doc = await client.open(params)
-await doc.find(params)
-await doc.insert(params)
-await doc.save(params)
-await doc.close(params)
-```
-
-### Collaboration sessions
-
-The SDK supports collaborative editing with `y-websocket`, `hocuspocus`, and `liveblocks` providers. Pass `collabUrl` for the websocket shorthand or a `collaboration` object for explicit provider config. See the [full collaboration docs](https://docs.superdoc.dev/document-engine/sdks#collaboration-sessions) for examples and all options.
-
-### Operations
-
-| Category | Operations |
-|----------|-----------|
-| **Query** | `find`, `query.match`, `getNode`, `getNodeById`, `info` |
-| **Mutation** | `insert`, `replace`, `delete` |
-| **Format** | `format.bold`, `format.italic`, `format.underline`, `format.strike` |
-| **Create** | `create.paragraph` |
-| **Lists** | `lists.list`, `lists.get`, `lists.insert`, `lists.create`, `lists.attach`, `lists.detach`, `lists.indent`, `lists.outdent`, `lists.join`, `lists.separate`, `lists.setLevel`, `lists.setValue`, `lists.continuePrevious`, `lists.setLevelRestart`, `lists.convertToText`, `lists.canJoin`, `lists.canContinuePrevious` |
-| **Comments** | `comments.create`, `comments.patch`, `comments.delete`, `comments.get`, `comments.list` |
-| **Track Changes** | `trackChanges.list`, `trackChanges.get`, `trackChanges.decide` |
-| **Lifecycle** | `client.open`, `doc.save`, `doc.close` |
-| **Client** | `client.describe`, `client.describeCommand` |
-
-### AI Tool Integration
-
-The SDK includes built-in support for exposing grouped intent tools as AI tool definitions:
-
-```ts
-import {
-  chooseTools,
-  dispatchSuperDocTool,
-  getToolCatalog,
-} from '@superdoc-dev/sdk';
-
-// Get the full grouped tool set for your AI provider
-const { tools, meta } = await chooseTools({
-  provider: 'openai',  // 'openai' | 'anthropic' | 'vercel' | 'generic'
-});
-
-// Optional: inspect the generated tool catalog
-const catalog = await getToolCatalog();
-
-// Dispatch a tool call from the AI model
-const doc = await client.open({ doc: './contract.docx' });
-const result = await dispatchSuperDocTool(doc, toolName, args);
-```
-
-The current catalog contains 9 grouped tools:
-`superdoc_get_content`, `superdoc_edit`, `superdoc_format`, `superdoc_create`, `superdoc_list`, `superdoc_comment`, `superdoc_track_changes`, `superdoc_search`, and `superdoc_mutations`.
-
-Multi-action tools use an `action` field to select the underlying operation. Single-action tools like `superdoc_search` do not require `action`.
-
-| Function | Description |
-|----------|-------------|
-| `chooseTools(input)` | Load grouped tool definitions for a provider |
-| `listTools(provider)` | List all tool definitions for a provider |
-| `dispatchSuperDocTool(doc, toolName, args)` | Execute a tool call against a bound document handle |
-| `getToolCatalog()` | Load the grouped tool catalog with metadata |
-| `getSystemPrompt()` | Read the bundled system prompt for intent tools |
-
-## Part of SuperDoc
-
-This SDK is part of [SuperDoc](https://github.com/superdoc/docx-editor) — open-source DOCX editing and tooling. Renders, edits, and automates .docx in the browser and on the server.
+See the [Node.js SDK guide](https://docs.superdoc.dev/agents/automation/node-sdk) for a complete workflow.
 
 ## License
 
-AGPL-3.0 · [Enterprise license available](https://superdoc.dev)
+AGPL-3.0. Commercial licenses are available from [SuperDoc](https://www.superdoc.dev).