minfraud 1.0.4 → 2.4.0

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/api-documentation/requests?lang=en#schema--request--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

data/lib/minfraud/components/event.rb

@@ -1,32 +1,79 @@
+# frozen_string_literal: true
+
 module Minfraud
   module Components
+    # Event corresponds to the event object of a minFraud request.
+    #
+    # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--event
     class Event < Base
       include ::Minfraud::Enum
-      # @attribute transaction_id
-      # @return [String] Internal ID for the transaction. Used to locate a specific transaction in minFraud logs
+      include Minfraud::Validates
+
+      # Your internal ID for the transaction. MaxMind can use this to locate a
+      # specific transaction in logs, and it will also show up in email alerts
+      # and notifications from MaxMind to you. No specific format is required.
+      #
+      # @return [String, nil]
       attr_accessor :transaction_id
 
-      # @attribute shop_id
-      # @return [String] Internal ID for the shop, affiliate, or merchant this order is coming from
+      # Your internal ID for the shop, affiliate, or merchant this order is
+      # coming from. Required for minFraud users who are resellers, payment
+      # providers, gateways and affiliate networks. No specific format is
+      # required.
+      #
+      # @return [String, nil]
       attr_accessor :shop_id
 
-      # @attribute time
-      # @return [String] The date and time the event occurred. The string must be in the RFC 3339 date-time format.
-      # If this field is not in the request, the current time will be used
+      # The date and time the event occurred. The string must be in the RFC
+      # 3339 date-time format, e.g., "2012-04-12T23:20:50.52Z". The time must
+      # be within the past 10 years. If this field is not in the request, the
+      # current time will be used.
+      #
+      # @see https://tools.ietf.org/html/rfc3339
+      #
+      # @return [String, nil]
       attr_accessor :time
 
-      # @attribute type
-      # @return [String] The type of event being scored
-      enum_accessor :type, [:account_creation, :account_login, :purchase, :recurring_purchase, :referral, :survey]
+      # The type of event being scored. This must be one of
+      # +:account_creation+, +:account_login+, +:email_change+,
+      # +:password_reset+, +:payout_change+, +:purchase+,
+      # +:recurring_purchase+, +:referral+, or +:survey+.
+      #
+      # @!attribute type
+      #
+      # @return [Symbol, nil]
+      enum_accessor :type,
+                    %i[
+                      account_creation
+                      account_login
+                      email_change
+                      password_reset
+                      payout_change
+                      purchase
+                      recurring_purchase
+                      referral
+                      survey
+                    ]
 
-      # Creates Minfraud::Components::Event instance
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::Components::Event] an Event instance
+      # @param params [Hash] Hash of parameters. Each key/value should
+      #   correspond to one of the available attributes.
       def initialize(params = {})
         @transaction_id = params[:transaction_id]
         @shop_id        = params[:shop_id]
         @time           = params[:time]
         self.type       = params[:type]
+
+        validate
+      end
+
+      private
+
+      def validate
+        return if !Minfraud.enable_validation
+
+        validate_string('transaction_id', 255, @transaction_id)
+        validate_string('shop_id', 255, @shop_id)
+        validate_rfc3339('time', @time)
       end
     end
   end

data/lib/minfraud/components/order.rb

@@ -1,51 +1,88 @@
+# frozen_string_literal: true
+
 module Minfraud
   module Components
+    # Order corresponds to the order object of a minFraud request.
+    #
+    # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--order
     class Order < Base
-      # @attribute amount
-      # @return [Decimal] The total order amount for the transaction
+      include Minfraud::Validates
+
+      # The total order amount for the transaction before taxes and discounts.
+      # The value must be at least 0 and at most 1e14 - 1.
+      #
+      # @return [Float, nil]
       attr_accessor :amount
 
-      # @attribute currency
-      # @return [String] The ISO 4217 currency code for the currency used in the transaction
+      # The ISO 4217 currency code for the currency used in the transaction.
+      #
+      # @see https://en.wikipedia.org/wiki/ISO_4217
+      #
+      # @return [String, nil]
       attr_accessor :currency
 
