@superdoc-dev/sdk 1.0.0-alpha.4 → 1.0.0-alpha.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +116 -0
  2. package/package.json +6 -6
package/README.md ADDED
@@ -0,0 +1,116 @@
1
+ # @superdoc-dev/sdk
2
+
3
+ Programmatic SDK for deterministic DOCX operations through SuperDoc's Document API.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install @superdoc-dev/sdk
9
+ ```
10
+
11
+ The package automatically installs a native CLI binary for your platform via optionalDependencies. Supported platforms:
12
+
13
+ | Platform | Package |
14
+ |----------|---------|
15
+ | macOS (Apple Silicon) | `@superdoc-dev/sdk-darwin-arm64` |
16
+ | macOS (Intel) | `@superdoc-dev/sdk-darwin-x64` |
17
+ | Linux (x64) | `@superdoc-dev/sdk-linux-x64` |
18
+ | Linux (ARM64) | `@superdoc-dev/sdk-linux-arm64` |
19
+ | Windows (x64) | `@superdoc-dev/sdk-windows-x64` |
20
+
21
+ ## Quick Start
22
+
23
+ ```ts
24
+ import { createSuperDocClient } from '@superdoc-dev/sdk';
25
+
26
+ const client = createSuperDocClient();
27
+ await client.connect();
28
+
29
+ await client.doc.open({ doc: './contract.docx' });
30
+
31
+ const info = await client.doc.info();
32
+ console.log(info.counts);
33
+
34
+ const results = await client.doc.find({ query: { kind: 'text', pattern: 'termination' } });
35
+
36
+ await client.doc.replace({
37
+ target: results.context[0].textRanges[0],
38
+ text: 'expiration',
39
+ });
40
+
41
+ await client.doc.save({ inPlace: true });
42
+ await client.doc.close();
43
+ await client.dispose();
44
+ ```
45
+
46
+ ## API
47
+
48
+ ### Client
49
+
50
+ ```ts
51
+ import { SuperDocClient, createSuperDocClient } from '@superdoc-dev/sdk';
52
+
53
+ const client = createSuperDocClient(options?);
54
+ await client.connect(); // start the host process
55
+ await client.dispose(); // shut down gracefully
56
+ ```
57
+
58
+ All document operations are on `client.doc`:
59
+
60
+ ```ts
61
+ client.doc.open(params)
62
+ client.doc.find(params)
63
+ client.doc.insert(params)
64
+ // ... etc
65
+ ```
66
+
67
+ ### Operations
68
+
69
+ | Category | Operations |
70
+ |----------|-----------|
71
+ | **Query** | `find`, `getNode`, `getNodeById`, `info` |
72
+ | **Mutation** | `insert`, `replace`, `delete` |
73
+ | **Format** | `format.bold`, `format.italic`, `format.underline`, `format.strikethrough` |
74
+ | **Create** | `create.paragraph` |
75
+ | **Lists** | `lists.list`, `lists.get`, `lists.insert`, `lists.setType`, `lists.indent`, `lists.outdent`, `lists.restart`, `lists.exit` |
76
+ | **Comments** | `comments.add`, `comments.edit`, `comments.reply`, `comments.move`, `comments.resolve`, `comments.remove`, `comments.setInternal`, `comments.setActive`, `comments.goTo`, `comments.get`, `comments.list` |
77
+ | **Track Changes** | `trackChanges.list`, `trackChanges.get`, `trackChanges.accept`, `trackChanges.reject`, `trackChanges.acceptAll`, `trackChanges.rejectAll` |
78
+ | **Lifecycle** | `open`, `save`, `close` |
79
+ | **Session** | `session.list`, `session.save`, `session.close`, `session.setDefault` |
80
+ | **Introspection** | `status`, `describe`, `describeCommand` |
81
+
82
+ ### AI Tool Integration
83
+
84
+ The SDK includes built-in support for exposing document operations as AI tool definitions:
85
+
86
+ ```ts
87
+ import { chooseTools, dispatchSuperDocTool, inferDocumentFeatures } from '@superdoc-dev/sdk';
88
+
89
+ // Get tool definitions for your AI provider
90
+ const { tools, selected } = await chooseTools({
91
+ provider: 'openai', // 'openai' | 'anthropic' | 'vercel' | 'generic'
92
+ profile: 'intent', // human-friendly tool names
93
+ taskContext: { phase: 'mutate' },
94
+ documentFeatures: inferDocumentFeatures(await client.doc.info()),
95
+ });
96
+
97
+ // Dispatch a tool call from the AI model
98
+ const result = await dispatchSuperDocTool(client, toolName, args);
99
+ ```
100
+
101
+ | Function | Description |
102
+ |----------|-------------|
103
+ | `chooseTools(input)` | Select tools filtered by phase, capabilities, and budget |
104
+ | `listTools(provider, options?)` | List all tool definitions for a provider |
105
+ | `dispatchSuperDocTool(client, toolName, args)` | Execute a tool call against a client |
106
+ | `resolveToolOperation(toolName)` | Map a tool name to its operation ID |
107
+ | `getToolCatalog(options?)` | Load the full tool catalog |
108
+ | `inferDocumentFeatures(infoResult)` | Derive feature flags from `doc.info` output |
109
+
110
+ ## Part of SuperDoc
111
+
112
+ This SDK is part of [SuperDoc](https://github.com/superdoc-dev/superdoc) — an open source document editor bringing Microsoft Word to the web.
113
+
114
+ ## License
115
+
116
+ AGPL-3.0 · [Enterprise license available](https://superdoc.dev)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@superdoc-dev/sdk",
3
- "version": "1.0.0-alpha.4",
3
+ "version": "1.0.0-alpha.5",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -19,11 +19,11 @@
19
19
  "tools"
20
20
  ],
21
21
  "optionalDependencies": {
22
- "@superdoc-dev/sdk-darwin-arm64": "1.0.0-alpha.4",
23
- "@superdoc-dev/sdk-darwin-x64": "1.0.0-alpha.4",
24
- "@superdoc-dev/sdk-linux-arm64": "1.0.0-alpha.4",
25
- "@superdoc-dev/sdk-linux-x64": "1.0.0-alpha.4",
26
- "@superdoc-dev/sdk-windows-x64": "1.0.0-alpha.4"
22
+ "@superdoc-dev/sdk-darwin-arm64": "1.0.0-alpha.5",
23
+ "@superdoc-dev/sdk-darwin-x64": "1.0.0-alpha.5",
24
+ "@superdoc-dev/sdk-linux-arm64": "1.0.0-alpha.5",
25
+ "@superdoc-dev/sdk-linux-x64": "1.0.0-alpha.5",
26
+ "@superdoc-dev/sdk-windows-x64": "1.0.0-alpha.5"
27
27
  },
28
28
  "devDependencies": {
29
29
  "@types/bun": "^1.3.8",