minfraud 1.0.4 → 2.4.0

data/lib/minfraud/model/email.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+require 'minfraud/model/email_domain'
+
+module Minfraud
+  module Model
+    # Model containing information about the email address.
+    class Email < Abstract
+      # An object containing information about the email domain.
+      #
+      # @return [Minfraud::Model::EmailDomain]
+      attr_reader :domain
+
+      # A date string (e.g. 2017-04-24) to identify the date an email address
+      # was first seen by MaxMind. This is expressed using the ISO 8601 date
+      # format.
+      #
+      # @return [String, nil]
+      attr_reader :first_seen
+
+      # Whether this email address is from a disposable email provider. The
+      # value will be nil when no email address or email domain has been passed
+      # as an input.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_disposable
+
+      # This property is true if MaxMind believes that this email is hosted by
+      # a free email provider such as Gmail or Yahoo! Mail.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_free
+
+      # This field is true if MaxMind believes that this email is likely to be
+      # used for fraud. Note that this is also factored into the overall
+      # risk_score in the response as well.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_high_risk
+
+      # @!visibility private
+      def initialize(record)
+        super(record)
+
+        @domain        = Minfraud::Model::EmailDomain.new(get('domain'))
+        @first_seen    = get('first_seen')
+        @is_disposable = get('is_disposable')
+        @is_free       = get('is_free')
+        @is_high_risk  = get('is_high_risk')
+      end
+    end
+  end
+end

data/lib/minfraud/model/email_domain.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+
+module Minfraud
+  module Model
+    # Model containing information about the email domain.
+    class EmailDomain < Abstract
+      # A date string (e.g. 2017-04-24) to identify the date an email domain
+      # was first seen by MaxMind. This is expressed using the ISO 8601 date
+      # format.
+      #
+      # @return [String, nil]
+      attr_reader :first_seen
+
+      # @!visibility private
+      def initialize(record)
+        super(record)
+
+        @first_seen = get('first_seen')
+      end
+    end
+  end
+end

data/lib/minfraud/model/error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+
+module Minfraud
+  module Model
+    # Model with information about an error.
+    class Error < Abstract
+      # An error code for machine use.
+      #
+      # @return [String]
+      attr_reader :code
+
+      # A human readable error message.
+      #
+      # @return [String]
+      attr_reader :error
+
+      # @!visibility private
+      def initialize(record)
+        super(record)
+
+        @code  = get('code')
+        @error = get('error')
+      end
+    end
+  end
+end

data/lib/minfraud/model/factors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/insights'
+require 'minfraud/model/subscores'
+
+module Minfraud
+  module Model
+    # Model representing the Factors response.
+    class Factors < Insights
+      # An object containing scores for many of the individual risk factors
+      # that are used to calculate the overall risk score.
+      #
+      # @return [Minfraud::Model::Subscores]
+      attr_reader :subscores
+
+      # @!visibility private
+      def initialize(record, locales)
+        super(record, locales)
+
+        @subscores = Minfraud::Model::Subscores.new(get('subscores'))
+      end
+    end
+  end
+end

data/lib/minfraud/model/geoip2_location.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/location'
+
+module Minfraud
+  module Model
+    # Model of the GeoIP2 location information, including the local time.
+    class GeoIP2Location < MaxMind::GeoIP2::Record::Location
+      # The date and time of the transaction in the time zone associated with
+      # the IP address. The value is formatted according to RFC 3339. For
+      # instance, the local time in Boston might be returned as
+      # 2015-04-27T19:17:24-04:00.
+      #
+      # @return [String]
+      attr_reader :local_time
+
+      # @!visibility private
+      def initialize(record)
+        super(record)
+
+        @local_time = get('local_time')
+      end
+    end
+  end
+end

