More updates to Verify

Testing, documentation, validation, missing fields...

CHANGELOG.md

@@ -8,8 +8,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Fixed parsing `MessageResponseException` when entity body is empty
 - Added toggle for using Messages API Sandbox to `MessagesClient`
 - Deprecated `request_type` in `VerifyRequest`
-- Fixed incorrect `Content-Type` header in `VerifyEndpoint`
+- Deprecated `ip_address` in `CheckRequest`
+- Fixed incorrect `Content-Type` header in `VerifyEndpoint` (issue #405) and `CheckEndpoint`
 - Added `network` field to `VerifyResponse`
+- Added `estimated_price_messages_sent` to `CheckResponse` and `VerifyDetails`
+- Updated `VerifyStatus` enum values
+- Added missing documentation and validation to requests and responses in Verify API
 
 ## [7.0.0]
 - Removed SMS Search API

src/main/java/com/vonage/client/messages/SendMessageEndpoint.java

@@ -23,10 +23,8 @@
 import org.apache.http.client.methods.RequestBuilder;
 import org.apache.http.entity.ContentType;
 import org.apache.http.entity.StringEntity;
-import java.io.BufferedReader;
+import org.apache.http.util.EntityUtils;
 import java.io.IOException;
-import java.io.InputStreamReader;
-import java.util.stream.Collectors;
 
 class SendMessageEndpoint extends AbstractMethod<MessageRequest, MessageResponse> {
 	private static final Class<?>[] ALLOWED_AUTH_METHODS = {JWTAuthMethod.class, TokenAuthMethod.class};
@@ -67,9 +65,7 @@ public MessageResponse parseResponse(HttpResponse response) throws IOException {
 			return MessageResponse.fromJson(json);
 		}
 		else {
-			try (BufferedReader br = new BufferedReader(new InputStreamReader(response.getEntity().getContent()))) {
-				json = br.lines().collect(Collectors.joining(System.lineSeparator()));
-			}
+			json = EntityUtils.toString(response.getEntity());
 			MessageResponseException mrx = MessageResponseException.fromJson(json);
 			if (mrx.title == null) {
 				mrx.title = response.getStatusLine().getReasonPhrase();

src/main/java/com/vonage/client/redact/RedactEndpoint.java

@@ -31,7 +31,6 @@
 
 class RedactEndpoint extends AbstractMethod<RedactRequest, Void> {
     private static final Class<?>[] ALLOWED_AUTH_METHODS = {SignatureAuthMethod.class, TokenAuthMethod.class};
-
     private static final String PATH = "/redact/transaction";
 
     RedactEndpoint(HttpWrapper httpWrapper) {
@@ -64,7 +63,6 @@ public Void parseResponse(HttpResponse response) throws IOException, VonageClien
         if (response.getStatusLine().getStatusCode() != 204) {
             throw new VonageBadRequestException(EntityUtils.toString(response.getEntity()));
         }
-
         return null;
     }
 

src/main/java/com/vonage/client/sns/SnsEndpoint.java

@@ -42,7 +42,7 @@ class SnsEndpoint extends AbstractMethod<SnsRequest, SnsResponse> {
     private static final Class<?>[] ALLOWED_AUTH_METHODS = {SignatureAuthMethod.class, TokenAuthMethod.class};
     private static final String PATH = "/sns/xml";
 
-    private XmlParser xmlParser = new XmlParser();
+    private final XmlParser xmlParser = new XmlParser();
 
     SnsEndpoint(HttpWrapper httpWrapper) {
         super(httpWrapper);
@@ -54,8 +54,8 @@ protected Class<?>[] getAcceptableAuthMethods() {
     }
 
     @Override
-    public RequestBuilder makeRequest(SnsRequest snsRequest) throws UnsupportedEncodingException {String uri = httpWrapper.getHttpConfig().getSnsBaseUri() + PATH;
-
+    public RequestBuilder makeRequest(SnsRequest snsRequest) throws UnsupportedEncodingException {
+        String uri = httpWrapper.getHttpConfig().getSnsBaseUri() + PATH;
         RequestBuilder requestBuilder = RequestBuilder.post(uri)
                 .addParameter("cmd", snsRequest.getCommand());
         for (Map.Entry<String, String> entry : snsRequest.getQueryParameters().entrySet()) {

src/main/java/com/vonage/client/verify/BaseRequest.java

@@ -24,25 +24,25 @@
 import java.util.Locale;
 
 /**
- * Base request class for {@link VerifyRequest} and {@link Psd2Request}
+ * Base request class for {@link VerifyRequest} and {@link Psd2Request}.
  * @since 5.5.0
  */
 public abstract class BaseRequest {
-    private final String number;
-    private Integer length;
-    private Locale locale;
-    private String country;
-    private Integer pinExpiry;
-    private Integer nextEventWait;
-
+    private final String number, country;
+    private final Integer length, pinExpiry, nextEventWait;
+    private final Locale locale;
 
     protected BaseRequest(String number, Integer length, Locale locale, String country, Integer pinExpiry, Integer nextEventWait) {
         this.number = number;
         this.length = length;
         this.locale = locale;
         this.country = country;
-        this.pinExpiry = pinExpiry;
-        this.nextEventWait = nextEventWait;
+        if ((this.pinExpiry = pinExpiry) != null && (pinExpiry < 60 || pinExpiry > 3600)) {
+            throw new IllegalArgumentException("pin_expiry '"+pinExpiry+"' is out of bounds");
+        }
+        if ((this.nextEventWait = nextEventWait) != null && (nextEventWait < 60 || nextEventWait > 900)) {
+            throw new IllegalArgumentException("next_event_wait '"+nextEventWait+"' is out of bounds");
+        }
     }
 
     /**
@@ -61,7 +61,6 @@ public Integer getLength() {
         return length;
     }
 
-
     /**
      * @return the default locale used for verification. If this value is {@code null}, the locale will be determined
      * from the country code included in {@code number}
@@ -70,16 +69,14 @@ public Locale getLocale() {
         return locale;
     }
 
-
-
     /**
      * @return the default locale used for verification in snake case.
      * Ex: {@code en-gb}
      * If this value is {@code null}, the locale will be determined
      * from the country code included in {@code number}
      */
-    public String getDashedLocale(){
-        if(locale != null){
+    public String getDashedLocale() {
+        if (locale != null) {
            return locale.toLanguageTag().toLowerCase();
         }
         else return null;
@@ -94,23 +91,26 @@ public String getCountry() {
         return country;
     }
 
-
     /**
-     * @return PIN expiry time in seconds
+     * How long the generated verification code is valid for, in seconds. When you specify both <code>pin_expiry</code>
+     * and <code>next_event_wait</code> then <code>pin_expiry</code> must be an integer multiple of
+     * <code>next_event_wait</code>, otherwise <code>pin_expiry</code> will be equal to <code> next_event_wait</code>.
+     *
+     * @return An Integer between <code>60</code> and <code>3600</code>, or <code>null</code>.
      */
     public Integer getPinExpiry() {
         return pinExpiry;
     }
 
-
     /**
-     * @return the wait time between attempts to deliver the PIN. An Integer between 600-900, or null.
+     * The wait time between attempts to deliver the PIN.
+     *
+     * @return An Integer between <code>60</code> and <code>900</code>, or <code>null</code>.
      */
     public Integer getNextEventWait() {
         return nextEventWait;
     }
 
-
     @Override
     public String toString() {
         return  "number='" + number + '\'' +

src/main/java/com/vonage/client/verify/BaseResult.java

@@ -18,8 +18,9 @@
 
 /**
  * An abstract base class for verification results.
- *
+ * @deprecated This class isn't used anywhere in the codebase and will be removed.
  */
+@Deprecated
 public abstract class BaseResult {
     /**
      * Verify was successfully submitted to the Vonage service

src/main/java/com/vonage/client/verify/CheckEndpoint.java

@@ -38,12 +38,9 @@ protected Class<?>[] getAcceptableAuthMethods() {
 
     @Override
     public RequestBuilder makeRequest(CheckRequest request) throws UnsupportedEncodingException {
-        if (request.getRequestId() == null || request.getCode() == null) {
-            throw new IllegalArgumentException("request ID and code parameters are mandatory.");
-        }
-
-        RequestBuilder result = RequestBuilder.post(httpWrapper.getHttpConfig().getApiBaseUri() + PATH)
-                .setHeader("Content-Type", "application/json")
+        String uri = httpWrapper.getHttpConfig().getApiBaseUri() + PATH;
+        RequestBuilder result = RequestBuilder.post(uri)
+                .setHeader("Content-Type", "application/x-www-form-urlencoded")
                 .setHeader("Accept", "application/json")
                 .addParameter("request_id", request.getRequestId())
                 .addParameter("code", request.getCode());

src/main/java/com/vonage/client/verify/CheckRequest.java

@@ -16,28 +16,59 @@
 package com.vonage.client.verify;
 
 public class CheckRequest {
-    private final String requestId;
-    private final String code;
-    private final String ipAddress;
+    private final String requestId, code, ipAddress;
 
+    /**
+     * @param requestId The Verify request to check.
+     * This is the request_id you received in the response to the Verify request.
+     *
+     * @param code The verification code entered by your user. Between 4 and 6 characters.
+     */
     public CheckRequest(String requestId, String code) {
         this(requestId, code, null);
     }
 
+    /**
+     *
+     * @param ipAddress No longer used
+     * @deprecated Please use {@link CheckRequest#CheckRequest(String, String)}.
+     */
+    @Deprecated
     public CheckRequest(String requestId, String code, String ipAddress) {
-        this.requestId = requestId;
-        this.code = code;
+        if ((this.requestId = requestId) == null) {
+            throw new IllegalArgumentException("request_id is required");
+        }
+        if ((this.code = code) == null) {
+            throw new IllegalArgumentException("code is required");
+        }
+        if (requestId.length() > 32) {
+            throw new IllegalArgumentException("request_id '"+requestId+"' is longer than 32 characters");
+        }
+        if (code.length() < 4 || code.length() > 6) {
+            throw new IllegalArgumentException("code '"+code+"' is not between 4 and 6 characters long");
+        }
         this.ipAddress = ipAddress;
     }
 
+    /**
+     * @return The Verify request to check.
+     * This is the request_id you received in the response to the Verify request.
+     */
     public String getRequestId() {
         return requestId;
     }
 
+    /**
+     * @return The verification code entered by your user.
+     */
     public String getCode() {
         return code;
     }
 
+    /**
+     * @deprecated This field is no longer used.
+     */
+    @Deprecated
     public String getIpAddress() {
         return ipAddress;
     }

src/main/java/com/vonage/client/verify/CheckResponse.java

@@ -27,45 +27,76 @@
 
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class CheckResponse {
-    private String requestId;
-    private String eventId;
-    private VerifyStatus status;
-    private BigDecimal price;
-    private String currency;
-    private String errorText;
+    private String requestId, eventId, currency, errorText;
+    private final VerifyStatus status;
+    private BigDecimal price, estimatedPriceMessagesSent;
 
     @JsonCreator
     public CheckResponse(@JsonProperty(value = "status", required = true) VerifyStatus status) {
         this.status = status;
     }
 
+    /**
+     * @return The <code>request_id</code> that you received in the response to the Verify request
+     * and used in the Verify check request.
+     */
     @JsonProperty("request_id")
     public String getRequestId() {
         return requestId;
     }
 
+    /**
+     * @return The ID of the verification event, such as an SMS or TTS call.
+     */
     @JsonProperty("event_id")
     public String getEventId() {
         return eventId;
     }
 
+    /**
+     * @return A value of {@link VerifyStatus#OK} indicates that your user entered the correct code.
+     * Otherwise, check {@link #getErrorText()}.
+     */
     public VerifyStatus getStatus() {
         return status;
     }
 
+    /**
+     * @return The cost incurred for this request.
+     */
     public BigDecimal getPrice() {
         return price;
     }
 
+    /**
+     * @return The currency code.
+     */
     public String getCurrency() {
         return currency;
     }
 
+    /**
+     * @return If the status is non-zero, this explains the error encountered.
+     */
     @JsonProperty("error_text")
     public String getErrorText() {
         return errorText;
     }
 
+    /**
+     * @return This field may not be present, depending on your pricing model.
+     * The value indicates the cost (in EUR) of the calls made and messages sent for the verification process.
+     * This value may be updated during and shortly after the request completes because user input events can
+     * overlap with message/call events. When this field is present, the total cost of the verification is the
+     * sum of this field and the <code>price</code> field.
+     *
+     * @since 7.1.0
+     */
+    @JsonProperty("estimated_price_messages_sent")
+    public BigDecimal getEstimatedPriceMessagesSent() {
+        return estimatedPriceMessagesSent;
+    }
+
     public static CheckResponse fromJson(String json) {
         try {
             ObjectMapper mapper = new ObjectMapper();

src/main/java/com/vonage/client/verify/ControlEndpoint.java

@@ -53,7 +53,6 @@ public ControlResponse parseResponse(HttpResponse response) throws IOException,
         if (!controlResponse.getStatus().equals("0")) {
             throw new VerifyException(controlResponse.getStatus(), controlResponse.getErrorText());
         }
-
         return controlResponse;
     }
 }

src/main/java/com/vonage/client/verify/ControlRequest.java

@@ -35,8 +35,7 @@ public VerifyControlCommand getCommand() {
     }
 
     public void addParams(RequestBuilder request) {
-        request
-                .addParameter("request_id", getRequestId())
+        request.addParameter("request_id", getRequestId())
                 .addParameter("cmd", getCommand().toString());
     }
 

src/main/java/com/vonage/client/verify/ControlResponse.java

@@ -46,6 +46,11 @@ public VerifyControlCommand getCommand() {
         return command;
     }
 
+    /**
+     * If the status is non-zero, this explains the error encountered.
+     *
+     * @return The error description, or <code>null</code> if there was no error.
+     */
     @JsonProperty("error_text")
     public String getErrorText() {
         return errorText;

src/main/java/com/vonage/client/verify/Psd2Endpoint.java

@@ -46,6 +46,7 @@ protected Class<?>[] getAcceptableAuthMethods() {
     public RequestBuilder makeRequest(Psd2Request request) throws UnsupportedEncodingException {
         RequestBuilder builder =  RequestBuilder
                 .post(httpWrapper.getHttpConfig().getApiBaseUri() + PATH)
+                .setHeader("Content-Type", "application/x-www-form-urlencoded")
                 .setHeader("Accept", "application/json")
                 .addParameter("number", request.getNumber())
                 .addParameter("payee", request.getPayee())
@@ -63,7 +64,6 @@ public RequestBuilder makeRequest(Psd2Request request) throws UnsupportedEncodin
         optionalParams(builder, "next_event_wait", request.getNextEventWait());
 
         return builder;
-
     }
 
     @Override