@superdoc-dev/sdk

Programmatic SDK for deterministic DOCX operations through SuperDoc's Document API.

Install

npm install @superdoc-dev/sdk

The package automatically installs a native CLI binary for your platform via optionalDependencies. Supported platforms:

| 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 |

Quick Start

Both ESM and CommonJS are supported.

// ESM
import { createSuperDocClient } from '@superdoc-dev/sdk';

// CJS
const { createSuperDocClient } = require('@superdoc-dev/sdk');

import { createSuperDocClient } from '@superdoc-dev/sdk';

const client = createSuperDocClient();
await client.connect();

const doc = await client.open({ doc: './contract.docx' });

const info = await doc.info();
console.log(info.counts);

const match = await doc.query.match({
  select: { type: 'text', pattern: 'termination' },
  require: 'first',
});

const target = match.items?.[0]?.target;
if (target) {
  await doc.replace({
    target,
    text: 'expiration',
  });
}

await doc.save({ inPlace: true });
await doc.close();
await client.dispose();

Encrypted Documents

Pass password when opening a password-protected .docx:

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

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:

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 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:

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 — open-source DOCX editing and tooling. Renders, edits, and automates .docx in the browser and on the server.

License

AGPL-3.0 · Enterprise license available