minfraud 2.8.0 → 2.10.0

data/lib/minfraud/http_service/response.rb

@@ -7,18 +7,20 @@ require 'minfraud/model/insights'
 require 'minfraud/model/score'
 
 module Minfraud
+  # HTTPService contains classes for handling HTTP communication with the
+  # minFraud web services.
   module HTTPService
     # Response class for HTTP requests.
     class Response
       # Response HTTP status code.
       #
-      # @return [Fixnum, nil]
+      # @return [Integer, nil]
       attr_reader :status
 
       # Response model.
       #
       # @return [Minfraud::Model::Score, Minfraud::Model::Insights,
-      #   Minfraud::Model::Factors, nil]
+      #   Minfraud::Model::Factors, Minfraud::Model::Error, nil]
       attr_reader :body
 
       # @param endpoint [Symbol, nil] endpoint name, like :score.

data/lib/minfraud/model/abstract.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Minfraud
+  # Model contains classes for the minFraud response data. These classes
+  # represent the data returned by the Score, Insights, and Factors
+  # endpoints.
   module Model
     # @!visibility private
     class Abstract

data/lib/minfraud/model/device.rb

@@ -8,7 +8,7 @@ module Minfraud
     #
     # In order to receive device output from minFraud Insights or minFraud
     # Factors, you must be using the Device Tracking Add-on
-    # (https://dev.maxmind.com/minfraud/track-devices?lang=en).
+    # (https://dev.maxmind.com/minfraud/track-devices/?lang=en).
     class Device < Abstract
       # This number represents our confidence that the device_id refers to a
       # unique device as opposed to a cluster of similar devices. A confidence

data/lib/minfraud/model/email.rb

@@ -14,7 +14,8 @@ module Minfraud
 
       # 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.
+      # format YYYY-MM-DD. The earliest date that may be returned is January
+      # 1, 2008.
       #
       # @return [String, nil]
       attr_reader :first_seen

data/lib/minfraud/model/email_domain.rb

@@ -1,23 +1,56 @@
 # frozen_string_literal: true
 
 require 'minfraud/model/abstract'
+require 'minfraud/model/email_domain_visit'
 
 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
+      # A classification of the domain. Possible values are:
+      # * business
+      # * education
+      # * government
+      # * isp_email
+      #
+      # @return [String, nil]
+      attr_reader :classification
+
+      # A date string (e.g. 2019-01-01) to identify the date an email domain
       # was first seen by MaxMind. This is expressed using the ISO 8601 date
-      # format.
+      # format YYYY-MM-DD. The earliest date that may be returned is January
+      # 1, 2019.
       #
       # @return [String, nil]
       attr_reader :first_seen
 
+      # A risk score ranging from 0.01 to 99. Higher values indicate greater
+      # risk.
+      #
+      # @return [Float, nil]
+      attr_reader :risk
+
+      # An object containing information about an automated visit to the email
+      # domain.
+      #
+      # @return [Minfraud::Model::EmailDomainVisit, nil]
+      attr_reader :visit
+
+      # Activity across the minFraud network expressed as sightings per
+      # million. The value ranges from 0.001 to 1,000,000.
+      #
+      # @return [Float, nil]
+      attr_reader :volume
+
       # @!visibility private
       def initialize(record)
         super
 
-        @first_seen = get('first_seen')
+        @classification = get('classification')
+        @first_seen     = get('first_seen')
+        @risk           = get('risk')
+        @visit          = EmailDomainVisit.new(get('visit'))
+        @volume         = get('volume')
       end
     end
   end

data/lib/minfraud/model/email_domain_visit.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+
+module Minfraud
+  module Model
+    # Model containing information about an automated visit to the email
+    # domain.
+    class EmailDomainVisit < Abstract
+      # This is true if the domain in the request has redirects (configured
+      # to automatically send visitors to another URL). Otherwise, this will
+      # be nil.
+      #
+      # @return [Boolean, nil]
+      attr_reader :has_redirect
+
+      # A date string (e.g. 2025-11-15) identifying the date the automated
+      # visit was completed. This is expressed using the ISO 8601 date format.
+      #
+      # @return [String, nil]
+      attr_reader :last_visited_on
+
+      # The status of the domain. Possible values are:
+      # * live - The domain is reachable and serving content normally.
+      # * dns_error - The domain is missing, expired, or DNS is misconfigured.
+      # * network_error - The domain is offline, blocked, or unreachable.
+      # * http_error - The domain is reachable but the web application had a
+      #   problem or denied the request.
+      # * parked - The domain is live and is in a parked state.
+      # * pre_development - The domain is live and is in a pre-development
+      #   state.
+      #
+      # @return [String, nil]
+      attr_reader :status
+
+      # @!visibility private
+      def initialize(record)
+        super
+
+        @has_redirect    = get('has_redirect')
+        @last_visited_on = get('last_visited_on')
+        @status          = get('status')
+      end
+    end
+  end
+end

