mindee 4.7.2 → 4.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2279aaa45f25ab506ab861d139c93029ddcffe5899ca448041fbbe02ef422058
-  data.tar.gz: 8a531ca5073b775a5b4afdb6e97f001129fb9d1aa4cf3f4f31633580cd9c16aa
+  metadata.gz: 6bbe7fd9450d6e87f07b3b96c636ef8715200370503eb97d65db46225b6ccf8e
+  data.tar.gz: 36b67f8ca703982d40048e4d7e9a3b20e4204c7a36386028b3bd11da79560a20
 SHA512:
-  metadata.gz: d3b4a6fb9da9a9b8bd3d14b8b06d7c77e328c7eaa060910578f4e345ebc0a732d2b5c4b6e9117621caa1ff7b5f2633624f383833b80c8e7f81faa16236f9d1ca
-  data.tar.gz: 4be80490fb4f63677954c770458d9bcfdd237bb7fbd1f72fed286b3414046987c0281d6cb2867490e4261e7c423e3ee8d37a24b7e986de77bf97abfbe96950c4
+  metadata.gz: '08dd6e3e40ea73f874647ab537f2539342aca107bb1d324c04fa8b8de1fa803f5893117bcaf0e840dd6210b55e6e7c163897bb6cba6a36389b44daeab6a886e2'
+  data.tar.gz: 6028ec9f0d38e9e7840c33c98a517d8db02aef34058b8ae517c560cdc0b88524a0e2ab4a472dfe4e1f12ef027fce5bd2153cebd628e2c66f29ac3c8733c1cec3

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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

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/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/version.rb

@@ -3,7 +3,7 @@
 # Mindee
 module Mindee
   # Current version.
-  VERSION = '4.7.2'
+  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/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.2
+  version: 4.8.0
 platform: ruby
 authors:
 - Mindee, SA
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-10-13 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
@@ -247,37 +260,6 @@ files:
 - 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
@@ -287,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
@@ -366,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
@@ -384,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
@@ -571,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
@@ -635,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
@@ -652,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

data/docs/advanced_file_operations.md

@@ -1,109 +0,0 @@
----
-title: Advanced File Operations
-category: 622b805aaec68102ea7fcbc2
-slug: ruby-advanced-file-operations
-parentDoc: 6294d97ee723f1008d2ab28e
----
-
-> ❗️ Disclaimer: the file operations listed below do not directly manipulate the files you will pass to the library,
-> They will instead create a copy before applying any operations, which means that the file you send may not be an exact copy of the file the server will receive.
-> To avoid any unexpected or unwanted result, you can save a copy of the created file locally to inspect it visually before sending it.
-
-## Image compression
-
-The compression functionality for image files (JPEG, PNG, etc.) via the `compress!` method available on a
-LocalInputSource. This method allows you to reduce file size by specifying quality and dimension constraints.
-
-Example:
-
-```rb
-# Compress an image with custom parameters.
-input_source.compress!(quality: 85, max_width: 1024, max_height: 768)
-```
-> ⚠️ Warning: Compression alters the original image data.
-> We strongly advise you inspect a compressed file before sending it:
-> ```rb
-> # Compress using a quality of 50%:
-> input_source.compress!(quality: 50)
-> input_source.write_to_file('path/to/my/compressed/file_50.jpg')
-> ```
-
-For reference, here's what the following levels of compression on this image will look like:
-
-**Original:**
-![Invoice sample](https://github.com/mindee/client-lib-test-data/blob/main/products/invoices/default_sample.jpg?raw=true)
-
-**85% compressed:**
-![85% sample](https://github.com/mindee/client-lib-test-data/blob/main/file_operations/compression/compressed_ruby_85.jpg?raw=true)
-
-**50% compressed:**
-![50% sample](https://github.com/mindee/client-lib-test-data/blob/main/file_operations/compression/compressed_ruby_50.jpg?raw=true)
-
-**10% compressed:**
-![10% sample](https://github.com/mindee/client-lib-test-data/blob/main/file_operations/compression/compressed_ruby_10.jpg?raw=true)
-
-
-## PDF operations
-
-PDF operations include both compression and fixing features.
-These are specifically designed to handle challenges associated with PDF files, such as large file sizes and formatting
-issues.
-
-### PDF compression
-
-> 🧪 PDF compression is an **experimental** feature that rasterizes each page of the PDF (similar to how images are
-> compressed) to reduce its overall size.
-> 
-> Because the process involves re-rendering the PDF’s contents, some source text may be lost or rendered differently.
-> Use this feature with caution.
-
-
-```rb
-# Load a local input source.
-input_file_path = "path/to/your/file.pdf"
-output_file_path = "path/to/the/compressed/file.pdf"
-pdf_input = Mindee::Input::Source::PathInputSource.new(input_file_path)
-
-# We advise you test the quality value yourself, as results may vary greatly depending on the input file
-pdf_input.compress!(quality: 50)
-
-# Write the output file locally for visual checking:
-File.write(output_file_path, pdf_input.io_stream.read)
-```
-
-> 🚧 Be warned that the source text (the text embedded in the PDF itself) might not render properly,
-> and so source PDFs will be ignored by default.
-> 
-> You can bypass this using:
-
-```rb
-pdf_input.compress!(quality: 50, force_source_text: true)
-```
-
-Or alternatively, you can try to approximate the re-rendering of the source-text using:
-
-```rb
-pdf_input.compress!(quality: 50, force_source_text: true, disable_source_text: false)
-```
-
-### PDF Repair
-
-The PDF repair feature attempts to rescue PDFs with invalid or broken header information.
-This can sometimes help when files get rejected by the server.
-
-Example:
-```rb
-# Load a PDF file with the repair_pdf flag enabled.
-input_source = mindee_client.source_from_file(file, "document.pdf", repair_pdf: true)
-```
-
-> ⚠️ Warning: PDF fixing alters the input file by re-writing header information.
-> Use this feature only when required, as it might affect the integrity of the document file.
-
----
-
-Feel free to expand these examples and adjust the parameters as needed for your projects. For further details on
-authentication and usage, you can refer to the [Getting Started Guide](getting_started.md).
-
-# Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)