zerobounce 0.0.5 → 0.2.0

data/lib/zerobounce/request/v1_request.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Zerobounce
+  class Request
+    # Request methods specific to V1 of the API.
+    module V1Request
+      # Valid v1 get query params
+      VALID_GET_PARAMS = %i[apikey ipaddress email].freeze
+
+      # Validate the email address.
+      #
+      # @param [Hash] params
+      # @option params [String] :email
+      # @option params [String] :ip_address
+      # @option params [String] :apikey
+      # @return [Zerobounce::Response]
+      def validate(params)
+        if params.key?(:ipaddress) || params.key?(:ip_address)
+          validate_with_ip(params)
+        else
+          Response.new(get('validate', params), self)
+        end
+      end
+
+      # Validate the email address and get geoip info for the IP.
+      #
+      # @param [Hash] params
+      # @option params [String] :email
+      # @option params [String] :ip_address
+      # @option params [String] :apikey
+      # @return [Zerobounce::Response]
+      def validate_with_ip(params)
+        Response.new(get('validatewithip', params), self)
+      end
+
+      private
+
+      # @param [Hash] params
+      # @return [Hash]
+      def get_params(params)
+        params[:ipaddress] = params.delete(:ip_address) if params.key?(:ip_address) # normalize ipaddress key
+        params[:apikey] = params.delete(:api_key) if params.key?(:api_key) # normalize apikey param
+        { apikey: Zerobounce.config.apikey }.merge(params.select { |k, _| VALID_GET_PARAMS.include?(k) })
+      end
+    end
+  end
+end

data/lib/zerobounce/request/v2_request.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Zerobounce
+  class Request
+    # Request methods specific to V2 of the API.
+    module V2Request
+      # Valid v2 query params
+      VALID_GET_PARAMS = %i[api_key ip_address email].freeze
+
+      # Validate the email address.
+      #
+      # @param [Hash] params
+      # @option params [String] :email
+      # @option params [String] :ip_address
+      # @option params [String] :api_key
+      # @return [Zerobounce::Response]
+      def validate(params)
+        Response.new(get('validate', params), self)
+      end
+
+      private
+
+      # @param [Hash] params
+      # @return [Hash]
+      def get_params(params)
+        params[:ip_address] ||= '' # ip_address must be in query string
+        params[:api_key] = params.delete(:apikey) if params.key?(:apikey) # normalize api_key param
+        { api_key: Zerobounce.config.apikey }.merge(params.select { |k, _| VALID_GET_PARAMS.include?(k) })
+      end
+    end
+  end
+end

data/lib/zerobounce/response.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'time'
+require 'zerobounce/response/v1_response'
+require 'zerobounce/response/v2_response'
 
 module Zerobounce
   # A Zerobounce response
@@ -11,62 +13,24 @@ module Zerobounce
   #   The request instance.
   #
   # @attr_reader [Faraday::Response] response
-  #   The original {https://www.rubydoc.info/gems/faraday/0.15.2/Faraday/Response Faraday::Response}
+  #   The original {https://www.rubydoc.info/gems/faraday/1.4.2/Faraday/Response Faraday::Response}
   class Response
     attr_reader :response
     attr_reader :request
 
     # @param [Faraday::Response] response
-    # @param [Zerobounce::Request] request
+    # @param [Zerobounce::Request::V2Response, Zerobounce::Request::V1Response] request
     def initialize(response, request)
       @response = response
       @request = request
       @body = response.body
-    end
-
-    # Deliverability status
-    #
-    # Possible values:
-    #   :valid
-    #   :invalid
-    #   :catch_all
-    #   :unknown
-    #   :spamtrap
-    #   :abuse
-    #   :do_not_mail
-    #
-    # @return [Symbol] The status as a +Symbol+.
-    def status
-      @status ||= underscore(@body[:status])&.to_sym
-    end
 
-    # A more detailed status
-    #
-    # Possible values:
-    #   :antispam_system
-    #   :greylisted
-    #   :mail_server_temporary_error
-    #   :forcible_disconnect
-    #   :mail_server_did_not_respond
-    #   :timeout_exceeded
-    #   :failed_smtp_connection
-    #   :mailbox_quota_exceeded
-    #   :exception_occurred
-    #   :possible_traps
-    #   :role_based
-    #   :global_suppression
-    #   :mailbox_not_found
-    #   :no_dns_entries
-    #   :failed_syntax_check
-    #   :possible_typo
-    #   :unroutable_ip_address
-    #   :leading_period_removed
-    #   :does_not_accept_mail
-    #   :alias_address
-    #
-    # @return [Symbol] The sub_status as a +Symbol+.
-    def sub_status
-      @sub_status ||= underscore(@body[:sub_status])&.to_sym
+      case request.api_version
+      when 'v2'
+        extend(V2Response)
+      else
+        extend(V1Response)
+      end
     end
 
     # The email address you are validating.