-      # @attribute discount_code
-      # @return [String] The discount code applied to the transaction. If multiple discount codes are used,
-      # please separate them with a comma.
+      # The discount code applied to the transaction. If multiple discount
+      # codes are used, please separate them with a comma.
+      #
+      # @return [String, nil]
       attr_accessor :discount_code
 
-      # @attribute affiliate_id
-      # @return [String] The ID of the affiliate where the order is coming from
+      # The ID of the affiliate where the order is coming from. No specific
+      # format is required.
+      #
+      # @return [String, nil]
       attr_accessor :affiliate_id
 
-      # @attribute subaffiliate_id
-      # @return [String] The ID of the sub-affiliate where the order is coming from
+      # The ID of the sub-affiliate where the order is coming from. No specific
+      # format is required.
+      #
+      # @return [String, nil]
       attr_accessor :subaffiliate_id
 
-      # @attribute :referrer_uri
-      # @return [String] The URI of the referring site for this order
+      # The URI of the referring site for this order. Needs to be absolute and
+      # have a URI scheme such as +https://+.
+      #
+      # @return [String, nil]
       attr_accessor :referrer_uri
 
-      # @attribute :is_gift
-      # @return [Boolean] Whether order was marked as a gift by the purchaser
+      # Whether order was marked as a gift by the purchaser.
+      #
+      # @return [Boolean, nil]
       attr_accessor :is_gift
 
-      # @attribute :has_gift_message
-      # @return [Boolean] Whether the purchaser included a gift message
+      # Whether the purchaser included a gift message.
+      #
+      # @return [Boolean, nil]
       attr_accessor :has_gift_message
 
-      # Creates Minfraud::Components::Order instance
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::Components::Order] an Order instance
-      def initialize (params = {})
+      # @param params [Hash] Hash of parameters. Each key/value should
+      #   correspond to one of the available attributes.
+      def initialize(params = {})
         @amount           = params[:amount]
         @has_gift_message = params[:has_gift_message]
         @affiliate_id     = params[:affiliate_id]
         @subaffiliate_id  = params[:subaffiliate_id]
         @currency         = params[:currency]
-        @discount_code    = params[:discount_cide]
+        @discount_code    = params[:discount_code]
         @referrer_uri     = params[:referrer_uri]
         @is_gift          = params[:is_gift]
+
+        validate
+      end
+
+      private
+
+      def validate
+        return if !Minfraud.enable_validation
+
+        validate_nonnegative_number('amount', @amount)
+        validate_boolean('has_gift_message', @has_gift_message)
+        validate_string('affiliate_id', 255, @affiliate_id)
+        validate_string('subaffiliate_id', 255, @subaffiliate_id)
+        validate_regex('currency', /\A[A-Z]{3}\z/, @currency)
+        validate_string('discount_code', 255, @discount_code)
+        validate_uri('referrer_uri', @referrer_uri)
+        validate_boolean('is_gift', @is_gift)
       end
     end
   end

data/lib/minfraud/components/payment.rb

@@ -1,39 +1,209 @@
+# frozen_string_literal: true
+
 module Minfraud
   module Components
+    # Payment corresponds to the payment object of a minFraud request.
+    #
+    # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--payment
     class Payment < Base
       include ::Minfraud::Enum
