mindee 4.12.0 → 5.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ec6f37e83f30ed06cca64a016ea4936211726fe0e4e6281f6e9eec42f32bfdc
-  data.tar.gz: 780f641de505dcb64842c73b2597d389894522f38c345d92c2b28fd52db61749
+  metadata.gz: a0f0f74c2ffa0b955e76431c51bff64e2683439045ee6059d1a582885c5dcd2f
+  data.tar.gz: 3663bcce828f5851c59a83bc71776e3c9d77ddc92aa657c8dc2573277a89186b
 SHA512:
-  metadata.gz: f0909570d17dfcc54d8d95671ec323c733a98be640bd71c837708759a623d16896133998f2e5af67aa845420f92ef7c6c875d9890c6e8e9dbe97db0069529f73
-  data.tar.gz: '0975d445b49f5e22805baec50eebbaf2e8127fd85ab22fe5970167eeb3d31217be2db50ddc6a56155580d70f5fbce888f4b491d58343d7fc3fea806ed5de0d33'
+  metadata.gz: f2741d09c26053c130af682a29e28ae54854ba6d9ad652559d8b6706ff6d8fd2ea7afcc90ed2ed2cecc27a3926bc3fc61a2e7a671a3f0eaea63886ab9db929e0
+  data.tar.gz: c3c72bbadb037a126c594c51610a43cb874a1d8cc15d43d3b5241bfaa69f3f1b647751faebf215f8642634ef77c72ea6cbd47af1e450a82c53075d7323cbf513

data/.editorconfig

@@ -0,0 +1,24 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{rb,rake,gemspec,rbs,ru}]
+indent_style = space
+indent_size = 2
+
+[*.{yml,yaml,json}]
+indent_style = space
+indent_size = 2
+
+[*.sh]
+indent_style = space
+indent_size = 2
+
+[Makefile]
+indent_style = tab

data/.gitignore

@@ -16,6 +16,8 @@
 /test/version_tmp/
 /tmp/
 _test.rb
+_test_v1.rb
+_test_v2.rb
 /vendor
 /mindee-*/
 local-test

data/.pre-commit-config.yaml

@@ -0,0 +1,36 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+        args: ["--maxkb=1024"]
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.0
+    hooks:
+      - id: gitleaks
+        exclude: ^(spec/data/|docs/code_samples/|local_test/)
+
+  - repo: local
+    hooks:
+      - id: rubocop
+        name: RuboCop
+        entry: bundle exec rubocop --force-exclusion --no-server
+        language: system
+        pass_filenames: false
+      - id: steep
+        name: Steep
+        entry: bundle exec steep check
+        language: system
+        pass_filenames: false
+        stages: [pre-commit, pre-push]
+      - id: bundle-audit
+        name: Bundle Audit
+        entry: bundle exec bundle-audit check
+        language: system
+        pass_filenames: false
+        stages: [pre-commit, pre-push]

data/.rubocop.yml

@@ -6,11 +6,11 @@ AllCops:
     - 'tmp/**/*'
     - '.git/**/*'
     - 'bin/*'
