mindee 3.19.1 → 4.0.0

data/lib/mindee/{extraction/common → image}/image_extractor.rb

@@ -4,20 +4,19 @@ require 'mini_magick'
 require 'origami'
 require 'stringio'
 require 'tempfile'
-require_relative '../../input/sources'
+require_relative '../input/sources'
 require_relative 'extracted_image'
 
 module Mindee
   # Image Extraction Module.
-  module Extraction
+  module Image
     # Image Extraction wrapper class.
     module ImageExtractor
+      # Attaches an image as a new page in a PdfDocument object.
+      #
+      # @param [StringIO] input_buffer Input buffer. Only supports JPEG.
+      # @return [Origami::PDF] A PdfDocument handle.
       def self.attach_image_as_new_file(input_buffer, format: 'jpg')
-        # Attaches an image as a new page in a PdfDocument object.
-        #
-        # @param [StringIO] input_buffer Input buffer. Only supports JPEG.
-        # @return [Origami::PDF] A PdfDocument handle.
-
         magick_image = MiniMagick::Image.read(input_buffer)
         # NOTE: some jpeg images get rendered as three different versions of themselves per output if the format isn't
         # converted.
@@ -35,9 +34,9 @@ module Mindee
       # @param [Integer] page_id ID of the Page to extract from.
       # @param [Array<Array<Mindee::Geometry::Point>>, Array<Mindee::Geometry::Quadrangle>] polygons List of coordinates
       # to extract.
-      # @return [Array<Mindee::Extraction::ExtractedImage>] Extracted Images.
+      # @return [Array<Mindee::Image::ExtractedImage>] Extracted Images.
       def self.extract_multiple_images_from_source(input_source, page_id, polygons)
-        new_stream = load_input_source_pdf_page_as_image(input_source, page_id)
+        new_stream = load_input_source_pdf_page_as_stringio(input_source, page_id)
         new_stream.seek(0)
 
         extract_images_from_polygons(input_source, new_stream, page_id, polygons)
@@ -49,13 +48,13 @@ module Mindee
       # @param [StringIO] pdf_stream Buffer of the PDF.
       # @param [Integer] page_id Page ID.
       # @param [Array<Mindee::Geometry::Point, Mindee::Geometry::Polygon, Mindee::Geometry::Quadrangle>] polygons
-      # @return [Array<Mindee::Extraction::ExtractedImage>] Extracted Images.
+      # @return [Array<Mindee::Image::ExtractedImage>] Extracted Images.
       def self.extract_images_from_polygons(input_source, pdf_stream, page_id, polygons)
         extracted_elements = []
 
         polygons.each_with_index do |polygon, element_id|
-          polygon = normalize_polygon(polygon)
-          page_content = read_page_content(pdf_stream)
+          polygon = ImageUtils.normalize_polygon(polygon)
+          page_content = ImageUtils.read_page_content(pdf_stream)
 
           min_max_x = Geometry.get_min_max_x([
                                                polygon.top_left,
@@ -69,16 +68,16 @@ module Mindee
                                                polygon.top_right,
                                                polygon.bottom_left,
                                              ])
-          file_extension = determine_file_extension(input_source)
-          cropped_image = crop_image(page_content, min_max_x, min_max_y)
+          file_extension = ImageUtils.determine_file_extension(input_source)
+          cropped_image = ImageUtils.crop_image(page_content, min_max_x, min_max_y)
           if file_extension == 'pdf'
             cropped_image.format('jpg')
           else
-            cropped_image.format(file_extension)
+            cropped_image.format(file_extension.to_s)
           end
 
           buffer = StringIO.new
-          write_image_to_buffer(cropped_image, buffer)
+          ImageUtils.write_image_to_buffer(cropped_image, buffer)
           file_name = "#{input_source.filename}_page#{page_id}-#{element_id}.#{file_extension}"
 
           extracted_elements << create_extracted_image(buffer, file_name, page_id, element_id)
