✨ add support for us mail v3

docs/code_samples/us_mail_v3_async.txt

@@ -0,0 +1,23 @@
+using Mindee;
+using Mindee.Input;
+using Mindee.Product.Us.UsMail;
+
+string apiKey = "my-api-key";
+string filePath = "/path/to/the/file.ext";
+
+// Construct a new client
+MindeeClient mindeeClient = new MindeeClient(apiKey);
+
+// Load an input source as a path string
+// Other input types can be used, as mentioned in the docs
+var inputSource = new LocalInputSource(filePath);
+
+// Call the product asynchronously with auto-polling
+var response = await mindeeClient
+    .EnqueueAndParseAsync<UsMailV3>(inputSource);
+
+// Print a summary of all the predictions
+System.Console.WriteLine(response.Document.ToString());
+
+// Print only the document-level predictions
+// System.Console.WriteLine(response.Document.Inference.Prediction.ToString());

docs/us_mail_v2.md → docs/us_mail_v3.md

@@ -27,7 +27,7 @@ var inputSource = new LocalInputSource(filePath);
 
 // Call the product asynchronously with auto-polling
 var response = await mindeeClient
-    .EnqueueAndParseAsync<UsMailV2>(inputSource);
+    .EnqueueAndParseAsync<UsMailV3>(inputSource);
 
 // Print a summary of all the predictions
 System.Console.WriteLine(response.Document.ToString());
@@ -39,7 +39,20 @@ System.Console.WriteLine(response.Document.ToString());
 
 **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
@@ -48,11 +61,12 @@ System.Console.WriteLine(response.Document.ToString());
   :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
@@ -78,13 +92,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** (`bool?`): 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.
@@ -93,12 +111,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.
@@ -107,10 +126,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.
+
+```csharp
+System.Console.WriteLine(result.Document.Inference.Prediction.IsReturnToSender.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.
 
 ```csharp
 foreach (var RecipientAddressesElem in result.Document.Inference.Prediction.RecipientAddresses)
@@ -130,7 +156,7 @@ foreach (var RecipientNamesElem in result.Document.Inference.Prediction.Recipien
 ```
 
 ## Sender Address
-**SenderAddress**([UsMailV2SenderAddress](#sender-address-field)): The address of the sender.
+**SenderAddress**([UsMailV3SenderAddress](#sender-address-field)): The address of the sender.
 
 ```csharp
 System.Console.WriteLine(result.Document.Inference.Prediction.SenderAddress.Value);

src/Mindee.Cli/Program.cs

@@ -57,9 +57,9 @@
     Mindee.Product.Us.BankCheck.BankCheckV1Document
 >;
 using PredictUsMailCommand = Mindee.Cli.PredictCommand<
-    Mindee.Product.Us.UsMail.UsMailV2,
-    Mindee.Product.Us.UsMail.UsMailV2Document,
-    Mindee.Product.Us.UsMail.UsMailV2Document
+    Mindee.Product.Us.UsMail.UsMailV3,
+    Mindee.Product.Us.UsMail.UsMailV3Document,
+    Mindee.Product.Us.UsMail.UsMailV3Document
 >;
 using PredictUsPayrollCheckRegisterCommand = Mindee.Cli.PredictCommand<
     Mindee.Product.Us.PayrollCheckRegister.PayrollCheckRegisterV1,

src/Mindee/Product/Us/UsMail/UsMailV3.cs

@@ -0,0 +1,20 @@
+using System.Text.Json.Serialization;
+using Mindee.Http;
+using Mindee.Parsing.Common;
+
+namespace Mindee.Product.Us.UsMail
+{
+    /// <summary>
+    /// US Mail API version 3 inference prediction.
+    /// </summary>
+    [Endpoint("us_mail", "3")]
+    public sealed class UsMailV3 : Inference<UsMailV3Document, UsMailV3Document>
+    {
+        /// <summary>
+        /// The pages and the associated values which were detected on the document.
+        /// </summary>
+        [JsonPropertyName("pages")]
+        [JsonConverter(typeof(PagesJsonConverter<UsMailV3Document>))]
+        public override Pages<UsMailV3Document> Pages { get; set; }
+    }
+}

src/Mindee/Product/Us/UsMail/UsMailV3Document.cs

@@ -0,0 +1,63 @@
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Text.Json.Serialization;
+using Mindee.Parsing;
+using Mindee.Parsing.Standard;
+
+namespace Mindee.Product.Us.UsMail
+{
+    /// <summary>
+    /// US Mail API version 3.0 document data.
+    /// </summary>
+    public class UsMailV3Document : IPrediction
+    {
+        /// <summary>
+        /// Whether the mailing is marked as return to sender.
+        /// </summary>
+        [JsonPropertyName("is_return_to_sender")]
+        public BooleanField IsReturnToSender { get; set; }
+
+        /// <summary>
+        /// The addresses of the recipients.
+        /// </summary>
+        [JsonPropertyName("recipient_addresses")]
+        [JsonConverter(typeof(ObjectListJsonConverter<UsMailV3RecipientAddresses, UsMailV3RecipientAddress>))]
+        public UsMailV3RecipientAddresses RecipientAddresses { get; set; }
+
+        /// <summary>
+        /// The names of the recipients.
+        /// </summary>
+        [JsonPropertyName("recipient_names")]
+        public IList<StringField> RecipientNames { get; set; } = new List<StringField>();
+
+        /// <summary>
+        /// The address of the sender.
+        /// </summary>
+        [JsonPropertyName("sender_address")]
+        public UsMailV3SenderAddress SenderAddress { get; set; }
+
+        /// <summary>
+        /// The name of the sender.
+        /// </summary>
+        [JsonPropertyName("sender_name")]
+        public StringField SenderName { get; set; }
+
+        /// <summary>
+        /// A prettier representation of the current model values.
+        /// </summary>
+        public override string ToString()
+        {
+            string recipientNames = string.Join(
+                "\n " + string.Concat(Enumerable.Repeat(" ", 17)),
+                RecipientNames.Select(item => item));
+            StringBuilder result = new StringBuilder();
+            result.Append($":Sender Name: {SenderName}\n");
+            result.Append($":Sender Address:{SenderAddress.ToFieldList()}");
+            result.Append($":Recipient Names: {recipientNames}\n");
+            result.Append($":Recipient Addresses:{RecipientAddresses}");
+            result.Append($":Return to Sender: {IsReturnToSender}\n");
+            return SummaryHelper.Clean(result.ToString());
+        }
+    }
+}