docling-serve-client 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Martin Winkler
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,287 @@
-# Temporary Holding Version
+[![Test](https://github.com/martin-winkler-dev/docling-serve-client-js/actions/workflows/test.yml/badge.svg)](https://github.com/martin-winkler-dev/docling-serve-client-js/actions/workflows/test.yml)
+[![Package](https://github.com/martin-winkler-dev/docling-serve-client-js/actions/workflows/package.yml/badge.svg)](https://github.com/martin-winkler-dev/docling-serve-client-js/actions/workflows/package.yml)
+[![Bun](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmartin-winkler-dev%2Fdocling-serve-client-js%2Fmain%2Fpackage.json&query=%24.engines.bun&label=Bun&logo=bun&color=blue)](https://bun.sh)
+[![Node.js](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmartin-winkler-dev%2Fdocling-serve-client-js%2Fmain%2Fpackage.json&query=%24.engines.node&label=Node.js&logo=nodedotjs&color=blue)](https://nodejs.org)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# docling-serve-client
+
+Typed HTTP client for a running [docling-serve](https://github.com/docling-project/docling-serve): **PDF or image
+bytes in, docling's Markdown or DoclingDocument JSON out**.
+
+- Two outputs: `convertMarkdown` returns docling's Markdown unchanged except for image handling; `convertDocument`
+  returns the DoclingDocument (the JSON AST with labels, reading order, pages and bounding boxes) as docling sends it.
+- No cleanup, no heuristics on text. Repairs and analysis belong in the code that uses this client. The Markdown is
+  docling's raw output, e.g. with `&` entities, soft hyphens and dot leaders left in.
+- In-memory only: no file I/O, no streaming.
+- **Calls never throw on runtime failures.** Every call resolves to `{ ok: true, data } | { ok: false, error }`.
+  Two exceptions are programming errors: the factory throws a `TypeError` on an invalid config, and a call with an
+  invalid option throws a `TypeError` (the promise rejects) before it sends anything.
+- Sync (`convert*`) and async (`submit*` + `check`). No built-in polling, queueing or rate limiting.
+- Zero dependencies. ESM, works in Node ≥ 22.12 (also via `require()`) and Bun.
+
+## Usage
+
+```ts
+import { createDoclingClient } from 'docling-serve-client';
+
+const docling = createDoclingClient({ baseUrl: 'http://127.0.0.1:5001' });
+
+// Input is always a Uint8Array (Node Buffer is one): a PDF, or a PNG, JPEG, TIFF or WebP image
+const pdf = await readFile('paper.pdf');                                  // node:fs/promises
+// const pdf = await Bun.file('paper.pdf').bytes();                       // Bun
+// const pdf = new Uint8Array(await (await fetch(pdfUrl)).arrayBuffer()); // any download
+
+const md = await docling.convertMarkdown(pdf);
+if (md.ok) console.log(md.data.markdown, md.data.warnings);
+
+const doc = await docling.convertDocument(pdf);
+if (doc.ok) {
+    for (const item of doc.data.document.texts) {
+        if (item.label === 'section_header') console.log(item.level, item.text, item.prov[0]?.page_no);
+    }
+} else {
+    console.error(doc.error.code, doc.error.message);
+}
+```
+
+### Async
+
+`submitMarkdown()` and `submitDocument()` return a plain JSON job object. Store all of it and pass it back to
+`check()`. A Markdown job carries its image handling, so `check()` works the same from another process or after a
+restart. `check()` returns the result type that matches the job's `kind`.
+
+```ts
+const job = await docling.submitDocument(pdf);
+if (!job.ok) return handle(job.error);
+await save(JSON.stringify(job.data)); // { kind: 'document', id }
+
+// later, as often as you like:
+const state = await docling.check(JSON.parse(await load()));
+if (state.ok) {
+    switch (state.data.status) {
+        case 'queued':  /* state.data.position */ break;
+        case 'running': break;
+        case 'done':    use(state.data.document); break;
+    }
+}
+```
+
+docling-serve deletes a result `DOCLING_SERVE_RESULT_REMOVAL_DELAY` seconds (default 300) after its first fetch
+(`DOCLING_SERVE_SINGLE_USE_RESULTS=true`, the default). A `check()` whose result download failed (network error,
+`timeoutMs`, abort) can be repeated within that time; later `check()` returns `not_found` (`Result already fetched or
+expired`), so persist the `done` data. Start docling-serve with `DOCLING_SERVE_SINGLE_USE_RESULTS=false` to keep results
+until they expire. These are server settings; `convert*()` is not affected.
+
+### Options
+
+Set docling options on the factory and override them per call, key by key; `ocrLang`, `pageRange` and
+`documentTimeout` are factory-only and reject per call. Nothing is silently ignored or converted:
+an unknown option or an invalid value throws a `TypeError` at the start of the call, before any request
+(`Option "x" is not supported`, `Invalid value for option "x"`; nested keys are named like `imageOptions.prefix`).
+
+```ts
+const docling = createDoclingClient({
+    baseUrl: 'http://127.0.0.1:5001',
+    apiKey: '…',                        // only if docling-serve requires X-Api-Key
+    timeoutMs: 120_000,                 // optional limit per request; on expiry the call resolves with `aborted`
+    options: { ocrLang: ['de', 'en'] }, // docling defaults for every call
+    fetch: myFetch,                     // optional custom fetch
+});
+
+await docling.convertDocument(pdf, { ocr: false, images: 'placeholder', signal: AbortSignal.timeout(60_000) });
+```
+
+docling options (factory and per call):
+
+| option | default | effect |
+|---|---|---|
+| `headingHierarchy` | `true` | heading levels by bookmarks, numbering and font; `false` = every heading level 1 |
+| `formulaEnrichment` | `true` | formulas as LaTeX (extra model; runs only on formulas); without it formula `text` is empty and the md shows `<!-- formula-not-decoded -->` |
+| `codeEnrichment` | `false` | code listings via extra model (slower) |
+| `chartExtraction` | `false` | charts as data (vision model, slower) |
+| `pipeline` | `'standard'` | `'vlm'` runs a vision-language model per page (slow) |
+| `pdfBackend` | `'docling_parse'` | text extractor; `'pypdfium2'` reads ligatures and word spaces better but misses page headers and footers |
+| `ocr` | `true` | OCR bitmap content of PDFs (scans, pictures); image input is always OCRed |
+| `forceOcr` | `false` | OCR whole PDF pages and drop their text layer, for PDFs with broken text; ignored for image input |
+
+Factory only (`options` of `createDoclingClient`; per call they throw `Option "x" is not supported`). Use a second
+client for other values:
+
+| option | default | effect |
+|---|---|---|
+| `ocrLang` | engine default | BCP-47 hints in order of preference, e.g. `['de', 'en-US']`; `[]` = engine default |
+| `pageRange` | all pages | `[from, to]`, 1-based, inclusive |
+| `documentTimeout` | server default | server-side limit in seconds |
+
+Per call only: `signal` (cancels the request), `images`, for Markdown `imageOptions`, for documents `pageImages`.
+`timeoutMs` is a factory setting: it limits every request except `GET /version` and is combined with `signal`.
+
+Always on, not configurable: table structure with the accurate TableFormer model (`do_table_structure`,
+`table_mode: 'accurate'`), pictures and page images at 144 dpi (`images_scale=2`, exported as `PAGE_IMAGE_SCALE`)
+and, for Markdown, compact tables (`md_compact_tables`). The image scale does not affect OCR: docling OCRs at its own
+fixed 216 dpi.
+
+### Input formats
+
+The format is detected from the first bytes; anything else resolves to `invalid_input` without a request.
+
+| input | detected by | sent as |
+|---|---|---|
+| PDF | `%PDF-` within the first 1024 bytes | `from_formats=pdf`, `document.pdf` |
+| PNG, JPEG, TIFF, WebP | file signature at byte 0 | `from_formats=image`, `document.png` / `.jpg` / `.tiff` / `.webp` |
+
+An image is converted as one page: docling runs layout detection and OCR on it, and `ocrLang` applies. OCR is always
+on for images and never full-page: `ocr: false` would return no text, and `forceOcr: true` merges words (`stepsand`),
+so both are ignored for image input. Use it e.g. to re-read a crop of a page whose text layer is broken. Text only
+comes back if the server has a working OCR engine. PDF-only options (`pdfBackend`, `pageRange`) have no effect on
+images.
+
+### Images in the DoclingDocument
+
+| `images` | effect |
+|---|---|
+| `'embedded'` (default) | `pictures[].image.uri` is a `data:image/png;base64,…` URI; pictures keep their position, captions and size |
+| `'placeholder'` | `pictures[].image` is `null`; the picture items stay, the document is much smaller |
+
+The base64 data stays inside the document. Pull it out when you need files, e.g. when rendering Markdown from the
+document. `isSmallImage(picture.image.size)` applies the same size filter as `omitSmall` (see below).
+
+### Page images
+
+`pageImages: true` (documents only, default `false`) asks docling to render every page (`include_page_images`). The
+client moves them out of the document: `document.pages[n].image` is always `null`, so the JSON stays small, and the
+images come back decoded in `data.pageImages`, in page order:
+
+```ts
+const res = await docling.convertDocument(pdf, { pageImages: true, images: 'placeholder' });
+if (res.ok) {
+    await writeFile(`out/${docId}.json`, JSON.stringify(res.data.document)); // no page image data inside
+    for (const image of res.data.pageImages) {
+        await writeFile(`out/${docId}-p${image.page}.png`, image.bytes);   // { page, mimeType, width, height, dpi, bytes }
+    }
+}
+```
+
+- `page` is the 1-based PDF page (absolute, also with `pageRange`); `dpi` is always 144.
+- `width` and `height` are pixels from the PNG header, else docling's `image.size`. Pixel size = page size in points
+  × 2; an A4 page is about 1190 × 1684 px and 0.4 to 0.6 MB as PNG.
+- Page images are independent of `images`: `images: 'placeholder'` drops picture data and keeps page images.
+- Async: `submitDocument(pdf, { pageImages: true })` stores nothing extra in the job; `check()` returns the images.
+- A page image that is not a base64 data URI or has invalid or empty data is missing from `pageImages`, stays in
+  `document.pages[].image` as docling sent it, and is reported as a `page_image_not_decoded` warning (`details.page`).
+
+The document keeps docling's bboxes as sent: PDF points, mostly with a bottom-left origin. `toPageImageBox` maps one
+onto its page image as `{ page, x, y, width, height }` in pixels with a top-left origin (unrounded), ready to store
+next to the page image file or to crop with:
+
+```ts
+for (const item of res.data.document.texts) {
+    for (const prov of item.prov) {
+        const box = toPageImageBox(res.data.document, prov); // undefined if the page is missing
+    }
+}
+// table cells carry their own bbox (top-left origin) and the page of their table:
+const box = toPageImageBox(document, { page_no: table.prov[0].page_no, bbox: cell.bbox });
+```
+
+The boxes fit page images of any conversion by this client, also when `pageImages` was off.
+
+### Images in the Markdown
+
+| `images` | effect |
+|---|---|
+| `'placeholder'` (default) | `<!-- image -->` marks a picture, as docling writes it |
+| `'none'` | placeholders removed |
+| `'extract'` | pictures come back as bytes in `data.images`, linked as `<prefix><n>.<ext>` |
+
+With `'extract'`, `imageOptions` is required on each call, because the prefix names one document's images:
+
+```ts
+const res = await docling.convertMarkdown(pdf, {
+    images: 'extract',
+    imageOptions: { prefix: `images/${docId}-` }, // omitSmall: drop bullets, icons and small logos, default true
+});
+if (res.ok) {
+    await writeFile(`out/${docId}.md`, res.data.markdown);           // ![Image](images/1234-1.png)
+    for (const image of res.data.images) {
+        await writeFile(`out/${image.path}`, image.bytes);           // { path, mimeType, bytes, width, height }
+    }
+}
+```
+
+- `n` starts at 1 and counts kept images only. `<ext>` comes from the MIME type: `png`, `jpg`, `gif`, `webp`, `svg`,
+  `tiff`, `bmp`, otherwise `bin`.
+- `omitSmall` (default `true`) removes small pictures from the Markdown and does not return them. Small means: area
+  below 15 000 px, longer side below 200 px, or shorter side below 24 px (`isSmallImage`). Only PNGs have a known
+  size (`readPngSize`); other formats are always kept and report `width` and `height` as `0`.
+- A picture with invalid or empty base64 data is removed and reported as an `image_not_decoded` warning
+  (`details.index`: 1-based position among all embedded pictures); the conversion still succeeds.
+- A picture docling sent without image data keeps its `<!-- image -->` placeholder, as in `'placeholder'` mode.
+- Removing a picture or placeholder keeps the blank line that separates the paragraphs around it.
+
+### Warnings
+
+`data.warnings` lists non-fatal notes. The conversion still succeeded; decide yourself whether a warning matters.
+
+| code | `details` | meaning |
+|---|---|---|
+| `server` | `{ component, module, category, page }` | problem reported by docling-serve (e.g. a single page failed, `document timeout exceeded`); `page` is the 1-based PDF page, or `null` |
+| `image_not_decoded` | `{ index }` | Markdown with `images: 'extract'` only, see above |
+| `page_image_not_decoded` | `{ page }` | documents with `pageImages: true` only, see above |
+
+Pages docling gave up on (e.g. `documentTimeout` exceeded) have no content. The only sign is a `server` warning per
+failed page.
+
+### Server versions
+
+`data.versions` holds the versions the server reports on `GET /version`, unchanged, e.g.
+`{ 'docling-serve': '1.36.0', docling: '2.135.0', 'docling-core': '2.101.1', … }`, or `null` if it reports none.
+Store it with each converted document: the same PDF can convert differently under another docling version, and
+`document.version` is the DoclingDocument schema version. Errors from a request the server answered (`http`,
+`not_found`, `conversion_failed`, `invalid_response`) carry the same `error.versions`. Each client asks for the
+versions once and keeps them; the request has its own 2 s limit, and when it fails `versions` is `null` and the next
+result asks again. Create a new client after a server update.
+
+### Broken umlauts / special characters
+
+If the output shows `fŸhrt`, `Nu§baum`, `…sterreich`, the PDF's text layer uses an encoding docling-parse misreads
+(seen with `/MacRomanEncoding` PDFs from Mac Word). Re-convert that document with `{ forceOcr: true }` (with `ocrLang: ['de']` on the factory).
+It is slower, so use it per document, not by default.
+
+### Errors
+
+`error.code` is one of:
+
+| code | meaning |
+|---|---|
+| `invalid_input` | not a non-empty PDF, PNG, JPEG, TIFF or WebP `Uint8Array`, a truncated PDF (cross-reference offset past the end of the file), or not a job object from `submit*()`, or input that could not be prepared for upload (e.g. out of memory); no request sent |
+| `network` | server unreachable (the message includes the cause, e.g. `ECONNREFUSED`) |
+| `aborted` | your `signal` fired (incl. `AbortSignal.timeout()`) or `timeoutMs` expired |
+| `http` | non-2xx response (`error.status` set), e.g. auth, sync wait exceeded |
+| `not_found` | `check()`: `Unknown job id` (e.g. after a server restart), or `Result already fetched or expired`; the server's own message follows in parentheses |
+| `conversion_failed` | the server could not convert the document, also a `partial_success` (or a success with error items) that has no Markdown or DoclingDocument |
+| `invalid_response` | unexpected response body (no status, no Markdown or DoclingDocument without server details, a non-JSON body (quoted in the message), an unusable task id, or a body too large to read) |
+
+`conversion_failed` adds `error.details` as `{ errors, failure }`: `errors` lists docling's error items as
+`{ message, details }` (component, module, category, page); `failure` is docling's task classification
+`{ category, phase, retryable }` for async jobs, or `null`.
+
+## Development
+
+### Running docling-serve (CUDA)
+
+```bash
+# Install or reinstall docling-serve with CUDA 12.6
+uv tool install --reinstall --torch-backend cu126 docling-serve
+
+# Start the server on port 5001
+docling-serve run --port 5001
+```
+
+```bash
+bun install
+bun runtest check -p tsconfig.test.json   # lint fixes, typecheck, lint, unit tests against a mock docling server
+bun run test:e2e                          # end-to-end tests against docling-serve on :5001; fail if it is down
+bun run check                             # lint, tests, build, smoke tests on the built package, package check
+```

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+import type { DoclingClient, DoclingConfig } from './types.js';
+/**
+ * **docling-serve client factory**.
+ *
+ * - validates configuration once; its only state is the cached server versions
+ * - returned functions resolve to `Result`; invalid options reject with a `TypeError` before any request
+ * - `timeoutMs` limits every request except `/version`, which has its own limit
+ * @throws `TypeError` on invalid configuration.
+ */
+export declare function createDoclingClient(config: DoclingConfig): DoclingClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAKR,aAAa,EACb,aAAa,EAOhB,MAAM,YAAY,CAAC;AAyDpB;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CA+NxE"}

package/dist/core/http.d.ts

@@ -0,0 +1,12 @@
+import type { Result } from '../types.js';
+/**
+ * **Executes `fetch` and parses the JSON body into a `Result`**.
+ *
+ * - non-2xx: `http` with FastAPI `detail`; unparsable 2xx body: `invalid_response`
+ * - body too large for a string or for memory: `invalid_response`, as a retry fails the same way
+ * - aborted signal: `aborted`; anything else thrown: `network`
+ */
+export declare function fetchJson(fetchFn: typeof fetch, url: string, init: RequestInit): Promise<Result<unknown>>;
+/** Extracts message, appending `cause.message` if present. */
+export declare function errorMessage(e: unknown): string;
+//# sourceMappingURL=http.d.ts.map

package/dist/core/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/core/http.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAuB1C;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAmB/G;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAK/C"}

package/dist/core/input.d.ts

@@ -0,0 +1,18 @@
+/** Detected input format and how it is sent to docling-serve. */
+export type InputFormat = {
+    /** docling's `from_formats` value. */
+    fromFormat: 'pdf' | 'image';
+    /** MIME type of the multipart file part. */
+    mimeType: string;
+    /** File name of the multipart file part; docling reads the format from its extension. */
+    fileName: string;
+};
+/**
+ * **Detects the input format by magic bytes**.
+ *
+ * - image signatures must start at byte 0; PDF: `%PDF-` within the first 1024 bytes
+ * - images are checked first, so an image whose data happens to contain `%PDF-` is still an image
+ * @returns `undefined` for empty, non-`Uint8Array` or unrecognized input
+ */
+export declare function detectInputFormat(bytes: unknown): InputFormat | undefined;
+//# sourceMappingURL=input.d.ts.map

package/dist/core/input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/core/input.ts"],"names":[],"mappings":"AASA,iEAAiE;AACjE,MAAM,MAAM,WAAW,GAAG;IACtB,sCAAsC;IACtC,UAAU,EAAE,KAAK,GAAG,OAAO,CAAC;IAC5B,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;CACpB,CAAC;AAuCF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAWzE"}

package/dist/core/pdf.d.ts

@@ -0,0 +1,11 @@
+/** Matches a `%PDF-` header starting within the first 1024 bytes. */
+export declare function isPdf(bytes: unknown): bytes is Uint8Array;
+/**
+ * **Returns cross-reference offset if PDF is truncated**: last 'startxref' points at or past EOF.
+ *
+ * - typical for aborted downloads; docling then fails with a vague load error
+ * - only the last 2 KB are read, as latin1
+ * - returns 'undefined' when offset lies inside file or no 'startxref' found
+ */
+export declare function findTruncatedXref(bytes: Uint8Array): number | undefined;
+//# sourceMappingURL=pdf.d.ts.map

package/dist/core/pdf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdf.d.ts","sourceRoot":"","sources":["../../src/core/pdf.ts"],"names":[],"mappings":"AAoBA,qEAAqE;AACrE,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAkBzD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAKvE"}

package/dist/core/result.d.ts

@@ -0,0 +1,54 @@
+import type { ConversionFailure, ConvertError, Result } from '../types.js';
+/** Error code union inferred from `ERR`. */
+export type ErrorCode = ReturnType<(typeof ERR)[keyof typeof ERR]>['code'];
+/** Error factories keyed by domain error code. */
+export declare const ERR: {
+    /** Input rejected before request: not a valid PDF `Uint8Array`, or invalid job object. */
+    INVALID_INPUT: (message: string) => {
+        code: 'invalid_input';
+        message: string;
+    };
+    /** Server unreachable (connection refused, DNS, socket reset). */
+    NETWORK: (message: string) => {
+        code: 'network';
+        message: string;
+    };
+    /** Caller `AbortSignal` or `timeoutMs` fired (including `AbortSignal.timeout()`). */
+    ABORTED: (message: string) => {
+        code: 'aborted';
+        message: string;
+    };
+    /** Non-2xx response (bad options, auth, 5xx, sync wait exceeded). */
+    HTTP: (status: number, detail: string) => {
+        code: 'http';
+        message: string;
+        status: number;
+    };
+    /** Job ID unknown to server: expired, restarted, or nonexistent. */
+    NOT_FOUND: (message: string) => {
+        code: 'not_found';
+        message: string;
+        status: number;
+    };
+    /** Document processing failed (corrupt PDF, model failure); `details` holds what the server reported. */
+    CONVERSION_FAILED: (reason: string, details: ConversionFailure) => {
+        code: 'conversion_failed';
+        message: string;
+        details: ConversionFailure;
+    };
+    /** Server answered 2xx with unexpected response body. */
+    INVALID_RESPONSE: (message: string, status?: number) => {
+        code: 'invalid_response';
+        message: string;
+        status?: never;
+    } | {
+        code: 'invalid_response';
+        message: string;
+        status: number;
+    };
+};
+/** Wraps value in `{ ok: true, data }`. */
+export declare function ok<T>(data: T): Result<T>;
+/** Wraps error in `{ ok: false, error }`. */
+export declare function fail<T = never>(error: ConvertError): Result<T>;
+//# sourceMappingURL=result.d.ts.map

package/dist/core/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/core/result.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAM3E,4CAA4C;AAC5C,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAM3E,kDAAkD;AAClD,eAAO,MAAM,GAAG;IACZ,0FAA0F;6BACjE,MAAM;cAAc,eAAe;;;IAC5D,kEAAkE;uBAC/C,MAAM;cAAc,SAAS;;;IAChD,qFAAqF;uBAClE,MAAM;cAAc,SAAS;;;IAChD,qEAAqE;mBACtD,MAAM,UAAU,MAAM;cAAc,MAAM;;;;IACzD,oEAAoE;yBAC/C,MAAM;cAAc,WAAW;;;;IACpD,yGAAyG;gCAC7E,MAAM,WAAW,iBAAiB;cACpD,mBAAmB;;;;IAI7B,yDAAyD;gCAC7B,MAAM,WAAW,MAAM;cAEjC,kBAAkB;;;;cAClB,kBAAkB;;;;CACvC,CAAC;AAMF,2CAA2C;AAC3C,wBAAgB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAExC;AAED,6CAA6C;AAC7C,wBAAgB,IAAI,CAAC,CAAC,GAAG,KAAK,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CAAC,CAAC,CAAC,CAE9D"}

package/dist/core/validate.d.ts

@@ -0,0 +1,29 @@
+/** Accepts or rejects one option value. */
+export type OptionRule = (value: unknown) => boolean;
+/** Error message when options argument is provided but is not a plain object. */
+export declare const OPTIONS_OBJECT_EXPECTED = "Invalid options: expected an object";
+/**
+ * **Checks every key of `input` against its rule**.
+ *
+ * - unsupported options throw `TypeError` even if their value is `undefined`
+ * - `undefined` values for supported options are skipped, as if the key were missing
+ * - arrays are copied, so later changes by the caller do not reach the resolved options
+ * - `namePrefix` names nested options in messages, e.g. `imageOptions.`
+ * @throws `TypeError` on unsupported option or invalid value.
+ */
+export declare function validateKeys<T extends object>(input: Record<string, unknown>, rules: Record<keyof T, OptionRule>, namePrefix?: string): Partial<T>;
+/** Formats error message for an unsupported option. */
+export declare function notSupported(name: string): string;
+/** Formats error message for a rejected option value. */
+export declare function invalidValue(name: string): string;
+/**
+ * **Object literal, `JSON.parse` result or `Object.create(null)`**.
+ *
+ * - rejects arrays, `Map`, `Date`, class instances and objects from another realm
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** Checks whether value is a boolean primitive. */
+export declare function isBoolean(value: unknown): value is boolean;
+/** Type guard checking whether string is included in allowed set. */
+export declare function isOneOf<T extends string>(value: unknown, allowed: readonly T[]): value is T;
+//# sourceMappingURL=validate.d.ts.map