// Public type surface for the `docling.rs` npm package. Re-exports the native
// binding's option/result types and unguarded functions, and declares the
// JS-wrapped classes, the dependency API, and the streaming helper.

import type {
  ConverterOptions,
  OutputOptions,
  ConvertOptions,
  ConvertInput as NativeConvertInput,
  ConvertResult,
  ArchiveItem,
  ChunkOptions,
  Chunk,
  EmailAttachment,
  EmailAttachmentOptions,
} from './native'

/**
 * In-memory input: the native binding's, plus the media type a registered
 * backend can claim it by (#680). The built-in formats ignore `mimeType`.
 */
export interface ConvertInput extends NativeConvertInput {
  mimeType?: string
}

export type {
  ArchiveItem,
  ConverterOptions,
  OutputOptions,
  ConvertOptions,
  ConvertResult,
  ChunkOptions,
  Chunk,
  EmailAttachment,
  EmailAttachmentOptions,
}

// Format helpers pass straight through from the native binding.
export { supportedFormats, formatFromName, detectFormat } from './native'
// Email attachment payloads of an .eml / .msg (#561): list them with their
// bytes, then `convert({ name: att.name, data: att.data, format: att.format })`
// the ones you want — `format` carries what the extension cannot (#564). The
// `*Async` forms parse off the event loop.
export {
  emailAttachments,
  emailAttachmentsFile,
  emailAttachmentsAsync,
  emailAttachmentsFileAsync,
} from './native'

/**
 * A backend for {@link registerBackend} (#680): a function that reads one
 * input format, and what it claims. An input is claimed when its extension
 * is in `extensions`, *or* its `mimeType` in `mimeTypes`, *or* `sniff`
 * accepts its bytes.
 */
export interface BackendSpec {
  /** Shown by {@link registeredBackends} and in errors; defaults to the first extension or media type. */
  name?: string
  /** Extensions, case-insensitive, with or without the dot (`'rtf2'`, `'.RTF2'`). */
  extensions?: string[]
  /** Media types, matched without parameters (`'application/x-rtf2'`). */
  mimeTypes?: string[]
  /** A cheap content check; runs on every input before the built-in formats. A throw counts as `false`. */
  sniff?: (data: Buffer) => boolean
  /**
   * Read the input: return Markdown (a string) or a DoclingDocument (the
   * docling-core JSON as an object). Either is converted under the caller's
   * options. May return a promise when called through the `*Async` functions.
   */
  convert: (data: Buffer, name: string) => string | object | Promise<string | object>
  /** Higher is tried first; among equals, the earlier registration. Default 0. */
  priority?: number
}

/** What {@link registeredBackends} lists for one backend. */
export interface RegisteredBackend {
  name: string
  extensions: string[]
  mimeTypes: string[]
  sniff: boolean
  priority: number
}

/**
 * Register a backend (#680) for the module-level functions (convert,
 * chunk, streamFileMarkdown, …) and every {@link DocumentConverter} created
 * afterwards. Registered backends are consulted before the built-in
 * formats, so one can add a format or take one over. A claimed input's
 * result reports its built-in format id, or `'plugin'`. Archive entries are
 * not routed to registered backends. Returns the backend's name.
 */
export declare function registerBackend(spec: BackendSpec): string
/** The module-level backends, in the order they are tried. */
export declare function registeredBackends(): RegisteredBackend[]
/** Remove the module-level backends of this name; whether any was removed. */
export declare function unregisterBackend(name: string): boolean

/** Callback form used by the native streaming API (prefer {@link streamFileMarkdown}). */
export type StreamCallback = (err: Error | null, chunk: string | undefined | null) => void

/**
 * A conversion progress event (#783; docling's `docling.datamodel.progress`), as the
 * async conversions' `progress` callback receives it: `document_started`, one
 * `page_completed` per PDF / image page (`completed_pages` counts up to `total_pages`,
 * the pages `pages` selected; a page the `documentTimeout` cut off comes with
 * `success: false`), `enrichment_progress` for the picture passes, and last
 * `document_completed` with the result's `status`.
 */
