zerobounce-sdk 2.1.8 → 3.0.0

data/lib/zerobounce/api_key.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Zerobounce
+  # Checks an API key before it is sent.
+  module ApiKey
+    module_function
+
+    # The key, unchanged, or an ArgumentError when it has surrounding
+    # whitespace or control characters (a key read from a file with its
+    # newline). Such a key would fail at the API, and the HTTP library's own
+    # error could quote it unredacted.
+    def check!(api_key)
+      key = api_key.to_s
+      if key != key.strip || key.match?(/[\u0000-\u001f\u007f]/)
+        raise ArgumentError, 'api_key has surrounding whitespace or control characters'
+      end
+
+      api_key
+    end
+  end
+end

data/lib/zerobounce/api_urls.rb

@@ -14,5 +14,14 @@ module Zerobounce
 
     # Bulk API URLs
     BULK_DEFAULT_URL = 'https://bulkapi.zerobounce.net/v2/'
+
+    # The S3 and SFTP/FTP bulk jobs live on the bulkapi host WITHOUT the /v2
+    # path. See https://www.zerobounce.net/docs/api-integrations.
+    BULK_ROOT_URL = 'https://bulkapi.zerobounce.net/'
+
+    # The list evaluator and the Inbox Placement Tester have their own base
+    # URLs, not paths built from the bulk one.
+    LIST_EVALUATOR_URL = 'https://bulkapi.zerobounce.net/v2/listevaluator/'
+    INBOX_PLACEMENT_URL = 'https://bulkapi.zerobounce.net/api/ipt'
   end
 end

data/lib/zerobounce/base_request.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'zerobounce/api_urls'
+require 'zerobounce/response_error'
+require 'zerobounce/api_key'
+require 'zerobounce/error'
 
 # https://github.com/rest-client/rest-client
 require 'rest-client'
@@ -41,36 +45,120 @@ module Zerobounce
       canonical
     end
 
+    def self.__require_https__(url)
+      unless url.to_s.downcase.start_with?('https://')
+        raise ArgumentError, 'API URL must be an https:// URL'
+      end
+      url
+    end
+
+    # Removes the API key from error text. The key the request actually used
+    # (a Zerobounce::Client's or with_api_key's, which is thread-local) is
+    # redacted as well as the global one, in its raw and URL-encoded forms.
+    def self.__redact_api_key__(message)
+      text = message.to_s
+      [current_api_key, Zerobounce.config.apikey].uniq.each do |key|
+        next if key.nil? || key.to_s.strip.empty?
+
+        [key.to_s, URI.encode_www_form_component(key.to_s)].uniq.each do |form|
+          text = text.gsub(form, '***')
+        end
+      end
+      text
+    end
+
+    def self.current_api_key
+      key = Thread.current[:zerobounce_api_key]
+      key.nil? ? Zerobounce.config.apikey : key
+    end
+
+    # The key for this request, or an error before anything is sent. A key with
+    # surrounding whitespace or control characters (one read from a file with
+    # its newline) would go out as it is and fail, and the HTTP library could
+    # quote it unredacted.
+    def self.__checked_api_key__
+      api_key = current_api_key
+      raise ('API key must be assigned') if api_key.nil? || api_key.to_s.strip.empty?
+
+      ApiKey.check!(api_key)
+    end
+
+    # The message for an HTTP error status.
+    def self.__http_error_message__(error)
+      code = error.http_code.to_i
+      # max_redirects is 0, so a 3xx is never followed; say so rather than
+      # reporting its (usually empty) body as an "Empty response".
+      if code.between?(300, 399)
+        return "ZeroBounce answered with a redirect (HTTP #{code}), which is not followed"
+      end
+
+      ResponseError.message_from(error.response)
+    end
+
+    def self.__execute_request__(**kwargs)
+      kwargs[:max_redirects] = 0
+      user_agent = Zerobounce.config.headers && Zerobounce.config.headers[:user_agent]
+      kwargs[:headers] = (kwargs[:headers] || {}).merge(user_agent: user_agent) if user_agent
+      RestClient::Request.execute(**kwargs)
+    rescue RestClient::ExceptionWithResponse => e
+      # Re-raised as the same RestClient class (RestClient::NotFound and so
+      # on), so `rescue RestClient::...` and #http_code keep working as they
+      # did up to 2.1.8. Only the message changes: the API's short error text,
+      # with the key redacted.
+      e.message = __redact_api_key__(__http_error_message__(e))
+      raise e
+    rescue RestClient::Exception => e
+      e.message = __redact_api_key__(e.message)
+      raise e
+    rescue StandardError => e
+      # Same class and backtrace, redacted message. cause: nil, because the
+      # original (unredacted) error would otherwise ride along as #cause and
+      # be printed by #full_message.
+      raise e.exception(__redact_api_key__(e.message)), cause: nil
+    end
+
     def self._get(root, path, params, content_type='application/json')
 
       # puts path
       # puts Zerobounce.config.apikey
 
