docling-serve-client 0.4.0 → 0.6.0

package/src/types.ts

@@ -5,7 +5,7 @@ import type { ErrorCode } from './core/result.js';
 import type { DoclingDocument } from './document.js';
 
 // -------------------------------------------------------------------
-// --- 1. Result & Error Types
+// --- 1. Types
 // -------------------------------------------------------------------
 
 /** Identifies failure cause across validation, network, HTTP, and conversion. */
@@ -90,9 +90,7 @@ export type ServerError = {
  */
 export type ServerVersions = Record<string, string>;
 
-// -------------------------------------------------------------------
-// --- 2. Options
-// -------------------------------------------------------------------
+// Options
 
 /**
  * **Bytes of the file to convert; the format is detected by magic bytes**.
@@ -103,7 +101,7 @@ export type ServerVersions = Record<string, string>;
  */
 export type ConvertInput = Uint8Array;
 
-/** @deprecated Use `ConvertInput`; images are accepted as well. */
+/** Deprecated: use `ConvertInput`; images are accepted as well. */
 export type PdfInput = ConvertInput;
 
 /** Supported conversion pipeline backend. */
@@ -112,6 +110,14 @@ export type Pipeline = 'standard' | 'vlm';
 /** PDF text extraction backend used by docling. */
 export type PdfBackend = 'docling_parse' | 'pypdfium2';
 
+/**
+ * **OCR engine preset sent as `ocr_preset`**.
+ *
+ * - known engines autocomplete; any other non-empty preset id is accepted and sent as is
+ * - installed engines: `stages.ocr.presets` of `client.capabilities()`
+ */
+export type OcrEngine = 'auto' | 'rapidocr' | 'easyocr' | 'tesseract' | 'tesserocr' | 'ocrmac' | (string & {});
+
 /** docling conversion options; set as factory defaults and/or per call. */
 export type DoclingOptions = {
     /** Nests headings by bookmarks, numbering, and font style; without it every heading has level 1. Default `true`. */
@@ -135,9 +141,12 @@ export type DoclingOptions = {
     /**
      * **OCRs whole PDF pages and drops their text layer**: for PDFs with broken text. Default `false`.
      *
+     * - enables OCR even with `ocr: false` (docling skips full-page OCR when `do_ocr=false`)
      * - ignored for image input: it has no text layer, and full-page OCR there merges words (`stepsand`)
      */
     forceOcr?: boolean;
+    /** OCR engine preset (`ocr_preset`); an engine the server lacks fails the conversion. Default `'auto'`. */
+    ocrEngine?: OcrEngine;
 };
 
 /** docling options of the factory: every per-call option plus the factory-only ones, applied to every call. */
@@ -156,6 +165,17 @@ export type CallOptions = {
     signal?: AbortSignal;
 };
 
+/**
+ * **Options for job helpers (`runMarkdown`, `runDocument`, `waitForJob`)**.
+ *
+ * - `signal` covers entire call: submit, status polls, and waits
+ * - rejected by `convert*`, `submit*`, and `check`
+ */
+export type PollOptions = CallOptions & {
+    /** Delay between status polls in ms (integer `1..2147483647`). Default: factory `pollMs` (`10`). */
+    pollMs?: number;
+};
+
 /**
  * **Images in the md**.
  *
@@ -200,9 +220,7 @@ export type DocumentOptions = DoclingOptions &
         pageImages?: boolean;
     };
 
-// -------------------------------------------------------------------
-// --- 3. Outputs
-// -------------------------------------------------------------------
+// Outputs
 
 /** Pixel dimensions of an image. */
 export type ImageSize = {
@@ -305,9 +323,53 @@ export type ConvertedDocument = {
     versions: ServerVersions | null;
 };
 
-// -------------------------------------------------------------------
-// --- 4. Asynchronous Jobs
-// -------------------------------------------------------------------
+/**
+ * **Conversion settings exactly as sent in the multipart request**.
+ *
+ * - every key is the camelCase name of a docling-serve form field (`ocrPreset` = `ocr_preset`)
+ * - `null`: field not sent (md-only fields of json output, unused presets, unset factory options)
+ * - `ocrLang`: empty means not sent, i.e. engine default
+ * - server-side configuration not covered by request fields (e.g. layout model) is not included
+ */
+export type DoclingSettings = {
+    fromFormats: 'pdf' | 'image';
+    toFormats: 'md' | 'json';
+    imageExportMode: 'embedded' | 'placeholder';
+    includeImages: boolean;
+    includePageImages: boolean;
+    imagesScale: number;
+    mdCompactTables: boolean | null;
+    mdPageBreakPlaceholder: string | null;
+    doOcr: boolean;
+    forceOcr: boolean;
+    ocrPreset: string;
+    ocrLang: string[];
+    pdfBackend: PdfBackend;
+    pipeline: Pipeline;
+    vlmPipelinePreset: string | null;
+    doTableStructure: boolean;
+    tableMode: 'accurate';
+    tableStructurePreset: string;
+    tableCellMatching: boolean;
+    doPdfHeadingHierarchy: boolean;
+    doFormulaEnrichment: boolean;
+    doCodeEnrichment: boolean;
+    codeFormulaPreset: string | null;
+    doChartExtraction: boolean;
+    chartExtractionPreset: string | null;
+    doPictureClassification: boolean;
+    doPictureDescription: boolean;
+    pageRange: [from: number, to: number] | null;
+    documentTimeout: number | null;
+    abortOnError: boolean;
+};
+
+/** Result of `convert*` and `run*` plus the settings sent with the conversion. */
+export type WithSettings<T> = T & {
+    settings: DoclingSettings;
+};
+
+// Asynchronous Jobs
 
 /** Image handling of a md job, applied when `check()` picks up the result. */
 export type MarkdownJobOutput =
@@ -320,6 +382,8 @@ export type MarkdownJob = {
     /** Server-side task id. */
     id: string;
     output: MarkdownJobOutput;
+    /** Settings sent with the submission; `check()` neither needs nor returns them. */
+    settings: DoclingSettings;
 };
 
 /** Handle of a document conversion, returned by `submitDocument()`; plain JSON, safe to store. */
@@ -327,11 +391,16 @@ export type DocumentJob = {
     kind: 'document';
     /** Server-side task id. */
     id: string;
+    /** Settings sent with the submission; `check()` neither needs nor returns them. */
+    settings: DoclingSettings;
 };
 
-/** Any job handle accepted by `check()`. */
+/** Any job handle returned by `submit*()`. */
 export type Job = MarkdownJob | DocumentJob;
 
+/** Job handle accepted by `check()`; `settings` may be dropped when storing the job. */
+export type JobRef = Omit<MarkdownJob, 'settings'> | Omit<DocumentJob, 'settings'>;
+
 /** State of an async job; `done` carries the conversion result. */
 export type JobState<T> =
     /** Pending in server queue; `position` is 1-based when reported by server. */
@@ -341,18 +410,73 @@ export type JobState<T> =
     /** Completed; carries the conversion result. */
     | ({ status: 'done' } & T);
 
-// -------------------------------------------------------------------
-// --- 5. Client
-// -------------------------------------------------------------------
+// Server Capabilities
+
+/** Model or engine preset a pipeline stage offers; `id` is the value of the stage's form field. */
+export type CapabilityPreset = {
+    id: string;
+    name: string;
+    description: string | null;
+    /** Origin, e.g. `'docling'` or `'default'` (server default alias). */
+    source: string;
+};
+
+/** Pipeline stage (OCR, table structure, VLM, ...) with its form field and installed presets. */
+export type CapabilityStage = {
+    /** Form field selecting the preset, e.g. `'ocr_preset'`. */
+    option: string;
+    customConfigOption: string | null;
+    /** Preset used when the field is not sent. */
+    default: string;
+    presets: CapabilityPreset[];
+};
+
+/** Server limits; `null` means unlimited or not reported. */
+export type CapabilityLimits = {
+    maxDocumentTimeout: number | null;
+    maxImagesScale: number | null;
+    maxSourcesPerRequest: number | null;
+    maxNumPages: number | null;
+    maxFileSize: number | null;
+};
+
+/**
+ * **What the docling-serve instance offers (`GET /v1/capabilities`)**.
+ *
+ * - snake_case keys of the server payload converted to camelCase; `stages` keys stay as sent (e.g. `table_structure`)
+ * - missing or mistyped fields become empty lists, `''`, `null` or `false`
+ * - diagnostics only: conversions never query it
+ */
+export type ServerCapabilities = {
+    versions: ServerVersions;
+    stages: Record<string, CapabilityStage>;
+    sources: string[];
+    targets: {
+        allowed: string[];
+        default: string;
+    };
+    outputFormats: string[];
+    imageExportModes: string[];
+    limits: CapabilityLimits;
+    features: {
+        apiKeyRequired: boolean;
+        artifactStorage: boolean;
+        websocket: boolean;
+    };
+};
+
+// Client
 
 /** Configuration passed to `createDoclingClient`. */
 export type DoclingConfig = {
-    /** docling-serve base URL, e.g. `'http://127.0.0.1:5001'`; trailing `/` are removed. */
+    /** docling-serve base URL, e.g. `'http://127.0.0.1:5001'`; trailing `/` removed; no query, fragment, or credentials. */
     baseUrl: string;
     /** Sent as `X-Api-Key` header. */
     apiKey?: string;
-    /** Limit per request in ms (not `/version`); on expiry the call resolves with `aborted`. */
+    /** Time limit per request in ms (integer `1..2147483647`, excludes `/version`); resolves to `aborted` on expiry. */
     timeoutMs?: number;
+    /** Delay between job helper status polls in ms (integer `1..2147483647`). Default `10`. */
+    pollMs?: number;
     /** Custom fetch implementation for mocking or custom dispatchers. */
     fetch?: typeof fetch;
     /** Defaults for every call; call options override them key by key, except the factory-only ones. */
@@ -360,28 +484,65 @@ export type DoclingConfig = {
 };
 
 /**
- * **docling-serve client**.
+ * **docling-serve client**: every call returns a Promise.
  *
- * - `convert*`: one synchronous request
- * - `submit*` + `check`: async job; the caller stores the job and polls
+ * - single request (`convert*`): one HTTP request to sync endpoint; answers on `DOCLING_SERVE_SYNC_POLL_INTERVAL`
+ *   ticks (default 2 s) and returns 504 after `DOCLING_SERVE_MAX_SYNC_WAIT`
+ * - job (`submit*` + `check`): async endpoints; caller stores job and polls
+ * - job helper (`run*`, `waitForJob`): submits or takes a job and polls every `pollMs` until done
  */
 export type DoclingClient = {
     /** PDF or image to docling's md; images as placeholders, removed or extracted. */
-    convertMarkdown(input: ConvertInput, options?: MarkdownOptions): Promise<Result<ConvertedMarkdown>>;
+    convertMarkdown(input: ConvertInput, options?: MarkdownOptions): Promise<Result<WithSettings<ConvertedMarkdown>>>;
     /** PDF or image to docling's DoclingDocument. */
-    convertDocument(input: ConvertInput, options?: DocumentOptions): Promise<Result<ConvertedDocument>>;
-    /** Starts an async md conversion. */
+    convertDocument(input: ConvertInput, options?: DocumentOptions): Promise<Result<WithSettings<ConvertedDocument>>>;
+    /** Starts an async md conversion; the job carries the sent settings. */
     submitMarkdown(input: ConvertInput, options?: MarkdownOptions): Promise<Result<MarkdownJob>>;
-    /** Starts an async document conversion. */
+    /** Starts an async document conversion; the job carries the sent settings. */
     submitDocument(input: ConvertInput, options?: DocumentOptions): Promise<Result<DocumentJob>>;
     /**
      * **Polls a job; fetches its result once done**.
      *
-     * - docling-serve deletes a result `DOCLING_SERVE_RESULT_REMOVAL_DELAY` seconds (default 300) after its first
-     *   fetch: a `check` whose result download failed can be repeated within that time, later it returns
-     *   `not_found`; persist `done` data, or start docling-serve with `DOCLING_SERVE_SINGLE_USE_RESULTS=false`
+     * - docling-serve deletes the task `DOCLING_SERVE_RESULT_REMOVAL_DELAY` seconds (default 300) after first
+     *   result fetch: a `check` whose result download failed can be repeated within that window, later returning
+     *   `not_found` (`Unknown job id`); persist `done` data, or set `DOCLING_SERVE_SINGLE_USE_RESULTS=false`
+     * - `done` carries no settings (stored on the job)
+     */
+    check(job: Omit<MarkdownJob, 'settings'>, options?: CallOptions): Promise<Result<JobState<ConvertedMarkdown>>>;
+    check(job: Omit<DocumentJob, 'settings'>, options?: CallOptions): Promise<Result<JobState<ConvertedDocument>>>;
+    check(job: JobRef, options?: CallOptions): Promise<Result<JobState<ConvertedMarkdown | ConvertedDocument>>>;
+    /**
+     * **Submits an md job and polls every `pollMs` until done**: same result as `convertMarkdown`.
+     *
+     * - `signal` covers submit, status polls, and waits; `timeoutMs` limits each HTTP request
+     * - first error ends call; job never returned (use `submitMarkdown` + `waitForJob` to keep it)
+     * - aborting does not cancel the server-side job
+     */
+    runMarkdown(
+        input: ConvertInput,
+        options?: MarkdownOptions & PollOptions,
+    ): Promise<Result<WithSettings<ConvertedMarkdown>>>;
+    /**
+     * **Submits a document job and polls every `pollMs` until done**: same result as `convertDocument`.
+     *
+     * - `signal` covers submit, status polls, and waits; `timeoutMs` limits each HTTP request
+     * - first error ends call; job never returned (use `submitDocument` + `waitForJob` to keep it)
+     * - aborting does not cancel the server-side job
+     */
+    runDocument(
+        input: ConvertInput,
+        options?: DocumentOptions & PollOptions,
+    ): Promise<Result<WithSettings<ConvertedDocument>>>;
+    /**
+     * **Polls an existing job every `pollMs` until done**.
+     *
+     * - first status poll runs immediately; already-finished jobs cost one `check`
+     * - resolves to `check`'s `done` data without `status`; first error ends call
+     * - repeatable after a failed result download within `DOCLING_SERVE_RESULT_REMOVAL_DELAY` (default 300 s)
      */
-    check(job: MarkdownJob, options?: CallOptions): Promise<Result<JobState<ConvertedMarkdown>>>;
-    check(job: DocumentJob, options?: CallOptions): Promise<Result<JobState<ConvertedDocument>>>;
-    check(job: Job, options?: CallOptions): Promise<Result<JobState<ConvertedMarkdown | ConvertedDocument>>>;
+    waitForJob(job: Omit<MarkdownJob, 'settings'>, options?: PollOptions): Promise<Result<ConvertedMarkdown>>;
+    waitForJob(job: Omit<DocumentJob, 'settings'>, options?: PollOptions): Promise<Result<ConvertedDocument>>;
+    waitForJob(job: JobRef, options?: PollOptions): Promise<Result<ConvertedMarkdown | ConvertedDocument>>;
+    /** Installed presets, limits and features of the server; on demand only, never used by conversions. */
+    capabilities(options?: CallOptions): Promise<Result<ServerCapabilities>>;
 };