data/lib/minfraud/model/insights.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/billing_address'
+require 'minfraud/model/credit_card'
+require 'minfraud/model/device'
+require 'minfraud/model/email'
+require 'minfraud/model/ip_address'
+require 'minfraud/model/score'
+require 'minfraud/model/shipping_address'
+
+module Minfraud
+  module Model
+    # Model of the Insights response.
+    class Insights < Score
+      # An object containing minFraud data related to the billing address used
+      # in the transaction.
+      #
+      # @return [Minfraud::Model::BillingAddress]
+      attr_reader :billing_address
+
+      # An object containing minFraud data about the credit card used in the
+      # transaction.
+      #
+      # @return [Minfraud::Model::CreditCard]
+      attr_reader :credit_card
+
+      # This object contains information about the device that MaxMind believes
+      # is associated with the IP address passed in the request.
+      #
+      # @return [Minfraud::Model::Device]
+      attr_reader :device
+
+      # This object contains information about the email address passed in the
+      # request.
+      #
+      # @return [Minfraud::Model::Email]
+      attr_reader :email
+
+      # An object containing GeoIP2 and minFraud Insights information about the
+      # geolocated IP address.
+      #
+      # @return [Minfraud::Model::IPAddress]
+      attr_reader :ip_address
+
+      # An object containing minFraud data related to the shipping address used
+      # in the transaction.
+      #
+      # @return [Minfraud::Model::ShippingAddress]
+      attr_reader :shipping_address
+
+      # @!visibility private
+      def initialize(record, locales)
+        super(record, locales)
+
+        @billing_address  = Minfraud::Model::BillingAddress.new(
+          get('billing_address')
+        )
+        @credit_card      = Minfraud::Model::CreditCard.new(get('credit_card'))
+        @device           = Minfraud::Model::Device.new(get('device'))
+        @email            = Minfraud::Model::Email.new(get('email'))
+        @ip_address       = Minfraud::Model::IPAddress.new(get('ip_address'), locales)
+        @shipping_address = Minfraud::Model::ShippingAddress.new(
+          get('shipping_address')
+        )
+      end
+    end
+  end
+end

data/lib/minfraud/model/ip_address.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/model/insights'
+require 'minfraud/model/geoip2_location'
+require 'minfraud/model/ip_risk_reason'
+
+module Minfraud
+  module Model
+    # Model containing GeoIP2 data and the risk for the IP address.
+    class IPAddress < MaxMind::GeoIP2::Model::Insights
+      # This field contains the risk associated with the IP address. The value
+      # ranges from 0.01 to 99. A higher score indicates a higher risk.
+      #
+      # @return [Float]
+      attr_reader :risk
+
+      # This field contains IPRiskReason objects identifying the reasons why
+      # the IP address received the associated risk. This will be an empty
+      # array if there are no reasons.
+      #
+      # @return [Array<Minfraud::Model::IPRiskReason>]
+      attr_reader :risk_reasons
+
+      # @!visibility private
+      def initialize(record, locales)
+        if record
+          super(record, locales)
+        else
+          super({}, locales)
+        end
+
+        if record
+          @location = Minfraud::Model::GeoIP2Location.new(record.fetch('location', nil))
+        else
+          @location = Minfraud::Model::GeoIP2Location.new(nil)
+        end
+        if record
+          @risk = record.fetch('risk', nil)
+        else
+          @risk = nil
+        end
+
+        @risk_reasons = []
+        if record&.key?('risk_reasons')
+          record['risk_reasons'].each do |r|
+            @risk_reasons << Minfraud::Model::IPRiskReason.new(r)
+          end
+        end
+
+        # These attributes are deprecated and aren't in maxmind-geoip2. The
+        # webservice still sends them as of writing, so we'd like to keep them
+        # for now as they could still be providing value.
+        @traits.define_singleton_method(:is_anonymous_proxy) { get('is_anonymous_proxy') }
+        @traits.define_singleton_method(:is_satellite_provider) { get('is_satellite_provider') }
+      end
+    end
+  end
+end

data/lib/minfraud/model/ip_risk_reason.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+
+module Minfraud
+  module Model
+    # Reason for the IP risk.
+    #
+    # This class provides both a machine-readable code and a human-readable
+    # explanation of the reason for the IP risk score.
+    #
+    # Although more codes may be added in the future, the current codes are:
+    #
+    # * ANONYMOUS_IP - The IP address belongs to an anonymous network. See the
+    #   object at ip_address.traits for more details.
+    # * BILLING_POSTAL_VELOCITY - Many different billing postal codes have been
+    #   seen on this IP address.
+    # * EMAIL_VELOCITY - Many different email addresses have been seen on this
+    #   IP address.
+    # * HIGH_RISK_DEVICE - A high risk device was seen on this IP address.
+    # * HIGH_RISK_EMAIL - A high risk email address was seen on this IP address
+    #   in your past transactions.
+    # * ISSUER_ID_NUMBER_VELOCITY - Many different issuer ID numbers have been
+    #   seen on this IP address.
+    # * MINFRAUD_NETWORK_ACTIVITY - Suspicious activity has been seen on this
+    #   IP address across minFraud customers.
+    class IPRiskReason < Abstract
+      # This value is a machine-readable code identifying the reason.
+      #
+      # @return [String, nil]
+      attr_reader :code
+
+      # This field provides a human-readable explanation of the reason. The
+      # text may change at any time and should not be matched against.
+      #
+      # @return [String, nil]
+      attr_reader :reason
+
+      # @!visibility private
+      def initialize(record)
+        super(record)
+
+        @code   = get('code')
+        @reason = get('reason')
+      end
+    end
+  end
+end

