mindee 3.8.0 → 3.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d657be2dabdd3f93c49ead9299fa47fdad4d1afbc0115224668ffc43489b923e
-  data.tar.gz: 3f36429f4d0302573f0619818f0eb1f26177fbf839f9fbb47ed6b8d5a2abd067
+  metadata.gz: bdc0f8cc57ce32684b3da523ce0a6666a251ff90d7a6d894a7b4601231bed3e4
+  data.tar.gz: e249e12de6c86cc4a7683392504d5cd914afb941a99b5b00bff3f90fd0f4ae36
 SHA512:
-  metadata.gz: 4457a03fac7ad60960fe271d4672b17615be5e2bedc34d4b679a17ded4a52afa01cdf1d70f01efae77ff34c6f9e5ebb107098c2e33bc2055d9a7275194a95c4e
-  data.tar.gz: b2671d071bbef4afc2764f9d56a7d8e60022b403ab77b845b0e74b0f33a3ed47a8b9968308baa3595b9db220516d675250d2c20231c9403a0c3f0e74e96fc5a9
+  metadata.gz: 713cf8cb6259b54637865f6799db1f5da7d7f27c436960316f84e2d404fe743d343d2d307feb2023c0fcab580421e5e0004bc70d34735d5800f0530d135c70ea
+  data.tar.gz: 535dc099fe76a27b3af26bb5cb726756e1b158056027782b607820e2648b92dbc32e65cf453d356c33355c5b94a3df9ffbbd86fabfc18fd5f439b48efa68816c

data/.rubocop.yml

@@ -32,7 +32,7 @@ Metrics/BlockLength:
     - '**/*.gemspec'
 
 Metrics/MethodLength:
-  Max: 45
+  Max: 50
 
 Metrics/ClassLength:
   Max: 200

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Mindee Ruby API Library Changelog
 
