New

docx-editor 1.x has shipped. Vue support, i18n, agents. Read the migration guide →

API Referencev1.0.2

@eigenpal/docx-editor-core/types/agentApi

Agent API Types

TypeScript interfaces for the agent API: - Position and Range types - Command types for document manipulation - Context types for AI agents

Functions(7)

Compare two positions Returns: -1 if a b, 0 if equal, 1 if a b

declare function comparePositions(a: Position, b: Position): -1 | 0 | 1;

Create a collapsed range (cursor) at a position

declare function createCollapsedRange(position: Position): Range;

Create a command with generated ID

declare function createCommand<T extends AgentCommand>(command: Omit<T, 'id'>): T;

Create a range from two positions

declare function createRange(start: Position, end: Position): Range;

Get action description

declare function getActionDescription(action: AIAction): string;

Get action label

declare function getActionLabel(action: AIAction): string;

Check if a position is within a range

declare function isPositionInRange(position: Position, range: Range): boolean;

Interfaces(28)

Content block in agent response

interface AgentContent
MemberTypeSummary
formatting?Partial<TextFormatting>Formatting
imageSrc?stringImage src (for image type)
paragraphFormatting?Partial<ParagraphFormatting>Paragraph formatting
tableData?string[][]Table data (for table type)
text?stringText content
type'text' | 'paragraph' | 'table' | 'image'Content type

Document context for AI agents

interface AgentContext
MemberTypeSummary
availableStylesStyleInfo[]Available styles
characterCountnumberTotal character count
hasImagesbooleanHas images
hasTablesbooleanHas tables
language?stringDocument language
outlineParagraphOutline[]Content outline (first N chars per paragraph)
paragraphCountnumberTotal paragraph count
sectionsSectionInfo[]Document sections info
variableCountnumberVariable count
variablesstring[]Detected template variables
wordCountnumberTotal word count (approximate)

Response from an agent action

interface AgentResponse
MemberTypeSummary
commands?AgentCommand[]Commands to execute
error?stringError message if failed
metadata?Record<string, unknown>Metadata about the response
newContent?AgentContent[]New formatted content
newText?stringNew text to insert (for rewrite/expand/etc.)
successbooleanSuccess status
warnings?string[]Warning messages

AI action request

interface AIActionRequest
MemberTypeSummary
actionAIActionAction type
contextSelectionContextSelection context
customPrompt?stringCustom prompt (for 'custom' action)
options?Record<string, unknown>Additional options
targetLanguage?stringTarget language (for 'translate' action)

Apply a named style to a paragraph

interface ApplyStyleCommand extends BaseCommand
MemberTypeSummary
paragraphIndexnumberParagraph index
styleIdstringStyle ID to apply
type'applyStyle'
interface

ApplyVariablesCommand

packages/core/src/types/agentApi.ts:284

Apply all template variables

interface ApplyVariablesCommand extends BaseCommand
MemberTypeSummary
type'applyVariables'
valuesRecord<string, string>Variable values

Base command interface

interface BaseCommand
MemberTypeSummary
id?stringUnique command ID (for undo tracking)
typestringCommand type

Delete text in a range

interface DeleteTextCommand extends BaseCommand
MemberTypeSummary
rangeRangeRange to delete
type'deleteText'
interface

FormatParagraphCommand

packages/core/src/types/agentApi.ts:164

Apply paragraph formatting

interface FormatParagraphCommand extends BaseCommand
MemberTypeSummary
formattingPartial<ParagraphFormatting>Formatting to apply
paragraphIndexnumberParagraph index
type'formatParagraph'

Apply formatting to a range

interface FormatTextCommand extends BaseCommand
MemberTypeSummary
formattingPartial<TextFormatting>Formatting to apply
rangeRangeRange to format
type'formatText'
interface

InsertHyperlinkCommand

packages/core/src/types/agentApi.ts:220

Insert a hyperlink at a range

interface InsertHyperlinkCommand extends BaseCommand
MemberTypeSummary
displayText?stringDisplay text (replaces range text if provided)
rangeRangeRange to make into a hyperlink
tooltip?stringTooltip
type'insertHyperlink'
urlstringURL of the hyperlink

Insert an image at a position

interface InsertImageCommand extends BaseCommand
MemberTypeSummary
alt?stringAlt text
height?numberImage height in pixels
positionPositionPosition to insert at
srcstringImage source (base64 or URL)
type'insertImage'
width?numberImage width in pixels
interface

InsertParagraphBreakCommand

packages/core/src/types/agentApi.ts:244

Insert a paragraph break

interface InsertParagraphBreakCommand extends BaseCommand
MemberTypeSummary
positionPositionPosition to break at
type'insertParagraphBreak'

Insert a table at a position

interface InsertTableCommand extends BaseCommand
MemberTypeSummary
columnsnumberNumber of columns
data?string[][]Optional table data
hasHeader?booleanOptional header row
positionPositionPosition to insert at
rowsnumberNumber of rows
type'insertTable'

Insert text at a position

