remove_bg 1.2.0 → 1.5.0

data/gemfiles/faraday_0_16.gemfile

@@ -0,0 +1,11 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "faraday", "~> 0.16.0"
+
+group :development do
+  gem "appraisal", git: "https://github.com/thoughtbot/appraisal.git", ref: "5868643"
+end
+
+gemspec path: "../"

data/gemfiles/faraday_0_17.gemfile

@@ -0,0 +1,11 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "faraday", "~> 0.17.0"
+
+group :development do
+  gem "appraisal", git: "https://github.com/thoughtbot/appraisal.git", ref: "5868643"
+end
+
+gemspec path: "../"

data/gemfiles/faraday_1_x.gemfile

@@ -0,0 +1,11 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "faraday", "~> 1.0"
+
+group :development do
+  gem "appraisal", git: "https://github.com/thoughtbot/appraisal.git", ref: "5868643"
+end
+
+gemspec path: "../"

data/lib/remove_bg.rb

@@ -4,16 +4,38 @@ require "remove_bg/configuration"
 require "remove_bg/request_options"
 
 module RemoveBg
+  # Removes the background from an image on the local file system
+  # @param image_path [String] Path to the input image
+  # @param options [Hash<Symbol, Object>] Image processing options (see API docs)
+  # @return [RemoveBg::Result|RemoveBg::CompositeResult] a processed image result
+  #
   def self.from_file(image_path, raw_options = {})
     options = RemoveBg::RequestOptions.new(raw_options)
     ApiClient.new.remove_from_file(image_path, options)
   end
 
+  # Removes the background from the image at the URL specified
+  # @param image_url [String] Absolute URL of the input image
+  # @param options [Hash<Symbol, Object>] Image processing options (see API docs)
+  # @return [RemoveBg::Result|RemoveBg::CompositeResult] A processed image result
+  #
   def self.from_url(image_url, raw_options = {})
     options = RemoveBg::RequestOptions.new(raw_options)
     ApiClient.new.remove_from_url(image_url, options)
   end
 
+  # Fetches account information for the globally configured API key, or a
+  # specific API key if provided
+  # @param options [Hash<Symbol, Object>]
+  # @return [RemoveBg::AccountInfo]
+  #
+  def self.account_info(raw_options = {})
+    options = RemoveBg::BaseRequestOptions.new(raw_options)
+    ApiClient.new.account_info(options)
+  end
+
+  # Yields the global Remove.bg configuration
+  # @yield [RemoveBg::Configuration]
   def self.configure
     yield RemoveBg::Configuration.configuration
   end

data/lib/remove_bg/account_info.rb

@@ -0,0 +1,34 @@
+module RemoveBg
+  class AccountInfo
+    # @return [RemoveBg::AccountInfo::ApiInfo]
+    attr_reader :api
+
+    # @return [RemoveBg::AccountInfo::CreditsInfo]
+    attr_reader :credits
+
+    def initialize(attributes)
+      @api = ApiInfo.new(**attributes.fetch(:api))
+      @credits = CreditsInfo.new(**attributes.fetch(:credits))
+    end
+
+    class ApiInfo
+      attr_reader :free_calls, :sizes
+
+      def initialize(free_calls:, sizes:)
+        @free_calls = free_calls
+        @sizes = sizes
+      end
+    end
+
+    class CreditsInfo
+      attr_reader :total, :subscription, :payg, :enterprise
+
+      def initialize(total:, subscription:, payg:, enterprise:)
+        @total = total
+        @subscription = subscription
+        @payg = payg
+        @enterprise = enterprise
+      end
+    end
+  end
+end

data/lib/remove_bg/api.rb

@@ -2,19 +2,13 @@ module RemoveBg
   module Api
     URL = "https://api.remove.bg"
 
+    V1_ACCOUNT = "/v1.0/account"
+    private_constant :V1_ACCOUNT
+
     V1_REMOVE_BG = "/v1.0/removebg"
     private_constant :V1_REMOVE_BG
 
     HEADER_API_KEY = "X-Api-Key"
     private_constant :HEADER_API_KEY
-
-    HEADER_WIDTH = "X-Width"
-    private_constant :HEADER_WIDTH
-
-    HEADER_HEIGHT = "X-Height"
-    private_constant :HEADER_HEIGHT
-
-    HEADER_CREDITS_CHARGED = "X-Credits-Charged"
-    private_constant :HEADER_CREDITS_CHARGED
   end
 end

data/lib/remove_bg/api_client.rb

@@ -1,7 +1,13 @@
 require "json"
+require "tempfile"
+
+require_relative "account_info"
 require_relative "api"
+require_relative "composite_result"
 require_relative "error"
 require_relative "http_connection"
+require_relative "rate_limit_info"
+require_relative "result_metadata"
 require_relative "result"
 require_relative "upload"
 require_relative "url_validator"