export type ProgressEvent =
  | { kind: 'document_started'; document_index: number; document_name: string }
  | {
      kind: 'page_completed'
      document_index: number
      document_name: string
      page_no: number
      success: boolean
      completed_pages: number
      total_pages: number
    }
  | {
      kind: 'enrichment_progress'
      document_index: number
      document_name: string
      step: 'code_formula' | 'picture_classification' | 'picture_description' | 'chart_extraction' | 'other'
      label: string
      completed_items: number
      total_items: number
    }
  | {
      kind: 'document_completed'
      document_index: number
      document_name: string
      status: 'success' | 'partial_success' | 'failure'
    }

/** The async conversions' progress callback (#783): called with each {@link ProgressEvent} as it happens. */
export type ProgressCallback = (event: ProgressEvent) => void

/**
 * Convert a file on disk (format detected from the extension). Throws for
 * PDF/image/METS if deps aren't installed — except under `pipeline: 'vlm'`,
 * which loads no ONNX models and needs nothing on disk.
 */
export declare function convertFile(path: string, options?: ConvertOptions | null): ConvertResult
/** Convert in-memory bytes. Throws for PDF/image/METS if deps aren't installed (see {@link convertFile}). */
export declare function convert(input: ConvertInput, options?: ConvertOptions | null): ConvertResult
/** Async (Promise) file conversion, off the event loop. Rejects for PDF/image/METS if deps aren't installed (see {@link convertFile}). */
export declare function convertFileAsync(path: string, options?: ConvertOptions | null, progress?: ProgressCallback | null): Promise<ConvertResult>
/** Async (Promise) bytes conversion, off the event loop. Rejects for PDF/image/METS if deps aren't installed (see {@link convertFile}). */
export declare function convertAsync(input: ConvertInput, options?: ConvertOptions | null, progress?: ProgressCallback | null): Promise<ConvertResult>

/**
 * Convert every document inside a ZIP archive on disk (#557): one
 * {@link ArchiveItem} per entry in archive order — `converted` with its
 * result, `skipped` with the reason (unsupported type, nested archive, unsafe
 * path, over a `DOCLING_RS_ZIP_MAX_*` limit) or `failed` with the error. A
 * broken document fails only its own item. Throws only when the file is not
 * a readable ZIP archive. Not ML-guarded: a PDF entry without the models is
 * that entry's `failed` item.
 */
export declare function convertArchiveFile(path: string, options?: ConvertOptions | null): Array<ArchiveItem>
/** In-memory {@link convertArchiveFile}; `input.name` names the archive, `input.format` is ignored. */
export declare function convertArchive(input: ConvertInput, options?: ConvertOptions | null): Array<ArchiveItem>
/** Async (Promise) {@link convertArchiveFile}, off the event loop. */
export declare function convertArchiveFileAsync(path: string, options?: ConvertOptions | null): Promise<Array<ArchiveItem>>
/** Async (Promise) {@link convertArchive}, off the event loop. */
export declare function convertArchiveAsync(input: ConvertInput, options?: ConvertOptions | null): Promise<Array<ArchiveItem>>

/**
 * Chunk a file with docling's chunkers: convert it, then run the hierarchical
 * (default) or hybrid (`chunker: 'hybrid'` + `tokenizer`) chunker over the
 * document. Throws for PDF/image/METS if deps aren't installed.
 */
export declare function chunkFile(path: string, options?: ChunkOptions | null): Array<Chunk>
/** Async (Promise) {@link chunkFile}; conversion + chunking run off the event loop. */
export declare function chunkFileAsync(path: string, options?: ChunkOptions | null): Promise<Array<Chunk>>
/** Chunk in-memory bytes (same input contract as {@link convert}). */
export declare function chunk(input: ConvertInput, options?: ChunkOptions | null): Array<Chunk>
/** Async (Promise) {@link chunk}. */
export declare function chunkAsync(input: ConvertInput, options?: ChunkOptions | null): Promise<Array<Chunk>>
/**
 * Chunk an already-converted document, passed as docling-core JSON (the
 * `content` of a `convert*` call with `to: 'json'`) — so a document converted
 * once (e.g. through the warm PDF {@link Pipeline}) chunks without re-converting.
 */
