minfraud 1.1.0 → 1.5.0

data/lib/minfraud/http_service/response.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'minfraud/model/error'
 require 'minfraud/model/factors'
 require 'minfraud/model/insights'
@@ -5,24 +7,26 @@ require 'minfraud/model/score'
 
 module Minfraud
   module HTTPService
-    # Response class for HTTP requests
+    # Response class for HTTP requests.
     class Response
-      # @attribute status
-      # @return [Integer] HTTP response status
+      # HTTP response status.
+      #
+      # @return [Integer, nil]
       attr_reader :status
 
-      # @attribute body
+      # HTTP response model.
+      #
       # @return [Minfraud::Model::Score, Minfraud::Model::Insights,
-      #   Minfraud::Model::Factors] HTTP response body
+      #   Minfraud::Model::Factors, nil]
       attr_reader :body
 
-      # @attribute headers
-      # @return [Hash] HTTP response headers
+      # HTTP response headers.
+      #
+      # @return [Hash, nil]
       attr_reader :headers
 
-      # Creates Minfraud::HTTPService::Response instance
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::HTTPService::Response] Response instance
+      # @param params [Hash] Hash of parameters. +:status+, +:endpoint+,
+      #   +:body+, +:locales+, and +:headers+ are used.
       def initialize(params = {})
         @status  = params[:status]
         @body    = make_body(
@@ -33,8 +37,9 @@ module Minfraud
         @headers = params[:headers]
       end
 
-      # Returns minFraud-specific response code
-      # @return [Symbol, nil] minFraud specific request code
+      # Return the minFraud-specific response code.
+      #
+      # @return [Symbol, nil]
       def code
         return nil if body.nil?
 
@@ -55,9 +60,9 @@ module Minfraud
       end
 
       ENDPOINT_TO_CLASS = {
-        factors: Minfraud::Model::Factors,
+        factors:  Minfraud::Model::Factors,
         insights: Minfraud::Model::Insights,
-        score: Minfraud::Model::Score
+        score:    Minfraud::Model::Score
       }.freeze
     end
   end

data/lib/minfraud/model/address.rb

@@ -42,10 +42,10 @@ module Minfraud
         super(record)
 
         @distance_to_ip_location = get('distance_to_ip_location')
-        @is_in_ip_country = get('is_in_ip_country')
-        @is_postal_in_city = get('is_postal_in_city')
-        @latitude = get('latitude')
-        @longitude = get('longitude')
+        @is_in_ip_country        = get('is_in_ip_country')
+        @is_postal_in_city       = get('is_postal_in_city')
+        @latitude                = get('latitude')
+        @longitude               = get('longitude')
       end
     end
   end

data/lib/minfraud/model/credit_card.rb

@@ -59,16 +59,16 @@ module Minfraud
       def initialize(record)
         super(record)
 
-        @brand = get('brand')
-        @country = get('country')
-        @is_business = get('is_business')
+        @brand                                = get('brand')
+        @country                              = get('country')
+        @is_business                          = get('is_business')
         @is_issued_in_billing_address_country = get(
           'is_issued_in_billing_address_country'
         )
-        @is_prepaid = get('is_prepaid')
-        @is_virtual = get('is_virtual')
-        @issuer = Minfraud::Model::Issuer.new(get('issuer'))
-        @type = get('type')
+        @is_prepaid                           = get('is_prepaid')
+        @is_virtual                           = get('is_virtual')
+        @issuer                               = Minfraud::Model::Issuer.new(get('issuer'))
+        @type                                 = get('type')
       end
     end
   end

data/lib/minfraud/model/device.rb

@@ -45,8 +45,8 @@ module Minfraud
         super(record)
 
         @confidence = get('confidence')
-        @id = get('id')
-        @last_seen = get('last_seen')
+        @id         = get('id')
+        @last_seen  = get('last_seen')
         @local_time = get('local_time')
       end
     end

data/lib/minfraud/model/email.rb

@@ -43,11 +43,11 @@ module Minfraud
       def initialize(record)
         super(record)
 
-        @domain = Minfraud::Model::EmailDomain.new(get('domain'))
-        @first_seen = get('first_seen')
+        @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')
+        @is_free       = get('is_free')
+        @is_high_risk  = get('is_high_risk')
       end
     end
   end

data/lib/minfraud/model/error.rb

@@ -20,7 +20,7 @@ module Minfraud
       def initialize(record)
         super(record)
 
-        @code = get('code')
+        @code  = get('code')
         @error = get('error')
       end
     end

data/lib/minfraud/model/insights.rb

@@ -52,13 +52,13 @@ module Minfraud
       def initialize(record, locales)
         super(record, locales)
 
-        @billing_address = Minfraud::Model::BillingAddress.new(
+        @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)
+        @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')
         )

data/lib/minfraud/model/ip_address.rb

@@ -2,6 +2,7 @@
 
 require 'maxmind/geoip2/model/insights'
 require 'minfraud/model/geoip2_location'
+require 'minfraud/model/ip_risk_reason'
 
 module Minfraud
   module Model
@@ -13,9 +14,20 @@ module Minfraud
       # @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)
-        super(record, locales)
+        if record
+          super(record, locales)
+        else
+          super({}, locales)
+        end
 
         if record
           @location = Minfraud::Model::GeoIP2Location.new(record.fetch('location', nil))
