mindee 4.7.1 → 4.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d580e2dacf0b4846ff5f9d921cfbf53d7c6fe59c8c0c585088812098ab9bd23c
-  data.tar.gz: 494f8a70fd7b52bdebfc702496621e2625a3822ceb4c31233b9c5f85c2d396c6
+  metadata.gz: 6bbe7fd9450d6e87f07b3b96c636ef8715200370503eb97d65db46225b6ccf8e
+  data.tar.gz: 36b67f8ca703982d40048e4d7e9a3b20e4204c7a36386028b3bd11da79560a20
 SHA512:
-  metadata.gz: b70d059341d2e80348533ac94a05a12436f5c713e7dd531343945ef8ceecfa7474d0e16d13654583642a15ce1e6afbcdadca3bf6ac570e776d48d49bc8f88cc6
-  data.tar.gz: 1dea5f165d3cda7b6de477fee9b739b1a789d492f28deaa9a3878f9068bab7f5eb5d6a81a3d0bdb6674ae659560ca6912fbba5b1e9a47bc5a32dfa248a4a1b46
+  metadata.gz: '08dd6e3e40ea73f874647ab537f2539342aca107bb1d324c04fa8b8de1fa803f5893117bcaf0e840dd6210b55e6e7c163897bb6cba6a36389b44daeab6a886e2'
+  data.tar.gz: 6028ec9f0d38e9e7840c33c98a517d8db02aef34058b8ae517c560cdc0b88524a0e2ab4a472dfe4e1f12ef027fce5bd2153cebd628e2c66f29ac3c8733c1cec3

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Mindee Ruby API Library Changelog
 
+## v4.8.0 - 2025-11-18
+### Changes
+* :sparkles: add support for better errors
+* :sparkles: add support for RAG metadata
+### Fixes
+* :recycle: harmonize test structure with other libraries
+
+
+## v4.7.2 - 2025-10-13
+### Changes
+* :recycle: harmonize getting page count from a local input source
+
+
 ## v4.7.1 - 2025-09-19
 ### Fixes
 * :sparkles: add missing `to_s` method on raw_text

data/README.md

@@ -7,26 +7,26 @@ Quickly and easily connect to Mindee's API services using Ruby.
 ## Mindee API Versions
 This client library has support for both Mindee platform versions.
 
-### Latest - V2
-This is the new platform located here:
+### V2 - Latest
+This is the latest platform located here:
 
 https://app.mindee.com
 
 It uses **API version 2**.
 
 Consult the