@@ -87,73 +86,16 @@ module Mindee
         extracted_elements
       end
 
-      # Retrieves the bounding box of a polygon.
-      #
-      # @param [Array<Point>, Mindee::Geometry::Polygon] polygon
-      def self.normalize_polygon(polygon)
-        if polygon.is_a?(Mindee::Geometry::Polygon)
-          Mindee::Geometry.get_bounding_box(polygon)
-        else
-          polygon
-        end
-      end
-
-      # Loads a buffer into a MiniMagick Image.
-      #
-      # @param [StringIO] pdf_stream Buffer containg the PDF
-      # @return [MiniMagick::Image] a valid MiniMagick image handle.
-      def self.read_page_content(pdf_stream)
-        pdf_stream.rewind
-        MiniMagick::Image.read(pdf_stream)
-      end
-
-      # Crops a MiniMagick Image from a the given bounding box.
-      #
-      # @param [MiniMagick::Image] image Input Image.
-      # @param [Mindee::Geometry::MinMax] min_max_x minimum & maximum values for the x coordinates.
-      # @param [Mindee::Geometry::MinMax] min_max_y minimum & maximum values for the y coordinates.
-      def self.crop_image(image, min_max_x, min_max_y)
-        width = image[:width].to_i
-        height = image[:height].to_i
-
-        image.format('jpg')
-        new_width = (min_max_x.max - min_max_x.min) * width
-        new_height = (min_max_y.max - min_max_y.min) * height
-        image.crop("#{new_width}x#{new_height}+#{min_max_x.min * width}+#{min_max_y.min * height}")
-
-        image
-      end
-
-      # Writes a MiniMagick::Image to a buffer.
-      #
-      # @param [MiniMagick::Image] image a valid MiniMagick image.
-      # @param [StringIO] buffer
-      def self.write_image_to_buffer(image, buffer)
-        image.write(buffer)
-      end
-
-      # Retrieves the file extension from the main file to apply it to the extracted images. Note: coerces pdf as jpg.
-      #
-      # @param [Mindee::Input::Source::LocalInputSource] input_source Local input source.
-      # @return [String] A valid file extension.
-      def self.determine_file_extension(input_source)
-        if input_source.pdf? || input_source.filename.downcase.end_with?('pdf')
-          'jpg'
-        else
-          File.extname(input_source.filename).strip.downcase[1..]
-        end
-      end
-
       # Generates an ExtractedImage.
       #
       # @param [StringIO] buffer Buffer containing the image.
       # @param [String] file_name Name for the file.
-      # @param [Object] page_id ID of the page the file was generated from.
+      # @param [Object] page_id ID of the page the file was universal from.
       # @param [Object] element_id ID of the element of a given page.
       def self.create_extracted_image(buffer, file_name, page_id, element_id)
         buffer.rewind
         ExtractedImage.new(
-          Mindee::Input::Source::BytesInputSource.new(buffer.read, file_name),
+          Mindee::Input::Source::BytesInputSource.new(buffer.read.to_s, file_name),
           page_id,
           element_id
         )
@@ -163,11 +105,11 @@ module Mindee
       #
       # @param input_file [LocalInputSource] Local input.
       # @param [Integer] page_id Page ID.
-      # @return [MiniMagick::Image] A valid PdfDocument handle.
-      def self.load_input_source_pdf_page_as_image(input_file, page_id)
+      # @return [StringIO] A valid PdfDocument handle.
+      def self.load_input_source_pdf_page_as_stringio(input_file, page_id)
         input_file.io_stream.rewind
         if input_file.pdf?
-          Mindee::PDF::PdfProcessor.get_page(Origami::PDF.read(input_file.io_stream), page_id)
+          Mindee::PDF::PDFProcessor.get_page(Origami::PDF.read(input_file.io_stream), page_id)
         else
           input_file.io_stream
         end

data/lib/mindee/image/image_utils.rb

