Skip to content

Commit

Permalink
Release: v5.0.0
Browse files Browse the repository at this point in the history 
- 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
  • Loading branch information
@OndraFiedler
OndraFiedler committed Jan 14, 2025
1 parent fcf2be3 commit 26792c2
Show file tree
Hide file tree
Showing 19 changed files with 577 additions and 155 deletions.
2 changes: 1 addition & 1 deletion lib/api-client.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
};
Expand Down
136 changes: 123 additions & 13 deletions lib/index.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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(): {
Expand All @@ -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(): {
Expand Down Expand Up @@ -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;
}
);
Expand Down Expand Up @@ -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;
};
}

Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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.
Expand Down
12 changes: 11 additions & 1 deletion lib/requests/add-series.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

/**
Expand All @@ -26,6 +33,9 @@ class AddSeries extends rqs.Request {
bodyParameters() {
let params = {};

if(this.cascadeCreate !== undefined)
params.cascadeCreate = this.cascadeCreate;

return params;
}

Expand Down
12 changes: 11 additions & 1 deletion lib/requests/delete-series.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

/**
Expand All @@ -27,6 +34,9 @@ class DeleteSeries extends rqs.Request {
bodyParameters() {
let params = {};

if(this.cascadeDelete !== undefined)
params.cascadeDelete = this.cascadeDelete;

return params;
}

Expand Down
1 change: 1 addition & 0 deletions lib/requests/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion lib/requests/insert-to-series.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
4 changes: 2 additions & 2 deletions lib/requests/recommend-item-segments-to-item-segment.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand Down
Loading

0 comments on commit 26792c2

Please sign in to comment.