@@ -10,59 +16,141 @@ module RemoveBg
   class ApiClient
     include RemoveBg::Api
 
+    # @param connection [Faraday::Connection]
+    #
     def initialize(connection: RemoveBg::HttpConnection.build)
       @connection = connection
     end
 
+    # Removes the background from an image on the local file system
+    # @param image_path [String]
+    # @param options [RemoveBg::RequestOptions]
+    # @return [RemoveBg::Result|RemoveBg::CompositeResult]
+    # @raise [RemoveBg::Error]
+    #
     def remove_from_file(image_path, options)
       data = options.data.merge(image_file: Upload.for_file(image_path))
       request_remove_bg(data, options.api_key)
     end
 
+    # Removes the background from the image at the URL specified
+    # @param image_url [String]
+    # @param options [RemoveBg::RequestOptions]
+    # @return [RemoveBg::Result|RemoveBg::CompositeResult]
+    # @raise [RemoveBg::Error]
+    #
     def remove_from_url(image_url, options)
       RemoveBg::UrlValidator.validate(image_url)
       data = options.data.merge(image_url: image_url)
       request_remove_bg(data, options.api_key)
     end
 
+    # Fetches account information
+    # @param options [RemoveBg::BaseRequestOptions]
+    # @return [RemoveBg::AccountInfo]
+    # @raise [RemoveBg::Error]
+    #
+    def account_info(options)
+      request_account_info(options.api_key)
+    end
+
     private
 
     attr_reader :connection
 
     def request_remove_bg(data, api_key)
+      download = Tempfile.new("remove-bg-download")
+      download.binmode
+
+      streaming = false
+
       response = connection.post(V1_REMOVE_BG, data) do |req|
         req.headers[HEADER_API_KEY] = api_key
+
+        # Faraday v0.16 & v1.0+ support streaming, v0.17 did not (rollback release)
+        if req.options.respond_to?(:on_data)
+          streaming = true
+          req.options.on_data = Proc.new do |chunk, _|
+            download.write(chunk)
+          end
+        end
+      end
+
+      # Faraday v0.15 / v0.17
+      if !streaming
+        download.write(response.body)
+      end
+
+      download.rewind
+
+      if response.status == 200
+        parse_image_result(headers: response.headers, download: download)
+      else
+        response_body = download.read
+        download.close
+        download.unlink
+        handle_http_error(response: response, body: response_body)
+      end
+    end
+
+    def request_account_info(api_key)
+      response = connection.get(V1_ACCOUNT) do |req|
+        req.headers[HEADER_API_KEY] = api_key
       end
 
+      if response.status == 200
+        parse_account_result(response)
+      else
+        handle_http_error(response: response, body: response.body)
+      end
+    end
+
+    def handle_http_error(response:, body:)
+      error_message = parse_error_message(body)
+
       case response.status
-      when 200
-        parse_result(response)
+      when 429
+        rate_limit = RateLimitInfo.new(response.headers)
+        raise RemoveBg::RateLimitError.new(error_message, response, body, rate_limit)
       when 400..499
-        error_message = parse_error_message(response)
-        raise RemoveBg::ClientHttpError.new(error_message, response)
+        raise RemoveBg::ClientHttpError.new(error_message, response, body)
       when 500..599
-        error_message = parse_error_message(response)
-        raise RemoveBg::ServerHttpError.new(error_message, response)
+        raise RemoveBg::ServerHttpError.new(error_message, response, body)
       else
-        raise RemoveBg::HttpError.new("An unknown error occurred", response)
+        raise RemoveBg::HttpError.new("An unknown error occurred", response, body)
       end
     end
 
