✨ add support for US Mail V3 (#135)

Author: sebastianMindee

docs/code_samples/us_mail_v3_async.txt

@@ -0,0 +1,19 @@
+require 'mindee'
+
+# Init a new client
+mindee_client = Mindee::Client.new(api_key: 'my-api-key')
+
+# Load a file from disk
+input_source = mindee_client.source_from_path('/path/to/the/file.ext')
+
+# Parse the file
+result = mindee_client.enqueue_and_parse(
+  input_source,
+  Mindee::Product::US::UsMail::UsMailV3
+)
+
+# Print a full summary of the parsed data in RST format
+puts result.document
+
+# Print the document-level parsed data
+# puts result.document.inference.prediction

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

@@ -22,7 +22,7 @@ input_source = mindee_client.source_from_path('/path/to/the/file.ext')
 # Parse the file
 result = mindee_client.enqueue_and_parse(
   input_source,
-  Mindee::Product::US::UsMail::UsMailV2
+  Mindee::Product::US::UsMail::UsMailV3
 )
 
 # Print a full summary of the parsed data in RST format
@@ -35,7 +35,20 @@ puts result.document
 
 **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
@@ -44,11 +57,12 @@ puts result.document
   :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,7 +92,7 @@ Fields which are specific to this product; they are not used in any other produc
 ### 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.
@@ -87,12 +101,13 @@ A `UsMailV2RecipientAddress` implements the following attributes:
 * `private_mailbox_number` (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.
@@ -101,10 +116,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
+**is_return_to_sender** ([BooleanField](#boolean-field)): Whether the mailing is marked as return to sender.
+
+```rb
+puts result.document.inference.prediction.is_return_to_sender.value
+```
 
 ## Recipient Addresses
-**recipient_addresses** (Array<[UsMailV2RecipientAddress](#recipient-addresses-field)>): The addresses of the recipients.
+**recipient_addresses** (Array<[UsMailV3RecipientAddress](#recipient-addresses-field)>): The addresses of the recipients.
 
 ```rb
 for recipient_addresses_elem in result.document.inference.prediction.recipient_addresses do
@@ -122,7 +144,7 @@ end
 ```
 
 ## Sender Address
-**sender_address** ([UsMailV2SenderAddress](#sender-address-field)): The address of the sender.
+**sender_address** ([UsMailV3SenderAddress](#sender-address-field)): The address of the sender.
 
 ```rb
 puts result.document.inference.prediction.sender_address.value

lib/mindee/parsing/standard/boolean_field.rb

@@ -14,6 +14,12 @@ class BooleanField < Field
         def initialize(prediction, page_id = nil, reconstructed: false)
           super
         end
+
+        def to_s
+          return '' if value.nil?
+
+          value ? 'True' : 'False'
+        end
       end
     end
   end

lib/mindee/product.rb

@@ -36,4 +36,5 @@
 require_relative 'product/us/driver_license/driver_license_v1'
 require_relative 'product/us/healthcare_card/healthcare_card_v1'
 require_relative 'product/us/us_mail/us_mail_v2'
+require_relative 'product/us/us_mail/us_mail_v3'
 require_relative 'product/us/w9/w9_v1'

lib/mindee/product/ind/indian_passport/indian_passport_v1_document.rb

@@ -6,7 +6,7 @@ module Mindee
   module Product
     module IND
       module IndianPassport
-        # Passport - India API version 1.0 document data.
+        # Passport - India API version 1.2 document data.
         class IndianPassportV1Document < Mindee::Parsing::Common::Prediction
           include Mindee::Parsing::Standard
           # The first line of the address of the passport holder.

lib/mindee/product/ind/indian_passport/indian_passport_v1_page.rb

@@ -7,7 +7,7 @@ module Mindee
   module Product
     module IND
       module IndianPassport
-        # Passport - India API version 1.0 page data.
+        # Passport - India API version 1.2 page data.
         class IndianPassportV1Page < Mindee::Parsing::Common::Page
           # @param prediction [Hash]
           def initialize(prediction)

lib/mindee/product/us/us_mail/us_mail_v3.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative '../../../parsing'
+require_relative 'us_mail_v3_document'
+require_relative 'us_mail_v3_page'
+
+module Mindee
+  module Product
+    module US
+      # US Mail module.
+      module UsMail
+        # US Mail API version 3 inference prediction.
+        class UsMailV3 < Mindee::Parsing::Common::Inference
+          @endpoint_name = 'us_mail'
+          @endpoint_version = '3'
+
+          # @param prediction [Hash]
+          def initialize(prediction)
+            super
+            @prediction = UsMailV3Document.new(prediction['prediction'], nil)
+            @pages = []
+            prediction['pages'].each do |page|
+              if page.key?('prediction') && !page['prediction'].nil? && !page['prediction'].empty?
+                @pages.push(UsMailV3Page.new(page))
+              end
+            end
+          end
+
+          class << self
+            # Name of the endpoint for this product.
+            # @return [String]
+            attr_reader :endpoint_name
+            # Version for this product.
+            # @return [String]
+            attr_reader :endpoint_version
+          end
+        end
+      end
+    end
+  end
+end

lib/mindee/product/us/us_mail/us_mail_v3_document.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative '../../../parsing'
+require_relative 'us_mail_v3_sender_address'
+require_relative 'us_mail_v3_recipient_address'
+
+module Mindee
+  module Product
+    module US
+      module UsMail
+        # US Mail API version 3.0 document data.
+        class UsMailV3Document < Mindee::Parsing::Common::Prediction
+          include Mindee::Parsing::Standard
+          # Whether the mailing is marked as return to sender.
+          # @return [Mindee::Parsing::Standard::BooleanField]
+          attr_reader :is_return_to_sender
+          # The addresses of the recipients.
+          # @return [Array<Mindee::Product::US::UsMail::UsMailV3RecipientAddress>]
+          attr_reader :recipient_addresses
+          # The names of the recipients.
+          # @return [Array<Mindee::Parsing::Standard::StringField>]
+          attr_reader :recipient_names
+          # The address of the sender.
+          # @return [Mindee::Product::US::UsMail::UsMailV3SenderAddress]
+          attr_reader :sender_address
+          # The name of the sender.
+          # @return [Mindee::Parsing::Standard::StringField]
+          attr_reader :sender_name
+
+          # @param prediction [Hash]
+          # @param page_id [Integer, nil]
+          def initialize(prediction, page_id)
+            super()
+            @is_return_to_sender = BooleanField.new(prediction['is_return_to_sender'], page_id)
+            @recipient_addresses = []
+            prediction['recipient_addresses'].each do |item|
+              @recipient_addresses.push(UsMailV3RecipientAddress.new(item, page_id))
+            end
+            @recipient_names = []
+            prediction['recipient_names'].each do |item|
+              @recipient_names.push(StringField.new(item, page_id))
+            end
+            @sender_address = UsMailV3SenderAddress.new(prediction['sender_address'], page_id)
+            @sender_name = StringField.new(prediction['sender_name'], page_id)
+          end
+
+          # @return [String]
+          def to_s
+            sender_address = @sender_address.to_s
+            recipient_names = @recipient_names.join("\n #{' ' * 17}")
+            recipient_addresses = recipient_addresses_to_s
+            out_str = String.new
+            out_str << "\n:Sender Name: #{@sender_name}".rstrip
+            out_str << "\n:Sender Address:"
+            out_str << sender_address
+            out_str << "\n:Recipient Names: #{recipient_names}".rstrip
+            out_str << "\n:Recipient Addresses:"
+            out_str << recipient_addresses
+            out_str << "\n:Return to Sender: #{@is_return_to_sender}".rstrip
+            out_str[1..].to_s
+          end
+
+          private
+
+          # @param char [String]
+          # @return [String]
+          def recipient_addresses_separator(char)
+            out_str = String.new
+            out_str << '  '
+            out_str << "+#{char * 17}"
+            out_str << "+#{char * 37}"
+            out_str << "+#{char * 19}"
+            out_str << "+#{char * 13}"
+            out_str << "+#{char * 24}"
+            out_str << "+#{char * 7}"
+            out_str << "+#{char * 27}"
+            out_str << "+#{char * 17}"
+            out_str << '+'
+            out_str
+          end
+
+          # @return [String]
+          def recipient_addresses_to_s
+            return '' if @recipient_addresses.empty?
+
+            line_items = @recipient_addresses.map(&:to_table_line).join("\n#{recipient_addresses_separator('-')}\n  ")
+            out_str = String.new
+            out_str << "\n#{recipient_addresses_separator('-')}"
+            out_str << "\n  |"
+            out_str << ' City            |'
+            out_str << ' Complete Address                    |'
+            out_str << ' Is Address Change |'
+            out_str << ' Postal Code |'
+            out_str << ' Private Mailbox Number |'
+            out_str << ' State |'
+            out_str << ' Street                    |'
+            out_str << ' Unit            |'
+            out_str << "\n#{recipient_addresses_separator('=')}"
+            out_str << "\n  #{line_items}"
+            out_str << "\n#{recipient_addresses_separator('-')}"
+            out_str
+          end
+        end
+      end
+    end
+  end
+end

lib/mindee/product/us/us_mail/us_mail_v3_page.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative '../../../parsing'
+require_relative 'us_mail_v3_document'
+
+module Mindee
+  module Product
+    module US
+      module UsMail
+        # US Mail API version 3.0 page data.
+        class UsMailV3Page < Mindee::Parsing::Common::Page
+          # @param prediction [Hash]
+          def initialize(prediction)
+            super(prediction)
+            @prediction = UsMailV3PagePrediction.new(
+              prediction['prediction'],
+              prediction['id']
+            )
+          end
+        end
+
+        # US Mail V3 page prediction.
+        class UsMailV3PagePrediction < UsMailV3Document
+          # @return [String]
+          def to_s
+            out_str = String.new
+            out_str << "\n#{super}"
+            out_str
+          end
+        end
+      end
+    end
+  end
+end