@@ -28,6 +40,13 @@ module Minfraud
           @risk = nil
         end
 
+        @risk_reasons = []
+        if record && record.key?('risk_reasons')
+          record['risk_reasons'].each do |r|
+            @risk_reasons << Minfraud::Model::IPRiskReason.new(r)
+          end
+        end
+
         # Decorate objects with deprecated attributes and names for backwards
         # compatibility. Do this here rather than with the overhead of
         # subclasses/modules for them in the hope that one day we can delete

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

@@ -39,9 +39,9 @@ module Minfraud
       def initialize(record)
         super(record)
 
-        @name = get('name')
-        @phone_number = get('phone_number')
-        @matches_provided_name = get('matches_provided_name')
+        @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

data/lib/minfraud/model/score.rb

@@ -58,13 +58,13 @@ module Minfraud
       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'))
+        @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 = []
+        @risk_score        = get('risk_score')
+        @warnings          = []
         if record && record.key?('warnings')
           record['warnings'].each do |w|
             @warnings << Minfraud::Model::Warning.new(w)

data/lib/minfraud/model/shipping_address.rb

@@ -23,7 +23,7 @@ module Minfraud
         super(record)
 
         @distance_to_billing_address = get('distance_to_billing_address')
-        @is_high_risk = get('is_high_risk')
+        @is_high_risk                = get('is_high_risk')
       end
     end
   end

data/lib/minfraud/model/subscores.rb

@@ -59,6 +59,12 @@ module Minfraud
       # @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.
       #
@@ -71,6 +77,13 @@ module Minfraud
       # @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 issuer ID number on the email domain. If
       # present, this is a value in the range 0.01 to 99.
       #
@@ -111,6 +124,12 @@ module Minfraud
       # @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.
@@ -129,27 +148,30 @@ module Minfraud
       def initialize(record)
         super(record)
 
-        @avs_result = get('avs_result')
-        @billing_address = get('billing_address')
-        @billing_address_distance_to_ip_location = get(
+        @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')
-        @email_address = get('email_address')
-        @email_domain = get('email_domain')
-        @email_tenure = get('email_tenure')
-        @ip_tenure = get('ip_tenure')
-        @issuer_id_number = get('issuer_id_number')
-        @order_amount = get('order_amount')
-        @phone_number = get('phone_number')
+        @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')
+        @email_tenure                             = get('email_tenure')
+        @ip_tenure                                = get('ip_tenure')
+        @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')
+        @time_of_day                              = get('time_of_day')
       end
     end
   end

data/lib/minfraud/model/warning.rb

@@ -54,8 +54,8 @@ module Minfraud
       def initialize(record)
         super(record)
 
-        @code = get('code')
-        @warning = get('warning')
+        @code          = get('code')
+        @warning       = get('warning')
         @input_pointer = get('input_pointer')
       end
     end

data/lib/minfraud/report.rb

@@ -1,36 +1,56 @@
+# frozen_string_literal: true
+
 module Minfraud
+  # Report is used to perform minFraud Report Transaction API requests.
+  #
+  # @see https://dev.maxmind.com/minfraud/report-transaction/
   class Report
     include ::Minfraud::HTTPService
 
-    # @!attribute transaction
-    # @return [Minfraud::Components::Report::Transaction] Report::Transaction component
+    # The Report::Transaction component.
+    #
+    # @return [Minfraud::Components::Report::Transaction, nil]
     attr_accessor :transaction
 
-    # @param  [Hash] params hash of parameters
-    # @return [Minfraud::ReportTransaction] ReportTransaction instance
+    # @param params [Hash] Hash of parameters. The only supported key is
+    #   +:transaction+, which should have a
+    #   +Minfraud::Components::Report::Transaction+ as its value.
     def initialize(params = {})
       @transaction = params[:transaction]
     end
 
-    # @method report_transaction
-    # Makes a request to the minFraud report transactions API.
-    # Raises an error in case of invalid response.
+    # Perform a request to the minFraud Report Transaction API.
+    #
     # @return [nil]
+    #
+    # @raise [Minfraud::AuthorizationError] If there was an authentication
+    #   problem.
+    #
+    # @raise [Minfraud::ClientError] If there was a critical problem with one
+    #   of your inputs.
+    #
+    # @raise [Minfraud::ServerError] If the server reported an error of some
+    #   kind.
     def report_transaction
-      raw = request.perform(verb: :post, endpoint: 'transactions/report', body: @transaction.to_json)
+      raw = request.perform(
+        verb:     :post,
+        endpoint: 'transactions/report',
+        body:     @transaction.to_json,
+      )
 
       response = ::Minfraud::HTTPService::Response.new(
-        status: raw.status.to_i,
-        body: raw.body,
+        status:  raw.status.to_i,
+        body:    raw.body,
         headers: raw.headers
       )
+
       ::Minfraud::ErrorHandler.examine(response)
 
-      return nil
+      nil
     end
 
-    # Creates memoized Minfraud::HTTPService::Request instance
-    # @return [Minfraud::HTTPService::Request] Request instance based on configuration params
+    private
+
     def request
       @request ||= Request.new(::Minfraud::HTTPService.configuration)
     end