data/lib/minfraud/model/factors.rb

@@ -21,7 +21,7 @@ module Minfraud
       # that are used to calculate the overall risk score.
       #
       # @return [Minfraud::Model::Subscores]
-      # @deprecated Use {::risk_score_reasons} instead.
+      # @deprecated Use {#risk_score_reasons} instead.
       attr_reader :subscores
 
       # @!visibility private

data/lib/minfraud/model/geoip2_location.rb

@@ -4,7 +4,7 @@ require 'maxmind/geoip2/record/location'
 
 module Minfraud
   module Model
-    # Model of the GeoIP2 location information, including the local time.
+    # Model of the GeoIP 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

data/lib/minfraud/model/insights.rb

@@ -43,7 +43,7 @@ module Minfraud
       # @return [Minfraud::Model::Email]
       attr_reader :email
 
-      # An object containing GeoIP2 and minFraud Insights information about the
+      # An object containing GeoIP and minFraud Insights information about the
       # geolocated IP address.
       #
       # @return [Minfraud::Model::IPAddress]

data/lib/minfraud/model/ip_address.rb

@@ -6,7 +6,7 @@ require 'minfraud/model/ip_risk_reason'
 
 module Minfraud
   module Model
-    # Model containing GeoIP2 data and the risk for the IP address.
+    # Model containing GeoIP 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.

data/lib/minfraud/model/reason.rb

@@ -8,7 +8,7 @@ module Minfraud
     #
     # This class provides both a machine-readable code and a human-readable
     # explanation of the reason for the risk score, see
-    # https://dev.maxmind.com/minfraud/api-documentation/responses/schema--response--risk-score-reason--multiplier-reason.
+    # https://dev.maxmind.com/minfraud/api-documentation/responses/#schema--response--risk-score-reason--multiplier-reason.
     # Although more codes may be added in the future, the current codes are:
     #
     # * BROWSER_LANGUAGE - Riskiness of the browser user-agent and

data/lib/minfraud/model/risk_score_reason.rb

@@ -14,9 +14,9 @@ module Minfraud
       # @return [Float]
       attr_reader :multiplier
 
-      # This field contains Risk objects that describe one of the reasons for the multiplier.
+      # Reasons for the multiplier.
       #
-      # @return [Array<Minfraud::Model::Risk>]
+      # @return [Array<Minfraud::Model::Reason>]
       attr_reader :reasons
 
       # @!visibility private

data/lib/minfraud/model/shipping_address.rb

@@ -6,7 +6,7 @@ module Minfraud
   module Model
     # Model containing information about the shipping address.
     class ShippingAddress < Address
-      # The distance in kilometers from the shipping address to billing
+      # The distance in kilometers from the shipping address to the billing
       # address.
       #
       # @return [Integer, nil]
@@ -16,6 +16,8 @@ module Minfraud
       # 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.
+      #
+      # @return [Boolean, nil]
       attr_reader :is_high_risk
 
       # @!visibility private

data/lib/minfraud/model/warning.rb

@@ -17,19 +17,30 @@ module Minfraud
     #   our database.
     # * BILLING_POSTAL_NOT_FOUND - the billing postal could not be found in our
     #   database.
+    # * BILLING_REGION_NOT_FOUND - the billing region could not be found in our
+    #   database.
+    # * EMAIL_ADDRESS_UNUSABLE - the email address entered is likely incorrect
+    #   due to an integration issue. To avoid false positives, it has not been
+    #   used in scoring.
     # * INPUT_INVALID - the value associated with the key does not meet the
     #   required constraints, e.g., "United States" in a field that requires a
     #   two-letter country code.
     # * INPUT_UNKNOWN - an unknown key was encountered in the request body.
+    # * IP_ADDRESS_INVALID - the IP address supplied is not a valid IPv4 or
+    #   IPv6 address.
     # * IP_ADDRESS_NOT_FOUND - the IP address could not be geolocated.
-    # * SHIPPING_COUNTRY_MISSING - shipping address information was provided
-    #   without providing a shipping country.
+    # * IP_ADDRESS_RESERVED - the IP address supplied is in a reserved
+    #   network.
     # * SHIPPING_CITY_NOT_FOUND - the shipping city could not be found in our
     #   database.
+    # * SHIPPING_COUNTRY_MISSING - shipping address information was provided
+    #   without providing a shipping country.
     # * SHIPPING_COUNTRY_NOT_FOUND - the shipping country could not be found in
     #   our database.
     # * SHIPPING_POSTAL_NOT_FOUND - the shipping postal could not be found in
     #   our database.
