Merge pull request #16 from horgh/horgh/response-classes

Add response classes

.travis.yml

@@ -1,5 +1,11 @@
-sudo: false
 language: ruby
 rvm:
-  - 2.3.1
-before_install: gem install bundler -v 1.12.5
+  - 1.9
+  - 2.0
+  - 2.1
+  - 2.2
+  - 2.3
+  - 2.4
+  - 2.5
+  - 2.6
+  - 2.7

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Minfraud Changelog
 
+* Adds classes for the Score, Insights, and Factors responses. This allows
+  us to provide API documentation for the various response attributes.
+* Removes `hashie` as a required dependency.
 * Adds new processor types to `Minfraud::Components::Payment`: `:affirm`,
   `:afterpay`, `:cardpay`, `:ccavenue`, `:cetelem`, `:ct_payments`, `:dalenys`,
   `:datacash`, `:dotpay`, `:ecommpay`, `:epx`, `:g2a_pay`, `:gocardless`,

Gemfile

@@ -1,5 +1,12 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in minfraud.gemspec
-gem 'coveralls', require: false
+# coveralls fails on Ruby 1.9. My understanding is we don't need to run this on
+# more than one version anyway, so restrict to the current latest.
+version_pieces = RUBY_VERSION.split('.')
+major_version = version_pieces[0]
+minor_version = version_pieces[1]
+if major_version == '2' && minor_version == '7'
+  gem 'coveralls', require: false
+end
+
 gemspec

lib/maxmind/geoip2/model/city.rb

@@ -0,0 +1,99 @@
+# Copyright (c) 2020 by 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
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/model/country'
+require 'maxmind/geoip2/record/city'
+require 'maxmind/geoip2/record/location'
+require 'maxmind/geoip2/record/postal'
+require 'maxmind/geoip2/record/subdivision'
+
+module MaxMind
+  module GeoIP2
+    module Model
+      # Model class for the data returned by the GeoIP2 City web service and
+      # database. It is also used for GeoLite2 City lookups.
+      #
+      # The only difference between the City and Insights model classes is which
+      # fields in each record may be populated. See
+      # https://dev.maxmind.com/geoip/geoip2/web-services for more details.
+      #
+      # See {MaxMind::GeoIP2::Model::Country} for inherited methods.
+      class City < Country
+        # City data for the IP address.
+        #
+        # @return [MaxMind::GeoIP2::Record::City]
+        attr_reader :city
+
+        # Location data for the IP address.
+        #
+        # @return [MaxMind::GeoIP2::Record::Location]
+        attr_reader :location
+
+        # Postal data for the IP address.
+        #
+        # @return [MaxMind::GeoIP2::Record::Postal]
+        attr_reader :postal
+
+        # The country subdivisions for the IP address.
+        #
+        # The number and type of subdivisions varies by country, but a subdivision
+        # is typically a state, province, country, etc. Subdivisions are ordered
+        # from most general (largest) to most specific (smallest).
+        #
+        # If the response did not contain any subdivisions, this attribute will be
+        # an empty array.
+        #
+        # @return [Array<MaxMind::GeoIP2::Record::Subdivision>]
+        attr_reader :subdivisions
+
+        # @!visibility private
+        def initialize(record, locales)
+          super(record, locales)
+          @city = MaxMind::GeoIP2::Record::City.new(record['city'], locales)
+          @location = MaxMind::GeoIP2::Record::Location.new(record['location'])
+          @postal = MaxMind::GeoIP2::Record::Postal.new(record['postal'])
+          @subdivisions = create_subdivisions(record['subdivisions'], locales)
+        end
+
+        # The most specific subdivision returned.
+        #
+        # If the response did not contain any subdivisions, this method returns
+        # nil.
+        #
+        # @return [MaxMind::GeoIP2::Record::Subdivision, nil]
+        def most_specific_subdivision
+          @subdivisions.last
+        end
+
+        private
+
+        def create_subdivisions(subdivisions, locales)
+          return [] if subdivisions.nil?
+
+          subdivisions.map do |s|
+            MaxMind::GeoIP2::Record::Subdivision.new(s, locales)
+          end
+        end
+      end
+    end
+  end
+end

lib/maxmind/geoip2/model/country.rb