-    - _test.rb
+    - _test*.rb
     - local_test/*
     - Steepfile
 
-  TargetRubyVersion: 3.0.0
+  TargetRubyVersion: 3.2
   SuggestExtensions: false
 
 Gemspec/DevelopmentDependencies:
@@ -37,7 +37,8 @@ Metrics/MethodLength:
 
 Metrics/ClassLength:
   Max: 200
-
+Metrics/ModuleLength:
+  Max: 200
 Metrics/ParameterLists:
   Max: 8
 

data/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Mindee Ruby API Library Changelog
 
+## v5.0.0.beta1 - 2026-04-07
+### ¡Breaking Changes!
+* :boom: :recycle: update V1 & V2 syntaxes to match other SDKs
+  * :recycle: move V1 client to V1 module
+  * :recycle: move V2 client to V2 module
+  * :recycle: move legacy products to 'V1' module
+  * :recycle: add parsing and extraction to v1 module
+  * :recycle: move V1 HTTP to V1 module
+  * :recycle: move V2 HTTP module to V2 namespace
+  * :recycle: move data schema to extraction parameters namespace
+* :arrow_up: :boom: drop support for ruby < 3.2
+* :recycle: :boom: change raw_http attribute in responses to be actual json strings
+* :recycle: :boom: make logging configurable and default output to stderr
+* :recycle: :boom: remove useless `PDFExtractor` module
+* :recycle: :boom: change `Errors` module to `Error`
+* :recycle: :boom: change Ocr modules and classes to OCR to keep consistency
+* :boom: remove support for the following V1 products:
+    * :coffin: US Bank Check V1
+    * :coffin: Bill of Lading V1
+    * :coffin: Business Card V1
+    * :coffin: FR Carte Grise V1
+    * :coffin: Delivery Notes V1
+    * :coffin: Driver License V1
+    * :coffin: FR Energy Bill V1
+    * :coffin: Nutrition Facts V1
+
+### Changes
+* :sparkles: :arrow_up: add support for mindee-lite gem
+* :sparkles: add support for crop operation
+* :sparkles: add support for split operation
+* :sparkles: add support for model search
+* :sparkles: add support for V2 CLI
+* :wrench: :arrow_up: add better tooling and pre-commit hook
+* :arrow_up: and bump all dependencies
+
+### Fixes
+* :bug: fix webhook IDs not sending properly
+* :bug: fix miscellaneous issues leading to saved `ExtractedPDF` instances having invalid names
+* :recycle: fix miscellaneous typing issues relating to `ExtractedPDF` and `ExtractedImage` classes
+
+
+## v4.13.0 - 2026-03-03
+### Changes
+* :sparkles: add support for V2 Classification product
+* :sparkles: add support for V2 Crop product
+* :sparkles: add support for V2 Ocr product
+* :sparkles: add support for V2 Split product
+* :recycle: make polling follow API urls instead of re-constructing them
+* :sparkles: add support for generic product accessors in V2
+* :recycle: add proper tests for ruby 4
+### Fixes
+* :recycle: fix tests file paths
+
+
 ## v4.12.0 - 2026-02-25
 ### Changes
 * :sparkles: add job information to inference
@@ -45,7 +99,7 @@
 
 
 ## v4.7.0 - 2025-09-18
-Including RC changes and fixes. 
+Including RC changes and fixes.
 ### Changes
 * :sparkles: add support for V2 Mindee API
 * :sparkles: add missing accessors for PDF fixing options in `LocalInputSource`

data/CONTRIBUTING.md

@@ -88,3 +88,20 @@ Examples:
 
 We keep our code base consistent and expect Ruby code to adhere to our Rubocop styleguide,
 see the `.rubocop` file.
+
+### Local Quality Checks
+
+We use [`pre-commit`](https://pre-commit.com/) hooks to run quality and security checks before
+changes are pushed:
+
+1. Install `pre-commit`, either using `pip` or `brew`:
+   - `pip install pre-commit`
+   - `brew install pre-commit`
+2. Install project hooks:
+   - `pre-commit install`
+   - `pre-commit install --hook-type pre-push`
+
+Run hooks manually:
+
+* `pre-commit run --all-files`
+* `pre-commit run --all-files --hook-stage pre-push`

data/Gemfile

@@ -3,4 +3,12 @@
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in mindee.gemspec
-gemspec
+
+gemspec name: ENV.fetch('MINDEE_GEM_NAME', 'mindee')
+
+group :development, :test do
+  gem 'openssl', '~> 4.0'
+  gem 'prism', '~> 1.3'
+  gem 'rake', '~> 13.3'
+  gem 'rspec', '~> 3.13'
+end

data/README.md

@@ -1,4 +1,4 @@
-[![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)
+[![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/push-main-branch.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
 
@@ -15,7 +15,7 @@ https://app.mindee.com
 It uses **API version 2**.
 
 Consult the
-**[V2 Documentation](https://docs.mindee.com/integrations/client-libraries-sdk)**
+**<a href="https://docs.mindee.com/integrations/client-libraries-sdk">V2 Documentation</a>**
 
 
 ### V1
@@ -26,17 +26,17 @@ https://platform.mindee.com/
 It uses **API version 1**.
 
 Consult the
-[V1 Documentation](https://docs.mindee.com/v1/libraries/ruby-sdk)
+<a href="https://docs.mindee.com/v1/libraries/ruby-sdk">V1 Documentation</a>
 
 ## Additional Information
 
-**[Source Code](https://github.com/mindee/mindee-api-ruby)**
+**<a href="https://github.com/mindee/mindee-api-ruby">Source Code</a>**
 
-**[Reference Documentation](https://mindee.github.io/mindee-api-ruby/)**
+**<a href="https://mindee.github.io/mindee-api-ruby/">Reference Documentation</a>**
 
-**[Feedback](https://feedback.mindee.com/)**
+**<a href="https://feedback.mindee.com/">Feedback</a>**
 
 ### License
 Copyright © Mindee
 
-Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Available as open source under the terms of the <a href="https://opensource.org/licenses/MIT">MIT License</a>.

data/Rakefile

@@ -2,33 +2,39 @@
 
 require 'rake'
 require 'rspec/core/rake_task'
-require 'yard'
+
+is_lite_mode = ENV.fetch('MINDEE_GEM_NAME', 'mindee') == 'mindee-lite'
 
 begin
   require 'bundler/setup'
-  Bundler::GemHelper.install_tasks
+  require 'bundler/gem_helper'
+  Bundler::GemHelper.install_tasks(name: ENV.fetch('MINDEE_GEM_NAME', 'mindee'))
 rescue LoadError
   puts 'although not required, bundler is recommended for running the tests'
 end
 
 task default: :spec
+exclusion_opts = is_lite_mode ? ['--tag', '~all_deps'] : []
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = exclusion_opts
+end
+unless is_lite_mode
+  require 'yard'
+  desc 'Generate documentation'
+  YARD::Rake::YardocTask.new(:doc) do |task|
+    task.files = ['lib/**/*.rb']
+  end
 