+    # * SHIPPING_REGION_NOT_FOUND - the shipping region could not be found in
+    #   our database.
     class Warning < Abstract
       # This value is a machine-readable code identifying the warning.
       #

data/lib/minfraud/report.rb

@@ -3,7 +3,7 @@
 module Minfraud
   # Report is used to perform minFraud Report Transaction API requests.
   #
-  # @see https://dev.maxmind.com/minfraud/report-a-transaction?lang=en
+  # @see https://dev.maxmind.com/minfraud/report-a-transaction/?lang=en
   class Report
     # The Report::Transaction component.
     #

data/lib/minfraud/validates.rb

@@ -4,10 +4,23 @@ require 'date'
 require 'ipaddr'
 require 'uri'
 
-# rubocop:disable Metrics/ModuleLength
 module Minfraud
   # @!visibility private
+  # Validates provides validation helper methods for component input values.
+  # These methods are used internally when validation is enabled via
+  # Minfraud.enable_validation.
+  #
+  # rubocop:disable Metrics/ModuleLength
   module Validates
+    # Validates that a string value does not exceed a maximum length.
+    #
+    # @param field [String] The field name for error messages.
+    # @param length [Integer] The maximum allowed length.
+    # @param value [String, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value exceeds the maximum length.
+    #
+    # @return [nil]
     def validate_string(field, length, value)
       return if !value
 
@@ -16,6 +29,14 @@ module Minfraud
       end
     end
 
+    # Validates that a value is a valid MD5 hash string.
+    #
+    # @param field [String] The field name for error messages.
+    # @param value [String, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value is not a valid MD5 hash.
+    #
+    # @return [nil]
     def validate_md5(field, value)
       return if !value
 
@@ -24,10 +45,18 @@ module Minfraud
       end
     end
 
+    # Validates that a value is a valid UUID string.
+    #
+    # @param field [String] The field name for error messages.
+    # @param value [String, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value is not a valid UUID.
+    #
+    # @return [nil]
     def validate_uuid(field, value)
       return if !value
 
-      stripped_value = value.to_s.gsub('-', '')
+      stripped_value = value.to_s.delete('-')
 
       # Define a regex pattern for a valid UUID without dashes
       uuid_regex = /\A[0-9a-f]{32}\z/i
@@ -37,6 +66,14 @@ module Minfraud
       end
     end
 
+    # Validates that a value is a valid ISO 3166-2 subdivision code.
+    #
+    # @param field [String] The field name for error messages.
+    # @param value [String, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value is not a valid subdivision code.
+    #
+    # @return [nil]
     def validate_subdivision_code(field, value)
       return if !value
 
@@ -45,6 +82,14 @@ module Minfraud
       end
     end
 
+    # Validates that a value is a valid ISO 3166-1 alpha-2 country code.
+    #
+    # @param field [String] The field name for error messages.
+    # @param value [String, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value is not a valid country code.
+    #
+    # @return [nil]
     def validate_country_code(field, value)
       return if !value
 
@@ -53,6 +98,15 @@ module Minfraud
       end
     end
 
+    # Validates that a value is a valid telephone country code (1-4 digits).
+    #
+    # @param field [String] The field name for error messages.
+    # @param value [String, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value is not a valid telephone country
+    #   code.
+    #
+    # @return [nil]
     def validate_telephone_country_code(field, value)
       return if !value
 
@@ -61,6 +115,15 @@ module Minfraud
       end
     end
 
+    # Validates that a value matches a regular expression pattern.
+    #
+    # @param field [String] The field name for error messages.
+    # @param regex [Regexp] The regular expression pattern to match.
+    # @param value [String, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value does not match the pattern.
+    #
+    # @return [nil]
     def validate_regex(field, regex, value)
       return if !value
 
@@ -69,6 +132,14 @@ module Minfraud
       end
     end
 
+    # Validates that a value is a valid credit card token.
+    #
+    # @param field [String] The field name for error messages.
+    # @param value [String, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value is not a valid credit card token.
+    #
+    # @return [nil]
     def validate_credit_card_token(field, value)
       return if !value
 
@@ -78,11 +149,19 @@ module Minfraud
         raise InvalidInputError, "The #{field} value is not valid. It must contain only non-space printable ASCII characters."
       end
 
-      if /\A[0-9]{1,19}\z/.match(s)
+      if /\A[0-9]{1,19}\z/.match?(s)
         raise InvalidInputError, "The #{field} value is not valid. If it is all digits, it must be longer than 19 characters."
       end
     end
 
+    # Validates a custom input value (boolean, numeric, or string).
+    #
+    # @param field [String] The field name for error messages.
+    # @param value [Boolean, Numeric, String, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value is not valid.
+    #
+    # @return [nil]
     def validate_custom_input_value(field, value)
       return if !value
 
@@ -101,6 +180,14 @@ module Minfraud
       validate_string(field, 255, value)
     end
 
