From 79466ebd7578b97830c524a62e5069845f3de9b1 Mon Sep 17 00:00:00 2001 From: Ondrej Cvacho Date: Sat, 8 Feb 2025 22:40:13 +0100 Subject: [PATCH] Update docs & TS definition --- lib/index.d.ts | 209 +++++++++--------- lib/requests/index.js | 2 +- lib/requests/list-items.js | 4 +- lib/requests/list-users.js | 4 +- .../recommend-items-to-item-segment.js | 4 +- lib/requests/recommend-items-to-item.js | 4 +- lib/requests/recommend-items-to-user.js | 4 +- lib/requests/recommend-next-items.js | 7 +- lib/requests/recommend-users-to-item.js | 4 +- lib/requests/recommend-users-to-user.js | 4 +- lib/requests/search-items.js | 4 +- lib/requests/update-more-items.js | 2 +- 12 files changed, 127 insertions(+), 125 deletions(-) diff --git a/lib/index.d.ts b/lib/index.d.ts index ddf1824..71ae693 100644 --- a/lib/index.d.ts +++ b/lib/index.d.ts @@ -605,7 +605,7 @@ export module "recombee-api-client" { /** * Updates (some) property values of all the items that pass the filter. * Example: *Setting all the items that are older than a week as unavailable* - * ``` + * ```json * { * "filter": "'releaseDate' < now() - 7*24*3600", * "changes": {"available": false} @@ -2001,13 +2001,114 @@ 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(): { + }; + } + /** * Returns items 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 items that shall be returned (`count`). * The base request can be one of: - * - [Recommend items to item](https://docs.recombee.com/api.html#recommend-items-to-item) - * - [Recommend items to user](https://docs.recombee.com/api.html#recommend-items-to-user) - * - [Search items](https://docs.recombee.com/api.html#search-items) + * - [Recommend Items to Item](https://docs.recombee.com/api.html#recommend-items-to-item) + * - [Recommend Items to User](https://docs.recombee.com/api.html#recommend-items-to-user) + * - [Recommend Items to Item Segment](https://docs.recombee.com/api.html#recommend-items-to-item-segment) + * - [Search Items](https://docs.recombee.com/api.html#search-items) * All the other parameters are inherited from the base request. * *Recommend next items* can be called many times for a single `recommId` and each call returns different (previously not recommended) items. * The number of *Recommend next items* calls performed so far is returned in the `numberNextRecommsCalls` field. @@ -2412,106 +2513,6 @@ 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. diff --git a/lib/requests/index.js b/lib/requests/index.js index 924ae4e..5951a3a 100644 --- a/lib/requests/index.js +++ b/lib/requests/index.js @@ -56,13 +56,13 @@ exports.ListItemViewPortions = require("./list-item-view-portions").ListItemView exports.ListUserViewPortions = require("./list-user-view-portions").ListUserViewPortions; exports.RecommendItemsToUser = require("./recommend-items-to-user").RecommendItemsToUser; exports.RecommendItemsToItem = require("./recommend-items-to-item").RecommendItemsToItem; +exports.RecommendItemsToItemSegment = require("./recommend-items-to-item-segment").RecommendItemsToItemSegment; exports.RecommendNextItems = require("./recommend-next-items").RecommendNextItems; exports.RecommendUsersToUser = require("./recommend-users-to-user").RecommendUsersToUser; exports.RecommendUsersToItem = require("./recommend-users-to-item").RecommendUsersToItem; 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; diff --git a/lib/requests/list-items.js b/lib/requests/list-items.js index c39f308..8461aab 100644 --- a/lib/requests/list-items.js +++ b/lib/requests/list-items.js @@ -27,7 +27,7 @@ class ListItems extends rqs.Request { * - Type: boolean * - Description: With `returnProperties=true`, property values of the listed items are returned along with their IDs in a JSON dictionary. * Example response: - * ``` + * ```json * [ * { * "itemId": "tv-178", @@ -49,7 +49,7 @@ class ListItems extends rqs.Request { * - Type: string[] * - Description: Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. * Example response for `includedProperties=description,price`: - * ``` + * ```json * [ * { * "itemId": "tv-178", diff --git a/lib/requests/list-users.js b/lib/requests/list-users.js index e4f7936..654badd 100644 --- a/lib/requests/list-users.js +++ b/lib/requests/list-users.js @@ -27,7 +27,7 @@ class ListUsers extends rqs.Request { * - Type: boolean * - Description: With `returnProperties=true`, property values of the listed users are returned along with their IDs in a JSON dictionary. * Example response: - * ``` + * ```json * [ * { * "userId": "user-81", @@ -45,7 +45,7 @@ class ListUsers extends rqs.Request { * - Type: string[] * - Description: Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. * Example response for `includedProperties=country`: - * ``` + * ```json * [ * { * "userId": "user-81", diff --git a/lib/requests/recommend-items-to-item-segment.js b/lib/requests/recommend-items-to-item-segment.js index 365f96b..002a12e 100644 --- a/lib/requests/recommend-items-to-item-segment.js +++ b/lib/requests/recommend-items-to-item-segment.js @@ -48,7 +48,7 @@ class RecommendItemsToItemSegment extends rqs.Request { * - Type: boolean * - Description: 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. * Example response: - * ``` + * ```json * { * "recommId": "0c6189e7-dc1a-429a-b613-192696309361", * "recomms": @@ -79,7 +79,7 @@ class RecommendItemsToItemSegment extends rqs.Request { * - Type: string[] * - Description: Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. * Example response for `includedProperties=description,price`: - * ``` + * ```json * { * "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80", * "recomms": diff --git a/lib/requests/recommend-items-to-item.js b/lib/requests/recommend-items-to-item.js index b81e34d..3ace398 100644 --- a/lib/requests/recommend-items-to-item.js +++ b/lib/requests/recommend-items-to-item.js @@ -46,7 +46,7 @@ class RecommendItemsToItem extends rqs.Request { * - Type: boolean * - Description: 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. * Example response: - * ``` + * ```json * { * "recommId": "0c6189e7-dc1a-429a-b613-192696309361", * "recomms": @@ -77,7 +77,7 @@ class RecommendItemsToItem extends rqs.Request { * - Type: string[] * - Description: Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. * Example response for `includedProperties=description,price`: - * ``` + * ```json * { * "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80", * "recomms": diff --git a/lib/requests/recommend-items-to-user.js b/lib/requests/recommend-items-to-user.js index 3430a4f..810004b 100644 --- a/lib/requests/recommend-items-to-user.js +++ b/lib/requests/recommend-items-to-user.js @@ -34,7 +34,7 @@ class RecommendItemsToUser extends rqs.Request { * - Type: boolean * - Description: 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. * Example response: - * ``` + * ```json * { * "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", * "recomms": @@ -65,7 +65,7 @@ class RecommendItemsToUser extends rqs.Request { * - Type: string[] * - Description: Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. * Example response for `includedProperties=description,price`: - * ``` + * ```json * { * "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b", * "recomms": diff --git a/lib/requests/recommend-next-items.js b/lib/requests/recommend-next-items.js index 58f1b8f..5238539 100644 --- a/lib/requests/recommend-next-items.js +++ b/lib/requests/recommend-next-items.js @@ -9,9 +9,10 @@ const rqs = require("./request"); * Returns items 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 items that shall be returned (`count`). * The base request can be one of: - * - [Recommend items to item](https://docs.recombee.com/api.html#recommend-items-to-item) - * - [Recommend items to user](https://docs.recombee.com/api.html#recommend-items-to-user) - * - [Search items](https://docs.recombee.com/api.html#search-items) + * - [Recommend Items to Item](https://docs.recombee.com/api.html#recommend-items-to-item) + * - [Recommend Items to User](https://docs.recombee.com/api.html#recommend-items-to-user) + * - [Recommend Items to Item Segment](https://docs.recombee.com/api.html#recommend-items-to-item-segment) + * - [Search Items](https://docs.recombee.com/api.html#search-items) * All the other parameters are inherited from the base request. * *Recommend next items* can be called many times for a single `recommId` and each call returns different (previously not recommended) items. * The number of *Recommend next items* calls performed so far is returned in the `numberNextRecommsCalls` field. diff --git a/lib/requests/recommend-users-to-item.js b/lib/requests/recommend-users-to-item.js index 61869e7..929fad6 100644 --- a/lib/requests/recommend-users-to-item.js +++ b/lib/requests/recommend-users-to-item.js @@ -30,7 +30,7 @@ class RecommendUsersToItem extends rqs.Request { * - Type: boolean * - Description: With `returnProperties=true`, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended users. * Example response: - * ``` + * ```json * { * "recommId": "039b71dc-b9cc-4645-a84f-62b841eecfce", * "recomms": @@ -57,7 +57,7 @@ class RecommendUsersToItem extends rqs.Request { * - Type: string[] * - Description: Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. * Example response for `includedProperties=country`: - * ``` + * ```json * { * "recommId": "b2b355dd-972a-4728-9c6b-2dc229db0678", * "recomms": diff --git a/lib/requests/recommend-users-to-user.js b/lib/requests/recommend-users-to-user.js index 5f65096..6bcaf1f 100644 --- a/lib/requests/recommend-users-to-user.js +++ b/lib/requests/recommend-users-to-user.js @@ -30,7 +30,7 @@ class RecommendUsersToUser extends rqs.Request { * - Type: boolean * - Description: With `returnProperties=true`, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended users. * Example response: - * ``` + * ```json * { * "recommId": "9cb9c55d-50ba-4478-84fd-ab456136156e", * "recomms": @@ -57,7 +57,7 @@ class RecommendUsersToUser extends rqs.Request { * - Type: string[] * - Description: Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. * Example response for `includedProperties=country`: - * ``` + * ```json * { * "recommId": "b326d82d-5d57-4b45-b362-c9d6f0895855", * "recomms": diff --git a/lib/requests/search-items.js b/lib/requests/search-items.js index 12dde69..9cac9d0 100644 --- a/lib/requests/search-items.js +++ b/lib/requests/search-items.js @@ -36,7 +36,7 @@ class SearchItems extends rqs.Request { * - Type: boolean * - Description: 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. * Example response: - * ``` + * ```json * { * "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", * "recomms": @@ -67,7 +67,7 @@ class SearchItems extends rqs.Request { * - Type: string[] * - Description: Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. * Example response for `includedProperties=description,price`: - * ``` + * ```json * { * "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b", * "recomms": diff --git a/lib/requests/update-more-items.js b/lib/requests/update-more-items.js index 2b47438..9c45f1c 100644 --- a/lib/requests/update-more-items.js +++ b/lib/requests/update-more-items.js @@ -8,7 +8,7 @@ const rqs = require("./request"); /** * Updates (some) property values of all the items that pass the filter. * Example: *Setting all the items that are older than a week as unavailable* - * ``` + * ```json * { * "filter": "'releaseDate' < now() - 7*24*3600", * "changes": {"available": false}