[ACL-226] New HPP link builder with ability to show mandate results, and set wait and/or signup (#328)

Author: dili91

README.md

@@ -123,11 +123,30 @@ CompletableFuture<ApiResponse<CreatePaymentResponse>> paymentResponse = client
 ApiResponse<CreatePaymentResponse> payment = paymentResponse.get();
 ```
 
-### Build a link to our hosted createPaymentResponse page
+### Build a link to our Hosted Payment Page (HPP)
+
+By default, the Hosted Payment Page link builder creates a payment result page, so you can just pass 
+a `resource_id`, a `resource_token` and `return_uri` parameters:
+```java
+URI link = client.hppLinkBuilder()
+        .resourceType(ResourceType.PAYMENT) // Either PAYMENT or MANDATE. Not mandatory, if not specified PAYMENT is used as default
+        .resourceId("$resourceId")
+        .resourceToken("$resourceToken")
+        .returnUri(URI.create("http://yourdomain.com"))
+        .build();
+```
+If needed, you can specify extra parameters as per our [public documentation](https://docs.truelayer.com/docs/authorise-payments-or-mandates-with-the-hpp#1-build-a-hpp-url),
+like `max_wait_for_result` and `signup`:
+
 ```java
-URI hppLink = client.hpp().getHostedPaymentPageLink("your-createPaymentResponse-id",
-        "your-createPaymentResponse-token",
-        URI.create("http://yourdomain.com"));
+URI link = client.hppLinkBuilder()
+        .resourceType(ResourceType.MANDATE)
+        .resourceId("$resourceId")
+        .resourceToken("$resourceToken")
+        .returnUri(URI.create("http://yourdomain.com"))
+        .maxWaitForResultSeconds(15)
+        .signup(true)
+        .build();
 ```
 
 ## Local setup

gradle.properties

@@ -1,7 +1,7 @@
 # Main properties
 group=com.truelayer
 archivesBaseName=truelayer-java
-version=16.0.1
+version=16.1.0
 
 # Artifacts properties
 sonatype_repository_url=https://s01.oss.sonatype.org/service/local/

src/main/java/com/truelayer/java/HostedPaymentPageLinkBuilder.java

@@ -0,0 +1,84 @@
+package com.truelayer.java;
+
+import static org.apache.commons.lang3.ObjectUtils.isEmpty;
+
+import com.truelayer.java.entities.ResourceType;
+import java.net.URI;
+import java.text.MessageFormat;
+import lombok.AccessLevel;
+import lombok.RequiredArgsConstructor;
+
+@RequiredArgsConstructor(access = AccessLevel.PACKAGE)
+public class HostedPaymentPageLinkBuilder {
+    private final Environment environment;
+
+    private ResourceType resourceType = ResourceType.PAYMENT;
+    private String resourceId;
+    private String resourceToken;
+    private URI returnUri;
+    private Integer maxWaitForResultSeconds;
+    private Boolean signup;
+
+    public HostedPaymentPageLinkBuilder resourceType(ResourceType resourceType) {
+        this.resourceType = resourceType;
+        return this;
+    }
+
+    public HostedPaymentPageLinkBuilder resourceId(String resourceId) {
+        this.resourceId = resourceId;
+        return this;
+    }
+
+    public HostedPaymentPageLinkBuilder resourceToken(String resourceToken) {
+        this.resourceToken = resourceToken;
+        return this;
+    }
+
+    public HostedPaymentPageLinkBuilder returnUri(URI returnUri) {
+        this.returnUri = returnUri;
+        return this;
+    }
+
+    public HostedPaymentPageLinkBuilder maxWaitForResultSeconds(int maxWaitForResultSeconds) {
+        this.maxWaitForResultSeconds = maxWaitForResultSeconds;
+        return this;
+    }
+
+    public HostedPaymentPageLinkBuilder signup(boolean signup) {
+        this.signup = signup;
+        return this;
+    }
+
+    public URI build() {
+        if (isEmpty(this.resourceId)) {
+            throw new TrueLayerException("resource_id must be set");
+        }
+
+        if (isEmpty(resourceToken)) {
+            throw new TrueLayerException("resource_token must be set");
+        }
+
+        if (isEmpty(returnUri) || isEmpty(returnUri.toString())) {
+            throw new TrueLayerException("return_uri must be set");
+        }
+
+        URI hppLink = URI.create(MessageFormat.format(
+                "{0}/{1}#{2}={3}&resource_token={4}&return_uri={5}",
+                environment.getHppUri(),
+                resourceType.getHppLinkPath(),
+                resourceType.getHppLinkQueryParameter(),
+                resourceId,
+                resourceToken,
+                returnUri));
+
+        if (!isEmpty(maxWaitForResultSeconds)) {
+            hppLink = URI.create(MessageFormat.format("{0}&max_wait_for_result={1}", hppLink, maxWaitForResultSeconds));
+        }
+
+        if (!isEmpty(signup)) {
+            hppLink = URI.create(MessageFormat.format("{0}&signup={1}", hppLink, signup));
+        }
+
+        return hppLink;
+    }
+}

src/main/java/com/truelayer/java/ITrueLayerClient.java

@@ -63,9 +63,17 @@ public interface ITrueLayerClient {
     /**
      * Entrypoint for Hosted Payment Page related services.
      * @return a utility to build a Hosted Payment Page URL.
+     * @deprecated use {@link #hppLinkBuilder()} instead.
      */
+    @Deprecated
     IHostedPaymentPageLinkBuilder hpp();
 
+    /**
+     * Entrypoint for Hosted Payment Page related services.
+     * @return a utility to build a Hosted Payment Page URL.
+     */
+    HostedPaymentPageLinkBuilder hppLinkBuilder();
+
     /**
      * Utility to submit payment returns parameters.
      * @param request a submit payment return parameters payload

src/main/java/com/truelayer/java/TrueLayerClient.java

@@ -34,17 +34,25 @@ public class TrueLayerClient implements ITrueLayerClient {
     private ISignupPlusHandler signupPlusHandler;
     private ICommonHandler commonHandler;
 
-    private IHostedPaymentPageLinkBuilder hostedPaymentPageLinkBuilder;
+    /**
+     * @deprecated - use {@link #hostedPaymentPageLinkBuilder} instead.
+     */
+    @Deprecated
+    private IHostedPaymentPageLinkBuilder hppLinkBuilder;
+
+    private HostedPaymentPageLinkBuilder hostedPaymentPageLinkBuilder;
 
     public TrueLayerClient(
             IAuthenticationHandler authenticationHandler,
             IHostedPaymentPageLinkBuilder hostedPaymentPageLinkBuilder,
             ICommonHandler commonHandler,
-            ISignupPlusHandler signupPlusHandler) {
+            ISignupPlusHandler signupPlusHandler,
+            HostedPaymentPageLinkBuilder hppLinkBuilder) {
         this.authenticationHandler = authenticationHandler;
-        this.hostedPaymentPageLinkBuilder = hostedPaymentPageLinkBuilder;
+        this.hppLinkBuilder = hostedPaymentPageLinkBuilder;
         this.commonHandler = commonHandler;
         this.signupPlusHandler = signupPlusHandler;
+        this.hostedPaymentPageLinkBuilder = hppLinkBuilder;
     }
 
     /**
@@ -124,7 +132,13 @@ public ISignupPlusHandler signupPlus() {
      * {@inheritDoc}
      */
     @Override
+    @Deprecated
     public IHostedPaymentPageLinkBuilder hpp() {
+        return this.hppLinkBuilder;
+    }
+
+    @Override
+    public HostedPaymentPageLinkBuilder hppLinkBuilder() {
         return this.hostedPaymentPageLinkBuilder;
     }
 

src/main/java/com/truelayer/java/TrueLayerClientBuilder.java

@@ -9,7 +9,6 @@
 import com.truelayer.java.commonapi.ICommonApi;
 import com.truelayer.java.commonapi.ICommonHandler;
 import com.truelayer.java.entities.RequestScopes;
-import com.truelayer.java.hpp.HostedPaymentPageLinkBuilder;
 import com.truelayer.java.hpp.IHostedPaymentPageLinkBuilder;
 import com.truelayer.java.http.OkHttpClientFactory;
 import com.truelayer.java.http.RetrofitFactory;
@@ -229,8 +228,9 @@ public TrueLayerClient build() {
                 .httpClient(RetrofitFactory.build(authServerApiHttpClient, environment.getAuthApiUri()))
                 .build();
 
-        IHostedPaymentPageLinkBuilder hppLinkBuilder =
-                HostedPaymentPageLinkBuilder.New().uri(environment.getHppUri()).build();
+        IHostedPaymentPageLinkBuilder hppLinkBuilder = com.truelayer.java.hpp.HostedPaymentPageLinkBuilder.New()
+                .uri(environment.getHppUri())
+                .build();
 
         // We're reusing a client with only User agent and Idempotency key interceptors and give it our base payment
         // endpoint
@@ -254,7 +254,12 @@ public TrueLayerClient build() {
         // As per our RFC, if signing options is not configured we create a client which is able to interact
         // with the Authentication API only
         if (isEmpty(signingOptions)) {
-            return new TrueLayerClient(authenticationHandler, hppLinkBuilder, commonHandler, signupPlusHandler);
+            return new TrueLayerClient(
+                    authenticationHandler,
+                    hppLinkBuilder,
+                    commonHandler,
+                    signupPlusHandler,
+                    new HostedPaymentPageLinkBuilder(environment));
         }
 
         // The client used for PayIn endpoints has the authenticated as baseline, but adds the signature manager
@@ -319,7 +324,8 @@ public TrueLayerClient build() {
                 payoutsHandler,
                 signupPlusHandler,
                 commonHandler,
-                hppLinkBuilder);
+                hppLinkBuilder,
+                new HostedPaymentPageLinkBuilder(environment));
     }
 
     private boolean customScopesPresent() {

src/main/java/com/truelayer/java/entities/ResourceType.java

@@ -0,0 +1,15 @@
+package com.truelayer.java.entities;
+
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+
+@RequiredArgsConstructor
+@Getter
+public enum ResourceType {
+    PAYMENT("payments", "payment_id"),
+    MANDATE("mandates", "mandate_id"),
+    ;
+
+    private final String hppLinkPath;
+    private final String hppLinkQueryParameter;
+}

src/main/java/com/truelayer/java/hpp/HostedPaymentPageLinkBuilder.java

@@ -9,13 +9,13 @@
 
 /**
  * {@inheritDoc}
+ * @deprecated - use {@link com.truelayer.java.HostedPaymentPageLinkBuilder} instead.
  */
 @Builder(builderMethodName = "New")
 @Getter
+@Deprecated
 public class HostedPaymentPageLinkBuilder implements IHostedPaymentPageLinkBuilder {
-    /**
-     * @param uri the hosted payment page URI
-     */
+
     private URI uri;
 
     @Override

src/main/java/com/truelayer/java/hpp/IHostedPaymentPageLinkBuilder.java

@@ -4,8 +4,11 @@
 
 /**
  * Exposes all the Hosted Payment Page related capabilities of the library.
+ * @deprecated - use {@link com.truelayer.java.HostedPaymentPageLinkBuilder} instead
  */
+@Deprecated
 public interface IHostedPaymentPageLinkBuilder {
+
     /**
      * Builds a link to TrueLayer HPP with the given details
      * @param paymentId the id of the payment created with a previous call to the Create Payment endpoint