recombee-api-client 6.2.0 → 6.3.0

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

package/lib/index.d.ts

@@ -296,9 +296,21 @@ declare module "recombee-api-client" {
     values?: Record<string, EntityProperty>;
   }
 
+  export type PropertyRole = {
+    name: string;
+    settings?: Record<string, unknown>;
+  }
+
+  export type PropertyMetadata = {
+    name: string;
+    settings?: Record<string, unknown>;
+  }
+
   export type PropertyInfo = {
     name: string;
     type: string;
+    role?: PropertyRole;
+    metadata?: PropertyMetadata[];
   }
 
   export type UpdateMoreItemsResponse = {
@@ -563,29 +575,40 @@ declare module "recombee-api-client" {
       /**
        * @param propertyName - Name of the item property to be created. Currently, the following names are reserved: `id`, `itemid`, case-insensitively. Also, the length of the property name must not exceed 63 characters.
        * @param type - Value type of the item property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`, `image` or `imageList`.
-       * * `int`- Signed integer number.
+       * * `int` - Signed integer number.
        * * `double` - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).
        * * `string` - UTF-8 string.
        * * `boolean` - *true* / *false*
-       * * `timestamp` - Value representing date and time.
+       * * `timestamp` - Value representing date and time. ISO8601-1 pattern (string) or UTC epoch time (number).
        * * `set` - Set of strings.
        * * `image` - URL of an image (`jpeg`, `png` or `gif`).
-       * * `imageList` - List of URLs that refer to images. 
+       * * `imageList` - List of URLs that refer to images.
+       * @param optional - Optional parameters given as an object.
        */
       constructor(
         propertyName: string,
         type: string,
+        optional?: {
+          /** [Role](https://docs.recombee.com/api/property_roles_metadata#roles) to assign to the property. */
+          role?: string | object;
+          /** List of [metadata](https://docs.recombee.com/api/property_roles_metadata#metadata) entries to assign to the property. */
+          metadata?: string[];
+        }
       );
 
       propertyName: string;
       type: string;
+      role?: string | object;
+      metadata?: string[];
       protected __response_type: string;
 
       bodyParameters(): {
+        type: string;
+        role?: string | object;
+        metadata?: string[];
       };
 
       queryParameters(): {
-        type: string;
       };
     }
 
@@ -1022,23 +1045,34 @@ declare module "recombee-api-client" {
        * * `double` - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).
        * * `string` - UTF-8 string.
        * * `boolean` - *true* / *false*
-       * * `timestamp` - Value representing date and time.
+       * * `timestamp` - Value representing date and time. ISO8601-1 pattern (string) or UTC epoch time (number).
        * * `set` - Set of strings.
+       * @param optional - Optional parameters given as an object.
        */
       constructor(
         propertyName: string,
         type: string,
+        optional?: {
+          /** [Role](https://docs.recombee.com/api/property_roles_metadata#roles) to assign to the property. */
+          role?: string | object;
+          /** List of [metadata](https://docs.recombee.com/api/property_roles_metadata#metadata) entries to assign to the property. */
+          metadata?: string[];
+        }
       );
 
       propertyName: string;
       type: string;
+      role?: string | object;
+      metadata?: string[];
       protected __response_type: string;
 
       bodyParameters(): {
+        type: string;
+        role?: string | object;
+        metadata?: string[];
       };
 
       queryParameters(): {
-        type: string;
       };
     }
 