@@ -30,13 +30,14 @@ module Mindee
       # @param [MiniMagick::Image, StringIO, File, Tempfile] image The input image
       # @return [MiniMagick::Image]
       def self.to_image(image)
-        if image.respond_to?(:read) && image.respond_to?(:rewind)
+        if image.is_a?(MiniMagick::Image)
+          image
+        elsif image.is_a?(StringIO) || image.is_a?(IO) || image.is_a?(File) || image.is_a?(Tempfile)
           image.rewind
           MiniMagick::Image.read(image)
-        elsif image.is_a?(MiniMagick::Image)
-          image
         else
-          raise "Expected an I/O object or a MiniMagick::Image. '#{image.class}' given instead."
+          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."
         end
       end
 
@@ -59,7 +60,7 @@ module Mindee
       # @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 'Provided image could not be processed for resizing.' if original.nil?
+        raise Errors::MindeeImageError, 'Provided image could not be processed for resizing.' if original.nil?
 
         return [original.width, original.height] if max_width.nil? && max_height.nil?
 
@@ -68,8 +69,8 @@ module Mindee
 
         scale_factor = [width_ratio, height_ratio].min
 
-        new_width = (original.width * scale_factor).to_i
-        new_height = (original.height * scale_factor).to_i
+        new_width = (original.width.to_f * scale_factor).to_i
+        new_height = (original.height.to_f * scale_factor).to_i
 
         [new_width, new_height]
       end
@@ -99,6 +100,66 @@ module Mindee
         compressed_image.quality image_quality.to_s
         compressed_image
       end
+
+      # Retrieves the bounding box of a polygon.
+      #
+      # @param [Array<Point>, Mindee::Geometry::Polygon] polygon
+      def self.normalize_polygon(polygon)
+        if polygon.is_a?(Mindee::Geometry::Polygon) ||
+           (polygon.is_a?(Array) && polygon[0].is_a?(Mindee::Geometry::Point))
+          Mindee::Geometry.get_bounding_box(polygon)
+        elsif polygon.is_a?(Mindee::Geometry::Quadrilateral)
+          polygon
+        else
+          raise Errors::MindeeGeometryError, 'Provided polygon has an invalid type.'
+        end
+      end
+
+      # Loads a buffer into a MiniMagick Image.
+      #
+      # @param [StringIO] pdf_stream Buffer containg the PDF
+      # @return [MiniMagick::Image] a valid MiniMagick image handle.
+      def self.read_page_content(pdf_stream)
+        pdf_stream.rewind
+        MiniMagick::Image.read(pdf_stream)
+      end
+
+      # Crops a MiniMagick Image from a the given bounding box.
+      #
+      # @param [MiniMagick::Image] image Input Image.
+      # @param [Mindee::Geometry::MinMax] min_max_x minimum & maximum values for the x coordinates.
+      # @param [Mindee::Geometry::MinMax] min_max_y minimum & maximum values for the y coordinates.
+      def self.crop_image(image, min_max_x, min_max_y)
+        width = image[:width].to_i
+        height = image[:height].to_i
+
+        image.format('jpg')
+        new_width = (min_max_x.max - min_max_x.min) * width
+        new_height = (min_max_y.max - min_max_y.min) * height
+        image.crop("#{new_width}x#{new_height}+#{min_max_x.min * width}+#{min_max_y.min * height}")
+
+        image
+      end
+
+      # Writes a MiniMagick::Image to a buffer.
+      #
+      # @param [MiniMagick::Image] image a valid MiniMagick image.
+      # @param [StringIO] buffer
+      def self.write_image_to_buffer(image, buffer)
+        image.write(buffer)
+      end
+
+      # Retrieves the file extension from the main file to apply it to the extracted images. Note: coerces pdf as jpg.
+      #
+      # @param [Mindee::Input::Source::LocalInputSource] input_source Local input source.
+      # @return [String, nil] A valid file extension.
+      def self.determine_file_extension(input_source)
+        if input_source.pdf? || input_source.filename.downcase.end_with?('pdf')
+          'jpg'
+        else
+          File.extname(input_source.filename.to_s).strip.downcase[1..].to_s
+        end
+      end
     end
   end
 end

