[CH9786] Implement recommendation methods (#38)

* Add method to retrieve recommendations + request definition + tests.

* Add in support for list of item ID's.

* Add tests for recommendations responses.

* Add ResultPod definition + test clarity.

* CR fixes.

* Minor tweak to comments

Co-authored-by: Zubin Tiku <rubikzube@gmail.com>

Author: sblaurock

constructorio-client/src/main/java/io/constructor/client/ConstructorIO.java

@@ -17,6 +17,7 @@
 
 import io.constructor.client.models.AutocompleteResponse;
 import io.constructor.client.models.SearchResponse;
+import io.constructor.client.models.RecommendationsResponse;
 import io.constructor.client.models.ServerError;
 import okhttp3.HttpUrl;
 import okhttp3.MediaType;
@@ -97,7 +98,7 @@ public ConstructorIO(String apiToken, String apiKey, boolean isHTTPS, String hos
 
     /**
      * Creates a constructor.io Client.
-     * 
+     *
      * @param apiToken API Token, gotten from your <a href="https://constructor.io/dashboard">Constructor.io Dashboard</a>, and kept secret.
      * @param apiKey API Key, used publically in your in-site javascript client.
      * @param isHTTPS true to use HTTPS, false to use HTTP. It is highly recommended that you use HTTPS.
@@ -349,7 +350,7 @@ public boolean modifyItem(ConstructorItem item, String autocompleteSection, Stri
     /**
      * Queries the autocomplete service.
      *
-     * Note that if you're making an autocomplete service on a website, you should definitely use our javascript client instead of doing it server-side!
+     * Note that if you're making an autocomplete request for a website, you should definitely use our javascript client instead of doing it server-side!
      * That's important. That will be a solid latency difference.
      *
      * @param req the autocomplete request
@@ -369,7 +370,7 @@ public AutocompleteResponse autocomplete(AutocompleteRequest req, UserInfo userI
     /**
      * Queries the autocomplete service.
      *
-     * Note that if you're making an autocomplete service on a website, you should definitely use our javascript client instead of doing it server-side!
+     * Note that if you're making an autocomplete request for a website, you should definitely use our javascript client instead of doing it server-side!
      * That's important. That will be a solid latency difference.
      *
      * @param req the autocomplete request
@@ -405,7 +406,7 @@ public String autocompleteAsJSON(AutocompleteRequest req, UserInfo userInfo) thr
     /**
      * Queries the search service.
      *
-     * Note that if you're making an search service on a website, you should definitely use our javascript client instead of doing it server-side!
+     * Note that if you're making a search request for a website, you should definitely use our javascript client instead of doing it server-side!
      * That's important. That will be a solid latency difference.
      *
      * @param req the search request
@@ -425,7 +426,7 @@ public SearchResponse search(SearchRequest req, UserInfo userInfo) throws Constr
     /**
      * Queries the search service.
      *
-     * Note that if you're making an search service on a website, you should definitely use our javascript client instead of doing it server-side!
+     * Note that if you're making a search request for a website, you should definitely use our javascript client instead of doing it server-side!
      * That's important. That will be a solid latency difference.
      *
      * @param req the search request
@@ -479,7 +480,7 @@ public String searchAsJSON(SearchRequest req, UserInfo userInfo) throws Construc
     /**
      * Queries the search service with natural language processing.
      *
-     * Note that if you're making a search service on a website, you should definitely use our javascript client instead of doing it server-side!
+     * Note that if you're making a search request for a website, you should definitely use our javascript client instead of doing it server-side!
      * That's important. That will be a solid latency difference.
      *
      * @param req the natural language search request
@@ -499,7 +500,7 @@ public SearchResponse naturalLanguageSearch(NaturalLanguageSearchRequest req, Us
     /**
      * Queries the search service with natural language processing.
      *
-     * Note that if you're making a search service on a website, you should definitely use our javascript client instead of doing it server-side!
+     * Note that if you're making a search request for a website, you should definitely use our javascript client instead of doing it server-side!
      * That's important. That will be a solid latency difference.
      *
      * @param req the natural language search request
@@ -530,6 +531,66 @@ public String naturalLanguageSearchAsJSON(NaturalLanguageSearchRequest req, User
         }
     }
 
+    /**
+     * Queries the recommendations service to retrieve results.
+     *
+     * Note that if you're making a recommendations request for a website, you should definitely use our javascript client instead of doing it server-side!
+     * That's important. That will be a solid latency difference.
+     *
+     * @param req the recommendations request
+     * @param userInfo optional information about the user
+     * @return a recommendations response
+     * @throws ConstructorException if the request is invalid.
+     */
+    public RecommendationsResponse recommendations(RecommendationsRequest req, UserInfo userInfo) throws ConstructorException {
+        try {
+            String json = recommendationsAsJSON(req, userInfo);
+            return createRecommendationsResponse(json);
+        } catch (Exception exception) {
+            throw new ConstructorException(exception);
+        }
+    }
+
+    /**
+     * Queries the recommendations service to retrieve results.
+     *
+     * Note that if you're making an recommendations request for a website, you should definitely use our javascript client instead of doing it server-side!
+     * That's important. That will be a solid latency difference.
+     *
+     * @param req the recommendations request
+     * @param userInfo optional information about the user
+     * @return a string of JSON
+     * @throws ConstructorException if the request is invalid.
+     */
+    public String recommendationsAsJSON(RecommendationsRequest req, UserInfo userInfo) throws ConstructorException {
+        try {
+            String path = "recommendations/v1/pods/" + req.getPodId();
+            HttpUrl url = (userInfo == null) ? this.makeUrl(path) : this.makeUrl(path, userInfo);
+            url = url.newBuilder()
+                .addQueryParameter("num_results", String.valueOf(req.getNumResults()))
+                .addQueryParameter("section", req.getSection())
+                .build();
+
+            if (req.getItemIds() != null) {
+                for (String itemId : req.getItemIds()) {
+                    url = url.newBuilder()
+                        .addQueryParameter("item_id", itemId)
+                        .build();
+                }
+            }
+
+            Request request = this.makeUserRequestBuilder(userInfo)
+                .url(url)
+                .get()
+                .build();
+
+            Response response = clientWithRetry.newCall(request).execute();
+            return getResponseBody(response);
+        } catch (Exception exception) {
+            throw new ConstructorException(exception);
+        }
+    }
+
     /**
      * Makes a URL to issue the requests to.  Note that the URL will automagically have the apiKey embedded.
      *
@@ -544,7 +605,7 @@ protected HttpUrl makeUrl(String path) throws UnsupportedEncodingException {
             .addQueryParameter("c", this.version)
             .host(this.host)
             .build();
-        
+
         return url;
     }
 
@@ -568,7 +629,7 @@ protected HttpUrl makeUrl(String path, UserInfo info) throws UnsupportedEncoding
         if (info.getUserId() != null) {
             url = url.newBuilder()
                 .addQueryParameter("ui", String.valueOf(info.getUserId()))
-                .build();            
+                .build();
         }
 
         if (info.getUserSegments() != null) {
@@ -584,7 +645,7 @@ protected HttpUrl makeUrl(String path, UserInfo info) throws UnsupportedEncoding
 
     /**
      * Creates a builder for an authorized request
-     * 
+     *
      * @return Request Builder
      */
     protected Builder makeAuthorizedRequestBuilder() {
@@ -595,7 +656,7 @@ protected Builder makeAuthorizedRequestBuilder() {
 
     /**
      * Creates a builder for an end user request
-     * 
+     *
      * @param info user information if available
      * @return Request Builder
      */
@@ -612,7 +673,7 @@ protected Builder makeUserRequestBuilder(UserInfo info) {
 
     /**
      * Checks the response from an endpoint and throws an exception if an error occurred
-     * 
+     *
      * @return whether the request was successful
      */
     protected static String getResponseBody(Response response) throws ConstructorException {
@@ -681,7 +742,21 @@ protected static SearchResponse createSearchResponse(String string) {
     }
 
     /**
-     * Moves metadata out of the result data for an array of results 
+     * Transforms a JSON string to a new JSON string for easy Gson parsing into an recommendations response.
+     * Using JSON objects to acheive this is considerably less error prone than attempting to do it in
+     * a Gson Type Adapter.
+     */
+    protected static RecommendationsResponse createRecommendationsResponse(String string) {
+        JSONObject json = new JSONObject(string);
+        JSONObject response = json.getJSONObject("response");
+        JSONArray results = response.getJSONArray("results");
+        moveMetadataOutOfResultData(results);
+        String transformed = json.toString();
+        return new Gson().fromJson(transformed, RecommendationsResponse.class);
+    }
+
+    /**
+     * Moves metadata out of the result data for an array of results
      * @param results A JSON array of results
      */
     protected static void moveMetadataOutOfResultData(JSONArray results) {
@@ -690,7 +765,7 @@ protected static void moveMetadataOutOfResultData(JSONArray results) {
             JSONObject result = results.getJSONObject(i);
             JSONObject resultData = result.getJSONObject("data");
             JSONObject metadata = new JSONObject();
-            
+
             // Move unspecified properties in result data object to metadata object
             for (Object propertyKey : resultData.keySet()) {
                 String propertyName = (String)propertyKey;
@@ -709,4 +784,4 @@ protected static void moveMetadataOutOfResultData(JSONArray results) {
             resultData.put("metadata", metadata);
         }
     }
-}
+}

constructorio-client/src/main/java/io/constructor/client/RecommendationsRequest.java

@@ -0,0 +1,86 @@
+package io.constructor.client;
+
+import java.util.List;
+
+/**
+ * Constructor.io Recommendations Request
+ */
+public class RecommendationsRequest {
+
+    private String podId;
+    private int numResults;
+    private List<String> itemIds;
+    private String section;
+
+    /**
+     * Creates a recommendations request
+     *
+     * @param podId the pod id to retrieve results from
+     */
+    public RecommendationsRequest(String podId) throws IllegalArgumentException {
+      if (podId == null) {
+          throw new IllegalArgumentException("podId is a required parameter of type string");
+      }
+
+      this.podId = podId;
+      this.numResults = 10;
+      this.itemIds = null;
+      this.section = "Products";
+    }
+
+    /**
+     * @param podId the pod id to set
+     */
+    public void setPodId(String podId) {
+      this.podId = podId;
+    }
+
+    /**
+     * @return the pod id
+     */
+    public String getPodId() {
+      return podId;
+    }
+
+    /**
+     * @param numResults the num results to set
+     */
+    public void setNumResults(int numResults) {
+      this.numResults = numResults;
+    }
+
+    /**
+     * @return the num results
+     */
+    public int getNumResults() {
+      return numResults;
+    }
+
+    /**
+     * @param itemIds the item id's to set
+     */
+    public void setItemIds(List<String> itemIds) {
+      this.itemIds = itemIds;
+  }
+
+    /**
+     * @return the item id's
+     */
+    public List<String> getItemIds() {
+      return itemIds;
+    }
+
+    /**
+     * @param section the section to set
+     */
+    public void setSection(String section) {
+      this.section = section;
+    }
+
+    /**
+     * @return the section
+     */
+    public String getSection() {
+      return section;
+    }
+}

constructorio-client/src/main/java/io/constructor/client/models/RecommendationsResponse.java

@@ -0,0 +1,29 @@
+package io.constructor.client.models;
+
+import com.google.gson.annotations.SerializedName;
+
+/**
+ * Constructor.io Recommendations Response ... uses Gson/Reflection to load data in
+ */
+public class RecommendationsResponse {
+
+    @SerializedName("result_id")
+    private String resultId;
+
+    @SerializedName("response")
+    private RecommendationsResponseInner response;
+    
+    /**
+     * @return the resultId
+     */
+    public String getResultId() {
+      return resultId;
+    }
+
+    /**
+     * @return the response
+     */
+    public RecommendationsResponseInner getResponse() {
+      return response;
+    }
+}

constructorio-client/src/main/java/io/constructor/client/models/RecommendationsResponseInner.java

@@ -0,0 +1,42 @@
+package io.constructor.client.models;
+
+import java.util.List;
+import java.util.Map;
+
+import com.google.gson.annotations.SerializedName;
+
+/**
+ * Constructor.io Recommendations Response Inner ... uses Gson/Reflection to load data in
+ */
+public class RecommendationsResponseInner {
+
+    @SerializedName("results")
+    private List<Result> results;
+
+    @SerializedName("total_num_results")
+    private Integer totalNumberOfResults;
+
+    @SerializedName("pod")
+    private ResultPod pod;
+
+    /**
+     * @return the results
+     */
+    public List<Result> getResults() {
+      return results;
+    }
+
+    /**
+     * @return the totalNumberOfResults
+     */
+    public Integer getTotalNumberOfResults() {
+      return totalNumberOfResults;
+    }
+
+    /**
+     * @return the pod
+     */
+    public ResultPod getPod() {
+      return pod;
+    }
+}