-      raise ("API key must be assigned") if not Zerobounce.config.apikey
+      api_key = __checked_api_key__
 
-      params[:api_key] = Zerobounce.config.apikey
+      params[:api_key] = api_key
       url = "#{Zerobounce::BaseRequest.__root_without_trailing_slashes__(root)}/#{path}"
+      Zerobounce::BaseRequest.__require_https__(url)
 
-      response = RestClient.get(url, {params: params})
+      response = __execute_request__(method: :get, url: url, timeout: 120, headers: { params: params })
       return response
     end
 
     def self._post(root, path, params, content_type='application/json', filepath=nil)
 
-      raise ("API key must be assigned") if not Zerobounce.config.apikey
+      api_key = __checked_api_key__
 
-      params[:api_key] = Zerobounce.config.apikey
+      params[:api_key] = api_key
       url = "#{Zerobounce::BaseRequest.__root_without_trailing_slashes__(root)}/#{path}"
+      Zerobounce::BaseRequest.__require_https__(url)
       response = nil
 
       if filepath or content_type == 'multipart/form-data'
+        params.each do |key, value|
+          params[key] = value ? 'true' : 'false' if value == true || value == false
+        end
         params[:file] = File.new(Zerobounce::BaseRequest.__safe_file_path__(filepath), 'rb')
         params[:multipart] = true
-        response = RestClient.post(url, params)
+        response = __execute_request__(method: :post, url: url, payload: params, timeout: 120)
 
       elsif content_type == 'application/json'