@@ -111,13 +75,6 @@ module Zerobounce
       @gender ||= @body[:gender]
     end
 
-    # The location of the owner of the email when available.
-    #
-    # @return [String, nil]
-    def location
-      @location ||= @body[:location]
-    end
-
     # The country of the IP passed in.
     #
     # @return [String, nil]
@@ -162,48 +119,13 @@ module Zerobounce
       !valid?
     end
 
-    # If the email domain is disposable, which are usually temporary email addresses.
-    #
-    # These are temporary emails created for the sole purpose to sign up to websites without giving their real
-    # email address. These emails are short lived from 15 minutes to around 6 months.
-    #
-    # @note If you have valid emails with this flag set to +true+, you shouldn't email them.
-    #
-    # @return [Boolean]
-    def disposable?
-      @disposable ||= @body[:disposable] || false
-    end
-
-    # These domains are known for abuse, spam, or are bot created.
-    #
-    # @note If you have a valid email with this flag set to +true+, you shouldn't email them.
-    #
-    # @return [Boolean]
-    def toxic?
-      @toxic ||= @body[:toxic] || false
-    end
-
-    # The UTC time the email was validated.
-    #
-    # @return [Time, nil]
-    def process_date
-      @process_date ||= @body[:processedat] && Time.parse(@body[:processedat])
-    end
-
-    # The creation date of the email when available.
-    #
-    # @return [Time, nil]
-    def creation_date
-      @creation_date ||= @body[:creationdate] && Time.parse(@body[:creationdate])
-    end
-
     # Returns a string containing a human-readable representation.
     #
     # @note Overriding inspect to hide the {#request}/{#response} instance variables
     #
     # @return [String]
     def inspect
-      "#<#{self.class.name}:#{object_id}>"
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} @address=#{address}>"
     end
 
     # Convert to a hash.
@@ -212,17 +134,9 @@ module Zerobounce
     def to_h
       public_methods(false).each_with_object({}) do |meth, memo|
         next if %i[request response inspect to_h].include?(meth)
+
         memo[meth] = send(meth)
       end
     end
-
-    private
-
-    # @param [String, nil] word
-    # @return [String, nil]
-    def underscore(word)
-      return if word.nil? || word.empty?
-      word.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.tr('-', '_')
-    end
   end
 end

data/lib/zerobounce/response/v1_response.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Zerobounce
+  class Response
+    # V1 specific methods for the API.
+    module V1Response
+      # Deliverability status
+      #
+      # Possible values:
+      #   :valid
+      #   :invalid
+      #   :catch_all
+      #   :unknown
+      #   :spamtrap
+      #   :abuse
+      #   :do_not_mail
+      #
+      # @return [Symbol] The status as a +Symbol+.
+      def status
+        @status ||= @body[:status].to_s.empty? ? nil : underscore(@body[:status]).to_sym
+      end
+
+      # A more detailed status
+      #
+      # Possible values:
+      #   :antispam_system
+      #   :greylisted
+      #   :mail_server_temporary_error
+      #   :forcible_disconnect
+      #   :mail_server_did_not_respond
+      #   :timeout_exceeded
+      #   :failed_smtp_connection
+      #   :mailbox_quota_exceeded
+      #   :exception_occurred
+      #   :possible_traps
+      #   :role_based
+      #   :global_suppression
+      #   :mailbox_not_found
+      #   :no_dns_entries
+      #   :failed_syntax_check
+      #   :possible_typo
+      #   :unroutable_ip_address
+      #   :leading_period_removed
+      #   :does_not_accept_mail
+      #   :alias_address
+      #   :unknown
+      #
+      # @return [Symbol] The sub_status as a +Symbol+.
+      def sub_status
+        @sub_status ||= @body[:sub_status].to_s.empty? ? nil : underscore(@body[:sub_status]).to_sym
+      end
+
+      # If the email domain is disposable, which are usually temporary email addresses.
+      #
+      # These are temporary emails created for the sole purpose to sign up to websites without giving their real
+      # email address. These emails are short lived from 15 minutes to around 6 months.
+      #
+      # @note If you have valid emails with this flag set to +true+, you shouldn't email them.
+      #
+      # @return [Boolean]
+      def disposable?
+        @disposable ||= @body[:disposable] || false
+      end
+
+      # These domains are known for abuse, spam, or are bot created.
+      #
+      # @note If you have a valid email with this flag set to +true+, you shouldn't email them.
+      #
+      # @return [Boolean]
+      def toxic?
+        @toxic ||= @body[:toxic] || false
+      end
+
+      # The location of the owner of the email when available.
+      #
+      # @return [String, nil]
+      def location
+        @location ||= @body[:location]
+      end
+
+      # The UTC time the email was validated.
+      #
+      # @return [Time, nil]
+      def processed_at
+        @processed_at ||= @body[:processedat] && Time.parse("#{@body[:processedat]} UTC")
+      end
+
+      # The creation date of the email when available.
+      #
+      # @return [Time, nil]
+      def creation_date
+        @creation_date ||= @body[:creationdate] && Time.parse("#{@body[:creationdate]} UTC")
+      end
+
+      private
+
+      # @param [String] word
+      # @return [String]
+      def underscore(word)
+        word.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.tr('-', '_')
+      end
+    end
+  end
+end

