Merge pull request #187 from maxmind/wstorey/tweaks

oschwald · web-flow · commit 3862c5709563 · 2026-01-15T14:51:34.000-08:00
Fix documentation issues
diff --git a/LICENSE.txt b/LICENSE.txt
@@ -1,7 +1,7 @@
 The MIT License (MIT)
 
 Copyright (c) 2016-2020 kushnir.yb
-Copyright (c) 2020-2025 MaxMind, Inc.
+Copyright (c) 2020-2026 MaxMind, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
diff --git a/README.md b/README.md
@@ -48,7 +48,7 @@ Minfraud.configure do |c|
   c.license_key = 'your_license_key'
   c.enable_validation = true
 end
-````
+```
 
 To use the Sandbox web service instead of the production web service, you can provide the host:
 
@@ -69,8 +69,8 @@ creating the object.
 
 After populating the object, call the method for the minFraud endpoint you
 want to use: `#score`, `#insights`, or `#factors`. The returned value is a
-`MinFraud::Response` object. You can access the response model through its
-`#body` attribute.
+`Minfraud::HTTPService::Response` object. You can access the response model
+through its `#body` attribute.
 
 An exception will be thrown for critical errors. You should check for
 `warnings` related to your inputs after a request.
@@ -245,6 +245,8 @@ this functionality.
 
 The gem supplies several distinct exception-types:
 
+* `InvalidInputError` - Raised if an input value is invalid when client-side
+  validation is enabled
 * `RequestFormatError` - Raised if an unknown key is provided to the
   `Minfraud::Assessments` constructor
 * `ClientError` - Raised if the IP address is absent, reserved, or the JSON
