Methods

Reference for AIActions helpers and the high-level action surface. AIActions exposes two layers of functionality:

Wrapper methods on the AIActions instance (lifecycle & raw completions).
Action helpers under ai.action, which combine prompting, response parsing, and editor updates.

Instance methods

`waitUntilReady`

Resolves once provider/user set-up completes. Safe to call multiple times. Returns: Promise<void> Example:

await ai.waitUntilReady();
console.log('AI is ready!');

`getIsReady`

Returns true after initialisation. Returns: boolean Example:

if (ai.getIsReady()) {
  console.log('AI is ready!');
}

`getCompletion`

Single-shot completion that includes the serialized document context. Parameters:

string

required

The user prompt for the AI

CompletionOptions

Optional completion configuration

Returns: Promise<string> Example:

const response = await ai.getCompletion('Summarise the introduction', {
  temperature: 0.3,
  maxTokens: 600,
  stop: ['</summary>'],
  metadata: { documentId: 'contract-42' },
  providerOptions: { top_p: 0.9 },
});

`streamCompletion`

Streams a completion, firing hooks for each chunk and resolving with the full string. Parameters:

string

required

The user prompt for the AI

StreamOptions

Optional streaming configuration

Returns: Promise<string> Example:

const response = await ai.streamCompletion('Explain the GDPR section', {
  temperature: 0.7,
  maxTokens: 1000,
});

`getDocumentContext`

Retrieves the current document context for AI processing. Returns the plain text content of the active editor document. Returns: string Example:

const context = ai.getDocumentContext();
console.log('Document text:', context);

Action helpers

All actions return a Result object containing { success: boolean; results: FoundMatch[] }. Each FoundMatch includes the AI text (originalText, suggestedText) alongside the resolved document positions.

`find`

Finds the first occurrence and resolves its document positions. Parameters:

string

required

AI instruction describing what to find

Returns: Promise<Result> Example:

const { success, results } = await ai.action.find('GDPR clause');
if (success && results[0]?.positions?.length) {
  console.log('Found at', results[0].positions[0]);
}

`findAll`

Finds every occurrence matching the instruction. Parameters:

string

required

AI instruction describing what to find

Returns: Promise<Result>

`highlight`

Highlights the first match in the editor with the specified color. Parameters:

string

required

AI instruction describing what to highlight

string

default:"#6CA0DC"

Hex color code for the highlight

Returns: Promise<Result>

`replace`

Replaces a single match with AI-generated text. Parameters:

string

required

AI instruction describing what to replace and how

Returns: Promise<Result> Example:

await ai.action.replace('Replace "utilize" with "use"');

Note: Replacements are inserted as fresh text, so existing styling (bold, numbering, etc.) might not carry over. Re-apply any required formatting after the AI edit.

`replaceAll`

Replaces every match with AI-generated text. Parameters:

string

required

AI instruction describing what to replace and how

Returns: Promise<Result>

`literalReplace`

Performs literal text replacement when you have exact find and replace text. Prefer this over replaceAll when the user provides explicit text pairs (e.g., “change X to Y”, “replace A with B”). Automatically replaces all instances. Parameters:

string

required

Exact text to find

string

required

Exact replacement text

object

Optional replacement options

{
  caseSensitive?: boolean;      // Default: false
  trackChanges?: boolean;        // Default: false
}

Returns: Promise<Result> Example:

// Direct replacement
await ai.action.literalReplace('CompanyA', 'CompanyB');

// Case-sensitive replacement with tracked changes
await ai.action.literalReplace('utilize', 'use', {
  caseSensitive: true,
  trackChanges: true
});

`insertTrackedChange`

Inserts a tracked change attributed to the configured user (e.g., “RedlineBot”). Parameters:

string

required

AI instruction describing what change to track

Returns: Promise<Result> Example:

await ai.action.insertTrackedChange(
  'Rewrite the GDPR clause as bullet points'
);

Note: Tracked changes are also inserted as newly generated text, which can strip local formatting. Double-check for styling regressions after accepting or rejecting the change.

`insertTrackedChanges`

Inserts tracked changes for multiple matches. Parameters:

string

required

AI instruction describing what changes to track

Returns: Promise<Result>

`insertComment`

