minfraud 1.1.0 → 1.5.0

data/lib/minfraud/components/addressable.rb

@@ -1,54 +1,81 @@
+# frozen_string_literal: true
+
 module Minfraud
   module Components
+    # This is a parent class for the Billing and Shipping components.
     class Addressable < Base
-      # @attribute first_name
-      # @return [String] The first name of the end user as provided in their billing / shipping information
+      include Minfraud::Validates
+
+      # The first name of the end user as provided in their billing / shipping
+      # information.
+      #
+      # @return [String, nil]
       attr_accessor :first_name
 
-      # @attribute last_name
-      # @return [String] The last name of the end user as provided in their billing / shipping information
+      # The last name of the end user as provided in their billing / shipping
+      # information.
+      #
+      # @return [String, nil]
       attr_accessor :last_name
 
-      # @attribute company
-      # @return [String] The company of the end user as provided in their billing / shipping information
+      # The company of the end user as provided in their billing / shipping
+      # information.
+      #
+      # @return [String, nil]
       attr_accessor :company
 
-      # @attribute address
-      # @return [String] The first line of the user’s billing / shipping address
+      # The first line of the user's billing / shipping address.
+      #
+      # @return [String, nil]
       attr_accessor :address
 
-      # @attribute address_2
-      # @return [String] The second line of the user’s billing / shipping address
+      # The second line of the user's billing / shipping address.
+      #
+      # @return [String, nil]
       attr_accessor :address_2
 
-      # @attribute city
-      # @return [String] The city of the user's billing / shipping address
+      # The city of the user's billing / shipping address.
+      #
+      # @return [String, nil]
       attr_accessor :city
 
-      # @attribute region
-      # @return [String] The ISO 3166-2 subdivision code for the user’s billing / shipping address
+      # The ISO 3166-2 subdivision code for the user's billing / shipping
+      # address.
+      #
+      # @see https://en.wikipedia.org/wiki/ISO_3166-2
+      #
+      # @return [String, nil]
       attr_accessor :region
 
-      # @attribute country
-      # @return [String] The two character ISO 3166-1 alpha-2 country code of the user’s billing / shipping address
+      # The two character ISO 3166-1 alpha-2 country code of the user's billing
+      # / shipping address.
+      #
+      # @see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+      #
+      # @return [String, nil]
       attr_accessor :country
 
-      # @attribute postal
-      # @return [String] The postal code of the user’s billing / shipping address
+      # The postal code of the user's billing / shipping address.
+      #
+      # @return [String, nil]
       attr_accessor :postal
 
-      # @attribute phone_number
-      # @return [String] The phone number without the country code for the user’s billing / shipping address
+      # The phone number without the country code for the user's billing /
+      # shipping address. Punctuation characters will be stripped. After
+      # stripping punctuation characters, the number must contain only digits.
+      #
+      # @return [String, nil]
       attr_accessor :phone_number
 
-      # @attribute phone_country_code
-      # @return [String] The country code for phone number associated with the user’s billing / shipping address
+      # The country code for the phone number associated with the user's
+      # billing / shipping address. If you provide this information then you
+      # must provide at least one digit.
+      #
+      # @return [String, nil]
       attr_accessor :phone_country_code
 
-      # Creates Minfraud::Components::Addressable instance
-      # @note This class is used as a parent class for Billing and Shipping components
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::Components::Addressable] an Addressable instance
+      # @param params [Hash] Hash of parameters. Each key/value should
+      #   correspond to one of the available attributes.
       def initialize(params = {})
         @first_name         = params[:first_name]
         @last_name          = params[:last_name]
@@ -61,6 +88,26 @@ module Minfraud
         @postal             = params[:postal]
         @phone_number       = params[:phone_number]
         @phone_country_code = params[:phone_country_code]
+
+        validate
+      end
+
+      private
+
+      def validate
+        return if !Minfraud.enable_validation
+
+        validate_string('first_name', 255, @first_name)
+        validate_string('last_name', 255, @last_name)
+        validate_string('company', 255, @company)
+        validate_string('address', 255, @address)
+        validate_string('address_2', 255, @address_2)
+        validate_string('city', 255, @city)
+        validate_subdivision_code('region', @region)
+        validate_country_code('country', @country)
+        validate_string('postal', 255, @postal)
+        validate_string('phone_number', 255, @phone_number)
+        validate_telephone_country_code('phone_country_code', @phone_country_code)
       end
     end
   end

data/lib/minfraud/components/base.rb

@@ -1,35 +1,47 @@
+# frozen_string_literal: true
+
 module Minfraud
   module Components
-    # @note This class is used as a parent class for all other components
-    # @note It defines a method which is used for basic JSON representation of PORO objects
+    # This is a parent class for all components. It defines a method which is
+    # used for basic JSON representation of the component objects.
     class Base
