@eigenpal/docx-js-editor 0.0.1

package/dist/headless.d.cts

@@ -0,0 +1,361 @@
+export { A as AgentContextOptions, S as ContextSelectionOptions, C as CreateEmptyDocumentOptions, D as DocumentAgent, E as ExtendedSelectionContext, F as FormattedTextSegment, a as FormattingSummary, I as InsertHyperlinkOptions, b as InsertImageOptions, c as InsertTableOptions, d as InsertTextOptions, P as ProcessTemplateOptions, e as ProcessTemplateResult, f as SelectionContextOptions, T as TemplateError, g as blendColors, h as buildExtendedSelectionContext, i as buildSelectionContext, j as buildSelectionContextFromContext, k as colorsEqual, l as createAgent, m as createAgentFromDocument, n as createDocumentWithText, o as createEmptyDocument, p as createRgbColor, q as createTemplateProcessor, r as createThemeColor, s as darkenColor, D as default, t as emuToPixels, u as emuToTwips, v as executeCommand, w as executeCommands, x as formatPx, y as getAgentContext, z as getContrastingColor, B as getDocumentSummary, G as getMissingVariables, H as getSelectionFormattingSummary, J as getTemplateTags, K as halfPointsToPixels, L as isBlack, M as isWhite, N as lightenColor, O as parseColorString, Q as parseDocx, R as pixelsToEmu, U as pixelsToTwips, V as pointsToPixels, W as previewTemplate, X as processTemplate, Y as processTemplateAdvanced, Z as processTemplateAsBlob, _ as processTemplateDetailed, $ as resolveColor, a0 as resolveHighlightColor, a1 as resolveShadingColor, a2 as serializeDocumentBody, a3 as serializeDocx, a4 as serializeSectionProperties, a5 as twipsToEmu, a6 as twipsToPixels, a7 as validateTemplate } from './colorResolver-C-tITrbI.cjs';
+import { D as DocumentBody, e as Paragraph, T as TextFormatting, H as Hyperlink, R as Run, f as Table, g as Position, h as Document } from './types-BJXChtaM.cjs';
+export { A as AIAction, i as AIActionRequest, j as AgentCommand, k as AgentContext, l as AgentResponse, m as ApplyStyleCommand, n as ApplyVariablesCommand, B as BlockContent, b as CommandHandler, o as CommandResult, C as CorePlugin, p as DEFAULT_AI_ACTIONS, q as DeleteTextCommand, r as DocxPackage, E as Endnote, F as Footnote, s as FormatParagraphCommand, t as FormatTextCommand, I as Image, u as InsertHyperlinkCommand, v as InsertImageCommand, w as InsertTableCommand, x as InsertTextCommand, J as JsonSchema, L as ListLevel, y as LoadedDocument, d as McpSession, z as McpToolAnnotations, G as McpToolContent, K as McpToolContext, M as McpToolDefinition, N as McpToolHandler, O as McpToolResult, Q as NumberingDefinitions, S as ParagraphContext, U as ParagraphFormatting, V as ParagraphOutline, C as Plugin, W as PluginCommand, b as PluginCommandHandler, X as PluginEvent, c as PluginEventListener, P as PluginOptions, a as PluginRegistrationResult, Y as Range, Z as Relationship, _ as ReplaceTextCommand, $ as RunContent, a0 as SectionInfo, a1 as SectionProperties, a2 as SelectionContext, a3 as SetVariableCommand, a4 as Style, a5 as StyleDefinitions, a6 as StyleInfo, a7 as SuggestedAction, a8 as TableCell, a9 as TableRow, aa as TextContent, ab as Theme, M as ToolDefinition, N as ToolHandler, O as ToolResult, ac as ZodSchemaLike, ad as comparePositions, ae as createCollapsedRange, af as createCommand, ag as createRange, ah as getActionDescription, ai as getActionLabel, aj as isPositionInRange, ak as isZodSchema } from './types-BJXChtaM.cjs';
+export { P as PluginRegistry, c as createPluginRegistrar, p as pluginRegistry, r as registerPlugins } from './registry-DeeU0bQB.cjs';
+
+/**
+ * Shared Text Utilities for Agent Module
+ *
+ * Common text extraction and manipulation utilities used by
+ * context.ts, selectionContext.ts, and other agent-related code.
+ *
+ * Consolidates duplicated helper functions into a single location.
+ */
+
+/**
+ * Get plain text from a paragraph
+ */
+declare function getParagraphText(paragraph: Paragraph): string;
+/**
+ * Get plain text from a run
+ */
+declare function getRunText(run: Run): string;
+/**
+ * Get plain text from a hyperlink
+ */
+declare function getHyperlinkText(hyperlink: Hyperlink): string;
+/**
+ * Get plain text from a table
+ */
+declare function getTableText(table: Table): string;
+/**
+ * Get plain text from document body
+ */
+declare function getBodyText(body: DocumentBody): string;
+/**
+ * Count words in text
+ */
+declare function countWords(text: string): number;
+/**
+ * Count characters in text
+ */
+declare function countCharacters(text: string, includeSpaces?: boolean): number;
+/**
+ * Get word count from document body
+ */
+declare function getBodyWordCount(body: DocumentBody): number;
+/**
+ * Get character count from document body
+ */
+declare function getBodyCharacterCount(body: DocumentBody): number;
+/**
+ * Get text before a position
+ *
+ * @param paragraphs - Array of paragraphs
+ * @param position - Position to get text before
+ * @param maxChars - Maximum characters to return
+ * @returns Text before the position
+ */
+declare function getTextBefore(paragraphs: Paragraph[], position: Position, maxChars: number): string;
+/**
+ * Get text after a position
+ *
+ * @param paragraphs - Array of paragraphs
+ * @param position - Position to get text after
+ * @param maxChars - Maximum characters to return
+ * @returns Text after the position
+ */
+declare function getTextAfter(paragraphs: Paragraph[], position: Position, maxChars: number): string;
+/**
+ * Get formatting at a specific position in a paragraph
+ *
+ * @param paragraph - The paragraph to check
+ * @param offset - Character offset in the paragraph
+ * @returns Formatting at that position
+ */
+declare function getFormattingAtPosition(paragraph: Paragraph, offset: number): Partial<TextFormatting>;
+/**
+ * Check if position is within a hyperlink
+ *
+ * @param paragraph - The paragraph to check
+ * @param offset - Character offset in the paragraph
+ * @returns True if position is in a hyperlink
+ */
+declare function isPositionInHyperlink(paragraph: Paragraph, offset: number): boolean;
+/**
+ * Get hyperlink at position
+ *
+ * @param paragraph - The paragraph to check
+ * @param offset - Character offset in the paragraph
+ * @returns The hyperlink at that position, or undefined
+ */
+declare function getHyperlinkAtPosition(paragraph: Paragraph, offset: number): Hyperlink | undefined;
+/**
+ * Check if style ID represents a heading
+ *
+ * @param styleId - Style ID to check
+ * @returns True if it's a heading style
+ */
+declare function isHeadingStyle(styleId?: string): boolean;
+/**
+ * Parse heading level from style ID
+ *
+ * @param styleId - Style ID to parse
+ * @returns Heading level (1-9) or undefined
+ */
+declare function parseHeadingLevel(styleId?: string): number | undefined;
+/**
+ * Check if document body has images
+ *
+ * @param body - Document body to check
+ * @returns True if contains images
+ */
+declare function hasImages(body: DocumentBody): boolean;
+/**
+ * Check if document body has hyperlinks
+ *
+ * @param body - Document body to check
+ * @returns True if contains hyperlinks
+ */
+declare function hasHyperlinks(body: DocumentBody): boolean;
+/**
+ * Check if document body has tables
+ *
+ * @param body - Document body to check
+ * @returns True if contains tables
+ */
+declare function hasTables(body: DocumentBody): boolean;
+/**
+ * Get all paragraphs from document body
+ *
+ * @param body - Document body
+ * @returns Array of paragraphs
+ */
+declare function getParagraphs(body: DocumentBody): Paragraph[];
+/**
+ * Get paragraph at index from document body
+ *
+ * @param body - Document body
+ * @param index - Paragraph index (0-indexed)
+ * @returns Paragraph or undefined
+ */
+declare function getParagraphAtIndex(body: DocumentBody, index: number): Paragraph | undefined;
+/**
+ * Get block index for a paragraph index
+ *
+ * @param body - Document body
+ * @param paragraphIndex - Paragraph index
+ * @returns Block index or -1 if not found
+ */
+declare function getBlockIndexForParagraph(body: DocumentBody, paragraphIndex: number): number;
+
+/**
+ * DOCX Repacker - Repack modified document into valid DOCX
+ *
+ * Takes a Document with modified content and creates a new DOCX file
+ * by updating document.xml while preserving all other files from
+ * the original ZIP archive.
+ *
+ * This ensures round-trip fidelity:
+ * - styles.xml, theme1.xml, fontTable.xml remain untouched
+ * - Media files preserved
+ * - Relationships preserved
+ * - Only document.xml is updated with new content
+ *
+ * OOXML Package Structure:
+ * - [Content_Types].xml - Content type declarations
+ * - _rels/.rels - Package relationships
+ * - word/document.xml - Main document (modified)
+ * - word/styles.xml - Styles (preserved)
+ * - word/theme/theme1.xml - Theme (preserved)
+ * - word/numbering.xml - Numbering (preserved)
+ * - word/fontTable.xml - Font table (preserved)
+ * - word/settings.xml - Settings (preserved)
+ * - word/header*.xml - Headers (preserved)
+ * - word/footer*.xml - Footers (preserved)
+ * - word/footnotes.xml - Footnotes (preserved)
+ * - word/endnotes.xml - Endnotes (preserved)
+ * - word/media/* - Media files (preserved)
+ * - word/_rels/document.xml.rels - Document relationships (preserved)
+ * - docProps/* - Document properties (preserved)
+ */
+
+/**
+ * Options for repacking DOCX
+ */
+interface RepackOptions {
+    /** Compression level (0-9, default: 6) */
+    compressionLevel?: number;
+    /** Whether to update modification date in docProps/core.xml */
+    updateModifiedDate?: boolean;
+    /** Custom modifier name for lastModifiedBy */
+    modifiedBy?: string;
+}
+/**
+ * Repack a Document into a valid DOCX file
+ *
+ * @param doc - Document with modified content
+ * @param options - Optional repack options
+ * @returns Promise resolving to DOCX as ArrayBuffer
+ * @throws Error if document has no original buffer for round-trip
+ */
+declare function repackDocx(doc: Document, options?: RepackOptions): Promise<ArrayBuffer>;
+/**
+ * Create a new DOCX from a Document (without requiring original buffer)
+ *
+ * @param doc - Document to serialize
+ * @returns Promise resolving to DOCX as ArrayBuffer
+ */
+declare function createDocx(doc: Document): Promise<ArrayBuffer>;
+
+/**
+ * Variable Detector Utility
+ *
+ * Scans a DOCX document for template variables in the format {{variable_name}}.
+ * Returns a unique, sorted list of variable names found in the document.
+ */
+
+/**
+ * Result of variable detection
+ */
+interface VariableDetectionResult {
+    /** Unique variable names sorted alphabetically */
+    variables: string[];
+    /** Total count of variable occurrences */
+    totalOccurrences: number;
+    /** Variables by location */
+    byLocation: {
+        body: string[];
+        headers: string[];
+        footers: string[];
+        footnotes: string[];
+        endnotes: string[];
+        textBoxes: string[];
+    };
+    /** Variable occurrences with positions */
+    occurrences: VariableOccurrence[];
+}
+/**
+ * A single variable occurrence with location info
+ */
+interface VariableOccurrence {
+    /** Variable name (without braces) */
+    name: string;
+    /** Location type */
+    location: 'body' | 'header' | 'footer' | 'footnote' | 'endnote' | 'textBox';
+    /** Paragraph index within location */
+    paragraphIndex?: number;
+    /** Section index (for headers/footers) */
+    sectionIndex?: number;
+}
+/**
+ * Detect all template variables in a document
+ *
+ * @param doc - The parsed document
+ * @returns Array of unique variable names sorted alphabetically
+ */
+declare function detectVariables(doc: Document): string[];
+/**
+ * Detect variables with detailed information
+ *
+ * @param doc - The parsed document
+ * @returns Detailed detection result
+ */
+declare function detectVariablesDetailed(doc: Document): VariableDetectionResult;
+/**
+ * Detect variables in document body
+ */
+declare function detectVariablesInBody(body: DocumentBody): string[];
+/**
+ * Detect variables in a paragraph
+ */
+declare function detectVariablesInParagraph(paragraph: Paragraph): string[];
+/**
+ * Extract variable names from text
+ *
+ * @param text - The text to search
+ * @returns Array of variable names (without braces)
+ */
+declare function extractVariablesFromText(text: string): string[];
+/**
+ * Check if text contains template variables
+ */
+declare function hasTemplateVariables(text: string): boolean;
+/**
+ * Check if a variable name is valid
+ */
+declare function isValidVariableName(name: string): boolean;
+/**
+ * Sanitize a variable name
+ */
+declare function sanitizeVariableName(name: string): string;
+/**
+ * Format a variable name with braces
+ */
+declare function formatVariable(name: string): string;
+/**
+ * Parse a variable string to get the name
+ */
+declare function parseVariable(variable: string): string | null;
+/**
+ * Replace variables in text with values
+ *
+ * @param text - The text containing variables
+ * @param values - Map of variable name to replacement value
+ * @returns Text with variables replaced
+ */
+declare function replaceVariables(text: string, values: Record<string, string>): string;
+/**
+ * Replace all variables in text with a placeholder
+ *
+ * @param text - The text containing variables
+ * @param placeholder - Placeholder to use (default: empty string)
+ * @returns Text with variables replaced
+ */
+declare function removeVariables(text: string, placeholder?: string): string;
+/**
+ * Check if document has any template variables
+ */
+declare function documentHasVariables(doc: Document): boolean;
+
+/**
+ * Headless API Entry Point
+ *
+ * Provides document manipulation functionality without React/DOM dependencies.
+ * Suitable for Node.js scripts, CLI tools, and server-side processing.
+ *
+ * @example
+ * ```ts
+ * import { DocumentAgent, parseDocx, pluginRegistry } from '@eigenpal/docx-editor/headless';
+ * import { docxtemplaterPlugin } from '@eigenpal/docx-editor/core-plugins';
+ *
+ * // Register plugins
+ * pluginRegistry.register(docxtemplaterPlugin);
+ *
+ * // Load and manipulate document
+ * const buffer = fs.readFileSync('template.docx');
+ * const agent = await DocumentAgent.fromBuffer(buffer);
+ *
+ * // Get document info
+ * console.log('Word count:', agent.getWordCount());
+ * console.log('Variables:', agent.getVariables());
+ *
+ * // Edit document
+ * const newAgent = agent
+ *   .insertText({ paragraphIndex: 0, offset: 0 }, 'Hello ')
+ *   .applyStyle(0, 'Heading1');
+ *
+ * // Apply template variables
+ * const finalAgent = await newAgent.applyVariables({
+ *   customer_name: 'Jane Doe',
+ *   date: '2024-02-15',
+ * });
+ *
+ * // Export
+ * const output = await finalAgent.toBuffer();
+ * fs.writeFileSync('output.docx', Buffer.from(output));
+ * ```
+ */
+declare const VERSION = "0.1.0";
+
+export { Document, DocumentBody, Hyperlink, Paragraph, Position, Run, Table, TextFormatting, VERSION, type VariableDetectionResult, type VariableOccurrence, countCharacters, countWords, createDocx, detectVariables, detectVariablesDetailed, detectVariablesInBody, detectVariablesInParagraph, documentHasVariables, extractVariablesFromText, formatVariable, getBlockIndexForParagraph, getBodyCharacterCount, getBodyText, getBodyWordCount, getFormattingAtPosition, getHyperlinkAtPosition, getHyperlinkText, getParagraphAtIndex, getParagraphText, getParagraphs, getRunText, getTableText, getTextAfter, getTextBefore, hasHyperlinks, hasImages, hasTables, hasTemplateVariables, isHeadingStyle, isPositionInHyperlink, isValidVariableName, parseHeadingLevel, parseVariable, removeVariables, repackDocx, replaceVariables, sanitizeVariableName };