data/lib/minfraud/model/issuer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+
+module Minfraud
+  module Model
+    # Model containing information about the card issuer.
+    class Issuer < Abstract
+      # The name of the bank which issued the credit card.
+      #
+      # @return [String, nil]
+      attr_reader :name
+
+      # This property is true if the name matches the name provided in the
+      # request for the card issuer. It is false if the name does not match.
+      # The property is nil if either no name or issuer ID number (IIN) was
+      # provided in the request or if MaxMind does not have a name associated
+      # with the IIN.
+      #
+      # @return [Boolean, nil]
+      attr_reader :matches_provided_name
+
+      # This property is true if the phone number matches the number provided
+      # in the request for the card issuer. It is false if the number does not
+      # match. It is nil if either no phone number was provided or issuer ID
+      # number (IIN) was provided in the request or if MaxMind does not have a
+      # phone number associated with the IIN.
+      #
+      # @return [Boolean, nil]
+      attr_reader :matches_provided_phone_number
+
+      # The phone number of the bank which issued the credit card. In some
+      # cases the phone number we return may be out of date.
+      #
+      # @return [String, nil]
+      attr_reader :phone_number
+
+      # @!visibility private
+      def initialize(record)
+        super(record)
+
+        @name                          = get('name')
+        @phone_number                  = get('phone_number')
+        @matches_provided_name         = get('matches_provided_name')
+        @matches_provided_phone_number = get('matches_provided_phone_number')
+      end
+    end
+  end
+end

data/lib/minfraud/model/score.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+require 'minfraud/model/disposition'
+require 'minfraud/model/score_ip_address'
+require 'minfraud/model/warning'
+
+module Minfraud
+  module Model
+    # Model of the Score response.
+    class Score < Abstract
+      # An object containing the disposition set by custom rules.
+      #
+      # @return [Minfraud::Model::Disposition]
+      attr_reader :disposition
+
+      # The approximate US dollar value of the funds remaining on your MaxMind
+      # account.
+      #
+      # @return [Float]
+      attr_reader :funds_remaining
+
+      # This is a UUID that identifies the minFraud request. Please use this ID
+      # in bug reports or support requests to MaxMind so that we can easily
+      # identify a particular request.
+      #
+      # @return [String]
+      attr_reader :id
+
+      # An object containing the IP risk for the transaction.
+      #
+      # @return [Minfraud::Model::ScoreIPAddress]
+      attr_reader :ip_address
+
+      # The approximate number of queries remaining for this service before
+      # your account runs out of funds.
+      #
+      # @return [Integer]
+      attr_reader :queries_remaining
+
+      # This property contains the risk score, from 0.01 to 99. A higher score
+      # indicates a higher risk of fraud. For example, a score of 20 indicates
+      # a 20% chance that a transaction is fraudulent. We never return a risk
+      # score of 0, since all transactions have the possibility of being
+      # fraudulent. Likewise we never return a risk score of 100.
+      #
+      # @return [Float]
+      attr_reader :risk_score
+
+      # This array contains objects detailing issues with the request that was
+      # sent, such as invalid or unknown inputs. It is highly recommended that
+      # you check this array for issues when integrating the web service.
+      #
+      # @return [Array<Minfraud::Model::Warning>]
+      attr_reader :warnings
+
+      # @!visibility private
+      def initialize(record, _locales)
+        super(record)
+
+        @disposition       = Minfraud::Model::Disposition.new(get('disposition'))
+        @funds_remaining   = get('funds_remaining')
+        @id                = get('id')
+        @ip_address        = Minfraud::Model::ScoreIPAddress.new(get('ip_address'))
+        @queries_remaining = get('queries_remaining')
+        @risk_score        = get('risk_score')
+        @warnings          = []
+        if record&.key?('warnings')
+          record['warnings'].each do |w|
+            @warnings << Minfraud::Model::Warning.new(w)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/minfraud/model/score_ip_address.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+
+module Minfraud
+  module Model
+    # Model containing the IP address's risk for the Score response.
+    class ScoreIPAddress < Abstract
+      # This field contains the risk associated with the IP address. The value
+      # ranges from 0.01 to 99. A higher score indicates a higher risk.
+      #
+      # @return [Float]
+      attr_reader :risk
+
+      # @!visibility private
+      def initialize(record)
+        super(record)
+
+        @risk = get('risk')
+      end
+    end
+  end
+end