-      # @return [Hash] a JSON representation of component attributes
-      def to_json
-        instance_variables.inject({}) { |mem, e| populate!(mem, e) }
+      # A JSON representation of component attributes.
+      #
+      # @return [Hash]
+      def to_json(*_args)
+        instance_variables.reduce({}) { |mem, e| populate!(mem, e) }
       end
 
       private
 
-      # @note   This method may modify passed hash. Non-existing instance variables are ignored
-      # @param  [Hash] hash an accumulator
-      # @param  [Symbol] v_sym an instance variable symbol
-      # @return [Hash] a hash containing a JSON representation of instance variable name and it's value
+      # Create a hash containing a JSON representation of instance variable
+      # name and its value.
+      #
+      # @param hash [Hash] An accumulator.
+      #
+      # @param v_sym [Symbol] An instance variable symbol.
+      #
+      # @return [Hash]
       def populate!(hash, v_sym)
-        return hash unless value = instance_variable_get(v_sym)
+        return hash unless (value = instance_variable_get(v_sym))
 
         key = v_sym.to_s.gsub(/@/, '')
         hash.merge!(key => represent(key, value))
       end
 
-      # param [Symbol] key instance variable symbol
-      # param [Object] value instance variable value
-      # @return [Object] value representation according to the request format
+      # Return the value according to the request format.
+      #
+      # @param key [Symbol] An instance variable symbol.
+      #
+      # @param value [Object] An instance variable value.
+      #
+      # @return [Object]
       def represent(key, value)
         BOOLS.include?(key) ? value : value.to_s
       end
 
       # Keys that have to remain boolean
-      BOOLS = %w(was_authorized is_gift has_gift_message)
+      BOOLS = %w[was_authorized is_gift has_gift_message].freeze
     end
   end
 end

data/lib/minfraud/components/billing.rb

@@ -1,5 +1,10 @@
+# frozen_string_literal: true
+
 module Minfraud
   module Components
+    # Billing corresponds to the billing object of a minFraud request.
+    #
+    # @see https://dev.maxmind.com/minfraud/#Billing_(/billing)
     class Billing < Addressable; end
   end
 end

data/lib/minfraud/components/credit_card.rb

@@ -1,42 +1,69 @@
+# frozen_string_literal: true
+
 module Minfraud
   module Components
+    # CreditCard corresponds to the credit_card object of a minFraud request.
+    #
+    # @see https://dev.maxmind.com/minfraud/#Credit_Card_(/creditcard)
     class CreditCard < Base
-      # @attribute issuer_id_number
-      # # @return [String] The issuer ID number for the credit card. This is the first 6 digits of the credit card number.
-      # It identifies the issuing bank
+      include Minfraud::Validates
+
+      # The issuer ID number for the credit card. This is the first 6 digits of
+      # the credit card number. It identifies the issuing bank.
+      #
+      # @return [String, nil]
       attr_accessor :issuer_id_number
 
-      # @attribute last_4_digits
-      # @return [String] The last four digits of the credit card number
+      # The last four digits of the credit card number.
+      #
+      # @return [String, nil]
       attr_accessor :last_4_digits
 
-      # @attribute bank_name
-      # @return [String] The name of the issuing bank as provided by the end user
+      # The name of the issuing bank as provided by the end user.
+      #
+      # @return [String, nil]
       attr_accessor :bank_name
 
-      # @attribute bank_phone_country_code
-      # @return [String] The phone country code for the issuing bank as provided by the end user
+      # The phone country code for the issuing bank as provided by the end
+      # user. If you provide this information then you must provide at least
+      # one digit.
+      #
+      # @return [String, nil]
       attr_accessor :bank_phone_country_code
 
-      # @attribute bank_phone_number
-      # @return [String] The phone number, without the country code, for the issuing bank as provided by the end user
+      # The phone number, without the country code, for the issuing bank as
+      # provided by the end user. Punctuation characters will be stripped.
+      # After stripping punctuation characters, the number must contain only
+      # digits.
+      #
+      # @return [String, nil]
       attr_accessor :bank_phone_number
 
-      #@attribute token
-      #@return [String] A token uniquely identifying the card. The token should consist of non-space printable ASCII characters.
+      # A token uniquely identifying the card. The token should consist of
+      # non-space printable ASCII characters. If the token is all digits, it
+      # must be more than 19 characters long. The token must not be a primary
+      # account number (PAN) or a simple transformation of it. If you have a
+      # valid token that looks like a PAN but is not one, you may prefix that
+      # token with a fixed string, e.g., +token-+.
+      #
+      # @return [String, nil]
       attr_accessor :token
 
-      # @attribute avs_result
-      # @return [String] The address verification system (AVS) check result, as returned to you by the credit card processor
+      # The address verification system (AVS) check result, as returned to you
+      # by the credit card processor. The minFraud service supports the
+      # standard AVS codes.
+      #
+      # @return [String, nil]
       attr_accessor :avs_result
 
