docling-serve-client 0.5.0 → 0.6.0

package/src/images.ts

@@ -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)) {
-            // Marker, so removing it below also normalizes surrounding blank lines.
             output += OMITTED_IMAGE;
             continue;
         }
@@ -263,7 +261,7 @@ export function removeImagePlaceholders(markdown: string): string {
 }
 
 // -------------------------------------------------------------------
-// --- 4. Internal Functions
+// --- 4. Private Functions
 // -------------------------------------------------------------------
 
 /**

package/src/index.ts

@@ -45,6 +45,7 @@ export type {
     PdfBackend,
     PdfInput,
     Pipeline,
+    PollOptions,
     Result,
     ServerCapabilities,
     ServerDetails,

package/src/options.ts

@@ -23,6 +23,7 @@ import type {
     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;
@@ -102,7 +111,6 @@ const CALL_OPTION_RULES: Record<keyof DoclingOptions, OptionRule> = {
     pdfBackend: (value) => isOneOf(value, PDF_BACKENDS),
     ocr: isBoolean,
     forceOcr: isBoolean,
-    // Open list: presets depend on server installation, unknown IDs are left to server.
     ocrEngine: (value) => typeof value === 'string' && value !== '',
 };
 
@@ -141,15 +149,37 @@ 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-]+$/;
 
@@ -165,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()';
 
@@ -182,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'));
     }
@@ -195,47 +235,76 @@ export function resolveConfig(config: unknown): ResolvedConfig {
         ...(apiKey === undefined ? {} : { apiKey }),
         fetch: fetchFn ?? fetch,
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        pollMs,
         defaults,
     };
 }
 
 /**
- * Validates md call options over factory defaults.
+ * 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.
+ * 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));
+}
+
+/**
+ * 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 };
 }
 
 /**
- * Validates signal-only call options (`check`, `capabilities`).
+ * 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**.
  *
@@ -269,7 +338,7 @@ export function isJobId(value: unknown): value is string {
 }
 
 // -------------------------------------------------------------------
-// --- 4. Internal Functions
+// --- 4. Private Functions
 // -------------------------------------------------------------------
 
 /**
@@ -286,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**.
  *
@@ -317,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 (
@@ -344,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
 // -------------------------------------------------------------------
 
 /**

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,10 +101,7 @@ export type ServerVersions = Record<string, string>;
  */
 export type ConvertInput = Uint8Array;
 
-/**
- * Use `ConvertInput`; images are accepted as well.
- * @deprecated
- */
+/** Deprecated: use `ConvertInput`; images are accepted as well. */
 export type PdfInput = ConvertInput;
 
 /** Supported conversion pipeline backend. */
@@ -146,6 +141,7 @@ 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;
@@ -169,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**.
  *
@@ -213,9 +220,7 @@ export type DocumentOptions = DoclingOptions &
         pageImages?: boolean;
     };
 
-// -------------------------------------------------------------------
-// --- 3. Outputs
-// -------------------------------------------------------------------
+// Outputs
 
 /** Pixel dimensions of an image. */
 export type ImageSize = {
@@ -359,14 +364,12 @@ export type DoclingSettings = {
     abortOnError: boolean;
 };
 
-/** Sync conversion result plus the settings sent with its request. */
+/** Result of `convert*` and `run*` plus the settings sent with the conversion. */
 export type WithSettings<T> = T & {
     settings: DoclingSettings;
 };
 
-// -------------------------------------------------------------------
-// --- 4. Asynchronous Jobs
-// -------------------------------------------------------------------
+// Asynchronous Jobs
 
 /** Image handling of a md job, applied when `check()` picks up the result. */
 export type MarkdownJobOutput =
@@ -407,9 +410,7 @@ export type JobState<T> =
     /** Completed; carries the conversion result. */
     | ({ status: 'done' } & T);
 
-// -------------------------------------------------------------------
-// --- 5. Server Capabilities
-// -------------------------------------------------------------------
+// Server Capabilities
 
 /** Model or engine preset a pipeline stage offers; `id` is the value of the stage's form field. */
 export type CapabilityPreset = {
@@ -464,18 +465,18 @@ export type ServerCapabilities = {
     };
 };
 
-// -------------------------------------------------------------------
-// --- 6. Client
-// -------------------------------------------------------------------
+// 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. */
@@ -483,10 +484,12 @@ 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. */
@@ -500,14 +503,46 @@ export type DoclingClient = {
     /**
      * **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`
-     * - `done` carries no settings: they are on the job
+     * - 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)
+     */
+    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>>;
 };