-**[Latest Documentation](https://docs.mindee.com/integrations/client-libraries-sdk)**
+**[V2 Documentation](https://docs.mindee.com/integrations/client-libraries-sdk)**
 
 
-### Legacy - V1
-This is the legacy platform located here:
+### V1
+This is the platform located here:
 
 https://platform.mindee.com/
 
 It uses **API version 1**.
 
 Consult the
-**[Legacy Documentation](https://developers.mindee.com/docs/ruby-getting-started)**
+[V1 Documentation](https://docs.mindee.com/v1/libraries/ruby-sdk)
 
 ## Additional Information
 

data/Rakefile

@@ -23,6 +23,7 @@ end
 desc 'Run integration tests'
 RSpec::Core::RakeTask.new(:integration) do |t|
   t.pattern = 'spec/**/*_integration.rb'
+  t.rspec_opts = ['--require', 'integration_helper']
 end
 
 Rake::Task[:doc].enhance do

data/lib/mindee/errors/mindee_http_error_v2.rb

@@ -1,25 +1,44 @@
 # frozen_string_literal: true
 
 require_relative 'mindee_error'
+require_relative '../parsing/v2/error_item'
 
 module Mindee
   module Errors
     # API V2 HttpError
     class MindeeHTTPErrorV2 < MindeeError
-      # @return [Integer]
+      # @return [Integer] The HTTP status code returned by the server.
       attr_reader :status
-      # @return [String]
+      # @return [String] A human-readable explanation specific to the occurrence of the problem.
       attr_reader :detail
+      # @return [String] A short, human-readable summary of the problem.
+      attr_reader :title
+      # @return [String] A machine-readable code specific to the occurrence of the problem.
+      attr_reader :code
+      # @return [Array<ErrorItem>] A list of explicit error details.
+      attr_reader :errors
 
       # @param http_error [Hash, Parsing::V2::ErrorResponse]
       def initialize(http_error)
         if http_error.is_a?(Parsing::V2::ErrorResponse)
           http_error = { 'detail' => http_error.detail,
-                         'status' => http_error.status }
+                         'status' => http_error.status,
+                         'title' => http_error.title,
+                         'code' => http_error.code,
+                         'errors' => http_error.errors }
         end
         @status = http_error['status']
         @detail = http_error['detail']
-        super("HTTP error: #{@status} - #{@detail}")
+        @title = http_error['title']
+        @code = http_error['code']
+        @errors = if http_error.key?('errors')
+                    http_error['errors'].map do |error|
+                      Parsing::V2::ErrorItem.new(error)
+                    end
+                  else
+                    []
+                  end
+        super("HTTP #{@status} - #{@title} :: #{@code} - #{@detail}")
       end
     end
   end

data/lib/mindee/errors/mindee_http_unknown_error_v2.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'mindee_error'
+
+module Mindee
+  module Errors
+    # Unknown HTTP error for the V2 API.
+    class MindeeHTTPUnknownErrorV2 < MindeeHTTPErrorV2
+      def initialize(http_error)
+        super({ 'detail' => "Couldn't deserialize server error. Found: #{http_error}",
+                'status' => -1,
+                'title' => 'Unknown Error',
+                'code' => '000-000',
+                'errors' => nil })
+      end
+    end
+  end
+end

data/lib/mindee/http/endpoint.rb

@@ -7,6 +7,7 @@ require_relative '../version'
 require_relative 'response_validation'
 
 module Mindee
+  # Mindee internal HTTP module.
   module HTTP
     # API key's default environment key name.
     API_KEY_ENV_NAME = 'MINDEE_API_KEY'

data/lib/mindee/input/sources/local_input_source.rb

@@ -141,7 +141,7 @@ module Mindee
         # Returns the page count for a document.
         # Defaults to one for images.
         # @return [Integer]
-        def count_pages
+        def page_count
           return 1 unless pdf?
 
           @io_stream.seek(0)
@@ -149,6 +149,14 @@ module Mindee
           pdf_processor.pages.size
         end
 
+        # Returns the page count for a document.
+        # Defaults to one for images.
+        # @return [Integer]
+        # @deprecated Use {#page_count} instead.
+        def count_pages
+          page_count
+        end
+
         # Compresses the file, according to the provided info.
         # @param [Integer] quality Quality of the output file.
         # @param [Integer, nil] max_width Maximum width (Ignored for PDFs).

data/lib/mindee/parsing/v2/error_item.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Parsing
+    module V2
+      # Individual error item.
+      class ErrorItem
+        # @return [String, nil] A JSON Pointer to the location of the body property.
+        attr_reader :pointer
+        # @return [String, nil] Explicit information on the issue.
+        attr_reader :detail
+
+        # @param server_response [Hash] Raw JSON parsed into a Hash.
+        def initialize(server_response)
+          @pointer = server_response['pointer']
+          @detail = server_response['detail']
+        end
+      end
+    end
+  end
+end

data/lib/mindee/parsing/v2/error_response.rb

@@ -5,21 +5,36 @@ module Mindee
     module V2
       # Encapsulates information returned by the API when an error occurs.
       class ErrorResponse
-        # @return [Integer] HTTP status code.
+        # @return [Integer] The HTTP status code returned by the server.
         attr_reader :status
-        # @return [String] Error detail.
+        # @return [String] A human-readable explanation specific to the occurrence of the problem.
         attr_reader :detail
+        # @return [String] A short, human-readable summary of the problem.
+        attr_reader :title
+        # @return [String] A machine-readable code specific to the occurrence of the problem.
+        attr_reader :code
+        # @return [Array<ErrorItem>] A list of explicit error details.
+        attr_reader :errors
 
         # @param server_response [Hash] Raw JSON parsed into a Hash.
         def initialize(server_response)
           @status = server_response['status']
           @detail = server_response['detail']
+          @title = server_response['title']
+          @code = server_response['code']
+          @errors = if server_response.key?('errors')
+                      server_response['errors'].map do |error|
+                        ErrorItem.new(error)
+                      end
+                    else
+                      []
+                    end
         end
 
         # String representation.
         # @return [String]
         def to_s
-          "Error\n=====\n:Status: #{@status}\n:Detail: #{@detail}"
+          "HTTP #{@status} - #{@title} :: #{@code} - #{@detail}"
         end
 
         # Hash representation

data/lib/mindee/parsing/v2/inference_result.rb

@@ -2,6 +2,7 @@
 
 require_relative 'field/inference_fields'
 require_relative 'raw_text'
+require_relative 'rag_metadata'
 
 module Mindee
   module Parsing
@@ -12,6 +13,8 @@ module Mindee
         attr_reader :fields
         # @return [Mindee::Parsing::V2::RawText, nil] Optional extra data.
         attr_reader :raw_text
+        # @return [Mindee::Parsing::V2::RAGMetadata, nil] Optional RAG metadata.
+        attr_reader :rag
 
         # @param server_response [Hash] Hash version of the JSON returned by the API.
         def initialize(server_response)
@@ -20,6 +23,7 @@ module Mindee
           @fields = Field::InferenceFields.new(server_response['fields'])
 
           @raw_text = server_response['raw_text'] ? RawText.new(server_response['raw_text']) : nil
+          @rag = (V2::RAGMetadata.new(server_response['rag']) if server_response.key?('rag') && server_response['rag'])
         end
 
         # String representation.

data/lib/mindee/parsing/v2/rag_metadata.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Parsing
+    module V2
+      # Metadata about the RAG operation.
+      class RAGMetadata
+        # The UUID of the matched document used during the RAG operation.
+        attr_accessor :retrieved_document_id
+
+        def initialize(server_response)
+          @retrieved_document_id = server_response.fetch('retrieved_document_id', nil)
+        end
+      end
+    end
+  end
+end

data/lib/mindee/product.rb

@@ -29,5 +29,4 @@ require_relative 'product/resume/resume_v1'
 require_relative 'product/universal/universal'
 require_relative 'product/us/bank_check/bank_check_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'

data/lib/mindee/version.rb

@@ -3,7 +3,7 @@
 # Mindee
 module Mindee
   # Current version.
-  VERSION = '4.7.1'
+  VERSION = '4.8.0'
 
   # Finds and return the current platform.
   # @return [Symbol, Hash[String | Symbol, Regexp], Nil?]

data/mindee.gemspec

@@ -33,6 +33,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'origamindee', '~> 4.0'
   spec.add_dependency 'pdf-reader', '~> 2.14'
 
+  spec.add_development_dependency 'openssl', '~> 3.3.2'
   spec.add_development_dependency 'prism', '~> 1.3'
   spec.add_development_dependency 'rake', '~> 13.2'
   spec.add_development_dependency 'rbs', '~> 3.6'

data/sig/mindee/errors/mindee_http_error_v2.rbs

@@ -3,9 +3,12 @@ module Mindee
   module Errors
     # API V2 HttpError
     class MindeeHTTPErrorV2 < MindeeError
-
       attr_reader detail: String
       attr_reader status: Integer
+      attr_reader code: String
+      attr_reader title: String
+      attr_reader errors: Array[Parsing::V2::ErrorItem]
+
       def initialize: (Hash[String, untyped] | Parsing::V2::ErrorResponse) -> void
     end
   end

data/sig/mindee/errors/mindee_http_unknown_error_v2.rbs

@@ -0,0 +1,9 @@
+# lib/mindee/errors/mindee_http_unknown_error_v2.rb
+module Mindee
+  module Errors
+    # Unknown HTTP error for the V2 API.
+    class MindeeHTTPUnknownErrorV2 < MindeeHTTPErrorV2
+      def initialize: (Hash[String|Symbol, untyped]) -> void
+    end
+  end
+end

data/sig/mindee/http/endpoint.rbs

@@ -23,6 +23,7 @@ module Mindee
       def document_queue_req_post: (Input::Source::LocalInputSource | Input::Source::URLInputSource, ParseOptions) -> Net::HTTPResponse
       def document_queue_req_get: (String) -> Net::HTTPResponse
       def check_api_key: -> void
+      def configure_ssl: (Net::HTTP) -> void
     end
   end
 end

data/sig/mindee/input/sources/local_input_source.rbs

@@ -14,12 +14,12 @@ module Mindee
 
         def logger: () -> Logger
 
-
         def rescue_broken_pdf: (untyped) -> void
         def pdf?: -> bool
         def apply_page_options: (PageOptions) -> StringIO?
         def process_pdf: (PageOptions) -> StringIO?
         def read_contents: (?close: bool) -> [String?, Hash[:filename, String]]
+        def page_count: -> Integer
         def count_pages: -> Integer
         def write_to_file: (String?) -> void
         def compress!: (?quality: Integer, ?max_width: Integer?, ?max_height: Integer?, ?force_source_text: bool, ?disable_source_text: bool) -> Integer

data/sig/mindee/parsing/v2/error_item.rbs

@@ -0,0 +1,13 @@
+# lib/mindee/parsing/v2/error_item.rb
+module Mindee
+  module Parsing
+    module V2
+      class ErrorItem
+        attr_reader pointer: String
+        attr_reader detail: String|nil
+
+        def initialize: (Hash[String|Symbol, untyped]) -> void
+      end
+    end
+  end
+end

data/sig/mindee/parsing/v2/error_response.rbs

@@ -5,6 +5,9 @@ module Mindee
       class ErrorResponse
         attr_reader detail: String
         attr_reader status: Integer
+        attr_reader code: String
+        attr_reader title: String
+        attr_reader errors: Array[ErrorItem]
         def initialize: (Hash[String | Symbol, untyped]) -> void
 
         def as_hash: -> Hash[Symbol, String | Integer]

data/sig/mindee/parsing/v2/inference_result.rbs

@@ -5,6 +5,7 @@ module Mindee
       class InferenceResult
         attr_reader fields: Field::InferenceFields
         attr_reader raw_text: RawText?
+        attr_reader rag: RAGMetadata?
 
         def initialize: (Hash[String | Symbol, untyped]) -> void
         def to_s: -> String

data/sig/mindee/parsing/v2/rag_metadata.rbs

@@ -0,0 +1,13 @@
+# lib/mindee/parsing/v2/rag_metadata.rb
+
+module Mindee
+  module Parsing
+    module V2
+      class RAGMetadata
+        attr_accessor retrieved_document_id: string | nil
+
+        def initialize: (Hash[String | Symbol, untyped]) -> void
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mindee
 version: !ruby/object:Gem::Version
-  version: 4.7.1
+  version: 4.8.0
 platform: ruby
 authors:
 - Mindee, SA
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-19 00:00:00.000000000 Z
+date: 2025-11-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -86,6 +86,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.2
 - !ruby/object:Gem::Dependency
   name: prism
   requirement: !ruby/object:Gem::Requirement
@@ -209,7 +223,6 @@ files:
 - bin/cli_products.rb
 - bin/console
 - bin/mindee.rb
-- docs/advanced_file_operations.md
 - docs/code_samples/bank_account_details_v1.txt
 - docs/code_samples/bank_account_details_v2.txt
 - docs/code_samples/bank_check_v1.txt
@@ -244,41 +257,9 @@ files:
 - docs/code_samples/payslip_fra_v3_async.txt
 - docs/code_samples/resume_v1_async.txt
 - docs/code_samples/us_healthcare_cards_v1_async.txt
-- docs/code_samples/us_mail_v2_async.txt
 - docs/code_samples/us_mail_v3_async.txt
 - docs/code_samples/workflow_execution.txt
 - docs/code_samples/workflow_polling.txt
-- docs/getting_started.md
-- docs/global_products.md
-- docs/global_products/barcode_reader_v1.md
-- docs/global_products/bill_of_lading_v1.md
-- docs/global_products/business_card_v1.md
-- docs/global_products/cropper_v1.md
-- docs/global_products/delivery_notes_v1.md
-- docs/global_products/driver_license_v1.md
-- docs/global_products/expense_receipts_v5.md
-- docs/global_products/financial_document_v1.md
-- docs/global_products/international_id_v2.md
-- docs/global_products/invoice_splitter_v1.md
-- docs/global_products/invoices_v4.md
-- docs/global_products/multi_receipts_detector_v1.md
-- docs/global_products/nutrition_facts_v1.md
-- docs/global_products/passport_v1.md
-- docs/global_products/resume_v1.md
-- docs/global_products/universal.md
-- docs/loading_a_document.md
-- docs/localized_products.md
-- docs/localized_products/bank_account_details_v2.md
-- docs/localized_products/bank_check_v1.md
-- docs/localized_products/bank_statement_fr_v2.md
-- docs/localized_products/carte_grise_v1.md
-- docs/localized_products/energy_bill_fra_v1.md
-- docs/localized_products/french_healthcard_v1.md
-- docs/localized_products/idcard_fr_v2.md
-- docs/localized_products/ind_passport_v1.md
-- docs/localized_products/payslip_fra_v3.md
-- docs/localized_products/us_healthcare_cards_v1.md
-- docs/localized_products/us_mail_v3.md
 - examples/auto_invoice_splitter_extraction.rb
 - examples/auto_multi_receipts_detector_extraction.rb
 - lib/mindee.rb
@@ -288,6 +269,7 @@ files:
 - lib/mindee/errors/mindee_error.rb
 - lib/mindee/errors/mindee_http_error.rb
 - lib/mindee/errors/mindee_http_error_v2.rb
+- lib/mindee/errors/mindee_http_unknown_error_v2.rb
 - lib/mindee/errors/mindee_input_error.rb
 - lib/mindee/extraction.rb
 - lib/mindee/extraction/multi_receipts_extractor.rb
@@ -367,6 +349,7 @@ files:
 - lib/mindee/parsing/universal/universal_object_field.rb
 - lib/mindee/parsing/v2.rb
 - lib/mindee/parsing/v2/common_response.rb
+- lib/mindee/parsing/v2/error_item.rb
 - lib/mindee/parsing/v2/error_response.rb
 - lib/mindee/parsing/v2/field.rb
 - lib/mindee/parsing/v2/field/base_field.rb
@@ -385,6 +368,7 @@ files:
 - lib/mindee/parsing/v2/job.rb
 - lib/mindee/parsing/v2/job_response.rb
 - lib/mindee/parsing/v2/job_webhook.rb
+- lib/mindee/parsing/v2/rag_metadata.rb
 - lib/mindee/parsing/v2/raw_text.rb
 - lib/mindee/parsing/v2/raw_text_page.rb
 - lib/mindee/pdf.rb
@@ -554,12 +538,6 @@ files:
 - lib/mindee/product/us/healthcare_card/healthcare_card_v1_copays.rb
 - lib/mindee/product/us/healthcare_card/healthcare_card_v1_document.rb
 - lib/mindee/product/us/healthcare_card/healthcare_card_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_recipient_addresses.rb
-- lib/mindee/product/us/us_mail/us_mail_v2_sender_address.rb
 - lib/mindee/product/us/us_mail/us_mail_v3.rb
 - lib/mindee/product/us/us_mail/us_mail_v3_document.rb
 - lib/mindee/product/us/us_mail/us_mail_v3_page.rb
@@ -578,6 +556,7 @@ files:
 - sig/mindee/errors/mindee_error.rbs
 - sig/mindee/errors/mindee_http_error.rbs
 - sig/mindee/errors/mindee_http_error_v2.rbs
+- sig/mindee/errors/mindee_http_unknown_error_v2.rbs
 - sig/mindee/errors/mindee_input_error.rbs
 - sig/mindee/extraction/multi_receipts_extractor.rbs
 - sig/mindee/geometry/min_max.rbs
@@ -642,6 +621,7 @@ files:
 - sig/mindee/parsing/universal/universal_list_field.rbs
 - sig/mindee/parsing/universal/universal_object_field.rbs
 - sig/mindee/parsing/v2/common_response.rbs
+- sig/mindee/parsing/v2/error_item.rbs
 - sig/mindee/parsing/v2/error_response.rbs
 - sig/mindee/parsing/v2/field/base_field.rbs
 - sig/mindee/parsing/v2/field/field_confidence.rbs
@@ -659,6 +639,7 @@ files:
 - sig/mindee/parsing/v2/job.rbs
 - sig/mindee/parsing/v2/job_response.rbs
 - sig/mindee/parsing/v2/job_webhook.rbs
+- sig/mindee/parsing/v2/rag_metadata.rbs
 - sig/mindee/parsing/v2/raw_text.rbs
 - sig/mindee/parsing/v2/raw_text_page.rbs
 - sig/mindee/pdf/extracted_pdf.rbs
@@ -825,12 +806,6 @@ files:
 - sig/mindee/product/us/healthcare_card/healthcare_card_v1_copays.rbs
 - sig/mindee/product/us/healthcare_card/healthcare_card_v1_document.rbs
 - sig/mindee/product/us/healthcare_card/healthcare_card_v1_page.rbs
-- sig/mindee/product/us/us_mail/us_mail_v2.rbs
-- sig/mindee/product/us/us_mail/us_mail_v2_document.rbs
-- sig/mindee/product/us/us_mail/us_mail_v2_page.rbs
-- sig/mindee/product/us/us_mail/us_mail_v2_recipient_address.rbs
-- sig/mindee/product/us/us_mail/us_mail_v2_recipient_addresses.rbs
-- sig/mindee/product/us/us_mail/us_mail_v2_sender_address.rbs
 - sig/mindee/product/us/us_mail/us_mail_v3.rbs
 - sig/mindee/product/us/us_mail/us_mail_v3_document.rbs
 - sig/mindee/product/us/us_mail/us_mail_v3_page.rbs