@@ -2608,18 +2642,18 @@ declare module "recombee-api-client" {
     }
 
     /**
-     * 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`).
+     * Returns [Item Segments](https://docs.recombee.com/segmentations) to be shown as the next recommendations when a user scrolls (e.g., within a carousel or feed of Item Segments such as brands, artists, topics, or categories).
+     * The request requires the `recommId` of a base recommendation request and the number of Segments to return (`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.
+     * All other parameters are inherited from the base request associated with the provided `recommId`.
+     * This endpoint can be called multiple times for a single `recommId`. Each call returns different Item Segments that have not been recommended in previous calls.
+     * The number of calls made so far is returned in the `numberNextRecommsCalls` field.
+     * Requests can be made up to 30 minutes after the base request or the most recent Recommend Next Item Segments call.
+     * For billing purposes, each call to this endpoint is counted as a separate recommendation request.
      */
     export class RecommendNextItemSegments extends requests.Request {
       /**

package/lib/requests/add-item-property.js

@@ -14,19 +14,30 @@ class AddItemProperty extends rqs.Request {
    * Construct the request
    * @param {string} propertyName - Name of the item property to be created. Currently, the following names are reserved: `id`, `itemid`, case-insensitively. Also, the length of the property name must not exceed 63 characters.
    * @param {string} type - Value type of the item property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`, `image` or `imageList`.
-   * * `int`- Signed integer number.
+   * * `int` - Signed integer number.
    * * `double` - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).
    * * `string` - UTF-8 string.
    * * `boolean` - *true* / *false*
-   * * `timestamp` - Value representing date and time.
+   * * `timestamp` - Value representing date and time. ISO8601-1 pattern (string) or UTC epoch time (number).
    * * `set` - Set of strings.
    * * `image` - URL of an image (`jpeg`, `png` or `gif`).
-   * * `imageList` - List of URLs that refer to images. 
+   * * `imageList` - List of URLs that refer to images.
+   * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
+   * - Allowed parameters:
+   *     - *role*
+   *         - Type: string | object
+   *         - Description: [Role](https://docs.recombee.com/api/property_roles_metadata#roles) to assign to the property.
+   *     - *metadata*
+   *         - Type: string[]
+   *         - Description: List of [metadata](https://docs.recombee.com/api/property_roles_metadata#metadata) entries to assign to the property.
    */
-  constructor(propertyName, type) {
+  constructor(propertyName, type, optional) {
     super('PUT', `/items/properties/${propertyName}`, 100000, false);
     this.propertyName = propertyName;
     this.type = type;
+    optional = optional || {};
+    this.role = optional.role;
+    this.metadata = optional.metadata;
   }
 
   /**
@@ -35,6 +46,13 @@ class AddItemProperty extends rqs.Request {
    */
   bodyParameters() {
     let params = {};
+    params.type = this.type;
+
+    if(this.role !== undefined)
+      params.role = this.role;
+
+    if(this.metadata !== undefined)
+      params.metadata = this.metadata;
 
     return params;
   }
@@ -45,7 +63,6 @@ class AddItemProperty extends rqs.Request {
    */
   queryParameters() {
     let params = {};
-    params.type = this.type;
     return params;
   }
 }

package/lib/requests/add-user-property.js

@@ -18,13 +18,24 @@ class AddUserProperty extends rqs.Request {
    * * `double` - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).
    * * `string` - UTF-8 string.
    * * `boolean` - *true* / *false*
-   * * `timestamp` - Value representing date and time.
+   * * `timestamp` - Value representing date and time. ISO8601-1 pattern (string) or UTC epoch time (number).
    * * `set` - Set of strings.
+   * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
+   * - Allowed parameters:
+   *     - *role*
+   *         - Type: string | object
+   *         - Description: [Role](https://docs.recombee.com/api/property_roles_metadata#roles) to assign to the property.
+   *     - *metadata*
+   *         - Type: string[]
+   *         - Description: List of [metadata](https://docs.recombee.com/api/property_roles_metadata#metadata) entries to assign to the property.
    */
-  constructor(propertyName, type) {
+  constructor(propertyName, type, optional) {
     super('PUT', `/users/properties/${propertyName}`, 100000, false);
     this.propertyName = propertyName;
     this.type = type;
+    optional = optional || {};
+    this.role = optional.role;
+    this.metadata = optional.metadata;
   }
 
   /**
@@ -33,6 +44,13 @@ class AddUserProperty extends rqs.Request {
    */
   bodyParameters() {
     let params = {};
+    params.type = this.type;
+
+    if(this.role !== undefined)
+      params.role = this.role;
+
+    if(this.metadata !== undefined)
+      params.metadata = this.metadata;
 
     return params;
   }
@@ -43,7 +61,6 @@ class AddUserProperty extends rqs.Request {
    */
   queryParameters() {
     let params = {};
-    params.type = this.type;
     return params;
   }
 }

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

@@ -6,18 +6,18 @@
 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`).
+ * Returns [Item Segments](https://docs.recombee.com/segmentations) to be shown as the next recommendations when a user scrolls (e.g., within a carousel or feed of Item Segments such as brands, artists, topics, or categories).
+ * The request requires the `recommId` of a base recommendation request and the number of Segments to return (`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.
+ * All other parameters are inherited from the base request associated with the provided `recommId`.
+ * This endpoint can be called multiple times for a single `recommId`. Each call returns different Item Segments that have not been recommended in previous calls.
+ * The number of calls made so far is returned in the `numberNextRecommsCalls` field.
+ * Requests can be made up to 30 minutes after the base request or the most recent Recommend Next Item Segments call.
+ * For billing purposes, each call to this endpoint is counted as a separate recommendation request.
  */
 class RecommendNextItemSegments extends rqs.Request {
 

package/package.json

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

package/test/add-item-property-batch_test.js

@@ -25,7 +25,11 @@ describe('AddItemProperty', function(){
       new rqs.AddItemProperty('str','string'),
       new rqs.AddItemProperty('prop','integer'),
       new rqs.AddItemProperty('number2','int'),
-      new rqs.AddItemProperty('number2','int')
+      new rqs.AddItemProperty('number2','int'),
+      new rqs.AddItemProperty('title','string',{'role': 'title'}),
+      new rqs.AddItemProperty('str4','string',{'role': 'summary'}),
+      new rqs.AddItemProperty('str4','string',{'role': 'summary'}),
+      new rqs.AddItemProperty('str5','string',{'role': 'titl'})
       ];
     
     env.client.send(new rqs.Batch(requests))
@@ -35,6 +39,10 @@ describe('AddItemProperty', function(){
         assert.equal(responses[2].code, 400);
         assert.equal(responses[3].code, 201);
         assert.equal(responses[4].code, 409);
+        assert.equal(responses[5].code, 201);
+        assert.equal(responses[6].code, 201);
+        assert.equal(responses[7].code, 409);
+        assert.equal(responses[8].code, 404);
       done();
     });
   });

package/test/add-item-property-callback_test.js

@@ -77,4 +77,49 @@ describe('AddItemProperty', function(){
       }
     }));
   });
+  
+  it ('does not fail with valid property role and metadata', (done) => {
+    let req, req2, resp;
+    req = new rqs.AddItemProperty('title','string',{'role': 'title'});
+    env.client.send(req,((err,res) => {
+      if(err) {
+        assert.fail();
+      }
+      else {
+        done();
+      }
+    }));
+  });
+  
+  it ('fails with duplicate property role or invalid metadata', (done) => {
+    let req, req2, resp;
+    req = new rqs.AddItemProperty('str4','string',{'role': 'summary'});
+    env.client.send(req,((err,res) => {
+      if(err) {
+        assert.fail();
+      }
+      else {
+        env.client.send(req,((err,res) => {
+          if(err) {
+            assert.equal(err.name, 'ResponseError');
+            assert.equal(err.statusCode, 409);
+            req = new rqs.AddItemProperty('str5','string',{'role': 'titl'});
+            env.client.send(req,((err,res) => {
+              if(err) {
+                assert.equal(err.name, 'ResponseError');
+                assert.equal(err.statusCode, 404);
+                done();
+              }
+              else {
+                assert.fail();
+              }
+            }));
+          }
+          else {
+            assert.fail();
+          }
+        }));
+      }
+    }));
+  });
 });

