💥 ✨ add support for V2 crop & split operation

.github/workflows/_test-integrations.yml

@@ -45,11 +45,11 @@ jobs:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
 
-      - name: Install Ghostscript on Ubuntu
+      - name: Install Ghostscript and ImageMagick on Ubuntu
         if: runner.os == 'Linux'
         run: |
           sudo apt update
-          sudo apt-get install -y ghostscript
+          sudo apt-get install -y ghostscript imagemagick
 
       - name: Install Ghostscript and ImageMagick on macOS
         if: runner.os == 'macOS'

examples/auto_invoice_splitter_extraction.rb

@@ -22,7 +22,7 @@ def parse_single_page(mindee_client, input_source)
 end
 
 def parse_multi_page(mindee_client, input_source)
-  pdf_extractor = Mindee::PDF::PDFExtractor::PDFExtractor.new(input_source)
+  pdf_extractor = Mindee::PDF::PDFExtractor.new(input_source)
   invoice_splitter_response = mindee_client.parse(
     input_source,
     Mindee::V1::Product::InvoiceSplitter::InvoiceSplitterV1,

lib/mindee.rb

@@ -7,7 +7,7 @@
 
 module Mindee
   # Mindee internal error module.
-  module Errors
+  module Error
   end
 
   # Custom extraction module
@@ -94,6 +94,16 @@ module V2
     module HTTP
     end
 
+    module FileOperation
+      # Crop operations.
+      module Crop
+      end
+
+      # Split operations.
+      module Split
+      end
+    end
+
     # Product-specific module.
     module Product
     end

lib/mindee/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'error/mindee_error'
+require_relative 'error/mindee_http_error'
+require_relative 'error/mindee_http_error_v2'
+require_relative 'error/mindee_input_error'

lib/mindee/errors/mindee_error.rb → lib/mindee/error/mindee_error.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Mindee
-  module Errors
+  module Error
     # Base class for all custom mindee errors.
     class MindeeError < StandardError; end
 

lib/mindee/errors/mindee_http_error.rb → lib/mindee/error/mindee_http_error.rb

@@ -3,7 +3,7 @@
 require_relative 'mindee_error'
 
 module Mindee
-  module Errors
+  module Error
     # API HttpError
     class MindeeHTTPError < MindeeError
       # @return [String]

lib/mindee/errors/mindee_http_error_v2.rb → lib/mindee/error/mindee_http_error_v2.rb

@@ -4,7 +4,7 @@
 require_relative '../v2/parsing/error_item'
 
 module Mindee
-  module Errors
+  module Error
     # API V2 HttpError
     class MindeeHTTPErrorV2 < MindeeError
       # @return [Integer] The HTTP status code returned by the server.

lib/mindee/errors/mindee_http_unknown_error_v2.rb → lib/mindee/error/mindee_http_unknown_error_v2.rb

@@ -3,7 +3,7 @@
 require_relative 'mindee_error'
 
 module Mindee
-  module Errors
+  module Error
     # Unknown HTTP error for the V2 API.
     class MindeeHTTPUnknownErrorV2 < MindeeHTTPErrorV2
       def initialize(http_error)

lib/mindee/errors/mindee_input_error.rb → lib/mindee/error/mindee_input_error.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Mindee
-  module Errors
-    # Base class for errors relating to input documents.
+  module Error
+    # Base class for error relating to input documents.
     class MindeeInputError < MindeeError; end
 
     # Errors relating to sources (documents) handling.

lib/mindee/http/http_error_handler.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
-require_relative '../errors/mindee_http_error'
+require_relative '../error/mindee_http_error'
 
 module Mindee
   module HTTP
@@ -81,11 +81,11 @@ def handle_error(url, response)
         error_obj = create_error_obj(parsed_hash)
         case code
         when 400..499
-          Errors::MindeeHTTPClientError.new(error_obj || {}, url, code)
+          Error::MindeeHTTPClientError.new(error_obj || {}, url, code)
         when 500..599
-          Errors::MindeeHTTPServerError.new(error_obj || {}, url, code)
+          Error::MindeeHTTPServerError.new(error_obj || {}, url, code)
         else
-          Errors::MindeeHTTPError.new(error_obj || {}, url, code)
+          Error::MindeeHTTPError.new(error_obj || {}, url, code)
         end
       end
 
@@ -94,11 +94,11 @@ def handle_error(url, response)
       def generate_v2_error(hashed_response)
         code = hashed_response[:code].to_i
         if hashed_response.key?(:status)
-          Errors::MindeeHTTPErrorV2.new(hashed_response.transform_keys(&:to_s))
+          Error::MindeeHTTPErrorV2.new(hashed_response.transform_keys(&:to_s))
         elsif code < 200 || code > 399
-          Errors::MindeeHTTPErrorV2.new({ 'status' => code, 'detail' => 'No details available.' })
+          Error::MindeeHTTPErrorV2.new({ 'status' => code, 'detail' => 'No details available.' })
         else
-          Errors::MindeeHTTPErrorV2.new({ 'status' => -1, 'detail' => 'Unknown Error.' })
+          Error::MindeeHTTPErrorV2.new({ 'status' => -1, 'detail' => 'Unknown Error.' })
         end
       end
     end

lib/mindee/image/extracted_image.rb

@@ -18,23 +18,29 @@ class ExtractedImage
       attr_reader :buffer
 
       # Internal name for the file.
-      attr_reader :internal_file_name
+      attr_reader :filename
 
       # Initializes the ExtractedImage with a buffer and an internal file name.
       #
-      # @param input_source [LocalInputSource] Local source for input.
+      # @param input_source [LocalInputSource, BytesInputSource] Local source for input.
       # @param page_id [Integer] ID of the page the element was found on.
       # @param element_id [Integer, nil] ID of the element in a page.
-      def initialize(input_source, page_id, element_id)
+      # @param preserve_input_filename [Boolean] If true, keep the input source filename as-is.
+      def initialize(input_source, page_id, element_id, preserve_input_filename: false)
         @buffer = StringIO.new(input_source.io_stream.read.to_s)
         @buffer.rewind
-        extension = if input_source.pdf?
-                      '.jpg'
+
+        @filename = if preserve_input_filename
+                      input_source.filename.to_s
                     else
-                      File.extname(input_source.filename)
+                      extension = if input_source.pdf?
+                                    '.jpg'
+                                  else
+                                    File.extname(input_source.filename)
+                                  end
+                      base_name = File.basename(input_source.filename, File.extname(input_source.filename))
+                      "#{base_name}_p#{page_id}_#{element_id}#{extension}"
                     end
-        base_name = File.basename(input_source.filename, File.extname(input_source.filename))
-        @internal_file_name = "#{base_name}_p#{page_id}_#{element_id}#{extension}"
         @page_id = page_id
         @element_id = element_id.nil? ? 0 : element_id
       end
@@ -48,7 +54,7 @@ def initialize(input_source, page_id, element_id)
       def write_to_file(output_path, file_format = nil)
         resolved_path = Pathname.new(File.expand_path(output_path))
         if file_format.nil?
-          raise Errors::MindeeImageError, 'Invalid file format.' if resolved_path.extname.delete('.').empty?
+          raise Error::MindeeImageError, 'Invalid file format.' if resolved_path.extname.delete('.').empty?
 
           file_format = resolved_path.extname.delete('.').upcase
         end
@@ -59,8 +65,8 @@ def write_to_file(output_path, file_format = nil)
           image.write resolved_path.to_s
           logger.info("File saved successfully to '#{resolved_path}'")
         rescue StandardError
-          raise Errors::MindeeImageError, "Could not save file '#{output_path}'. " \
-                                          'Is the provided file path valid?.'
+          raise Error::MindeeImageError, "Could not save file '#{output_path}'. " \
+                                         'Is the provided file path valid?.'
         end
       end
 
@@ -69,7 +75,14 @@ def write_to_file(output_path, file_format = nil)
       # @return [FileInputSource] A BufferInput source.
       def as_source
         @buffer.rewind
-        Mindee::Input::Source::BytesInputSource.new(@buffer.read || '', @internal_file_name)
+        Mindee::Input::Source::BytesInputSource.new(@buffer.read || '', @filename)
+      end
+
+      # Return the file as a Mindee-compatible BufferInput source.
+      #
+      # @return [FileInputSource] A BufferInput source.
+      def as_input_source
+        as_source
       end
     end
   end

lib/mindee/image/image_extractor.rb

@@ -94,7 +94,8 @@ def self.create_extracted_image(buffer, file_name, page_id, element_id)
         ExtractedImage.new(
           Input::Source::BytesInputSource.new(buffer.read.to_s, file_name),
           page_id,
-          element_id
+          element_id,
+          preserve_input_filename: true
         )
       end
 

lib/mindee/image/image_utils.rb

@@ -37,7 +37,7 @@ def self.to_image(image)
           MiniMagick::Image.read(image)
         else
           img_class = image.class ? image.class.to_s : 'unknown format'
-          raise Errors::MindeeImageError, "Expected an I/O object or a MiniMagick::Image. '#{img_class}' given instead."
+          raise Error::MindeeImageError, "Expected an I/O object or a MiniMagick::Image. '#{img_class}' given instead."
         end
       end
 
@@ -60,7 +60,7 @@ def self.image_to_stringio(image, format = 'JPEG')
       # @param max_width [Integer] 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.
       def self.calculate_new_dimensions(original, max_width: nil, max_height: nil)
-        raise Errors::MindeeImageError, 'Provided image could not be processed for resizing.' if original.nil?
+        raise Error::MindeeImageError, 'Provided image could not be processed for resizing.' if original.nil?
 
         return [original.width, original.height] if max_width.nil? && max_height.nil?
 
@@ -111,7 +111,7 @@ def self.normalize_polygon(polygon)
         elsif polygon.is_a?(Mindee::Geometry::Quadrilateral)
           polygon
         else
-          raise Errors::MindeeGeometryError, 'Provided polygon has an invalid type.'
+          raise Error::MindeeGeometryError, 'Provided polygon has an invalid type.'
         end
       end
 

lib/mindee/input/base_parameters.rb

@@ -31,7 +31,7 @@ def initialize(
         polling_options: nil,
         close_file: true
       )
-        raise Errors::MindeeInputError, 'Model ID is required.' if model_id.empty? || model_id.nil?
+        raise Error::MindeeInputError, 'Model ID is required.' if model_id.empty? || model_id.nil?
 
         @model_id = model_id
         @file_alias = file_alias
@@ -72,7 +72,7 @@ def self.load_from_hash(params: {})
         params.transform_keys!(&:to_sym)
 
         if params.empty? || params[:model_id].nil? || params[:model_id].empty?
-          raise Errors::MindeeInputError, 'Model ID is required.'
+          raise Error::MindeeInputError, 'Model ID is required.'
         end
 
         polling_options_input = params.fetch(:page_options, PollingOptions.new)

lib/mindee/input/local_response.rb

@@ -27,7 +27,7 @@ def initialize(input_file)
                   end
           @file.rewind
         else
-          raise Errors::MindeeInputError, "Incompatible type for input '#{input_file.class}'."
+          raise Error::MindeeInputError, "Incompatible type for input '#{input_file.class}'."
         end
       end
 
@@ -38,7 +38,7 @@ def as_hash
         file_str = @file.read or raise 'File could not be read'
         JSON.parse(file_str, object_class: Hash)
       rescue JSON::ParserError
-        raise Errors::MindeeInputError, "File is not a valid dict. #{file_str}"
+        raise Error::MindeeInputError, "File is not a valid dict. #{file_str}"
       end
 
       # Processes the secret key
@@ -57,7 +57,7 @@ def get_hmac_signature(secret_key)
           mac = OpenSSL::HMAC.hexdigest(algorithm, self.class.process_secret_key(secret_key),
                                         @file.read || raise('File could not be read'))
         rescue StandardError
-          raise Errors::MindeeInputError, 'Could not get HMAC signature from payload.'
+          raise Error::MindeeInputError, 'Could not get HMAC signature from payload.'
         end
         mac
       end

lib/mindee/input/sources/local_input_source.rb

@@ -53,7 +53,7 @@ def initialize(io_stream, filename, repair_pdf: false)
             return if ALLOWED_MIME_TYPES.include? @file_mimetype
           end
 
-          raise Errors::MindeeMimeTypeError, @file_mimetype.to_s
+          raise Error::MindeeMimeTypeError, @file_mimetype.to_s
         end
 
         # @deprecated See {#fix_pdf!} or {#self.fix_pdf} instead.
@@ -69,7 +69,7 @@ def pdf?
         # Attempts to fix the PDF data in the file.
         # @param maximum_offset [Integer] Maximum offset to look for the PDF header.
         # @return [void]
-        # @raise [Mindee::Errors::MindeePDFError]
+        # @raise [Mindee::Error::MindeePDFError]
         def fix_pdf!(maximum_offset: 500)
           @io_stream = LocalInputSource.fix_pdf(@io_stream, maximum_offset: maximum_offset)
           @io_stream.rewind
@@ -80,11 +80,11 @@ def fix_pdf!(maximum_offset: 500)
         # @param stream [StringIO] The stream to fix.
         # @param maximum_offset [Integer] Maximum offset to look for the PDF header.
         # @return [StringIO] The fixed stream.
-        # @raise [Mindee::Errors::MindeePDFError]
+        # @raise [Mindee::Error::MindeePDFError]
         def self.fix_pdf(stream, maximum_offset: 500)
           out_stream = StringIO.new
           stream.gets('%PDF-')
-          raise Errors::MindeePDFError if stream.eof? || stream.pos > maximum_offset
+          raise Error::MindeePDFError if stream.eof? || stream.pos > maximum_offset
 
           stream.pos = stream.pos - 5
           out_stream << stream.read

lib/mindee/input/sources/url_input_source.rb

@@ -14,7 +14,7 @@ class URLInputSource
         attr_reader :url
 
         def initialize(url)
-          raise Errors::MindeeInputError, 'URL must be HTTPS' unless url.start_with? 'https://'
+          raise Error::MindeeInputError, 'URL must be HTTPS' unless url.start_with? 'https://'
 
           logger.debug("URL input: #{url}")
 
@@ -75,9 +75,9 @@ def fetch_file_content(username: nil, password: nil, token: nil, max_redirects:
 
           response = make_request(uri, request, max_redirects)
           if response.code.to_i > 299
-            raise Errors::MindeeAPIError, "Failed to download file: HTTP status code #{response.code}"
+            raise Error::MindeeAPIError, "Failed to download file: HTTP status code #{response.code}"
           elsif response.code.to_i < 200
-            raise Errors::MindeeAPIError, "Failed to download file: Invalid response code #{response.code}."
+            raise Error::MindeeAPIError, "Failed to download file: Invalid response code #{response.code}."
           end
 
           response.body
@@ -103,7 +103,7 @@ def make_request(uri, request, max_redirects)
             response = http.request(request)
             if response.is_a?(Net::HTTPRedirection) && max_redirects.positive?
               location = response['location']
-              raise Errors::MindeeInputError, 'No location in redirection header.' if location.nil?
+              raise Error::MindeeInputError, 'No location in redirection header.' if location.nil?
 
               new_uri = URI.parse(location)
               request = Net::HTTP::Get.new(new_uri)