data/lib/mindee/image.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'image/extracted_image'
 require_relative 'image/image_compressor'
+require_relative 'image/image_extractor'
 require_relative 'image/image_utils'

data/lib/mindee/input/local_response.rb

@@ -16,18 +16,18 @@ module Mindee
       def initialize(input_file)
         case input_file
         when IO, StringIO, File, Tempfile
-          str_stripped = input_file.read.gsub(%r{[\r\n]}, '')
+          str_stripped = input_file.read.to_s.gsub(%r{[\r\n]}, '')
           @file = StringIO.new(str_stripped)
           @file.rewind
         when Pathname, String
-          @file = if Pathname(input_file).exist?
-                    StringIO.new(File.read(input_file, encoding: 'utf-8').gsub(%r{[\r\n]}, ''))
+          @file = if Pathname(input_file.to_s).exist?
+                    StringIO.new(File.read(input_file.to_s, encoding: 'utf-8').gsub(%r{[\r\n]}, ''))
                   else
-                    StringIO.new(input_file.gsub(%r{[\r\n]}, ''))
+                    StringIO.new(input_file.to_s.gsub(%r{[\r\n]}, ''))
                   end
           @file.rewind
         else
-          raise "Incompatible type for input '#{input_file.class}'."
+          raise Errors::MindeeInputError, "Incompatible type for input '#{input_file.class}'."
         end
       end
 
@@ -38,7 +38,7 @@ module Mindee
         file_str = @file.read
         JSON.parse(file_str, object_class: Hash)
       rescue JSON::ParserError
-        raise "File is not a valid dict. #{file_str}"
+        raise Errors::MindeeInputError, "File is not a valid dict. #{file_str}"
       end
 
       # Processes the secret key
@@ -56,14 +56,14 @@ module Mindee
           @file.rewind
           mac = OpenSSL::HMAC.hexdigest(algorithm, self.class.process_secret_key(secret_key), @file.read)
         rescue StandardError
-          raise 'Could not get HMAC signature from payload.'
+          raise Errors::MindeeInputError, 'Could not get HMAC signature from payload.'
         end
         mac
       end
 
       # @param secret_key [String] Secret key, either a string or a byte/byte array.
       # @param signature [String]
-      # @return [Boolean]
+      # @return [bool]
       def valid_hmac_signature?(secret_key, signature)
         signature == get_hmac_signature(secret_key)
       end

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

@@ -9,17 +9,17 @@ module Mindee
       class Base64InputSource < LocalInputSource
         # @param base64_string [String]
         # @param filename [String]
-        # @param fix_pdf [Boolean]
-        def initialize(base64_string, filename, fix_pdf: false)
-          io_stream = StringIO.new(base64_string.unpack1('m*'))
+        # @param repair_pdf [bool]
+        def initialize(base64_string, filename, repair_pdf: false)
+          io_stream = StringIO.new(base64_string.unpack1('m*').to_s)
           io_stream.set_encoding Encoding::BINARY
-          super(io_stream, filename, fix_pdf: fix_pdf)
+          super(io_stream, filename, repair_pdf: repair_pdf)
         end
 
         # Overload of the same function to prevent a base64 from being re-encoded.
-        # @param close [Boolean]
+        # @param close [bool]
         # @return [Array<String, [String, aBinaryString ], [Hash, nil] >]
-        def read_document(close: true)
+        def read_contents(close: true)
           @io_stream.seek(0)
           data = @io_stream.read
           @io_stream.close if close

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

@@ -9,11 +9,11 @@ module Mindee
       class BytesInputSource < LocalInputSource
         # @param raw_bytes [String]
         # @param filename [String]