package/test/add-item-property-test.js

@@ -69,4 +69,45 @@ describe('AddItemProperty', function(){
       });
     });
   });
+  
+  it ('does not fail with valid property role and metadata', (done) => {
+    let req, req2, resp;
+    req = new rqs.AddItemProperty('title','string',{'role': 'title'});
+    env.client.send(req)
+    .then((res) => {
+      done();
+    });
+  });
+  
+  it ('fails with duplicate property role or invalid metadata', (done) => {
+    let req, req2, resp;
+    req = new rqs.AddItemProperty('str4','string',{'role': 'summary'});
+    env.client.send(req)
+    .then((res) => {
+      env.client.send(req)
+      .then((res) => {
+        assert.fail();
+        req = new rqs.AddItemProperty('str5','string',{'role': 'titl'});
+      env.client.send(req)
+      .then((res) => {
+        assert.fail();
+        done();
+      })
+      .catch((err) => {
+        if (err instanceof recombee.errors.ResponseError) {
+          assert.equal(err.statusCode, 404);
+          done();
+        }
+        throw err;
+      });
+      })
+      .catch((err) => {
+        if (err instanceof recombee.errors.ResponseError) {
+          assert.equal(err.statusCode, 409);
+          done();
+        }
+        throw err;
+      });
+    });
+  });
 });