Merge pull request #109 from oalders/report-transaction

Add support for report transaction API

Author: oschwald

CHANGELOG.md

@@ -1,6 +1,9 @@
 CHANGELOG
 =========
 
+* Added support for Report Transaction API. Report Transaction requests can be
+  created via `TransactionReport.Builder()`.
+
 1.13.0 (2020-04-06)
 -------------------
 

README.md

@@ -3,8 +3,8 @@
 
 ## 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/).
 
 ## Installation ##
 
@@ -87,6 +87,18 @@ FactorsResponse factors = client.factors(transaction);
 If the request succeeds, a model object will be returned for the endpoint.
 If the request fails, an exception will be thrown.
 
+To report a transaction:
+
+```java
+TransactionReport transaction = new TransactionReport.Builder(
+         InetAddress.getByName("1.1.1.1"), Tag.NOT_FRAUD
+     ).build();
+client.reportTransaction(transaction);
+```
+
+`reportTransaction()` has a `void` return type. If the request fails, an
+exception will be thrown.
+
 See the API documentation for more details.
 
 ### Exceptions ###
@@ -113,7 +125,9 @@ Checked exceptions:
 * `HttpException` -This will be thrown when an unexpected HTTP error
   occurs such as an internal server error or other unexpected status code.
 
-## Example
+## Examples
+
+### Insights
 
 ```java
 
@@ -222,6 +236,34 @@ WebServiceClient client = new WebServiceClient.Builder(6, "ABCD567890").build();
 System.out.println(client.insights(request));
 ```
 
+### 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 arguments.  Additional params may also
+be set, as documented below.
+
+If the report is successful, nothing is returned. If the report fails, an
+exception with be thrown.
+
+See the API documentation for more details.
+
+```java
+TransactionReport transaction = new TransactionReport.Builder(InetAddress.getByName("1.1.1.1"), Tag.NOT_FRAUD)
+    .chargebackCode("mycode")
+    .maxmindId("12345678")
+    .minfraudId(UUID.fromString("58fa38d8-4b87-458b-a22b-f00eda1aa20d"))
+    .notes("notes go here")
+    .transactionId("foo")
+    .build();
+
+WebServiceClient client = new WebServiceClient.Builder(6, "ABCD567890").build();
+
+client.reportTransaction(transaction);
+```
+
 ## Support ##
 
 Please report all issues with this code using the
@@ -246,6 +288,6 @@ This API uses [Semantic Versioning](https://semver.org/).
 
 ## Copyright and License ##
 
-This software is Copyright (c) 2015-2018 by MaxMind, Inc.
+This software is Copyright (c) 2015-2020 by MaxMind, Inc.
 
 This is free software, licensed under the Apache License, Version 2.0.

dev-bin/release.sh

@@ -52,7 +52,7 @@ popd
 
 mvn versions:display-dependency-updates
 
-read -e -p "Continue given above dependencies? (y/n) " should_continue
+read -e -p -r "Continue given above dependencies? (y/n) " should_continue
 
 if [ "$should_continue" != "y" ]; then
     echo "Aborting"
@@ -78,7 +78,7 @@ cat README.md >> $page
 if [ -n "$(git status --porcelain)" ]; then
     git diff
 
-    read -e -p "Commit README.md changes? " should_commit
+    read -e -p -r "Commit README.md changes? " should_commit
     if [ "$should_commit" != "y" ]; then
         echo "Aborting"
         exit 1
@@ -105,7 +105,7 @@ $notes
 
 "
 
-read -e -p "Push to origin? " should_push
+read -e -p -r "Push to origin? " should_push
 
 if [ "$should_push" != "y" ]; then
     echo "Aborting"

src/main/java/com/maxmind/minfraud/WebServiceClient.java

@@ -10,6 +10,7 @@
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
 import com.maxmind.minfraud.exception.*;
 import com.maxmind.minfraud.request.Transaction;
+import com.maxmind.minfraud.request.TransactionReport;
 import com.maxmind.minfraud.response.FactorsResponse;
 import com.maxmind.minfraud.response.InsightsResponse;
 import com.maxmind.minfraud.response.ScoreResponse;
@@ -282,7 +283,39 @@ public ScoreResponse score(Transaction transaction) throws IOException,
         return responseFor("score", transaction, ScoreResponse.class);
     }
 
-    private <T> T responseFor(String service, Transaction transaction, Class<T> cls)
+    /**
+     * Make a Report Transaction request to the web service using the TransactionReport
+     * request object passed to the method.
+     *
+     * @param transaction A TransactionReport request object.
+     * @throws InsufficientFundsException  when there are insufficient funds on
+     *                                     the account.
+     * @throws AuthenticationException     when there is a problem authenticating.
+     * @throws InvalidRequestException     when the request is invalid for some
+     *                                     other reason.
+     * @throws PermissionRequiredException when permission is required to use the
+     *                                     service.
+     * @throws MinFraudException           when the web service returns unexpected
+     *                                     content.
+     * @throws HttpException               when the web service returns an unexpected
+     *                                     response.
+     * @throws IOException                 when some other IO error occurs.
+     */
+    public void reportTransaction(TransactionReport transaction) throws IOException,
+            MinFraudException, InsufficientFundsException, InvalidRequestException,
+            AuthenticationException, PermissionRequiredException, HttpException {
+        if (transaction == null) {
+            throw new IllegalArgumentException("transaction report must not be null");
+        }
+        URL url = createUrl(WebServiceClient.pathBase + "transactions/report");
+        HttpPost request = requestFor(transaction, url);
+
+        try (CloseableHttpResponse response = httpClient.execute(request)) {
+            maybeThrowException(response, url);
+        }
+    }
+
+    private <T> T responseFor(String service, AbstractModel transaction, Class<T> cls)
             throws IOException, MinFraudException {
         if (transaction == null) {
             throw new IllegalArgumentException("transaction must not be null");
@@ -295,7 +328,7 @@ private <T> T responseFor(String service, Transaction transaction, Class<T> cls)
         }
     }
 
-    private HttpPost requestFor(Transaction transaction, URL url)
+    private HttpPost requestFor(AbstractModel transaction, URL url)
             throws MinFraudException, IOException {
         Credentials credentials = new UsernamePasswordCredentials(Integer.toString(accountId), licenseKey);
 
@@ -321,18 +354,23 @@ private HttpPost requestFor(Transaction transaction, URL url)
         return request;
     }
 
-    private <T> T handleResponse(CloseableHttpResponse response, URL url, Class<T> cls)
-            throws MinFraudException, IOException {
+    private void maybeThrowException(CloseableHttpResponse response, URL url) throws IOException, MinFraudException {
         int status = response.getStatusLine().getStatusCode();
         if (status >= 400 && status < 500) {
             this.handle4xxStatus(response, url);
         } else if (status >= 500 && status < 600) {
             throw new HttpException("Received a server error (" + status
                     + ") for " + url, status, url);
-        } else if (status != 200) {
+        } else if (status != 200 && status != 204) {
             throw new HttpException("Received an unexpected HTTP status ("
                     + status + ") for " + url, status, url);
         }
+    }
+
+    private <T> T handleResponse(CloseableHttpResponse response, URL url, Class<T> cls)
+            throws MinFraudException, IOException {
+        maybeThrowException(response, url);
+
         HttpEntity entity = response.getEntity();
 
         InjectableValues inject = new Std().addValue(