recombee-api-client 6.1.0 → 6.2.0

package/README.md

@@ -37,14 +37,12 @@ const client = new ApiClient(
 
 const request = new requests.ListUsers({ count: 10 });
 
-client
-	.send(request)
-	.then((result) => {
-		console.log(result);
-	})
-	.catch((error) => {
-		console.error(error);
-	});
+try {
+	const result = await client.send(request);
+	console.log(result);
+} catch (error) {
+	console.error(error);
+}
 ```
 
 ```javascript
@@ -89,12 +87,12 @@ async function example() {
 	const response = await client.send(
 		new requests.RecommendItemsToUser("user-25", 5)
 	);
-	console.log("Recommended items for user-25: %j", response.recomms);
+	console.log("Recommended items for user-25:", response.recomms);
 	// User scrolled down - get next 3 recommended items
 	const response2 = await client.send(
 		new requests.RecommendNextItems(response.recommId, 3)
 	);
-	console.log("Next recommended items for user-25: %j", response2.recomms);
+	console.log("Next recommended items for user-25:", response2.recomms);
 }
 
 example();
@@ -121,137 +119,107 @@ const NUM = 100;
 //   - image (url of computer's photo)
 
 // Add properties of items
-client
-	.send(
-		new rqs.Batch([
-			new rqs.AddItemProperty("price", "double"),
-			new rqs.AddItemProperty("num-cores", "int"),
-			new rqs.AddItemProperty("description", "string"),
-			new rqs.AddItemProperty("time", "timestamp"),
-			new rqs.AddItemProperty("image", "image"),
-		])
-	)
-	.then((responses) => {
-		//Prepare requests for setting a catalog of computers
-
-		var requests = Array.apply(0, Array(NUM)).map((_, i) => {
-			return new rqs.SetItemValues(
-				`computer-${i}`, //itemId
-				//values:
-				{
-					price: 600 + 400 * Math.random(),
-					"num-cores": Math.floor(Math.random() * 8) + 1,
-					description: "Great computer",
-					time: new Date().toISOString(),
-					image: `http://examplesite.com/products/computer-${i}.jpg`,
-				},
-				//optional parameters:
-				{
-					cascadeCreate: true, // Use cascadeCreate for creating item
-					// with given itemId, if it doesn't exist
-				}
-			);
-		});
-		//Send catalog to the recommender system
-		return client.send(new rqs.Batch(requests));
-	})
-	.then((responses) => {
-		// Generate some random purchases of items by users
-		const userIds = Array.apply(0, Array(NUM)).map((_, i) => {
-			return `user-${i}`;
-		});
-		const itemIds = Array.apply(0, Array(NUM)).map((_, i) => {
-			return `computer-${i}`;
-		});
+await client.send(
+	new rqs.Batch([
+		new rqs.AddItemProperty("price", "double"),
+		new rqs.AddItemProperty("num-cores", "int"),
+		new rqs.AddItemProperty("description", "string"),
+		new rqs.AddItemProperty("time", "timestamp"),
+		new rqs.AddItemProperty("image", "image"),
+	])
+);
 
-		// Generate some random purchases of items by users
-		const PROBABILITY_PURCHASED = 0.1;
-		const purchases = [];
-		userIds.forEach((userId) => {
-			const purchased = itemIds.filter(
-				() => Math.random() < PROBABILITY_PURCHASED
-			);
-			purchased.forEach((itemId) => {
-				purchases.push(
-					new rqs.AddPurchase(userId, itemId, { cascadeCreate: true })
-				);
-			});
-		});
-		// Send purchases to the recommender system
-		return client.send(new rqs.Batch(purchases));
-	})
-	.then((responses) => {
-		// Get 5 recommendations for user-42, who is currently viewing computer-6
-		// Recommend only computers that have at least 3 cores
-		return client.send(
-			new rqs.RecommendItemsToItem("computer-6", "user-42", 5, {
-				filter: "'num-cores' >= 3",
-			})
-		);
-	})
-	.then((recommended) => {
-		console.log(
-			"Recommended items with at least 3 processor cores: %j",
-			recommended
-		);
 
-		// Recommend only items that are more expensive then currently viewed item (up-sell)
-		return client.send(
-			new rqs.RecommendItemsToItem("computer-6", "user-42", 5, {
-				filter: " 'price' > context_item[\"price\"] ",
-				returnProperties: true,
-			})
-		);
-	})
-	.then((recommended) => {
-		console.log("Recommended up-sell items: %j", recommended);
-
-		// Filters, boosters and other settings can be set also in the Admin UI (admin.recombee.com)
-		// when scenario is specified
-		return client.send(
-			new rqs.RecommendItemsToItem("computer-6", "user-42", 5, {
-				scenario: "product_detail",
-			})
-		);
-	})
-	.then((recommended) => {
-		// Perform personalized full-text search with a user's search query (e.g. "computers")
-		return client.send(
-			new rqs.SearchItems("user-42", "computers", 5, {
-				scenario: "search_top",
-			})
-		);
-	})
-	.then((matched) => {
-		console.log("Matched items: %j", matched);
-	})
-	.catch((error) => {
-		console.error(error);
-		// Use fallback
-	});
-```
+// Prepare requests for setting a catalog of computers
+var requests = Array.apply(0, Array(NUM)).map((_, i) => {
+	return new rqs.SetItemValues(
+		`computer-${i}`, // itemId
+		// values:
+		{
+			price: 600 + 400 * Math.random(),
+			"num-cores": Math.floor(Math.random() * 8) + 1,
+			description: "Great computer",
+			time: new Date().toISOString(),
+			image: `http://examplesite.com/products/computer-${i}.jpg`,
+		},
+		// optional parameters:
+		{
+			cascadeCreate: true, // Use cascadeCreate for creating item
+			// with given itemId, if it doesn't exist
+		}
+	);
+});
 
