Release: v5.0.0

- Support new Recommend Items to Item Segment endpoint
- Series API improvements:
	- Add Series endpoint creates associated Item for the Series automatically (based on the cascadeCreate parameter)
	- Breaking change: Remove From Series no longer requires the time parameter
- Removed deprecated Groups endpoints

Author: OndraFiedler

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/4.1.5'},
+                  'User-Agent': 'recombee-node-api-client/5.0.0'},
         timeout: request.timeout,
         agent: this.options.agent
     };

lib/index.d.ts

@@ -664,15 +664,22 @@ export module "recombee-api-client" {
     export class AddSeries extends requests.Request {
       /**
        * @param seriesId - ID of the series to be created.
+       * @param optional - Optional parameters given as an object.
        */
       constructor(
         seriesId: string,
+        optional?: {
+          /** If set to `true`, the item will be created with the same ID as the series. Default is `true`. */
+          cascadeCreate?: boolean;
+        }
       );
 
       seriesId: string;
+      cascadeCreate?: boolean;
       protected __response_type: string;
 
       bodyParameters(): {
+        cascadeCreate?: boolean;
       };
 
       queryParameters(): {
@@ -686,15 +693,22 @@ export module "recombee-api-client" {
     export class DeleteSeries extends requests.Request {
       /**
        * @param seriesId - ID of the series to be deleted.
+       * @param optional - Optional parameters given as an object.
        */
       constructor(
         seriesId: string,
+        optional?: {
+          /** If set to `true`, item with the same ID as seriesId will be also deleted. Default is `false`. */
+          cascadeDelete?: boolean;
+        }
       );
 
       seriesId: string;
+      cascadeDelete?: boolean;
       protected __response_type: string;
 
       bodyParameters(): {
+        cascadeDelete?: boolean;
       };
 
       queryParameters(): {
@@ -758,7 +772,7 @@ export module "recombee-api-client" {
         itemId: string,
         time: number,
         optional?: {
-          /** Indicates that any non-existing entity specified within the request should be created (as if corresponding PUT requests were invoked). This concerns both the `seriesId` and the `itemId`. If `cascadeCreate` is set to true, the behavior also depends on the `itemType`. Either item or series may be created if not present in the database. */
+          /** Indicates that any non-existing entity specified within the request should be created (as if corresponding PUT requests were invoked). This concerns both the `seriesId` and the `itemId`. If `cascadeCreate` is set to true, the behavior also depends on the `itemType`. In case of `item`, an item is created, in case of `series` a series + corresponding item with the same ID is created. */
           cascadeCreate?: boolean;
         }
       );
@@ -789,28 +803,24 @@ export module "recombee-api-client" {
        * @param seriesId - ID of the series from which a series item is to be removed.
        * @param itemType - Type of the item to be removed.
        * @param itemId - ID of the item iff `itemType` is `item`. ID of the series iff `itemType` is `series`.
-       * @param time - Time index of the item to be removed.
        */
       constructor(
         seriesId: string,
         itemType: string,
         itemId: string,
-        time: number,
       );
 
       seriesId: string;
       itemType: string;
       itemId: string;
-      time: number;
       protected __response_type: string;
 
       bodyParameters(): {
+        itemType: string;
+        itemId: string;
       };
 
       queryParameters(): {
-        itemType: string;
-        itemId: string;
-        time: number;
       };
     }
 
@@ -2179,13 +2189,13 @@ export module "recombee-api-client" {
     }
 
     /**
-     * Recommends the top Segments from a Segmentation for a particular user, based on the user's past interactions.
+     * Recommends the top Segments from a [Segmentation](https://docs.recombee.com/segmentations.html) for a particular user, based on the user's past interactions.
      * Based on the used Segmentation, this endpoint can be used for example for:
      *   - Recommending the top categories for the user
      *   - Recommending the top genres for the user
      *   - Recommending the top brands for the user
      *   - Recommending the top artists for the user
-     * You need to set the used Segmentation the Admin UI in the Scenario settings prior to using this endpoint.
+     * You need to set the used Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.
      * The returned segments are sorted by relevance (first segment being the most relevant).
      * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
      */
@@ -2243,13 +2253,13 @@ export module "recombee-api-client" {
     }
 
     /**
-     * Recommends Segments from a Segmentation that are the most relevant to a particular item.
+     * Recommends Segments from a [Segmentation](https://docs.recombee.com/segmentations.html) that are the most relevant to a particular item.
      * Based on the used Segmentation, this endpoint can be used for example for:
      *   - Recommending the related categories
      *   - Recommending the related genres
      *   - Recommending the related brands
      *   - Recommending the related artists
-     * You need to set the used Segmentation the Admin UI in the Scenario settings prior to using this endpoint.
+     * You need to set the used Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.
      * The returned segments are sorted by relevance (first segment being the most relevant).
      * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
      */
@@ -2323,12 +2333,12 @@ export module "recombee-api-client" {
     }
 
     /**
-     * Recommends Segments from a result Segmentation that are the most relevant to a particular Segment from a context Segmentation.
+     * Recommends Segments from a result [Segmentation](https://docs.recombee.com/segmentations.html) that are the most relevant to a particular Segment from a context Segmentation.
      * Based on the used Segmentations, this endpoint can be used for example for:
      *   - Recommending the related brands to particular brand
      *   - Recommending the related brands to particular category
      *   - Recommending the related artists to a particular genre (assuming songs are the Items)
-     * You need to set the used context and result Segmentation the Admin UI in the Scenario settings prior to using this endpoint.
+     * You need to set the used context and result Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.
      * The returned segments are sorted by relevance (first segment being the most relevant).
      * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
      */
@@ -2402,6 +2412,106 @@ export module "recombee-api-client" {
       };
     }
 
+    /**
+     * Recommends Items that are the most relevant to a particular Segment from a context [Segmentation](https://docs.recombee.com/segmentations.html).
+     * Based on the used Segmentation, this endpoint can be used for example for:
+     * - Recommending articles related to a particular topic
+     * - Recommending songs belonging to a particular genre
+     * - Recommending products produced by a particular brand
+     * You need to set the used context Segmentation in the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.
+     * The returned items are sorted by relevance (the first item being the most relevant).
+     * It is also possible to use the POST HTTP method (for example, in the case of a very long ReQL filter) — query parameters then become body parameters.
+     */
+    export class RecommendItemsToItemSegment extends requests.Request {
+      /**
+       * @param contextSegmentId - ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.
+       * @param targetUserId - ID of the user who will see the recommendations.
+       * Specifying the *targetUserId* is beneficial because:
+       * * It makes the recommendations personalized
+       * * Allows the calculation of Actions and Conversions
+       *   in the graphical user interface,
+       *   as Recombee can pair the user who got recommendations
+       *   and who afterward viewed/purchased an item.
+       * If you insist on not specifying the user, pass `null`
+       * (`None`, `nil`, `NULL` etc., depending on the language) to *targetUserId*.
+       * Do not create some special dummy user for getting recommendations,
+       * as it could mislead the recommendation models,
+       * and result in wrong recommendations.
+       * For anonymous/unregistered users, it is possible to use, for example, their session ID.
+       * @param count - Number of items to be recommended (N for the top-N recommendation).
+       * @param optional - Optional parameters given as an object.
+       */
+      constructor(
+        contextSegmentId: string,
+        targetUserId: string,
+        count: number,
+        optional?: {
+          /** Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". */
+          scenario?: string;
+          /** If an item of the given *itemId* or user of the given *targetUserId* doesn't exist in the database, it creates the missing entity/entities and returns some (non-personalized) recommendations. This allows, for example, rotations in the following recommendations for the user of the given *targetUserId*, as the user will be already known to the system. */
+          cascadeCreate?: boolean;
+          /** With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user.  */
+          returnProperties?: boolean;
+          /** Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. */
+          includedProperties?: string[];
+          /** Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression, which allows you to filter recommended items based on the values of their attributes. */
+          filter?: string;
+          /** Number-returning [ReQL](https://docs.recombee.com/reql.html) expression, which allows you to boost the recommendation rate of some items based on the values of their attributes. */
+          booster?: string;
+          /** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. */
+          logic?: string | object;
+          /** **Expert option** If the *targetUserId* is provided:  Specifies the threshold of how relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend a number of items equal to *count* at any cost. If there is not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations being appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevance and may return less than *count* items when there is not enough data to fulfill it. */
+          minRelevance?: string;
+          /** **Expert option** If the *targetUserId* is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per request in a backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example, `rotationRate=0.2` for only slight rotation of recommended items. */
+          rotationRate?: number;
+          /** **Expert option** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long it takes for an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. */
+          rotationTime?: number;
+          /** Dictionary of custom options. */
+          expertSettings?: { [key: string]: unknown };
+          /** If there is a custom AB-testing running, return the name of the group to which the request belongs. */
+          returnAbGroup?: boolean;
+        }
+      );
+
+      contextSegmentId: string;
+      targetUserId: string;
+      count: number;
+      scenario?: string;
+      cascadeCreate?: boolean;
+      returnProperties?: boolean;
+      includedProperties?: string[];
+      filter?: string;
+      booster?: string;
+      logic?: string | object;
+      minRelevance?: string;
+      rotationRate?: number;
+      rotationTime?: number;
+      expertSettings?: { [key: string]: unknown };
+      returnAbGroup?: boolean;
+      protected __response_type: RecommendationResponse;
+
+      bodyParameters(): {
+        contextSegmentId: string;
+        targetUserId: string;
+        count: number;
+        scenario?: string;
+        cascadeCreate?: boolean;
+        returnProperties?: boolean;
+        includedProperties?: string[];
+        filter?: string;
+        booster?: string;
+        logic?: string | object;
+        minRelevance?: string;
+        rotationRate?: number;
+        rotationTime?: number;
+        expertSettings?: { [key: string]: unknown };
+        returnAbGroup?: boolean;
+      };
+
+      queryParameters(): {
+      };
+    }
+
     /**
      * Full-text personalized search. The results are based on the provided `searchQuery` and also on the user's past interactions (purchases, ratings, etc.) with the items (items more suitable for the user are preferred in the results).
      * All the string and set item properties are indexed by the search engine.

lib/requests/add-series.js

@@ -13,10 +13,17 @@ class AddSeries extends rqs.Request {
   /**
    * Construct the request
    * @param {string} seriesId - ID of the series to be created.
+   * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
+   * - Allowed parameters:
+   *     - *cascadeCreate*
+   *         - Type: boolean
+   *         - Description: If set to `true`, the item will be created with the same ID as the series. Default is `true`.
    */
-  constructor(seriesId) {
+  constructor(seriesId, optional) {
     super('PUT', `/series/${seriesId}`, 3000, false);
     this.seriesId = seriesId;
+    optional = optional || {};
+    this.cascadeCreate = optional.cascadeCreate;
   }
 
   /**
@@ -26,6 +33,9 @@ class AddSeries extends rqs.Request {
   bodyParameters() {
     let params = {};
 
+    if(this.cascadeCreate !== undefined)
+      params.cascadeCreate = this.cascadeCreate;
+
     return params;
   }
 

lib/requests/delete-series.js

@@ -14,10 +14,17 @@ class DeleteSeries extends rqs.Request {
   /**
    * Construct the request
    * @param {string} seriesId - ID of the series to be deleted.
+   * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
+   * - Allowed parameters:
+   *     - *cascadeDelete*
+   *         - Type: boolean
+   *         - Description: If set to `true`, item with the same ID as seriesId will be also deleted. Default is `false`.
    */
-  constructor(seriesId) {
+  constructor(seriesId, optional) {
     super('DELETE', `/series/${seriesId}`, 3000, false);
     this.seriesId = seriesId;
+    optional = optional || {};
+    this.cascadeDelete = optional.cascadeDelete;
   }
 
   /**
@@ -27,6 +34,9 @@ class DeleteSeries extends rqs.Request {
   bodyParameters() {
     let params = {};
 
+    if(this.cascadeDelete !== undefined)
+      params.cascadeDelete = this.cascadeDelete;
+
     return params;
   }
 

lib/requests/index.js

@@ -62,6 +62,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.RecommendItemsToItemSegment = require("./recommend-items-to-item-segment").RecommendItemsToItemSegment;
 exports.SearchItems = require("./search-items").SearchItems;
 exports.SearchItemSegments = require("./search-item-segments").SearchItemSegments;
 exports.AddSearchSynonym = require("./add-search-synonym").AddSearchSynonym;

lib/requests/insert-to-series.js

@@ -20,7 +20,7 @@ class InsertToSeries extends rqs.Request {
    * - Allowed parameters:
    *     - *cascadeCreate*
    *         - Type: boolean
-   *         - Description: Indicates that any non-existing entity specified within the request should be created (as if corresponding PUT requests were invoked). This concerns both the `seriesId` and the `itemId`. If `cascadeCreate` is set to true, the behavior also depends on the `itemType`. Either item or series may be created if not present in the database.
+   *         - Description: Indicates that any non-existing entity specified within the request should be created (as if corresponding PUT requests were invoked). This concerns both the `seriesId` and the `itemId`. If `cascadeCreate` is set to true, the behavior also depends on the `itemType`. In case of `item`, an item is created, in case of `series` a series + corresponding item with the same ID is created.
    */
   constructor(seriesId, itemType, itemId, time, optional) {
     super('POST', `/series/${seriesId}/items/`, 3000, false);

lib/requests/recommend-item-segments-to-item-segment.js

@@ -6,12 +6,12 @@
 const rqs = require("./request");
 
 /**
- * Recommends Segments from a result Segmentation that are the most relevant to a particular Segment from a context Segmentation.
+ * Recommends Segments from a result [Segmentation](https://docs.recombee.com/segmentations.html) that are the most relevant to a particular Segment from a context Segmentation.
  * Based on the used Segmentations, this endpoint can be used for example for:
  *   - Recommending the related brands to particular brand
  *   - Recommending the related brands to particular category
  *   - Recommending the related artists to a particular genre (assuming songs are the Items)
- * You need to set the used context and result Segmentation the Admin UI in the Scenario settings prior to using this endpoint.
+ * You need to set the used context and result Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.
  * The returned segments are sorted by relevance (first segment being the most relevant).
  * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
  */