-      # @attribute cvv_result
-      # @return [String] The card verification value (CVV) code as provided by the payment processor
+      # The card verification value (CVV) code as provided by the payment
+      # processor.
+      #
+      # @return [String, nil]
       attr_accessor :cvv_result
 
-      # Creates Minfraud::Components::CreditCard instance
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::Components::CreditCard] a CreditCard instance
+      # @param params [Hash] Hash of parameters. Each key/value should
+      #   correspond to one of the available attributes.
       def initialize(params = {})
         @bank_phone_country_code = params[:bank_phone_country_code]
         @issuer_id_number        = params[:issuer_id_number]
@@ -46,6 +73,23 @@ module Minfraud
         @avs_result              = params[:avs_result]
         @cvv_result              = params[:cvv_result]
         @token                   = params[:token]
+
+        validate
+      end
+
+      private
+
+      def validate
+        return if !Minfraud.enable_validation
+
+        validate_telephone_country_code('bank_phone_country_code', @bank_phone_country_code)
+        validate_regex('issuer_id_number', /\A[0-9]{6}\z/, @issuer_id_number)
+        validate_regex('last_4_digits', /\A[0-9]{4}\z/, @last_4_digits)
+        validate_string('bank_name', 255, @bank_name)
+        validate_string('bank_phone_number', 255, @bank_phone_number)
+        validate_string('avs_result', 1, @avs_result)
+        validate_string('cvv_result', 1, @cvv_result)
+        validate_credit_card_token('token', @token)
       end
     end
   end

data/lib/minfraud/components/custom_inputs.rb

@@ -1,12 +1,23 @@
+# frozen_string_literal: true
+
 module Minfraud
   module Components
+    # CustomInputs corresponds to the custom_inputs object of a minFraud
+    # request.
+    #
+    # @see https://dev.maxmind.com/minfraud/#Custom_Inputs_(/custominputs)
     class CustomInputs < Base
-      # Creates Minfraud::Components::CustomInputs instance
-      # @param  [Hash] params hash with keys that match your created custom input keys
-      # @return [Minfraud::Components::CustomInputs] a CustomInputs instance
+      include Minfraud::Validates
+
+      # @param params [Hash] Each key/value should correspond to your defined
+      #   custom inputs.
       def initialize(params = {})
         params.each do |name, value|
           instance_variable_set("@#{name}", value)
+
+          if Minfraud.enable_validation
+            validate_custom_input_value(name, value)
+          end
         end
       end
     end

data/lib/minfraud/components/device.rb

@@ -1,37 +1,67 @@
+# frozen_string_literal: true
+
 module Minfraud
   module Components
+    # Device corresponds to the device object of a minFraud request.
+    #
+    # @see https://dev.maxmind.com/minfraud/#Device_(/device)
     class Device < Base
-      # @!attribute ip_address
-      # @return [String] The IP address associated with the device used by the customer in the transaction.
-      # The IP address must be in IPv4 or IPv6 presentation format
+      include Minfraud::Validates
+
+      # The IP address associated with the device used by the customer in the
+      # transaction. The IP address must be in IPv4 or IPv6 presentation
+      # format, i.e., dotted-quad notation or the IPv6 hexadecimal-colon
+      # notation.
+      #
+      # @return [String, nil]
       attr_accessor :ip_address
 
-      # @attribute user_agent
-      # @return [String] The HTTP "User-Agent" header of the browser used in the transaction
+      # The HTTP "User-Agent" header of the browser used in the transaction.
+      #
+      # @return [String, nil]
       attr_accessor :user_agent
 
-      # @attribute :accept_language
-      # @return [String] The HTTP "Accept-Language" header of the browser used in the transaction
+      # The HTTP "Accept-Language" header of the browser used in the
+      # transaction.
+      #
+      # @return [String, nil]
       attr_accessor :accept_language
 
-      # @attribute :session_age
-      # @return [Decimal] The number of seconds between the creation of the user’s session and the time of the transaction.
-      # Note that session_age is not the duration of the current visit, but the time since the start of the first visit.
+      # The number of seconds between the creation of the user's session and
+      # the time of the transaction. Note that session_age is not the duration
+      # of the current visit, but the time since the start of the first visit.
+      # The value must be at least 0 and at most 10^13-1.
+      #
+      # @return [Float, nil]
       attr_accessor :session_age
 
-      # @attribute :session_id
-      # @return [String] An ID that uniquely identifies a visitor’s session on the site.
+      # An ID that uniquely identifies a visitor's session on the site.
+      #
+      # @return [String, nil]
       attr_accessor :session_id
 