-## Promises / callbacks
+// Send catalog to the recommender system
+await client.send(new rqs.Batch(requests));
 
-The SDK supports both Promises and callbacks, so you can choose the way which suits your coding style and conventions of your project:
 
-```javascript
-// Using Promises
-await client.send(new ListUsers());
-// or
-client
-	.send(new ListUsers())
-	.then((response) => {
-		// handle response
-	})
-	.catch((error) => {
-		// handle error
-	});
+// Generate some random purchases of items by users
+const userIds = Array.apply(0, Array(NUM)).map((_, i) => {
+	return `user-${i}`;
+});
+const itemIds = Array.apply(0, Array(NUM)).map((_, i) => {
+	return `computer-${i}`;
+});
 
-// Using callbacks
-client.send(new ListUsers(), (error, response) => {
-	// handle result
+// Generate some random purchases of items by users
+const PROBABILITY_PURCHASED = 0.1;
+const purchases = [];
+userIds.forEach((userId) => {
+	const purchased = itemIds.filter(
+		() => Math.random() < PROBABILITY_PURCHASED
+	);
+	purchased.forEach((itemId) => {
+		purchases.push(
+			new rqs.AddPurchase(userId, itemId, { cascadeCreate: true })
+		);
+	});
 });
+// Send purchases to the recommender system
+await client.send(new rqs.Batch(purchases));
+
+// Get 5 recommendations for user-42, who is currently viewing computer-6
+// Recommend only computers that have at least 3 cores
+const recommended = await client.send(
+	new rqs.RecommendItemsToItem("computer-6", "user-42", 5, {
+		filter: "'num-cores' >= 3",
+	})
+);
+console.log(
+	"Recommended items with at least 3 processor cores:",
+	recommended
+);
+
+// Recommend only items that are more expensive then currently viewed item (up-sell)
+const upsell = await client.send(
+	new rqs.RecommendItemsToItem("computer-6", "user-42", 5, {
+		filter: " 'price' > context_item[\"price\"] ",
+		returnProperties: true,
+	})
+);
+console.log("Recommended up-sell items:", upsell);
+
+// Filters, boosters and other settings can be set also in the Admin UI (admin.recombee.com)
+// when scenario is specified
+const productDetail = await client.send(
+	new rqs.RecommendItemsToItem("computer-6", "user-42", 5, {
+		scenario: "product_detail",
+	})
+);
+console.log("Recommended items for product detail scenario:", productDetail);
+
+// Perform personalized full-text search with a user's search query (e.g. "computers")
+try {
+	const searchResults = await client.send(
+		new rqs.SearchItems("user-42", "computers", 5, {
+			scenario: "search_top",
+		})
+	);
+	console.log("Matched items:", searchResults);
+} catch (error) {
+	console.error(error);
+	// use fallback...
+}
 ```
 
 ## Errors handling