data/lib/minfraud/model/shipping_address.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/address'
+
+module Minfraud
+  module Model
+    # Model containing information about the shipping address.
+    class ShippingAddress < Address
+      # The distance in kilometers from the shipping address to billing
+      # address.
+      #
+      # @return [Integer, nil]
+      attr_reader :distance_to_billing_address
+
+      # This field is true if the shipping address is an address associated
+      # with fraudulent transactions. The field is false when the address is
+      # not associated with increased risk. The key will only be present when a
+      # shipping address is provided.
+      attr_reader :is_high_risk
+
+      # @!visibility private
+      def initialize(record)
+        super(record)
+
+        @distance_to_billing_address = get('distance_to_billing_address')
+        @is_high_risk                = get('is_high_risk')
+      end
+    end
+  end
+end

data/lib/minfraud/model/subscores.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+
+module Minfraud
+  module Model
+    # Score for risk factors that are used in calculating the riskScore.
+    class Subscores < Abstract
+      # The risk associated with the AVS result. If present, this is a value in
+      # the range 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :avs_result
+
+      # The risk associated with the billing address. If present, this is a
+      # value in the range 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :billing_address
+
+      # The risk associated with the distance between the billing address and
+      # the location for the given IP address. If present, this is a value in
+      # the range 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :billing_address_distance_to_ip_location
+
+      # The risk associated with the browser attributes such as the User-Agent
+      # and Accept-Language. If present, this is a value in the range 0.01 to
+      # 99.
+      #
+      # @return [Float, nil]
+      attr_reader :browser
+
+      # Individualized risk of chargeback for the given IP address given for
+      # your account and any shop ID passed. This is only available to users
+      # sending chargeback data to MaxMind. If present, this is a value in the
+      # range 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :chargeback
+
+      # The risk associated with the country the transaction originated from.
+      # If present, this is a value in the range 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :country
+
+      # The risk associated with the combination of IP country, card issuer
+      # country, billing country, and shipping country. If present, this is a
+      # value in the range 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :country_mismatch
+
+      # The risk associated with the CVV result. If present, this is a value in
+      # the range 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :cvv_result
+
+      # The risk associated with the device. If present, this is a value in the
+      # range of 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :device
+
+      # The risk associated with the particular email address. If present, this
+      # is a value in the range 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :email_address
+
+      # The general risk associated with the email domain. If present, this is
+      # a value in the range 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :email_domain
+
+      # The risk associated with the email address local part (the part of
+      # the email address before the @ symbol). If present, this is a value
+      # in the range 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :email_local_part
+
+      # The risk associated with the particular issuer ID number (IIN) given
+      # the billing location and the history of usage of the IIN on your
+      # account and shop ID. If present, this is a value in the range 0.01 to
+      # 99.
+      #
+      # @return [Float, nil]
+      attr_reader :issuer_id_number
+
+      # The risk associated with the particular order amount for your account
+      # and shop ID. If present, this is a value in the range 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :order_amount
+
+      # The risk associated with the particular phone number. If present, this
+      # is a value in the range 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :phone_number
+
+      # The risk associated with the shipping address. If present, this is a
+      # value in the range 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :shipping_address
+
+      # The risk associated with the distance between the shipping address and
+      # the IP location for the given IP address. If present, this is a value
+      # in the range 0.01 to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :shipping_address_distance_to_ip_location
+
+      # The risk associated with the local time of day of the transaction in
+      # the IP address location. If present, this is a value in the range 0.01
+      # to 99.
+      #
+      # @return [Float, nil]
+      attr_reader :time_of_day
+
+      # @!visibility private
+      def initialize(record)
+        super(record)
+
+        @avs_result                               = get('avs_result')
+        @billing_address                          = get('billing_address')
+        @billing_address_distance_to_ip_location  = get(
+          'billing_address_distance_to_ip_location'
+        )
+        @browser                                  = get('browser')
+        @chargeback                               = get('chargeback')
+        @country                                  = get('country')
+        @country_mismatch                         = get('country_mismatch')
+        @cvv_result                               = get('cvv_result')
+        @device                                   = get('device')
+        @email_address                            = get('email_address')
+        @email_domain                             = get('email_domain')
+        @email_local_part                         = get('email_local_part')
+        @issuer_id_number                         = get('issuer_id_number')
+        @order_amount                             = get('order_amount')
+        @phone_number                             = get('phone_number')
+        @shipping_address                         = get('shipping_address')
+        @shipping_address_distance_to_ip_location = get(
+          'shipping_address_distance_to_ip_location'
+        )
+        @time_of_day                              = get('time_of_day')
+      end
+    end
+  end
+end