mindee-lite 5.2.0 → 5.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 426b1664ea37257f3e79f9da29fca7096392ba5c9fca021279acb79ae8c4c80b
-  data.tar.gz: dfa07b33ef6c2da5f5d973fa47c01ff969bcd011e3b595785f2f06dd411b4c4c
+  metadata.gz: f309aa0cd9c594dd11e44b754a6f313f56786ddc0e03b7ea1503d38d48ae4701
+  data.tar.gz: c00cd97ccded0ac194a1311d45adc36baa04c5e932fd49248b46c59e065c71f7
 SHA512:
-  metadata.gz: f7cd5d72568f93b852368f0e85244ca7453932f9f0fde1b0623a1fcc6cd9f53ff16a571f0ce1ca19c810ce51e2740718984c08150e6e03d9b18b4f0a4aa8c67a
-  data.tar.gz: 10644668f5aa9b0c2848e252cfe8174368c3bd49f5483028c9d0a7e316356986c0300acd875e162156e5338ff53d3d297e47aec5fd33ca9824e39d3d3181272b
+  metadata.gz: bc4983fa4d22c23b4fac65c3d9d36441114c8a94117f4aed73dd628aca2ea1b1216ad05cc0cadd2b1f9298c98561f674786c559eb69b4f40184c1e8960a06fdd
+  data.tar.gz: d53c54dee59e8f1ee9ff6b62267def50a08248d27e491f2d5ccd53a28277812167c507efa7f1f990cb7a264985df126b7a9cb8c544c728dd98a5d243207b26f2

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Mindee Ruby API Library Changelog
 