-        # @param fix_pdf [Boolean]
-        def initialize(raw_bytes, filename, fix_pdf: false)
+        # @param repair_pdf [bool]
+        def initialize(raw_bytes, filename, repair_pdf: false)
           io_stream = StringIO.new(raw_bytes)
           io_stream.set_encoding Encoding::BINARY
-          super(io_stream, filename, fix_pdf: fix_pdf)
+          super(io_stream, filename, repair_pdf: repair_pdf)
         end
       end
     end

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

@@ -9,10 +9,10 @@ module Mindee
       class FileInputSource < LocalInputSource
         # @param input_file [File]
         # @param filename [String]
-        # @param fix_pdf [Boolean]
-        def initialize(input_file, filename, fix_pdf: false)
+        # @param repair_pdf [bool]
+        def initialize(input_file, filename, repair_pdf: false)
           io_stream = input_file
-          super(io_stream, filename, fix_pdf: fix_pdf)
+          super(io_stream, filename, repair_pdf: repair_pdf)
         end
       end
     end

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

@@ -2,6 +2,7 @@
 
 require 'stringio'
 require 'marcel'
+require 'fileutils'
 
 require_relative '../../pdf'
 require_relative '../../image'
@@ -20,29 +21,6 @@ module Mindee
         'image/webp',
       ].freeze
 
-      # Standard error for invalid mime types
-      class MimeTypeError < StandardError
-      end
-
-      # Error sent if the file's mimetype isn't allowed
-      class InvalidMimeTypeError < MimeTypeError
-        # @return [String]
-        attr_reader :invalid_mimetype
-
-        # @param mime_type [String]
-        def initialize(mime_type)
-          @invalid_mimetype = mime_type
-          super("'#{@invalid_mimetype}' mime type not allowed, must be one of #{ALLOWED_MIME_TYPES.join(', ')}")
-        end
-      end
-
-      # Error sent if a pdf file couldn't be fixed
-      class UnfixablePDFError < MimeTypeError
-        def initialize
-          super("Corrupted PDF couldn't be repaired.")
-        end
-      end
-
       # Base class for loading documents.
       class LocalInputSource
         # @return [String]
@@ -52,27 +30,31 @@ module Mindee
         # @return [StringIO]
         attr_reader :io_stream
 
-        # @param io_stream [StringIO]
+        # @param io_stream [StringIO, File]
         # @param filename [String]
-        # @param fix_pdf [Boolean]
-        def initialize(io_stream, filename, fix_pdf: false)
+        # @param repair_pdf [bool]
+        def initialize(io_stream, filename, repair_pdf: false)
           @io_stream = io_stream
           @filename = filename
-          @file_mimetype = if fix_pdf
+          @file_mimetype = if repair_pdf
                              Marcel::MimeType.for @io_stream
                            else
                              Marcel::MimeType.for @io_stream, name: @filename
                            end
-          return if ALLOWED_MIME_TYPES.include? @file_mimetype
+          if ALLOWED_MIME_TYPES.include? @file_mimetype
+            logger.debug("Loaded new input #{@filename} from #{self.class}")
+            return
+          end
 
-          if filename.end_with?('.pdf') && fix_pdf
+          if filename.end_with?('.pdf') && repair_pdf
             rescue_broken_pdf(@io_stream)
             @file_mimetype = Marcel::MimeType.for @io_stream
 
+            logger.debug("Loaded new input #{@filename} from #{self.class}")
             return if ALLOWED_MIME_TYPES.include? @file_mimetype
           end
 
-          raise InvalidMimeTypeError, @file_mimetype.to_s
+          raise Errors::MindeeMimeTypeError, @file_mimetype.to_s
         end
 
         # Attempts to fix pdf files if mimetype is rejected.
@@ -81,7 +63,7 @@ module Mindee
         # @param stream [StringIO]
         def rescue_broken_pdf(stream)
           stream.gets('%PDF-')