@@ -295,7 +297,7 @@ This API uses [Semantic Versioning](https://semver.org/).
 
 Copyright (c) 2016-2020 kushnir.yb.
 
-Copyright (c) 2020-2025 MaxMind, Inc.
+Copyright (c) 2020-2026 MaxMind, Inc.
 
 The gem is available as open source under the terms of the [MIT
 License](https://opensource.org/licenses/MIT).
diff --git a/lib/minfraud/components/credit_card.rb b/lib/minfraud/components/credit_card.rb
@@ -14,7 +14,8 @@ class CreditCard < Base
       # @return [String, nil]
       attr_accessor :issuer_id_number
 
-      # The last two or four digits of the credit card number.
+      # The last two or four digits of the credit card number. In most cases,
+      # you should send the last four digits for +last_digits+.
       #
       # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--credit-card__last_digits
       #
@@ -42,7 +43,7 @@ class CreditCard < Base
       attr_accessor :bank_phone_number
 
       # The two character ISO 3166-1 alpha-2 country code where the issuer of
-      # the card is located. This may be passed instead of {::issuer_id_number}
+      # the card is located. This may be passed instead of {#issuer_id_number}
       # if you do not wish to pass partial account numbers, or if your payment
       # processor does not provide them.
       #
@@ -74,7 +75,7 @@ class CreditCard < Base
       # @return [String, nil]
       attr_accessor :cvv_result
 
-      # Whether the outcome of 3-D Secure verification (e.g. Safekey,
+      # Whether the outcome of 3-D Secure verification (e.g. SafeKey,
       # SecureCode, Verified by Visa) was successful. +true+ if customer
       # verification was successful, or +false+ if the customer failed
       # verification. If 3-D Secure verification was not used, was unavailable,
@@ -86,7 +87,7 @@ class CreditCard < Base
 
       # Get the last digits of the credit card number.
       #
-      # @deprecated Use {::last_digits} instead.
+      # @deprecated Use {#last_digits} instead.
       #
       # @return [String, nil]
       def last_4_digits
@@ -95,7 +96,7 @@ def last_4_digits
 
       # Set the last digits of the credit card number.
       #
-      # @deprecated Use {::last_digits} instead.
+      # @deprecated Use {#last_digits} instead.
       #
       # @return [String, nil]
       def last_4_digits=(last4)
diff --git a/lib/minfraud/components/email.rb b/lib/minfraud/components/email.rb
@@ -7,7 +7,7 @@ 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
+    # @see https://dev.maxmind.com/minfraud/api-documentation/requests/?lang=en#email
     class Email < Base
       include Minfraud::Validates
 
diff --git a/lib/minfraud/components/event.rb b/lib/minfraud/components/event.rb
@@ -38,7 +38,7 @@ class Event < Base
 
       # 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
+      # be within the past year. If this field is not in the request, the
       # current time will be used.
       #
       # @see https://tools.ietf.org/html/rfc3339
diff --git a/lib/minfraud/components/order.rb b/lib/minfraud/components/order.rb
@@ -9,7 +9,7 @@ class Order < Base
       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.
+      # The value must be at least 0 and at most 1e13 - 1.
       #
       # @return [Float, nil]
       attr_accessor :amount
diff --git a/lib/minfraud/components/shopping_cart_item.rb b/lib/minfraud/components/shopping_cart_item.rb
@@ -5,20 +5,20 @@ module Components
     # ShoppingCartItem corresponds to objects in the shopping_cart object
     # of a minFraud request.
     #
-    # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--shopping-cart--item
+    # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--shopping-cart
     class ShoppingCartItem < Base
       include Minfraud::Validates
 
       # The category of the item. This can also be a hashed value; see link.
       #
-      # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--shopping-cart--item__category
+      # @see https://dev.maxmind.com/minfraud/api-documentation/requests/?lang=en#schema--request--shopping-cart__category
       #
       # @return [String, nil]
       attr_accessor :category
 
       # The internal ID of the item. This can also be a hashed value; see link.
       #
-      # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--shopping-cart--item__item_id
+      # @see https://dev.maxmind.com/minfraud/api-documentation/requests/?lang=en#schema--request--shopping-cart__item_id
       #
       # @return [String, nil]
       attr_accessor :item_id
@@ -31,7 +31,7 @@ class ShoppingCartItem < Base
 
       # The per-unit price of this item in the shopping cart. This should use
       # the same currency as the order currency. The value must be at least 0
-      # and at most 1e14 - 1.
+      # and at most 1e13 - 1.
       #
       # @return [Float, nil]
       attr_accessor :price
diff --git a/lib/minfraud/http_service/response.rb b/lib/minfraud/http_service/response.rb
@@ -12,13 +12,13 @@ module HTTPService
     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.
diff --git a/lib/minfraud/model/email.rb b/lib/minfraud/model/email.rb
@@ -14,7 +14,8 @@ class Email < Abstract
 
       # 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
diff --git a/lib/minfraud/model/email_domain.rb b/lib/minfraud/model/email_domain.rb
@@ -16,9 +16,10 @@ class EmailDomain < Abstract
       # @return [String, nil]
       attr_reader :classification
 
-      # A date string (e.g. 2017-04-24) to identify the date an email domain
+      # 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
diff --git a/lib/minfraud/model/email_domain_visit.rb b/lib/minfraud/model/email_domain_visit.rb
@@ -7,7 +7,9 @@ module Model
     # Model containing information about an automated visit to the email
     # domain.
     class EmailDomainVisit < Abstract
-      # Whether the domain redirects to another URL.
+      # 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
@@ -19,12 +21,13 @@ class EmailDomainVisit < Abstract
       attr_reader :last_visited_on
 
       # The status of the domain. Possible values are:
-      # * live - The domain is operational and serving content.
-      # * dns_error - The domain has missing, expired, or misconfigured DNS.
-      # * network_error - The domain is offline or unreachable.
-      # * http_error - The domain is reachable, but has an application error.
-      # * parked - The domain is reachable and in a parked state.
-      # * pre_development - The domain is reachable and in a pre-development
+      # * 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]
diff --git a/lib/minfraud/model/factors.rb b/lib/minfraud/model/factors.rb
@@ -21,7 +21,7 @@ class Factors < Insights
       # 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
diff --git a/lib/minfraud/model/shipping_address.rb b/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 @@ class ShippingAddress < Address
       # 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
diff --git a/lib/minfraud/model/warning.rb b/lib/minfraud/model/warning.rb
@@ -17,19 +17,30 @@ module Model
     #   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.
       #

Original file line number	Diff line number	Diff line change
`@@ -14,7 +14,8 @@ class CreditCard < Base`
`14`	`14`	`# @return [String, nil]`
`15`	`15`	`attr_accessor :issuer_id_number`
`16`	`16`
`17`		`- # The last two or four digits of the credit card number.`
	`17`	`+ # The last two or four digits of the credit card number. In most cases,`
	`18`	`+ # you should send the last four digits for +last_digits+.`
`18`	`19`	`#`
`19`	`20`	`# @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--credit-card__last_digits`
`20`	`21`	`#`
`@@ -42,7 +43,7 @@ class CreditCard < Base`
`42`	`43`	`attr_accessor :bank_phone_number`
`43`	`44`
`44`	`45`	`# The two character ISO 3166-1 alpha-2 country code where the issuer of`
`45`		`- # the card is located. This may be passed instead of {::issuer_id_number}`
	`46`	`+ # the card is located. This may be passed instead of {#issuer_id_number}`
`46`	`47`	`# if you do not wish to pass partial account numbers, or if your payment`
`47`	`48`	`# processor does not provide them.`
`48`	`49`	`#`
`@@ -74,7 +75,7 @@ class CreditCard < Base`
`74`	`75`	`# @return [String, nil]`
`75`	`76`	`attr_accessor :cvv_result`
`76`	`77`
`77`		`- # Whether the outcome of 3-D Secure verification (e.g. Safekey,`
	`78`	`+ # Whether the outcome of 3-D Secure verification (e.g. SafeKey,`
`78`	`79`	`# SecureCode, Verified by Visa) was successful. +true+ if customer`
`79`	`80`	`# verification was successful, or +false+ if the customer failed`
`80`	`81`	`# verification. If 3-D Secure verification was not used, was unavailable,`
`@@ -86,7 +87,7 @@ class CreditCard < Base`
`86`	`87`
`87`	`88`	`# Get the last digits of the credit card number.`
`88`	`89`	`#`
`89`		`- # @deprecated Use {::last_digits} instead.`
	`90`	`+ # @deprecated Use {#last_digits} instead.`
`90`	`91`	`#`
`91`	`92`	`# @return [String, nil]`
`92`	`93`	`def last_4_digits`
`@@ -95,7 +96,7 @@ def last_4_digits`
`95`	`96`
`96`	`97`	`# Set the last digits of the credit card number.`
`97`	`98`	`#`
`98`		`- # @deprecated Use {::last_digits} instead.`
	`99`	`+ # @deprecated Use {#last_digits} instead.`
`99`	`100`	`#`
`100`	`101`	`# @return [String, nil]`
`101`	`102`	`def last_4_digits=(last4)`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@ module Minfraud`
`7`	`7`	`module Components`
`8`	`8`	`# Email corresponds to the email object of a minFraud request.`
`9`	`9`	`#`
`10`		`- # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--email`
	`10`	`+ # @see https://dev.maxmind.com/minfraud/api-documentation/requests/?lang=en#email`
`11`	`11`	`class Email < Base`
`12`	`12`	`include Minfraud::Validates`
`13`	`13`
Original file line number	Diff line number	Diff line change
`@@ -38,7 +38,7 @@ class Event < Base`
`38`	`38`
`39`	`39`	`# The date and time the event occurred. The string must be in the RFC`
`40`	`40`	`# 3339 date-time format, e.g., "2012-04-12T23:20:50.52Z". The time must`
`41`		`- # be within the past 10 years. If this field is not in the request, the`
	`41`	`+ # be within the past year. If this field is not in the request, the`
`42`	`42`	`# current time will be used.`
`43`	`43`	`#`
`44`	`44`	`# @see https://tools.ietf.org/html/rfc3339`
Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ class Order < Base`
`9`	`9`	`include Minfraud::Validates`
`10`	`10`
`11`	`11`	`# The total order amount for the transaction before taxes and discounts.`
`12`		`- # The value must be at least 0 and at most 1e14 - 1.`
	`12`	`+ # The value must be at least 0 and at most 1e13 - 1.`
`13`	`13`	`#`
`14`	`14`	`# @return [Float, nil]`
`15`	`15`	`attr_accessor :amount`
Original file line number	Diff line number	Diff line change
`@@ -5,20 +5,20 @@ module Components`
`5`	`5`	`# ShoppingCartItem corresponds to objects in the shopping_cart object`
`6`	`6`	`# of a minFraud request.`
`7`	`7`	`#`
`8`		`- # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--shopping-cart--item`
	`8`	`+ # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--shopping-cart`
`9`	`9`	`class ShoppingCartItem < Base`
`10`	`10`	`include Minfraud::Validates`
`11`	`11`
`12`	`12`	`# The category of the item. This can also be a hashed value; see link.`
`13`	`13`	`#`
`14`		`- # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--shopping-cart--item__category`
	`14`	`+ # @see https://dev.maxmind.com/minfraud/api-documentation/requests/?lang=en#schema--request--shopping-cart__category`
`15`	`15`	`#`
`16`	`16`	`# @return [String, nil]`
`17`	`17`	`attr_accessor :category`
`18`	`18`
`19`	`19`	`# The internal ID of the item. This can also be a hashed value; see link.`
`20`	`20`	`#`
`21`		`- # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--shopping-cart--item__item_id`
	`21`	`+ # @see https://dev.maxmind.com/minfraud/api-documentation/requests/?lang=en#schema--request--shopping-cart__item_id`
`22`	`22`	`#`
`23`	`23`	`# @return [String, nil]`
`24`	`24`	`attr_accessor :item_id`
`@@ -31,7 +31,7 @@ class ShoppingCartItem < Base`
`31`	`31`
`32`	`32`	`# The per-unit price of this item in the shopping cart. This should use`
`33`	`33`	`# the same currency as the order currency. The value must be at least 0`
`34`		`- # and at most 1e14 - 1.`
	`34`	`+ # and at most 1e13 - 1.`
`35`	`35`	`#`
`36`	`36`	`# @return [Float, nil]`
`37`	`37`	`attr_accessor :price`
Original file line number	Diff line number	Diff line change
`@@ -12,13 +12,13 @@ module HTTPService`
`12`	`12`	`class Response`
`13`	`13`	`# Response HTTP status code.`
`14`	`14`	`#`
`15`		`- # @return [Fixnum, nil]`
	`15`	`+ # @return [Integer, nil]`
`16`	`16`	`attr_reader :status`
`17`	`17`
`18`	`18`	`# Response model.`
`19`	`19`	`#`
`20`	`20`	`# @return [Minfraud::Model::Score, Minfraud::Model::Insights,`
`21`		`- # Minfraud::Model::Factors, nil]`
	`21`	`+ # Minfraud::Model::Factors, Minfraud::Model::Error, nil]`
`22`	`22`	`attr_reader :body`
`23`	`23`
`24`	`24`	`# @param endpoint [Symbol, nil] endpoint name, like :score.`
Original file line number	Diff line number	Diff line change
`@@ -14,7 +14,8 @@ class Email < Abstract`
`14`	`14`
`15`	`15`	`# A date string (e.g. 2017-04-24) to identify the date an email address`
`16`	`16`	`# was first seen by MaxMind. This is expressed using the ISO 8601 date`
`17`		`- # format.`
	`17`	`+ # format YYYY-MM-DD. The earliest date that may be returned is January`
	`18`	`+ # 1, 2008.`
`18`	`19`	`#`
`19`	`20`	`# @return [String, nil]`
`20`	`21`	`attr_reader :first_seen`