Skip to content

Commit 6e59dd8

Browse files
OndraFiedlerOndraFiedler
committed
Release: v6.0.0
- Added support for the new Composite Recommendation endpoint - Added new parameter `autoPresented` for Detail View and View Portion interactions - Added new parameter `timeSpent` for View Portion interactions - Added support for `reqlExpressions` on recommended items
1 parent fd526b1 commit 6e59dd8

File tree

253 files changed

+1897
-1182
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

253 files changed

+1897
-1182
lines changed

‎lib/api-client.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ class ApiClient {
4343
method: request.method,
4444
headers: {'Accept': 'application/json',
4545
'Content-Type': 'application/json',
46-
'User-Agent': 'recombee-node-api-client/5.1.1'},
46+
'User-Agent': 'recombee-node-api-client/6.0.0'},
4747
timeout: request.timeout,
4848
agent: this.options.agent
4949
};

‎lib/index.d.ts‎

Lines changed: 180 additions & 53 deletions
Large diffs are not rendered by default.

‎lib/requests/add-detail-view.js‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,9 @@ class AddDetailView extends rqs.Request {
3131
* - *additionalData*
3232
* - Type: object
3333
* - Description: A dictionary of additional data for the interaction.
34+
* - *autoPresented*
35+
* - Type: boolean
36+
* - Description: Indicates whether the item was automatically presented to the user (e.g., in a swiping feed) or explicitly requested by the user (e.g., by clicking on a link). Defaults to `false`.
3437
*/
3538
constructor(userId, itemId, optional) {
3639
super('POST', '/detailviews/', 3000, false);
@@ -42,6 +45,7 @@ class AddDetailView extends rqs.Request {
4245
this.cascadeCreate = optional.cascadeCreate;
4346
this.recommId = optional.recommId;
4447
this.additionalData = optional.additionalData;
48+
this.autoPresented = optional.autoPresented;
4549
}
4650

4751
/**
@@ -68,6 +72,9 @@ class AddDetailView extends rqs.Request {
6872
if(this.additionalData !== undefined)
6973
params.additionalData = this.additionalData;
7074

75+
if(this.autoPresented !== undefined)
76+
params.autoPresented = this.autoPresented;
77+
7178
return params;
7279
}
7380

‎lib/requests/composite-recommendation.js‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
/*
2+
This file is auto-generated, do not edit
3+
*/
4+
5+
'use strict';
6+
const rqs = require("./request");
7+
8+
/**
9+
* 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.
10+
* 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>*.
11+
* See detailed **examples and configuration guidance** in the [Composite Scenarios documentation](https://docs.recombee.com/scenarios#composite-recommendations).
12+
* **Structure**
13+
* The endpoint operates in two stages:
14+
* 1. Recommends the *source* (e.g., an Item Segment or item) to the user.
15+
* 2. Recommends *results* (items or Item Segments) related to that *source*.
16+
* For example, *Articles from <category>* can be decomposed into:
17+
* - [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-item-segments-to-user) to find the category.
18+
* - [Recommend Items To Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment) to recommend articles from that category.
19+
* Since the first step uses [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-items-to-user), you must include the `userId` parameter in the *Composite Recommendation* request.
20+
* Each *Composite Recommendation* counts as a single recommendation API request for billing.
21+
* **Stage-specific Parameters**
22+
* Additional parameters can be supplied via [sourceSettings](https://docs.recombee.com/api#composite-recommendation-param-sourceSettings) and [resultSettings](https://docs.recombee.com/api#composite-recommendation-param-resultSettings).
23+
* In the example above:
24+
* - `sourceSettings` may include any parameter valid for [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-items-to-user) (e.g., `filter`, `booster`).
25+
* - `resultSettings` may include any parameter valid for [Recommend Items To Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment).
26+
* See [this example](https://docs.recombee.com/api#composite-recommendation-example-setting-parameters-for-individual-stages) for more details.
27+
*/
28+
class CompositeRecommendation extends rqs.Request {
29+
30+
/**
31+
* Construct the request
32+
* @param {string} scenario - Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
33+
* You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.
34+
* The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.
35+
* @param {number} count - Number of items to be recommended (N for the top-N recommendation).
36+
* @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
37+
* - Allowed parameters:
38+
* - *itemId*
39+
* - Type: string
40+
* - Description: ID of the item for which the recommendations are to be generated.
41+
* - *userId*
42+
* - Type: string
43+
* - Description: ID of the user for which the recommendations are to be generated.
44+
* - *logic*
45+
* - Type: string | object
46+
* - Description: Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
47+
* See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.
48+
* The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
49+
* Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).
50+
* - *segmentId*
51+
* - Type: string
52+
* - Description: ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.
53+
* - *cascadeCreate*
54+
* - Type: boolean
55+
* - 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.
56+
* - *sourceSettings*
57+
* - Type: object
58+
* - Description: Parameters applied for recommending the *Source* stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the *Source*.
59+
* - *resultSettings*
60+
* - Type: object
61+
* - Description: Parameters applied for recommending the *Result* stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the *Result*.
62+
* - *expertSettings*
63+
* - Type: object
64+
* - Description: Dictionary of custom options.
65+
*/
66+
constructor(scenario, count, optional) {
67+
super('POST', '/recomms/composite/', 3000, false);
68+
this.scenario = scenario;
69+
this.count = count;
70+
optional = optional || {};
71+
this.itemId = optional.itemId;
72+
this.userId = optional.userId;
73+
this.logic = optional.logic;
74+
this.segmentId = optional.segmentId;
75+
this.cascadeCreate = optional.cascadeCreate;
76+
this.sourceSettings = optional.sourceSettings;
77+
this.resultSettings = optional.resultSettings;
78+
this.expertSettings = optional.expertSettings;
79+
}
80+
81+
/**
82+
* Get body parameters
83+
* @return {Object} The values of body parameters (name of parameter: value of the parameter)
84+
*/
85+
bodyParameters() {
86+
let params = {};
87+
params.scenario = this.scenario;
88+
params.count = this.count;
89+
90+
if(this.itemId !== undefined)
91+
params.itemId = this.itemId;
92+
93+
if(this.userId !== undefined)
94+
params.userId = this.userId;
95+
96+
if(this.logic !== undefined)
97+
params.logic = this.logic;
98+
99+
if(this.segmentId !== undefined)
100+
params.segmentId = this.segmentId;
101+
102+
if(this.cascadeCreate !== undefined)
103+
params.cascadeCreate = this.cascadeCreate;
104+
105+
if(this.sourceSettings !== undefined)
106+
params.sourceSettings = this.sourceSettings;
107+
108+
if(this.resultSettings !== undefined)
109+
params.resultSettings = this.resultSettings;
110+
111+
if(this.expertSettings !== undefined)
112+
params.expertSettings = this.expertSettings;
113+
114+
return params;
115+
}
116+
117+
/**
118+
* Get query parameters
119+
* @return {Object} The values of query parameters (name of parameter: value of the parameter)
120+
*/
121+
queryParameters() {
122+
let params = {};
123+
return params;
124+
}
125+
}
126+
127+
exports.CompositeRecommendation = CompositeRecommendation

‎lib/requests/index.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ exports.RecommendUsersToItem = require("./recommend-users-to-item").RecommendUse
6363
exports.RecommendItemSegmentsToUser = require("./recommend-item-segments-to-user").RecommendItemSegmentsToUser;
6464
exports.RecommendItemSegmentsToItem = require("./recommend-item-segments-to-item").RecommendItemSegmentsToItem;
6565
exports.RecommendItemSegmentsToItemSegment = require("./recommend-item-segments-to-item-segment").RecommendItemSegmentsToItemSegment;
66+
exports.CompositeRecommendation = require("./composite-recommendation").CompositeRecommendation;
6667
exports.SearchItems = require("./search-items").SearchItems;
6768
exports.SearchItemSegments = require("./search-item-segments").SearchItemSegments;
6869
exports.AddSearchSynonym = require("./add-search-synonym").AddSearchSynonym;

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

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,44 @@ class RecommendItemsToItemSegment extends rqs.Request {
116116
* See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.
117117
* The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
118118
* Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).
119+
* - *reqlExpressions*
120+
* - Type: object
121+
* - Description: A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item.
122+
* This can be used to compute additional properties of the recommended items that are not stored in the database.
123+
* The keys are the names of the expressions, and the values are the actual ReQL expressions.
124+
* Example request:
125+
* ```json
126+
* {
127+
* "reqlExpressions": {
128+
* "isInUsersCity": "context_user[\"city\"] in 'cities'",
129+
* "distanceToUser": "earth_distance('location', context_user[\"location\"])"
130+
* }
131+
* }
132+
* ```
133+
* Example response:
134+
* ```json
135+
* {
136+
* "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
137+
* "recomms":
138+
* [
139+
* {
140+
* "id": "restaurant-178",
141+
* "reqlEvaluations": {
142+
* "isInUsersCity": true,
143+
* "distanceToUser": 5200.2
144+
* }
145+
* },
146+
* {
147+
* "id": "bar-42",
148+
* "reqlEvaluations": {
149+
* "isInUsersCity": false,
150+
* "distanceToUser": 2516.0
151+
* }
152+
* }
153+
* ],
154+
* "numberNextRecommsCalls": 0
155+
* }
156+
* ```
119157
* - *minRelevance*
120158
* - Type: string
121159
* - Description: **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.
@@ -145,6 +183,7 @@ class RecommendItemsToItemSegment extends rqs.Request {
145183
this.filter = optional.filter;
146184
this.booster = optional.booster;
147185
this.logic = optional.logic;
186+
this.reqlExpressions = optional.reqlExpressions;
148187
this.minRelevance = optional.minRelevance;
149188
this.rotationRate = optional.rotationRate;
150189
this.rotationTime = optional.rotationTime;
@@ -183,6 +222,9 @@ class RecommendItemsToItemSegment extends rqs.Request {
183222
if(this.logic !== undefined)
184223
params.logic = this.logic;
185224

225+
if(this.reqlExpressions !== undefined)
226+
params.reqlExpressions = this.reqlExpressions;
227+
186228
if(this.minRelevance !== undefined)
187229
params.minRelevance = this.minRelevance;
188230

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

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,47 @@ class RecommendItemsToItem extends rqs.Request {
114114
* See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.
115115
* The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
116116
* Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).
117+
* - *reqlExpressions*
118+
* - Type: object
119+
* - Description: A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item.
120+
* This can be used to compute additional properties of the recommended items that are not stored in the database.
121+
* The keys are the names of the expressions, and the values are the actual ReQL expressions.
122+
* Example request:
123+
* ```json
124+
* {
125+
* "reqlExpressions": {
126+
* "isInUsersCity": "context_user[\"city\"] in 'cities'",
127+
* "distanceToUser": "earth_distance('location', context_user[\"location\"])",
128+
* "isFromSameCompany": "'company' == context_item[\"company\"]"
129+
* }
130+
* }
131+
* ```
132+
* Example response:
133+
* ```json
134+
* {
135+
* "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
136+
* "recomms":
137+
* [
138+
* {
139+
* "id": "restaurant-178",
140+
* "reqlEvaluations": {
141+
* "isInUsersCity": true,
142+
* "distanceToUser": 5200.2,
143+
* "isFromSameCompany": false
144+
* }
145+
* },
146+
* {
147+
* "id": "bar-42",
148+
* "reqlEvaluations": {
149+
* "isInUsersCity": false,
150+
* "distanceToUser": 2516.0,
151+
* "isFromSameCompany": true
152+
* }
153+
* }
154+
* ],
155+
* "numberNextRecommsCalls": 0
156+
* }
157+
* ```
117158
* - *userImpact*
118159
* - Type: number
119160
* - Description: **Expert option:** If *targetUserId* parameter is present, the recommendations are biased towards the given user. Using *userImpact*, you may control this bias. For an extreme case of `userImpact=0.0`, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for `userImpact=1.0`, you'll get a user-based recommendation. The default value is `0`.
@@ -149,6 +190,7 @@ class RecommendItemsToItem extends rqs.Request {
149190
this.filter = optional.filter;
150191
this.booster = optional.booster;
151192
this.logic = optional.logic;
193+
this.reqlExpressions = optional.reqlExpressions;
152194
this.userImpact = optional.userImpact;
153195
this.diversity = optional.diversity;
154196
this.minRelevance = optional.minRelevance;
@@ -188,6 +230,9 @@ class RecommendItemsToItem extends rqs.Request {
188230
if(this.logic !== undefined)
189231
params.logic = this.logic;
190232

233+
if(this.reqlExpressions !== undefined)
234+
params.reqlExpressions = this.reqlExpressions;
235+
191236
if(this.userImpact !== undefined)
192237
params.userImpact = this.userImpact;
193238

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

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,44 @@ class RecommendItemsToUser extends rqs.Request {
102102
* See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.
103103
* The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
104104
* Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).
105+
* - *reqlExpressions*
106+
* - Type: object
107+
* - Description: A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item.
108+
* This can be used to compute additional properties of the recommended items that are not stored in the database.
109+
* The keys are the names of the expressions, and the values are the actual ReQL expressions.
110+
* Example request:
111+
* ```json
112+
* {
113+
* "reqlExpressions": {
114+
* "isInUsersCity": "context_user[\"city\"] in 'cities'",
115+
* "distanceToUser": "earth_distance('location', context_user[\"location\"])"
116+
* }
117+
* }
118+
* ```
119+
* Example response:
120+
* ```json
121+
* {
122+
* "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
123+
* "recomms":
124+
* [
125+
* {
126+
* "id": "restaurant-178",
127+
* "reqlEvaluations": {
128+
* "isInUsersCity": true,
129+
* "distanceToUser": 5200.2
130+
* }
131+
* },
132+
* {
133+
* "id": "bar-42",
134+
* "reqlEvaluations": {
135+
* "isInUsersCity": false,
136+
* "distanceToUser": 2516.0
137+
* }
138+
* }
139+
* ],
140+
* "numberNextRecommsCalls": 0
141+
* }
142+
* ```
105143
* - *diversity*
106144
* - Type: number
107145
* - Description: **Expert option:** Real number from [0.0, 1.0], which determines how mutually dissimilar the recommended items should be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification.
@@ -133,6 +171,7 @@ class RecommendItemsToUser extends rqs.Request {
133171
this.filter = optional.filter;
134172
this.booster = optional.booster;
135173
this.logic = optional.logic;
174+
this.reqlExpressions = optional.reqlExpressions;
136175
this.diversity = optional.diversity;
137176
this.minRelevance = optional.minRelevance;
138177
this.rotationRate = optional.rotationRate;
@@ -170,6 +209,9 @@ class RecommendItemsToUser extends rqs.Request {
170209
if(this.logic !== undefined)
171210
params.logic = this.logic;
172211

212+
if(this.reqlExpressions !== undefined)
213+
params.reqlExpressions = this.reqlExpressions;
214+
173215
if(this.diversity !== undefined)
174216
params.diversity = this.diversity;
175217

0 commit comments

Comments
 (0)