✨ add support for us mail v3 (#216)

Author: ianardee

docs/code_samples/us_mail_v3_async.txt

@@ -0,0 +1,41 @@
+import com.mindee.MindeeClient;
+import com.mindee.input.LocalInputSource;
+import com.mindee.parsing.common.AsyncPredictResponse;
+import com.mindee.product.us.usmail.UsMailV3;
+import java.io.File;
+import java.io.IOException;
+
+public class SimpleMindeeClient {
+
+  public static void main(String[] args) throws IOException, InterruptedException {
+    String apiKey = "my-api-key";
+    String filePath = "/path/to/the/file.ext";
+
+    // Init a new client
+    MindeeClient mindeeClient = new MindeeClient(apiKey);
+
+    // Load a file from disk
+    LocalInputSource inputSource = new LocalInputSource(new File(filePath));
+
+    // Parse the file asynchronously
+    AsyncPredictResponse<UsMailV3> response = mindeeClient.enqueueAndParse(
+        UsMailV3.class,
+        inputSource
+    );
+
+    // Print a summary of the response
+    System.out.println(response.toString());
+
+    // Print a summary of the predictions
+//  System.out.println(response.getDocumentObj().toString());
+
+    // Print the document-level predictions
+//    System.out.println(response.getDocumentObj().getInference().getPrediction().toString());
+
+    // Print the page-level predictions
+//    response.getDocumentObj().getInference().getPages().forEach(
+//        page -> System.out.println(page.toString())
+//    );
+  }
+
+}

docs/us_mail_v2.md renamed to docs/us_mail_v3.md

@@ -14,7 +14,7 @@ Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/mai
 import com.mindee.MindeeClient;
 import com.mindee.input.LocalInputSource;
 import com.mindee.parsing.common.AsyncPredictResponse;
-import com.mindee.product.us.usmail.UsMailV2;
+import com.mindee.product.us.usmail.UsMailV3;
 import java.io.File;
 import java.io.IOException;
 
@@ -31,8 +31,8 @@ public class SimpleMindeeClient {
     LocalInputSource inputSource = new LocalInputSource(new File(filePath));
 
     // Parse the file asynchronously
-    AsyncPredictResponse<UsMailV2> response = mindeeClient.enqueueAndParse(
-        UsMailV2.class,
+    AsyncPredictResponse<UsMailV3> response = mindeeClient.enqueueAndParse(
+        UsMailV3.class,
         inputSource
     );
 
@@ -57,7 +57,20 @@ public class SimpleMindeeClient {
 
 **Output (RST):**
 ```rst
-:Sender Name: zed
+########
+Document
+########
+:Mindee ID: f9c36f59-977d-4ddc-9f2d-31c294c456ac
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/us_mail v3.0
+:Rotation applied: Yes
+
+Prediction
+==========
+:Sender Name: company zed
 :Sender Address:
   :City: Dallas
   :Complete Address: 54321 Elm Street, Dallas, Texas 54321
@@ -66,11 +79,12 @@ public class SimpleMindeeClient {
   :Street: 54321 Elm Street
 :Recipient Names: Jane Doe
 :Recipient Addresses:
-  +-----------------+-------------------------------------+-------------------+-------------+------------------------+-------+---------------------------+
-  | City            | Complete Address                    | Is Address Change | Postal Code | Private Mailbox Number | State | Street                    |
-  +=================+=====================================+===================+=============+========================+=======+===========================+
-  | Detroit         | 1234 Market Street PMB 4321, Det... |                   | 12345       | 4321                   | MI    | 1234 Market Street        |
-  +-----------------+-------------------------------------+-------------------+-------------+------------------------+-------+---------------------------+
+  +-----------------+-------------------------------------+-------------------+-------------+------------------------+-------+---------------------------+-----------------+
+  | City            | Complete Address                    | Is Address Change | Postal Code | Private Mailbox Number | State | Street                    | Unit            |
+  +=================+=====================================+===================+=============+========================+=======+===========================+=================+
+  | Detroit         | 1234 Market Street PMB 4321, Det... | False             | 12345       | 4321                   | MI    | 1234 Market Street        |                 |
+  +-----------------+-------------------------------------+-------------------+-------------+------------------------+-------+---------------------------+-----------------+
+:Return to Sender: False
 ```
 
 # Field Types
@@ -96,13 +110,17 @@ The text field `StringField` extends `BaseField`, but also implements:
 * **value** (`String`): corresponds to the field value.
 * **rawValue** (`String`): corresponds to the raw value as it appears on the document.
 
+### BooleanField
+The boolean field `BooleanField` extends BaseField, but also implements:
+* **value** (`Boolean`): corresponds to the value of the field.
+
 ## Specific Fields
 Fields which are specific to this product; they are not used in any other product.
 
 ### Recipient Addresses Field
 The addresses of the recipients.
 
-A `UsMailV2RecipientAddress` implements the following attributes:
+A `UsMailV3RecipientAddress` implements the following attributes:
 
 * **city** (`String`): The city of the recipient's address.
 * **complete** (`String`): The complete address of the recipient.
@@ -111,12 +129,13 @@ A `UsMailV2RecipientAddress` implements the following attributes:
 * **privateMailboxNumber** (`String`): The private mailbox number of the recipient's address.
 * **state** (`String`): Second part of the ISO 3166-2 code, consisting of two letters indicating the US State.
 * **street** (`String`): The street of the recipient's address.
+* **unit** (`String`): The unit number of the recipient's address.
 Fields which are specific to this product; they are not used in any other product.
 
 ### Sender Address Field
 The address of the sender.
 
-A `UsMailV2SenderAddress` implements the following attributes:
+A `UsMailV3SenderAddress` implements the following attributes:
 
 * **city** (`String`): The city of the sender's address.
 * **complete** (`String`): The complete address of the sender.
@@ -125,10 +144,17 @@ A `UsMailV2SenderAddress` implements the following attributes:
 * **street** (`String`): The street of the sender's address.
 
 # Attributes
-The following fields are extracted for US Mail V2:
+The following fields are extracted for US Mail V3:
+
+## Return to Sender
+**isReturnToSender**: Whether the mailing is marked as return to sender.
+
+```java
+System.out.println(result.getDocument().getInference().getPrediction().getIsReturnToSender().value);
+```
 
 ## Recipient Addresses
-**recipientAddresses**(List<[UsMailV2RecipientAddress](#recipient-addresses-field)>): The addresses of the recipients.
+**recipientAddresses**(List<[UsMailV3RecipientAddress](#recipient-addresses-field)>): The addresses of the recipients.
 
 ```java
 for (recipientAddressesElem : result.getDocument().getInference().getPrediction().getRecipientAddresses())
@@ -148,7 +174,7 @@ for (recipientNamesElem : result.getDocument().getInference().getPrediction().ge
 ```
 
 ## Sender Address
-**senderAddress**([UsMailV2SenderAddress](#sender-address-field)): The address of the sender.
+**senderAddress**([UsMailV3SenderAddress](#sender-address-field)): The address of the sender.
 
 ```java
 System.out.println(result.getDocument().getInference().getPrediction().getSenderAddress().value);

src/main/java/com/mindee/CommandLineInterface.java

@@ -9,12 +9,14 @@
 import com.mindee.parsing.common.Inference;
 import com.mindee.parsing.common.PredictResponse;
 import com.mindee.product.custom.CustomV1;
+import com.mindee.product.financialdocument.FinancialDocumentV1;
 import com.mindee.product.internationalid.InternationalIdV2;
 import com.mindee.product.invoice.InvoiceV4;
 import com.mindee.product.invoicesplitter.InvoiceSplitterV1;
 import com.mindee.product.multireceiptsdetector.MultiReceiptsDetectorV1;
 import com.mindee.product.passport.PassportV1;
 import com.mindee.product.receipt.ReceiptV4;
+import com.mindee.product.us.usmail.UsMailV3;
 import java.io.File;
 import java.io.IOException;
 import java.util.ArrayList;
@@ -105,6 +107,14 @@ void receiptMethod(
     System.out.println(standardProductOutput(ReceiptV4.class, file));
   }
 
+  @Command(name = "financial-document", description = "Parse using Financial Document")
+  void financialDocumentMethod(
+      @Parameters(index = "0", paramLabel = "<path>", scope = ScopeType.LOCAL)
+      File file
+  ) throws IOException {
+    System.out.println(standardProductOutput(FinancialDocumentV1.class, file));
+  }
+
   @Command(name = "multi-receipt-detector", description = "Parse using Multi Receipts Detector")
   void multiReceiptDetectorMethod(
       @Parameters(index = "0", paramLabel = "<path>", scope = ScopeType.LOCAL)
@@ -137,6 +147,14 @@ void internationalIdMethod(
     System.out.println(standardProductAsyncOutput(InternationalIdV2.class, file));
   }
 
+  @Command(name = "us-mail", description = "Parse using US Mail")
+  void usMailMethod(
+      @Parameters(index = "0", paramLabel = "<path>", scope = ScopeType.LOCAL)
+      File file
+  ) throws IOException, InterruptedException {
+    System.out.println(standardProductAsyncOutput(UsMailV3.class, file));
+  }
+
   @Command(name = "custom", description = "Invokes a Custom API")
   void customMethod(
       @Option(

src/main/java/com/mindee/parsing/SummaryHelper.java

@@ -55,7 +55,10 @@ public static String formatForDisplay(String inputValue, Integer maxColSize) {
     if (inputValue == null || inputValue.isEmpty()) {
       return "";
     }
-    String outputValue = inputValue.replace("\n", "\\n").replace("\t", "\\t").replace("\r", "\\r");
+    String outputValue = inputValue
+        .replace("\n", "\\n")
+        .replace("\t", "\\t")
+        .replace("\r", "\\r");
     if (maxColSize == null || outputValue.length() <= maxColSize) {
       return outputValue;
     } else {

src/main/java/com/mindee/parsing/standard/BooleanField.java

@@ -5,6 +5,7 @@
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.mindee.geometry.Polygon;
 import com.mindee.geometry.PolygonDeserializer;
+import com.mindee.parsing.SummaryHelper;
 import lombok.Getter;
 
 
@@ -45,7 +46,7 @@ public boolean isEmpty() {
    */
   @Override
   public String toString() {
-    return this.value == null ? "" : value.toString();
+    return SummaryHelper.formatForDisplay(this.value, null);
   }
 
 }

src/main/java/com/mindee/parsing/standard/StringField.java

@@ -5,6 +5,7 @@
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.mindee.geometry.Polygon;
 import com.mindee.geometry.PolygonDeserializer;
+import com.mindee.parsing.SummaryHelper;
 import lombok.Getter;
 
 /**
@@ -56,6 +57,6 @@ public boolean isEmpty() {
 
   @Override
   public String toString() {
-    return value == null ? "" : value;
+    return SummaryHelper.formatString(this.value);
   }
 }

src/main/java/com/mindee/product/us/usmail/UsMailV3.java

@@ -0,0 +1,16 @@
+package com.mindee.product.us.usmail;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.mindee.http.EndpointInfo;
+import com.mindee.parsing.common.Inference;
+import lombok.Getter;
+
+/**
+ * US Mail API version 3 inference prediction.
+ */
+@Getter
+@JsonIgnoreProperties(ignoreUnknown = true)
+@EndpointInfo(endpointName = "us_mail", version = "3")
+public class UsMailV3
+    extends Inference<UsMailV3Document, UsMailV3Document> {
+}

src/main/java/com/mindee/product/us/usmail/UsMailV3Document.java

@@ -0,0 +1,100 @@
+package com.mindee.product.us.usmail;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.mindee.parsing.SummaryHelper;
+import com.mindee.parsing.common.Prediction;
+import com.mindee.parsing.standard.BooleanField;
+import com.mindee.parsing.standard.StringField;
+import java.util.ArrayList;
+import java.util.List;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+
+/**
+ * US Mail API version 3.0 document data.
+ */
+@Getter
+@EqualsAndHashCode(callSuper = false)
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class UsMailV3Document extends Prediction {
+
+  /**
+   * Whether the mailing is marked as return to sender.
+   */
+  @JsonProperty("is_return_to_sender")
+  protected BooleanField isReturnToSender;
+  /**
+   * The addresses of the recipients.
+   */
+  @JsonProperty("recipient_addresses")
+  protected List<UsMailV3RecipientAddress> recipientAddresses = new ArrayList<>();
+  /**
+   * The names of the recipients.
+   */
+  @JsonProperty("recipient_names")
+  protected List<StringField> recipientNames = new ArrayList<>();
+  /**
+   * The address of the sender.
+   */
+  @JsonProperty("sender_address")
+  protected UsMailV3SenderAddress senderAddress;
+  /**
+   * The name of the sender.
+   */
+  @JsonProperty("sender_name")
+  protected StringField senderName;
+
+  @Override
+  public boolean isEmpty() {
+    return (
+      this.senderName == null
+      && this.senderAddress == null
+      && (this.recipientNames == null || this.recipientNames.isEmpty())
+      && (this.recipientAddresses == null || this.recipientAddresses.isEmpty())
+      && this.isReturnToSender == null
+      );
+  }
+
+  @Override
+  public String toString() {
+    StringBuilder outStr = new StringBuilder();
+    outStr.append(
+        String.format(":Sender Name: %s%n", this.getSenderName())
+    );
+    outStr.append(
+        String.format(":Sender Address:%n%s", this.getSenderAddress().toFieldList())
+    );
+    String recipientNames = SummaryHelper.arrayToString(
+        this.getRecipientNames(),
+        "%n                  "
+    );
+    outStr.append(
+        String.format(":Recipient Names: %s%n", recipientNames)
+    );
+    String recipientAddressesSummary = "";
+    if (!this.getRecipientAddresses().isEmpty()) {
+      int[] recipientAddressesColSizes = new int[]{17, 37, 19, 13, 24, 7, 27, 17};
+      recipientAddressesSummary =
+        String.format("%n%s%n  ", SummaryHelper.lineSeparator(recipientAddressesColSizes, "-"))
+          + "| City            "
+          + "| Complete Address                    "
+          + "| Is Address Change "
+          + "| Postal Code "
+          + "| Private Mailbox Number "
+          + "| State "
+          + "| Street                    "
+          + "| Unit            "
+          + String.format("|%n%s%n  ", SummaryHelper.lineSeparator(recipientAddressesColSizes, "="));
+      recipientAddressesSummary += SummaryHelper.arrayToString(this.getRecipientAddresses(), recipientAddressesColSizes);
+      recipientAddressesSummary += String.format("%n%s", SummaryHelper.lineSeparator(recipientAddressesColSizes, "-"));
+    }
+    outStr.append(
+        String.format(":Recipient Addresses: %s%n", recipientAddressesSummary)
+    );
+    outStr.append(
+        String.format(":Return to Sender: %s%n", this.getIsReturnToSender())
+    );
+    return SummaryHelper.cleanSummary(outStr.toString());
+  }
+}