package/lib/api-client.js

@@ -43,7 +43,7 @@ class ApiClient {
         method: request.method,
         headers: {'Accept': 'application/json',
                   'Content-Type': 'application/json',
-                  'User-Agent': 'recombee-node-api-client/6.1.0'},
+                  'User-Agent': 'recombee-node-api-client/6.2.0'},
         timeout: request.timeout,
         agent: this.options.agent
     };

package/lib/index.d.ts

@@ -168,6 +168,8 @@ declare module "recombee-api-client" {
         statusCode: number,
         message: string
       );
+
+      public readonly statusCode: number;
     }
 
     /**
@@ -2606,7 +2608,43 @@ declare module "recombee-api-client" {
     }
 
     /**
-     * Composite Recommendation returns both a *source entity* (e.g., an Item or [Item Segment](https://docs.recombee.com/segmentations.html)) and a list of related recommendations in a single response.
+     * Returns Item segments that shall be shown to a user as next recommendations when the user e.g. scrolls the page down (*infinite scroll*) or goes to the next page.
+     * It accepts `recommId` of a base recommendation request (e.g., request from the first page) and the number of segments that shall be returned (`count`).
+     * The base request can be one of:
+     *   - [Recommend Item Segments to Item](https://docs.recombee.com/api#recommend-item-segments-to-item)
+     *   - [Recommend Item Segments to User](https://docs.recombee.com/api#recommend-item-segments-to-user)
+     *   - [Recommend Item Segments to Item Segment](https://docs.recombee.com/api#recommend-item-segments-to-item-segment)
+     *   - [Search Item Segments](https://docs.recombee.com/api#search-item-segments)
+     * All the other parameters are inherited from the base request.
+     * *Recommend next Item segments* can be called many times for a single `recommId` and each call returns different (previously not recommended) segments.
+     * The number of *Recommend next Item segments* calls performed so far is returned in the `numberNextRecommsCalls` field.
+     * *Recommend next Item segments* can be requested up to 30 minutes after the base request or a previous *Recommend next Item segments* call.
+     * For billing purposes, each call to *Recommend next Item segments* is counted as a separate recommendation request.
+     */
+    export class RecommendNextItemSegments extends requests.Request {
+      /**
+       * @param recommId - ID of the base recommendation request for which next recommendations should be returned
+       * @param count - Number of item segments to be recommended
+       */
+      constructor(
+        recommId: string,
+        count: number,
+      );
+
+      recommId: string;
+      count: number;
+      protected __response_type: RecommendationResponse;
+
+      bodyParameters(): {
+        count: number;
+      };
+
+      queryParameters(): {
+      };
+    }
+
+    /**
+     * Composite Recommendation returns both a *source entity* (e.g., an Item or [Item Segment](https://docs.recombee.com/segmentations)) and a list of related recommendations in a single response.
      * It is ideal for use cases such as personalized homepage sections (*Articles from <category>*), *Because You Watched <movie>*, or *Artists Related to Your Favorite Artist <artist>*.
      * See detailed **examples and configuration guidance** in the [Composite Scenarios documentation](https://docs.recombee.com/scenarios#composite-recommendations).
      * **Structure**
@@ -2645,6 +2683,8 @@ declare module "recombee-api-client" {
           logic?: string | object;
           /** ID of the segment from `contextSegmentationId` for which the recommendations are to be generated. */
           segmentId?: string;
