mindee 3.6.0 → 3.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28d1e6c48c575030a3c6519080f7cff23b52745c212d8db9cc43f8c800c1c3d8
-  data.tar.gz: a96015beeeac1378f72f77bd3bcb73c3032e0946e39cc7a4519b5db3eca3e8c4
+  metadata.gz: d18b48dabb484d078d9fe9ccbe4266d80fde752fb261c13ec6143e69c0ebe0c8
+  data.tar.gz: 9340689c20fa1d161461252a379f0754fe7482dbac8fb89407845fc501ac4ae1
 SHA512:
-  metadata.gz: 2ca08ce6349eb1ebeaf7cf2bbba6004ff638cfc0db480d7b41bf183f6f6a4066bd1a76a36edbf4282eb65f31c89487cad388cc1f2ea6bfa2bb6bed7ff6c6e517
-  data.tar.gz: e18f1c1f8190c73987b036745fba0e6dca91b98ee71bc6144d8f1612be4c497cbb5f0301951b91db494c4812ca07ef6ec86fdeee17bdb3e83aacaef481b2fb3f
+  metadata.gz: c74414360e4f02582286e8e49e1fbff59dbc654c75876717268f6f3805c7dfbfbd14729828dde8a86d53b8fcbe3eaca0bf0c988dd66919d54c9cfbc719e6b49f
+  data.tar.gz: d14ac158a9d719cdfe2f5ecc5ba0b6a16eb6bae3ce83474a285be980cb00791acfe0e71aa9bb6dbd17945264168ce19f7e5ca75746083994d8a8d0927d76b43f

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Mindee Ruby API Library Changelog
 
+## v3.6.1 - 2024-03-07
+### Changes
+* :recycle: update error handling to account for future evolutions
+* :memo: update miscellaneous product documentations
+* :memo: add used environment variables to readme
+
+
 ## v3.6.0 - 2024-02-21
 ### Changes
 * :sparkles: add support for resume V1

data/README.md

