From ffb0826c4e5de544dce1d01b8ebf99b78bc62a46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ianar=C3=A9=20S=C3=A9vi?= Date: Wed, 6 May 2026 18:44:05 +0200 Subject: [PATCH 1/4] :sparkles: add SKILL.md --- SKILL.md | 375 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 375 insertions(+) create mode 100644 SKILL.md diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 00000000..4ee6e705 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,375 @@ +name: mindee-v2-node.js +description: Official Node.js SDK for the Mindee API v2. + +# Mindee API – Node.js SDK Skill Guide + +## Overview + +The `mindee` npm package is the official Node.js client library for the +[Mindee API](https://app.mindee.com). It lets you send documents (PDFs, images, +URLs) to Mindee's AI-powered document-processing platform and get back +structured, machine-readable data. + +This guide covers **API v2**, the current generation of the Mindee platform. + +Key capabilities exposed by the library: + +- **Extraction** – pull structured fields out of any document type using a + model you configure in the Mindee console. +- **Classification** – route documents to the right workflow by categorizing + them automatically. +- **OCR** – retrieve the full plain-text content of a document. +- **Crop** – detect and isolate sub-regions of interest within a page. +- **Split** – segment a multi-page document into logical sub-documents. + +All operations are asynchronous. There are two ways to retrieve results: + +- **Polling** – submit a document and let the library poll the queue until the + result is ready, then return it to you in one call. +- **Webhooks** – submit a document and have Mindee push the result directly to + your endpoint when processing is complete, with no polling on your side. + +## Requirements + +### Node.js + +Node.js **20.1 or later** is required. + +### API Key + +You need a Mindee API key. + +Refer to the [API Keys documentation](https://docs.mindee.com/integrations/api-keys) for instructions on creating one. + +## Installation + +Install the package via npm: + +```bash +npm install mindee +``` + +Optional dependencies are included by default. They enable additional features: + +| Feature | Package(s) | +|----------------------------------|-----------------------------------------| +| PDF manipulation & compression | `@cantoo/pdf-lib`, `node-poppler` | +| PDF text extraction | `pdf.js-extract` | +| Image compression | `sharp` | + +To skip them for a lighter install: + +```bash +npm install mindee --omit=optional +``` + +## Getting Started + +### Creating a Client + +All interactions with the Mindee API go through the `Client` class. Instantiate +it with your API key: + +```typescript +import * as mindee from "mindee"; + +const mindeeClient = new mindee.Client({ apiKey: "MY_API_KEY" }); +``` + +### Client Options + +The constructor accepts an optional `ClientOptions` object: + +| Option | Type | Default | Description | +|--------------|--------------|-------------|--------------------------------------------------| +| `apiKey` | `string` | `undefined` | Your Mindee API key. | +| `debug` | `boolean` | `false` | Enable debug-level logging. | +| `dispatcher` | `Dispatcher` | `undefined` | Custom `undici` dispatcher (e.g. for proxy use). | + +### API Key via Environment Variable + +Instead of hardcoding the key, you can set the `MINDEE_V2_API_KEY` environment +variable and omit `apiKey` from the constructor entirely: + +```bash +export MINDEE_V2_API_KEY="MY_API_KEY" +``` + +Then in your code: + +```typescript +import * as mindee from "mindee"; + +const mindeeClient = new mindee.Client(); +``` + +## Loading an Input Document + +Before sending a document to the API, wrap it in one of the input source +classes exported from the `mindee` package. All input sources are passed +directly to the client methods — you never need to call `init()` manually. + +### File Path + +The most common option. Pass a path string to the file on disk: + +```typescript +const filePath = "/path/to/the/file.ext"; +const inputSource = new mindee.PathInput({ inputPath: filePath }); +``` + +### Buffer + +Use when you already have the file contents in memory as a Node.js `Buffer`. +A filename (with extension) is required: + +```typescript +const buffer = Buffer.from( + await fs.promises.readFile("/path/to/the/file.ext") +); + +const inputSource = new mindee.BufferInput({ + buffer: buffer, + filename: "file.ext", +}); +``` + +### Base64 String + +Use when the file is provided as a Base64-encoded string, e.g. from a web upload or an external API. +A filename (with extension) is required: + +```typescript +const b64String = "iVBORw0KGgoAAAANSUhEUgAAABgAAA ..."; + +const inputSource = new mindee.Base64Input({ + inputString: b64String, + filename: "base64_file.txt", +}); +``` + +### Bytes (Uint8Array) + +Use when the file content is available as raw bytes. +A filename (with extension) is required: + +```typescript +const inputBytes = new Uint8Array( + await fs.promises.readFile("/path/to/the/file.ext") +); + +const inputSource = new mindee.BytesInput({ + inputBytes: inputBytes, + filename: "file.ext", +}); +``` + +### Readable Stream + +Use when reading from a Node.js `Readable` stream. +A filename (with extension) is required: + +```typescript +const stream = fs.createReadStream("/path/to/the/file.ext"); + +const inputSource = new mindee.StreamInput({ + inputStream: stream, + filename: "file.ext", +}); +``` + +### Remote URL + +Use to pass an HTTPS URL directly to the Mindee API without downloading the file locally first. +Only HTTPS URLs are accepted: +```typescript +const inputSource = new mindee.UrlInput({ url: "https://example.com/file.ext" }); +``` + +## Choosing a Product + +A product class tells the client which Mindee AI pipeline to use. All product +classes are exported from the `mindee` package under the `product` namespace. + +| Product class | Import | Use case | +|------------------|---------------------------------|----------------------------------------------------------------| +| `Extraction` | `mindee.product.Extraction` | Pull structured fields from any document using a custom model. | +| `Classification` | `mindee.product.Classification` | Sort documents into categories. | +| `Ocr` | `mindee.product.Ocr` | Extract raw text from any image or scanned document. | +| `Crop` | `mindee.product.Crop` | Detect and isolate document borders on each page. | +| `Split` | `mindee.product.Split` | Break a multi-page file into separate logical documents. | + +The product class is passed as the first argument to all client methods. You +never instantiate it directly: + +```typescript +import * as mindee from "mindee"; + +const response = await mindeeClient.enqueueAndGetResult( + mindee.product.Extraction, // <-- product class + inputSource, + params, +); +``` + +## Sending a Request + +The simplest way to get started is to use the built-in polling functionality of the library. + +### Parameters + +Every request requires a `params` object. At minimum, `modelId` must be set. +The `modelId` is the ID of the model you configured in the Mindee console: + +```typescript +const params = { + modelId: "MY_MODEL_ID", +}; +``` + +For `Extraction`, additional options are available: + +```typescript +const params = { + modelId: "MY_MODEL_ID", + + // Options: set to `true` or `false` to override defaults + + // Enhance extraction accuracy with Retrieval-Augmented Generation. + rag: undefined, + // Extract the full text content from the document as strings. + rawText: undefined, + // Calculate bounding box polygons for all fields. + polygon: undefined, + // Calculate confidence scores for all fields. + confidence: undefined, +}; +``` + +### All-in-One: `enqueueAndGetResult()` + +The simplest way to process a document. +The library enqueues the document, polls until the result is ready, and returns it: + +```typescript +import * as mindee from "mindee"; + +const apiKey = "MY_API_KEY"; +const filePath = "/path/to/the/file.ext"; +const modelId = "MY_MODEL_ID"; + +// Init a new client +const mindeeClient = new mindee.Client({ apiKey: apiKey }); + +// Set product parameters +const params = { + modelId: modelId, +}; + +// Load a file from disk +const inputSource = new mindee.PathInput({ inputPath: filePath }); + +// Send for processing and wait for the result +// Replace mindee.product.Extraction with any other product: +// mindee.product.Classification, mindee.product.Ocr, mindee.product.Crop, mindee.product.Split +const response = await mindeeClient.enqueueAndGetResult( + mindee.product.Extraction, + inputSource, + params, +); + +// Print a string summary +console.log(response.inference.toString()); +``` + +## Sending a Request Using Webhooks + +The document is enqueued and Mindee will call your webhook URL when processing is complete, no polling required on your side. + +### Requirements + +You must have configured a webhook in the Mindee platform, and have its ID available. + +Refer to the [Webhook Documentation](https://docs.mindee.com/integrations/webhooks) for instructions on creating one. + +### Parameters + +Every request requires a `params` object. At minimum, `modelId` must be set. +Pass the webhook ID in the `params` object: + +```typescript +import * as mindee from "mindee"; + +const apiKey = "MY_API_KEY"; +const filePath = "/path/to/the/file.ext"; +const modelId = "MY_MODEL_ID"; +const webhookId = "MY_WEBHOOK_ID"; + +// Init a new client +const mindeeClient = new mindee.Client({ apiKey: apiKey }); + +// Set product parameters, including the webhook ID +const params = { + modelId: modelId, + webhookIds: [webhookId], +}; + +// Load a file from disk +const inputSource = new mindee.PathInput({ inputPath: filePath }); + +// Enqueue the document — the result will be delivered to your webhook +// Replace mindee.product.Extraction with any other product: +// mindee.product.Classification, mindee.product.Ocr, mindee.product.Crop, mindee.product.Split +const jobResponse = await mindeeClient.enqueue( + mindee.product.Extraction, + inputSource, + params, +); + +// Save the job ID, you can use it to check status if the webhook doesn't arrive +const jobId = jobResponse.job.id; +console.log(`Enqueued with job ID: ${jobId}`); +``` + +> **Tip:** Persist the jobId in your database alongside your own record for this document. +> If the webhook callback never arrives (e.g. due to a network issue or a misconfigured endpoint), +> you can use it to check the job status at any time: +> ```typescript +> const jobResponse = await mindeeClient.getJob(jobId); +> console.log(`Job status: ${jobResponse.job.status}`); +> // Possible statuses: "Processing", "Processed", "Failed" +>``` + +When Mindee calls your webhook, the raw JSON string body of the HTTP request can be deserialized using `LocalResponse`: + +```typescript +import * as mindee from "mindee"; + +// `rawPayload` is the raw JSON string body received by your webhook handler +const localResponse = new mindee.v2.LocalResponse(rawPayload); +await localResponse.init(); + +// Pass the response class matching the product used when enqueuing. +// Replace ExtractionResponse with whichever product applies: +// - mindee.product.ClassificationResponse +// - mindee.product.OcrResponse +// - mindee.product.CropResponse +// - mindee.product.SplitResponse +const response = await localResponse.deserializeResponse( + mindee.product.ExtractionResponse, +); + +console.log(response.inference.toString()); +``` + +You can also verify the HMAC signature of the webhook payload to ensure it genuinely came from Mindee: + +```typescript +const secretKey = "MY_WEBHOOK_SECRET_KEY"; +// You'll need to get the "X-Signature" custom HTTP header. +const hmacSignature = request.headers.get("X-Signature"); + +if (!localResponse.isValidHmacSignature(secretKey, hmacSignature)) { + throw new Error("Bad HMAC signature! Is someone trying to do evil?"); +} +``` From 30efc05aed391b9a019f4af8688f0625a2cf9eb3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ianar=C3=A9=20S=C3=A9vi?= Date: Thu, 7 May 2026 11:03:13 +0200 Subject: [PATCH 2/4] add polling options --- SKILL.md | 44 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 40 insertions(+), 4 deletions(-) diff --git a/SKILL.md b/SKILL.md index 4ee6e705..6b2bb22e 100644 --- a/SKILL.md +++ b/SKILL.md @@ -15,7 +15,7 @@ This guide covers **API v2**, the current generation of the Mindee platform. Key capabilities exposed by the library: - **Extraction** – pull structured fields out of any document type using a - model you configure in the Mindee console. + model you configure in the Mindee platform. - **Classification** – route documents to the right workflow by categorizing them automatically. - **OCR** – retrieve the full plain-text content of a document. @@ -219,7 +219,7 @@ The simplest way to get started is to use the built-in polling functionality of ### Parameters Every request requires a `params` object. At minimum, `modelId` must be set. -The `modelId` is the ID of the model you configured in the Mindee console: +The `modelId` is the ID of the model you configured in the Mindee platform: ```typescript const params = { @@ -227,7 +227,7 @@ const params = { }; ``` -For `Extraction`, additional options are available: +For `Extraction` only, additional options are available: ```typescript const params = { @@ -246,6 +246,8 @@ const params = { }; ``` +Other products only take `modelId`. + ### All-in-One: `enqueueAndGetResult()` The simplest way to process a document. @@ -271,7 +273,10 @@ const inputSource = new mindee.PathInput({ inputPath: filePath }); // Send for processing and wait for the result // Replace mindee.product.Extraction with any other product: -// mindee.product.Classification, mindee.product.Ocr, mindee.product.Crop, mindee.product.Split +// mindee.product.Classification +// mindee.product.Ocr +// mindee.product.Crop +// mindee.product.Split const response = await mindeeClient.enqueueAndGetResult( mindee.product.Extraction, inputSource, @@ -282,6 +287,37 @@ const response = await mindeeClient.enqueueAndGetResult( console.log(response.inference.toString()); ``` +### Configuring Polling Timings + +By default, `enqueueAndGetResult()` uses these polling settings: + +| Option | Default | Description | +|--------------------|---------|-----------------------------------------------------------| +| `initialDelaySec` | `2` | Seconds to wait before the **first** poll attempt. | +| `delaySec` | `1.5` | Seconds to wait between each **subsequent** poll attempt. | +| `maxRetries` | `80` | Maximum number of polling attempts | + +If you are consistently having timeout issues, you may need to adjust these values. + +Pass a `PollingOptions` object as the optional fourth argument to override any of these values: + +```typescript +const pollingOptions = { + initialDelaySec: 4, // wait 4 s before the first poll (default: 2) + delaySec: 1, // wait 1 s between subsequent polls (default: 1.5) + maxRetries: 100, // give up after 100 attempts (default: 80) +}; + +const response = await mindeeClient.enqueueAndGetResult( + mindee.product.Extraction, + inputSource, + params, + pollingOptions, +); + +console.log(response.inference.toString()); +``` + ## Sending a Request Using Webhooks The document is enqueued and Mindee will call your webhook URL when processing is complete, no polling required on your side. From e5fe99002cccf29a878701ccb7b1c0a116462bf9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ianar=C3=A9=20S=C3=A9vi?= Date: Thu, 7 May 2026 13:02:57 +0200 Subject: [PATCH 3/4] formatting, add ask using GET --- SKILL.md | 155 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 86 insertions(+), 69 deletions(-) diff --git a/SKILL.md b/SKILL.md index 6b2bb22e..542c617b 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,33 +1,28 @@ name: mindee-v2-node.js -description: Official Node.js SDK for the Mindee API v2. +description: Official Node.js client library for the Mindee API v2. -# Mindee API – Node.js SDK Skill Guide +# Mindee API – Node.js Client Library Skill Guide ## Overview The `mindee` npm package is the official Node.js client library for the -[Mindee API](https://app.mindee.com). It lets you send documents (PDFs, images, -URLs) to Mindee's AI-powered document-processing platform and get back -structured, machine-readable data. +[Mindee API](https://app.mindee.com). +It lets you send documents (PDFs, images, URLs) to Mindee's AI-powered document-processing platform and get back structured, machine-readable data. This guide covers **API v2**, the current generation of the Mindee platform. Key capabilities exposed by the library: -- **Extraction** – pull structured fields out of any document type using a - model you configure in the Mindee platform. -- **Classification** – route documents to the right workflow by categorizing - them automatically. +- **Extraction** – pull structured fields out of any document type using a model you configure in the Mindee platform. +- **Classification** – route documents to the right workflow by categorizing them automatically. - **OCR** – retrieve the full plain-text content of a document. - **Crop** – detect and isolate sub-regions of interest within a page. - **Split** – segment a multi-page document into logical sub-documents. All operations are asynchronous. There are two ways to retrieve results: -- **Polling** – submit a document and let the library poll the queue until the - result is ready, then return it to you in one call. -- **Webhooks** – submit a document and have Mindee push the result directly to - your endpoint when processing is complete, with no polling on your side. +- **Polling** – submit a document and let the library poll the queue until the result is ready, then return it to you in one call. +- **Webhooks** – submit a document and have Mindee push the result directly to your endpoint when processing is complete, with no polling on your side. ## Requirements @@ -67,8 +62,8 @@ npm install mindee --omit=optional ### Creating a Client -All interactions with the Mindee API go through the `Client` class. Instantiate -it with your API key: +All interactions with the Mindee API go through the `Client` class. +Instantiate it with your API key: ```typescript import * as mindee from "mindee"; @@ -88,14 +83,13 @@ The constructor accepts an optional `ClientOptions` object: ### API Key via Environment Variable -Instead of hardcoding the key, you can set the `MINDEE_V2_API_KEY` environment -variable and omit `apiKey` from the constructor entirely: +Instead of hardcoding the key, you can set the `MINDEE_V2_API_KEY` environment variable: ```bash export MINDEE_V2_API_KEY="MY_API_KEY" ``` -Then in your code: +Then in your code simply ommit the `apiKey` from the constructor: ```typescript import * as mindee from "mindee"; @@ -105,9 +99,8 @@ const mindeeClient = new mindee.Client(); ## Loading an Input Document -Before sending a document to the API, wrap it in one of the input source -classes exported from the `mindee` package. All input sources are passed -directly to the client methods — you never need to call `init()` manually. +Before sending a document to the API, wrap it in one of the input source classes exported from the `mindee` package. +All input sources are then passed directly to various methods, mostly in the client. ### File Path @@ -186,36 +179,30 @@ Only HTTPS URLs are accepted: const inputSource = new mindee.UrlInput({ url: "https://example.com/file.ext" }); ``` -## Choosing a Product +## Available Products -A product class tells the client which Mindee AI pipeline to use. All product -classes are exported from the `mindee` package under the `product` namespace. +Mindee has several products that can be used to process files. +Each product is designed for a specific use case and has its own set of features and parameters. -| Product class | Import | Use case | -|------------------|---------------------------------|----------------------------------------------------------------| -| `Extraction` | `mindee.product.Extraction` | Pull structured fields from any document using a custom model. | -| `Classification` | `mindee.product.Classification` | Sort documents into categories. | -| `Ocr` | `mindee.product.Ocr` | Extract raw text from any image or scanned document. | -| `Crop` | `mindee.product.Crop` | Detect and isolate document borders on each page. | -| `Split` | `mindee.product.Split` | Break a multi-page file into separate logical documents. | +Products are defined in the library by a class in the `mindee.product` namespace. +The product class is often passed as an argument to methods dealing with sending requests and processing server responses. -The product class is passed as the first argument to all client methods. You -never instantiate it directly: - -```typescript -import * as mindee from "mindee"; - -const response = await mindeeClient.enqueueAndGetResult( - mindee.product.Extraction, // <-- product class - inputSource, - params, -); -``` +| Product class | Import | Use case | +|------------------|---------------------------------|----------------------------------------------------------| +| `Extraction` | `mindee.product.Extraction` | Extract structured fields from any document. | +| `Classification` | `mindee.product.Classification` | Sort documents into categories. | +| `Ocr` | `mindee.product.Ocr` | Extract raw text from any image or scanned document. | +| `Crop` | `mindee.product.Crop` | Detect and isolate document borders. | +| `Split` | `mindee.product.Split` | Break a multi-page file into separate logical documents. | ## Sending a Request The simplest way to get started is to use the built-in polling functionality of the library. +Sending requests is the same regardless of the product used. Only the product class changes. + +Handling the return *is* specific to each product, this is detailed in the product-specific documentation. + ### Parameters Every request requires a `params` object. At minimum, `modelId` must be set. @@ -227,27 +214,6 @@ const params = { }; ``` -For `Extraction` only, additional options are available: - -```typescript -const params = { - modelId: "MY_MODEL_ID", - - // Options: set to `true` or `false` to override defaults - - // Enhance extraction accuracy with Retrieval-Augmented Generation. - rag: undefined, - // Extract the full text content from the document as strings. - rawText: undefined, - // Calculate bounding box polygons for all fields. - polygon: undefined, - // Calculate confidence scores for all fields. - confidence: undefined, -}; -``` - -Other products only take `modelId`. - ### All-in-One: `enqueueAndGetResult()` The simplest way to process a document. @@ -303,9 +269,9 @@ Pass a `PollingOptions` object as the optional fourth argument to override any o ```typescript const pollingOptions = { - initialDelaySec: 4, // wait 4 s before the first poll (default: 2) - delaySec: 1, // wait 1 s between subsequent polls (default: 1.5) - maxRetries: 100, // give up after 100 attempts (default: 80) + initialDelaySec: 4, // wait 4 seconds before the first poll + delaySec: 1, // wait 1 seconds between subsequent polls + maxRetries: 100, // give up after 100 attempts }; const response = await mindeeClient.enqueueAndGetResult( @@ -318,9 +284,35 @@ const response = await mindeeClient.enqueueAndGetResult( console.log(response.inference.toString()); ``` +## Manual Polling (Advanced) +⚠️ Advanced users only. This pattern requires you to manage the polling loop yourself. +Most users should use `enqueueAndGetResult()` instead, which handles all of this automatically. + +Use this pattern when you need full control over the polling lifecycle. +For example, to integrate with your own retry logic, persist job state across process restarts, or implement custom timeout strategies. + +There are three steps: + +1. **Enqueue** the document with `enqueue()`, which returns a `JobResponse`. + Retrieve the job ID from `job.id` on the response. +2. **Poll** the job status by calling `getJob(jobId)`, which also returns a `JobResponse`. + Repeat until `job.status` is `"Processed"` or `"Failed"`. +3. **Fetch** the result with `getResultByUrl(product, url)` once the job status is `"Processed"`. + Pass the product class and the `job.resultUrl` from the last `getJob()` response as the URL argument. + +### Notes +* You are responsible for handling timeouts. +* Add a retry counter or deadline to your loop to avoid running forever. +* Make sure to wait some time before each poll request to avoid HTTP 429 errors. +* The `jobId` can be persisted and used in a future process or request if you need to resume polling after a restart. +* If `job.status` is `"Failed"`, check `job.error` on the `JobResponse` for details about the failure. +* Always check that `job.resultUrl` is defined before passing it to `getResultByUrl()`. + The result URL is only populated once the job status is `"Processed"`. + ## Sending a Request Using Webhooks -The document is enqueued and Mindee will call your webhook URL when processing is complete, no polling required on your side. +The document is enqueued, and Mindee will call your webhook URL when processing is complete. +Using this method, no polling is required; however, you will need a public web server accepting POST requests. ### Requirements @@ -328,7 +320,7 @@ You must have configured a webhook in the Mindee platform, and have its ID avail Refer to the [Webhook Documentation](https://docs.mindee.com/integrations/webhooks) for instructions on creating one. -### Parameters +### Enqueuing the Document Every request requires a `params` object. At minimum, `modelId` must be set. Pass the webhook ID in the `params` object: @@ -376,6 +368,8 @@ console.log(`Enqueued with job ID: ${jobId}`); > // Possible statuses: "Processing", "Processed", "Failed" >``` +### Loading the Response + When Mindee calls your webhook, the raw JSON string body of the HTTP request can be deserialized using `LocalResponse`: ```typescript @@ -398,6 +392,11 @@ const response = await localResponse.deserializeResponse( console.log(response.inference.toString()); ``` +The resulting object will be identical to one received by calling `enqueueAndGetResult()`. +You can therefore switch between polling and webhook flows with minimal changes to your code. + +### Verification + You can also verify the HMAC signature of the webhook payload to ensure it genuinely came from Mindee: ```typescript @@ -409,3 +408,21 @@ if (!localResponse.isValidHmacSignature(secretKey, hmacSignature)) { throw new Error("Bad HMAC signature! Is someone trying to do evil?"); } ``` + +--- + +# Agent Instructions: Querying The Documentation + +If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. + +Perform an HTTP GET request on the documentation URL with the `ask` query parameter. +Include `nodejs+sdk+-+` at the beginning of the question to get answers specific to this library: + +``` +GET https://docs.mindee.com/integrations.md?ask=nodejs+sdk+-+ +``` + +The question should be specific, self-contained, and written in natural language. +The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. + +Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections. From 7bd753f12aa22bc57422ac84fe6113f915b44db2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ianar=C3=A9=20S=C3=A9vi?= Date: Thu, 7 May 2026 16:58:45 +0200 Subject: [PATCH 4/4] add product docs --- SKILL.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 84 insertions(+), 2 deletions(-) diff --git a/SKILL.md b/SKILL.md index 542c617b..b380da59 100644 --- a/SKILL.md +++ b/SKILL.md @@ -52,7 +52,7 @@ Optional dependencies are included by default. They enable additional features: | PDF text extraction | `pdf.js-extract` | | Image compression | `sharp` | -To skip them for a lighter install: +If you never use these features, it's possible to skip them for a lighter installation: ```bash npm install mindee --omit=optional @@ -100,7 +100,7 @@ const mindeeClient = new mindee.Client(); ## Loading an Input Document Before sending a document to the API, wrap it in one of the input source classes exported from the `mindee` package. -All input sources are then passed directly to various methods, mostly in the client. +All input sources are then passed to various methods, mostly in the client. ### File Path @@ -409,6 +409,88 @@ if (!localResponse.isValidHmacSignature(secretKey, hmacSignature)) { } ``` +## Product Specific Handling + +### Extraction + +#### Parameters + +There are additional parameters: + +```typescript +const params = { + modelId: "MY_MODEL_ID", + + // Options: set to `true` or `false` to override defaults + + // Enhance extraction accuracy with Retrieval-Augmented Generation. + rag: undefined, + // Extract the full text content from the document as strings. + rawText: undefined, + // Calculate bounding box polygons for all fields. + polygon: undefined, + // Calculate confidence scores for all fields. + confidence: undefined, + // Additional text context used by the model during inference. + // Not recommended, for specific use only. + textContext: undefined, + // Dynamic changes to the data schema of the model for this inference. + // Not recommended, for specific use only. + dataSchema: undefined, +}; +``` + +#### Response + +### Split + +#### Parameters + +No additional parameters beyond the base ones. + +#### Response + +### Crop + +#### Parameters + +No additional parameters beyond the base ones. + +#### Response + +The `CropResponse` contains a `CropInference` object at `response.inference`. + +The `CropInference` exposes a `result` property of type `CropResult`, which contains an array of `CropItem` objects. + +##### Accessing Crop Items + +Each `CropItem` in `response.inference.result.crops` describes a detected region: + +| Property | Type | +|----------------------|-----------------------| +| `objectType` | `string` | +| `location` | `FieldLocation` | +| `extractionResponse` | `ExtractionResponse` | + +The `objectType` property is the classification of the detected object, as defined on the Mindee platform. + +The `location` property contains a `FieldLocation` instance: +- `location.polygon` – a `Polygon` instance defining the crop boundary. +- `location.page` – the 0-based page index where the crop was found. + +The `extractionResponse` property is an `ExtractionResponse` instance, which is identical to the response from Extraction product request. +It will contain data extracted from the crop, if: +* an extraction model was associated with a class on the Mindee platform +* the class was detected on the crop + +### OCR + +#### Parameters + +No additional parameters beyond the base ones. + +#### Response + --- # Agent Instructions: Querying The Documentation