@dragon708/docmind-node 1.13.7 → 1.14.0

package/README.md

@@ -0,0 +1,206 @@
+# `@dragon708/docmind-node`
+
+**Cliente oficial de DocMind para Node.js** (API pública de alto nivel): un solo módulo para `analyzeFile`, extracción de texto/metadata/HTML, OCR, **documento estructurado**, **Markdown híbrido** (DOCX, PDF, HTML, CSV, Excel mediante el motor de conversión a Markdown integrado en servidor), texto para LLM y trozos con Markdown. Resuelve rutas de disco y `file:` URLs con `fs`.
+
+**Requisito:** Node **≥ 18** (según `package.json` del paquete).
+
+---
+
+## Instalación
+
+```bash
+npm install @dragon708/docmind-node
+```
+
+Arrastra transitivamente `@dragon708/docmind-pdf`, `@dragon708/docmind-docx`, `@dragon708/docmind-ocr`, `@dragon708/docmind-markdown`, `@dragon708/docmind-shared` y dependencias pesadas (pdfjs, Tesseract, runtime de conversión a Markdown empaquetado con `docmind-markdown`, etc.). No es adecuado para bundlers “browser-only” sin sustituir por `@dragon708/docmind-browser`.
+
+---
+
+## Qué cubre este runtime
+
+| Formato | Texto / HTML | Structured | Markdown (`extractMarkdown`) | Notas |
+|---------|----------------|------------|------------------------------|--------|
+| PDF | Sí (nativo + OCR opcional) | Sí | Sí (conversión a Markdown en Node) | `pdf.ocr`, `ocrStrategy`, `maxPages` |
+| DOCX | Sí (Mammoth) | Sí | Sí (Mammoth → Turndown) | `docx.include` (headings, tables, blocks, …) |
+| Imagen raster | OCR (Tesseract) | Sí | Vía structured fallback típico | PNG/JPEG/WebP; TIFF multipage |
+| Texto UTF-8 | Sí | Normalización | Según contenido | — |
+| HTML / CSV / Excel (bytes) | — | — | Sí | Rutas binarias en `@dragon708/docmind-markdown` (solo Node) |
+
+---
+
+## Uso rápido
+
+### Analizar un fichero desde disco
+
+```ts
+import { readFile } from "node:fs/promises";
+import { analyzeFile } from "@dragon708/docmind-node";
+
+const data = await readFile("informe.pdf");
+const result = await analyzeFile({
+  data,
+  name: "informe.pdf",
+  mimeType: "application/pdf",
+});
+// result.text, result.html, result.warnings, result.fileKind, …
+```
+
+### Entrada unificada (`NodeAnalyzeInput`)
+
+```ts
+import { readFileToInput, analyzeFile } from "@dragon708/docmind-node";
+
+const input = await readFileToInput("/ruta/al/archivo.docx");
+const result = await analyzeFile(input);
+```
+
+### Documento estructurado
+
+```ts
+import { extractStructuredData } from "@dragon708/docmind-node";
+
+const structured = await extractStructuredData({
+  data: buffer,
+  name: "doc.docx",
+});
+// structured.blocks, structured.tables, structured.pages, …
+```
+
+### Markdown híbrido (PDF, DOCX, HTML, CSV, XLSX…)
+
+```ts
+import { extractMarkdown } from "@dragon708/docmind-node";
+
+const md = await extractMarkdown(
+  { data: buffer, name: "libro.xlsx" },
+  {
+    onMarkdownExtract: (info) => {
+      console.log(info.strategy, info.warnings, info.routing);
+    },
+    markdownSpreadsheet: { maxRowsPerSheet: 500 },
+  },
+);
+// md es string (el cliente Node devuelve el Markdown listo; ver tipos)
+```
+
+> La firma exacta y el tipo de retorno siguen los tipos exportados (`NodeExtractMarkdownOptions`, etc.); consulta el IDE o `dist/*.d.ts`.
+
+### Texto para LLM y trozos
+
+```ts
+import { extractLlmContent, extractStructuredChunks } from "@dragon708/docmind-node";
+
+const llmText = await extractLlmContent(input, { /* llm render options */ });
+const chunks = await extractStructuredChunks(input, { chunks: { includeMarkdown: true } });
+```
+
+### Introspección
+
+```ts
+import { getCapabilities, explainAnalysisPlan } from "@dragon708/docmind-node";
+
+const caps = await getCapabilities({ /* … */ });
+const plan = await explainAnalysisPlan({ /* … */ });
+```
+
+### Clasificación de tipo de fichero
+
+```ts
+import { detectFileKind } from "@dragon708/docmind-node";
+
+// Re-export de @dragon708/docmind-shared; útil tras resolver rutas
+```
+
+### Conversores directos HTML / CSV / Excel (Node)
+
+```ts
+import {
+  convertHtmlToMarkdown,
+  convertCsvToMarkdown,
+  convertSpreadsheetToMarkdown,
+  detectBinaryFormat,
+} from "@dragon708/docmind-node";
+```
+
+### Imágenes incrustadas en DOCX (Node)
+
+```ts
+import {
+  extractImagesFromDocx,
+  convertDocxImagesForWeb,
+  docxImageToDataUri,
+} from "@dragon708/docmind-node";
+```
+
+### Extractores estructurados por formato
+
+```ts
+import {
+  extractStructuredDataFromPdf,
+  extractStructuredDataFromDocx,
+  extractStructuredDataFromImage,
+} from "@dragon708/docmind-node";
+```
+
+---
+
+## Opciones destacadas (`NodeAnalyzeOptions`)
+
+Resumen; el detalle está en `nodeAnalyzeOptions.ts` y JSDoc:
+
+- **`ocr`**: política PDF / metadatos de pipeline (`off` | `auto` | `force`).
+- **`language`**: idiomas OCR (BCP-47 / Tesseract).
+- **`maxPages`**, **`ocrStrategy`**: PDF (estrategia del pipeline raster).
+- **`docx`**: `include` (`headings`, `tables`, `blocks`, `pagesApprox`, `embeddedImages`, …).
+- **`signal`**: `AbortSignal`.
+- **`structuredOutput` / `output`**: opt-in de `structured` en `analyzeFile` (ver `analyzeFileRequestsStructured` en shared).
+
+Para **Markdown / LLM / chunks**:
+
+- **`NodeExtractMarkdownOptions`**: `markdown`, `markdownDocx`, `markdownPdf`, `markdownHtml`, `markdownCsv`, `markdownSpreadsheet`, `onMarkdownExtract`, structured routing, etc.
+- **`NodeExtractLlmContentOptions`**, **`NodeExtractStructuredChunksOptions`**.
+
+---
+
+## Helpers de entrada
+
+- **`readFileToInput`**, **`bufferToInput`**, **`resolveNodeAnalyzeInput`**: convierten path / buffer / URL en `NodeAnalyzeInput`.
+
+---
+
+## Constantes y capacidades
+
+- **`DOCX_EMBEDDED_IMAGE_CAPABILITIES`**, **`DOCX_STRUCTURE_CAPABILITIES`**, **`docxIncludeRequested`**: matrices de capacidades para informes.
+
+---
+
+## Errores y advertencias
+
+Esta API propaga **`DocMindError`** (`@dragon708/docmind-shared`) cuando el input es inválido o el formato no está soportado. Los PDF/DOCX corruptos pueden lanzar o devolver payloads con `warnings` según la ruta.
+
+---
+
+## Relación con otros paquetes
+
+| Paquete | Uso desde Node |
+|---------|----------------|
+| `@dragon708/docmind-shared` | Tipos y `detectFileKind` |
+| `@dragon708/docmind-markdown` | `extractMarkdown`, render LLM, chunks, conversión binaria a Markdown en Node |
+| `@dragon708/docmind-pdf` | PDF nativo, PDF.js, formularios, pipeline OCR |
+| `@dragon708/docmind-docx` | Mammoth + extractores OOXML |
+| `@dragon708/docmind-ocr` | Tesseract, TIFF, preprocesado |
+
+En **navegador** usa `@dragon708/docmind-browser` (sin PDF completo ni conversión binaria pesada a Markdown en el cliente).
+
+---
+
+## Seguridad
+
+- No ejecutes `convertToHtml` / Markdown sobre **documentos no confiables** sin sanitizar antes de insertar en DOM.
+- PDF y DOCX pueden contener recursos remotos según opciones de conversión.
+
+---
+
+## Licencia
+
+MIT (monorepo DocMind).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dragon708/docmind-node",
-  "version": "1.13.7",
+  "version": "1.14.0",
   "description": "Official DocMind Node facade: analyzeFile, intent APIs, PDF/DOCX/OCR, and fs helpers.",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,11 +32,11 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@dragon708/docmind-docx": "^1.8.0",
-    "@dragon708/docmind-markdown": "^1.2.10",
-    "@dragon708/docmind-ocr": "^1.1.4",
-    "@dragon708/docmind-pdf": "^2.2.0",
-    "@dragon708/docmind-shared": "^1.2.0"
+    "@dragon708/docmind-docx": "^1.9.0",
+    "@dragon708/docmind-markdown": "^1.3.0",
+    "@dragon708/docmind-ocr": "^1.2.0",
+    "@dragon708/docmind-pdf": "^2.3.0",
+    "@dragon708/docmind-shared": "^1.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.37",