@@ -1,12 +1,15 @@
 [![License: MIT](https://img.shields.io/github/license/mindee/mindee-api-ruby)](https://opensource.org/licenses/MIT) [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/mindee/mindee-api-ruby/test.yml)](https://github.com/mindee/mindee-api-ruby) [![Gem Version](https://img.shields.io/gem/v/mindee)](https://rubygems.org/gems/mindee) [![Downloads](https://img.shields.io/gem/dt/mindee.svg)](https://rubygems.org/gems/mindee)
 
 # Mindee API Helper Library for Ruby
+
 Quickly and easily connect to Mindee's API services using Ruby.
 
 ## Requirements
+
 The following Ruby versions are tested and supported: 2.6, 2.7, 3.0, 3.1, 3.2
 
 ## Quick Start
+
 Here's the TL;DR of getting started.
 
 First, get an [API Key](https://developers.mindee.com/docs/create-api-key)
@@ -18,15 +21,38 @@ gem 'mindee'
 ```
 
 And then execute:
+
 ```sh
 bundle install
 ```
 
 Finally, Ruby away!
 
+### Environment Variables
+
+This library offers customizable features through environment variables. While there may be instances where you need to
+rely on them, it's crucial to exercise caution when modifying them to avoid unintended consequences.
+
+If you're unsure whether you need to adjust these variables, it's advisable to refrain from doing so unless you have a
+specific reason. Accidentally overwriting them can lead to unexpected behavior.
+
+Before making any changes, we recommend reviewing the following information to understand the purpose and potential
+impact of each environment variable:
+
+* `MINDEE_API_KEY`: 
+  * **Description**: Your personal Mindee API Key as shown on the platform. Be careful not to show this publicly!
+  * **Default Value**: `nil`
+* `MINDEE_BASE_URL`:
+  * **Description**: The default base URL of the API endpoint. Use this variable to specify the root URL for API requests. Modify as needed for proxy configurations or changes in API endpoint location.
+  * **Default Value**: `https://api.mindee.net/v1`
+* `MINDEE_REQUEST_TIMEOUT`:
+  * **Description**: The default timeout for HTTP requests (in seconds).
+  * **Default Value**: `120`
+
 ### Loading a File and Parsing It
 
 #### Global Documents
+
 ```ruby
 require 'mindee'
 
@@ -47,26 +73,31 @@ puts result.document
 **Note:** Files can also be loaded from:
 
 A URL (`https`):
+
 ```rb
 input_source = mindee_client.source_from_url("https://my-url")
 ```
 
 A bytes input stream:
+
 ```rb
 input_source = mindee_client.source_from_bytes('/path/to/the/file.ext', "name-of-my-file.ext")
 ```
 
 A base64 encoded string:
+
 ```rb
 input_source = mindee_client.source_from_b64string('/path/to/the/file.ext', "name-of-my-file.ext")
 ```
 
 A ruby `file` object:
+
 ```rb
 input_source = mindee_client.source_from_file(input_file, "name-of-my-file.ext")
 ```
 
 #### Region-Specific Documents
+
 ```ruby
 require 'mindee'
 
@@ -86,6 +117,7 @@ puts result.document
 ```
 
 ### Custom Document (API Builder)
+
 ```ruby
 require 'mindee'
 
@@ -119,17 +151,19 @@ end
 ## CLI Tool
 
 A command-line interface tool is available to quickly test documents:
+
 ```sh
 ruby ./bin/mindee.rb invoice path/to/your/file.ext
 ```
 
-
 Using the ruby bundler:
+
 ```sh
 bundle exec ruby ./bin/mindee.rb invoice path/to/your/file.ext
 ```
 
 ## Further Reading
+
 There's more to it than that for those that need more features, or want to
 customize the experience.
 
@@ -157,15 +191,15 @@ customize the experience.
 * [Invoice Splitter API Ruby](https://developers.mindee.com/docs/invoice-splitter-api-ruby)
 * [Multi Receipts Detector API Ruby](https://developers.mindee.com/docs/multi-receipts-detector-api-ruby)
 
-
 You can also take a look at the
 [Reference Documentation](https://mindee.github.io/mindee-api-ruby/).
 
-
 ## License
+
 Copyright © Mindee, SA
 
 Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Questions?
+
 [Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/international_id_v2.md

@@ -31,6 +31,37 @@ puts result.document
 
 **Output (RST):**
 ```rst
+########
+Document
+########
+:Mindee ID: cfa20a58-20cf-43b6-8cec-9505fa69d1c2
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/international_id v2.0
+:Rotation applied: No
+
+Prediction
+==========
+:Document Type: IDENTIFICATION_CARD
+:Document Number: 12345678A
+:Surnames: MUESTRA
+           MUESTRA
+:Given Names: CARMEN
+:Sex: F
+:Birth Date: 1980-01-01
+:Birth Place: CAMPO DE CRIPTANA CIUDAD REAL ESPANA
+:Nationality: ESP
+:Personal Number: BAB1834284<44282767Q0
+:Country of Issue: ESP
+:State of Issue: MADRID
+:Issue Date:
+:Expiration Date: 2030-01-01
+:Address: C/REAL N13, 1 DCHA COLLADO VILLALBA MADRID MADRID MADRID
+:MRZ Line 1: IDESPBAB1834284<44282767Q0<<<<
+:MRZ Line 2: 8001010F1301017ESP<<<<<<<<<<<3
+:MRZ Line 3: MUESTRA<MUESTRA<<CARMEN<<<<<<<
 ```
 
 # Field Types

data/lib/mindee/http/endpoint.rb

@@ -4,6 +4,7 @@ require 'json'
 require 'net/http'
 require_relative 'error'
 require_relative '../version'
+require_relative 'response_validation'
 
 module Mindee
   module HTTP
@@ -49,14 +50,15 @@ module Mindee
       # @param all_words [Boolean] Whether the full word extraction needs to be performed
       # @param close_file [Boolean] Whether the file will be closed after reading
       # @param cropper [Boolean] Whether a cropping operation will be applied
-      # @return [Hash]
+      # @return [Array]
       def predict(input_source, all_words, close_file, cropper)
         check_api_key
         response = predict_req_post(input_source, all_words: all_words, close_file: close_file, cropper: cropper)
         hashed_response = JSON.parse(response.body, object_class: Hash)
-        return [hashed_response, response.body] if (200..299).include?(response.code.to_i)
+        return [hashed_response, response.body] if ResponseValidation.valid_sync_response?(response)
 
-        error = Error.handle_error!(@url_name, hashed_response, response.code.to_i)
+        ResponseValidation.clean_request!(response)
+        error = Error.handle_error(@url_name, response)
         raise error
       end
 
@@ -65,27 +67,29 @@ module Mindee
       # @param all_words [Boolean] Whether the full word extraction needs to be performed
       # @param close_file [Boolean] Whether the file will be closed after reading
       # @param cropper [Boolean] Whether a cropping operation will be applied
-      # @return [Hash]
+      # @return [Array]
       def predict_async(input_source, all_words, close_file, cropper)
         check_api_key
         response = document_queue_req_get(input_source, all_words, close_file, cropper)
         hashed_response = JSON.parse(response.body, object_class: Hash)
-        return [hashed_response, response.body] if (200..299).include?(response.code.to_i)
+        return [hashed_response, response.body] if ResponseValidation.valid_async_response?(response)
 
-        error = Error.handle_error!(@url_name, hashed_response, response.code.to_i)
+        ResponseValidation.clean_request!(response)
+        error = Error.handle_error(@url_name, response)
         raise error
       end
 
       # Calls the parsed async doc.
       # @param job_id [String]
-      # @return [Hash]
+      # @return [Array]
       def parse_async(job_id)
         check_api_key
         response = document_queue_req(job_id)
         hashed_response = JSON.parse(response.body, object_class: Hash)
-        return [hashed_response, response.body] if (200..299).include?(response.code.to_i)
+        return [hashed_response, response.body] if ResponseValidation.valid_async_response?(response)
 
-        error = Error.handle_error!(@url_name, hashed_response, response.code.to_i)
+        ResponseValidation.clean_request!(response)
+        error = Error.handle_error(@url_name, response)
         raise error
       end
 
@@ -95,7 +99,7 @@ module Mindee
       # @param all_words [Boolean] Whether the full word extraction needs to be performed
       # @param close_file [Boolean] Whether the file will be closed after reading
       # @param cropper [Boolean] Whether a cropping operation will be applied
-      # @return [Net::HTTP, nil]
+      # @return [Net::HTTPResponse, nil]
       def predict_req_post(input_source, all_words: false, close_file: true, cropper: false)
         uri = URI("#{@url_root}/predict")
 
@@ -116,17 +120,18 @@ module Mindee
         form_data.push ['include_mvision', 'true'] if all_words
 
         req.set_form(form_data, 'multipart/form-data')
-
+        response = nil
         Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @request_timeout) do |http|
-          http.request(req)
+          response = http.request(req)
         end
+        response
       end
 
       # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
       # @param all_words [Boolean] Whether the full word extraction needs to be performed
       # @param close_file [Boolean] Whether the file will be closed after reading
       # @param cropper [Boolean] Whether a cropping operation will be applied
-      # @return [Net::HTTPResponse]
+      # @return [Net::HTTPResponse, nil]
       def document_queue_req_get(input_source, all_words, close_file, cropper)
         uri = URI("#{@url_root}/predict_async")
 
@@ -148,13 +153,15 @@ module Mindee
 
         req.set_form(form_data, 'multipart/form-data')
 
+        response = nil
         Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @request_timeout) do |http|
-          http.request(req)
+          response = http.request(req)
         end
+        response
       end
 
       # @param job_id [String]
-      # @return [Net::HTTPResponse]
+      # @return [Net::HTTPResponse, nil]
       def document_queue_req(job_id)
         uri = URI("#{@url_root}/documents/queue/#{job_id}")
 
@@ -171,8 +178,8 @@ module Mindee
 
         if response.code.to_i > 299 && response.code.to_i < 400
           req = Net::HTTP::Get.new(response['location'], headers)
-          response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @request_timeout) do |http|
-            http.request(req)
+          Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @request_timeout) do |http|
+            response = http.request(req)
           end
         end
         response

data/lib/mindee/http/error.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Mindee
   module HTTP
     # Mindee HTTP error module.
@@ -50,15 +52,20 @@ module Mindee
                       end
 
         end
-        error_obj
+        error_obj.nil? ? {} : error_obj
       end
 
       # Creates an appropriate HTTP error exception, based on retrieved http error code
       # @param url [String] the url of the product
       # @param response [Hash] dictionary response retrieved by the server
-      # @param code [Integer] http error code of the response
-      def handle_error!(url, response, code)
-        error_obj = create_error_obj(response)
+      def handle_error(url, response)
+        code = response.code.to_i
+        begin
+          parsed_hash = JSON.parse(response.body, object_class: Hash)
+        rescue JSON::ParserError
+          parsed_hash = response.body.to_s
+        end
+        error_obj = create_error_obj(parsed_hash)
         case code
         when 400..499
           MindeeHttpClientError.new(error_obj, url, code)

data/lib/mindee/http/response_validation.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+
+module Mindee
+  module HTTP
+    # Module dedicated to the validation & sanitizing of HTTP responses.
+    module ResponseValidation
+      # Checks if the synchronous response is valid. Returns True if the response is valid.
+      # @param [Net::HTTPResponse] response
+      # @return [Boolean]
+      def self.valid_sync_response?(response)
+        return false unless (200..399).cover?(response.code.to_i)
+
+        begin
+          JSON.parse(response.body, object_class: Hash)
+        rescue StandardError
+          return false
+        end
+        true
+      end
+
+      # Checks if the asynchronous response is valid. Also checks if it is a valid synchronous response.
+      # Returns true if the response is valid.
+      # @param [Net::HTTPResponse] response
+      # @return [Boolean]
+      def self.valid_async_response?(response)
+        return false unless valid_sync_response?(response)
+
+        return false unless (200..302).cover?(response.code.to_i)
+
+        hashed_response = JSON.parse(response.body, object_class: Hash)
+        return false if hashed_response.dig('job', 'error') && !hashed_response.dig('job', 'error').empty?
+
+        true
+      end
+
+      # Checks and correct the response object depending on the possible kinds of returns.
+      # @param response [Net::HTTPResponse]
+      def self.clean_request!(response)
+        return response if (response.code.to_i < 200) || (response.code.to_i > 302)
+
+        return response unless response.body.empty?
+
+        hashed_response = JSON.parse(response.body, object_class: Hash)
+        if hashed_response.dig('api_request', 'status_code').to_i > 399
+          response.instance_variable_set(:@code, hashed_response['api_request']['status_code'].to_s)
+        end
+        return unless hashed_response.dig('job', 'error').empty?
+
+        response.instance_variable_set(:@code, '500')
+      end
+    end
+  end
+end

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

@@ -14,6 +14,8 @@ module Mindee
         PROCESSING = :processing
         # Document parsing is complete.
         COMPLETED = :completed
+        # Job failed
+        FAILURE = :failed
       end
 
       # Potential values for requests.
@@ -36,10 +38,13 @@ module Mindee
         attr_reader :status
         # @return [Integer, nil]
         attr_reader :millisecs_taken
+        # @return [Hash, nil]
+        attr_reader :error
 
         # @param http_response [Hash]
         def initialize(http_response)
           @id = http_response['id']
+          @error = http_response['error']
           @issued_at = Time.iso8601(http_response['issued_at'])
           if http_response.key?('available_at') && !http_response['available_at'].nil?
             @available_at = Time.iso8601(http_response['available_at'])
@@ -108,7 +113,7 @@ module Mindee
           end
           if http_response.key?('document') &&
              (!http_response.key?('job') ||
-             http_response['job']['status'] == 'completed') &&
+               http_response['job']['status'] == 'completed') &&
              @api_request.status == RequestStatus::SUCCESS
             @document = Mindee::Parsing::Common::Document.new(product_class, http_response['document'])
           end

data/lib/mindee/version.rb

@@ -3,7 +3,7 @@
 # Mindee
 module Mindee
   # Current version.
-  VERSION = '3.6.0'
+  VERSION = '3.6.1'
 
   # 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.6.0
+  version: 3.6.1
 platform: ruby
 authors:
 - Mindee, SA
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-02-21 00:00:00.000000000 Z
+date: 2024-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: marcel
@@ -181,6 +181,7 @@ files:
 - lib/mindee/http/.rubocop.yml
 - lib/mindee/http/endpoint.rb
 - lib/mindee/http/error.rb
+- lib/mindee/http/response_validation.rb
 - lib/mindee/input.rb
 - lib/mindee/input/sources.rb
 - lib/mindee/parsing.rb