-          raise UnfixablePDFError if stream.eof? || stream.pos > 500
+          raise Errors::MindeePDFError if stream.eof? || stream.pos > 500
 
           stream.pos = stream.pos - 5
           data = stream.read
@@ -97,7 +79,7 @@ module Mindee
         end
 
         # Parses a PDF file according to provided options.
-        # @param options [Hash, nil] Page cutting/merge options:
+        # @param options [PageOptions, nil] Page cutting/merge options:
         #
         #  * `:page_indexes` Zero-based list of page indexes.
         #  * `:operation` Operation to apply on the document, given the `page_indexes specified:
@@ -106,25 +88,45 @@ module Mindee
         #  * `:on_min_pages` Apply the operation only if document has at least this many pages.
         def process_pdf(options)
           @io_stream.seek(0)
-          @io_stream = PdfProcessor.parse(@io_stream, options)
+          @io_stream = PDF::PDFProcessor.parse(@io_stream, options)
         end
 
         # Reads a document.
-        # @param close [Boolean]
+        # @param close [bool]
         # @return [Array<String, [String, aBinaryString ], [Hash, nil] >]
-        def read_document(close: true)
+        def read_contents(close: true)
+          logger.debug("Reading data from: #{@filename}")
           @io_stream.seek(0)
           # Avoids needlessly re-packing some files
           data = @io_stream.read
+          @io_stream.rewind
           @io_stream.close if close
           ['document', data, { filename: Mindee::Input::Source.convert_to_unicode_escape(@filename) }]
         end
 
-        def count_pdf_pages
+        # Write the file to a given path. Uses the initial file name by default.
+        # @param path [String] Path to write the file to.
+        def write_to_file(path)
+          full_path = if File.directory?(path) || path.end_with?('/')
+                        File.join(path, @filename)
+                      else
+                        path
+                      end
+          FileUtils.mkdir_p(File.dirname(full_path))
+          @io_stream.rewind
+          File.binwrite(full_path, @io_stream.read)
+          logger.debug("Wrote file successfully to #{full_path}")
+          @io_stream.rewind
+        end
+
+        # Returns the page count for a document.
+        # Defaults to one for images.
+        # @return [Integer]
+        def count_pages
           return 1 unless pdf?
 
           @io_stream.seek(0)
-          pdf_processor = Mindee::PDF::PdfProcessor.open_pdf(@io_stream)
+          pdf_processor = Mindee::PDF::PDFProcessor.open_pdf(@io_stream)
           pdf_processor.pages.size
         end
 
@@ -132,10 +134,10 @@ module Mindee
         # @param [Integer] quality Quality of the output file.
         # @param [Integer, nil] max_width Maximum width (Ignored for PDFs).
         # @param [Integer, nil] max_height Maximum height (Ignored for PDFs).
-        # @param [Boolean] force_source_text Whether to force the operation on PDFs with source text.
+        # @param [bool] force_source_text Whether to force the operation on PDFs with source text.
         #   This will attempt to re-render PDF text over the rasterized original. If disabled, ignored the operation.
         #   WARNING: this operation is strongly discouraged.
-        # @param [Boolean] disable_source_text If the PDF has source text, whether to re-apply it to the original or
+        # @param [bool] disable_source_text If the PDF has source text, whether to re-apply it to the original or
         #   not. Needs force_source_text to work.
         def compress!(quality: 85, max_width: nil, max_height: nil, force_source_text: false, disable_source_text: true)
           buffer = if pdf?
@@ -158,7 +160,7 @@ module Mindee
         end
 
         # Checks whether the file has source text if it is a pdf. False otherwise
-        # @return [Boolean] True if the file is a PDF and has source text.
+        # @return [bool] True if the file is a PDF and has source text.
         def source_text?
           Mindee::PDF::PDFTools.source_text?(@io_stream)
         end
@@ -171,7 +173,7 @@ module Mindee
         unicode_escape_string = ''.dup
         string.each_char do |char|
           unicode_escape_string << if char.bytesize > 1
