additionalData for interactions, returnAbGroup for recommendation endpoints

Author: OndraFiedler

README.md

@@ -1,11 +1,12 @@
 # Recombee API Client
 
 A Node.js client (SDK) for easy use of the [Recombee](https://www.recombee.com/) recommendation API.
-
 If you don't have an account at Recombee yet, you can create a free account [here](https://www.recombee.com/).
 
 Documentation of the API can be found at [docs.recombee.com](https://docs.recombee.com/).
 
+For client side (browser, mobile apps ...) .js library please see [this repository](https://github.com/recombee/js-api-client).
+
 ## Installation
 
 ```
@@ -43,7 +44,7 @@ client.send(new AddDetailView,
 var recombee = require('recombee-api-client');
 var rqs = recombee.requests;
 
-var client = new recombee.ApiClient('--my-database-id--', '--my-secret-token--');
+var client = new recombee.ApiClient('--my-database-id--', '--db-private-token--');
 
 // Prepare some userIDs and itemIDs
 const NUM = 100;
@@ -89,7 +90,7 @@ client.send(new rqs.Batch(purchases))
 var recombee = require('recombee-api-client');
 var rqs = recombee.requests;
 
-var client = new recombee.ApiClient('--my-database-id--', '--my-secret-token--');
+var client = new recombee.ApiClient('--my-database-id--', '--db-private-token--');
 const NUM = 100;
 
 // We will use computers as items in this example

lib/api-client.js

@@ -44,7 +44,7 @@ class ApiClient {
         uri: url,
         headers: {'Accept': 'application/json',
                   'Content-Type': 'application/json',
-                  'User-Agent': 'recombee-node-api-client/2.2.0'},
+                  'User-Agent': 'recombee-node-api-client/2.3.0'},
         timeout: request.timeout,
         resolveWithFullResponse: true,
         json: true

lib/requests/add-bookmark.js

@@ -25,6 +25,9 @@ class AddBookmark extends rqs.Request {
    *     - *recommId*
    *         - Type: string
    *         - Description: If this bookmark is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+   *     - *additionalData*
+   *         - Type: 
+   *         - Description: A dictionary of additional data for the interaction.
    */
   constructor(userId, itemId, optional) {
     super('POST', '/bookmarks/', 1000, false);
@@ -34,6 +37,7 @@ class AddBookmark extends rqs.Request {
     this.timestamp = optional.timestamp;
     this.cascadeCreate = optional.cascadeCreate;
     this.recommId = optional.recommId;
+    this.additionalData = optional.additionalData;
   }
 
   /**
@@ -54,6 +58,9 @@ class AddBookmark extends rqs.Request {
     if(this.recommId !== undefined)
       params.recommId = this.recommId;
 
+    if(this.additionalData !== undefined)
+      params.additionalData = this.additionalData;
+
     return params;
   }
 

lib/requests/add-cart-addition.js

@@ -31,6 +31,9 @@ class AddCartAddition extends rqs.Request {
    *     - *recommId*
    *         - Type: string
    *         - Description: If this cart addition is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+   *     - *additionalData*
+   *         - Type: 
+   *         - Description: A dictionary of additional data for the interaction.
    */
   constructor(userId, itemId, optional) {
     super('POST', '/cartadditions/', 1000, false);
@@ -42,6 +45,7 @@ class AddCartAddition extends rqs.Request {
     this.amount = optional.amount;
     this.price = optional.price;
     this.recommId = optional.recommId;
+    this.additionalData = optional.additionalData;
   }
 
   /**
@@ -68,6 +72,9 @@ class AddCartAddition extends rqs.Request {
     if(this.recommId !== undefined)
       params.recommId = this.recommId;
 
+    if(this.additionalData !== undefined)
+      params.additionalData = this.additionalData;
+
     return params;
   }
 

lib/requests/add-detail-view.js

@@ -28,6 +28,9 @@ class AddDetailView extends rqs.Request {
    *     - *recommId*
    *         - Type: string
    *         - Description: If this detail view is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+   *     - *additionalData*
+   *         - Type: 
+   *         - Description: A dictionary of additional data for the interaction.
    */
   constructor(userId, itemId, optional) {
     super('POST', '/detailviews/', 1000, false);
@@ -38,6 +41,7 @@ class AddDetailView extends rqs.Request {
     this.duration = optional.duration;
     this.cascadeCreate = optional.cascadeCreate;
     this.recommId = optional.recommId;
+    this.additionalData = optional.additionalData;
   }
 
   /**
@@ -61,6 +65,9 @@ class AddDetailView extends rqs.Request {
     if(this.recommId !== undefined)
       params.recommId = this.recommId;
 
+    if(this.additionalData !== undefined)
+      params.additionalData = this.additionalData;
+
     return params;
   }
 

lib/requests/add-purchase.js

@@ -34,6 +34,9 @@ class AddPurchase extends rqs.Request {
    *     - *recommId*
    *         - Type: string
    *         - Description: If this purchase is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+   *     - *additionalData*
+   *         - Type: 
+   *         - Description: A dictionary of additional data for the interaction.
    */
   constructor(userId, itemId, optional) {
     super('POST', '/purchases/', 1000, false);
@@ -46,6 +49,7 @@ class AddPurchase extends rqs.Request {
     this.price = optional.price;
     this.profit = optional.profit;
     this.recommId = optional.recommId;
+    this.additionalData = optional.additionalData;
   }
 
   /**
@@ -75,6 +79,9 @@ class AddPurchase extends rqs.Request {
     if(this.recommId !== undefined)
       params.recommId = this.recommId;
 
+    if(this.additionalData !== undefined)
+      params.additionalData = this.additionalData;
+
     return params;
   }
 

lib/requests/add-rating.js

@@ -26,6 +26,9 @@ class AddRating extends rqs.Request {
    *     - *recommId*
    *         - Type: string
    *         - Description: If this rating is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+   *     - *additionalData*
+   *         - Type: 
+   *         - Description: A dictionary of additional data for the interaction.
    */
   constructor(userId, itemId, rating, optional) {
     super('POST', '/ratings/', 1000, false);
@@ -36,6 +39,7 @@ class AddRating extends rqs.Request {
     this.timestamp = optional.timestamp;
     this.cascadeCreate = optional.cascadeCreate;
     this.recommId = optional.recommId;
+    this.additionalData = optional.additionalData;
   }
 
   /**
@@ -57,6 +61,9 @@ class AddRating extends rqs.Request {
     if(this.recommId !== undefined)
       params.recommId = this.recommId;
 
+    if(this.additionalData !== undefined)
+      params.additionalData = this.additionalData;
+
     return params;
   }
 

lib/requests/recommend-items-to-item.js

@@ -8,6 +8,7 @@ const rqs = require("./request");
 /**
  * Recommends set of items that are somehow related to one given item, *X*. Typical scenario  is when user *A* is viewing *X*. Then you may display items to the user that he might be also interested in. Recommend items to item request gives you Top-N such items, optionally taking the target user *A* into account.
  * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
+ * The returned items are sorted by relevancy (first item being the most relevant).
  */
 class RecommendItemsToItem extends rqs.Request {
 
@@ -116,6 +117,9 @@ class RecommendItemsToItem extends rqs.Request {
    *     - *expertSettings*
    *         - Type: 
    *         - Description: Dictionary of custom options.
+   *     - *returnAbGroup*
+   *         - Type: boolean
+   *         - Description: If there is a custom AB-testing running, return name of group to which the request belongs.
    */
   constructor(itemId, targetUserId, count, optional) {
     super('POST', `/recomms/items/${itemId}/items/`, 3000, false);
@@ -135,6 +139,7 @@ class RecommendItemsToItem extends rqs.Request {
     this.rotationRate = optional.rotationRate;
     this.rotationTime = optional.rotationTime;
     this.expertSettings = optional.expertSettings;
+    this.returnAbGroup = optional.returnAbGroup;
   }
 
   /**
@@ -182,6 +187,9 @@ class RecommendItemsToItem extends rqs.Request {
     if(this.expertSettings !== undefined)
       params.expertSettings = this.expertSettings;
 
+    if(this.returnAbGroup !== undefined)
+      params.returnAbGroup = this.returnAbGroup;
+
     return params;
   }
 

lib/requests/recommend-items-to-user.js

@@ -8,6 +8,7 @@ const rqs = require("./request");
 /**
  * Based on user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for a given user.
  * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
+ * The returned items are sorted by relevancy (first item being the most relevant).
  */
 class RecommendItemsToUser extends rqs.Request {
 
@@ -100,6 +101,9 @@ class RecommendItemsToUser extends rqs.Request {
    *     - *expertSettings*
    *         - Type: 
    *         - Description: Dictionary of custom options.
+   *     - *returnAbGroup*
+   *         - Type: boolean
+   *         - Description: If there is a custom AB-testing running, return name of group to which the request belongs.
    */
   constructor(userId, count, optional) {
     super('POST', `/recomms/users/${userId}/items/`, 3000, false);
@@ -117,6 +121,7 @@ class RecommendItemsToUser extends rqs.Request {
     this.rotationRate = optional.rotationRate;
     this.rotationTime = optional.rotationTime;
     this.expertSettings = optional.expertSettings;
+    this.returnAbGroup = optional.returnAbGroup;
   }
 
   /**
@@ -160,6 +165,9 @@ class RecommendItemsToUser extends rqs.Request {
     if(this.expertSettings !== undefined)
       params.expertSettings = this.expertSettings;
 
+    if(this.returnAbGroup !== undefined)
+      params.returnAbGroup = this.returnAbGroup;
+
     return params;
   }
 

lib/requests/recommend-users-to-item.js

@@ -8,6 +8,7 @@ const rqs = require("./request");
 /**
  * Recommend users that are likely to be interested in a given item.
  * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
+ * The returned users are sorted by predicted interest in the item (first user being the most interested).
  */
 class RecommendUsersToItem extends rqs.Request {
 
@@ -85,6 +86,9 @@ class RecommendUsersToItem extends rqs.Request {
    *     - *expertSettings*
    *         - Type: 
    *         - Description: Dictionary of custom options.
+   *     - *returnAbGroup*
+   *         - Type: boolean
+   *         - Description: If there is a custom AB-testing running, return name of group to which the request belongs.
    */
   constructor(itemId, count, optional) {
     super('POST', `/recomms/items/${itemId}/users/`, 50000, false);
@@ -99,6 +103,7 @@ class RecommendUsersToItem extends rqs.Request {
     this.includedProperties = optional.includedProperties;
     this.diversity = optional.diversity;
     this.expertSettings = optional.expertSettings;
+    this.returnAbGroup = optional.returnAbGroup;
   }
 
   /**
@@ -133,6 +138,9 @@ class RecommendUsersToItem extends rqs.Request {
     if(this.expertSettings !== undefined)
       params.expertSettings = this.expertSettings;
 
+    if(this.returnAbGroup !== undefined)
+      params.returnAbGroup = this.returnAbGroup;
+
     return params;
   }