+## v3.10.0 - 2024-05-31
+### Changes
+* :sparkles: add support for us mail v2 (#98)
+* :sparkles: add support for boolean fields
+* :sparkles: add support for webhooks (#97)
+### Fixes
+* :recycle: tweak display for LocaleField
+
+
+## v3.9.0 - 2024-05-16
+### Changes
+* :sparkles: update financial document to v1.7 & receipts to v5.2
+
+
 ## v3.8.0 - 2024-05-02
 ### Changes
 * :recycle: update products to newer syntax

data/docs/code_samples/us_mail_v2_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::UsMailV2
+)
+
+# 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

data/docs/expense_receipts_v5.md

@@ -221,6 +221,13 @@ end
 puts result.document.inference.prediction.locale.value
 ```
 
+## Receipt Number
+**receipt_number** ([StringField](#string-field)): The receipt number or identifier.
+
+```rb
+puts result.document.inference.prediction.receipt_number.value
+```
+
 ## Purchase Subcategory
 **subcategory** ([ClassificationField](#classification-field)): The purchase subcategory among predefined classes for transport and food.
 

data/docs/financial_document_v1.md

@@ -276,6 +276,13 @@ puts result.document.inference.prediction.customer_name.value
 puts result.document.inference.prediction.date.value
 ```
 
+## Document Number
+**document_number** ([StringField](#string-field)): The document number or identifier.
+
+```rb
+puts result.document.inference.prediction.document_number.value
+```
+
 ## Document Type
 **document_type** ([ClassificationField](#classification-field)): One of: 'INVOICE', 'CREDIT NOTE', 'CREDIT CARD RECEIPT', 'EXPENSE RECEIPT'.
 
@@ -291,7 +298,7 @@ puts result.document.inference.prediction.due_date.value
 ```
 
 ## Invoice Number
-**invoice_number** ([StringField](#string-field)): The invoice number or identifier.
+**invoice_number** ([StringField](#string-field)): The invoice number or identifier only if document is an invoice.
 
 ```rb
 puts result.document.inference.prediction.invoice_number.value
@@ -313,6 +320,13 @@ end
 puts result.document.inference.prediction.locale.value
 ```
 
+## Receipt Number
+**receipt_number** ([StringField](#string-field)): The receipt number or identifier only if document is a receipt.
+
+```rb
+puts result.document.inference.prediction.receipt_number.value
+```
+
 ## Reference Numbers
 **reference_numbers** (Array<[StringField](#string-field)>): List of Reference numbers, including PO number.
 

data/docs/us_mail_v2.md

@@ -0,0 +1,135 @@
+---
+title: US US Mail OCR Ruby
+---
+The Ruby OCR SDK supports the [US Mail API](https://platform.mindee.com/mindee/us_mail).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/us_mail/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![US Mail sample](https://github.com/mindee/client-lib-test-data/blob/main/products/us_mail/default_sample.jpg?raw=true)
+
+# Quick-Start
+```rb
+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::UsMailV2
+)
+
+# 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
+```
+
+**Output (RST):**
+```rst
+:Sender Name: zed
+:Sender Address:
+  :City: Dallas
+  :Complete Address: 54321 Elm Street, Dallas, Texas ...
+  :Postal Code: 54321
+  :State: TX
+  :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        |
+  +-----------------+-------------------------------------+-------------------+-------------+------------------------+-------+---------------------------+
+```
+
+# 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** (`String`, `Float`, `Integer`, `Boolean`): corresponds to the field value. Can be `nil` if no value was extracted.
+* **confidence** (Float, nil): the confidence score of the field prediction.
+* **bounding_box** (`Mindee::Geometry::Quadrilateral`, `nil`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document.
+* **polygon** (`Mindee::Geometry::Polygon`, `nil`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image.
+* **page_id** (`Integer`, `nil`): the ID of the page, is `nil` when at document-level.
+* **reconstructed** (`Boolean`): indicates whether an object was reconstructed (not extracted as the API gave it).
+
+
+Aside from the previous attributes, all basic fields have access to a `to_s` method that can be used to print their value as a string.
+
+### String Field
+The text field `StringField` only has one constraint: it's **value** is a `String` (or `nil`).
+
+## 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:
+
+* `city` (String): The city of the recipient's address.
+* `complete` (String): The complete address of the recipient.
+* `is_address_change` (Boolean): Indicates if the recipient's address is a change of address.
+* `postal_code` (String): The postal code of the recipient's address.
+* `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.
+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:
+
+* `city` (String): The city of the sender's address.
+* `complete` (String): The complete address of the sender.
+* `postal_code` (String): The postal code of the sender'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 sender's address.
+
+# Attributes
+The following fields are extracted for US Mail V2:
+
+## Recipient Addresses
+**recipient_addresses** (Array<[UsMailV2RecipientAddress](#recipient-addresses-field)>): The addresses of the recipients.
+
+```rb
+for recipient_addresses_elem in result.document.inference.prediction.recipient_addresses do
+  puts recipient_addresses_elem.value
+end
+```
+
+## Recipient Names
+**recipient_names** (Array<[StringField](#string-field)>): The names of the recipients.
+
+```rb
+for recipient_names_elem in result.document.inference.prediction.recipient_names do
+  puts recipient_names_elem.value
+end
+```
+
+## Sender Address
+**sender_address** ([UsMailV2SenderAddress](#sender-address-field)): The address of the sender.
+
+```rb
+puts result.document.inference.prediction.sender_address.value
+```
+
+## Sender Name
+**sender_name** ([StringField](#string-field)): The name of the sender.
+
+```rb
+puts result.document.inference.prediction.sender_name.value
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/lib/mindee/client.rb

@@ -182,6 +182,17 @@ module Mindee
 
     # rubocop:enable Metrics/ParameterLists
 
+    # Load a prediction.
+    #
+    # @param product_class [Mindee::Product] class of the product
+    # @param local_response [Mindee::Input::LocalResponse]
+    # @return [Mindee::Parsing::Common::ApiResponse]
+    def load_prediction(product_class, local_response)
+      Mindee::Parsing::Common::ApiResponse.new(product_class, local_response.as_hash, local_response.as_hash.to_json)
+    rescue KeyError
+      raise 'No prediction found in local response.'
+    end
+
     # Load a document from an absolute path, as a string.
     # @param input_path [String] Path of file to open
     # @param fix_pdf [Boolean] Attempts to fix broken pdf if true

data/lib/mindee/input/local_response.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'openssl'
+require 'stringio'
+require 'pathname'
+require 'tempfile'
+
+module Mindee
+  module Input
+    # Response loaded locally.
+    class LocalResponse
+      attr_reader :file
+
+      # @param input_file [File, Tempfile, IO, StringIO, String, Pathname] The input file, which can be a StringIO.
+      def initialize(input_file)
+        case input_file
+        when IO, StringIO, File, Tempfile
+          str_stripped = input_file.read.gsub(%r{[\r\n]}, '')
+          @file = StringIO.new(str_stripped)
+          @file.rewind
+        when Pathname, String
+          @file = if Pathname(input_file).exist?
+                    StringIO.new(File.read(input_file, encoding: 'utf-8').gsub(%r{[\r\n]}, ''))
+                  else
+                    StringIO.new(input_file.gsub(%r{[\r\n]}, ''))
+                  end
+          @file.rewind
+        else
+          raise "Incompatible type for input '#{input_file.class}'."
+        end
+      end
+
+      # Returns the file as a hash.
+      # @return [Hash]
+      def as_hash
+        @file.rewind
+        file_str = @file.read
+        JSON.parse(file_str, object_class: Hash)
+      rescue JSON::ParserError
+        raise "File is not a valid dict. #{file_str}"
+      end
+
+      # Processes the secret key
+      # @param secret_key [String] the secret key as plain text.
+      # @return [String]
+      def self.process_secret_key(secret_key)
+        secret_key.is_a?(String) ? secret_key.encode('utf-8') : secret_key
+      end
+
+      # @param [String] secret_key [String] Secret key, either a string or a byte/byte array.
+      # @return [String]
+      def get_hmac_signature(secret_key)
+        algorithm = OpenSSL::Digest.new('sha256')
+        begin
+          @file.rewind
+          mac = OpenSSL::HMAC.hexdigest(algorithm, self.class.process_secret_key(secret_key), @file.read)
+        rescue StandardError
+          raise 'Could not get HMAC signature from payload.'
+        end
+        mac
+      end
+
+      # @param secret_key [String] Secret key, either a string or a byte/byte array.
+      # @param signature [String]
+      # @return [Boolean]
+      def valid_hmac_signature?(secret_key, signature)
+        signature == get_hmac_signature(secret_key)
+      end
+    end
+  end
+end

data/lib/mindee/input/sources.rb

@@ -166,11 +166,11 @@ module Mindee
 
       # Load a document from a file handle.
       class FileInputSource < LocalInputSource
-        # @param file_handle [String]
+        # @param input_file [File]
         # @param filename [String]
         # @param fix_pdf [Boolean]
-        def initialize(file_handle, filename, fix_pdf: false)
-          io_stream = file_handle
+        def initialize(input_file, filename, fix_pdf: false)
+          io_stream = input_file
           super(io_stream, filename, fix_pdf: fix_pdf)
         end
       end

data/lib/mindee/parsing/common/api_response.rb

@@ -108,9 +108,10 @@ module Mindee
         # @param raw_http [String]
         def initialize(product_class, http_response, raw_http)
           @raw_http = raw_http.to_s
-          if http_response.key?('api_request')
-            @api_request = Mindee::Parsing::Common::ApiRequest.new(http_response['api_request'])
-          end
+          raise 'Invalid response format.' unless http_response.key?('api_request')
+
+          @api_request = Mindee::Parsing::Common::ApiRequest.new(http_response['api_request'])
+
           if http_response.key?('document') &&
              (!http_response.key?('job') ||
                http_response['job']['status'] == 'completed') &&

data/lib/mindee/parsing/standard/base_field.rb

@@ -89,10 +89,12 @@ module Mindee
       # Feature field object wrapper for specialized methods.
       class FeatureField < AbstractField
         # Format strings for display by shortening long strings and assigning empty ones.
-        # @param in_str [String, nil]
+        # @param in_str [String, Boolean, nil]
         # @param max_col_size [int, nil]
         # @return [String]
         def format_for_display(in_str, max_col_size = nil)
+          return 'True' if in_str == true
+          return 'False' if in_str == false
           return '' if in_str.nil?
           return in_str if max_col_size.nil?
 

data/lib/mindee/parsing/standard/boolean_field.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'base_field'
+
+module Mindee
+  module Parsing
+    module Standard
+      # Represents basic text information.
+      class BooleanField < Field
+        # Value as Boolean
+        # @return [Boolean, nil]
+        attr_reader :value
+
+        def initialize(prediction, page_id = nil, reconstructed: false)
+          super
+        end
+      end
+    end
+  end
+end

data/lib/mindee/parsing/standard/locale_field.rb

@@ -23,10 +23,10 @@ module Mindee
 
         # @param prediction [Hash]
         def initialize(prediction, _page_id = nil)
-          value_key = if prediction.include? 'value'
-                        'value'
-                      else
+          value_key = if !prediction.include?('value') || prediction['value'].nil?
                         'language'
+                      else
+                        'value'
                       end
           @confidence = prediction['confidence']
           @value = prediction[value_key]
@@ -38,7 +38,7 @@ module Mindee
         # @return [String]
         def to_s
           out_str = String.new
-          out_str << "#{@value}; " if @value
+          out_str << "#{@value}; " unless @value.nil?
           out_str << "#{@language}; " if @language
           out_str << "#{@country}; " if @country
           out_str << "#{@currency}; " if @currency

data/lib/mindee/parsing/standard.rb

@@ -2,6 +2,7 @@
 
 require_relative 'standard/amount_field'
 require_relative 'standard/base_field'
+require_relative 'standard/boolean_field'
 require_relative 'standard/classification_field'
 require_relative 'standard/company_registration_field'
 require_relative 'standard/date_field'

data/lib/mindee/product/financial_document/financial_document_v1_document.rb

@@ -6,7 +6,7 @@ require_relative 'financial_document_v1_line_item'
 module Mindee
   module Product
     module FinancialDocument
-      # Financial Document API version 1.6 document data.
+      # Financial Document API version 1.7 document data.
       class FinancialDocumentV1Document < Mindee::Parsing::Common::Prediction
         include Mindee::Parsing::Standard
         # The customer's address used for billing.
@@ -30,13 +30,16 @@ module Mindee
         # The date the purchase was made.
         # @return [Mindee::Parsing::Standard::DateField]
         attr_reader :date
+        # The document number or identifier.
+        # @return [Mindee::Parsing::Standard::StringField]
+        attr_reader :document_number
         # One of: 'INVOICE', 'CREDIT NOTE', 'CREDIT CARD RECEIPT', 'EXPENSE RECEIPT'.
         # @return [Mindee::Parsing::Standard::ClassificationField]
         attr_reader :document_type
         # The date on which the payment is due.
         # @return [Mindee::Parsing::Standard::DateField]
         attr_reader :due_date
-        # The invoice number or identifier.
+        # The invoice number or identifier only if document is an invoice.
         # @return [Mindee::Parsing::Standard::StringField]
         attr_reader :invoice_number
         # List of line item details.
@@ -45,6 +48,9 @@ module Mindee
         # The locale detected on the document.
         # @return [Mindee::Parsing::Standard::LocaleField]
         attr_reader :locale
+        # The receipt number or identifier only if document is a receipt.
+        # @return [Mindee::Parsing::Standard::StringField]
+        attr_reader :receipt_number
         # List of Reference numbers, including PO number.
         # @return [Array<Mindee::Parsing::Standard::StringField>]
         attr_reader :reference_numbers
@@ -108,6 +114,7 @@ module Mindee
           @customer_id = StringField.new(prediction['customer_id'], page_id)
           @customer_name = StringField.new(prediction['customer_name'], page_id)
           @date = DateField.new(prediction['date'], page_id)
+          @document_number = StringField.new(prediction['document_number'], page_id)
           @document_type = ClassificationField.new(prediction['document_type'], page_id)
           @due_date = DateField.new(prediction['due_date'], page_id)
           @invoice_number = StringField.new(prediction['invoice_number'], page_id)
@@ -116,6 +123,7 @@ module Mindee
             @line_items.push(FinancialDocumentV1LineItem.new(item, page_id))
           end
           @locale = LocaleField.new(prediction['locale'], page_id)
+          @receipt_number = StringField.new(prediction['receipt_number'], page_id)
           @reference_numbers = []
           prediction['reference_numbers'].each do |item|
             @reference_numbers.push(StringField.new(item, page_id))
@@ -153,6 +161,8 @@ module Mindee
           out_str = String.new
           out_str << "\n:Locale: #{@locale}".rstrip
           out_str << "\n:Invoice Number: #{@invoice_number}".rstrip
+          out_str << "\n:Receipt Number: #{@receipt_number}".rstrip
+          out_str << "\n:Document Number: #{@document_number}".rstrip
           out_str << "\n:Reference Numbers: #{reference_numbers}".rstrip
           out_str << "\n:Purchase Date: #{@date}".rstrip
           out_str << "\n:Due Date: #{@due_date}".rstrip

data/lib/mindee/product/financial_document/financial_document_v1_page.rb

@@ -6,7 +6,7 @@ require_relative 'financial_document_v1_document'
 module Mindee
   module Product
     module FinancialDocument
-      # Financial Document API version 1.6 page data.
+      # Financial Document API version 1.7 page data.
       class FinancialDocumentV1Page < Mindee::Parsing::Common::Page
         # @param prediction [Hash]
         def initialize(prediction)

data/lib/mindee/product/receipt/receipt_v5_document.rb

@@ -6,7 +6,7 @@ require_relative 'receipt_v5_line_item'
 module Mindee
   module Product
     module Receipt
-      # Receipt API version 5.1 document data.
+      # Receipt API version 5.2 document data.
       class ReceiptV5Document < Mindee::Parsing::Common::Prediction
         include Mindee::Parsing::Standard
         # The purchase category among predefined classes.
@@ -24,6 +24,9 @@ module Mindee
         # The locale detected on the document.
         # @return [Mindee::Parsing::Standard::LocaleField]
         attr_reader :locale
+        # The receipt number or identifier.
+        # @return [Mindee::Parsing::Standard::StringField]
+        attr_reader :receipt_number
         # The purchase subcategory among predefined classes for transport and food.
         # @return [Mindee::Parsing::Standard::ClassificationField]
         attr_reader :subcategory
@@ -70,6 +73,7 @@ module Mindee
             @line_items.push(ReceiptV5LineItem.new(item, page_id))
           end
           @locale = LocaleField.new(prediction['locale'], page_id)
+          @receipt_number = StringField.new(prediction['receipt_number'], page_id)
           @subcategory = ClassificationField.new(prediction['subcategory'], page_id)
           @supplier_address = StringField.new(prediction['supplier_address'], page_id)
           @supplier_company_registrations = []
@@ -106,6 +110,7 @@ module Mindee
           out_str << "\n:Supplier Company Registrations: #{supplier_company_registrations}".rstrip
           out_str << "\n:Supplier Address: #{@supplier_address}".rstrip
           out_str << "\n:Supplier Phone Number: #{@supplier_phone_number}".rstrip
+          out_str << "\n:Receipt Number: #{@receipt_number}".rstrip
           out_str << "\n:Line Items:"
           out_str << line_items
           out_str[1..].to_s

data/lib/mindee/product/receipt/receipt_v5_page.rb

@@ -6,7 +6,7 @@ require_relative 'receipt_v5_document'
 module Mindee
   module Product
     module Receipt
-      # Receipt API version 5.1 page data.
+      # Receipt API version 5.2 page data.
       class ReceiptV5Page < Mindee::Parsing::Common::Page
         # @param prediction [Hash]
         def initialize(prediction)

data/lib/mindee/product/us/us_mail/us_mail_v2.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative '../../../parsing'
+require_relative 'us_mail_v2_document'
+require_relative 'us_mail_v2_page'
+
+module Mindee
+  module Product
+    module US
+      # US Mail module.
+      module UsMail
+        # US Mail API version 2 inference prediction.
+        class UsMailV2 < Mindee::Parsing::Common::Inference
+          @endpoint_name = 'us_mail'
+          @endpoint_version = '2'
+
+          # @param prediction [Hash]
+          def initialize(prediction)
+            super
+            @prediction = UsMailV2Document.new(prediction['prediction'], nil)
+            @pages = []
+            prediction['pages'].each do |page|
+              if page.key?('prediction') && !page['prediction'].nil? && !page['prediction'].empty?
+                @pages.push(UsMailV2Page.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

data/lib/mindee/product/us/us_mail/us_mail_v2_document.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative '../../../parsing'
+require_relative 'us_mail_v2_sender_address'
+require_relative 'us_mail_v2_recipient_address'
+
+module Mindee
+  module Product
+    module US
+      module UsMail
+        # US Mail API version 2.0 document data.
+        class UsMailV2Document < Mindee::Parsing::Common::Prediction
+          include Mindee::Parsing::Standard
+          # The addresses of the recipients.
+          # @return [Array<Mindee::Product::US::UsMail::UsMailV2RecipientAddress>]
+          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::UsMailV2SenderAddress]
+          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()
+            @recipient_addresses = []
+            prediction['recipient_addresses'].each do |item|
+              @recipient_addresses.push(UsMailV2RecipientAddress.new(item, page_id))
+            end
+            @recipient_names = []
+            prediction['recipient_names'].each do |item|
+              @recipient_names.push(StringField.new(item, page_id))
+            end
+            @sender_address = UsMailV2SenderAddress.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[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 << '+'
+            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 << "\n#{recipient_addresses_separator('=')}"
+            out_str << "\n  #{line_items}"
+            out_str << "\n#{recipient_addresses_separator('-')}"
+            out_str
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mindee/product/us/us_mail/us_mail_v2_page.rb

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

data/lib/mindee/product/us/us_mail/us_mail_v2_recipient_address.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative '../../../parsing'
+
+module Mindee
+  module Product
+    module US
+      module UsMail
+        # The addresses of the recipients.
+        class UsMailV2RecipientAddress < Mindee::Parsing::Standard::FeatureField
+          include Mindee::Parsing::Standard
+          # The city of the recipient's address.
+          # @return [String]
+          attr_reader :city
+          # The complete address of the recipient.
+          # @return [String]
+          attr_reader :complete
+          # Indicates if the recipient's address is a change of address.
+          # @return [Boolean]
+          attr_reader :is_address_change
+          # The postal code of the recipient's address.
+          # @return [String]
+          attr_reader :postal_code
+          # The private mailbox number of the recipient's address.
+          # @return [String]
+          attr_reader :private_mailbox_number
+          # Second part of the ISO 3166-2 code, consisting of two letters indicating the US State.
+          # @return [String]
+          attr_reader :state
+          # The street of the recipient's address.
+          # @return [String]
+          attr_reader :street
+
+          # @param prediction [Hash]
+          # @param page_id [Integer, nil]
+          def initialize(prediction, page_id)
+            super(prediction, page_id)
+            @city = prediction['city']
+            @complete = prediction['complete']
+            @is_address_change = prediction['is_address_change']
+            @postal_code = prediction['postal_code']
+            @private_mailbox_number = prediction['private_mailbox_number']
+            @state = prediction['state']
+            @street = prediction['street']
+            @page_id = page_id
+          end
+
+          # @return [Hash]
+          def printable_values
+            printable = {}
+            printable[:city] = format_for_display(@city, 15)
+            printable[:complete] = format_for_display(@complete, 35)
+            printable[:is_address_change] = format_for_display(@is_address_change, nil)
+            printable[:postal_code] = format_for_display(@postal_code, nil)
+            printable[:private_mailbox_number] = format_for_display(@private_mailbox_number, nil)
+            printable[:state] = format_for_display(@state, nil)
+            printable[:street] = format_for_display(@street, 25)
+            printable
+          end
+
+          # @return [String]
+          def to_table_line
+            printable = printable_values
+            out_str = String.new
+            out_str << format('| %- 16s', printable[:city])
+            out_str << format('| %- 36s', printable[:complete])
+            out_str << format('| %- 18s', printable[:is_address_change])
+            out_str << format('| %- 12s', printable[:postal_code])
+            out_str << format('| %- 23s', printable[:private_mailbox_number])
+            out_str << format('| %- 6s', printable[:state])
+            out_str << format('| %- 26s', printable[:street])
+            out_str << '|'
+          end
+
+          # @return [String]
+          def to_s
+            printable = printable_values
+            out_str = String.new
+            out_str << "\n  :City: #{printable[:city]}"
+            out_str << "\n  :Complete Address: #{printable[:complete]}"
+            out_str << "\n  :Is Address Change: #{printable[:is_address_change]}"
+            out_str << "\n  :Postal Code: #{printable[:postal_code]}"
+            out_str << "\n  :Private Mailbox Number: #{printable[:private_mailbox_number]}"
+            out_str << "\n  :State: #{printable[:state]}"
+            out_str << "\n  :Street: #{printable[:street]}"
+            out_str
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mindee/product/us/us_mail/us_mail_v2_sender_address.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative '../../../parsing'
+
+module Mindee
+  module Product
+    module US
+      module UsMail
+        # The address of the sender.
+        class UsMailV2SenderAddress < Mindee::Parsing::Standard::FeatureField
+          include Mindee::Parsing::Standard
+          # The city of the sender's address.
+          # @return [String]
+          attr_reader :city
+          # The complete address of the sender.
+          # @return [String]
+          attr_reader :complete
+          # The postal code of the sender's address.
+          # @return [String]
+          attr_reader :postal_code
+          # Second part of the ISO 3166-2 code, consisting of two letters indicating the US State.
+          # @return [String]
+          attr_reader :state
+          # The street of the sender's address.
+          # @return [String]
+          attr_reader :street
+
+          # @param prediction [Hash]
+          # @param page_id [Integer, nil]
+          def initialize(prediction, page_id)
+            super(prediction, page_id)
+            @city = prediction['city']
+            @complete = prediction['complete']
+            @postal_code = prediction['postal_code']
+            @state = prediction['state']
+            @street = prediction['street']
+            @page_id = page_id
+          end
+
+          # @return [Hash]
+          def printable_values
+            printable = {}
+            printable[:city] = format_for_display(@city, 15)
+            printable[:complete] = format_for_display(@complete, 35)
+            printable[:postal_code] = format_for_display(@postal_code, nil)
+            printable[:state] = format_for_display(@state, nil)
+            printable[:street] = format_for_display(@street, 25)
+            printable
+          end
+
+          # @return [String]
+          def to_table_line
+            printable = printable_values
+            out_str = String.new
+            out_str << format('| %- 16s', printable[:city])
+            out_str << format('| %- 36s', printable[:complete])
+            out_str << format('| %- 12s', printable[:postal_code])
+            out_str << format('| %- 6s', printable[:state])
+            out_str << format('| %- 26s', printable[:street])
+            out_str << '|'
+          end
+
+          # @return [String]
+          def to_s
+            printable = printable_values
+            out_str = String.new
+            out_str << "\n  :City: #{printable[:city]}"
+            out_str << "\n  :Complete Address: #{printable[:complete]}"
+            out_str << "\n  :Postal Code: #{printable[:postal_code]}"
+            out_str << "\n  :State: #{printable[:state]}"
+            out_str << "\n  :Street: #{printable[:street]}"
+            out_str
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mindee/product.rb

@@ -26,4 +26,5 @@ require_relative 'product/international_id/international_id_v2'
 require_relative 'product/resume/resume_v1'
 require_relative 'product/us/bank_check/bank_check_v1'
 require_relative 'product/us/driver_license/driver_license_v1'
+require_relative 'product/us/us_mail/us_mail_v2'
 require_relative 'product/us/w9/w9_v1'

data/lib/mindee/version.rb

@@ -3,7 +3,7 @@
 # Mindee
 module Mindee
   # Current version.
-  VERSION = '3.8.0'
+  VERSION = '3.10.0'
 
   # Finds and return the current platform.
   # @return [String]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mindee
 version: !ruby/object:Gem::Version
-  version: 3.8.0
+  version: 3.10.0
 platform: ruby
 authors:
 - Mindee, SA
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-05-02 00:00:00.000000000 Z
+date: 2024-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: marcel
@@ -150,6 +150,7 @@ files:
 - docs/code_samples/proof_of_address_v1.txt
 - docs/code_samples/resume_v1_async.txt
 - docs/code_samples/us_driver_license_v1.txt
+- docs/code_samples/us_mail_v2_async.txt
 - docs/code_samples/us_w9_v1.txt
 - docs/cropper_v1.md
 - docs/custom_v1.md
@@ -168,6 +169,7 @@ files:
 - docs/proof_of_address_v1.md
 - docs/resume_v1.md
 - docs/us_driver_license_v1.md
+- docs/us_mail_v2.md
 - docs/us_w9_v1.md
 - lib/mindee.rb
 - lib/mindee/client.rb
@@ -183,6 +185,7 @@ files:
 - lib/mindee/http/error.rb
 - lib/mindee/http/response_validation.rb
 - lib/mindee/input.rb
+- lib/mindee/input/local_response.rb
 - lib/mindee/input/sources.rb
 - lib/mindee/parsing.rb
 - lib/mindee/parsing/common.rb
@@ -205,6 +208,7 @@ files:
 - lib/mindee/parsing/standard.rb
 - lib/mindee/parsing/standard/amount_field.rb
 - lib/mindee/parsing/standard/base_field.rb
+- lib/mindee/parsing/standard/boolean_field.rb
 - lib/mindee/parsing/standard/classification_field.rb
 - lib/mindee/parsing/standard/company_registration_field.rb
 - lib/mindee/parsing/standard/date_field.rb
@@ -307,6 +311,11 @@ files:
 - lib/mindee/product/us/driver_license/driver_license_v1.rb
 - lib/mindee/product/us/driver_license/driver_license_v1_document.rb
 - lib/mindee/product/us/driver_license/driver_license_v1_page.rb
+- lib/mindee/product/us/us_mail/us_mail_v2.rb
+- lib/mindee/product/us/us_mail/us_mail_v2_document.rb
+- lib/mindee/product/us/us_mail/us_mail_v2_page.rb
+- lib/mindee/product/us/us_mail/us_mail_v2_recipient_address.rb
+- lib/mindee/product/us/us_mail/us_mail_v2_sender_address.rb
 - lib/mindee/product/us/w9/w9_v1.rb
 - lib/mindee/product/us/w9/w9_v1_document.rb
 - lib/mindee/product/us/w9/w9_v1_page.rb