-RSpec::Core::RakeTask.new(:spec)
-
-desc 'Generate documentation'
-YARD::Rake::YardocTask.new(:doc) do |task|
-  task.files = ['lib/**/*.rb']
+  Rake::Task[:doc].enhance do
+    FileUtils.cp_r(
+      File.join('docs', 'code_samples'),
+      File.join('docs', '_build')
+    )
+  end
 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
-  FileUtils.cp_r(
-    File.join('docs', 'code_samples'),
-    File.join('docs', '_build')
-  )
+  t.rspec_opts = ['--require', 'integration_helper'] + exclusion_opts
 end

data/Steepfile

@@ -28,4 +28,3 @@ target :lib do
 
   configure_code_diagnostics(D::Ruby.default) # `default` diagnostics setting (applies by default)
 end
-

data/bin/mindee.rb

@@ -3,127 +3,28 @@
 
 require 'bundler/setup'
 require 'optparse'
-require 'mindee'
-
-require_relative 'cli_products'
-
-options = {}
-
-# Initializes universal-specific options
-# @param cli_parser [OptionParser]
-def custom_subcommand(cli_parser, options)
-  cli_parser.on('-v [VERSION]', '--version [VERSION]', 'Model version for the API') do |v|
-    options[:endpoint_version] = v
-  end
-  cli_parser.on('-a ACCOUNT_NAME', '--account ACCOUNT_NAME', 'API account name for the endpoint') do |v|
-    options[:account_name] = v
-  end
-end
-
-product_parser = {}
-PRODUCTS.each do |doc_key, doc_value|
-  product_parser[doc_key] = OptionParser.new do |opts|
-    opts.on('-w', '--all-words', 'Include words in response') do |v|
-      options[:all_words] = v
-    end
-    opts.on('-c', '--cut-pages', "Cut document pages") do |v|
-      options[:cut_pages] = v
-    end
-    opts.on('-k [KEY]', '--key [KEY]', 'API key for the endpoint') do |v|
-      options[:api_key] = v
-    end
-    opts.on('-f', '--full', "Print the full data, including pages") do |v|
-      options[:print_full] = true
-    end
-    opts.on('-F', '--fix-pdf', "Attempts to fix broken PDF files before sending them to the server.") do |v|
-      options[:repair_pdf] = true
-    end
-    if doc_key != 'universal'
-      opts.banner = "#{doc_value[:description]}. \nUsage: \nmindee.rb universal [options] endpoint_name file\nor\nmindee.rb universal [options] endpoint_name file"
-      custom_subcommand(opts, options)
-    end
-    if doc_value[:async]
-      if doc_value[:sync]
-        opts.on("-A", "--async", "Call asynchronously") do |v|
-          options[:parse_async] = v
-        end
-      end
-    end
+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"
   end