export declare function chunkDocument(documentJson: string, options?: ChunkOptions | null): Array<Chunk>
/** Async (Promise) {@link chunkDocument}. */
export declare function chunkDocumentAsync(documentJson: string, options?: ChunkOptions | null): Promise<Array<Chunk>>

/**
 * A reusable converter holding config (strict / fetchImages / allowedFormats,
 * and the `pipeline` / `vlm*` selection).
 */
export declare class DocumentConverter {
  constructor(options?: ConverterOptions | null)
  /** Register a backend on this converter only (#680); see {@link registerBackend}. */
  registerBackend(spec: BackendSpec): string
  /** This converter's backends: the module's as of its creation, then its own. */
  registeredBackends(): RegisteredBackend[]
  convertFile(path: string, options?: OutputOptions | null): ConvertResult
  convert(input: ConvertInput, options?: OutputOptions | null): ConvertResult
  convertFileAsync(path: string, options?: OutputOptions | null, progress?: ProgressCallback | null): Promise<ConvertResult>
  convertAsync(input: ConvertInput, options?: OutputOptions | null, progress?: ProgressCallback | null): Promise<ConvertResult>
  convertFileStreaming(path: string, callback: StreamCallback, options?: OutputOptions | null): void
  /** {@link convertArchiveFile} with this converter's config per entry. */
  convertArchiveFile(path: string, options?: OutputOptions | null): Array<ArchiveItem>
  convertArchive(input: ConvertInput, options?: OutputOptions | null): Array<ArchiveItem>
  convertArchiveFileAsync(path: string, options?: OutputOptions | null): Promise<Array<ArchiveItem>>
  convertArchiveAsync(input: ConvertInput, options?: OutputOptions | null): Promise<Array<ArchiveItem>>
}

/** Output options for {@link Pipeline.streamFileMarkdown} (streamable modes only). */
export interface PipelineStreamOptions {
  imageMode?: 'placeholder' | 'embedded'
  artifactsDir?: string
  /** Text inserted between pages in the Markdown (docling's `page_break_placeholder`). */
  pageBreakPlaceholder?: string
}

/**
 * A reusable PDF/image pipeline that keeps the ONNX models loaded across calls.
 * Use instead of the per-call functions when converting many PDFs/images — the
 * one-shot path reloads every model each call. Handles `pdf` and `image` inputs.
 *
 * The `*Async` variants run the conversion off the event loop; overlapping
 * calls on one instance queue (the models are mutable sessions), so batch
 * throughput comes from keeping the models warm, not from parallel calls.
 *
 * `pipeline: 'vlm'` is rejected here: it loads no models, so there is nothing
 * to keep warm. Use {@link DocumentConverter} or {@link convertFile} for it.
 */
export declare class Pipeline {
  constructor(options?: ConverterOptions | null)
  convertFile(path: string, options?: OutputOptions | null): ConvertResult
  convert(input: ConvertInput, options?: OutputOptions | null): ConvertResult
  /** Async (Promise) file conversion on the warm pipeline, off the event loop. */
  convertFileAsync(path: string, options?: OutputOptions | null, progress?: ProgressCallback | null): Promise<ConvertResult>
  /** Async (Promise) bytes conversion on the warm pipeline, off the event loop. */
  convertAsync(input: ConvertInput, options?: OutputOptions | null, progress?: ProgressCallback | null): Promise<ConvertResult>
  /** Callback-form streaming (prefer {@link Pipeline.streamFileMarkdown}). */
  convertFileStreaming(path: string, callback: StreamCallback, options?: OutputOptions | null): void
  /**
   * Stream a PDF's Markdown in chunks through the warm pipeline, in document
   * order, as pages finish converting (an image arrives as a single chunk).
   * Concatenating the chunks reproduces the buffered Markdown byte-for-byte.
   */
  streamFileMarkdown(
    filePath: string,
    options?: PipelineStreamOptions,
  ): AsyncGenerator<string, void, unknown>
}

