minfraud 1.0.0 → 1.1.0

data/lib/minfraud/components/report/transaction.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Minfraud
+  module Components
+    module Report
+      # Contains all of the fields which are used in the report transaction API
+      class Transaction < Base
+        include ::Minfraud::Enum
+
+        # @!attribute ip_address
+        # @return [String, nil] The IP address of the customer placing the order. This
+        #   should be passed as a string like "44.55.66.77" or "2001:db8::2:1".
+        attr_accessor :ip_address
+
+        # @!attribute tag
+        # This may be one of +:chargeback+, +:not_fraud+, +:spam_or_abuse+ or +:suspected_fraud+
+        # @return [Symbol, nil] A symbol indicating the likelihood that a transaction
+        #   may be fraudulent.
+        enum_accessor :tag, [:chargeback, :not_fraud, :spam_or_abuse, :suspected_fraud]
+
+        # @attribute chargeback_code
+        # @return [String, nil] A string which is provided by your payment processor
+        #   indicating the reason for the chargeback.
+        attr_accessor :chargeback_code
+
+        # @attribute maxmind_id
+        # @return [String, nil] A unique eight character string identifying a minFraud
+        #   Standard or Premium request. These IDs are returned in the maxmindID
+        #   field of a response for a successful minFraud request. This field is
+        #   not required, but you are encouraged to provide it, if possible.
+        attr_accessor :maxmind_id
+
+        # @attribute minfraud_id
+        # @return [String, nil] A UUID that identifies a minFraud Score, minFraud
+        #   Insights, or minFraud Factors request. This ID is returned at /id in
+        #   the response. This field is not required, but you are encouraged to
+        #   provide it if the request was made to one of these services.
+        attr_accessor :minfraud_id
+
+        # @attribute notes
+        # @return [String, nil] Your notes on the fraud tag associated with the
+        #   transaction. We manually review many reported transactions to improve
+        #   our scoring for you so any additional details to help us understand
+        #   context are helpful.
+        attr_accessor :notes
+
+        # @attribute transaction_id
+        # @return [String, nil] The transaction ID you originally passed to minFraud.
+        #   This field is not required, but you are encouraged to provide it or
+        #   the transaction's maxmind_id or minfraud_id
+        attr_accessor :transaction_id
+
+        # Creates Minfraud::Components::Report::Transaction instance
+        # @param  [Hash] params hash of parameters
+        # @return [Minfraud::Components::Report::Transaction] a Report::Transaction
+        #   instance
+        def initialize(params = {})
+          @ip_address = params[:ip_address]
+          @chargeback_code = params[:chargeback_code]
+          @maxmind_id = params[:maxmind_id]
+          @minfraud_id = params[:minfraud_id]
+          @notes = params[:notes]
+          @transaction_id = params[:transaction_id]
+          self.tag = params[:tag]
+        end
+      end
+    end
+  end
+end

data/lib/minfraud/components/shipping.rb

@@ -4,17 +4,13 @@ module Minfraud
       include ::Minfraud::Enum
       # @attribute delivery_speed
       # @return [String] The shipping delivery speed for the order. The valid values are:
-      #    => same_day
-      #    => overnight
-      #    => expedited
-      #    => standard
       enum_accessor :delivery_speed, [:same_day, :overnight, :expedited, :standard]
 
       # Creates Minfraud::Components::Shipping instance
       # @param  [Hash] params hash of parameters
       # @return [Minfraud::Components::Shipping] Shipping instance
       def initialize(params = {})
-        @delivery_speed = params[:delivery_speed]
+        self.delivery_speed = params[:delivery_speed]
         super
       end
     end

data/lib/minfraud/components/shopping_cart.rb

@@ -20,9 +20,10 @@ module Minfraud
       private
 
       # @param  [Hash] params hash of parameters for Minfraud::Components::ShoppingCartItem
+      # or Minfraud::Components::ShoppingCartItem instance
       # @return [Minfraud::Components::ShoppingCart] ShoppingCart instance
       def resolve(params)
-        ShoppingCartItem.new(params)
+        params.is_a?(ShoppingCartItem) ? params : ShoppingCartItem.new(params)
       end
     end
   end

data/lib/minfraud/enum.rb

@@ -5,12 +5,17 @@ module Minfraud
     end
 
     module ClassMethods
+      # Returns a hash with in the following format: attribute_name => permitted_values
+      # @return [Hash] mapping
       def mapping
         @mapping ||= {}
       end
 
+      # Creates a set of methods for enum-like behaviour of the attribute
+      # @param [Symbol] attribute attribute name
+      # @param [Array] assignable_values a set of values which are permitted
       def enum_accessor(attribute, assignable_values)
-        mapping[attribute] = assignable_values.map(&:to_s)
+        mapping[attribute] = assignable_values.map(&:intern)
 
         self.class.instance_eval do
           define_method("#{attribute}_values") { mapping[attribute] }
@@ -18,10 +23,9 @@ module Minfraud
 
         self.class_eval do
           define_method("#{attribute}") { instance_variable_get("@#{attribute}") }