-                                     "\\u#{char.unpack1('U').to_s(16).rjust(4, '0')}"
+                                     "\\u#{format('%04x', char.unpack1('U'))}"
                                    else
                                      char
                                    end

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

@@ -9,10 +9,10 @@ module Mindee
       # Load a document from a path.
       class PathInputSource < LocalInputSource
         # @param filepath [String]
-        # @param fix_pdf [Boolean]
-        def initialize(filepath, fix_pdf: false)
+        # @param repair_pdf [bool]
+        def initialize(filepath, repair_pdf: false)
           io_stream = File.open(filepath, 'rb')
-          super(io_stream, File.basename(filepath), fix_pdf: fix_pdf)
+          super(io_stream, File.basename(filepath), repair_pdf: repair_pdf)
         end
       end
     end

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

@@ -3,17 +3,20 @@
 require 'net/http'
 require 'uri'
 require 'fileutils'
+require_relative '../../logging'
 
 module Mindee
   module Input
     module Source
       # Load a remote document from a file url.
-      class UrlInputSource
+      class URLInputSource
         # @return [String]
         attr_reader :url
 
         def initialize(url)
-          raise 'URL must be HTTPS' unless url.start_with? 'https://'
+          raise Errors::MindeeInputError, 'URL must be HTTPS' unless url.start_with? 'https://'
+
+          logger.debug("URL input: #{url}")
 
           @url = url
         end
@@ -27,7 +30,7 @@ module Mindee
         # @param token [String, nil] Optional token for JWT-based authentication.
         # @param max_redirects [Integer] Maximum amount of redirects to follow.
         # @return [String] The full path of the saved file.
-        def save_to_file(path, filename: nil, username: nil, password: nil, token: nil, max_redirects: 3)
+        def write_to_file(path, filename: nil, username: nil, password: nil, token: nil, max_redirects: 3)
           response_body = fetch_file_content(username: username, password: password, token: token,
                                              max_redirects: max_redirects)
 
@@ -53,7 +56,7 @@ module Mindee
                                              max_redirects: max_redirects)
           bytes = StringIO.new(response_body)
 
-          BytesInputSource.new(bytes.read, filename)
+          BytesInputSource.new(bytes.read || '', filename || '')
         end
 
         # Fetches the file content from the URL.
@@ -72,9 +75,9 @@ module Mindee
 
           response = make_request(uri, request, max_redirects)
           if response.code.to_i > 299
-            raise "Failed to download file: HTTP status code #{response.code}"
+            raise Errors::MindeeAPIError, "Failed to download file: HTTP status code #{response.code}"
           elsif response.code.to_i < 200
-            raise "Failed to download file: Invalid response code #{response.code}."
+            raise Errors::MindeeAPIError, "Failed to download file: Invalid response code #{response.code}."
           end
 
           response.body
@@ -83,7 +86,7 @@ module Mindee
         private
 
         def extract_filename_from_url(uri)
-          filename = File.basename(uri.path)
+          filename = File.basename(uri.path.to_s)
           filename.empty? ? '' : filename
         end
 
@@ -100,7 +103,7 @@ module Mindee
             response = http.request(request)
             if response.is_a?(Net::HTTPRedirection) && max_redirects.positive?
               location = response['location']
-              raise 'No location in redirection header.' if location.nil?
+              raise Errors::MindeeInputError, 'No location in redirection header.' if location.nil?
 
               new_uri = URI.parse(location)
               request = Net::HTTP::Get.new(new_uri)

data/lib/mindee/logging/logger.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Mindee
+  # Mindee logging module.
+  module Logging
+    @logger = Logger.new($stdout)
+    log_level = ENV.fetch('MINDEE_LOG_LEVEL', 'WARN')
+    @logger.level = Logger.const_get(log_level)
+
+    class << self
+      attr_accessor :logger
+    end
+  end
+end

data/lib/mindee/logging.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'logging/logger'