Merge pull request #275 from maxmind/kevin/report-transaction

Add support for the Report Transaction API

Author: oschwald

CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+1.7.0 (XXXX-XX-XX)
+------------------
+
+* Added support for the Report Transaction API.
+
 1.6.0 (2020-04-06)
 ------------------
 

README.md

@@ -1,8 +1,8 @@
 # Node.js API for MaxMind minFraud Score, Insights, and Factors
 
 ## Description
-This package provides an API for the [MaxMind minFraud Score, Insights, and
-Factors web services](https://dev.maxmind.com/minfraud/).
+This package provides an API for the [MaxMind minFraud Score, Insights,
+Factors, and Report Transaction web services](https://dev.maxmind.com/minfraud/).
 
 ## Requirements
 
@@ -75,6 +75,49 @@ of:
 {
   code: string
   error: string
+  url: string
+}
+```
+
+### Reporting a transaction using the Report Transactions API
+
+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.
+
+See the API documentation for more details.
+
+```js
+  const transactionReport = new minFraud.TransactionReport({
+    ipAddress: '8.8.8.8',
+    tag: minFraud.Constants.Tag.NOT_FRAUD,
+
+    // The following key/values are not mandatory but are encouraged
+    chargebackCode: 'the string provided by your payment processor indicating
+    the reason for the chargeback',
+    maxmindId: '12345678',
+    minfraudId: '58fa38d8-4b87-458b-a22b-f00eda1aa20d',
+    notes: 'some notes',
+    transactionId: 'the transaction ID you originally passed to minFraud',
+  });
+
+  client.reportTransaction(transactionReport).then(() => ...);
+```
+
+
+If the request succeeds, no data is returned in the Promise.
+
+If the request fails, an error object will be returned in the catch in the
+form of:
+
+```js
+{
+  code: string
+  error: string
+  url: string
 }
 ```
 

src/constants.ts

@@ -143,3 +143,10 @@ export enum Processor {
   Wirecard = 'wirecard',
   Worldpay = 'worldpay',
 }
+
+export enum Tag {
+  CHARGEBACK = 'chargeback',
+  NOT_FRAUD = 'not_fraud',
+  SPAM_OR_ABUSE = 'spam_or_abuse',
+  SUSPECTED_FRAUD = 'suspected_fraud',
+}

src/index.ts

@@ -11,6 +11,7 @@ import Payment from './request/payment';
 import Shipping from './request/shipping';
 import ShoppingCartItem from './request/shopping-cart-item';
 import Transaction from './request/transaction';
+import TransactionReport from './request/transaction-report';
 import Client from './webServiceClient';
 
 export {
@@ -28,4 +29,5 @@ export {
   Shipping,
   ShoppingCartItem,
   Transaction,
+  TransactionReport,
 };

src/request/transaction-report.spec.ts

@@ -0,0 +1,35 @@
+import { Tag } from '../constants';
+import { ArgumentError } from '../errors';
+import TransactionReport from './transaction-report';
+
+describe('Device()', () => {
+  it('throws an error if TransactionReport.ipAddress is not valid', () => {
+    const report = () =>
+      new TransactionReport({
+        ipAddress: 'foo',
+        tag: Tag.CHARGEBACK,
+      });
+    expect(report).toThrowError(ArgumentError);
+    expect(report).toThrowError('transactionReport.ipAddress');
+  });
+
+  it('throws an error if TransactionReport.tag is not valid', () => {
+    const report = () =>
+      new TransactionReport({
+        ipAddress: '1.1.1.1',
+        // @ts-ignore
+        tag: 'foobar',
+      });
+    expect(report).toThrowError(ArgumentError);
+    expect(report).toThrowError('transactionReport.tag');
+  });
+
+  it('constructs', () => {
+    expect(() => {
+      const device = new TransactionReport({
+        ipAddress: '1.1.1.1',
+        tag: Tag.CHARGEBACK,
+      });
+    }).not.toThrow();
+  });
+});

src/request/transaction-report.ts

@@ -0,0 +1,89 @@
+import { isIP } from 'net';
+import * as snakecaseKeys from 'snakecase-keys';
+import { Tag } from '../constants';
+import { ArgumentError } from '../errors';
+
+interface TransactionReportProps {
+  /**
+   * A string which is provided by your payment processor indicating the
+   * reason for the chargeback.
+   */
+  chargebackCode?: string;
+  /**
+   * The IP address of the customer placing the order.
+   */
+  ipAddress: string;
+  /**
+   * 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.
+   */
+  maxmindId?: string;
+  /**
+   * 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.
+   */
+  minfraudId?: string;
+  /**
+   * 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.
+   */
+  notes?: string;
+  /**
+   * A Tag enum indicating the likelihood that a transaction may be
+   * fraudulent.
+   */
+  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.
+   */
+  transactionId?: string;
+}
+
+export default class TransactionReport {
+  /** @inheritDoc TransactionReportProps.chargebackCode */
+  public chargebackCode?: string;
+  /** @inheritDoc TransactionReportProps.ipAddress */
+  public ipAddress: string;
+  /** @inheritDoc TransactionReportProps.maxmindId */
+  public maxmindId?: string;
+  /** @inheritDoc TransactionReportProps.minfraudId */
+  public minfraudId?: string;
+  /** @inheritDoc TransactionReportProps.notes */
+  public notes?: string;
+  /** @inheritDoc TransactionReportProps.tag */
+  public tag: Tag;
+  /** @inheritDoc TransactionReportProps.transactionId */
+  public transactionId?: string;
+
+  public constructor(transactionReport: TransactionReportProps) {
+    if (isIP(transactionReport.ipAddress) === 0) {
+      throw new ArgumentError(
+        '`transactionReport.ipAddress` is an invalid IP address'
+      );
+    }
+
+    if (
+      !transactionReport.tag ||
+      !Object.values(Tag).includes(transactionReport.tag)
+    ) {
+      throw new ArgumentError(
+        `"${transactionReport.tag}" is an invalid value for "transactionReport.tag"`
+      );
+    }
+
+    this.ipAddress = transactionReport.ipAddress;
+    this.tag = transactionReport.tag;
+    Object.assign(this, transactionReport);
+  }
+
+  public toString(): string {
+    return JSON.stringify(snakecaseKeys(this));
+  }
+}

src/webServiceClient.spec.ts

@@ -3,7 +3,13 @@ import * as nock from 'nock';
 import * as insights from '../fixtures/insights.json';
 import * as score from '../fixtures/score.json';
 import * as subscores from '../fixtures/subscores.json';
-import { Client, Device, Transaction } from './index';
+import {
+  Client,
+  Constants,
+  Device,
+  Transaction,
+  TransactionReport,
+} from './index';
 import * as webRecords from './response/web-records';
 import { camelizeResponse } from './utils';
 
@@ -130,6 +136,43 @@ describe('WebServiceClient', () => {
     });
   });
 
+  describe('reportTransaction', () => {
+    it('handles bare minimum request', () => {
+      const report = new TransactionReport({
+        ipAddress: '1.1.1.1',
+        tag: Constants.Tag.CHARGEBACK,
+      });
+
+      expect.assertions(1);
+
+      nockInstance
+        .post(fullPath('transactions/report'), report.toString())
+        .reply(204);
+
+      return expect(client.reportTransaction(report)).resolves.toBeUndefined();
+    });
+
+    it('handles a "full" request', () => {
+      const report = new TransactionReport({
+        chargebackCode: 'foobar',
+        ipAddress: '1.1.1.1',
+        maxmindId: '1234',
+        minfraudId: '1234',
+        notes: 'hello world',
+        tag: Constants.Tag.CHARGEBACK,
+        transactionId: 'what the',
+      });
+
+      expect.assertions(1);
+
+      nockInstance
+        .post(fullPath('transactions/report'), report.toString())
+        .reply(204);
+
+      return expect(client.reportTransaction(report)).resolves.toBeUndefined();
+    });
+  });
+
   describe('error handling', () => {
     const transaction = new Transaction({
       device: new Device({

src/webServiceClient.ts

@@ -2,6 +2,7 @@ import * as http from 'http';
 import * as https from 'https';
 import { version } from '../package.json';
 import Transaction from './request/transaction';
+import TransactionReport from './request/transaction-report';
 import * as models from './response/models';
 import { WebServiceClientError } from './types';
 
@@ -10,7 +11,7 @@ interface ResponseError {
   error?: string;
 }
 
-type servicePath = 'factors' | 'insights' | 'score';
+type servicePath = 'factors' | 'insights' | 'score' | 'transactions/report';
 
 export default class WebServiceClient {
   private accountID: string;
@@ -49,10 +50,14 @@ export default class WebServiceClient {
     );
   }
 
+  public reportTransaction(report: TransactionReport): Promise<void> {
+    return this.responseFor<void>('transactions/report', report.toString());
+  }
+
   private responseFor<T>(
     path: servicePath,
     postData: string,
-    modelClass: any
+    modelClass?: any
   ): Promise<T> {
     const parsedPath = `/minfraud/v2.0/${path}`;
     const url = `https://${this.host}${parsedPath}`;
@@ -80,6 +85,10 @@ export default class WebServiceClient {
         });
 
         response.on('end', () => {
+          if (response.statusCode && response.statusCode === 204) {
+            return resolve();
+          }
+
           try {
             data = JSON.parse(data);
           } catch {