From b960896f2ad78eef8074665c3b8bf6296773f807 Mon Sep 17 00:00:00 2001 From: Andres Garcia Date: Thu, 12 Nov 2026 11:43:16 -0500 Subject: [PATCH] PLAT-9436: document the thinking parameter in the Node.js SDK Add thinking ("light" or "deep") to the JSDoc of the process_document methods and to the TypeScript extra args type, plus a README example and tests. Co-Authored-By: Claude Sonnet 5.5 --- README.md | 8 +++++ lib/documents/processDocument.js | 1 + lib/documents/processDocumentBase64.js | 1 + lib/documents/processDocumentStream.js | 1 + lib/documents/processDocumentUrl.js | 3 +- lib/types/VeryfiExtraArgs.ts | 8 ++++- test/main.test.js | 48 ++++++++++++++++++++++++++ 7 files changed, 68 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7c8494d..2d4d552 100644 --- a/README.md +++ b/README.md @@ -76,6 +76,14 @@ let response = veryfi_client.process_document_from_url(url, null, categories, fa }); ``` +Run thinking on the line items with `thinking` (`'light'` or `'deep'`; omit it to turn it off). Every `process_document*` method accepts it in the extra parameters, and `'deep'` takes longer than `'light'`. It only takes effect if thinking mode is enabled for your account. + +```js +let response = veryfi_client.process_document(file_path, categories, false, {thinking: 'light'}).then(response => { + console.log(response) +}); +``` + ### Line items, tags, and other products ```js diff --git a/lib/documents/processDocument.js b/lib/documents/processDocument.js index 09242e0..2a97438 100644 --- a/lib/documents/processDocument.js +++ b/lib/documents/processDocument.js @@ -14,6 +14,7 @@ const fs = require('fs'); * @param {Array} categories List of categories Veryfi can use to categorize the document * @param {Boolean} auto_delete Delete this document from Veryfi after data has been extracted * @param {Object} kwargs Additional request parameters + * @param {('light'|'deep')} [kwargs.thinking] Extra LLM pass on the line items: "light" or "deep" (slower). Omit to turn it off. Needs thinking mode enabled for your account. * @returns {JSON} Data extracted from the document */ Client.prototype.process_document = async function ( diff --git a/lib/documents/processDocumentBase64.js b/lib/documents/processDocumentBase64.js index 086f463..3a65e72 100644 --- a/lib/documents/processDocumentBase64.js +++ b/lib/documents/processDocumentBase64.js @@ -14,6 +14,7 @@ const Client = require('../client/constructor'); * @param {Array} categories List of categories Veryfi can use to categorize the document * @param {Boolean} auto_delete Delete this document from Veryfi after data has been extracted * @param {Object} kwargs Additional request parameters + * @param {('light'|'deep')} [kwargs.thinking] Extra LLM pass on the line items: "light" or "deep" (slower). Omit to turn it off. Needs thinking mode enabled for your account. * @returns {JSON} Data extracted from the document */ Client.prototype.process_document_from_base64 = async function ( diff --git a/lib/documents/processDocumentStream.js b/lib/documents/processDocumentStream.js index d02219d..88bda8b 100644 --- a/lib/documents/processDocumentStream.js +++ b/lib/documents/processDocumentStream.js @@ -13,6 +13,7 @@ const Client = require('../client/constructor'); * @param {String} file_name The file name including the extension * @param {Boolean} auto_delete Delete this document from Veryfi after data has been extracted * @param {Object} kwargs Additional request parameters (categories, tags, async, parse_address, crop_document, compute, country, document_type, device_data, package_path, bucket, bounding_boxes, confidence_details) + * @param {('light'|'deep')} [kwargs.thinking] Extra LLM pass on the line items: "light" or "deep" (slower). Omit to turn it off. Needs thinking mode enabled for your account. * @returns {JSON} Data extracted from the document */ Client.prototype.process_document_from_stream = async function ( diff --git a/lib/documents/processDocumentUrl.js b/lib/documents/processDocumentUrl.js index a96b5e5..6f3217c 100644 --- a/lib/documents/processDocumentUrl.js +++ b/lib/documents/processDocumentUrl.js @@ -12,7 +12,8 @@ const Client = require('../client/constructor'); * @param {boolean} boost_mode Flag that tells Veryfi whether boost mode should be enabled. When set to 1, Veryfi will skip data enrichment steps, but will process the document faster. Default value for this flag is 0 * @param {string|null} external_id Optional custom document identifier. Use this if you would like to assign your own ID to documents * @param {int} max_pages_to_process When sending a long document to Veryfi for processing, this parameter controls how many pages of the document will be read and processed, starting from page 1. - * @param {Object} kwargs Additional request parameters (async, tags, parse_address, crop_document, compute, country, document_type, device_data, package_path, bucket, bounding_boxes, confidence_details, thinking, thinking_llm_version, allowed_async_enrichments, emailed_receipt_id, receipt_id) + * @param {Object} kwargs Additional request parameters (async, tags, parse_address, crop_document, compute, country, document_type, device_data, package_path, bucket, bounding_boxes, confidence_details, thinking_llm_version, allowed_async_enrichments, emailed_receipt_id, receipt_id) + * @param {('light'|'deep')} [kwargs.thinking] Extra LLM pass on the line items: "light" or "deep" (slower). Omit to turn it off. Needs thinking mode enabled for your account. * @return {JSON} Data extracted from the document. */ Client.prototype.process_document_from_url = async function ( diff --git a/lib/types/VeryfiExtraArgs.ts b/lib/types/VeryfiExtraArgs.ts index 6f5be71..28afdef 100644 --- a/lib/types/VeryfiExtraArgs.ts +++ b/lib/types/VeryfiExtraArgs.ts @@ -3,6 +3,12 @@ * Nested objects, arrays, and nulls are allowed because several Veryfi * body fields (device_data, vendor, line_items, document_types, tags) are not scalars. */ -export declare type VeryfiExtraArgs = Record; +export declare type VeryfiExtraArgs = Record & { + /** + * Extra LLM pass on the line items: "light" or "deep" (slower). + * Omit to turn it off. Needs thinking mode enabled for your account. + */ + thinking?: "light" | "deep"; +}; export type JsonObject = Record; diff --git a/test/main.test.js b/test/main.test.js index 8c06a9d..c8d51e2 100644 --- a/test/main.test.js +++ b/test/main.test.js @@ -139,6 +139,54 @@ describe('Processing documents', () => { }); }); +describe('Thinking parameter', () => { + const newClient = () => { + const client = new Client('client_id', undefined, 'username', 'api_key'); + client._request = jest.fn().mockResolvedValue({data: {}}); + return client; + }; + // request_arguments is the third argument of _request + const sentArguments = (client) => client._request.mock.calls[0][2]; + + test.each(['light', 'deep'])('process_document sends thinking=%s', async (mode) => { + const client = newClient(); + await client.process_document('resources/receipt.png', null, false, {thinking: mode}); + expect(sentArguments(client).thinking).toBe(mode); + }); + + test('process_document does not send thinking when omitted', async () => { + const client = newClient(); + await client.process_document('resources/receipt.png'); + expect(sentArguments(client)).not.toHaveProperty('thinking'); + }); + + test.each(['light', 'deep'])('process_document_from_base64 sends thinking=%s', async (mode) => { + const client = newClient(); + await client.process_document_from_base64('ZmFrZQ==', 'receipt.png', null, false, {thinking: mode}); + expect(sentArguments(client).thinking).toBe(mode); + }); + + test.each(['light', 'deep'])('process_document_from_stream sends thinking=%s', async (mode) => { + const client = newClient(); + const stream = fs.createReadStream('resources/receipt.png'); + await client.process_document_from_stream(stream, 'receipt.png', false, {thinking: mode}); + stream.destroy(); + expect(sentArguments(client).thinking).toBe(mode); + }); + + test.each(['light', 'deep'])('process_document_from_url sends thinking=%s', async (mode) => { + const client = newClient(); + await client.process_document_from_url('https://cdn.example.com/receipt.jpg', null, null, false, false, null, 1, {thinking: mode}); + expect(sentArguments(client).thinking).toBe(mode); + }); + + test('process_document_from_url does not send thinking when omitted', async () => { + const client = newClient(); + await client.process_document_from_url('https://cdn.example.com/receipt.jpg'); + expect(sentArguments(client)).not.toHaveProperty('thinking'); + }); +}); + describe('Managing documents', () => { test('Get documents', async () => { try {