@dragon708/docmind-shared

Tipos, contratos y utilidades compartidas entre @dragon708/docmind-browser y @dragon708/docmind-node. No incluye parsers pesados de PDF ni motores de conversión a Markdown: solo clasificación de ficheros, normalización de bytes, errores comunes y el modelo de documento estructurado (StructuredDocumentResult) que usan Markdown, LLM y chunks.

Instalación

npm install @dragon708/docmind-shared

No arrastra Tesseract ni pdfjs: es seguro como dependencia en bundles ligeros o en librerías que solo necesitan tipos y detectFileKind.

Ámbito del paquete

| Incluye | No incluye | |--------|------------| | FileKind, detección por extensión/MIME/sniff | Lectura de PDF/DOCX | | Normalización Buffer / Uint8Array / Blob / File | OCR ni raster | | DocMindError, isDocMindError, validación de entrada mínima | Implementación de analyzeFile (vive en browser/node) | | Contratos AnalysisResult, opciones de intents, capabilities/plan (tipos) | Ejecución real de planes | | StructuredDocumentResult y normalizadores | Render a Markdown (eso es @dragon708/docmind-markdown) |

Uso rápido

Clasificar un fichero

import { detectFileKind } from "@dragon708/docmind-shared";

const kind = await detectFileKind({
  data: uint8Array,
  name: "informe.pdf",
  mimeType: "application/pdf",
});
// kind.kind → "pdf" | "docx" | "image" | "text" | …

Normalizar entrada binaria

import { toUint8Array, getFileName, getMimeType } from "@dragon708/docmind-shared";

const bytes = await toUint8Array(fileOrBlob);
const name = getFileName(input);
const mime = getMimeType(input);

Errores y validación

import {
  isDocMindError,
  DocMindError,
  assertValidAnalyzeFileInput,
} from "@dragon708/docmind-shared";

try {
  assertValidAnalyzeFileInput(payload);
} catch (e) {
  if (isDocMindError(e)) {
    console.error(e.code, e.message);
  }
}

Documento estructurado

import {
  normalizeToStructuredResult,
  isStructuredDocumentResult,
  type StructuredDocumentResult,
} from "@dragon708/docmind-shared";

const doc: StructuredDocumentResult = normalizeToStructuredResult(partial);
if (isStructuredDocumentResult(unknown)) {
  // …
}

Texto UTF-8

import { analyzeText } from "@dragon708/docmind-shared";

const result = await analyzeText({ data: textEncoder.encode("Hola") });

Resultado “no implementado”

import { notImplementedResult } from "@dragon708/docmind-shared";

// Patrón interno para rutas no soportadas en un runtime concreto

Structured opcional en analyzeFile

import { analyzeFileRequestsStructured } from "@dragon708/docmind-shared";

if (analyzeFileRequestsStructured(options)) {
  // El cliente pidió `structured` en la respuesta
}

Tipos y contratos principales

Clasificación y entrada

• FileKind: resultado abstracto del tipo de fichero.
• DetectFileKindInput: data, name, mimeType opcionales.
• NamedInput / FileLikeInput / BinaryInput: formas de entrada que aceptan los clientes browser/node.
• sniffBinaryFileKind: heurística sobre bytes (uso avanzado).

Análisis (contratos públicos compartidos)

Re-exportados para que browser/node alineen firmas:

• AnalysisResult, GenericAnalysisResult, variantes por analizador (PdfAnalysisCoreResult, DocxAnalysisCoreResult, …).
• AnalyzeFileOptions, ExtractTextOptions, ConvertToHtmlOptions, RunOcrOptions, ExtractMetadataOptions.
• GetCapabilitiesOptions / GetCapabilitiesResult, ExplainAnalysisPlanOptions / ExplainAnalysisPlanResult.
• DocMindPublicIntent, DocMindAnalyzeOptions, DocMindV2Extensions (incluye hueco opcional structured).

Modelo estructurado

• StructuredDocumentResult: sobre (blocks, tables, pages, images, metadata, warnings, …).
• DocumentBlock y variantes: paragraph, heading, table, list-item, image-ref, page-break, unknown.
• DocumentTable, DocumentTableCell, DocumentPage, DocumentImageRef.
• normalizeBlock, normalizeBlocks, normalizeTables, normalizePages, normalizeImages, normalizeToStructuredResult.
• STRUCTURED_LOGICAL_FORMAT_HINTS: pistas de formato lógico.

Errores

• DocMindError, InvalidInputError, UnsupportedFormatError, CorruptFileError.
• DOC_MIND_ERROR_PREFIX, UNKNOWN_FORMAT_WARNING.

Guardas y utilidades binarias

• isBuffer, isUint8Array, isArrayBuffer, isBlob, isFile, isNamedInput, isBinaryInput, detectBinaryShape.
• binaryToUint8Array, resolveData.

Documentación ampliada

Los JSDoc del código fuente (src/index.ts, analysis/types.js, etc.) son la referencia más detallada. En el monorepo, Typedoc puede generar HTML a partir de estos paquetes.

Paquetes relacionados

| Paquete | Rol | |---------|-----| | @dragon708/docmind-node | Cliente Node: PDF, DOCX, OCR, Markdown híbrido, conversión binaria en servidor | | @dragon708/docmind-browser | Cliente navegador: DOCX, imágenes OCR, texto; sin PDF nativo | | @dragon708/docmind-markdown | Structured → Markdown / LLM / chunks; extractMarkdown unificado | | @dragon708/docmind-docx | Mammoth + ZIP para DOCX | | @dragon708/docmind-pdf | PDF.js, pdf-parse, pdf-lib, pipeline OCR | | @dragon708/docmind-ocr | Tesseract.js, TIFF, preprocesado |

Licencia

MIT (monorepo DocMind).