data/lib/zerobounce/response/v2_response.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Zerobounce
+  class Response
+    # V2 specific methods for the API.
+    module V2Response
+      # Deliverability status
+      #
+      # @see https://www.zerobounce.net/docs/email-validation-api-quickstart/#status_codes__v2__
+      #
+      # Possible values:
+      #   :valid
+      #   :invalid
+      #   :catch_all
+      #   :unknown
+      #   :spamtrap
+      #   :abuse
+      #   :do_not_mail
+      #
+      # @return [Symbol, nil] The status as a +Symbol+.
+      def status
+        @status ||= @body[:status].to_s.empty? ? nil : @body[:status].tr('-', '_').to_sym
+      end
+
+      # @return [Symbol, nil]
+      def sub_status
+        @sub_status ||= @body[:sub_status].to_s.empty? ? nil : @body[:sub_status].to_sym
+      end
+
+      # @return [Integer]
+      def domain_age_days
+        @domain_age_days ||= @body[:domain_age_days].to_i
+      end
+
+      # The SMTP Provider of the email.
+      #
+      # @return [String, nil]
+      def smtp_provider
+        @smtp_provider ||= @body[:smtp_provider]
+      end
+
+      # @return [String, nil]
+      def did_you_mean
+        @did_you_mean ||= @body[:did_you_mean]
+      end
+
+      # The preferred MX record of the domain.
+      #
+      # @return [String, nil]
+      def mx_record
+        @mx_record ||= @body[:mx_record]
+      end
+
+      # The UTC time the email was validated.
+      #
+      # @return [Time, nil]
+      def processed_at
+        @processed_at ||= @body[:processed_at] && Time.parse("#{@body[:processed_at]} UTC")
+      end
+
+      # If the email comes from a free provider.
+      #
+      # @return [Boolean]
+      def free_email?
+        @free_email ||= @body[:free_email] || false
+      end
+
+      # If the email domain is disposable, which are usually temporary email addresses.
+      #
+      # These are temporary emails created for the sole purpose to sign up to websites without giving their real
+      # email address. These emails are short lived from 15 minutes to around 6 months.
+      #
+      # @note If you have valid emails with this flag set to +true+, you shouldn't email them.
+      #
+      # @return [Boolean]
+      def disposable?
+        @disposable ||= sub_status == :disposable
+      end
+
+      # These domains are known for abuse, spam, or are bot created.
+      #
+      # @note If you have a valid email with this flag set to +true+, you shouldn't email them.
+      #
+      # @return [Boolean]
+      def toxic?
+        @toxic ||= sub_status == :toxic
+      end
+
+      # Does the domain have an MX record.
+      #
+      # @return [Boolean]
+      def mx_found?
+        @mx_found ||= @body[:mx_found] == 'true'
+      end
+    end
+  end
+end

data/lib/zerobounce/version.rb

@@ -2,5 +2,5 @@
 
 module Zerobounce
   # The version of the gem.
-  VERSION = '0.0.5'
+  VERSION = '0.2.0'
 end