Inserts a comment annotating the first match. Parameters:

string

required

AI instruction describing what to comment on

Returns: Promise<Result>

`insertComments`

Inserts comments for every match. Parameters:

string

required

AI instruction describing what to comment on

Returns: Promise<Result>

`literalInsertComment`

Inserts a comment when you have exact find text and comment text. Prefer this over insertComments when the user provides explicit text to find and exact comment text to add. Automatically adds comments to all instances. Parameters:

string

required

Exact text to find

string

required

Exact comment text to add

object

Optional search options

{
  caseSensitive?: boolean;      // Default: false
}

Returns: Promise<Result> Example:

// Add comment to all instances
await ai.action.literalInsertComment('GDPR', 'Please review GDPR compliance');

// Case-sensitive search
await ai.action.literalInsertComment('CompanyA', 'Verify entity name', {
  caseSensitive: true
});

`summarize`

Returns AI-generated summary text in the suggestedText field. Streams results if the provider supports streaming. Parameters:

string

required

AI instruction describing what to summarize

Returns: Promise<Result> Example:

const { results } = await ai.action.summarize('Summarize the introduction');
console.log(results[0]?.suggestedText);

`insertContent`

Inserts AI-generated content into the document at the current cursor position, or appends it to the end if no cursor location is set. Content streams directly into the editor as it arrives from the provider. Parameters:

string

required

AI instruction describing what content to insert

object

Optional insertion options

{
  position?: 'before' | 'after' | 'replace';  // Default: 'after'
}

Returns: Promise<Result> Example:

// Insert after cursor
await ai.action.insertContent('Add a conclusion paragraph');

// Insert before cursor
await ai.action.insertContent('Add an introduction', { position: 'before' });

// Replace selection
await ai.action.insertContent('Rewrite this section', { position: 'replace' });

AI Planner

The AI Planner enables multi-step AI workflows where the AI can plan and execute a sequence of actions automatically.

`planner`

Access the planner instance via the planner property. The planner is lazily initialized on first access. Returns: AIPlanner Example:

const ai = new AIActions(superdoc, { user, provider });

// Access the planner
const result = await ai.planner.execute('Review the document and add comments to all legal terms');

`planner.execute`

Executes a user instruction by having the AI plan and execute a sequence of actions. Parameters:

string

required

Natural language instruction describing the multi-step task to perform

CompletionOptions

Optional completion configuration for the planning phase

Returns: Promise<AIPlannerExecutionResult> Result structure:

{
  success: boolean;
  executedTools: string[];        // Names of tools that were executed
  reasoning?: string;              // AI's reasoning for the plan
  response?: string;               // Final response from the AI
  plan?: AIPlan;                   // The execution plan that was created
  rawPlan?: string;                // Raw plan text from the AI
  error?: string;                  // Error message if execution failed
  warnings?: string[];             // Warnings encountered during execution
}

Example:

const result = await ai.planner.execute('Fix all grammar issues and add comments to unclear sentences');

if (result.success) {
  console.log('Executed tools:', result.executedTools);
  console.log('AI reasoning:', result.reasoning);
  console.log('Final response:', result.response);
} else {
  console.error('Planner failed:', result.error);
  console.log('Warnings:', result.warnings);
}

Use cases:

Complex multi-step document reviews
Automated document improvement workflows
Batch operations across multiple document sections
Conditional workflows based on document content

The planner automatically selects and sequences the appropriate tools based on your instruction. You don’t need to specify which tools to use - the AI decides the best approach.

Types

Result

{
  success: boolean;
  results: FoundMatch[];
}

Standard result structure returned by all AI actions.

FoundMatch

{
  originalText?: string;
  suggestedText?: string;
  positions?: DocumentPosition[];
}

Represents a match found by AI operations, with optional original text, suggested replacement, and document positions.

DocumentPosition

{
  from: number;
  to: number;
}

Position range in the document (character offsets).

CompletionOptions

{
  temperature?: number;
  maxTokens?: number;
  stop?: string[];
  model?: string;
  signal?: AbortSignal;         // Cancel request
  metadata?: Record<string, unknown>;  // Custom metadata
  providerOptions?: Record<string, unknown>;  // Provider-specific options
  documentId?: string;          // Document tracking
}