-
           define_method "#{attribute}=" do |value|
-            raise NotEnumValueError,  'Value is not permitted' unless self.class.mapping[attribute].include?(value.to_s)
-            instance_variable_set("@#{attribute}", value.to_s)
+            raise NotEnumValueError,  'Value is not permitted' if value && !self.class.mapping[attribute].include?(value.intern)
+            instance_variable_set("@#{attribute}", value ? value.intern : nil)
           end
         end
       end

data/lib/minfraud/error_handler.rb

@@ -1,45 +1,65 @@
+# frozen_string_literal: true
+
 module Minfraud
   module ErrorHandler
     class << self
-      # Returns a response if status code is 200, rises an error otherwise
+      # Returns a response if status code is 2xx, raises an error otherwise
       # @param [Minfraud::HTTPService::Response] response
       # @return [Minfraud::HTTPService::Response] if status code is 200
-      def inspect(response)
-        return response if response.status == 200
+      def examine(response)
+        return response if response.status > 199 && response.status < 300
 
-        raise *STATUS_CODES.fetch(response.code&.intern, [ServerError, 'Service not available'])
+        raise *STATUS_CODES.fetch(response.code, [ServerError, 'Server error'])
       end
 
       # A hash that maps status codes returned by minFraud with errors & messages
       STATUS_CODES = {
-        IP_ADDRESS_INVALID:    [
-          ClientError, 'You have no supplied a valid IPv4 or IPv6 address'
+        IP_ADDRESS_INVALID: [
+          ClientError, 'You have not supplied a valid IPv4 or IPv6 address'
         ],
-        IP_ADDRESS_REQUIRED:   [
-          ClientError,  'You have not supplied an IP address which is required filed'
+        IP_ADDRESS_REQUIRED: [
+          ClientError, 'You have not supplied an IP address which is a required field'
         ],
-        IP_ADDRESS_RESERVED:   [
+        IP_ADDRESS_RESERVED: [
           ClientError, 'You have supplied an IP address which is reserved'
         ],
-        JSON_INVALID:          [
+        JSON_INVALID: [
           ClientError, 'JSON body cannot be decoded'
         ],
+        MAXMIND_ID_INVALID: [
+          ClientError, 'You have not supplied a valid maxmind_id'
+        ],
+        MINFRAUD_ID_INVALID: [
+          ClientError, 'You have not supplied a valid minfraud_id'
+        ],
+        PARAMETER_UNKNOWN: [
+          ClientError, 'You have supplied an unknown parameter'
+        ],
+        TAG_REQUIRED: [
+          ClientError, 'You have not supplied a tag, which is a required field'
+        ],
+        TAG_INVALID: [
+          ClientError, 'You have not supplied a valid tag'
+        ],
+        ACCOUNT_ID_REQUIRED: [
+          AuthorizationError, 'You have not supplied a account ID'
+        ],
         AUTHORIZATION_INVALID: [
-          AuthorizationError, 'Invalid license key and / or user id'
+          AuthorizationError, 'Invalid license key and / or account ID'
         ],
-        LICENSE_KEY_REQUIRED:  [
+        LICENSE_KEY_REQUIRED: [
           AuthorizationError, 'You have not supplied a license key'
         ],
-        USER_ID_REQUIRED:      [
-          AuthorizationError, 'You have not supplied a user id'
+        USER_ID_REQUIRED: [
+          AuthorizationError, 'You have not supplied a account id'
         ],
-        INSUFFICIENT_FUNDS:    [
+        INSUFFICIENT_FUNDS: [
           ClientError, 'The license key you have provided does not have a sufficient funds to use this service'
         ],
-        PERMISSION_REQUIRED:   [
+        PERMISSION_REQUIRED: [
           ClientError, 'You do not have permission to use this service'
         ]
-      }
+      }.freeze
     end
   end
 end

data/lib/minfraud/http_service.rb

@@ -19,13 +19,12 @@ module Minfraud
 
       builder.basic_auth *::Minfraud.configuration.values
 
-      builder.response   :mashify
       builder.response   :json, content_type: /\bjson$/
 
       builder.adapter    Faraday.default_adapter
     end
 
     # Minfraud default server
-    DEFAULT_SERVER = 'https://minfraud.maxmind.com/minfraud/v2.0'
+    DEFAULT_SERVER = 'https://minfraud.maxmind.com/minfraud/v2.0'.freeze
   end
 end

data/lib/minfraud/http_service/request.rb

@@ -14,7 +14,7 @@ module Minfraud
       # Creates Minfraud::HTTPService::Request instance
       # @param  [Hash] params hash of parameters
       # @return [Minfraud::HTTPService::Request] Request instance
-      def initialize(params)
+      def initialize(params = {})
         @middleware = params[:middleware]
         @server     = params[:server]
       end

data/lib/minfraud/http_service/response.rb

@@ -1,36 +1,64 @@
+require 'minfraud/model/error'
+require 'minfraud/model/factors'
+require 'minfraud/model/insights'
+require 'minfraud/model/score'
+
 module Minfraud
   module HTTPService
+    # Response class for HTTP requests
     class Response
       # @attribute status
       # @return [Integer] HTTP response status
       attr_reader :status
 
       # @attribute body
-      # @return [Hash] HTTP response body
+      # @return [Minfraud::Model::Score, Minfraud::Model::Insights,
+      #   Minfraud::Model::Factors] HTTP response body
       attr_reader :body
 
       # @attribute headers
       # @return [Hash] HTTP response headers
       attr_reader :headers
 
-      # @attribute code
-      # @return [String] minFraud specific HTTP response code
-      attr_reader :code
-
       # Creates Minfraud::HTTPService::Response instance
       # @param  [Hash] params hash of parameters
       # @return [Minfraud::HTTPService::Response] Response instance
-      def initialize(params)
+      def initialize(params = {})
         @status  = params[:status]
-        @body    = params[:body]
+        @body    = make_body(
+          params[:endpoint],
+          params[:body],
+          params[:locales]
+        )
         @headers = params[:headers]
       end
 
-      # Returns minFraud specific response code
-      # @return [String] minFraud specific request code
+      # Returns minFraud-specific response code
+      # @return [Symbol, nil] minFraud specific request code
       def code
-        body.code if body.respond_to?(:code)
+        return nil if body.nil?
+
+        body.code.intern if body.respond_to?(:code) && body.code
       end
+
+      private
+
+      def make_body(endpoint, body, locales)
+        if @status != 200
+          # Won't be a Hash when the body is not JSON.
+          return nil unless body.is_a?(Hash)
+
+          return Minfraud::Model::Error.new(body)
+        end
+
+        ENDPOINT_TO_CLASS[endpoint].new(body, locales)
+      end
+
+      ENDPOINT_TO_CLASS = {
+        factors: Minfraud::Model::Factors,
+        insights: Minfraud::Model::Insights,
+        score: Minfraud::Model::Score
+      }.freeze
     end
   end
 end

data/lib/minfraud/model/abstract.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Minfraud
+  module Model
+    # @!visibility private
+    class Abstract
+      def initialize(record)
+        @record = record
+      end
+
+      protected
+
+      def get(key)
+        return nil if @record.nil? || !@record.key?(key)
+
+        @record[key]
+      end
+    end
+  end
+end

data/lib/minfraud/model/address.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+
+module Minfraud
+  module Model
+    # Abstract model for a postal address.
+    class Address < Abstract
+      # The distance in kilometers from the address to the IP location.
+      #
+      # @return [Integer, nil]
+      attr_reader :distance_to_ip_location
+
+      # This property is true if the address is in the IP country. The property
+      # is false when the address is not in the IP country. If the address
+      # could not be parsed or was not provided or if the IP address could not
+      # be geolocated, the property will be nil.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_in_ip_country
+
+      # This property is true if the postal code provided with the address is
+      # in the city for the address. The property is false when the postal code
+      # is not in the city. If the address was not provided or could not be
+      # parsed, the property will be nil.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_postal_in_city
+
+      # The latitude associated with the address.
+      #
+      # @return [Float, nil]
+      attr_reader :latitude
+
+      # The longitude associated with the address.
+      #
+      # @return [Float, nil]
+      attr_reader :longitude
+
+      # @!visibility private
+      def initialize(record)
+        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')
+      end
+    end
+  end
+end

data/lib/minfraud/model/billing_address.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/address'
+
+module Minfraud
+  module Model
+    # Model containing information about the billing address.
+    class BillingAddress < Address
+    end
+  end
+end

data/lib/minfraud/model/credit_card.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+require 'minfraud/model/issuer'
+
+module Minfraud
+  module Model
+    # Model with details about the credit card used.
+    class CreditCard < Abstract
+      # The card brand, such as "Visa", "Discover", "American Express", etc.
+      #
+      # @return [String, nil]
+      attr_reader :brand
+
+      # This property contains the two letter ISO 3166-1 alpha-2 country code
+      # (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) associated with the
+      # location of the majority of customers using this credit card as
+      # determined by their billing address. In cases where the location of
+      # customers is highly mixed, this defaults to the country of the bank
+      # issuing the card.
+      #
+      # @return [String, nil]
+      attr_reader :country
+
+      # This property is true if the card is a business card.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_business
+
+      # This property is true if the country of the billing address matches the
+      # country of the majority of customers using this credit card. In cases
+      # where the location of customers is highly mixed, the match is to the
+      # country of the bank issuing the card.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_issued_in_billing_address_country
+
+      # This property is true if the card is a prepaid card.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_prepaid
+
+      # This property is true if the card is a virtual card.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_virtual
+
+      # An object containing information about the credit card issuer.
+      #
+      # @return [Minfraud::Model::Issuer]
+      attr_reader :issuer
+
+      # The card's type. The valid values are: charge, credit, debit.
+      #
+      # @return [String, nil]
+      attr_reader :type
+
+      # @!visibility private
+      def initialize(record)
+        super(record)
+
+        @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')
+      end
+    end
+  end
+end