-end
-
-global_parser = OptionParser.new do |opts|
-  opts.banner = "Usage: mindee.rb product [options] file"
-  opts.separator "Available products:"
-  opts.separator "  #{PRODUCTS.keys.join("\n  ")}"
-end
-
-command = ARGV.shift
-unless PRODUCTS.include?(command)
-  abort(global_parser.help)
-end
-doc_class = PRODUCTS[command][:doc_class]
-product_parser[command].parse!
+  main_command = ARGV.shift
 
-if command == 'universal'
-  if ARGV.length < 2
-    $stderr.puts "The '#{command}' command requires both ENDPOINT_NAME and file arguments."
-    abort(product_parser[command].help)
-  end
-  endpoint_name = ARGV[0]
-  options[:file_path] = ARGV[1]
-else
-  if ARGV.length < 1
-    $stderr.puts "file missing"
-    abort(product_parser[command].help)
-  end
-  endpoint_name = nil
-  options[:file_path] = ARGV[0]
-end
-
-mindee_client = Mindee::Client.new(api_key: options[:api_key])
-if options[:file_path].start_with?("https://")
-  input_source = mindee_client.source_from_url(options[:file_path])
-else
-  input_source = mindee_client.source_from_path(options[:file_path], repair_pdf: options[:repair_pdf])
-end
-
-if command == 'universal'
-  custom_endpoint = mindee_client.create_endpoint(
-    endpoint_name: endpoint_name,
-    account_name: options[:account_name],
-    version: options[:endpoint_version].nil? ? "1" : options[:endpoint_version]
-  )
-else
-  custom_endpoint = nil
-end
-
-if options[:cut_pages].nil? || !options[:cut_pages].is_a?(Integer) || options[:cut_pages] < 0
-  page_options = nil
-else
-  page_options = Mindee::PageOptions.new(params: {
-    page_indexes: (0..options[:cut_pages].to_i).to_a,
-    operation: :KEEP_ONLY,
-    on_min_pages: 0,
-  })
-end
-
-if options[:parse_async].nil?
-  if !PRODUCTS[command][:sync]
-    options[:parse_async] = true
+  case main_command
+  when 'v1'
+    v1_parser.execute
+  when 'v2'
+    v2_parser.execute
   else
-    options[:parse_async] = false
+    abort(main_parser.help)
   end
 end
-result = mindee_client.parse(
-  input_source,
-  doc_class,
-  options: { endpoint: custom_endpoint,
-             options: Mindee::ParseOptions.new(params: { page_options: page_options }), enqueue: options[:parse_async] }
-)
 
-if options[:print_full]
-  puts result.document
-else
-  puts result.document.inference.prediction
-end
+setup_main_parser

