@dragon708/docmind-pdf

PDF para DocMind: texto nativo y metadatos (pdf-parse), texto y estructura con PDF.js (por página, outline, enlaces, anotaciones), formularios AcroForm con pdf-lib (listar, rellenar, aplanar), manipulación básica (insertar/paginar/partir/merge) y extractStructuredDataFromPdf, que construye StructuredDocumentResult. Opcionalmente, pipeline OCR sobre rasters en submódulo ./pipeline (integración con @dragon708/docmind-ocr). PDFs cifrados (Node): detección y desbloqueo opcional con qpdf-wasm (@neslinesli93/qpdf-wasm); ver sección Acceso / contraseña más abajo.

Requisito: Node ≥ 20 (motores pdfjs / entorno).

Si pdf-parse falla con errores como bad XRef entry (PDFs con xref incremental o restricciones), las APIs principales reintentan con PDF.js y añaden un warning: en el resultado.

Instalación

npm install @dragon708/docmind-pdf

Depende de @dragon708/docmind-ocr para el pipeline raster y de @neslinesli93/qpdf-wasm para el desbloqueo opcional con contraseña. No uses este paquete en bundles browser estándar salvo que configures pdfjs/workers explícitamente; en apps web suele procesarse PDF en servidor (@dragon708/docmind-node).

Exportaciones del entry principal (@dragon708/docmind-pdf)

Análisis y texto

import {
  analyzePdf,
  extractTextFromPdf,
  extractPdfMetadata,
  getPdfPageCount,
  type PdfAnalyzeOptions,
  type PdfAnalysisResult,
} from "@dragon708/docmind-pdf";

const analysis = await analyzePdf(buffer, {
  ocr: "auto",
  password: undefined, // opcional: PDF cifrado
  pdfUnlock: { preProcess: false, enabled: true },
});
const meta = await extractPdfMetadata(buffer);
const pages = await getPdfPageCount(buffer);

Documento estructurado

import {
  extractStructuredDataFromPdf,
  type ExtractStructuredDataFromPdfOptions,
  type ExtractStructuredDataFromPdfIncludeFlags,
} from "@dragon708/docmind-pdf";

const structured = await extractStructuredDataFromPdf(buffer, {
  include: { outline: true, links: true, annotations: true },
  ocr: "auto",
});

Texto por página (PDF.js)

import {
  extractPdfTextByPage,
  extractPdfPages,
  type ExtractPdfByPageOptions,
} from "@dragon708/docmind-pdf";

const byPage = await extractPdfTextByPage(buffer, { maxPages: 50 });
const pageBodies = await extractPdfPages(buffer, options);

Outline, enlaces, anotaciones

import {
  extractPdfOutline,
  extractPdfLinks,
  extractPdfAnnotations,
} from "@dragon708/docmind-pdf";

const outline = await extractPdfOutline(buffer);
const links = await extractPdfLinks(buffer);
const annotations = await extractPdfAnnotations(buffer);

Formularios (pdf-lib)

import {
  getPdfFormFields,
  fillPdfForm,
  flattenPdfForm,
  type PdfFormFillValues,
} from "@dragon708/docmind-pdf";

const fields = await getPdfFormFields(buffer);
await fillPdfForm(buffer, { campo: "valor" } as PdfFormFillValues);
await flattenPdfForm(buffer);

Manipulación

import {
  mergePdf,
  splitPdf,
  insertPdfPages,
  removePdfPages,
  type SplitPdfOptions,
  type InsertPdfPagesOptions,
} from "@dragon708/docmind-pdf";

Estrategia OCR del pipeline PDF

import type { PdfOcrPipelineStrategy } from "@dragon708/docmind-pdf";
// "native-first" | "ocr-only" | "hybrid"

Acceso / contraseña (Node, qpdf-wasm)

import {
  analyzePdf,
  detectPdfAccessState,
  getProcessablePdfInput,
  cleanupUnlockedPdfArtifacts,
  unlockPdfWithQpdfWasm,
} from "@dragon708/docmind-pdf";

const state = await detectPdfAccessState(buffer);
const proc = await getProcessablePdfInput(buffer, { password: "secret" });
if (proc.ok) {
  try {
    /* pdf-parse, analyzePdf(proc.buffer, …), etc. */
  } finally {
    cleanupUnlockedPdfArtifacts(proc);
  }
}

• DOCMIND_DISABLE_QPDF_WASM=1: no carga wasm (fallos explícitos si hace falta desbloquear).
• analyzePdf: pasa password y/o pdfUnlock.preProcess para activar la capa antes del parse.

Submódulo ./pipeline (@dragon708/docmind-pdf/pipeline)

import { runPdfOcrPipeline } from "@dragon708/docmind-pdf/pipeline";

// Rasteriza / elige estrategia nativa vs OCR según opciones

Úsalo cuando la API pública de Node (analyzeFile, runOcr) no baste y necesites control fino del pipeline en servidor.

Tipos y opciones frecuentes

• PdfBinaryInput: buffer + nombre/MIME opcionales.
• PdfAnalyzeOptions: ocr, maxPages, ocrStrategy, idiomas, señales de abort, etc.
• ExtractPdfByPageOptions, ExtractPdfStructureOptions: flags de inclusión para outline/links/anotaciones.
• Resultados tipados: PdfOutlineResult, PdfLinksResult, PdfAnnotationsResult, GetPdfFormFieldsResult, etc.

Integración con Markdown

@dragon708/docmind-markdown convierte PDF a Markdown en Node (con fallback estructurado cuando aplica); ese camino se alimenta del análisis PDF y del texto/layout expuesto aquí y en el paquete markdown. Este paquete no reexporta extractMarkdown.

Errores y PDF corruptos

PDF inválidos o cifrados pueden fallar con errores de pdf-parse/pdf-lib/pdfjs. Captura y muestra message; DocMind a veces envuelve en DocMindError aguas arriba.

Paquetes relacionados

| Paquete | Rol | |---------|-----| | @dragon708/docmind-node | API pública analyzeFile / extractStructuredData PDF | | @dragon708/docmind-ocr | Tesseract en pipeline | | @dragon708/docmind-markdown | PDF → Markdown en Node | | @dragon708/docmind-shared | Tipos |

Licencia

MIT (monorepo DocMind).