Add support for risk score reasons

Author: oschwald

CHANGELOG.md

@@ -7,6 +7,7 @@ CHANGELOG
 * **Breaking** Updated `TransactionReport` to make the `ipAddress` parameter
   optional. Now the `tag` and at least one of the following paramters must be
   supplied: `ipAddress`, `maxmindId`, `minfraudId`, `transactionId`.
+* Added support for the new risk reasons outputs in minFraud Factors.
 
 6.1.0 (2024-04-16)
 ------------------

e2e/js/package-lock.json

@@ -0,0 +1,38 @@
+[
+  {
+    "multiplier": 45,
+    "reasons": [
+      {
+        "code": "ANONYMOUS_IP",
+        "reason": "Risk due to IP being an Anonymous IP"
+      }
+    ]
+  },
+  {
+    "multiplier": 1.8,
+    "reasons": [
+      {
+        "code": "TIME_OF_DAY",
+        "reason": "Risk due to local time of day"
+      }
+    ]
+  },
+  {
+    "multiplier": 1.6,
+    "reasons": [
+      {
+        "reason": "Riskiness of newly-sighted email domain",
+        "code": "EMAIL_DOMAIN_NEW"
+      }
+    ]
+  },
+  {
+    "multiplier": 0.34,
+    "reasons": [
+      {
+        "code": "EMAIL_ADDRESS_NEW",
+        "reason": "Riskiness of newly-sighted email address"
+      }
+    ]
+  }
+]

e2e/ts/package-lock.json

@@ -4,6 +4,8 @@ import * as webRecords from '../web-records';
 import Insights from './insights';
 
 export default class Factors extends Insights {
+  public readonly riskScoreReasons?: records.RiskScoreReason[];
+
   /**
    * An object containing GeoIP2 and minFraud Insights information about the IP
    * address.
@@ -13,6 +15,7 @@ export default class Factors extends Insights {
   public constructor(response: webRecords.FactorsResponse) {
     super(response);
 
+    this.riskScoreReasons = response.risk_score_reasons;
     this.subscores = camelizeResponse(response.subscores) as records.Subscores;
   }
 }

fixtures/reasons.json

@@ -330,6 +330,35 @@ export interface Disposition {
   readonly ruleLabel?: string;
 }
 
+/**
+ * This object describes one of the reasons for the multiplier.
+ */
+export interface Reason {
+  /**
+   * The machine-readable code for the reason.
+   */
+  code: string;
+  /**
+   * The human-readable description of the reason.
+   */
+  reason: string;
+}
+
+/**
+ * The object describing the risk score multiplier and the reasons for that
+ * multiplier.
+ */
+export interface RiskScoreReason {
+  /**
+   * The risk score multiplier.
+   */
+  multiplier: number;
+  /**
+   * The reasons for the multiplier.
+   */
+  reasons: Reason[];
+}
+
 /**
  * This object contains scores for many of the individual risk factors that
  * are used to calculate the overall risk score.

src/response/models/factors.ts

@@ -114,6 +114,16 @@ export interface DispositionWebRecord {
   readonly rule_label?: string;
 }
 
+export interface ReasonWebRecord {
+  code: string;
+  reason: string;
+}
+
+export interface RiskScoreReasonWebRecord {
+  multiplier: number;
+  reasons: ReasonWebRecord[];
+}
+
 export interface SubscoresWebRecord {
   readonly avs_result?: number;
   readonly billing_address?: number;
@@ -163,5 +173,6 @@ export interface InsightsResponse extends ScoreResponse {
 }
 
 export interface FactorsResponse extends InsightsResponse {
+  readonly risk_score_reasons?: RiskScoreReasonWebRecord[];
   readonly subscores: SubscoresWebRecord;
 }

src/response/records.ts

@@ -2,6 +2,7 @@ import cloneDeep = require('lodash.clonedeep');
 import nock from 'nock';
 import * as models from './response/models';
 import * as insights from '../fixtures/insights.json';
+import reasons from '../fixtures/reasons.json';
 import * as score from '../fixtures/score.json';
 import * as subscores from '../fixtures/subscores.json';
 import {
@@ -26,6 +27,7 @@ const client = new Client(auth.user, auth.pass);
 describe('WebServiceClient', () => {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const factors = cloneDeep(insights) as any;
+  factors.response.full.risk_score_reasons = cloneDeep(reasons);
   factors.response.full.subscores = cloneDeep(subscores);
 
   describe('factors()', () => {
@@ -36,7 +38,7 @@ describe('WebServiceClient', () => {
     });
 
     it('handles "full" responses', async () => {
-      expect.assertions(159);
+      expect.assertions(164);
 
       nockInstance
         .post(fullPath('factors'), factors.request.basic)
@@ -239,6 +241,14 @@ describe('WebServiceClient', () => {
       );
       expect(got.warnings?.[0].inputPointer).toEqual('/shipping/city');
 
+      expect(got.riskScoreReasons).toHaveLength(4);
+      expect(got.riskScoreReasons?.[0].multiplier).toEqual(45);
+      expect(got.riskScoreReasons?.[0].reasons).toHaveLength(1);
+      expect(got.riskScoreReasons?.[0].reasons[0].code).toEqual('ANONYMOUS_IP');
+      expect(got.riskScoreReasons?.[0].reasons[0].reason).toEqual(
+        'Risk due to IP being an Anonymous IP'
+      );
+
       expect(got?.subscores?.avsResult).toEqual(0.01);
       expect(got?.subscores?.billingAddress).toEqual(0.02);
       expect(got?.subscores?.billingAddressDistanceToIpLocation).toEqual(0.03);