data/bin/v1/parser.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'mindee'
+require_relative 'products'
+
+module MindeeCLI
+  # Mindee Command Line Interface
+  # V1 CLI class.
+  class V1Parser
+    # @return [Array<String>]
+    attr_reader :arguments
+
+    # @return [OptionParser]
+    attr_reader :options_parser
+
+    # @return [Parser]
+    attr_reader :product_parser
+
+    def initialize(arguments)
+      @arguments = arguments
+      @options_parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: mindee v1 product [options] file'
+        opts.separator 'Available products:'
+        opts.separator "  #{V1_PRODUCTS.keys.join("\n  ")}"
+      end
+      @product_parser = init_product_parser
+    end
+
+    # @param cli_parser [OptionParser]
+    def custom_subcommand(cli_parser)
+      cli_parser.on('-v [VERSION]', '--version [VERSION]', 'Model version for the API') do |v|
+        @options[:endpoint_version] = v
+      end
+      cli_parser.on('-a ACCOUNT_NAME', '--account ACCOUNT_NAME', 'API account name for the endpoint') do |v|
+        @options[:account_name] = v
+      end
+    end
+
+    # @return [Hash]
+    def init_product_parser
+      v1_product_parser = {}
+      V1_PRODUCTS.each do |doc_key, doc_value|
+        v1_product_parser[doc_key] = OptionParser.new do |options_parser|
+          options_parser.on('-w', '--all-words', 'Include words in response') { |v| @options[:all_words] = v }
+          options_parser.on('-k [KEY]', '--key [KEY]', 'API key for the endpoint') { |v| @options[:api_key] = v }
+          options_parser.on('-o FORMAT', '--output-format FORMAT', ['raw', 'full', 'summary'],
+                            'Format of the output (raw, full, summary). Default: summary') do |format|
+            @options[:output_format] = format
+          end
+          options_parser.on('-F', '--fix-pdf', 'Repair PDF') { @options[:repair_pdf] = true }
+
+          if doc_key != 'universal'
+            options_parser.banner = "Usage: mindee v1 #{doc_key} [options] file"
+            custom_subcommand(options_parser)
+          end
+
+          if doc_value[:async] && doc_value[:sync]
+            options_parser.on('-A', '--async', 'Call asynchronously') { |v| @options[:parse_async] = v }
+          end
+        end
+      end
+      v1_product_parser
+    end
+
+    # @param product_command [String]
+    # @param endpoint_name [String, nil]
+    # @param options [Hash]
+    # @return [Mindee::V1::Parsing::Common::ApiResponse]
+    def send(product_command, endpoint_name, options)
+      mindee_client = Mindee::V1::Client.new(api_key: options[:api_key])
+      doc_class = V1_PRODUCTS[product_command][:doc_class]
+      input_source = setup_input_source(mindee_client, options)
+      custom_endpoint = setup_endpoint(mindee_client, product_command, endpoint_name, options)
+      options[:parse_async] = !V1_PRODUCTS[product_command][:sync] if options[:parse_async].nil?
+
+      mindee_client.parse(
+        input_source,
+        doc_class,
+        options: { endpoint: custom_endpoint,
+                   enqueue: options[:parse_async] }
+      )
+    end
+
+    def print_result(result, output_format)
+      if output_format == :raw
+        puts JSON.pretty_generate(JSON.parse(result.raw_http))
+      else
+        puts output_format == :full ? result.document : result.document.inference.prediction
+      end
+    end
+
+    # @param product_command [String]
+    def execute
+      @options = { output_format: :summary }
+      product_command = @arguments.shift
+
+      abort(@options_parser.help) unless V1_PRODUCTS.include?(product_command)
+      @product_parser[product_command].parse!
+
+      if product_command == 'universal'
+        if @arguments.length < 2
+          warn "The 'universal' command requires both ENDPOINT_NAME and file arguments."
+          abort(@product_parser[product_command].help)
+        end
+        endpoint_name = @arguments[0]
+        @options[:file_path] = @arguments[1]
+      else
+        if @arguments.empty?
+          warn 'file missing'
+          abort(@product_parser[product_command].help)
+        end
+        endpoint_name = nil
+        @options[:file_path] = @arguments[0]
+      end
+
+      result = send(product_command, endpoint_name, @options)
+      print_result(result, output_format)
+    end
+
+    private
+
+    # @return [Symbol]
+    def output_format
+      @options[:output_format]&.to_sym || :summary
+    end
+
+    # @param mindee_client [Mindee::V1::Client]
+    # @param options [Hash]
+    # @return [Hash]
+    def setup_input_source(mindee_client, options)
+      if options[:file_path].start_with?('https://')
+        mindee_client.source_from_url(options[:file_path])
+      else
+        mindee_client.source_from_path(options[:file_path], repair_pdf: options[:repair_pdf])
+      end
+    end
+
+    # @param mindee_client [Mindee::V1::Client]
+    # @param product_command [String]
+    # @param endpoint_name [String, nil]
+    # @param options [Hash]
+    # @return [Mindee::HTTP::Endpoint, nil]
+    def setup_endpoint(mindee_client, product_command, endpoint_name, options)
+      return unless product_command == 'universal'
+
+      mindee_client.create_endpoint(
+        endpoint_name: endpoint_name,
+        account_name: options[:account_name],
+        version: options[:endpoint_version] || '1'
+      )
+    end
+  end
+end