docling-serve-client 0.4.0 → 0.6.0

package/src/images.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { isPlainObject } from './core/validate.js';
-import type { DoclingDocument, PageItem, ProvenanceItem } from './document.js';
+import type { BoundingBox, DoclingDocument, PageItem } from './document.js';
 import type {
     ExtractedImage,
     ImageOptions,
@@ -113,7 +113,6 @@ export function readPngSize(bytes: Uint8Array): ImageSize | undefined {
     if (!(bytes instanceof Uint8Array) || bytes.length < 24) {
         return undefined;
     }
-    // IHDR holds 32-bit width and height at offsets 16 and 20.
     const isPng =
         PNG_SIGNATURE.every((byte, i) => bytes[i] === byte) && PNG_IHDR.every((byte, i) => bytes[12 + i] === byte);
     if (!isPng) {
@@ -154,7 +153,6 @@ export function extractImages(markdown: string, options: Required<ImageOptions>)
         }
         const size = readPngSize(bytes);
         if (options.omitSmall && size !== undefined && isSmallImage(size)) {
-            // a marker, so removing it below also normalizes the blank lines around it
             output += OMITTED_IMAGE;
             continue;
         }
@@ -218,11 +216,11 @@ export function extractPageImages(document: DoclingDocument): ExtractedPageImage
  * - `prov`: any `prov[]` entry; for a table cell pass `{ page_no: table.prov[0].page_no, bbox: cell.bbox }`
  * - flips `BOTTOMLEFT` boxes using the page height from `document.pages`, then scales points by `PAGE_IMAGE_SCALE`
  * - works without `pageImages: true`; the boxes fit the page images of any conversion by this client
- * - returns `undefined` when page_no or a coordinate is not a finite number, or page is missing from `document.pages`
+ * - returns `undefined` when `page_no` or coordinate is not a finite number, or page is missing from `document.pages`
  */
 export function toPageImageBox(
     document: DoclingDocument,
-    prov: Pick<ProvenanceItem, 'page_no' | 'bbox'>,
+    prov: { page_no: number; bbox?: BoundingBox | null },
 ): PageImageBox | undefined {
     const pageNo = prov?.page_no;
     if (!isFiniteNumber(pageNo)) {
@@ -263,7 +261,7 @@ export function removeImagePlaceholders(markdown: string): string {
 }
 
 // -------------------------------------------------------------------
-// --- 4. Internal Functions
+// --- 4. Private Functions
 // -------------------------------------------------------------------
 
 /**

package/src/index.ts

@@ -8,6 +8,9 @@
 export type * from './document.js';
 export type {
     CallOptions,
+    CapabilityLimits,
+    CapabilityPreset,
+    CapabilityStage,
     ClientOptions,
     ConversionFailure,
     ConvertError,
@@ -17,6 +20,7 @@ export type {
     DoclingClient,
     DoclingConfig,
     DoclingOptions,
+    DoclingSettings,
     DocumentImageMode,
     DocumentJob,
     DocumentOptions,
@@ -27,24 +31,29 @@ export type {
     ImageSize,
     ImageWarning,
     Job,
+    JobRef,
     JobState,
     MarkdownImageMode,
     MarkdownJob,
     MarkdownJobOutput,
     MarkdownOptions,
     MarkdownWarning,
+    OcrEngine,
     PageImage,
     PageImageBox,
     PageImageWarning,
     PdfBackend,
     PdfInput,
     Pipeline,
+    PollOptions,
     Result,
+    ServerCapabilities,
     ServerDetails,
     ServerError,
     ServerVersions,
     ServerWarning,
     TaskFailure,
+    WithSettings,
 } from './types.js';
 
 // -------------------------------------------------------------------

package/src/options.ts

@@ -19,10 +19,11 @@ import type {
     DocumentImageMode,
     DocumentOptions,
     ImageOptions,
-    Job,
+    JobRef,
     MarkdownImageMode,
     MarkdownJobOutput,
     MarkdownOptions,
+    PollOptions,
     Result,
 } from './types.js';
 
@@ -44,10 +45,18 @@ export type ResolvedConfig = {
     fetch: typeof fetch;
     /** Time limit per request in ms; unset means no limit. */
     timeoutMs?: number;
+    /** Delay between job helper status polls in ms; defaults to `DEFAULT_POLL_MS`. */
+    pollMs: number;
     /** Factory defaults merged over `DEFAULT_OPTIONS`. */
     defaults: ResolvedOptions;
 };
 
+/** Validated poll settings for job helpers. */
+export type PollCall = {
+    pollMs: number;
+    signal?: AbortSignal;
+};
+
 /** Validated md call: server options, image handling and signal. */
 export type MarkdownCall = {
     options: ResolvedOptions;
@@ -89,6 +98,7 @@ export const DEFAULT_OPTIONS: Readonly<ResolvedOptions> = Object.freeze({
     pdfBackend: 'docling_parse',
     ocr: true,
     forceOcr: false,
+    ocrEngine: 'auto',
 });
 
 /** Rules for docling options, accepted by the factory and every conversion call. */
@@ -101,6 +111,7 @@ const CALL_OPTION_RULES: Record<keyof DoclingOptions, OptionRule> = {
     pdfBackend: (value) => isOneOf(value, PDF_BACKENDS),
     ocr: isBoolean,
     forceOcr: isBoolean,
+    ocrEngine: (value) => typeof value === 'string' && value !== '',
 };
 
 /** Rules for factory options: per-call options plus the factory-only ones. */
@@ -133,20 +144,42 @@ const IMAGE_OPTION_RULES: Record<keyof ImageOptions, OptionRule> = {
     omitSmall: isBoolean,
 };
 
-/** Rules for `check` options. */
+/** Rules for `check` and `capabilities` options. */
 const CHECK_RULES: Record<keyof CallOptions, OptionRule> = {
     signal: isAbortSignal,
 };
 
+/** Rules for `waitForJob` options. */
+const POLL_RULES: Record<keyof PollOptions, OptionRule> = {
+    ...CHECK_RULES,
+    pollMs: isTimerDelay,
+};
+
+/** Rules for `runMarkdown` options: md call options plus `pollMs`. */
+const RUN_MARKDOWN_RULES: Record<keyof (MarkdownOptions & PollOptions), OptionRule> = {
+    ...MARKDOWN_RULES,
+    ...POLL_RULES,
+};
+
+/** Rules for `runDocument` options: document call options plus `pollMs`. */
+const RUN_DOCUMENT_RULES: Record<keyof (DocumentOptions & PollOptions), OptionRule> = {
+    ...DOCUMENT_RULES,
+    ...POLL_RULES,
+};
+
 /** Rules for factory configuration; the keys of `options` are checked separately. */
 const CONFIG_RULES: Record<keyof DoclingConfig, OptionRule> = {
     baseUrl: isHttpUrl,
     apiKey: (value) => typeof value === 'string' && value !== '',
     fetch: (value) => typeof value === 'function',
-    timeoutMs: isPositiveNumber,
+    timeoutMs: isTimerDelay,
+    pollMs: isTimerDelay,
     options: isPlainObject,
 };
 
+/** Default delay in ms between job helper status polls. */
+const DEFAULT_POLL_MS = 10;
+
 /** Job id of word characters and `-` only, so it cannot leave the URL path segment. */
 const MATCH_JOB_ID = /^[\w-]+$/;
 
@@ -162,6 +195,9 @@ const MATCH_TRAILING_SLASHES = /\/+$/;
 /** Matches HTTP or HTTPS protocol schemes. */
 const MATCH_HTTP_PROTOCOL = /^https?:$/;
 
+/** Maximum timer delay in ms (2^31 - 1); Node timers overflow above this and fire after 1 ms. */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
 /** Error message for a missing or malformed job object. */
 const INVALID_JOB = 'Expected the job object returned by submitMarkdown() or submitDocument()';
 
@@ -179,7 +215,14 @@ export function resolveConfig(config: unknown): ResolvedConfig {
     if (!isPlainObject(config)) {
         throw new TypeError('Invalid config: expected an object');
     }
-    const { baseUrl, apiKey, fetch: fetchFn, timeoutMs, options } = validateKeys<DoclingConfig>(config, CONFIG_RULES);
+    const {
+        baseUrl,
+        apiKey,
+        fetch: fetchFn,
+        timeoutMs,
+        pollMs = DEFAULT_POLL_MS,
+        options,
+    } = validateKeys<DoclingConfig>(config, CONFIG_RULES);
     if (baseUrl === undefined) {
         throw new TypeError(invalidValue('baseUrl'));
     }
@@ -192,44 +235,83 @@ export function resolveConfig(config: unknown): ResolvedConfig {
         ...(apiKey === undefined ? {} : { apiKey }),
         fetch: fetchFn ?? fetch,
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        pollMs,
         defaults,
     };
 }
 
-/** Validates md call options over factory defaults; throws TypeError on invalid options. */
+/**
+ * Merges and validates md call options against factory defaults.
+ * @throws `TypeError` on invalid options.
+ */
 export function resolveMarkdownCall(defaults: Readonly<ResolvedOptions>, options: unknown): MarkdownCall {
-    const {
-        signal,
-        images = 'placeholder',
-        imageOptions,
-        ...docling
-    } = validateKeys<MarkdownOptions>(callObject(options), MARKDOWN_RULES);
-    const output = resolveImageOutput(images, imageOptions);
-    return { options: { ...defaults, ...docling }, output, ...(signal === undefined ? {} : { signal }) };
+    return toMarkdownCall(defaults, validateKeys<MarkdownOptions>(callObject(options), MARKDOWN_RULES));
 }
 
-/** Validates document call options over factory defaults; throws TypeError on invalid options. */
+/**
+ * Merges and validates document call options against factory defaults.
+ * @throws `TypeError` on invalid options.
+ */
 export function resolveDocumentCall(defaults: Readonly<ResolvedOptions>, options: unknown): DocumentCall {
-    const {
-        signal,
-        images = 'embedded',
-        pageImages = false,
-        ...docling
-    } = validateKeys<DocumentOptions>(callObject(options), DOCUMENT_RULES);
-    return { options: { ...defaults, ...docling }, images, pageImages, ...(signal === undefined ? {} : { signal }) };
+    return toDocumentCall(defaults, validateKeys<DocumentOptions>(callObject(options), DOCUMENT_RULES));
 }
 
-/** Validates `check` call options (signal only); throws TypeError on invalid options. */
+/**
+ * Merges md call options and poll settings; `pollMs` defaults to factory `pollMs`.
+ * @throws `TypeError` on invalid options.
+ */
+export function resolveRunMarkdownCall(
+    defaults: Readonly<ResolvedOptions>,
+    defaultPollMs: number,
+    options: unknown,
+): MarkdownCall & PollCall {
+    const { pollMs = defaultPollMs, ...call } = validateKeys<MarkdownOptions & PollOptions>(
+        callObject(options),
+        RUN_MARKDOWN_RULES,
+    );
+    return { ...toMarkdownCall(defaults, call), pollMs };
+}
+
+/**
+ * Merges document call options and poll settings; `pollMs` defaults to factory `pollMs`.
+ * @throws `TypeError` on invalid options.
+ */
+export function resolveRunDocumentCall(
+    defaults: Readonly<ResolvedOptions>,
+    defaultPollMs: number,
+    options: unknown,
+): DocumentCall & PollCall {
+    const { pollMs = defaultPollMs, ...call } = validateKeys<DocumentOptions & PollOptions>(
+        callObject(options),
+        RUN_DOCUMENT_RULES,
+    );
+    return { ...toDocumentCall(defaults, call), pollMs };
+}
+
+/**
+ * Checks signal-only call options (`check`, `capabilities`).
+ * @throws `TypeError` on invalid options.
+ */
 export function resolveCheckOptions(options: unknown): CallOptions {
     return validateKeys<CallOptions>(callObject(options), CHECK_RULES);
 }
 
+/**
+ * Checks `waitForJob` options; `pollMs` defaults to factory `pollMs`.
+ * @throws `TypeError` on invalid options.
+ */
+export function resolvePollOptions(defaultPollMs: number, options: unknown): PollCall {
+    const { pollMs = defaultPollMs, signal } = validateKeys<PollOptions>(callObject(options), POLL_RULES);
+    return { pollMs, ...(signal === undefined ? {} : { signal }) };
+}
+
 /**
  * **Checks a job object against the shape `submitMarkdown()` and `submitDocument()` return**.
  *
  * - never throws: a malformed job is `invalid_input`
+ * - `settings` and other extra keys are ignored and not returned
  */
-export function validateJob(job: unknown): Result<Job> {
+export function validateJob(job: unknown): Result<JobRef> {
     if (!isPlainObject(job) || !isJobId(job.id)) {
         return fail(ERR.INVALID_INPUT(INVALID_JOB));
     }
@@ -256,10 +338,13 @@ export function isJobId(value: unknown): value is string {
 }
 
 // -------------------------------------------------------------------
-// --- 4. Internal Functions
+// --- 4. Private Functions
 // -------------------------------------------------------------------
 
-/** Returns call options as a plain object (`undefined` becomes `{}`); throws TypeError otherwise. */
+/**
+ * Returns call options as a plain object (`undefined` becomes `{}`).
+ * @throws `TypeError` when options is not a plain object.
+ */
 function callObject(options: unknown): Record<string, unknown> {
     if (options === undefined) {
         return {};
@@ -270,6 +355,22 @@ function callObject(options: unknown): Record<string, unknown> {
     return options;
 }
 
+/**
+ * Splits validated md call options into server options over the defaults, image handling and signal.
+ * @throws `TypeError` on a missing, unexpected or invalid `imageOptions`.
+ */
+function toMarkdownCall(defaults: Readonly<ResolvedOptions>, options: Partial<MarkdownOptions>): MarkdownCall {
+    const { signal, images = 'placeholder', imageOptions, ...docling } = options;
+    const output = resolveImageOutput(images, imageOptions);
+    return { options: { ...defaults, ...docling }, output, ...(signal === undefined ? {} : { signal }) };
+}
+
+/** Splits validated document call options into server options over the defaults, image modes and signal. */
+function toDocumentCall(defaults: Readonly<ResolvedOptions>, options: Partial<DocumentOptions>): DocumentCall {
+    const { signal, images = 'embedded', pageImages = false, ...docling } = options;
+    return { options: { ...defaults, ...docling }, images, pageImages, ...(signal === undefined ? {} : { signal }) };
+}
+
 /**
  * **Combines image mode and image options into the md job output**.
  *
@@ -301,6 +402,11 @@ function isPositiveNumber(value: unknown): value is number {
     return typeof value === 'number' && Number.isFinite(value) && value > 0;
 }
 
+/** Integer ms from 1 to `MAX_TIMEOUT_MS`; `AbortSignal.timeout` throws on fractions, `setTimeout` overflows above. */
+function isTimerDelay(value: unknown): value is number {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= MAX_TIMEOUT_MS;
+}
+
 /** 1-based ascending integer pair `[from, to]`. */
 function isPageRange(value: unknown): value is [number, number] {
     return (
@@ -328,7 +434,16 @@ function isAbortSignal(value: unknown): value is AbortSignal {
     return value instanceof AbortSignal;
 }
 
-/** Parseable HTTP or HTTPS URL. */
+/**
+ * **HTTP or HTTPS URL that routes can be appended to**.
+ *
+ * - no `?` or `#`, even empty ones: `${baseUrl}${route}` would put the route into the query or fragment
+ * - no user name or password: Node's `fetch` refuses such URLs; the key belongs in `apiKey`
+ */
 function isHttpUrl(value: unknown): value is string {
-    return typeof value === 'string' && URL.canParse(value) && MATCH_HTTP_PROTOCOL.test(new URL(value).protocol);
+    if (typeof value !== 'string' || !URL.canParse(value) || value.includes('?') || value.includes('#')) {
+        return false;
+    }
+    const url = new URL(value);
+    return MATCH_HTTP_PROTOCOL.test(url.protocol) && url.username === '' && url.password === '';
 }

package/src/response.ts

@@ -135,7 +135,7 @@ export function readText(value: unknown): string | undefined {
 }
 
 // -------------------------------------------------------------------
-// --- 4. Internal Functions
+// --- 4. Private Functions
 // -------------------------------------------------------------------
 
 /**
@@ -212,7 +212,7 @@ function readServerError(error: DoclingErrorItem): ServerWarning[] {
     ];
 }
 
-/** docling `page_no`: integer >= 1; `0`, negatives and fractions are rejected. */
+/** Docling `page_no`: integer >= 1; 0, negatives and fractions are rejected. */
 function isPageNumber(value: unknown): value is number {
     return typeof value === 'number' && Number.isInteger(value) && value >= 1;
 }