-      # @attribute processor
-      # @return [String] The payment processor used for the transaction
-      enum_accessor :processor, [
-        :adyen, :altapay, :amazon_payments, :authorizenet, :balanced, :beanstream,
-        :bluepay, :braintree, :ccnow, :chase_paymentech, :cielo, :collector, :compropago,
-        :concept_payments, :conekta, :cuentadigital, :dalpay, :dibs, :digital_river, :ecomm365,
-        :elavon, :epay, :eprocessing_network, :eway, :first_data, :global_payments, :ingenico,
-        :internetsecure, :intuit_quickbooks_payments, :iugu, :mastercard_payment_gateway,
-        :mercadopago, :merchant_esolutions, :mirjeh, :mollie, :moneris_solutions, :nmi,
-        :openpaymx, :optimal_payments, :orangepay, :other, :pacnet_services, :payfast,
-        :paygate, :payone, :paypal, :payplus, :paystation, :paytrace, :paytrail, :payture,
-        :payu, :payulatam, :pinpayments, :princeton_payment_solutions, :psigate, :qiwi,
-        :quickpay, :raberil, :rede, :redpagos, :rewardspay, :sagepay, :simplify_commerce,
-        :skrill, :smartcoin, :sps_decidir, :stripe, :telerecargas, :towah, :usa_epay,
-        :verepay, :vindicia, :virtual_card_services, :vme, :worldpay
+      include Minfraud::Validates
+
+      # The payment processor used for the transaction. The value is one
+      # listed as a valid value, as a symbol.
+      #
+      # @!attribute processor
+      #
+      # @return [Symbol, nil]
+      enum_accessor :processor, %i[
+        adyen
+        affirm
+        afterpay
+        altapay
+        amazon_payments
+        american_express_payment_gateway
+        apple_pay
+        aps_payments
+        authorizenet
+        balanced
+        beanstream
+        bluepay
+        bluesnap
+        boacompra
+        boku
+        bpoint
+        braintree
+        cardknox
+        cardpay
+        cashfree
+        ccavenue
+        ccnow
+        cetelem
+        chase_paymentech
+        checkout_com
+        cielo
+        collector
+        commdoo
+        compropago
+        concept_payments
+        conekta
+        coregateway
+        creditguard
+        credorax
+        ct_payments
+        cuentadigital
+        curopayments
+        cybersource
+        dalenys
+        dalpay
+        datacap
+        datacash
+        dibs
+        digital_river
+        dlocal
+        dotpay
+        ebs
+        ecomm365
+        ecommpay
+        elavon
+        emerchantpay
+        epay
+        eprocessing_network
+        epx
+        eway
+        exact
+        first_atlantic_commerce
+        first_data
+        fiserv
+        g2a_pay
+        global_payments
+        gocardless
+        google_pay
+        heartland
+        hipay
+        ingenico
+        interac
+        internetsecure
+        intuit_quickbooks_payments
+        iugu
+        klarna
+        komoju
+        lemon_way
+        mastercard_payment_gateway
+        mercadopago
+        mercanet
+        merchant_esolutions
+        mirjeh
+        mollie
+        moneris_solutions
+        neopay
+        neosurf
+        nmi
+        oceanpayment
+        oney
+        onpay
+        openbucks
+        openpaymx
+        optimal_payments
+        orangepay
+        other
+        pacnet_services
+        payeezy
+        payfast
+        paygate
+        paylike
+        payment_express
+        paymentwall
+        payone
+        paypal
+        payplus
+        paysafecard
+        paysera
+        paystation
+        paytm
+        paytrace
+        paytrail
+        payture
+        payu
+        payulatam
+        payvision
+        payway
+        payza
+        pinpayments
+        placetopay
+        posconnect
+        princeton_payment_solutions
+        psigate
+        pxp_financial
+        qiwi
+        quickpay
+        raberil
+        razorpay
+        rede
+        redpagos
+        rewardspay
+        safecharge
+        sagepay
+        securetrading
+        shopify_payments
+        simplify_commerce
+        skrill
+        smartcoin
+        smartdebit
+        solidtrust_pay
+        sps_decidir
+        stripe
+        synapsefi
+        systempay
+        telerecargas
+        towah
+        transact_pro
+        trustly
+        trustpay
+        tsys
+        usa_epay
+        vantiv
+        verepay
+        vericheck
+        vindicia
+        virtual_card_services
+        vme
+        vpos
+        windcave
+        wirecard
+        worldpay
       ]
 
-      # @attribute was_authorized
-      # @return [Boolean] The authorization outcome from the payment processor. If the transaction has not yet been approved or denied, do not include this field
+      # The authorization outcome from the payment processor. If the
+      # transaction has not yet been approved or denied, do not include this
+      # field.
+      #
+      # @return [Boolean, nil]
       attr_accessor :was_authorized
 
-      # @attribute decline_code
-      # @return [String] The decline code as provided by your payment processor. If the transaction was not declined, do not include this field
+      # The decline code as provided by your payment processor. If the
+      # transaction was not declined, do not include this field.
+      #
+      # @return [String, nil]
       attr_accessor :decline_code
 
-      # Creates Minfraud::Components::Payment instance
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::Components::Payment] Payment instance
+      # @param params [Hash] Hash of parameters. Each key/value should
+      #   correspond to one of the available attributes.
       def initialize(params = {})
         @was_authorized = params[:was_authorized]
         @decline_code   = params[:decline_code]
         self.processor  = params[:processor]
