Merge pull request #98 from maxmind/nlogan/report-no-ip

Make IP address optional when reporting transactions

Author: oschwald

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v2.6.0
+
+* Updated the validation for the Report Transactions API to make the
+  `ip_address` parameter optional. Now the `tag` and at least one of the
+  following parameters must be supplied: `ip_address`, `maxmind_id`,
+  `minfraud_id`, `transaction_id`.
+* Updated the validation for the Report Transactions API to check that
+  `ip_address`, `maxmind_id`, and `minfraud_id` contain valid values.
+
 ## v2.5.0 (2024-04-16)
 
 * Equivalent domain names are now normalized when `hash_address` is used.

README.md

@@ -208,9 +208,9 @@ channel is used to improve the accuracy of their fraud detection
 algorithms.
 
 To use the Report Transaction API, create a
-`Minfraud::Components::Report::Transaction` object. An IP address and a
-valid tag are required arguments for this API. Additional parameters may be
-set, as shown below.
+`Minfraud::Components::Report::Transaction` object. A valid tag and at least
+one of the following are required parameters: ip_address, maxmind_id,
+minfraud_id, transaction_id. Additional parameters may be set, as shown below.
 
 If the report is successful, nothing is returned. If the report fails, an
 exception will be thrown.

lib/minfraud/components/report/transaction.rb

@@ -8,9 +8,13 @@ module Report
       # @see https://dev.maxmind.com/minfraud/report-a-transaction?lang=en
       class Transaction < Base
         include ::Minfraud::Enum
+        include ::Minfraud::Validates
 
         # The IP address of the customer placing the order. This should be
-        # passed as a string like "152.216.7.110".
+        # passed as a string like "152.216.7.110". This field is not required
+        # if you provide at least one of the transaction's minfraud_id,
+        # maxmind_id, or transaction_id. You are encouraged to provide it, if
+        # possible.
         #
         # @return [String, nil]
         attr_accessor :ip_address
@@ -34,16 +38,19 @@ class Transaction < Base
 
         # 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.
+        # response for a successful minFraud request. This field is not required
+        # if you provide at least one of the transaction's ip_address,
+        # minfraud_id, or transaction_id. You are encouraged to provide it, if
+        # possible.
         #
         # @return [String, nil]
         attr_accessor :maxmind_id
 
         # 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.
+        # This field is not required if you provide at least one of the
+        # transaction's ip_address, maxmind_id, or transaction_id. You are
+        # encouraged to provide it, if possible.
         #
         # @return [String, nil]
         attr_accessor :minfraud_id
@@ -56,9 +63,10 @@ class Transaction < Base
         # @return [String, nil]
         attr_accessor :notes
 
-        # 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.
+        # The transaction ID you originally passed to minFraud. This field
+        # is not required if you provide at least one of the transaction's
+        # ip_address, maxmind_id, or minfraud_id. You are encouraged to
+        # provide it, if possible.
         #
         # @return [String, nil]
         attr_accessor :transaction_id
@@ -73,6 +81,30 @@ def initialize(params = {})
           @notes           = params[:notes]
           @transaction_id  = params[:transaction_id]
           self.tag         = params[:tag]
+
+          validate
+        end
+
+        private
+
+        def validate
+          return if !Minfraud.enable_validation
+
+          validate_ip('ip_address', @ip_address)
+          validate_string('maxmind_id', 8, @maxmind_id)
+          validate_uuid('minfraud_id', @minfraud_id)
+
+          if ip_address.nil? &&
+             (minfraud_id.nil? || empty_uuid(minfraud_id)) &&
+             (maxmind_id.nil? || maxmind_id.empty?) &&
+             (transaction_id.nil? || transaction_id.empty?)
+            raise ArgumentError, 'At least one of the following is required: ip_address, minfraud_id, maxmind_id, transaction_id.'
+          end
+        end
+
+        def empty_uuid(value)
+          stripped_value = value.to_s.gsub('-', '')
+          stripped_value == '0' * 32
         end
       end
     end

lib/minfraud/validates.rb

@@ -24,6 +24,19 @@ def validate_md5(field, value)
       end
     end
 
+    def validate_uuid(field, value)
+      return if !value
+
+      stripped_value = value.to_s.gsub('-', '')
+
+      # Define a regex pattern for a valid UUID without dashes
+      uuid_regex = /\A[0-9a-f]{32}\z/i
+
+      unless uuid_regex.match(stripped_value)
+        raise InvalidInputError, "The #{field} value is not valid. It must be a UUID string."
+      end
+    end
+
     def validate_subdivision_code(field, value)
       return if !value
 

spec/components/general_spec.rb

@@ -14,6 +14,9 @@
 end
 
 describe Minfraud::Components::Report::Transaction do
+  before do
+    Minfraud.configure { |c| c.enable_validation = false }
+  end
   describe '#initialize' do
     it { is_expected.to be_an_instance_of described_class }
     it { is_expected.to respond_to :to_json }

spec/components/report/transaction_spec.rb

@@ -4,6 +4,9 @@
 
 describe Minfraud::Components::Report::Transaction do
   describe '#initialize' do
+    before do
+      Minfraud.configure { |c| c.enable_validation = false }
+    end
     context 'with an invalid type' do
       it 'raises an exception' do
         expect do
@@ -42,4 +45,61 @@
       end
     end
   end
+
+  describe 'validation' do
+    before do
+      Minfraud.configure { |c| c.enable_validation = true }
+    end
+    context 'missing required identifier field' do
+      it 'raises an exception' do
+        expect do
+          described_class.new(tag: :suspected_fraud)
+        end.to raise_exception(ArgumentError)
+      end
+    end
+    context 'with tag + ip_address' do
+      it 'does not raise an exception' do
+        report = described_class.new(
+          ip_address: '1.2.3.4',
+          tag:        :suspected_fraud
+        )
+
+        expect(report.ip_address).to eq '1.2.3.4'
+        expect(report.tag).to eq :suspected_fraud
+      end
+    end
+    context 'with tag + maxmind_id' do
+      it 'does not raise an exception' do
+        report = described_class.new(
+          tag:        :suspected_fraud,
+          maxmind_id: '12345678'
+        )
+
+        expect(report.tag).to eq :suspected_fraud
+        expect(report.maxmind_id).to eq '12345678'
+      end
+    end
+    context 'with tag + minfraud_id' do
+      it 'does not raise an exception' do
+        report = described_class.new(
+          tag:         :suspected_fraud,
+          minfraud_id: '58fa38d8-4b87-458b-a22b-f00eda1aa20d'
+        )
+
+        expect(report.tag).to eq :suspected_fraud
+        expect(report.minfraud_id).to eq '58fa38d8-4b87-458b-a22b-f00eda1aa20d'
+      end
+    end
+    context 'with tag + transaction_id' do
+      it 'does not raise an exception' do
+        report = described_class.new(
+          tag:            :suspected_fraud,
+          transaction_id: '1FA254yZ'
+        )
+
+        expect(report.tag).to eq :suspected_fraud
+        expect(report.transaction_id).to eq '1FA254yZ'
+      end
+    end
+  end
 end