-    def parse_result(response)
-      RemoveBg::Result.new(
-        data: response.body,
-        width: response.headers[HEADER_WIDTH]&.to_i,
-        height: response.headers[HEADER_HEIGHT]&.to_i,
-        credits_charged: response.headers[HEADER_CREDITS_CHARGED]&.to_f,
+    def parse_image_result(headers:, download:)
+      result_for_content_type(headers["Content-Type"]).new(
+        download: download,
+        metadata: ResultMetadata.new(headers),
+        rate_limit: RateLimitInfo.new(headers)
       )
     end
 
-    def parse_error_message(response)
-      parse_errors(response).first["title"]
+    def result_for_content_type(content_type)
+      if content_type&.include?("application/zip")
+        CompositeResult
+      else
+        Result
+      end
+    end
+
+    def parse_account_result(response)
+      attributes = JSON.parse(response.body, symbolize_names: true)
+        .fetch(:data)
+        .fetch(:attributes)
+
+      RemoveBg::AccountInfo.new(attributes)
+    end
+
+    def parse_error_message(response_body)
+      parse_errors(response_body).first["title"]
     end
 
-    def parse_errors(response)
-      JSON.parse(response.body)["errors"] || []
+    def parse_errors(response_body)
+      JSON.parse(response_body)["errors"] || []
     rescue JSON::ParserError
       [{ "title" => "Unable to parse response" }]
     end

data/lib/remove_bg/base_request_options.rb

@@ -0,0 +1,32 @@
+require_relative "error"
+
+module RemoveBg
+  class BaseRequestOptions
+    attr_reader :api_key, :data
+
+    def initialize(raw_options = {})
+      options = raw_options.dup
+      @api_key = resolve_api_key(options.delete(:api_key))
+      @data = options
+    end
+
+    private
+
+    def resolve_api_key(request_api_key)
+      api_key = request_api_key || global_api_key
+
+      if api_key.nil? || api_key.empty?
+        raise RemoveBg::Error, <<~MSG
+          Please configure an API key or specify one per request. API key was:
+          #{api_key.inspect}
+        MSG
+      end
+
+      api_key
+    end
+
+    def global_api_key
+      RemoveBg::Configuration.configuration.api_key
+    end
+  end
+end

data/lib/remove_bg/composite_result.rb

@@ -0,0 +1,65 @@
+require_relative "result"
+
+module RemoveBg
+  # Handles image composition for larger images (over 10MP) where transparency is
+  # required.
+  # @see RemoveBg::Result
+  #
+  class CompositeResult < Result
+    # Saves the ZIP archive containing the alpha.png and color.jpg files
+    # (useful if you want to handle composition yourself)
+    # @param file_path [string]
+    # @param overwrite [boolean] Overwrite any existing file at the specified path
+    # @return [nil]
+    #
+    def save_zip(file_path, overwrite: false)
+      if File.exist?(file_path) && !overwrite
+        raise FileOverwriteError.new(file_path)
+      end
+
+      FileUtils.cp(download, file_path)
+    end
+
+    private
+
+    def image_file
+      composite_file
+    end
+
+    def composite_file
+      @composite_file ||= begin
+        binary_tempfile(["composed", ".png"])
+          .tap { |file| compose_to_file(file) }
+      end
+    end
+
+    def color_file
+      @color_file ||= binary_tempfile(["color", ".jpg"])
+    end
+
+    def alpha_file
+      @alpha_file ||= binary_tempfile(["alpha", ".png"])
+    end
+
+    def compose_to_file(destination)
+      extract_parts
+
+      ImageComposer.new.compose(
+        color_file: color_file,
+        alpha_file: alpha_file,
+        destination_path: destination.path
+      )
+    end
+
+    def extract_parts
+      Zip::File.open(download) do |zf|
+        zf.find_entry("color.jpg").extract(color_file.path) { true }
+        zf.find_entry("alpha.png").extract(alpha_file.path) { true }
+      end
+    end
+
+    def binary_tempfile(basename)
+      Tempfile.new(basename).tap { |file| file.binmode }
+    end
+  end
+end

data/lib/remove_bg/configuration.rb

@@ -1,13 +1,24 @@
+require_relative "image_composer"
+
 module RemoveBg
   class Configuration
-    attr_accessor :api_key
+    attr_accessor :api_key, :image_processor, :auto_upgrade_png_to_zip
 
     def self.configuration
-      @configuration ||= Configuration.new
+      @configuration ||= Configuration.new.tap do |config|
+        config.image_processor = ImageComposer.detect_image_processor
+
+        # Upgrade to ZIP where possible to save bandwith
+        config.auto_upgrade_png_to_zip = true
+      end
     end
 
     def self.reset
-      @configuration = Configuration.new
+      @configuration = nil
+    end
+
+    def can_process_images?
+      !image_processor.nil?
     end
   end
 end

data/lib/remove_bg/error.rb

@@ -2,17 +2,35 @@ module RemoveBg
   class Error < StandardError; end
 
   class HttpError < Error
+    # @return [Faraday::Response]
     attr_reader :http_response
 
-    def initialize(message, http_response)
+    # @return [String]
+    attr_reader :http_response_body
+
+    def initialize(message, http_response, http_response_body)
       @http_response = http_response
+      @http_response_body = http_response_body
       super(message)
     end
   end
 
+  # Raised for all HTTP 4XX errors
   class ClientHttpError < HttpError; end
+
+  # Raised for all HTTP 5XX errors
   class ServerHttpError < HttpError; end
 
+  # Raised for HTTP 429 status code
+  class RateLimitError < ClientHttpError
+    attr_reader :rate_limit
+
+    def initialize(message, http_response, http_response_body, rate_limit)
+      @rate_limit = rate_limit
+      super(message, http_response, http_response_body)
+    end
+  end
+
   class FileError < Error
     attr_reader :file_path