interface InsertTextCommand extends BaseCommand
MemberTypeSummary
formatting?TextFormattingOptional formatting for the inserted text
positionPositionPosition to insert at
textstringText to insert
type'insertText'
interface

MergeParagraphsCommand

packages/core/src/types/agentApi.ts:253

Merge paragraphs

interface MergeParagraphsCommand extends BaseCommand
MemberTypeSummary
countnumberNumber of paragraphs to merge with
paragraphIndexnumberFirst paragraph index
type'mergeParagraphs'

Paragraph context for selection

interface ParagraphContext
MemberTypeSummary
fullTextstringFull paragraph text
indexnumberParagraph index
style?stringParagraph style
wordCountnumberWord count

Paragraph outline for context

interface ParagraphOutline
MemberTypeSummary
headingLevel?numberHeading level (1-9)
indexnumberParagraph index
isEmpty?booleanIs empty paragraph
isHeading?booleanIs heading
isListItem?booleanIs list item
previewstringFirst N characters
style?stringParagraph style
interface

Position_2

Position within a document

interface Position
MemberTypeSummary
contentIndex?numberOptional: Content index within paragraph (run, hyperlink, etc.)
offsetnumberOffset within the paragraph in characters
paragraphIndexnumberIndex of the paragraph (0-indexed)
sectionIndex?numberOptional: Section index
interface

Range_2

Range within a document

interface Range
MemberTypeSummary
collapsed?booleanWhether the range is collapsed (cursor position)
endPositionEnd position
startPositionStart position
interface

RemoveHyperlinkCommand

packages/core/src/types/agentApi.ts:235

Remove a hyperlink but keep the text

interface RemoveHyperlinkCommand extends BaseCommand
MemberTypeSummary
rangeRangeRange containing the hyperlink
type'removeHyperlink'

Replace text in a range

interface ReplaceTextCommand extends BaseCommand
MemberTypeSummary
formatting?TextFormattingOptional formatting for the new text
rangeRangeRange to replace
textstringReplacement text
type'replaceText'

Section information

interface SectionInfo
MemberTypeSummary
hasFooter?booleanHas footer
hasHeader?booleanHas header
indexnumberSection index
isLandscape?booleanIs landscape
pageSize?{ width: number; height: number; }Page size
paragraphCountnumberNumber of paragraphs

Context about the current selection

interface SelectionContext
MemberTypeSummary
formattingPartial<TextFormatting>Current formatting of selection
inTable?booleanIs selection within a table
paragraphParagraphContextParagraph containing selection
paragraphFormattingPartial<ParagraphFormatting>Current paragraph formatting
rangeRangeSelection range
selectedTextstringSelected text
suggestedActions?SuggestedAction[]Suggested actions based on selection
textAfterstringText after selection (context)
textBeforestringText before selection (context)

Set template variable value

interface SetVariableCommand extends BaseCommand
MemberTypeSummary
namestringVariable name
type'setVariable'
valuestringVariable value
interface

SplitParagraphCommand

packages/core/src/types/agentApi.ts:264

Split a paragraph

interface SplitParagraphCommand extends BaseCommand
MemberTypeSummary
positionPositionPosition to split at
type'splitParagraph'

Style information for context

interface StyleInfo
MemberTypeSummary
builtIn?booleanIs built-in style
idstringStyle ID
namestringDisplay name
type'paragraph' | 'character' | 'table'Style type

Suggested action for context menu

interface SuggestedAction
MemberTypeSummary
description?stringDescription
icon?stringIcon name
idstringAction ID
labelstringDisplay label
priority?numberPriority (higher = more prominent)

Type aliases(5)

Union of all command types

type AgentCommand = InsertTextCommand | ReplaceTextCommand | DeleteTextCommand | FormatTextCommand | FormatParagraphCommand | ApplyStyleCommand | InsertTableCommand | InsertImageCommand | InsertHyperlinkCommand | RemoveHyperlinkCommand | InsertParagraphBreakCommand | MergeParagraphsCommand | SplitParagraphCommand | SetVariableCommand | ApplyVariablesCommand;

AI action types for context menu

type AIAction = 'askAI' | 'rewrite' | 'expand' | 'summarize' | 'translate' | 'explain' | 'fixGrammar' | 'makeFormal' | 'makeCasual' | 'custom';

AI request handler function type

type AIRequestHandler = (request: AIActionRequest) => Promise<AgentResponse>;

Command handler function type

type CommandHandler<T extends AgentCommand = AgentCommand> = (command: T) => Promise<boolean>;

Get command type

type CommandType = AgentCommand['type'];

Variables(2)

const

_default

_default: {
    createCollapsedRange: typeof createCollapsedRange;
    createRange: typeof createRange;
    isPositionInRange: typeof isPositionInRange;
    comparePositions: typeof comparePositions;
    getActionLabel: typeof getActionLabel;
    getActionDescription: typeof getActionDescription;
    createCommand: typeof createCommand;
    DEFAULT_AI_ACTIONS: AIAction[];
}

Default AI actions for context menu

DEFAULT_AI_ACTIONS: AIAction[]