+          /** Search query provided by the user. It is used for the full-text search. Only applicable if the *scenario* corresponds to a search scenario. */
+          searchQuery?: string;
           /** If the entity for the source recommendation does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that entity, as the entity will be already known to the system. */
           cascadeCreate?: boolean;
           /** Parameters applied for recommending the *Source* stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the *Source*. */
@@ -2662,6 +2702,7 @@ declare module "recombee-api-client" {
       userId?: string;
       logic?: string | object;
       segmentId?: string;
+      searchQuery?: string;
       cascadeCreate?: boolean;
       sourceSettings?: Record<string, unknown>;
       resultSettings?: Record<string, unknown>;
@@ -2675,6 +2716,7 @@ declare module "recombee-api-client" {
         userId?: string;
         logic?: string | object;
         segmentId?: string;
+        searchQuery?: string;
         cascadeCreate?: boolean;
         sourceSettings?: Record<string, unknown>;
         resultSettings?: Record<string, unknown>;

package/lib/requests/composite-recommendation.js

@@ -6,7 +6,7 @@
 const rqs = require("./request");
 
 /**
- * Composite Recommendation returns both a *source entity* (e.g., an Item or [Item Segment](https://docs.recombee.com/segmentations.html)) and a list of related recommendations in a single response.
+ * Composite Recommendation returns both a *source entity* (e.g., an Item or [Item Segment](https://docs.recombee.com/segmentations)) and a list of related recommendations in a single response.
  * It is ideal for use cases such as personalized homepage sections (*Articles from <category>*), *Because You Watched <movie>*, or *Artists Related to Your Favorite Artist <artist>*.
  * See detailed **examples and configuration guidance** in the [Composite Scenarios documentation](https://docs.recombee.com/scenarios#composite-recommendations).
  * **Structure**
@@ -50,6 +50,9 @@ class CompositeRecommendation extends rqs.Request {
    *     - *segmentId*
    *         - Type: string
    *         - Description: ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.
+   *     - *searchQuery*
+   *         - Type: string
+   *         - Description: Search query provided by the user. It is used for the full-text search. Only applicable if the *scenario* corresponds to a search scenario.
    *     - *cascadeCreate*
    *         - Type: boolean
    *         - Description: If the entity for the source recommendation does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that entity, as the entity will be already known to the system.
@@ -72,6 +75,7 @@ class CompositeRecommendation extends rqs.Request {
     this.userId = optional.userId;
     this.logic = optional.logic;
     this.segmentId = optional.segmentId;
+    this.searchQuery = optional.searchQuery;
     this.cascadeCreate = optional.cascadeCreate;
     this.sourceSettings = optional.sourceSettings;
     this.resultSettings = optional.resultSettings;
@@ -99,6 +103,9 @@ class CompositeRecommendation extends rqs.Request {
     if(this.segmentId !== undefined)
       params.segmentId = this.segmentId;
 
+    if(this.searchQuery !== undefined)
+      params.searchQuery = this.searchQuery;
+
     if(this.cascadeCreate !== undefined)
       params.cascadeCreate = this.cascadeCreate;
 

package/lib/requests/index.js

@@ -63,6 +63,7 @@ exports.RecommendUsersToItem = require("./recommend-users-to-item").RecommendUse
 exports.RecommendItemSegmentsToUser = require("./recommend-item-segments-to-user").RecommendItemSegmentsToUser;
 exports.RecommendItemSegmentsToItem = require("./recommend-item-segments-to-item").RecommendItemSegmentsToItem;
 exports.RecommendItemSegmentsToItemSegment = require("./recommend-item-segments-to-item-segment").RecommendItemSegmentsToItemSegment;
+exports.RecommendNextItemSegments = require("./recommend-next-item-segments").RecommendNextItemSegments;
 exports.CompositeRecommendation = require("./composite-recommendation").CompositeRecommendation;
 exports.SearchItems = require("./search-items").SearchItems;
 exports.SearchItemSegments = require("./search-item-segments").SearchItemSegments;

package/lib/requests/recommend-next-item-segments.js

@@ -0,0 +1,56 @@
+/*
+ This file is auto-generated, do not edit
+*/
+
+'use strict';
+const rqs = require("./request");
+
+/**
+ * Returns Item segments that shall be shown to a user as next recommendations when the user e.g. scrolls the page down (*infinite scroll*) or goes to the next page.
+ * It accepts `recommId` of a base recommendation request (e.g., request from the first page) and the number of segments that shall be returned (`count`).
+ * The base request can be one of:
+ *   - [Recommend Item Segments to Item](https://docs.recombee.com/api#recommend-item-segments-to-item)
+ *   - [Recommend Item Segments to User](https://docs.recombee.com/api#recommend-item-segments-to-user)
+ *   - [Recommend Item Segments to Item Segment](https://docs.recombee.com/api#recommend-item-segments-to-item-segment)
+ *   - [Search Item Segments](https://docs.recombee.com/api#search-item-segments)
+ * All the other parameters are inherited from the base request.
+ * *Recommend next Item segments* can be called many times for a single `recommId` and each call returns different (previously not recommended) segments.
+ * The number of *Recommend next Item segments* calls performed so far is returned in the `numberNextRecommsCalls` field.
+ * *Recommend next Item segments* can be requested up to 30 minutes after the base request or a previous *Recommend next Item segments* call.
+ * For billing purposes, each call to *Recommend next Item segments* is counted as a separate recommendation request.
+ */
+class RecommendNextItemSegments extends rqs.Request {
+
+  /**
+   * Construct the request
+   * @param {string} recommId - ID of the base recommendation request for which next recommendations should be returned
+   * @param {number} count - Number of item segments to be recommended
+   */
+  constructor(recommId, count) {
+    super('POST', `/recomms/next/item-segments/${recommId}`, 3000, false);
+    this.recommId = recommId;
+    this.count = count;
+  }
+
+  /**
+   * Get body parameters
+   * @return {Object} The values of body parameters (name of parameter: value of the parameter)
+   */
+  bodyParameters() {
+    let params = {};
+    params.count = this.count;
+
+    return params;
+  }
+
+  /**
+   * Get query parameters
+   * @return {Object} The values of query parameters (name of parameter: value of the parameter)
+   */
+  queryParameters() {
+    let params = {};
+    return params;
+  }
+}
+
+exports.RecommendNextItemSegments = RecommendNextItemSegments

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recombee-api-client",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "Node.js client (SDK) for easy use of the Recombee recommendation API",
   "main": "index.js",
   "types": "lib/index.d.ts",

package/test/recommend-next-item-segments-batch_test.js

@@ -0,0 +1,48 @@
+/*
+ This file is auto-generated, do not edit
+*/
+
+'use strict'
+var assert = require('chai').assert;
+var recombee = require('./../index.js');
+var rqs = recombee.requests;
+
+var env = require('./set-environment.js');
+
+describe('RecommendNextItemSegments', function(){
+  this.timeout(150000);
+
+  before(function(done){
+
+    env.setEnvironment()
+    .then(()=> {
+      done();
+     });
+  });
+  it ('works in batch', (done) => {
+    env.client.send(new rqs.RecommendNextItemSegments('invalid_recomm_id',5),((err,errRes) => {
+      if(err) {
+        assert.equal(err.statusCode, 400);
+        env.client.send(new rqs.RecommendItemsToUser('entity_id',3),((err,res) => {
+          if(err) {
+            assert.fail();
+          }
+          else {
+            let requests = [
+              new rqs.RecommendNextItemSegments(res['recommId'],5)
+              ];
+            
+            env.client.send(new rqs.Batch(requests))
+            .then((responses) => {
+                assert.equal(responses[0].code, 400);
+              done();
+            });
+          }
+        }));
+      }
+      else {
+        assert.fail();
+      }
+    }));
+  });
+});

package/test/recommend-next-item-segments-callback_test.js

@@ -0,0 +1,60 @@
+/*
+ This file is auto-generated, do not edit
+*/
+
+'use strict'
+var assert = require('chai').assert;
+var recombee = require('./../index.js');
+var rqs = recombee.requests;
+
+var env = require('./set-environment.js');
+
+describe('RecommendNextItemSegments', function(){
+  this.timeout(150000);
+
+  before(function(done){
+
+    env.setEnvironment()
+    .then(()=> {
+      done();
+     });
+  });
+  
+  it ('rejects request with invalid recommId', (done) => {
+    let req, req2, resp;
+    req2 = new rqs.RecommendNextItemSegments('invalid_recomm_id',5);
+    env.client.send(req2,((err,res) => {
+      if(err) {
+        assert.equal(err.name, 'ResponseError');
+        assert.equal(err.statusCode, 400);
+        done();
+      }
+      else {
+        assert.fail();
+      }
+    }));
+  });
+  
+  it ('rejects request to recommId which does not return item-segments', (done) => {
+    let req, req2, resp;
+    req2 = new rqs.RecommendItemsToUser('entity_id',3);
+    env.client.send(req2,((err,res) => {
+      if(err) {
+        assert.fail();
+      }
+      else {
+        req = new rqs.RecommendNextItemSegments(res['recommId'],5);
+        env.client.send(req,((err,res) => {
+          if(err) {
+            assert.equal(err.name, 'ResponseError');
+            assert.equal(err.statusCode, 400);
+            done();
+          }
+          else {
+            assert.fail();
+          }
+        }));
+      }
+    }));
+  });
+});

package/test/recommend-next-item-segments-test.js

@@ -0,0 +1,60 @@
+/*
+ This file is auto-generated, do not edit
+*/
+
+'use strict'
+var assert = require('chai').assert;
+var recombee = require('./../index.js');
+var rqs = recombee.requests;
+
+var env = require('./set-environment.js');
+
+describe('RecommendNextItemSegments', function(){
+  this.timeout(150000);
+
+  before(function(done){
+
+    env.setEnvironment()
+    .then(()=> {
+      done();
+     });
+  });
+  
+  it ('rejects request with invalid recommId', (done) => {
+    let req, req2, resp;
+    req2 = new rqs.RecommendNextItemSegments('invalid_recomm_id',5);
+    env.client.send(req2)
+    .then((res) => {
+      assert.fail();
+      done();
+    })
+    .catch((err) => {
+      if (err instanceof recombee.errors.ResponseError) {
+        assert.equal(err.statusCode, 400);
+        done();
+      }
+      throw err;
+    });
+  });
+  
+  it ('rejects request to recommId which does not return item-segments', (done) => {
+    let req, req2, resp;
+    req2 = new rqs.RecommendItemsToUser('entity_id',3);
+    env.client.send(req2)
+    .then((res) => {
+      req = new rqs.RecommendNextItemSegments(res['recommId'],5);
+      env.client.send(req)
+      .then((res) => {
+        assert.fail();
+        done();
+      })
+      .catch((err) => {
+        if (err instanceof recombee.errors.ResponseError) {
+          assert.equal(err.statusCode, 400);
+          done();
+        }
+        throw err;
+      });
+    });
+  });
+});