index.d.ts

export interface ParseOptions {
  /** Override where the bundled PDFium assets live. Needed only when a bundler or
   *  serverless packager relocates the package's files. Defaults to the pdfium/
   *  folder shipped with the package. */
  assetsDir?: string;
}

/** A single laid-out element extracted from the PDF. Bounding-box fields are
 *  normalized to 0..1 relative to the page, measured from the top-left. */
export interface Block {
  /** e.g. "Text", "Table", "Figure", "Header", "Section Header", "List Item",
   *  "Key Value", "Footer". Table content is HTML; Figure content is empty (it
   *  marks a graphic's location, no image bytes or OCR). */
  type: string;
  content: string;
  page: number;
  left: number;
  top: number;
  width: number;
  height: number;
}

export interface ParseResult {
  pages: number;
  has_text_layer: boolean;
  producer: string | null;
  blocks: Block[];
}

export interface BatchProgressEvent {
  index: number;
  completed: number;
  total: number;
  succeeded: number;
  failed: number;
  ok: boolean;
}

export interface ParsePdfBatchOptions extends ParseOptions {
  /** Maximum number of in-flight parses. Defaults to 4. */
  concurrency?: number;
  /** Stop after the first failed parse and reject. Defaults to false. */
  stopOnError?: boolean;
  /** Include per-item outputs in the return object. Defaults to true. */
  collectResults?: boolean;
  /** Called after each item finishes. */
  onProgress?: (event: BatchProgressEvent) => void;
}

export type ParsePdfBatchItemResult =
  | { ok: true; result: ParseResult }
  | { ok: false; error: Error };

export interface ParsePdfBatchSummary {
  total: number;
  succeeded: number;
  failed: number;
  results?: ParsePdfBatchItemResult[];
}

/** Load and instantiate the engine (PDFium + parser). The first call loads ~6 MB
 *  of WebAssembly and is the slow one; call once at startup so your first parse is
 *  fast. Optional: parsePdf() calls it for you. */
export function initParser(options?: ParseOptions): Promise<void>;

/** Parse PDF bytes into layout blocks. Rejects when the bytes are not a PDF
 *  PDFium can open. */
export function parsePdf(
  bytes: Uint8Array | ArrayBuffer,
  options?: ParseOptions,
): Promise<ParseResult>;

/** Parse many PDFs with bounded concurrency. */
export function parsePdfBatch(
  items: Array<Uint8Array | ArrayBuffer>,
  options?: ParsePdfBatchOptions,
): Promise<ParsePdfBatchSummary>;