@@ -0,0 +1,94 @@
+# Copyright (c) 2020 by 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
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/continent'
+require 'maxmind/geoip2/record/country'
+require 'maxmind/geoip2/record/maxmind'
+require 'maxmind/geoip2/record/represented_country'
+require 'maxmind/geoip2/record/traits'
+
+module MaxMind
+  module GeoIP2
+    module Model
+      # Model class for the data returned by the GeoIP2 Country web service and
+      # database. It is also used for GeoLite2 Country lookups.
+      class Country
+        # Continent data for the IP address.
+        #
+        # @return [MaxMind::GeoIP2::Record::Continent]
+        attr_reader :continent
+
+        # Country data for the IP address. This object represents the country where
+        # MaxMind believes the end user is located.
+        #
+        # @return [MaxMind::GeoIP2::Record::Country]
+        attr_reader :country
+
+        # Data related to your MaxMind account.
+        #
+        # @return [MaxMind::GeoIP2::Record::MaxMind]
+        attr_reader :maxmind
+
+        # Registered country data for the IP address. This record represents the
+        # country where the ISP has registered a given IP block and may differ from
+        # the user's country.
+        #
+        # @return [MaxMind::GeoIP2::Record::Country]
+        attr_reader :registered_country
+
+        # Represented country data for the IP address. The represented country is
+        # used for things like military bases. It is only present when the
+        # represented country differs from the country.
+        #
+        # @return [MaxMind::GeoIP2::Record::RepresentedCountry]
+        attr_reader :represented_country
+
+        # Data for the traits of the IP address.
+        #
+        # @return [MaxMind::GeoIP2::Record::Traits]
+        attr_reader :traits
+
+        # @!visibility private
+        def initialize(record, locales)
+          @continent = MaxMind::GeoIP2::Record::Continent.new(
+            record['continent'],
+            locales,
+          )
+          @country = MaxMind::GeoIP2::Record::Country.new(
+            record['country'],
+            locales,
+          )
+          @maxmind = MaxMind::GeoIP2::Record::MaxMind.new(record['maxmind'])
+          @registered_country = MaxMind::GeoIP2::Record::Country.new(
+            record['registered_country'],
+            locales,
+          )
+          @represented_country = MaxMind::GeoIP2::Record::RepresentedCountry.new(
+            record['represented_country'],
+            locales,
+          )
+          @traits = MaxMind::GeoIP2::Record::Traits.new(record['traits'])
+        end
+      end
+    end
+  end
+end

lib/maxmind/geoip2/model/insights.rb

@@ -0,0 +1,38 @@
+# Copyright (c) 2020 by 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
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/model/city'
+
+module MaxMind
+  module GeoIP2
+    module Model
+      # Model class for the data returned by the GeoIP2 Precision Insights web
+      # service.
+      #
+      # The only difference between the City and Insights model classes is which
+      # fields in each record may be populated. See
+      # https://dev.maxmind.com/geoip/geoip2/web-services for more details.
+      class Insights < City
+      end
+    end
+  end
+end

lib/maxmind/geoip2/record/abstract.rb

@@ -0,0 +1,46 @@
+# Copyright (c) 2020 by 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
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# frozen_string_literal: true
+
+module MaxMind
+  module GeoIP2
+    module Record
+      # @!visibility private
+      class Abstract
+        def initialize(record)
+          @record = record
+        end
+
+        protected
+
+        def get(key)
+          if @record.nil? || !@record.key?(key)
+            return false if key.start_with?('is_')
+
+            return nil
+          end
+
+          @record[key]
+        end
+      end
+    end
+  end
+end

lib/maxmind/geoip2/record/city.rb

@@ -0,0 +1,62 @@
+# Copyright (c) 2020 by 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
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/place'
+
+module MaxMind
+  module GeoIP2
+    module Record
+      # City-level data associated with an IP address.
+      #
+      # This record is returned by all location services and databases besides
+      # Country.
+      #
+      # See {MaxMind::GeoIP2::Record::Place} for inherited methods.
+      class City < Place
+        # A value from 0-100 indicating MaxMind's confidence that the city is
+        # correct. This attribute is only available from the Insights service and
+        # the GeoIP2 Enterprise database.
+        #
+        # @return [Integer, nil]
+        def confidence
+          get('confidence')
+        end
+
+        # The GeoName ID for the city. This attribute is returned by all location
+        # services and databases.
+        #
+        # @return [Integer, nil]
+        def geoname_id
+          get('geoname_id')
+        end
+
+        # A Hash where the keys are locale codes and the values are names. This
+        # attribute is returned by all location services and databases.
+        #
+        # @return [Hash<String, String>, nil]
+        def names
+          get('names')
+        end
+      end
+    end
+  end
+end