// --- dependency provisioning (PDF/image ML pipeline) -----------------------

/** Where installed dependencies live and which are present. */
export interface DependencyStatus {
  /** Install home directory. */
  home: string
  /** Layout model (layout_heron.onnx) present. */
  layout: boolean
  /** OCR model + dictionary present. */
  ocr: boolean
  /** PP-OCR text detector (ocr_det.onnx) present — optional; without it OCR reads only inside layout regions (#429). */
  ocrDet: boolean
  /** Text-line orientation classifier (ocr_textline_ori.onnx) present — optional; ocrTextlineOrientation's 0/180 check (#666). */
  ocrTextlineOri: boolean
  /** TableFormer encoder/decoder/bbox present. */
  tableformer: boolean
  /** Hybrid-chunker tokenizer (.models/chunk/tokenizer.json) present. */
  chunkTokenizer: boolean
  /**
   * True when the minimum for PDF and image input (the layout model) is
   * present — that is, for the *standard* pipeline. `pipeline: 'vlm'` needs
   * nothing on disk, so it can convert with `ready: false`.
   */
  ready: boolean
  /** Human-readable list of the missing required assets. */
  missing: string[]
}

/**
 * Report which PDF/image dependencies are present on disk. Fetch them with
 * `scripts/install/download_dependencies.sh` (see the package README) — this function
 * only reports status, it does not download anything.
 */
export declare function checkDependencies(options?: { dir?: string }): DependencyStatus

// --- streaming --------------------------------------------------------------

/**
 * Options for {@link streamFileMarkdown}: every converter knob (including
 * `pipeline` / `vlm*` and `pages`) plus the streamable output modes. Extending
 * `ConverterOptions` rather than restating fields keeps this from drifting as
 * the native option set grows — the implementation forwards the whole object.
 */
export interface StreamOptions extends ConverterOptions {
  imageMode?: 'placeholder' | 'embedded'
  artifactsDir?: string
  /** Text inserted between pages in the Markdown (docling's `page_break_placeholder`). */
  pageBreakPlaceholder?: string
}

/**
 * Stream a file's Markdown in chunks, in document order, as conversion
 * progresses — the win for PDF, whose pages convert in parallel. Concatenating
 * the chunks reproduces the buffered `convertFile(path).content` byte-for-byte.
 *
 * Under `pipeline: 'vlm'` nothing streams — the endpoint answers a whole page
 * per request — so the document arrives as a single chunk. The concatenation
 * contract above still holds.
 */
export declare function streamFileMarkdown(
  filePath: string,
  options?: StreamOptions,
): AsyncGenerator<string, void, unknown>

/**
 * Stream a file's chunks as the chunkers produce them — the streaming
 * counterpart of {@link chunkFile}. The first chunk is ready (e.g. for
 * embedding) while the rest of the document is still being chunked, and no
 * all-chunks array is materialized. Abandoning the generator early (`break`)
 * cancels the background chunking. Throws for PDF/image/METS if deps aren't
 * installed.
 */
export declare function streamFileChunks(
  filePath: string,
  options?: ChunkOptions | null,
): AsyncGenerator<Chunk, void, unknown>

/** Streaming counterpart of {@link chunk} (same contract as {@link streamFileChunks}). */
export declare function streamChunks(
  input: ConvertInput,
  options?: ChunkOptions | null,
): AsyncGenerator<Chunk, void, unknown>

/**
 * Streaming counterpart of {@link chunkDocument}: chunk an already-converted
 * docling-core JSON document (same contract as {@link streamFileChunks}).
 * Touches no ML models.
 */
export declare function streamDocumentChunks(
  documentJson: string,
  options?: ChunkOptions | null,
): AsyncGenerator<Chunk, void, unknown>