+
+        validate
+      end
+
+      private
+
+      def validate
+        return if !Minfraud.enable_validation
+
+        validate_boolean('was_authorized', @was_authorized)
+        validate_string('decline_code', 255, @decline_code)
       end
     end
   end

data/lib/minfraud/components/report/transaction.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Minfraud
+  module Components
+    module Report
+      # Contains the fields used in the Report Transaction API.
+      #
+      # @see https://dev.maxmind.com/minfraud/report-a-transaction?lang=en
+      class Transaction < Base
+        include ::Minfraud::Enum
+
+        # The IP address of the customer placing the order. This should be
+        # passed as a string like "152.216.7.110".
+        #
+        # @return [String, nil]
+        attr_accessor :ip_address
+
+        # A symbol indicating the likelihood that a transaction may be
+        # fraudulent.
+        #
+        # This may be one of +:chargeback+, +:not_fraud+, +:spam_or_abuse+, or
+        # +:suspected_fraud+.
+        #
+        # @!attribute tag
+        #
+        # @return [Symbol, nil]
+        enum_accessor :tag, %i[chargeback not_fraud spam_or_abuse suspected_fraud]
+
+        # A string which is provided by your payment processor indicating the
+        # reason for the chargeback.
+        #
+        # @return [String, nil]
+        attr_accessor :chargeback_code
+
+        # A unique eight character string identifying a minFraud Standard or
+        # Premium request. These IDs are returned in the maxmindID field of a
+        # response for a successful minFraud request. This field is not
+        # required, but you are encouraged to provide it, if possible.
+        #
+        # @return [String, nil]
+        attr_accessor :maxmind_id
+
+        # A UUID that identifies a minFraud Score, minFraud Insights, or
+        # minFraud Factors request. This ID is returned at /id in the response.
+        # This field is not required, but you are encouraged to provide it if
+        # the request was made to one of these services.
+        #
+        # @return [String, nil]
+        attr_accessor :minfraud_id
+
+        # Your notes on the fraud tag associated with the transaction. We
+        # manually review many reported transactions to improve our scoring for
+        # you so any additional details to help us understand context are
+        # helpful.
+        #
+        # @return [String, nil]
+        attr_accessor :notes
+
+        # The transaction ID you originally passed to minFraud. This field is
+        # not required, but you are encouraged to provide it or the
+        # transaction's maxmind_id or minfraud_id.
+        #
+        # @return [String, nil]
+        attr_accessor :transaction_id
+
+        # @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]
+          @chargeback_code = params[:chargeback_code]
+          @maxmind_id      = params[:maxmind_id]
+          @minfraud_id     = params[:minfraud_id]
+          @notes           = params[:notes]
+          @transaction_id  = params[:transaction_id]
+          self.tag         = params[:tag]
+        end
+      end
+    end
+  end
+end

data/lib/minfraud/components/shipping.rb

@@ -1,14 +1,23 @@
+# frozen_string_literal: true
+
 module Minfraud
   module Components
+    # Shipping corresponds to the shipping object of a minFraud request.
+    #
+    # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--shipping
     class Shipping < Addressable
       include ::Minfraud::Enum
-      # @attribute delivery_speed
-      # @return [String] The shipping delivery speed for the order. The valid values are:
-      enum_accessor :delivery_speed, [:same_day, :overnight, :expedited, :standard]
 
-      # Creates Minfraud::Components::Shipping instance
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::Components::Shipping] Shipping instance
+      # The shipping delivery speed for the order. Must be one of +:same_day+,
+      # +:overnight+, +:expedited+, or +:standard+.
+      #
+      # @!attribute delivery_speed
+      #
+      # @return [Symbol, nil]
+      enum_accessor :delivery_speed, %i[same_day overnight expedited standard]
+
+      # @param params [Hash] Hash of parameters. Each key/value should
+      #   correspond to one of the available attributes.
       def initialize(params = {})
         self.delivery_speed = params[:delivery_speed]
         super