♻️ update display & structure for invoice splitter v1 (#334)

sebastianMindee · web-flow · commit 84a502643ae5 · 2025-03-17T10:41:27.000+01:00
diff --git a/docs/code_samples/invoice_splitter_v1_async.txt b/docs/code_samples/invoice_splitter_v1_async.txt
@@ -8,14 +8,14 @@ const mindeeClient = new mindee.Client({ apiKey: "my-api-key" });
 // Load a file from disk
 const inputSource = mindeeClient.docFromPath("/path/to/the/file.ext");
 
-// Parse the file asynchronously.
-const asyncApiResponse = mindeeClient.enqueueAndParse(
+// Parse the file
+const apiResponse = mindeeClient.enqueueAndParse(
   mindee.product.InvoiceSplitterV1,
   inputSource
 );
 
 // Handle the response Promise
-asyncApiResponse.then((resp) => {
+apiResponse.then((resp) => {
   // print a string summary
   console.log(resp.document.toString());
-});
+});
diff --git a/docs/invoice_splitter_v1.md b/docs/invoice_splitter_v1.md
@@ -6,11 +6,10 @@ parentDoc: 609809574212d40077a040f1
 ---
 The Node.js OCR SDK supports the [Invoice Splitter API](https://platform.mindee.com/mindee/invoice_splitter).
 
-Using [this sample](https://github.com/mindee/client-lib-test-data/blob/main/products/invoice_splitter/default_sample.pdf), we are going to illustrate how to detect the pages of multiple invoices within the same document.
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/invoice_splitter/default_sample.pdf), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Invoice Splitter sample](https://github.com/mindee/client-lib-test-data/blob/main/products/invoice_splitter/default_sample.pdf?raw=true)
 
 # Quick-Start
-> **⚠️ Important:** This API only works **asynchronously**, which means that documents have to be sent and retrieved in a specific way:
-
 ```js
 const mindee = require("mindee");
 // for TS or modules:
@@ -22,11 +21,14 @@ const mindeeClient = new mindee.Client({ apiKey: "my-api-key" });
 // Load a file from disk
 const inputSource = mindeeClient.docFromPath("/path/to/the/file.ext");
 
-// Parse the file asynchronously.
-const asyncApiResponse = mindeeClient.enqueueAndParse(mindee.product.InvoiceSplitterV1, inputSource);
+// Parse the file
+const apiResponse = mindeeClient.enqueueAndParse(
+  mindee.product.InvoiceSplitterV1,
+  inputSource
+);
 
 // Handle the response Promise
-asyncApiResponse.then((resp) => {
+apiResponse.then((resp) => {
   // print a string summary
   console.log(resp.document.toString());
 });
@@ -37,51 +39,71 @@ asyncApiResponse.then((resp) => {
 ########
 Document
 ########
-:Mindee ID: 8c25cc63-212b-4537-9c9b-3fbd3bd0ee20
-:Filename: default_sample.jpg
+:Mindee ID: 15ad7a19-7b75-43d0-b0c6-9a641a12b49b
+:Filename: default_sample.pdf
 
 Inference
 #########
-:Product: mindee/carte_vitale v1.0
-:Rotation applied: Yes
+:Product: mindee/invoice_splitter v1.1
+:Rotation applied: No
 
 Prediction
 ==========
-:Given Name(s): NATHALIE
-:Surname: DURAND
-:Social Security Number: 269054958815780
-:Issuance Date: 2007-01-01
+:Invoice Page Groups:
+  :Page indexes: 0
+  :Page indexes: 1
 
 Page Predictions
 ================
 
 Page 0
 ------
-:Given Name(s): NATHALIE
-:Surname: DURAND
-:Social Security Number: 269054958815780
-:Issuance Date: 2007-01-01
+:Invoice Page Groups:
+
+Page 1
+------
+:Invoice Page Groups:
 ```
 
 # Field Types
+## Standard Fields
+These fields are generic and used in several products.
+
+### Basic Field
+Each prediction object contains a set of fields that inherit from the generic `Field` class.
+A typical `Field` object will have the following attributes:
+
+* **value** (`number | string`): corresponds to the field value. Can be `undefined` if no value was extracted.
+* **confidence** (`number`): the confidence score of the field prediction.
+* **boundingBox** (`[Point, Point, Point, Point]`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document.
+* **polygon** (`Point[]`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image.
+* **pageId** (`number`): the ID of the page, always `undefined` when at document-level.
+* **reconstructed** (`boolean`): indicates whether an object was reconstructed (not extracted as the API gave it).
+
+> **Note:** A `Point` simply refers to an array of two numbers (`[number, number]`).
+
+
+Aside from the previous attributes, all basic fields have access to a `toString()` method that can be used to print their value as a string.
+
 ## Specific Fields
-### Invoice Splitter V1 Page Group
-List of page group indexes.
+Fields which are specific to this product; they are not used in any other product.
+
+### Invoice Page Groups Field
+List of page groups. Each group represents a single invoice within a multi-invoice document.
 
-An `InvoiceSplitterV1PageGroup` implements the following attributes:
+A `InvoiceSplitterV1InvoicePageGroup` implements the following attributes:
 
-* **pageIndexes** (`number`[]): List of indexes of the pages of a single invoice.
-* **confidence** (`number`): The confidence of the prediction.
+* `pageIndexes` (Array<number>): List of page indexes that belong to the same invoice (group).
 
 # Attributes
 The following fields are extracted for Invoice Splitter V1:
 
 ## Invoice Page Groups
-**invoicePageGroups** ([InvoiceSplitterV1PageGroup](#invoice-splitter-v1-page-group)[]): List of page indexes that belong to the same invoice in the PDF.
+**invoicePageGroups** ([InvoiceSplitterV1InvoicePageGroup](#invoice-page-groups-field)[]): List of page groups. Each group represents a single invoice within a multi-invoice document.
 
 ```js
-for (const invoicePageGroupsElem of result.document.inference.prediction.invoicePageGroups){ 
-  console.log(invoicePageGroupsElem.pageIndexes.join(", "));
+for (const invoicePageGroupsElem of result.document.inference.prediction.invoicePageGroups) {
+  console.log(invoicePageGroupsElem.value);
 }
 ```
 
diff --git a/src/imageOperations/invoiceSplitterExtractor/invoiceSplitterExtractor.ts b/src/imageOperations/invoiceSplitterExtractor/invoiceSplitterExtractor.ts
@@ -62,7 +62,7 @@ export async function extractInvoices(
   if (indexes instanceof InvoiceSplitterV1) {
     indexes.prediction.invoicePageGroups.map((invoicePageGroup) => {
       if (!strict || invoicePageGroup.confidence === 1) {
-        customIndexes.push(invoicePageGroup.pageIndexes);
+        customIndexes.push(invoicePageGroup.pageIndexes ?? []);
       }
     });
   } else {
diff --git a/src/product/billOfLading/billOfLadingV1Carrier.ts b/src/product/billOfLading/billOfLadingV1Carrier.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../parsing/common";
 import { Polygon } from "../../geometry";
 
diff --git a/src/product/billOfLading/billOfLadingV1Consignee.ts b/src/product/billOfLading/billOfLadingV1Consignee.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../parsing/common";
 import { Polygon } from "../../geometry";
 
diff --git a/src/product/billOfLading/billOfLadingV1NotifyParty.ts b/src/product/billOfLading/billOfLadingV1NotifyParty.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../parsing/common";
 import { Polygon } from "../../geometry";
 
diff --git a/src/product/billOfLading/billOfLadingV1Shipper.ts b/src/product/billOfLading/billOfLadingV1Shipper.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../parsing/common";
 import { Polygon } from "../../geometry";
 
diff --git a/src/product/fr/bankAccountDetails/bankAccountDetailsV2Bban.ts b/src/product/fr/bankAccountDetails/bankAccountDetailsV2Bban.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../../parsing/common";
 import { Polygon } from "../../../geometry";
 
diff --git a/src/product/fr/energyBill/energyBillV1EnergyConsumer.ts b/src/product/fr/energyBill/energyBillV1EnergyConsumer.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../../parsing/common";
 import { Polygon } from "../../../geometry";
 
diff --git a/src/product/fr/energyBill/energyBillV1EnergySupplier.ts b/src/product/fr/energyBill/energyBillV1EnergySupplier.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../../parsing/common";
 import { Polygon } from "../../../geometry";
 
diff --git a/src/product/fr/energyBill/energyBillV1MeterDetail.ts b/src/product/fr/energyBill/energyBillV1MeterDetail.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../../parsing/common";
 import { Polygon } from "../../../geometry";
 
diff --git a/src/product/fr/payslip/payslipV2BankAccountDetail.ts b/src/product/fr/payslip/payslipV2BankAccountDetail.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../../parsing/common";
 import { Polygon } from "../../../geometry";
 
diff --git a/src/product/fr/payslip/payslipV2Employee.ts b/src/product/fr/payslip/payslipV2Employee.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../../parsing/common";
 import { Polygon } from "../../../geometry";
 
diff --git a/src/product/fr/payslip/payslipV2Employer.ts b/src/product/fr/payslip/payslipV2Employer.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../../parsing/common";
 import { Polygon } from "../../../geometry";
 
diff --git a/src/product/fr/payslip/payslipV2PayPeriod.ts b/src/product/fr/payslip/payslipV2PayPeriod.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../../parsing/common";
 import { Polygon } from "../../../geometry";
 
diff --git a/src/product/fr/payslip/payslipV3BankAccountDetail.ts b/src/product/fr/payslip/payslipV3BankAccountDetail.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../../parsing/common";
 import { Polygon } from "../../../geometry";
 
diff --git a/src/product/fr/payslip/payslipV3Employee.ts b/src/product/fr/payslip/payslipV3Employee.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../../parsing/common";
 import { Polygon } from "../../../geometry";
 
diff --git a/src/product/fr/payslip/payslipV3Employer.ts b/src/product/fr/payslip/payslipV3Employer.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../../parsing/common";
 import { Polygon } from "../../../geometry";
 
diff --git a/src/product/fr/payslip/payslipV3Employment.ts b/src/product/fr/payslip/payslipV3Employment.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../../parsing/common";
 import { Polygon } from "../../../geometry";
 
diff --git a/src/product/fr/payslip/payslipV3PayPeriod.ts b/src/product/fr/payslip/payslipV3PayPeriod.ts
@@ -1,4 +1,3 @@
-
 import { StringDict } from "../../../parsing/common";
 import { Polygon } from "../../../geometry";
 
diff --git a/src/product/invoiceSplitter/index.ts b/src/product/invoiceSplitter/index.ts
@@ -0,0 +1 @@
+export { InvoiceSplitterV1 } from "./invoiceSplitterV1";
diff --git a/src/product/invoiceSplitter/internal.ts b/src/product/invoiceSplitter/internal.ts
@@ -1,3 +1,3 @@
 export { InvoiceSplitterV1 } from "./invoiceSplitterV1";
 export { InvoiceSplitterV1Document } from "./invoiceSplitterV1Document";
-export { InvoiceSplitterV1PageGroup } from "./invoiceSplitterV1PageGroup";
+export { InvoiceSplitterV1InvoicePageGroup } from "./invoiceSplitterV1InvoicePageGroup";
diff --git a/src/product/invoiceSplitter/invoiceSplitterV1.ts b/src/product/invoiceSplitter/invoiceSplitterV1.ts
@@ -2,7 +2,7 @@ import { Inference, StringDict, Page } from "../../parsing/common";
 import { InvoiceSplitterV1Document } from "./invoiceSplitterV1Document";
 
 /**
- * Inference prediction for Invoice Splitter, API version 1.
+ * Invoice Splitter API version 1 inference prediction.
  */
 export class InvoiceSplitterV1 extends Inference {
   /** The endpoint's name. */
@@ -16,17 +16,19 @@ export class InvoiceSplitterV1 extends Inference {
 
   constructor(rawPrediction: StringDict) {
     super(rawPrediction);
-    this.prediction = new InvoiceSplitterV1Document(
-      rawPrediction["prediction"]
-    );
-    this.pages = rawPrediction["pages"].map(
-      (page: StringDict) =>
-        new Page(
-          InvoiceSplitterV1Document,
-          page,
-          page["id"],
-          page["orientation"]
-        )
+    this.prediction = new InvoiceSplitterV1Document(rawPrediction["prediction"]);
+    rawPrediction["pages"].forEach(
+      (page: StringDict) => {
+        if (page.prediction !== undefined && page.prediction !== null &&
+          Object.keys(page.prediction).length > 0) {
+          this.pages.push(new Page(
+            InvoiceSplitterV1Document,
+            page,
+            page["id"],
+            page["orientation"]
+          ));
+        }
+      }
     );
   }
 }
diff --git a/src/product/invoiceSplitter/invoiceSplitterV1Document.ts b/src/product/invoiceSplitter/invoiceSplitterV1Document.ts
@@ -1,31 +1,47 @@
-import { Prediction, StringDict, cleanOutString } from "../../parsing/common";
+import {
+  Prediction,
+  StringDict,
+  cleanOutString,lineSeparator,
+} from "../../parsing/common";
+import { InvoiceSplitterV1InvoicePageGroup } from "./invoiceSplitterV1InvoicePageGroup";
 
-import { InvoiceSplitterV1PageGroup } from "./invoiceSplitterV1PageGroup";
 
 /**
- * Document data for Invoice Splitter, API version 1.
+ * Invoice Splitter API version 1.2 document data.
  */
 export class InvoiceSplitterV1Document implements Prediction {
-  /** List of page indexes that belong to the same invoice in the PDF. */
-  invoicePageGroups: InvoiceSplitterV1PageGroup[] = [];
+  /** List of page groups. Each group represents a single invoice within a multi-invoice document. */
+  invoicePageGroups: InvoiceSplitterV1InvoicePageGroup[] = [];
 
-  constructor(rawPrediction: StringDict) {
+  constructor(rawPrediction: StringDict, pageId?: number) {
     rawPrediction["invoice_page_groups"] &&
-      rawPrediction["invoice_page_groups"].forEach((prediction: StringDict) =>
-        this.invoicePageGroups.push(new InvoiceSplitterV1PageGroup(prediction))
+      rawPrediction["invoice_page_groups"].map(
+        (itemPrediction: StringDict) =>
+          this.invoicePageGroups.push(
+            new InvoiceSplitterV1InvoicePageGroup({
+              prediction: itemPrediction,
+              pageId: pageId,
+            })
+          )
       );
   }
 
   /**
    * Default string representation.
    */
   toString(): string {
-    const invoicePageGroups: string = this.invoicePageGroups
-      .map((item: InvoiceSplitterV1PageGroup) => "\n  " + item.toString())
-      .join("")
-      .trimEnd();
-
-    const outStr = `:Invoice Page Groups:${invoicePageGroups}`;
+    let invoicePageGroupsSummary:string = "";
+    if (this.invoicePageGroups && this.invoicePageGroups.length > 0) {
+      const invoicePageGroupsColSizes:number[] = [74];
+      invoicePageGroupsSummary += "\n" + lineSeparator(invoicePageGroupsColSizes, "-") + "\n  ";
+      invoicePageGroupsSummary += "| Page Indexes                                                             ";
+      invoicePageGroupsSummary += "|\n" + lineSeparator(invoicePageGroupsColSizes, "=");
+      invoicePageGroupsSummary += this.invoicePageGroups.map(
+        (item) =>
+          "\n  " + item.toTableLine() + "\n" + lineSeparator(invoicePageGroupsColSizes, "-")
+      ).join("");
+    }
+    const outStr = `:Invoice Page Groups: ${invoicePageGroupsSummary}`.trimEnd();
     return cleanOutString(outStr);
   }
 }
diff --git a/src/product/invoiceSplitter/invoiceSplitterV1InvoicePageGroup.ts b/src/product/invoiceSplitter/invoiceSplitterV1InvoicePageGroup.ts
diff --git a/src/product/invoiceSplitter/invoiceSplitterV1PageGroup.ts b/src/product/invoiceSplitter/invoiceSplitterV1PageGroup.ts
diff --git a/src/product/us/usMail/usMailV3SenderAddress.ts b/src/product/us/usMail/usMailV3SenderAddress.ts
diff --git a/tests/data b/tests/data
diff --git a/tests/product/invoiceSplitter/invoiceSplitterV1.spec.ts b/tests/product/invoiceSplitter/invoiceSplitterV1.spec.ts

Original file line number	Diff line number	Diff line change
`@@ -62,7 +62,7 @@ export async function extractInvoices(`
`62`	`62`	`if (indexes instanceof InvoiceSplitterV1) {`
`63`	`63`	`indexes.prediction.invoicePageGroups.map((invoicePageGroup) => {`
`64`	`64`	`if (!strict \|\| invoicePageGroup.confidence === 1) {`
`65`		`- customIndexes.push(invoicePageGroup.pageIndexes);`
	`65`	`+ customIndexes.push(invoicePageGroup.pageIndexes ?? []);`
`66`	`66`	`}`
`67`	`67`	`});`
`68`	`68`	`} else {`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,3 @@`
`1`		`-`
`2`	`1`	`import { StringDict } from "../../parsing/common";`
`3`	`2`	`import { Polygon } from "../../geometry";`
`4`	`3`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,3 @@`
`1`		`-`
`2`	`1`	`import { StringDict } from "../../../parsing/common";`
`3`	`2`	`import { Polygon } from "../../../geometry";`
`4`	`3`