+## v5.2.2 - 2026-06-18
+### Changes
+* :recycle: refactor CLI to conform with other client libraries
+* :recycle: add secondary accessor for search model pagination to match json return
+* :recycle: ensure HEIF images are detected as such and properly handled
+
+
+## v5.2.1 - 2026-05-27
+### Changes
+* :recycle: add polling options as a dedicated parameter (#252)
+
+
 ## v5.2.0 - 2026-05-19
 ### Changes
 * :sparkles: add webhook info to model searches

data/bin/mindee.rb

@@ -6,24 +6,29 @@ require 'optparse'
 require_relative 'v1/parser'
 require_relative 'v2/parser'
 
-def setup_main_parser
-  v1_parser = MindeeCLI::V1Parser.new(ARGV)
-  v2_parser = MindeeCLI::V2Parser.new(ARGV)
-  main_parser = OptionParser.new do |opts|
-    opts.banner = "Usage: mindee [command]"
-    opts.separator "Commands:"
-    opts.separator "  v1    Use Version 1 of the Mindee API"
-    opts.separator "  v2    Use Version 2 of the Mindee API"
+def root_help
+  help = "Usage: mindee command [options]\n\nAvailable commands:\n"
+  help += "  #{'v1'.ljust(50)}Use Version 1 of the Mindee API\n"
+  help += "  #{'search-models'.ljust(50)}Search for available models for this API key\n"
+
+  V2_PRODUCTS.each do |product_key, product_values|
+    help += "  #{product_key.ljust(50)}#{product_values[:description]}\n"
   end
-  main_command = ARGV.shift
 
-  case main_command
-  when 'v1'
-    v1_parser.execute
-  when 'v2'
-    v2_parser.execute
+  help
+end
+
+def setup_main_parser
+  main_command = ARGV.first
+
+  if main_command == 'v1'
+    ARGV.shift
+    MindeeCLI::V1Parser.new(ARGV).execute
+  elsif main_command.nil? || %w[help -h --help].include?(main_command)
+    abort(root_help)
   else
-    abort(main_parser.help)
+    ARGV.shift if main_command == 'v2'
+    MindeeCLI::V2Parser.new(ARGV, command_prefix: 'mindee').execute
   end
 end
 

data/bin/v2/parser.rb

@@ -19,10 +19,11 @@ module MindeeCLI
     # @return [Parser]
     attr_reader :search_parser
 
-    def initialize(arguments)
+    def initialize(arguments, command_prefix: 'mindee v2')
       @arguments = arguments
+      @command_prefix = command_prefix
       @options_parser = OptionParser.new do |opts|
-        opts.banner = 'Usage: mindee v2 command [options]'
+        opts.banner = "Usage: #{@command_prefix} command [options]"
       end
       @product_parser = init_product_parser
       @search_parser = init_search_parser
@@ -67,6 +68,8 @@ module MindeeCLI
       else
         abort("#{e.message}\n\n#{@product_parser[command].help}")
       end
+    rescue Mindee::Error::MindeeError => e
+      abort(format_cli_error(e))
     end
 
     private
@@ -83,9 +86,21 @@ module MindeeCLI
       abort(error_msg)
     end
 
+    def format_cli_error(error)
+      if error.is_a?(Mindee::Error::MindeeHTTPErrorV2) && error.status.to_i == 401
+        "CLI error: Missing credentials. Provide an API key using '--key' or " \
+          "the 'MINDEE_V2_API_KEY' environment variable."
+      elsif error.is_a?(Mindee::Error::MindeeAPIError) && error.message.include?('Missing API key')
+        "CLI error: Missing API key. Provide it using '--key' or " \
+          "the 'MINDEE_V2_API_KEY' environment variable."
+      else
+        "CLI error: #{error.message}"
+      end
+    end
+
     def init_search_parser
       OptionParser.new do |options_parser|
-        options_parser.banner = 'Usage: mindee v2 search-models [options]'
+        options_parser.banner = "Usage: #{@command_prefix} search-models [options]"
         init_common_options(options_parser)
         options_parser.on('-n [NAME]', '--name [NAME]',
                           'Search for partial matches in model name. Note: case insensitive') do |v|
@@ -159,7 +174,7 @@ module MindeeCLI
       v2_product_parser = {}
       V2_PRODUCTS.each do |product_key, product_values|
         v2_product_parser[product_key] = OptionParser.new do |options_parser|
-          options_parser.banner = "Usage: mindee v2 #{product_key} [options] file"
+          options_parser.banner = "Usage: #{@command_prefix} #{product_key} [options] file"
           options_parser.on('-m MODEL_ID', '--model-id MODEL_ID', 'Model ID') { |v| @options[:model_id] = v }
           options_parser.on('-a ALIAS', '--alias ALIAS', 'Add a file alias to the response') do |v|
             @options[:alias] = v

data/lib/mindee/dependencies.rb

@@ -3,6 +3,7 @@
 module Mindee
   # Centralized check for optional heavy dependencies
   module Dependencies
+    # Checks the presence of dependencies.
     def self.check_all_dependencies
       require 'origami'
       require 'mini_magick'
@@ -12,16 +13,20 @@ module Mindee
       false
     end
 
+    # Memoized check.
     @all_deps_available = check_all_dependencies
 
+    # Checks whether all dependencies are available.
     def self.all_deps_available?
       check_all_dependencies
     end
 
+    # Raises an error if dependencies are not available.
     def self.require_all_deps!
       raise LoadError, MINDEE_DEPENDENCIES_LOAD_ERROR unless all_deps_available?
     end
 
+    # Error message to display when dependencies are not available.
     MINDEE_DEPENDENCIES_LOAD_ERROR = 'Attempted to load Mindee PDF/Image tools without required dependencies. ' \
                                      "If you need to process local files, please replace the 'mindee-lite' gem " \
                                      "with the standard 'mindee' gem in your Gemfile."

data/lib/mindee/image/image_compressor.rb

@@ -9,7 +9,7 @@ module Mindee
       # @param image [MiniMagick::Image, StringIO] Input image.
       # @param quality [Integer, nil] Quality of the final file.
       # @param max_width [Integer, nil] Maximum width. If not specified, the horizontal ratio will remain the same.
-      # @param max_height [Integer] Maximum height. If not specified, the vertical ratio will remain the same.
+      # @param max_height [Integer, nil] Maximum height. If not specified, the vertical ratio will remain the same.
       # @return [StringIO]
       def self.compress_image(image, quality: 85, max_width: nil, max_height: nil)
         processed_image = ImageUtils.to_image(image)

data/lib/mindee/input/base_parameters.rb

@@ -22,7 +22,7 @@ module Mindee
       # @param [String] model_id ID of the model
       # @param [String, nil] file_alias File alias, if applicable.
       # @param [Array<String>, nil] webhook_ids List of webhook IDs to propagate the API response to.
-      # @param [Hash, nil] polling_options Options for polling. Set only if having timeout issues.
+      # @param [Hash, PollingOptions, nil] polling_options Options for polling. Set only if having timeout issues.
       # @param [Boolean, nil] close_file Whether to close the file after parsing.
       def initialize(
         model_id,
@@ -40,6 +40,13 @@ module Mindee
         @close_file = close_file.nil? || close_file
       end
 
+      # Sets polling options after normalizing hash inputs.
+      # @param [Hash, PollingOptions, nil] polling_options
+      # @return [PollingOptions]
+      def polling_options=(polling_options)
+        @polling_options = get_clean_polling_options(polling_options)
+      end
+
       # @return [String] Slug for the endpoint.
       def self.slug
         if self == BaseParameters

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

@@ -16,6 +16,7 @@ module Mindee
       ALLOWED_MIME_TYPES = [
         'application/pdf',
         'image/heic',
+        'image/heif',
         'image/png',
         'image/jpeg',
         'image/tiff',
@@ -37,11 +38,7 @@ module Mindee
         def initialize(io_stream, filename, repair_pdf: false)
           @io_stream = io_stream
           @filename = filename
-          @file_mimetype = if repair_pdf
-                             Marcel::MimeType.for @io_stream
-                           else
-                             Marcel::MimeType.for @io_stream, name: @filename
-                           end
+          @file_mimetype = detect_mime_type(repair_pdf)
           if ALLOWED_MIME_TYPES.include? @file_mimetype
             logger.debug("Loaded new input #{@filename} from #{self.class}")
             return
@@ -83,12 +80,14 @@ module Mindee
         # @return [StringIO] The fixed stream.
         # @raise [Mindee::Error::MindeePDFError]
         def self.fix_pdf(stream, maximum_offset: 500)
-          out_stream = StringIO.new
+          out_stream = StringIO.new(''.b)
           stream.gets('%PDF-')
           raise Error::MindeePDFError if stream.eof? || stream.pos > maximum_offset
 
           stream.pos = stream.pos - 5
-          out_stream << stream.read
+          out_stream.write(stream.read.to_s.b)
+          out_stream.rewind
+          out_stream
         end
 
         # Cuts a PDF file according to provided options.
@@ -195,6 +194,28 @@ module Mindee
 
           Mindee::PDF::PDFTools.source_text?(@io_stream)
         end
+
+        private
+
+        # Checks the mimetype for the file. If it is a PDF, it will attempt to repair it if repair_pdf is true.
+        # @param repair_pdf [bool] Whether to attempt to repair the PDF.
+        # @return [String] The mimetype of the file.
+        def detect_mime_type(repair_pdf)
+          return Marcel::MimeType.for(@io_stream) if repair_pdf
+
+          heif_mimetype_from_extension || Marcel::MimeType.for(@io_stream, name: @filename)
+        end
+
+        # Checks the file extension for a HEIF mimetype.
+        # @return [String, nil] The mimetype if found, nil otherwise.
+        def heif_mimetype_from_extension
+          case File.extname(@filename.to_s).downcase
+          when '.heic'
+            'image/heic'
+          when '.heif'
+            'image/heif'
+          end
+        end
       end
 
       # Replaces non-ASCII characters by their UNICODE escape sequence.

data/lib/mindee/v2/client.rb

@@ -57,14 +57,16 @@ module Mindee
       # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::URLInputSource]
       #   The source of the input document (local file or URL).
       # @param params [Hash, Input::BaseParameters] Parameters for the inference.
+      # @param polling_options [Hash, PollingOptions, nil] Parameters for polling.
       # @return [Parsing::BaseResponse]
       def enqueue_and_get_result(
         product,
         input_source,
-        params
+        params,
+        polling_options = nil
       )
         enqueue_response = enqueue(product, input_source, params)
-        normalized_params = normalize_parameters(product.params_type, params)
+        normalized_params = normalize_parameters(product.params_type, params, polling_options: polling_options)
         normalized_params.validate_async_params
 
         if enqueue_response.job.id.nil? || enqueue_response.job.id.empty?
@@ -121,8 +123,14 @@ module Mindee
 
       # If needed, converts the parsing options provided as a hash into a proper BaseParameters subclass object.
       # @param params [Hash, Class<BaseParameters>] Params.
+      # @param polling_options [Hash, PollingOptions, nil] Polling options.
       # @return [BaseParameters]
-      def normalize_parameters(param_class, params)
+      def normalize_parameters(param_class, params, polling_options: nil)
+        if params.is_a?(Hash)
+          params[:polling_options] = polling_options if polling_options
+        elsif params.is_a?(Mindee::Input::BaseParameters) && !polling_options.nil?
+          params.polling_options = polling_options
+        end
         return param_class.from_hash(params: params) if params.is_a?(Hash)
 
         params

data/lib/mindee/v2/parsing/search/search_response.rb

@@ -6,16 +6,19 @@ module Mindee
       module Search
         # Models search response.
         class SearchResponse < CommonResponse
-          # @return [Search::Search] Parsed search payload.
+          # @return [Search::SearchModels] Parsed search payload.
           attr_reader :models
-          # @return [Search::Search] Pagination metadata.
+          # @return [Search::PaginationMetadata] Pagination metadata.
+          attr_reader :pagination
+          # @return [Search::PaginationMetadata] Pagination metadata.
           attr_reader :pagination_metadata
 
           def initialize(server_response)
             super
 
-            @models = Search::SearchModels.new(server_response['models'])
-            @pagination_metadata = PaginationMetadata.new(server_response['pagination'])
+            @models = SearchModels.new(server_response['models'])
+            @pagination = PaginationMetadata.new(server_response['pagination'])
+            @pagination_metadata = @pagination
           end
 
           # String representation.
@@ -27,7 +30,7 @@ module Mindee
               @models.to_s,
               'Pagination Metadata',
               '###################',
-              @pagination_metadata.to_s,
+              @pagination.to_s,
               '',
             ].join("\n")
           end

data/lib/mindee/v2/product/classification/params/classification_parameters.rb

@@ -16,7 +16,7 @@ module Mindee
             # @param [String] model_id ID of the model
             # @param [String, nil] file_alias File alias, if applicable.
             # @param [Array<String>, nil] webhook_ids List of webhook IDs to propagate the API response to.
-            # @param [Hash, nil] polling_options Options for polling. Set only if having timeout issues.
+            # @param [Hash, PollingOptions, nil] polling_options Options for polling. Set only if having timeout issues.
             # @param [Boolean, nil] close_file Whether to close the file after parsing.
             def initialize(
               model_id,

data/lib/mindee/v2/product/crop/params/crop_parameters.rb

@@ -16,7 +16,7 @@ module Mindee
             # @param [String] model_id ID of the model
             # @param [String, nil] file_alias File alias, if applicable.
             # @param [Array<String>, nil] webhook_ids List of webhook IDs to propagate the API response to.
-            # @param [Hash, nil] polling_options Options for polling. Set only if having timeout issues.
+            # @param [Hash, PollingOptions, nil] polling_options Options for polling. Set only if having timeout issues.
             # @param [Boolean, nil] close_file Whether to close the file after parsing.
             def initialize(
               model_id,

data/lib/mindee/v2/product/extraction/params/data_schema.rb

@@ -13,7 +13,7 @@ module Mindee
             # @return [Mindee::V2::Product::Extraction::Params::DataSchemaReplace]
             attr_reader :replace
 
-            # @param data_schema [Hash, String]
+            # @param data_schema [Hash, DataSchema, String]
             def initialize(data_schema)
               case data_schema
               when String

data/lib/mindee/v2/product/extraction/params/extraction_parameters.rb

@@ -46,7 +46,7 @@ module Mindee
             # @param [String, nil] file_alias File alias, if applicable.
             # @param [Array<String>, nil] webhook_ids
             # @param [String, nil] text_context
-            # @param [Hash, nil] polling_options
+            # @param [Hash, PollingOptions, nil] polling_options
             # @param [Boolean, nil] close_file
             # @param [DataSchemaField, String, Hash nil] data_schema
             def initialize(

data/lib/mindee/v2/product/ocr/params/ocr_parameters.rb

@@ -16,7 +16,7 @@ module Mindee
             # @param [String] model_id ID of the model
             # @param [String, nil] file_alias File alias, if applicable.
             # @param [Array<String>, nil] webhook_ids List of webhook IDs to propagate the API response to.
-            # @param [Hash, nil] polling_options Options for polling. Set only if having timeout issues.
+            # @param [Hash, PollingOptions, nil] polling_options Options for polling. Set only if having timeout issues.
             # @param [Boolean, nil] close_file Whether to close the file after parsing.
             def initialize(
               model_id,

data/lib/mindee/v2/product/split/params/split_parameters.rb

@@ -17,7 +17,7 @@ module Mindee
             # @param [String] model_id ID of the model
             # @param [String, nil] file_alias File alias, if applicable.
             # @param [Array<String>, nil] webhook_ids List of webhook IDs to propagate the API response to.
-            # @param [Hash, nil] polling_options Options for polling. Set only if having timeout issues.
+            # @param [Hash, PollingOptions, nil] polling_options Options for polling. Set only if having timeout issues.
             # @param [Boolean, nil] close_file Whether to close the file after parsing.
             def initialize(
               model_id,

data/lib/mindee/version.rb

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

data/sig/mindee/input/base_parameters.rbs

@@ -26,6 +26,7 @@ module Mindee
 
       def append_form_data: (Array[Array[untyped]]) -> Array[Array[untyped]]
       def validate_async_params: () -> void
+      def polling_options=: (Hash[Symbol | String, untyped] | PollingOptions?) -> PollingOptions
 
       private
 

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

@@ -23,6 +23,12 @@ module Mindee
         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
         def source_text?: -> bool?
+
+        private
+
+        def detect_mime_type: (bool) -> String
+
+        def heif_mimetype_from_extension: -> String?
       end
       def self.convert_to_unicode_escape: (String) -> String
     end

data/sig/mindee/v2/client.rbs

@@ -17,13 +17,13 @@ module Mindee
 
       def enqueue: [T] (HTTP::_ProductClass[T] product, Input::Source::LocalInputSource | Input::Source::URLInputSource, Hash[String | Symbol, untyped] | Input::BaseParameters params) -> V2::Parsing::JobResponse
 
-      def enqueue_and_get_result: [T] (HTTP::_ProductClass[T] product, Input::Source::LocalInputSource | Input::Source::URLInputSource, Hash[String | Symbol, untyped] | Input::BaseParameters params) -> T
+      def enqueue_and_get_result: [T] (HTTP::_ProductClass[T] product, Input::Source::LocalInputSource | Input::Source::URLInputSource, Hash[String | Symbol, untyped] | Input::BaseParameters params, ?Hash[String | Symbol, untyped] | Input::PollingOptions?) -> T
 
       def search_models: (String?, String?) -> Mindee::V2::Parsing::Search::SearchResponse
 
       def validate_async_params: (Integer | Float, Integer | Float, Integer) -> void
 
-      def normalize_parameters: (singleton(Input::BaseParameters) param_class, Hash[String | Symbol, untyped] | Input::BaseParameters params) -> Input::BaseParameters
+      def normalize_parameters: (singleton(Input::BaseParameters) param_class, Hash[String | Symbol, untyped] | Input::BaseParameters params, ?polling_options: Hash[String | Symbol, untyped] | Input::PollingOptions?) -> Input::BaseParameters
     end
   end
 end

data/sig/mindee/v2/parsing/search/search_models.rbs

@@ -0,0 +1,13 @@
+# lib/mindee/v2/parsing/search/search_models.rb
+
+module Mindee
+  module V2
+    module Parsing
+      module Search
+        # Array of search models.
+        class SearchModels < Array[SearchModel]
+        end
+      end
+    end
+  end
+end

data/sig/mindee/v2/parsing/search/search_response.rbs

@@ -5,6 +5,7 @@ module Mindee
       module Search
         class SearchResponse
           attr_reader models: Array[SearchResponse]
+          attr_reader pagination: PaginationMetadata
           attr_reader pagination_metadata: PaginationMetadata
 
           def initialize: (Hash[String|Symbol, untyped]) -> void

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mindee-lite
 version: !ruby/object:Gem::Version
-  version: 5.2.0
+  version: 5.2.2
 platform: ruby
 authors:
 - Mindee, SA
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-19 00:00:00.000000000 Z
+date: 2026-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -57,8 +57,8 @@ description: Quickly and easily connect to Mindee's API services using Ruby. Thi
 email:
 - opensource@mindee.co
 executables:
-- mindee.rb
 - console
+- mindee.rb
 extensions: []
 extra_rdoc_files: []
 files:
@@ -535,6 +535,7 @@ files:
 - sig/mindee/v2/parsing/search/model_webhook.rbs
 - sig/mindee/v2/parsing/search/pagination_metadata.rbs
 - sig/mindee/v2/parsing/search/search_model.rbs
+- sig/mindee/v2/parsing/search/search_models.rbs
 - sig/mindee/v2/parsing/search/search_response.rbs
 - sig/mindee/v2/parsing/search_models.rbs
 - sig/mindee/v2/product/base_product.rbs