-        response = RestClient.post(url, params.to_json, \
-                      content_type: :json, accept: :json)
+        response = __execute_request__(
+          method: :post,
+          url: url,
+          payload: params.to_json,
+          timeout: 120,
+          headers: { content_type: :json, accept: :json }
+        )
+      elsif content_type == 'application/x-www-form-urlencoded'
+        response = __execute_request__(method: :post, url: url, payload: params, timeout: 120)
       else
         # this shouldn't happen
         raise Error.new('Unknown content type specified in request.'\
@@ -79,5 +167,169 @@ module Zerobounce
       return response
     end
 
+    # Sends a request with an explicit method and an optional form or JSON body.
+    #
+    # The endpoints ported from the Python SDK need shapes _get and _post cannot
+    # express: a form-encoded POST on an arbitrary base URL, and the Inbox
+    # Placement Tester's PUT and DELETE with the API key on the query string.
+    # +bearer+ sends the key in an Authorization header instead of a query
+    # parameter, which the Inbox Placement Tester requires and which keeps the
+    # key out of request logs.
+    def self.__execute_with_method__(method, url, params, form: nil, json: nil, bearer: false)
+      api_key = __checked_api_key__
+
+      params = (params || {}).dup
+      extra = {}
+      if bearer
+        extra[:authorization] = "Bearer #{api_key}"
+      else
+        params = params.merge(api_key: api_key)
+      end
+      Zerobounce::BaseRequest.__require_https__(url)
+
+      options = { method: method, url: url, timeout: 120 }
+      if form
+        options[:payload] = form
+        options[:headers] = extra.merge(params: params, content_type: 'application/x-www-form-urlencoded')
+      elsif json
+        options[:payload] = json.to_json
+        options[:headers] = extra.merge(params: params, content_type: :json, accept: :json)
+      else
+        options[:headers] = extra.merge(params: params)
+      end
+
+      __execute_request__(**options)
+    end
+
+    # A GET or form-encoded POST against an arbitrary base URL, for the list
+    # evaluator, which has its own host.
+    def self.root_request(method, root, path, params, form: nil)
+      url = "#{__root_without_trailing_slashes__(root)}/#{path.to_s.sub(%r{\A/}, '')}"
+      __parse_json_response__(__execute_with_method__(method, url, params, form: form))
+    end
+
+    # One Inbox Placement Tester call.
+    def self.ipt_request(method, path, params = {}, json: nil)
+      root = Zerobounce.configuration.inbox_placement_root_url
+      url = "#{__root_without_trailing_slashes__(root)}/#{path.to_s.sub(%r{\A/}, '')}"
+      # LIVE: the Inbox Placement Tester authenticates with a Bearer header.
+      # Sent as an api_key parameter the request is rejected as unauthorized.
+      response = __execute_with_method__(method, url, params, json: json, bearer: true)
+      return nil if response.body.to_s.strip.empty?
+
+      __parse_json_response__(response)
+    end
+
+    # Whether a Content-Type names a JSON body.
+    #
+    # The API types most responses 'application/json' but some
+    # 'application/json; charset=utf-8'. Compared with ==, the second kind
+    # skipped JSON parsing entirely, so an {"error": ...} payload came back as
+    # a raw String and read as a success. Only the media type decides; the
+    # parameters after the semicolon are ignored.
+    def self.__json_content_type__(content_type)
+      media_type = content_type.to_s.split(';', 2).first.to_s.strip.downcase
+      media_type == 'application/json' || media_type.end_with?('+json')
+    end
+
+    # The root for the S3 and SFTP/FTP jobs: the bulkapi host WITHOUT /v2.
+    #
+    # +bulk_root_url+ (ZEROBOUNCE_BULK_ROOT_URL) wins when it is set, so these
+    # endpoints can be pointed at a mock server on their own. Left unset it is
+    # derived from +bulk_api_root_url+ with the /v2 stripped, so overriding
+    # that one alone still moves these endpoints with it.
+    def self.bulk_api_root_without_v2
+      configured = Zerobounce.configuration.bulk_root_url.to_s.strip
+      return __root_without_trailing_slashes__(configured) unless configured.empty?
+
+      derived = Zerobounce.configuration.bulk_api_root_url.to_s.sub(%r{/v2/?$}, '')
+      derived = ApiUrls::BULK_ROOT_URL if derived.strip.empty?
+      __root_without_trailing_slashes__(derived)
+    end
+
+    # Whether a "success" field means failure. The API sends it as a JSON
+    # false, "false" or "False" depending on the endpoint.
+    def self.__success_means_failure__(value)
+      return !value if value == true || value == false
+
+      value.is_a?(String) && value.strip.casecmp('false').zero?
+    end
+
+    # LIVE: {"success": false} on an HTTP 200 is a failure, not a result. The
+    # API answers an unknown bulk file id that way. Applied to the main API
+    # and the bulk API alike.
+    def self.__raise_if_success_false__(response, parsed)
+      return unless parsed.is_a?(Hash) && parsed.key?('success') && __success_means_failure__(parsed['success'])
+
+      raise ApiResponseError.new(
+        ResponseError.message_from_parts(response.code, response.headers[:content_type].to_s, response.body.to_s),
+        response.code
+      )
+    end
+
+    # A value that reads as an error: a non-blank String.
+    def self.__error_text__(value)
+      value.is_a?(String) && !value.strip.empty?
+    end
+
+    # An "error" value that means failure: anything but nil or a blank String.
+    def self.__error_value__(value)
+      !value.nil? && !(value.is_a?(String) && value.strip.empty?)
+    end
+
+    # The keys a message-only body is made of.
+    MESSAGE_KEYS = %w[error message error_message Message Error detail].freeze
+
+    # A body made only of message keys (no "success"), for the calls whose
+    # result is never a bare message.
+    def self.__raise_if_message_only__(response, parsed)
+      return if parsed.empty? || parsed.key?('success')
+      return unless parsed.keys.all? { |key| MESSAGE_KEYS.include?(key) }
+
+      text = MESSAGE_KEYS.map { |key| parsed[key] }.find { |value| __error_text__(value) }
+      raise ApiResponseError.new(ResponseError.strip_prefix(text), response.code) if text
+    end
+
+    # A dead or invalid key on an HTTP 200: no "success" field and a non-empty
+    # "Error" (LIVE: the filters spell it so) or "error_message".
+    def self.__raise_if_bare_error__(response, parsed)
+      return if parsed.key?('success')
+
+      %w[Error error_message].each do |key|
+        next unless __error_text__(parsed[key])
+
+        raise ApiResponseError.new(ResponseError.strip_prefix(parsed[key]), response.code)
+      end
+    end
+
+    def self.__parse_json_response__(response)
+      body = response.body.to_s
+      content_type = (response.headers[:content_type] || '').to_s
+      code = response.code
+      if ResponseError.html?(body, content_type) || body.strip.empty?
+        raise ApiResponseError.new(ResponseError.message_from_parts(code, content_type, body), code)
+      end
+      begin
+        parsed = JSON.parse(body)
+      rescue JSON::ParserError
+        raise ApiResponseError.new('ZeroBounce returned a response that is not valid JSON.', code)
+      end
+      return parsed unless parsed.is_a?(Hash)
+
+      __raise_if_success_false__(response, parsed)
+
+      raise ApiResponseError.new(ResponseError.strip_prefix(parsed['error']), code) if __error_value__(parsed['error'])
+      # The Inbox Placement Tester is a Django REST framework app and reports
+      # its errors under "detail" rather than "error"/"message".
+      if __error_value__(parsed['detail'])
+        raise ApiResponseError.new(ResponseError.strip_prefix(parsed['detail']), code)
+      end
+      __raise_if_bare_error__(response, parsed)
+      if parsed.key?('errors') && parsed['errors'].is_a?(Array) && !parsed['errors'].empty?
+        raise ApiResponseError.new(ResponseError.strip_prefix(parsed['errors'][0]['error']), code)
+      end
+      parsed
+    end
+
   end
 end

data/lib/zerobounce/client.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'zerobounce/api_key'
+
+module Zerobounce
+  # One API key. Package methods share Zerobounce.config; a Client does not.
+  class Client
+    def initialize(apikey)
+      ApiKey.check!(apikey) unless apikey.nil? || apikey.to_s.strip.empty?
+      @apikey = apikey
+    end
+
+    # Keeps the API key out of logs and consoles.
+    def inspect
+      "#<#{self.class.name} apikey=#{@apikey.nil? ? 'nil' : '[FILTERED]'}>"
+    end
+
+    def validate(email, ip_address = nil, **options)
+      Zerobounce.with_api_key(@apikey) { Zerobounce.validate(email, ip_address, **options) }
+    end
+
+    def credits
+      Zerobounce.with_api_key(@apikey) { Zerobounce.credits }
+    end
+
+    def validate_batch(emails, ip_addresses = [], **options)
+      Zerobounce.with_api_key(@apikey) { Zerobounce.validate_batch(emails, ip_addresses, **options) }
+    end
+  end
+end

data/lib/zerobounce/configuration.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'rest-client'
-require 'dotenv'
 require_relative 'api_urls'
 
 module Zerobounce
@@ -24,19 +23,41 @@ module Zerobounce
   # @attr [String] bulk_api_root_url
   #   The Zerobounce bulk API root URL.
   #
+  # @attr [String, nil] bulk_root_url
+  #   The root for the S3 and SFTP/FTP bulk jobs: the bulkapi host without the
+  #   /v2 path. Defaults to nil, which derives it from {#bulk_api_root_url}.
+  #
   # @attr [Array<Symbol>] valid_statues
   #   The statuses that are considered valid by {Response#valid?}.
   class Configuration
-    attr_accessor :headers, :apikey, :api_root_url, :bulk_api_root_url, :valid_statuses, :mock
+    attr_accessor :headers, :apikey, :api_root_url, :bulk_api_root_url, :bulk_root_url,
+                  :list_evaluator_root_url, :inbox_placement_root_url, :valid_statuses, :mock
 
     def initialize(mock = false)
-      File.file?('.env') ? Dotenv.load('.env') : Dotenv.load
       self.apikey = ENV['ZEROBOUNCE_API_KEY']
       self.api_root_url = ENV['ZEROBOUNCE_API_URL'] || ApiUrls::DEFAULT_URL
       self.bulk_api_root_url = ENV['ZEROBOUNCE_BULK_API_URL'] || ApiUrls::BULK_DEFAULT_URL
+      # The S3/SFTP root is the only one that can be derived from another base
+      # URL, so it is left unset unless it is asked for: BaseRequest then takes
+      # bulk_api_root_url with the /v2 stripped. Set it - in code or through
+      # ZEROBOUNCE_BULK_ROOT_URL - to point those jobs somewhere on their own.
+      self.bulk_root_url = ENV['ZEROBOUNCE_BULK_ROOT_URL']
+      # These two are separate base URLs rather than paths built from
+      # bulk_api_root_url, so overriding that alone leaves them on the live API.
+      self.list_evaluator_root_url = ENV['ZEROBOUNCE_LIST_EVALUATOR_URL'] || ApiUrls::LIST_EVALUATOR_URL
+      self.inbox_placement_root_url = ENV['ZEROBOUNCE_INBOX_PLACEMENT_URL'] || ApiUrls::INBOX_PLACEMENT_URL
       self.valid_statuses = %i[valid catch_all accept_all]
       self.headers = { user_agent: "ZerobounceRubyGem/#{Zerobounce::VERSION}" }
       self.mock = mock
     end
+
+    # Keep the API key out of logs, consoles and error pages that call #inspect.
+    def inspect
+      vars = instance_variables.map do |var|
+        value = var == :@apikey && apikey ? '[FILTERED]' : instance_variable_get(var).inspect
+        "#{var}=#{value}"
+      end
+      "#<#{self.class.name} #{vars.join(', ')}>"
+    end
   end
 end

data/lib/zerobounce/error.rb

@@ -54,6 +54,26 @@ module Zerobounce
     end
   end
 
+  # A failed API response.
+  #
+  # Carries the HTTP status so callers can tell a 403 (Cloudflare) from a
+  # 400/404 (API) or a 429 (the Warmup rate limit). The Warmup client raises
+  # it. The validation client raises the RestClient exception for an HTTP
+  # error status (status in #http_code), as it did up to 2.1.8, and this
+  # class, with the 2xx status (usually 200), for an error reported on a
+  # successful HTTP response; both carry the same short message. It is a
+  # RuntimeError, which those errors were before, so `rescue RuntimeError`
+  # still catches them.
+  class ApiResponseError < RuntimeError
+    # @return [Integer] the HTTP status of the failed response, or 0
+    attr_reader :status_code
+
+    def initialize(message, status_code = 0)
+      super(message)
+      @status_code = status_code.to_i
+    end
+  end
+
   # Server returned a 500 error.
   #
   # @author Aaron Frase

data/lib/zerobounce/get_file_helper.rb

@@ -2,6 +2,8 @@
 
 require 'json'
 require 'stringio'
+require 'zerobounce/error'
+require 'zerobounce/response_error'
 
 module Zerobounce
   # Bulk getfile response handling (v2): HTTP errors, JSON error bodies (including HTTP 200).
@@ -69,17 +71,13 @@ module Zerobounce
       body_str = response.body.to_s
       ct = (response.headers[:content_type] || response.headers['Content-Type'] || '').to_s
 
-      if code > 299
-        msg = if body_str.lstrip.start_with?('{')
-                format_error_message(body_str)
-              else
-                body_str.empty? ? "HTTP #{code}" : body_str
-              end
-        raise msg
+      # An empty body is no result file: an error, as in the other SDKs.
+      if code > 299 || body_str.strip.empty? || ResponseError.html?(body_str, ct)
+        raise ApiResponseError.new(ResponseError.message_from_parts(code, ct, body_str), code)
       end
 
       if should_treat_as_error?(body_str, ct)
-        raise format_error_message(body_str)
+        raise ApiResponseError.new(format_error_message(body_str), code)
       end
 
       io = StringIO.new(response.body)