Make IP address optional when reporting transactions

Author: ugexe

CHANGELOG.md

@@ -1,6 +1,13 @@
 CHANGELOG
 =========
 
+6.2.0
+------------------
+
+* 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`.
+
 6.1.0 (2024-04-16)
 ------------------
 

README.md

@@ -90,9 +90,10 @@ of:
 MaxMind encourages the use of this API, as data received through this channel
 is continually used to improve the accuracy of our fraud detection algorithms.
 
-To use the Report Transactions API, create a new `TransactionReport` object. An
-IP address and a valid tag are required key values. Additional key values may
-also be set, as documented below.
+To use the Report Transactions API, create a new `TransactionReport` object. A
+valid tag and at least one of the following are required parameters:
+IP address, maxmind ID, minfraud ID, or transaction ID. Additional key values
+may also be set, as documented below.
 
 See the API documentation for more details.
 

src/request/transaction-report.spec.ts

@@ -25,12 +25,39 @@ describe('Device()', () => {
     expect(report).toThrowError('transactionReport.tag');
   });
 
-  it('constructs', () => {
+  it('constructs with ipAddress', () => {
     expect(() => {
       new TransactionReport({
         ipAddress: '1.1.1.1',
         tag: Tag.CHARGEBACK,
       });
     }).not.toThrow();
   });
+
+  it('constructs with maxmindId', () => {
+    expect(() => {
+      new TransactionReport({
+        maxmindId: '12345678',
+        tag: Tag.CHARGEBACK,
+      });
+    }).not.toThrow();
+  });
+
+  it('constructs with minfraudId', () => {
+    expect(() => {
+      new TransactionReport({
+        minfraudId: '58fa38d8-4b87-458b-a22b-f00eda1aa20',
+        tag: Tag.CHARGEBACK,
+      });
+    }).not.toThrow();
+  });
+
+  it('constructs with transactionId', () => {
+    expect(() => {
+      new TransactionReport({
+        minfraudId: 'abc123',
+        tag: Tag.CHARGEBACK,
+      });
+    }).not.toThrow();
+  });
 });

src/request/transaction-report.ts

@@ -10,9 +10,12 @@ interface TransactionReportProps {
    */
   chargebackCode?: string;
   /**
-   * The IP address of the customer placing the order.
+   * The IP address of the customer placing the order. 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.
    */
-  ipAddress: string;
+  ipAddress?: string;
   /**
    * A unique eight character string identifying a minFraud Standard or
    * Premium request. These IDs are returned in the maxmindID field of a
@@ -23,8 +26,9 @@ interface TransactionReportProps {
   /**
    * 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.
+   * 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.
    */
   minfraudId?: string;
   /**
@@ -40,8 +44,9 @@ interface TransactionReportProps {
   tag: Tag;
   /**
    * The transaction ID you originally passed to minFraud. This field is not
-   * required, but you are encouraged to provide it or the transaction’s
-   * maxmindId or minfraudId.
+   * 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.
    */
   transactionId?: string;
 }
@@ -50,7 +55,7 @@ export default class TransactionReport {
   /** @inheritDoc TransactionReportProps.chargebackCode */
   public chargebackCode?: string;
   /** @inheritDoc TransactionReportProps.ipAddress */
-  public ipAddress: string;
+  public ipAddress?: string;
   /** @inheritDoc TransactionReportProps.maxmindId */
   public maxmindId?: string;
   /** @inheritDoc TransactionReportProps.minfraudId */
@@ -63,12 +68,26 @@ export default class TransactionReport {
   public transactionId?: string;
 
   public constructor(transactionReport: TransactionReportProps) {
-    if (isIP(transactionReport.ipAddress) === 0) {
+    // Check if at least one identifier field is set
+    if (
+      !transactionReport.ipAddress &&
+      !transactionReport.maxmindId &&
+      !transactionReport.minfraudId &&
+      !transactionReport.transactionId
+    ) {
       throw new ArgumentError(
-        '`transactionReport.ipAddress` is an invalid IP address'
+        'The report must contain at least one of the following fields: `ipAddress`, `maxmindId`, `minfraudId`, `transactionId`.'
       );
     }
 
+    if (transactionReport.ipAddress) {
+      if (isIP(transactionReport.ipAddress) === 0) {
+        throw new ArgumentError(
+          '`transactionReport.ipAddress` is an invalid IP address'
+        );
+      }
+    }
+
     if (
       !transactionReport.tag ||
       !Object.values(Tag).includes(transactionReport.tag)