Add new phone outputs

CHANGELOG.md

@@ -8,6 +8,11 @@
   `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.
+* Added `billing_phone` and `shipping_phone` attributes to the minFraud
+  Insights and Factors response models. These contain objects with
+  information about the respective phone numbers. Please see [our developer
+  site](https://dev.maxmind.com/minfraud/api-documentation/responses/) for
+  more information.
 
 ## v2.5.0 (2024-04-16)
 

lib/minfraud/model/insights.rb

@@ -5,6 +5,7 @@
 require 'minfraud/model/device'
 require 'minfraud/model/email'
 require 'minfraud/model/ip_address'
+require 'minfraud/model/phone'
 require 'minfraud/model/score'
 require 'minfraud/model/shipping_address'
 
@@ -18,6 +19,12 @@ class Insights < Score
       # @return [Minfraud::Model::BillingAddress]
       attr_reader :billing_address
 
+      # An object containing minFraud data related to the billing phone
+      # number used in the transaction.
+      #
+      # @return [Minfraud::Model::Phone]
+      attr_reader :billing_phone
+
       # An object containing minFraud data about the credit card used in the
       # transaction.
       #
@@ -48,20 +55,28 @@ class Insights < Score
       # @return [Minfraud::Model::ShippingAddress]
       attr_reader :shipping_address
 
+      # An object containing minFraud data related to the shipping phone
+      # number used in the transaction.
+      #
+      # @return [Minfraud::Model::Phone]
+      attr_reader :shipping_phone
+
       # @!visibility private
       def initialize(record, locales)
         super
 
         @billing_address  = Minfraud::Model::BillingAddress.new(
           get('billing_address')
         )
+        @billing_phone    = Minfraud::Model::Phone.new(get('billing_phone'))
         @credit_card      = Minfraud::Model::CreditCard.new(get('credit_card'))
         @device           = Minfraud::Model::Device.new(get('device'))
         @email            = Minfraud::Model::Email.new(get('email'))
         @ip_address       = Minfraud::Model::IPAddress.new(get('ip_address'), locales)
         @shipping_address = Minfraud::Model::ShippingAddress.new(
           get('shipping_address')
         )
+        @shipping_phone   = Minfraud::Model::Phone.new(get('shipping_phone'))
       end
     end
   end

lib/minfraud/model/phone.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+
+module Minfraud
+  module Model
+    # Model with information about the billing or shipping phone number.
+    class Phone < Abstract
+      # The two-character ISO 3166-1 country code for the country associated
+      # with the phone number.
+      #
+      # @return [String, nil]
+      attr_reader :country
+
+      # This is true if the phone number is a Voice over Internet Protocol
+      # (VoIP) number allocated by a regulator. It is false if the phone
+      # number is not a VoIP number allocated by a regulator. The attribute
+      # is nil when a valid phone number has not been provided or we do not
+      # have data for the phone number.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_voip
+
+      # The name of the original network operator associated with the phone
+      # number. This attribute does not reflect phone numbers that have been
+      # ported from the original operator to another, nor does it identify
+      # mobile virtual network operators.
+      #
+      # @return [String, nil]
+      attr_reader :network_operator
+
+      # One of the following values: fixed or mobile. Additional values may
+      # be added in the future.
+      #
+      # @return [String, nil]
+      attr_reader :number_type
+
+      # @!visibility private
+      def initialize(record)
+        super
+
+        @country          = get('country')
+        @is_voip          = get('is_voip')
+        @network_operator = get('network_operator')
+        @number_type      = get('number_type')
+      end
+    end
+  end
+end

spec/fixtures/files/insights-response1.json

@@ -150,6 +150,12 @@
     "distance_to_ip_location": 5465,
     "is_in_ip_country": false
   },
+  "billing_phone": {
+    "country": "US",
+    "is_voip": false,
+    "network_operator": "Verizon/1",
+    "number_type": "fixed"
+  },
   "credit_card": {
     "issuer": {
       "name": "Bank of No Hope",
@@ -189,6 +195,12 @@
     "latitude": 35.704729,
     "longitude": -97.568619
   },
+  "shipping_phone": {
+    "country": "CA",
+    "is_voip": true,
+    "network_operator": "Telus Mobility-SVR/2",
+    "number_type": "mobile"
+  },
   "warnings": [
     {
       "code": "INPUT_INVALID",
@@ -201,4 +213,4 @@
       "warning": "Encountered value at /account/username_md5 that does meet the required constraints"
     }
   ]
-}
+}

spec/model/insights_spec.rb

@@ -94,6 +94,11 @@
       expect(m.billing_address.distance_to_ip_location).to eq 5_465
       expect(m.billing_address.is_in_ip_country).to eq false
 
+      expect(m.billing_phone.country).to eq 'US'
+      expect(m.billing_phone.is_voip).to eq false
+      expect(m.billing_phone.network_operator).to eq 'Verizon/1'
+      expect(m.billing_phone.number_type).to eq 'fixed'
+
       expect(m.credit_card.issuer.name).to eq 'Bank of No Hope'
       expect(m.credit_card.issuer.matches_provided_name).to eq true
       expect(m.credit_card.issuer.phone_number).to eq '8003421232'
@@ -126,6 +131,11 @@
       expect(m.shipping_address.latitude).to eq 35.704729
       expect(m.shipping_address.longitude).to eq(-97.568619)
 
+      expect(m.shipping_phone.country).to eq 'CA'
+      expect(m.shipping_phone.is_voip).to eq true
+      expect(m.shipping_phone.network_operator).to eq 'Telus Mobility-SVR/2'
+      expect(m.shipping_phone.number_type).to eq 'mobile'
+
       expect(m.warnings[0].code).to eq 'INPUT_INVALID'
       expect(m.warnings[0].warning).to eq 'Encountered value at /account/user_id that does meet the required constraints'
       expect(m.warnings[0].input_pointer).to eq '/account/user_id'