-      # Creates Minfraud::Components::Device instance
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::Components::Device] a Device instance
+      # @param params [Hash] Hash of parameters. Each key/value should
+      #   correspond to one of the available attributes.
       def initialize(params = {})
         @ip_address      = params[:ip_address]
         @user_agent      = params[:user_agent]
         @accept_language = params[:accept_language]
         @session_age     = params[:session_age]
         @session_id      = params[:session_id]
+
+        validate
+      end
+
+      private
+
+      def validate
+        return if !Minfraud.enable_validation
+
+        validate_ip('ip_address', @ip_address)
+        validate_string('user_agent', 512, @user_agent)
+        validate_string('accept_language', 255, @accept_language)
+        validate_nonnegative_number('session_age', @session_age)
+        validate_string('session_id', 255, @session_id)
       end
     end
   end

data/lib/minfraud/components/email.rb

@@ -1,20 +1,131 @@
+# frozen_string_literal: true
+
+require 'digest/md5'
+require 'simpleidn'
+
 module Minfraud
   module Components
+    # Email corresponds to the email object of a minFraud request.
+    #
+    # @see https://dev.maxmind.com/minfraud/#Email_(/email)
     class Email < Base
-      # @attribute address
-      # @return [String] This field must be either a valid email address or an MD5 of the email used in the transaction
+      include Minfraud::Validates
+
+      # This field must be either be a valid email address or an MD5 of the
+      # lowercased email used in the transaction. Important: if using the MD5
+      # hash, please be sure to convert the email address to lowercase before
+      # calculating its MD5 hash. Instead of converting an address to an MD5
+      # hash yourself, please use the hash_address attribute in this class.
+      #
+      # @return [String, nil]
       attr_accessor :address
 
-      # @attribute domain
-      # @return [String] The domain of the email address used in the transaction
+      # The domain of the email address used in the transaction.
+      #
+      # @return [String, nil]
       attr_accessor :domain
 
-      # Creates Minfraud::Components::Email instance
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::Components::Email] an Email instance
+      # By default, the address will be sent in plain text. If this is set
+      # true, the address will instead be sent as an MD5 hash.
+      #
+      # @return [Boolean, nil]
+      attr_accessor :hash_address
+
+      # @param params [Hash] Hash of parameters. Each key/value should
+      #   correspond to one of the available attributes.
       def initialize(params = {})
-        @address = params[:address]
-        @domain  = params[:domain]
+        @address      = params[:address]
+        @domain       = params[:domain]
+        @hash_address = params[:hash_address]
+
+        validate
+      end
+
+      # A JSON representation of Minfraud::Components::Email.
+      #
+      # @return [Hash]
+      def to_json(*_args)
+        json = super
+
+        if json['address'] && !json['domain']
+          _, domain = address.split('@', 2)
+          if domain
+            domain         = clean_domain(domain)
+            json['domain'] = domain if domain
+          end
+        end
+
+        if json.delete('hash_address') && json['address']
+          hash = hash_email_address(json['address'])
+
+          # We could consider clearing the key if !hash.
+          json['address'] = hash if hash
+        end
+
+        json
+      end
+
+      private
+
+      def validate
+        return if !Minfraud.enable_validation
+
+        validate_email('email', @address)
+        validate_string('domain', 255, @domain)
+      end
+
+      def hash_email_address(address)
+        address = clean_email_address(address)
+        return nil if !address
+
+        Digest::MD5.hexdigest(address)
+      end
+
+      def clean_email_address(address)
+        address = address.strip
+        address.downcase!
+
+        local_part, domain = address.split('@', 2)
+        return nil if !local_part || !domain
+
+        domain = clean_domain(domain)
+
+        if domain == 'yahoo.com'
+          local_part.sub!(/\A([^-]+)-.*\z/, '\1')
+        else
+          local_part.sub!(/\A([^+]+)\+.*\z/, '\1')
+        end
+
+        "#{local_part}@#{domain}"
+      end
+
+      TYPO_DOMAINS = {
+        # gmail.com
+        '35gmai.com'     => 'gmail.com',
+        '636gmail.com'   => 'gmail.com',
+        'gamil.com'      => 'gmail.com',
+        'gmail.comu'     => 'gmail.com',
+        'gmial.com'      => 'gmail.com',
+        'gmil.com'       => 'gmail.com',
+        'yahoogmail.com' => 'gmail.com',
+        # outlook.com
+        'putlook.com'    => 'outlook.com',
+      }.freeze
+      private_constant :TYPO_DOMAINS
+
+      def clean_domain(domain)
+        domain = domain.strip
+
+        # We could use delete_suffix!, but that is in Ruby 2.5+ only.
+        domain.sub!(/\.\z/, '')
+
+        domain = SimpleIDN.to_ascii(domain)
+
+        if TYPO_DOMAINS.key?(domain)
+          domain = TYPO_DOMAINS[domain]
+        end
+
+        domain
       end
     end
   end