mindee 3.9.0 → 3.11.0

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

@@ -100,7 +100,7 @@ module Mindee
         attr_reader :job
         # @return [Mindee::Parsing::Common::ApiRequest]
         attr_reader :api_request
-        # @return [Hash]
+        # @return [String]
         attr_reader :raw_http
 
         # @param product_class [Class<Mindee::Product>]
@@ -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/common/ocr/mvision_v1.rb

@@ -27,6 +27,22 @@ module Mindee
             end
             out_str.strip
           end
+
+          # Constructs a line from a column, located underneath given coordinates
+          # @param coordinates [Array<Mindee::Geometry::Point>] Polygon or bounding box where the reconstruction should
+          # start.
+          # @param page_id [Integer] ID of the page to start at
+          # @param x_margin [Float] Margin of misalignment for the x coordinate.
+          # @return [Mindee::Parsing::Common::Ocr::OcrLine]
+          def reconstruct_vertically(coordinates, page_id, x_margin)
+            line_arr = OcrLine.new([])
+            @pages[page_id].all_lines.each do |line|
+              line.each do |word|
+                line_arr.push(word) if Geometry.below?(word.polygon, coordinates, x_margin / 2, x_margin * 2)
+              end
+            end
+            line_arr
+          end
         end
       end
     end

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

@@ -163,6 +163,16 @@ module Mindee
           def to_s
             @mvision_v1.to_s
           end
+
+          # Constructs a line from a column, located underneath given coordinates
+          # @param coordinates [Array<Mindee::Geometry::Point>] Polygon or bounding box where the reconstruction should
+          # start
+          # @param page_id [Integer] ID of the page to start at
+          # @param x_margin [Float] Margin of misalignment for the x coordinate (default 10%)
+          # @return [Mindee::Parsing::Common::Ocr::OcrLine]
+          def reconstruct_vertically(coordinates, page_id, x_margin = 0.05)
+            @mvision_v1.reconstruct_vertically(coordinates, page_id, x_margin)
+          end
         end
       end
     end

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/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.9.0'
+  VERSION = '3.11.0'
 
   # Finds and return the current platform.
   # @return [String]

data/lib/mindee.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'mindee/client'
+require 'mindee/extraction'
 
 module Mindee
   # Mindee internal http module.
@@ -18,6 +19,10 @@ module Mindee
     end
   end
 
+  # Custom extraction module
+  module Extraction
+  end
+
   # Parsing internals and fields.
   module Parsing
     # Common fields and functions.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mindee
 version: !ruby/object:Gem::Version
-  version: 3.9.0
+  version: 3.11.0
 platform: ruby
 authors:
 - Mindee, SA
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-05-21 00:00:00.000000000 Z
+date: 2024-06-10 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,9 +169,13 @@ 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
+- lib/mindee/extraction.rb
+- lib/mindee/extraction/ocr_extractor.rb
+- lib/mindee/extraction/tax_extractor.rb
 - lib/mindee/geometry.rb
 - lib/mindee/geometry/min_max.rb
 - lib/mindee/geometry/point.rb
@@ -183,6 +188,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 +211,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 +314,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