Configuration options for getCompletion() calls.

StreamOptions

{
  temperature?: number;
  maxTokens?: number;
  stop?: string[];
  model?: string;
  signal?: AbortSignal;         // Cancel request
  metadata?: Record<string, unknown>;  // Custom metadata
  providerOptions?: Record<string, unknown>;  // Provider-specific options
  documentId?: string;          // Document tracking
  stream?: boolean;             // Force streaming on/off
}

Configuration options for streamCompletion() calls. Extends CompletionOptions with a stream flag.

Tool utilities

The package exports utilities for working with AI tools and the tool registry:

`createToolRegistry`

Creates a tool registry with built-in and custom tools. Used internally by the planner but can be used for custom implementations. Parameters:

AIToolActions

required

AI actions service instance

AIToolDefinition[]

Optional array of custom tool definitions

Returns: Map<AIToolName, AIToolDefinition> Example:

import { createToolRegistry, AIActionsService } from '@superdoc-dev/ai';

const service = new AIActionsService(provider, editor, getContext, false);
const registry = createToolRegistry(service, [
  {
    name: 'customTool',
    description: 'My custom tool',
    handler: async ({ instruction, context }) => {
      // Custom implementation
      return { success: true };
    },
  },
]);

`getToolDescriptions`

Gets formatted descriptions of all tools in a registry for use in system prompts. Parameters:

Map<AIToolName, AIToolDefinition>

required

Tool registry map

Returns: string Example:

import { getToolDescriptions } from '@superdoc-dev/ai';

const descriptions = getToolDescriptions(registry);
// Returns: "- findAll: Find all occurrences...\n- highlight: Highlight content..."

`isValidTool`

Type guard to validate if a value is a valid tool definition. Parameters:

unknown

required

Value to validate

Returns: boolean Example:

import { isValidTool } from '@superdoc-dev/ai';

if (isValidTool(myTool)) {
  // TypeScript knows myTool is AIToolDefinition
  console.log(myTool.name, myTool.description);
}

Advanced exports

For advanced use cases, the package exports additional classes and utilities:

AIActionsService - Core service with direct access to action implementations
EditorAdapter - Editor interaction layer for custom integrations
createAIProvider(config) - Factory function for creating AI providers
Utilities: validateInput(), parseJSON(), removeMarkdownCodeBlocks(), generateId()

Getting Started

Authentication

Document Operations

System

Instance methods

`waitUntilReady`

`getIsReady`

`getCompletion`

`streamCompletion`

`getDocumentContext`

Action helpers

`find`

`findAll`

`highlight`

`replace`

`replaceAll`

`literalReplace`

`insertTrackedChange`

`insertTrackedChanges`

`insertComment`

`insertComments`

`literalInsertComment`

`summarize`

`insertContent`

AI Planner

`planner`

`planner.execute`

Types

Result

FoundMatch

DocumentPosition

CompletionOptions

StreamOptions

Tool utilities

`createToolRegistry`

`getToolDescriptions`

`isValidTool`

Advanced exports

​Instance methods

​waitUntilReady

​getIsReady

​getCompletion

​streamCompletion

​getDocumentContext

​Action helpers

​find

​findAll

​highlight

​replace

​replaceAll

​literalReplace

​insertTrackedChange

​insertTrackedChanges

​insertComment

​insertComments

​literalInsertComment

​summarize

​insertContent

​AI Planner

​planner

​planner.execute

​Types

​Result

​FoundMatch

​DocumentPosition

​CompletionOptions

​StreamOptions

​Tool utilities

​createToolRegistry

​getToolDescriptions

​isValidTool

​Advanced exports

Instance methods

`waitUntilReady`

`getIsReady`

`getCompletion`

`streamCompletion`

`getDocumentContext`

Action helpers

`find`

`findAll`

`highlight`

`replace`

`replaceAll`

`literalReplace`

`insertTrackedChange`

`insertTrackedChanges`

`insertComment`

`insertComments`

`literalInsertComment`

`summarize`

`insertContent`

AI Planner

`planner`

`planner.execute`

Types

Result

FoundMatch

DocumentPosition

CompletionOptions

StreamOptions

Tool utilities

`createToolRegistry`

`getToolDescriptions`

`isValidTool`

Advanced exports