@happyvertical/documents

中文文档
0.113.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 7721

Multi-part document processing with support for PDF, Word, PowerPoint, HTML, and Markdown

原始使用文档
文档目录15 节
  1. Installation
  2. Quick Start
  3. Usage
  4. Document Management System Detection
  5. Override MIME Type
  6. Cache Control
  7. API Reference
  8. fetchDocument(url, options?)
  9. FetchDocumentOptions
  10. Document (class)
  11. PDFProcessor
  12. DOCXProcessor and PPTXProcessor
  13. getTitleFromUrl(url, defaultTitle?)
  14. Types
  15. License

@happyvertical/documents

License: MIT

Document processing with hierarchical structure. Supports PDF documents with text extraction, Word (.docx) and PowerPoint (.pptx) files read through the optional Kreuzberg engine, automatic document management system detection (WordPress Download Manager, CivicWeb, DocuShare), and file caching. Uses @happyvertical/spider for web page analysis and @happyvertical/pdf for PDF text extraction.

Installation

Install from the public npm registry:

npm install @happyvertical/documents

Anonymous installs also require the package's external @happyvertical/ocr, @happyvertical/pdf, and @happyvertical/spider dependencies to be available on public npm.

Quick Start

import { fetchDocument } from '@happyvertical/documents';

// Process a local PDF
const doc = await fetchDocument('file:///path/to/report.pdf');

for (const part of doc.parts) {
  console.log(part.title);
  console.log(part.content);
}

// Fetch a remote PDF (auto-detected from URL extension)
const remote = await fetchDocument('https://example.com/report.pdf');
console.log(remote.parts[0].content);

Usage

Document Management System Detection

When fetching web URLs, the package uses @happyvertical/spider to detect document management systems and extract direct PDF links:

// WordPress Download Manager URL — spider detects the PDF link automatically
const doc = await fetchDocument(
  'https://example.com/download/meeting-minutes/',
  { scraper: 'basic', spider: 'dom' }
);

Override MIME Type

const doc = await fetchDocument('https://example.com/download?id=123', {
  type: 'application/pdf',
});

Cache Control

const doc = await fetchDocument('https://example.com/report.pdf', {
  cacheDir: './my-cache',
  cache: true,
  cacheExpiry: 600_000, // 10 minutes
});

API Reference

fetchDocument(url, options?)

Main factory function. Detects document format, selects the appropriate processor, and returns structured content.

  • url string — Document URL or file path (file://, http://, https://)
  • options FetchDocumentOptions — See below
  • Returns Promise<Document>
  • Throws if no processor is available for the detected MIME type

FetchDocumentOptions

OptionTypeDefaultDescription
typestringauto-detectedOverride MIME type detection
extractImagesbooleantrueExtract images from document (stub — currently returns [])
runOcrbooleantrue for PDFsRun OCR on extracted images (stub)
cacheDirstringOS temp dirDirectory for caching downloaded files
cachebooleantrueEnable/disable spider fetch caching
cacheExpirynumber300000Cache expiry in milliseconds
scraper'basic' | 'tree' | 'crawlee''basic'Scraper strategy for content extraction. crawlee is a deprecated alias for spider: 'crawlee' with basic scraping.
spider'simple' | 'dom' | 'crawlee' | 'crawl4ai''dom'Spider adapter for fetching web pages
headersRecord<string, string>—Custom HTTP headers for spider requests
timeoutnumber30000Request timeout in milliseconds
maxDurationnumber—Max scraping time in milliseconds
maxInteractionsnumber—Max interactions for advanced scrapers

Document (class)

Base document handler. Manages downloading, caching, and local file path resolution. Used internally by processors; can also be used directly via Document.create(url, options).

PDFProcessor

Implements DocumentProcessor. Extracts text from PDF files, validates PDF headers (detects HTML cache poisoning), and caches processed results.

DOCXProcessor and PPTXProcessor

Read Word and PowerPoint files through Kreuzberg (@kreuzberg/node, an optional dependency; no LibreOffice). fetchDocument picks them from the .docx / .pptx extension or MIME type.

  • DOCX: one markdown part per heading section, nested by heading level (text before the first heading is a leading part titled with the document title). Embedded images are attached to the first part.
  • PPTX: one text part per slide, in order. part.metadata.slide is the 1-based slide number, part.title the first line of slide text, part.notes the speaker notes (absent when the slide has none) and part.images the pictures on that slide (image.data holds the bytes, image.altText the description).
  • Kreuzberg not installed: process() resolves with parts: [] and document.unsupported = { code: 'dependency-missing', reason, dependency: '@kreuzberg/node' } instead of throwing. Corrupt files still reject.

For bytes you already hold in memory use extractOffice(source, 'docx' | 'pptx', { extractImages? }), which takes a Buffer, Uint8Array or file path and returns { status: 'ok', format, title, parts, metadata } or { status: 'unsupported', code, reason, dependency, format }.

import { extractOffice } from '@happyvertical/documents';

const result = await extractOffice(bytes, 'pptx');
if (result.status === 'unsupported') {
  console.warn(result.reason);
} else {
  for (const slide of result.parts) console.log(slide.metadata?.slide, slide.content, slide.notes);
}

getTitleFromUrl(url, defaultTitle?)

Extracts a human-readable title from a URL by parsing the filename, removing extensions, and decoding URL-encoded characters.

Types

interface Document {
  url: string;
  type: string;
  parts: DocumentPart[];
  metadata?: Record<string, any>;
  unsupported?: { code: 'dependency-missing'; reason: string; dependency?: string };
}

interface DocumentPart {
  id: string;
  title: string;
  content: string;
  type: 'text' | 'html' | 'markdown';
  images?: DocumentImage[];
  notes?: string; // speaker notes (PPTX slides)
  metadata?: Record<string, any>;
  parts?: DocumentPart[];
}

interface DocumentImage {
  id: string;
  url: string;
  localPath?: string;
  data?: Uint8Array; // in-memory bytes (Office documents)
  altText?: string;
  ocrText?: string;
  position?: number;
  metadata?: { width?: number; height?: number; format?: string };
}

interface DocumentProcessor {
  process(url: string, options?: FetchDocumentOptions): Promise<Document>;
  supports(type: string): boolean;
}

License

MIT

版本与发布记录

@happyvertical/documents 共发布 131 个版本,首次发布于 2026/06/24;过去 12 个月发布了 131 个版本。

版本发布日期距今
0.113.1latest2026/11/17今天
0.113.02026/11/152 天前
0.112.32026/11/134 天前
0.112.22026/11/125 天前
0.112.12026/11/125 天前
0.112.02026/11/125 天前

关于 @happyvertical/documents 的常见问题

@happyvertical/documents 是什么?

Multi-part document processing with support for PDF, Word, PowerPoint, HTML, and Markdown

如何安装 @happyvertical/documents?

在项目目录运行 npm install @happyvertical/documents,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 have-documents-context,可以用 npx have-documents-context 直接运行。

@happyvertical/documents 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/documents 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/documents 可以商用吗?

@happyvertical/documents 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/documents 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/documents 在 2026/10/17 – 2026/11/15 这 30 天内被下载 7,721 次,日均约 257 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/documents 还在维护吗?

最新版本 0.113.1 发布于 2026/11/17(今天);至今共发布 131 个版本,其中过去 12 个月发布了 131 个;首次发布于 2026/06/24。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。