+    # Validates that a value is a valid IPv4 or IPv6 address.
+    #
+    # @param field [String] The field name for error messages.
+    # @param value [String, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value is not a valid IP address.
+    #
+    # @return [nil]
     def validate_ip(field, value)
       return if !value
 
@@ -120,6 +207,15 @@ module Minfraud
       nil
     end
 
+    # Validates that a value is a non-negative number within range.
+    #
+    # @param field [String] The field name for error messages.
+    # @param value [Numeric, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value is not a valid non-negative
+    #   number.
+    #
+    # @return [nil]
     def validate_nonnegative_number(field, value)
       return if !value
 
@@ -132,6 +228,15 @@ module Minfraud
       end
     end
 
+    # Validates that a value is a non-negative integer within range.
+    #
+    # @param field [String] The field name for error messages.
+    # @param value [Integer, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value is not a valid non-negative
+    #   integer.
+    #
+    # @return [nil]
     def validate_nonnegative_integer(field, value)
       return if !value
 
@@ -144,10 +249,18 @@ module Minfraud
       end
     end
 
+    # Validates that a value is a valid email address or MD5 hash of one.
+    #
+    # @param field [String] The field name for error messages.
+    # @param value [String, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value is not a valid email or MD5 hash.
+    #
+    # @return [nil]
     def validate_email(field, value)
       return if !value
 
-      if /.@./.match(value)
+      if /.@./.match?(value)
         validate_string(field, 255, value)
         return
       end
@@ -155,6 +268,14 @@ module Minfraud
       validate_md5(field, value)
     end
 
+    # Validates that a value is in RFC 3339 date-time format.
+    #
+    # @param field [String] The field name for error messages.
+    # @param value [String, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value is not in RFC 3339 format.
+    #
+    # @return [nil]
     def validate_rfc3339(field, value)
       return if !value
 
@@ -169,6 +290,14 @@ module Minfraud
       nil
     end
 
+    # Validates that a value is a boolean.
+    #
+    # @param field [String] The field name for error messages.
+    # @param value [Boolean, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value is not a boolean.
+    #
+    # @return [nil]
     def validate_boolean(field, value)
       return if !value
 
@@ -177,6 +306,14 @@ module Minfraud
       end
     end
 
+    # Validates that a value is a valid absolute URI.
+    #
+    # @param field [String] The field name for error messages.
+    # @param value [String, nil] The value to validate.
+    #
+    # @raise [InvalidInputError] If the value is not a valid absolute URI.
+    #
+    # @return [nil]
     def validate_uri(field, value)
       return if !value
 
@@ -195,6 +332,6 @@ module Minfraud
       end
       # rubocop:enable Style/RescueStandardError
     end
+    # rubocop:enable Metrics/ModuleLength
   end
 end
-# rubocop:enable Metrics/ModuleLength

data/lib/minfraud/version.rb

@@ -2,5 +2,5 @@
 
 module Minfraud
   # The Gem version.
-  VERSION = '2.8.0'
+  VERSION = '2.10.0'
 end

data/lib/minfraud.rb

@@ -32,6 +32,9 @@ require 'minfraud/report'
 # for the gem's classes.
 module Minfraud
   class << self
+    # rubocop:disable ThreadSafety/ClassAndModuleAttributes
+    # This is a false positive - these configuration attributes are set during initialization
+
     # The MaxMind account ID that is used for authorization.
     #
     # @return [Integer, nil]
@@ -57,6 +60,8 @@ module Minfraud
     # @return [String, nil]
     attr_accessor :license_key
 
+    # rubocop:enable ThreadSafety/ClassAndModuleAttributes
+
     # @!visibility private
     attr_reader :connection_pool
 
@@ -67,8 +72,11 @@ module Minfraud
       yield self
 
       pool_size        = 5
+      # rubocop:disable ThreadSafety/ClassInstanceVariable
+      # This is a false positive - this configuration is set during initialization
       host             = @host.nil? ? 'minfraud.maxmind.com' : @host
       @connection_pool = ConnectionPool.new(size: pool_size) do
+        # rubocop:enable ThreadSafety/ClassInstanceVariable
         make_http_client.persistent("https://#{host}")
       end
     end
@@ -76,10 +84,13 @@ module Minfraud
     private
 
     def make_http_client
+      # rubocop:disable ThreadSafety/ClassInstanceVariable
+      # This is a false positive - this configuration is set during initialization
       HTTP.basic_auth(
         user: @account_id,
         pass: @license_key,
       ).headers(
+        # rubocop:enable ThreadSafety/ClassInstanceVariable
         accept:     'application/json',
         user_agent: "minfraud-api-ruby/#{Minfraud::VERSION} ruby/#{RUBY_VERSION} http/#{HTTP::VERSION}",
       )