documentation-hub 5.7.2

package/docs/api/API_README.md

@@ -0,0 +1,538 @@
+# Documentation Hub API Documentation
+
+Professional API documentation for the Documentation Hub DOCX processing system.
+
+## Overview
+
+This directory contains comprehensive API documentation for the Documentation Hub's document processing capabilities, powered by the custom-built docxmlater library.
+
+### What's Inside
+
+- **[API Reference](./API_REFERENCE.md)** - Complete method reference with examples for all 29 public methods
+- **[Type Definitions](./TYPE_DEFINITIONS.md)** - TypeScript type definitions guide with usage examples
+- **[TypeDoc Configuration](../../typedoc.json)** - Configuration for generating HTML documentation
+
+---
+
+## Quick Start
+
+### Installation
+
+The API is included in the Documentation Hub application. For external use:
+
+```bash
+npm install docxmlater
+```
+
+### Basic Usage
+
+```typescript
+import { DocXMLaterProcessor } from '@/services/document/DocXMLaterProcessor';
+
+// Create processor instance
+const processor = new DocXMLaterProcessor();
+
+// Load document
+const loadResult = await processor.loadFromFile('./document.docx');
+
+if (loadResult.success) {
+  const doc = loadResult.data;
+
+  // Modify hyperlinks
+  const urlMap = new Map([
+    ['http://old-site.com', 'https://new-site.com']
+  ]);
+  await processor.updateHyperlinkUrls(doc, urlMap);
+
+  // Save document
+  await processor.saveToFile(doc, './output.docx');
+
+  // Clean up
+  doc.dispose();
+}
+```
+
+---
+
+## API Categories
+
+### 📁 Document I/O (4 methods)
+
+Load, save, and convert documents between file paths and buffers.
+
+| Method | Description |
+|--------|-------------|
+| `loadFromFile()` | Load document from file path |
+| `loadFromBuffer()` | Load document from Buffer |
+| `saveToFile()` | Save document to file path |
+| `toBuffer()` | Convert document to Buffer |
+
+**Use Cases:** File operations, HTTP endpoints, database storage
+
+---
+
+### 🎨 Style Operations (2 methods)
+
+Create and apply custom styles to paragraphs.
+
+| Method | Description |
+|--------|-------------|
+| `createDocumentWithStyle()` | Create document with custom style |
+| `applyStyleToParagraphs()` | Apply style with pattern matching |
+
+**Use Cases:** Consistent branding, template generation, formatting automation
+
+---
+
+### 📊 Table Operations (3 methods)
+
+Create and format tables with borders, shading, and content.
+
+| Method | Description |
+|--------|-------------|
+| `createTable()` | Create formatted table |
+| `setCellShading()` | Set cell background color |
+| `addCellContent()` | Add formatted text to cells |
+
+**Use Cases:** Data presentation, reports, structured layouts
+
+---
+
+### 📝 Paragraph Formatting (2 methods)
+
+Control paragraph alignment, indentation, and spacing.
+
+| Method | Description |
+|--------|-------------|
+| `createParagraph()` | Create formatted paragraph |
+| `setIndentation()` | Set paragraph indentation |
+
+**Use Cases:** Document structure, text formatting, layout control
+
+---
+
+### 🔄 High-Level Operations (3 methods)
+
+Atomic operations for reading and modifying documents.
+
+| Method | Description |
+|--------|-------------|
+| `readDocument()` | Extract document structure |
+| `modifyDocument()` | Atomic load-modify-save |
+| `modifyDocumentBuffer()` | Modify from Buffer |
+
+**Use Cases:** Analysis, bulk processing, automated workflows
+
+---
+
+### 🔗 Hyperlink Operations (5 methods)
+
+Extract, update, and modify hyperlinks with comprehensive coverage.
+
+| Method | Description | Performance |
+|--------|-------------|-------------|
+| `extractHyperlinks()` | Extract all hyperlinks | 20-30% faster |
+| `updateHyperlinkUrls()` | Batch URL updates | 30-50% faster |
+| `modifyHyperlinks()` | Transform URLs | Optimized |
+| `appendContentIdToTheSourceUrls()` | Add #content to theSource | Batch API |
+| `replaceHyperlinkText()` | Replace display text | Pattern-based |
+
+**Use Cases:** Domain migration, URL sanitization, link management
+
+**Performance Benefits:**
+- 89% code reduction vs manual extraction
+- Comprehensive coverage (body, tables, headers, footers)
+- Defensive text sanitization prevents XML corruption
+
+---
+
+### 🔍 Search & Replace (2 methods)
+
+Find and replace text with regex support.
+
+| Method | Description |
+|--------|-------------|
+| `findText()` | Find text with options |
+| `replaceText()` | Replace text patterns |
+
+**Use Cases:** Template processing, content updates, data replacement
+
+---
+
+### 📈 Document Statistics (4 methods)
+
+Analyze document size, counts, and composition.
+
+| Method | Description |
+|--------|-------------|
+| `getWordCount()` | Count words |
+| `getCharacterCount()` | Count characters |
+| `estimateSize()` | Estimate file size |
+| `getSizeStats()` | Detailed statistics |
+
+**Use Cases:** Content analysis, size validation, reporting
+
+---
+
+### 🛠️ Utilities (4 methods)
+
+Helper functions for document creation and unit conversion.
+
+| Method | Description |
+|--------|-------------|
+| `createNewDocument()` | Create blank document |
+| `inchesToTwips()` | Convert inches to twips |
+| `pointsToTwips()` | Convert points to twips |
+| `twipsToPoints()` | Convert twips to points |
+
+**Conversion Reference:**
+- 1 inch = 1440 twips
+- 1 point = 20 twips
+- 72 points = 1 inch
+
+---
+
+## Common Patterns
+
+### Pattern 1: Load, Modify, Save
+
+```typescript
+const processor = new DocXMLaterProcessor();
+
+// Load document
+const loadResult = await processor.loadFromFile('input.docx');
+if (!loadResult.success) {
+  console.error(loadResult.error);
+  return;
+}
+
+const doc = loadResult.data;
+
+// Make modifications
+await processor.replaceText(doc, 'old', 'new');
+
+// Save document
+await processor.saveToFile(doc, 'output.docx');
+
+// Clean up
+doc.dispose();
+```
+
+---
+
+### Pattern 2: Batch Hyperlink Updates
+
+```typescript
+const processor = new DocXMLaterProcessor();
+
+await processor.modifyDocument('./document.docx', async (doc) => {
+  // Create URL mapping
+  const urlMap = new Map([
+    ['http://old-domain.com', 'https://new-domain.com'],
+    ['http://legacy.site.com', 'https://site.com']
+  ]);
+
+  // Batch update (30-50% faster)
+  const result = await processor.updateHyperlinkUrls(doc, urlMap);
+
+  console.log(`Updated ${result.data?.modifiedHyperlinks} hyperlinks`);
+});
+```
+
+---
+
+### Pattern 3: HTTP Document Processing
+
+```typescript
+app.post('/api/process', async (req, res) => {
+  const processor = new DocXMLaterProcessor();
+  const inputBuffer = req.file.buffer;
+
+  const result = await processor.modifyDocumentBuffer(inputBuffer, async (doc) => {
+    // Apply watermark
+    await processor.createParagraph(doc, 'CONFIDENTIAL', {
+      alignment: 'center',
+      color: '#FF0000',
+      fontSize: 48
+    });
+
+    // Replace placeholders
+    doc.replaceText('{{DATE}}', new Date().toLocaleDateString());
+  });
+
+  if (result.success) {
+    res.setHeader('Content-Type', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document');
+    res.send(result.data);
+  } else {
+    res.status(500).json({ error: result.error });
+  }
+});
+```
+
+---
+
+### Pattern 4: Template Processing
+
+```typescript
+const processor = new DocXMLaterProcessor();
+
+await processor.modifyDocument('./template.docx', async (doc) => {
+  // Replace all placeholders
+  const replacements = {
+    '{{COMPANY_NAME}}': 'Acme Corporation',
+    '{{YEAR}}': '2025',
+    '{{CLIENT_NAME}}': 'John Doe',
+    '{{PROJECT_NAME}}': 'Alpha Project'
+  };
+
+  for (const [find, replace] of Object.entries(replacements)) {
+    doc.replaceText(find, replace);
+  }
+
+  // Update all hyperlinks
+  const urlMap = new Map([
+    ['https://example.com', 'https://acme-corp.com']
+  ]);
+  doc.updateHyperlinkUrls(urlMap);
+});
+```
+
+---
+
+## Error Handling
+
+All methods return `ProcessorResult<T>` with consistent error handling:
+
+```typescript
+const result = await processor.loadFromFile('file.docx');
+
+// Check for errors
+if (!result.success) {
+  console.error('Error:', result.error);
+
+  // Check for warnings
+  if (result.warnings) {
+    result.warnings.forEach(w => console.warn('Warning:', w));
+  }
+
+  return;
+}
+
+// Safe to use result.data
+const doc = result.data;
+```
+
+---
+
+## Memory Management
+
+Always dispose documents to prevent memory leaks:
+
+```typescript
+// Manual disposal
+const result = await processor.loadFromFile('file.docx');
+if (result.success) {
+  const doc = result.data;
+  try {
+    // Work with document...
+  } finally {
+    doc.dispose(); // Always dispose
+  }
+}
+
+// Automatic disposal with high-level methods
+await processor.modifyDocument('./file.docx', async (doc) => {
+  // Document automatically disposed after this function
+  doc.replaceText('old', 'new');
+});
+```
+
+---
+
+## Performance Tips
+
+### 1. Use Batch Operations
+
+For hyperlink updates, prefer `updateHyperlinkUrls()` over `modifyHyperlinks()`:
+
+```typescript
+// ✅ FAST: Batch update (30-50% faster)
+const urlMap = new Map([
+  ['http://old.com', 'https://new.com']
+]);
+await processor.updateHyperlinkUrls(doc, urlMap);
+
+// ⚠️ SLOWER: Use only for complex transformations
+await processor.modifyHyperlinks(doc, (url) => {
+  // Custom transformation logic
+  return url.replace('http://', 'https://');
+});
+```
+
+### 2. Use extractHyperlinks() for Analysis
+
+The built-in extraction is 20-30% faster with comprehensive coverage:
+
+```typescript
+// ✅ FAST: Uses built-in API (89% code reduction)
+const hyperlinks = await processor.extractHyperlinks(doc);
+
+// Comprehensive coverage: body, tables, headers, footers
+console.log(`Found ${hyperlinks.length} hyperlinks`);
+```
+
+### 3. Use High-Level Methods for Atomic Operations
+
+```typescript
+// ✅ ATOMIC: Automatic cleanup and error handling
+await processor.modifyDocument('./file.docx', async (doc) => {
+  doc.replaceText('old', 'new');
+});
+
+// ⚠️ MANUAL: Must handle cleanup yourself
+const result = await processor.loadFromFile('./file.docx');
+try {
+  doc.replaceText('old', 'new');
+  await processor.saveToFile(doc, './file.docx');
+} finally {
+  doc.dispose();
+}
+```
+
+---
+
+## TypeScript Support
+
+Full TypeScript definitions with strict type checking:
+
+```typescript
+import {
+  DocXMLaterProcessor,
+  ProcessorResult,
+  TextStyle,
+  ParagraphStyle,
+  StyleApplication
+} from '@/services/document/DocXMLaterProcessor';
+
+// Type-safe style definition
+const style: TextStyle & ParagraphStyle = {
+  fontFamily: 'Arial',
+  fontSize: 12,
+  bold: true,
+  alignment: 'left',
+  indentLeft: 720 // TypeScript validates this is a number
+};
+
+// Type-safe result handling
+const result: ProcessorResult<Document> = await processor.loadFromFile('file.docx');
+
+if (result.success) {
+  // TypeScript knows result.data exists
+  const doc = result.data;
+}
+```
+
+---
+
+## Generating API Documentation
+
+### Using TypeDoc
+
+The project includes TypeDoc configuration for generating HTML documentation:
+
+```bash
+# Install TypeDoc (if not already installed)
+npm install --save-dev typedoc
+
+# Generate HTML documentation
+npm run docs:generate
+
+# Watch mode for development
+npm run docs:watch
+```
+
+Generated documentation will be in `docs/api/` directory.
+
+### TypeDoc Configuration
+
+Configuration is in `typedoc.json`:
+- Entry points: DocXMLaterProcessor, types, utilities
+- Output: `docs/api/`
+- Organized by groups (Document I/O, Style Operations, etc.)
+- Includes examples and cross-references
+
+---
+
+## API Coverage
+
+### Total Methods: 29
+
+| Category | Methods | Coverage |
+|----------|---------|----------|
+| Document I/O | 4 | 100% |
+| Style Operations | 2 | 100% |
+| Table Operations | 3 | 100% |
+| Paragraph Formatting | 2 | 100% |
+| High-Level Operations | 3 | 100% |
+| Hyperlink Operations | 5 | 100% |
+| Search & Replace | 2 | 100% |
+| Document Statistics | 4 | 100% |
+| Utilities | 4 | 100% |
+
+**JSDoc Coverage:** 100% (all methods documented)
+**Type Coverage:** 100% (all parameters and returns typed)
+**Examples:** 29+ code examples
+
+---
+
+## Related Documentation
+
+- **[API Reference](./API_REFERENCE.md)** - Detailed method reference
+- **[Type Definitions](./TYPE_DEFINITIONS.md)** - TypeScript types guide
+- **[docxmlater Library](https://github.com/ItMeDiaTech/docXMLater)** - Underlying DOCX library
+- **[Main README](../../README.md)** - Project overview
+
+
+---
+
+## Version History
+
+### Version 1.0.40 (2025-11-13)
+
+**Added:**
+- ✅ Comprehensive JSDoc comments for all 29 public methods
+- ✅ API Reference documentation with examples
+- ✅ TypeScript Type Definitions guide
+- ✅ TypeDoc configuration for HTML generation
+- ✅ Performance metrics and optimization notes
+
+**Documentation Coverage:**
+- 29 methods with detailed JSDoc
+- 50+ code examples across all documentation
+- Type definitions for all parameters and returns
+- Performance benchmarks for key operations
+
+---
+
+## Support
+
+### Documentation
+
+- **API Reference:** [./API_REFERENCE.md](./API_REFERENCE.md)
+- **Type Definitions:** [./TYPE_DEFINITIONS.md](./TYPE_DEFINITIONS.md)
+- **Examples:** See individual method documentation
+
+### Issues
+
+- **Project Issues:** [GitHub Issues](https://github.com/ItMeDiaTech/Documentation_Hub/issues)
+- **Library Issues:** [docxmlater Issues](https://github.com/ItMeDiaTech/docXMLater/issues)
+
+### Contact
+
+- **Repository:** https://github.com/ItMeDiaTech/Documentation_Hub
+- **Version:** 1.0.40
+- **Last Updated:** 2025-11-13
+
+---
+
+**Built with ❤️ by the Documentation Hub Team**