20 |
21 | ## ✨ Features
22 |
23 | - Thin JavaScript wrapper around the Recombee API
24 | - Supported endpoints: [Interactions](https://docs.recombee.com/api#user-item-interactions), [Recommendations](https://docs.recombee.com/api#recommendations) & [Search](https://docs.recombee.com/api#search)
25 | - UMD-compatible
26 | - TypeScript definitions included
27 |
28 | ## 🚀 Getting Started
29 |
30 | There are two ways to include the library in your project:
31 |
32 | ### 🔌 Install via code snippet
33 |
34 | You can add the following `
38 | ```
39 |
40 | After this script is included, you can access the client using the global `recombee` object (also available as `window.recombee`).
41 |
42 | ### 📦 Install via package manager
43 |
44 | If you prefer, you can also use a package manager:
45 |
46 | ```sh
47 | npm install recombee-js-api-client
48 | # or
49 | yarn add recombee-js-api-client
50 | # or
51 | pnpm add recombee-js-api-client
52 | # or
53 | bun add recombee-js-api-client
54 | ```
55 |
56 | Afterwards, you can import the `recombee` object:
57 |
58 | ```js
59 | import recombee from 'recombee-js-api-client'
60 | ```
61 |
62 | ### 🏗️ Example
63 |
64 | With the `recombee` object, you can send user-item interactions and receive recommendations as follows:
65 |
66 | ```js
67 | // Initialize the API client with the ID of your database and the associated PUBLIC token
68 | export const client = new recombee.ApiClient(
69 | 'database-id',
70 | '...db-public-token...',
71 | {
72 | // the region of your database (default: 'eu-west')
73 | region: 'us-west',
74 | },
75 | );
76 |
77 | // Send interactions
78 | client.send(
79 | new recombee.AddDetailView('user-4395', 'item-129', {
80 | cascadeCreate: true,
81 | recommId: '23eaa09b-0e24-4487-ba9c-8e255feb01bb',
82 | }),
83 | );
84 |
85 | // Request recommendations
86 | client
87 | .send(
88 | new recombee.RecommendItemsToItem('item-356', 'user-13434', 5, {
89 | returnProperties: true,
90 | includedProperties: ['title'],
91 | }),
92 | )
93 | .then((response) => {
94 | // `recommId` needs to be sent with interactions based on recommendations
95 | console.log(response.recommId);
96 |
97 | // The `recomms` object contains the `id` (and `values` if `returnProperties` is true)
98 | response.recomms.forEach((item) => {
99 | console.log(`ID: ${item.id}, Title: ${item.values.title}`);
100 | });
101 | })
102 | .catch((error) => {
103 | console.log(error);
104 | // use fallback...
105 | });
106 | ```
107 |
108 | ## 📝 Documentation
109 |
110 | Discover the full [JavaScript API Client documentation](https://docs.recombee.com/js_client) for comprehensive guides and examples.
111 |
112 | For a complete breakdown of all endpoints and their responses, check out our [API Reference](https://docs.recombee.com/api).
113 |
114 | ## 🤝 Contributing
115 |
116 | We welcome all contributions—whether it’s fixing a bug, improving documentation, or suggesting a new feature.
117 |
118 | To contribute, simply fork the repository, make your changes, and submit a pull request. Be sure to provide a clear description of your changes.
119 |
120 | Thanks for helping make this project better!
121 |
122 | ## 🔧 Troubleshooting
123 |
124 | Are you having issues? We recommend checking [our documentation](https://docs.recombee.com/js_client) to see if it contains a possible solution.
125 |
126 | If you want to reach out, you can either [open a GitHub issue](https://github.com/recombee/js-api-client/issues/new) or send an email to support@recombee.com.
127 |
128 | ## 📄 License
129 |
130 | The Recombee JavaScript API Client is provided under the [MIT License](https://opensource.org/licenses/MIT).
131 |
--------------------------------------------------------------------------------
/eslint.config.mjs:
--------------------------------------------------------------------------------
1 | import globals from 'globals';
2 | import tseslint from 'typescript-eslint';
3 |
4 | /** @type {import('eslint').Linter.Config[]} */
5 | export default tseslint.config({
6 | ignores: ['dist/*'],
7 | files: ['**/*.{js,mjs,cjs,ts}'],
8 | languageOptions: { globals: globals.browser },
9 | extends: [tseslint.configs.recommended],
10 | rules: {
11 | '@typescript-eslint/no-require-imports': 'off',
12 | '@typescript-eslint/no-empty-object-type': 'off',
13 | 'no-var': 'warn',
14 | 'prefer-const': 'warn',
15 | },
16 | });
17 |
--------------------------------------------------------------------------------
/examples/product_img.svg:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/examples/related_products.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/recombee/js-api-client/6c4ac8555e08997bfff604204ff090a74bcc9e0f/examples/related_products.png
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "recombee-js-api-client",
3 | "version": "5.0.2",
4 | "description": "Client-side js library for easy use of the Recombee recommendation API",
5 | "main": "./src/index.js",
6 | "browser": "./src/index.js",
7 | "types": "src/index.d.ts",
8 | "files": [
9 | "src",
10 | "dist"
11 | ],
12 | "repository": {
13 | "type": "git",
14 | "url": "git+https://github.com/Recombee/js-api-client.git"
15 | },
16 | "keywords": [
17 | "recombee",
18 | "recommendation engine",
19 | "recommender engine",
20 | "recommender as a service",
21 | "machine learning",
22 | "API",
23 | "SDK"
24 | ],
25 | "author": "Ondrej Fiedler (https://www.recombee.com/)",
26 | "license": "MIT",
27 | "bugs": {
28 | "url": "https://github.com/Recombee/js-api-client/issues"
29 | },
30 | "homepage": "https://github.com/Recombee/js-api-client#readme",
31 | "dependencies": {
32 | "jssha": "3.3.1"
33 | },
34 | "devDependencies": {
35 | "@babel/core": "7.26.0",
36 | "@babel/preset-env": "7.26.0",
37 | "babel-loader": "9.2.1",
38 | "eslint": "9.21.0",
39 | "globals": "15.13.0",
40 | "prettier": "3.5.3",
41 | "qunit": "2.23.1",
42 | "typescript": "5.8.2",
43 | "typescript-eslint": "8.26.0",
44 | "webpack": "5.97.1",
45 | "webpack-cli": "5.1.4",
46 | "webpack-node-externals": "3.0.0",
47 | "webpack-sources": "3.2.3"
48 | },
49 | "scripts": {
50 | "build": "webpack",
51 | "lint": "tsc; eslint .; prettier --check .",
52 | "lint:fix": "tsc && eslint . --fix && prettier --write .",
53 | "test": "pnpm run build && open ./tests/index.html"
54 | }
55 | }
56 |
--------------------------------------------------------------------------------
/src/api-client.js:
--------------------------------------------------------------------------------
1 | 'use strict';
2 |
3 | const jsSHA = require('jssha');
4 | const api_errors = require('./errors');
5 |
6 | /**
7 | * Client for sending requests to Recombee and getting replies
8 | */
9 | class ApiClient {
10 | /**
11 | * Construct the client
12 | * @param {string} databaseId - ID of your database
13 | * @param {string} publicToken - Corresponding public token
14 | * @param {Object} options - Other custom options
15 | */
16 | constructor(databaseId, publicToken, options) {
17 | this.databaseId = databaseId;
18 | this.publicToken = publicToken;
19 | this.options = options || {};
20 | this.baseUri = this._getBaseUri();
21 | this.useHttps = 'useHttps' in this.options ? this.options.useHttps : true;
22 | this.async = 'async' in this.options ? this.options.async : true;
23 | this.future_v6_fetch = 'future_v6_fetch' in this.options ? this.options.future_v6_fetch : false;
24 | }
25 |
26 | _getRegionalBaseUri(region) {
27 | const uri = {
28 | 'ap-se': 'client-rapi-ap-se.recombee.com',
29 | 'ca-east': 'client-rapi-ca-east.recombee.com',
30 | 'eu-west': 'client-rapi-eu-west.recombee.com',
31 | 'us-west': 'client-rapi-us-west.recombee.com',
32 | }[region.toLowerCase()];
33 |
34 | if (uri === undefined) {
35 | throw new Error(
36 | `Region "${region}" is unknown. You may need to update the version of the SDK.`,
37 | );
38 | }
39 |
40 | return uri;
41 | }
42 |
43 | _getBaseUri() {
44 | let baseUri = this.options.baseUri;
45 | if (this.options.region) {
46 | if (baseUri) {
47 | throw new Error('baseUri and region cannot be specified at the same time');
48 | }
49 | baseUri = this._getRegionalBaseUri(this.options.region);
50 | }
51 | return baseUri || 'client-rapi.recombee.com';
52 | }
53 |
54 | /**
55 | * Send the request to Recombee
56 | * @param {Request} request - Request to be sent
57 | * @param {Object} callback - Optional callback (send returns Promise if omitted)
58 | */
59 | send(request, callback) {
60 | if (this.future_v6_fetch) {
61 | if (!(typeof globalThis === 'undefined' ? window.Promise : globalThis.Promise)) {
62 | throw new Error('future_v6_fetch requires Promises to be available.');
63 | }
64 | if (!this.async) {
65 | throw new Error('future_v6_fetch cannot be used with synchronous requests.');
66 | }
67 | if (callback === undefined) {
68 | return this._sendFetch(request);
69 | } else {
70 | return this._sendFetch(request)
71 | .then((result) => callback(null, result))
72 | .catch(callback);
73 | }
74 | }
75 | return this._sendXhr(request, callback);
76 | }
77 |
78 | async _sendFetch(request) {
79 | const url = this._getUrl(request);
80 | try {
81 | const response = await fetch(url, {
82 | method: 'POST',
83 | headers: {
84 | Accept: 'application/json',
85 | 'Content-Type': 'application/json',
86 | },
87 | body: JSON.stringify(request.bodyParameters()),
88 | signal: AbortSignal.timeout(request.timeout),
89 | });
90 |
91 | if (response.ok) {
92 | return await response.json();
93 | } else {
94 | throw new api_errors.ResponseError(request, response.status, await response.text());
95 | }
96 | } catch (err) {
97 | if (err.name === 'TimeoutError') {
98 | throw new api_errors.TimeoutError(request);
99 | } else {
100 | throw err;
101 | }
102 | }
103 | }
104 |
105 | _sendXhr(request, callback) {
106 | const Promise = typeof globalThis === 'undefined' ? window.Promise : globalThis.Promise;
107 | if (callback === undefined && Promise) {
108 | const sendXhr = this._sendXhr.bind(this);
109 | return new Promise(function (resolve, reject) {
110 | sendXhr(request, function (err, result) {
111 | return err ? reject(err) : resolve(result);
112 | });
113 | });
114 | }
115 |
116 | const url = this._getUrl(request);
117 | const xmlhttp = new XMLHttpRequest();
118 | xmlhttp.open('POST', url, this.async);
119 | xmlhttp.setRequestHeader('Accept', 'application/json');
120 | xmlhttp.setRequestHeader('Content-Type', 'application/json');
121 |
122 | if (this.async) xmlhttp.timeout = request.timeout;
123 |
124 | xmlhttp.onreadystatechange = function () {
125 | if (this.readyState == 4 && this.responseText) {
126 | if (this.status == 200) {
127 | if (callback) return callback(null, JSON.parse(this.responseText));
128 | } else {
129 | if (callback)
130 | return callback(new api_errors.ResponseError(request, this.status, this.responseText));
131 | }
132 | }
133 | };
134 | xmlhttp.ontimeout = function () {
135 | if (callback) return callback(new api_errors.TimeoutError(request));
136 | };
137 |
138 | xmlhttp.send(JSON.stringify(request.bodyParameters()));
139 | }
140 |
141 | _getUrl(request) {
142 | const signedUrl = this._signUrl(request.path);
143 | const url =
144 | (this.useHttps || request.ensureHttps ? 'https://' : 'http://') + this.baseUri + signedUrl;
145 | return url;
146 | }
147 |
148 | _signUrl(req_part) {
149 | let url = '/' + this.databaseId + req_part;
150 | url +=
151 | (req_part.indexOf('?') == -1 ? '?' : '&') +
152 | 'frontend_timestamp=' +
153 | parseInt(new Date().getTime() / 1000);
154 |
155 | const shaObj = new jsSHA('SHA-1', 'TEXT');
156 | shaObj.setHMACKey(this.publicToken, 'TEXT');
157 | shaObj.update(url);
158 |
159 | url += '&frontend_sign=' + shaObj.getHMAC('HEX');
160 | return url;
161 | }
162 | }
163 |
164 | exports.ApiClient = ApiClient;
165 |
--------------------------------------------------------------------------------
/src/errors/api-error.js:
--------------------------------------------------------------------------------
1 | 'use strict';
2 |
3 | //http://stackoverflow.com/questions/31089801/extending-error-in-javascript-with-es6-syntax
4 |
5 | /**
6 | * Base class for errors that occur because of errors in requests reported by API or because of a timeout
7 | */
8 | class ApiError extends Error {
9 | constructor(message) {
10 | super(message);
11 | this.name = this.constructor.name;
12 | if (typeof Error.captureStackTrace === 'function') {
13 | Error.captureStackTrace(this, this.constructor);
14 | } else {
15 | this.stack = new Error(message).stack;
16 | }
17 | }
18 | }
19 |
20 | exports.ApiError = ApiError;
21 |
--------------------------------------------------------------------------------
/src/errors/index.js:
--------------------------------------------------------------------------------
1 | 'use strict';
2 | exports.ApiError = require('./api-error').ApiError;
3 | exports.ResponseError = require('./response-error').ResponseError;
4 | exports.TimeoutError = require('./timeout-error').TimeoutError;
5 |
--------------------------------------------------------------------------------
/src/errors/response-error.js:
--------------------------------------------------------------------------------
1 | 'use strict';
2 | const ae = require('./api-error');
3 |
4 | /**
5 | * Error thrown when a request did not succeed (did not return 200 or 201)
6 | */
7 | class ResponseError extends ae.ApiError {
8 | /**
9 | * Create the exception
10 | * @param {Request} request - Request which caused the exception
11 | * @param {number} statusCode - The returned status code
12 | * @param {string} message - Error message from the API
13 | */
14 | constructor(request, statusCode, message) {
15 | super(message);
16 | this.request = request;
17 | this.statusCode = statusCode;
18 | }
19 | }
20 |
21 | exports.ResponseError = ResponseError;
22 |
--------------------------------------------------------------------------------
/src/errors/timeout-error.js:
--------------------------------------------------------------------------------
1 | 'use strict';
2 | const ae = require('./api-error');
3 |
4 | /**
5 | * Error thrown when a request is not processed within the timeout
6 | */
7 | class TimeoutError extends ae.ApiError {
8 | /**
9 | * Create the exception
10 | * @param {Request} request - Request which caused the exception
11 | */
12 | constructor(request) {
13 | super(`Client did not get response within ${request.timeout} ms`);
14 | this.request = request;
15 | }
16 | }
17 |
18 | exports.TimeoutError = TimeoutError;
19 |
--------------------------------------------------------------------------------
/src/index.d.ts:
--------------------------------------------------------------------------------
1 | declare module 'recombee-js-api-client' {
2 | /**
3 | * Base class for errors that occur because of errors in requests reported by API or because of a timeout
4 | */
5 | export class ApiError extends Error {
6 | /**
7 | * @param message - Message of the exception.
8 | */
9 | constructor(message: string);
10 | }
11 |
12 | /**
13 | * Error thrown when a request did not succeed (did not return 200 or 201)
14 | */
15 | export class ResponseError extends ApiError {
16 | /**
17 | * @param request - Request which caused the exception.
18 | * @param statusCode - The returned status code.
19 | * @param message - Error message from the API.
20 | */
21 | constructor(request: Request, statusCode: number, message: string);
22 | }
23 |
24 | /**
25 | * Error thrown when a request is not processed within the timeout
26 | */
27 | export class TimeoutError extends ApiError {
28 | /**
29 | * @param request - Request which caused the exception.
30 | */
31 | constructor(request: Request);
32 | }
33 |
34 | /**
35 | * Base class for all the requests
36 | */
37 | export class Request {
38 | /**
39 | * @param method - GET/PUT/POST/DELETE.
40 | * @param path - Path to the endpoint.
41 | * @param timeout - Timeout in milliseconds.
42 | */
43 | constructor(
44 | method: 'GET' | 'PUT' | 'POST' | 'DELETE',
45 | path: string,
46 | timeout: number,
47 | ensureHttps: boolean,
48 | );
49 |
50 | method: 'GET' | 'PUT' | 'POST' | 'DELETE';
51 | path: string;
52 | timeout: number;
53 | ensureHttps: boolean;
54 |
55 | // eslint-disable-next-line @typescript-eslint/no-explicit-any
56 | protected __response_type: any;
57 | }
58 |
59 | /**
60 | * Batch processing allows you to submit any sequence of requests within a single HTTPS request.
61 | *
62 | * Any type of request from this SDK may be used in the Batch, and the Batch may combine different types of requests arbitrarily as well.
63 | *
64 | * Using Batch requests can be beneficial in situations such as synchronizing the catalog of items or uploading historical interaction data,
65 | * as sending the data in Batch is considerably faster than sending the individual requests (thanks to optimizations and reducing network and HTTPS overhead).
66 | *
67 | * @note The status code of the batch request itself is 200 even if the individual requests result in an error – you have to inspect the code values in the resulting array.
68 | */
69 | export class Batch extends Request {
70 | /**
71 | * @param requests - Array containing the requests.
72 | * @param optional - Optional parameters given as an object (allowed parameters: distinctRecomms).
73 | */
74 | constructor(
75 | requests: Request[],
76 | optional?: {
77 | distinctRecomms?: boolean;
78 | },
79 | );
80 |
81 | protected __response_type: BatchResponse;
82 |
83 | /**
84 | * Get body parameters
85 | *
86 | * @returns The values of body parameters (name of parameter: value of the parameter)
87 | */
88 | bodyParameters(): {
89 | requests: BatchedRequest[];
90 | distinctRecomms?: boolean;
91 | };
92 |
93 | _request_to_batch_object(req: Request): BatchedRequest;
94 | }
95 |
96 | export type BatchedRequest = {
97 | method: string;
98 | path: string;
99 | params?: { [key: string]: unknown };
100 | };
101 |
102 | export type ApiClientOptions = {
103 | baseUri?: string;
104 | region?: string;
105 | useHttps?: boolean;
106 | async?: boolean;
107 | future_v6_fetch?: boolean;
108 | };
109 |
110 | export type BatchResponse = {
111 | code: number;
112 | // eslint-disable-next-line @typescript-eslint/no-explicit-any
113 | json: any;
114 | }[];
115 |
116 | /**
117 | * Client for sending requests to Recombee and getting replies
118 | */
119 | export class ApiClient {
120 | /**
121 | * @param databaseId - ID of your database.
122 | * @param publicToken - Corresponding public token.
123 | * @param options - Other custom options.
124 | */
125 | constructor(databaseId: string, publicToken: string, options?: ApiClientOptions);
126 |
127 | _getRegionalBaseUri(region: string): string;
128 |
129 | _getBaseUri(): string;
130 |
131 | /**
132 | * Send the request to Recombee
133 | *
134 | * @param request - Request to be sent.
135 | * @param callback - Optional callback.
136 | * @returns Promise if callback is omitted, otherwise void.
137 | */
138 | send(
139 | request: TRequest,
140 | // @ts-expect-error private member
141 | callback?: (error: ResponseError | null, response?: TRequest['__response_type']) => void,
142 | ) // @ts-expect-error private member
143 | : Promise;
144 |
145 | _signUrl(req_part: string): string;
146 | }
147 |
148 | export type Recommendation = {
149 | id: string;
150 | values?: { [key: string]: unknown };
151 | };
152 |
153 | export type RecommendationResponse = {
154 | recommId: string;
155 | recomms: Recommendation[];
156 | numberNextRecommsCalls?: number;
157 | abGroup?: string;
158 | };
159 |
160 | export type SearchResponse = {
161 | recommId: string;
162 | recomms: Recommendation[];
163 | numberNextRecommsCalls?: number;
164 | abGroup?: string;
165 | };
166 |
167 | /**
168 | * Merges interactions (purchases, ratings, bookmarks, detail views ...) of two different users under a single user ID. This is especially useful for online e-commerce applications working with anonymous users identified by unique tokens such as the session ID. In such applications, it may often happen that a user owns a persistent account, yet accesses the system anonymously while, e.g., putting items into a shopping cart. At some point in time, such as when the user wishes to confirm the purchase, (s)he logs into the system using his/her username and password. The interactions made under anonymous session ID then become connected with the persistent account, and merging these two becomes desirable.
169 | * Merging happens between two users referred to as the *target* and the *source*. After the merge, all the interactions of the source user are attributed to the target user, and the source user is **deleted**.
170 | */
171 | export class MergeUsers extends Request {
172 | /**
173 | * @param targetUserId - ID of the target user.
174 | * @param sourceUserId - ID of the source user.
175 | * @param optional - Optional parameters given as an object.
176 | */
177 | constructor(
178 | targetUserId: string,
179 | sourceUserId: string,
180 | optional?: {
181 | /** Sets whether the user *targetUserId* should be created if not present in the database. */
182 | cascadeCreate?: boolean;
183 | },
184 | );
185 |
186 | targetUserId: string;
187 | sourceUserId: string;
188 | cascadeCreate?: boolean;
189 | protected __response_type: string;
190 |
191 | bodyParameters(): {};
192 |
193 | queryParameters(): {
194 | cascadeCreate?: boolean;
195 | };
196 | }
197 |
198 | /**
199 | * Adds a detail view of the given item made by the given user.
200 | */
201 | export class AddDetailView extends Request {
202 | /**
203 | * @param userId - User who viewed the item
204 | * @param itemId - Viewed item
205 | * @param optional - Optional parameters given as an object.
206 | */
207 | constructor(
208 | userId: string,
209 | itemId: string,
210 | optional?: {
211 | /** UTC timestamp of the view as ISO8601-1 pattern or UTC epoch time. The default value is the current time. */
212 | timestamp?: string | number;
213 | /** Duration of the view */
214 | duration?: number;
215 | /** Sets whether the given user/item should be created if not present in the database. */
216 | cascadeCreate?: boolean;
217 | /** If this detail view is based on a recommendation request, `recommId` is the id of the clicked recommendation. */
218 | recommId?: string;
219 | /** A dictionary of additional data for the interaction. */
220 | additionalData?: { [key: string]: unknown };
221 | },
222 | );
223 |
224 | userId: string;
225 | itemId: string;
226 | timestamp?: string | number;
227 | duration?: number;
228 | cascadeCreate?: boolean;
229 | recommId?: string;
230 | additionalData?: { [key: string]: unknown };
231 | protected __response_type: string;
232 |
233 | bodyParameters(): {
234 | userId: string;
235 | itemId: string;
236 | timestamp?: string | number;
237 | duration?: number;
238 | cascadeCreate?: boolean;
239 | recommId?: string;
240 | additionalData?: { [key: string]: unknown };
241 | };
242 |
243 | queryParameters(): {};
244 | }
245 |
246 | /**
247 | * Adds a purchase of the given item made by the given user.
248 | */
249 | export class AddPurchase extends Request {
250 | /**
251 | * @param userId - User who purchased the item
252 | * @param itemId - Purchased item
253 | * @param optional - Optional parameters given as an object.
254 | */
255 | constructor(
256 | userId: string,
257 | itemId: string,
258 | optional?: {
259 | /** UTC timestamp of the purchase as ISO8601-1 pattern or UTC epoch time. The default value is the current time. */
260 | timestamp?: string | number;
261 | /** Sets whether the given user/item should be created if not present in the database. */
262 | cascadeCreate?: boolean;
263 | /** Amount (number) of purchased items. The default is 1. For example, if `user-x` purchases two `item-y` during a single order (session...), the `amount` should equal 2. */
264 | amount?: number;
265 | /** Price paid by the user for the item. If `amount` is greater than 1, the sum of prices of all the items should be given. */
266 | price?: number;
267 | /** Your profit from the purchased item. The profit is natural in the e-commerce domain (for example, if `user-x` purchases `item-y` for $100 and the gross margin is 30 %, then the profit is $30) but is also applicable in other domains (for example, at a news company it may be income from a displayed advertisement on article page). If `amount` is greater than 1, the sum of profit of all the items should be given. */
268 | profit?: number;
269 | /** If this purchase is based on a recommendation request, `recommId` is the id of the clicked recommendation. */
270 | recommId?: string;
271 | /** A dictionary of additional data for the interaction. */
272 | additionalData?: { [key: string]: unknown };
273 | },
274 | );
275 |
276 | userId: string;
277 | itemId: string;
278 | timestamp?: string | number;
279 | cascadeCreate?: boolean;
280 | amount?: number;
281 | price?: number;
282 | profit?: number;
283 | recommId?: string;
284 | additionalData?: { [key: string]: unknown };
285 | protected __response_type: string;
286 |
287 | bodyParameters(): {
288 | userId: string;
289 | itemId: string;
290 | timestamp?: string | number;
291 | cascadeCreate?: boolean;
292 | amount?: number;
293 | price?: number;
294 | profit?: number;
295 | recommId?: string;
296 | additionalData?: { [key: string]: unknown };
297 | };
298 |
299 | queryParameters(): {};
300 | }
301 |
302 | /**
303 | * Adds a rating of the given item made by the given user.
304 | */
305 | export class AddRating extends Request {
306 | /**
307 | * @param userId - User who submitted the rating
308 | * @param itemId - Rated item
309 | * @param rating - Rating rescaled to interval [-1.0,1.0], where -1.0 means the worst rating possible, 0.0 means neutral, and 1.0 means absolutely positive rating. For example, in the case of 5-star evaluations, rating = (numStars-3)/2 formula may be used for the conversion.
310 | * @param optional - Optional parameters given as an object.
311 | */
312 | constructor(
313 | userId: string,
314 | itemId: string,
315 | rating: number,
316 | optional?: {
317 | /** UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time. */
318 | timestamp?: string | number;
319 | /** Sets whether the given user/item should be created if not present in the database. */
320 | cascadeCreate?: boolean;
321 | /** If this rating is based on a recommendation request, `recommId` is the id of the clicked recommendation. */
322 | recommId?: string;
323 | /** A dictionary of additional data for the interaction. */
324 | additionalData?: { [key: string]: unknown };
325 | },
326 | );
327 |
328 | userId: string;
329 | itemId: string;
330 | rating: number;
331 | timestamp?: string | number;
332 | cascadeCreate?: boolean;
333 | recommId?: string;
334 | additionalData?: { [key: string]: unknown };
335 | protected __response_type: string;
336 |
337 | bodyParameters(): {
338 | userId: string;
339 | itemId: string;
340 | rating: number;
341 | timestamp?: string | number;
342 | cascadeCreate?: boolean;
343 | recommId?: string;
344 | additionalData?: { [key: string]: unknown };
345 | };
346 |
347 | queryParameters(): {};
348 | }
349 |
350 | /**
351 | * Adds a cart addition of the given item made by the given user.
352 | */
353 | export class AddCartAddition extends Request {
354 | /**
355 | * @param userId - User who added the item to the cart
356 | * @param itemId - Item added to the cart
357 | * @param optional - Optional parameters given as an object.
358 | */
359 | constructor(
360 | userId: string,
361 | itemId: string,
362 | optional?: {
363 | /** UTC timestamp of the cart addition as ISO8601-1 pattern or UTC epoch time. The default value is the current time. */
364 | timestamp?: string | number;
365 | /** Sets whether the given user/item should be created if not present in the database. */
366 | cascadeCreate?: boolean;
367 | /** Amount (number) added to cart. The default is 1. For example, if `user-x` adds two `item-y` during a single order (session...), the `amount` should equal 2. */
368 | amount?: number;
369 | /** Price of the added item. If `amount` is greater than 1, the sum of prices of all the items should be given. */
370 | price?: number;
371 | /** If this cart addition is based on a recommendation request, `recommId` is the id of the clicked recommendation. */
372 | recommId?: string;
373 | /** A dictionary of additional data for the interaction. */
374 | additionalData?: { [key: string]: unknown };
375 | },
376 | );
377 |
378 | userId: string;
379 | itemId: string;
380 | timestamp?: string | number;
381 | cascadeCreate?: boolean;
382 | amount?: number;
383 | price?: number;
384 | recommId?: string;
385 | additionalData?: { [key: string]: unknown };
386 | protected __response_type: string;
387 |
388 | bodyParameters(): {
389 | userId: string;
390 | itemId: string;
391 | timestamp?: string | number;
392 | cascadeCreate?: boolean;
393 | amount?: number;
394 | price?: number;
395 | recommId?: string;
396 | additionalData?: { [key: string]: unknown };
397 | };
398 |
399 | queryParameters(): {};
400 | }
401 |
402 | /**
403 | * Adds a bookmark of the given item made by the given user.
404 | */
405 | export class AddBookmark extends Request {
406 | /**
407 | * @param userId - User who bookmarked the item
408 | * @param itemId - Bookmarked item
409 | * @param optional - Optional parameters given as an object.
410 | */
411 | constructor(
412 | userId: string,
413 | itemId: string,
414 | optional?: {
415 | /** UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time. */
416 | timestamp?: string | number;
417 | /** Sets whether the given user/item should be created if not present in the database. */
418 | cascadeCreate?: boolean;
419 | /** If this bookmark is based on a recommendation request, `recommId` is the id of the clicked recommendation. */
420 | recommId?: string;
421 | /** A dictionary of additional data for the interaction. */
422 | additionalData?: { [key: string]: unknown };
423 | },
424 | );
425 |
426 | userId: string;
427 | itemId: string;
428 | timestamp?: string | number;
429 | cascadeCreate?: boolean;
430 | recommId?: string;
431 | additionalData?: { [key: string]: unknown };
432 | protected __response_type: string;
433 |
434 | bodyParameters(): {
435 | userId: string;
436 | itemId: string;
437 | timestamp?: string | number;
438 | cascadeCreate?: boolean;
439 | recommId?: string;
440 | additionalData?: { [key: string]: unknown };
441 | };
442 |
443 | queryParameters(): {};
444 | }
445 |
446 | /**
447 | * Sets viewed portion of an item (for example a video or article) by a user (at a session).
448 | * If you send a new request with the same (`userId`, `itemId`, `sessionId`), the portion gets updated.
449 | */
450 | export class SetViewPortion extends Request {
451 | /**
452 | * @param userId - User who viewed a portion of the item
453 | * @param itemId - Viewed item
454 | * @param portion - Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the actual viewed part of the item, no matter the seeking. For example, if the user seeked immediately to half of the item and then viewed 10% of the item, the `portion` should still be `0.1`.
455 | * @param optional - Optional parameters given as an object.
456 | */
457 | constructor(
458 | userId: string,
459 | itemId: string,
460 | portion: number,
461 | optional?: {
462 | /** ID of the session in which the user viewed the item. Default is `null` (`None`, `nil`, `NULL` etc., depending on the language). */
463 | sessionId?: string;
464 | /** UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time. */
465 | timestamp?: string | number;
466 | /** Sets whether the given user/item should be created if not present in the database. */
467 | cascadeCreate?: boolean;
468 | /** If this view portion is based on a recommendation request, `recommId` is the id of the clicked recommendation. */
469 | recommId?: string;
470 | /** A dictionary of additional data for the interaction. */
471 | additionalData?: { [key: string]: unknown };
472 | },
473 | );
474 |
475 | userId: string;
476 | itemId: string;
477 | portion: number;
478 | sessionId?: string;
479 | timestamp?: string | number;
480 | cascadeCreate?: boolean;
481 | recommId?: string;
482 | additionalData?: { [key: string]: unknown };
483 | protected __response_type: string;
484 |
485 | bodyParameters(): {
486 | userId: string;
487 | itemId: string;
488 | portion: number;
489 | sessionId?: string;
490 | timestamp?: string | number;
491 | cascadeCreate?: boolean;
492 | recommId?: string;
493 | additionalData?: { [key: string]: unknown };
494 | };
495 |
496 | queryParameters(): {};
497 | }
498 |
499 | /**
500 | * Based on the user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for the given user.
501 | * The most typical use cases are recommendations on the homepage, in some "Picked just for you" section, or in email.
502 | * The returned items are sorted by relevance (the first item being the most relevant).
503 | * Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to:
504 | * - Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui.html#reported-metrics).
505 | * - Get subsequent recommended items when the user scrolls down (*infinite scroll*) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api.html#recommend-next-items).
506 | * It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.
507 | */
508 | export class RecommendItemsToUser extends Request {
509 | /**
510 | * @param userId - ID of the user for whom personalized recommendations are to be generated.
511 | * @param count - Number of items to be recommended (N for the top-N recommendation).
512 | * @param optional - Optional parameters given as an object.
513 | */
514 | constructor(
515 | userId: string,
516 | count: number,
517 | optional?: {
518 | /** Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". */
519 | scenario?: string;
520 | /** If the user 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 user, as the user will be already known to the system. */
521 | cascadeCreate?: boolean;
522 | /** 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. */
523 | returnProperties?: boolean;
524 | /** Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. */
525 | includedProperties?: string[];
526 | /** Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression, which allows you to filter recommended items based on the values of their attributes. */
527 | filter?: string;
528 | /** 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. */
529 | booster?: string;
530 | /** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. */
531 | logic?: string | object;
532 | /** **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. */
533 | diversity?: number;
534 | /** **Expert option** 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 to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such a 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. */
535 | minRelevance?: string;
536 | /** **Expert option** 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. Default: `0`. */
537 | rotationRate?: number;
538 | /** **Expert option** 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. Default: `7200.0`. */
539 | rotationTime?: number;
540 | /** Dictionary of custom options. */
541 | expertSettings?: { [key: string]: unknown };
542 | /** If there is a custom AB-testing running, return the name of the group to which the request belongs. */
543 | returnAbGroup?: boolean;
544 | },
545 | );
546 |
547 | userId: string;
548 | count: number;
549 | scenario?: string;
550 | cascadeCreate?: boolean;
551 | returnProperties?: boolean;
552 | includedProperties?: string[];
553 | filter?: string;
554 | booster?: string;
555 | logic?: string | object;
556 | diversity?: number;
557 | minRelevance?: string;
558 | rotationRate?: number;
559 | rotationTime?: number;
560 | expertSettings?: { [key: string]: unknown };
561 | returnAbGroup?: boolean;
562 | protected __response_type: RecommendationResponse;
563 |
564 | bodyParameters(): {
565 | count: number;
566 | scenario?: string;
567 | cascadeCreate?: boolean;
568 | returnProperties?: boolean;
569 | includedProperties?: string[];
570 | filter?: string;
571 | booster?: string;
572 | logic?: string | object;
573 | diversity?: number;
574 | minRelevance?: string;
575 | rotationRate?: number;
576 | rotationTime?: number;
577 | expertSettings?: { [key: string]: unknown };
578 | returnAbGroup?: boolean;
579 | };
580 |
581 | queryParameters(): {};
582 | }
583 |
584 | /**
585 | * Recommends a set of items that are somehow related to one given item, *X*. A typical scenario is when the user *A* is viewing *X*. Then you may display items to the user that he might also be interested in. Recommend items to item request gives you Top-N such items, optionally taking the target user *A* into account.
586 | * The returned items are sorted by relevance (the first item being the most relevant).
587 | * Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to:
588 | * - Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui.html#reported-metrics).
589 | * - Get subsequent recommended items when the user scrolls down (*infinite scroll*) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api.html#recommend-next-items).
590 | * It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.
591 | */
592 | export class RecommendItemsToItem extends Request {
593 | /**
594 | * @param itemId - ID of the item for which the recommendations are to be generated.
595 | * @param targetUserId - ID of the user who will see the recommendations.
596 | * Specifying the *targetUserId* is beneficial because:
597 | * * It makes the recommendations personalized
598 | * * Allows the calculation of Actions and Conversions
599 | * in the graphical user interface,
600 | * as Recombee can pair the user who got recommendations
601 | * and who afterward viewed/purchased an item.
602 | * If you insist on not specifying the user, pass `null`
603 | * (`None`, `nil`, `NULL` etc., depending on the language) to *targetUserId*.
604 | * Do not create some special dummy user for getting recommendations,
605 | * as it could mislead the recommendation models,
606 | * and result in wrong recommendations.
607 | * For anonymous/unregistered users, it is possible to use, for example, their session ID.
608 | * @param count - Number of items to be recommended (N for the top-N recommendation).
609 | * @param optional - Optional parameters given as an object.
610 | */
611 | constructor(
612 | itemId: string,
613 | targetUserId: string,
614 | count: number,
615 | optional?: {
616 | /** Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". */
617 | scenario?: string;
618 | /** 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. */
619 | cascadeCreate?: boolean;
620 | /** 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. */
621 | returnProperties?: boolean;
622 | /** Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. */
623 | includedProperties?: string[];
624 | /** Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression, which allows you to filter recommended items based on the values of their attributes. */
625 | filter?: string;
626 | /** 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. */
627 | booster?: string;
628 | /** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. */
629 | logic?: string | object;
630 | /** **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`. */
631 | userImpact?: number;
632 | /** **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. */
633 | diversity?: number;
634 | /** **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. */
635 | minRelevance?: string;
636 | /** **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. */
637 | rotationRate?: number;
638 | /** **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. */
639 | rotationTime?: number;
640 | /** Dictionary of custom options. */
641 | expertSettings?: { [key: string]: unknown };
642 | /** If there is a custom AB-testing running, return the name of the group to which the request belongs. */
643 | returnAbGroup?: boolean;
644 | },
645 | );
646 |
647 | itemId: string;
648 | targetUserId: string;
649 | count: number;
650 | scenario?: string;
651 | cascadeCreate?: boolean;
652 | returnProperties?: boolean;
653 | includedProperties?: string[];
654 | filter?: string;
655 | booster?: string;
656 | logic?: string | object;
657 | userImpact?: number;
658 | diversity?: number;
659 | minRelevance?: string;
660 | rotationRate?: number;
661 | rotationTime?: number;
662 | expertSettings?: { [key: string]: unknown };
663 | returnAbGroup?: boolean;
664 | protected __response_type: RecommendationResponse;
665 |
666 | bodyParameters(): {
667 | targetUserId: string;
668 | count: number;
669 | scenario?: string;
670 | cascadeCreate?: boolean;
671 | returnProperties?: boolean;
672 | includedProperties?: string[];
673 | filter?: string;
674 | booster?: string;
675 | logic?: string | object;
676 | userImpact?: number;
677 | diversity?: number;
678 | minRelevance?: string;
679 | rotationRate?: number;
680 | rotationTime?: number;
681 | expertSettings?: { [key: string]: unknown };
682 | returnAbGroup?: boolean;
683 | };
684 |
685 | queryParameters(): {};
686 | }
687 |
688 | /**
689 | * Recommends Items that are the most relevant to a particular Segment from a context [Segmentation](https://docs.recombee.com/segmentations.html).
690 | * Based on the used Segmentation, this endpoint can be used for example for:
691 | * - Recommending articles related to a particular topic
692 | * - Recommending songs belonging to a particular genre
693 | * - Recommending products produced by a particular brand
694 | * 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.
695 | * The returned items are sorted by relevance (the first item being the most relevant).
696 | * 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.
697 | */
698 | export class RecommendItemsToItemSegment extends Request {
699 | /**
700 | * @param contextSegmentId - ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.
701 | * @param targetUserId - ID of the user who will see the recommendations.
702 | * Specifying the *targetUserId* is beneficial because:
703 | * * It makes the recommendations personalized
704 | * * Allows the calculation of Actions and Conversions
705 | * in the graphical user interface,
706 | * as Recombee can pair the user who got recommendations
707 | * and who afterward viewed/purchased an item.
708 | * If you insist on not specifying the user, pass `null`
709 | * (`None`, `nil`, `NULL` etc., depending on the language) to *targetUserId*.
710 | * Do not create some special dummy user for getting recommendations,
711 | * as it could mislead the recommendation models,
712 | * and result in wrong recommendations.
713 | * For anonymous/unregistered users, it is possible to use, for example, their session ID.
714 | * @param count - Number of items to be recommended (N for the top-N recommendation).
715 | * @param optional - Optional parameters given as an object.
716 | */
717 | constructor(
718 | contextSegmentId: string,
719 | targetUserId: string,
720 | count: number,
721 | optional?: {
722 | /** Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". */
723 | scenario?: string;
724 | /** 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. */
725 | cascadeCreate?: boolean;
726 | /** 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. */
727 | returnProperties?: boolean;
728 | /** Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. */
729 | includedProperties?: string[];
730 | /** Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression, which allows you to filter recommended items based on the values of their attributes. */
731 | filter?: string;
732 | /** 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. */
733 | booster?: string;
734 | /** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. */
735 | logic?: string | object;
736 | /** **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. */
737 | minRelevance?: string;
738 | /** **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. */
739 | rotationRate?: number;
740 | /** **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. */
741 | rotationTime?: number;
742 | /** Dictionary of custom options. */
743 | expertSettings?: { [key: string]: unknown };
744 | /** If there is a custom AB-testing running, return the name of the group to which the request belongs. */
745 | returnAbGroup?: boolean;
746 | },
747 | );
748 |
749 | contextSegmentId: string;
750 | targetUserId: string;
751 | count: number;
752 | scenario?: string;
753 | cascadeCreate?: boolean;
754 | returnProperties?: boolean;
755 | includedProperties?: string[];
756 | filter?: string;
757 | booster?: string;
758 | logic?: string | object;
759 | minRelevance?: string;
760 | rotationRate?: number;
761 | rotationTime?: number;
762 | expertSettings?: { [key: string]: unknown };
763 | returnAbGroup?: boolean;
764 | protected __response_type: RecommendationResponse;
765 |
766 | bodyParameters(): {
767 | contextSegmentId: string;
768 | targetUserId: string;
769 | count: number;
770 | scenario?: string;
771 | cascadeCreate?: boolean;
772 | returnProperties?: boolean;
773 | includedProperties?: string[];
774 | filter?: string;
775 | booster?: string;
776 | logic?: string | object;
777 | minRelevance?: string;
778 | rotationRate?: number;
779 | rotationTime?: number;
780 | expertSettings?: { [key: string]: unknown };
781 | returnAbGroup?: boolean;
782 | };
783 |
784 | queryParameters(): {};
785 | }
786 |
787 | /**
788 | * 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.
789 | * 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`).
790 | * The base request can be one of:
791 | * - [Recommend Items to Item](https://docs.recombee.com/api.html#recommend-items-to-item)
792 | * - [Recommend Items to User](https://docs.recombee.com/api.html#recommend-items-to-user)
793 | * - [Recommend Items to Item Segment](https://docs.recombee.com/api.html#recommend-items-to-item-segment)
794 | * - [Search Items](https://docs.recombee.com/api.html#search-items)
795 | * All the other parameters are inherited from the base request.
796 | * *Recommend next items* can be called many times for a single `recommId` and each call returns different (previously not recommended) items.
797 | * The number of *Recommend next items* calls performed so far is returned in the `numberNextRecommsCalls` field.
798 | * *Recommend next items* can be requested up to 30 minutes after the base request or a previous *Recommend next items* call.
799 | * For billing purposes, each call to *Recommend next items* is counted as a separate recommendation request.
800 | */
801 | export class RecommendNextItems extends Request {
802 | /**
803 | * @param recommId - ID of the base recommendation request for which next recommendations should be returned
804 | * @param count - Number of items to be recommended
805 | */
806 | constructor(recommId: string, count: number);
807 |
808 | recommId: string;
809 | count: number;
810 | protected __response_type: RecommendationResponse;
811 |
812 | bodyParameters(): {
813 | count: number;
814 | };
815 |
816 | queryParameters(): {};
817 | }
818 |
819 | /**
820 | * Recommends the top Segments from a [Segmentation](https://docs.recombee.com/segmentations.html) for a particular user, based on the user's past interactions.
821 | * Based on the used Segmentation, this endpoint can be used for example for:
822 | * - Recommending the top categories for the user
823 | * - Recommending the top genres for the user
824 | * - Recommending the top brands for the user
825 | * - Recommending the top artists for the user
826 | * You need to set the used Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.
827 | * The returned segments are sorted by relevance (first segment being the most relevant).
828 | * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
829 | */
830 | export class RecommendItemSegmentsToUser extends Request {
831 | /**
832 | * @param userId - ID of the user for whom personalized recommendations are to be generated.
833 | * @param count - Number of item segments to be recommended (N for the top-N recommendation).
834 | * @param optional - Optional parameters given as an object.
835 | */
836 | constructor(
837 | userId: string,
838 | count: number,
839 | optional?: {
840 | /** Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". */
841 | scenario?: string;
842 | /** If the user 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 user, as the user will be already known to the system. */
843 | cascadeCreate?: boolean;
844 | /** Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended segments based on the `segmentationId`. */
845 | filter?: string;
846 | /** Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`. */
847 | booster?: string;
848 | /** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. */
849 | logic?: string | object;
850 | /** Dictionary of custom options. */
851 | expertSettings?: { [key: string]: unknown };
852 | /** If there is a custom AB-testing running, return the name of the group to which the request belongs. */
853 | returnAbGroup?: boolean;
854 | },
855 | );
856 |
857 | userId: string;
858 | count: number;
859 | scenario?: string;
860 | cascadeCreate?: boolean;
861 | filter?: string;
862 | booster?: string;
863 | logic?: string | object;
864 | expertSettings?: { [key: string]: unknown };
865 | returnAbGroup?: boolean;
866 | protected __response_type: RecommendationResponse;
867 |
868 | bodyParameters(): {
869 | count: number;
870 | scenario?: string;
871 | cascadeCreate?: boolean;
872 | filter?: string;
873 | booster?: string;
874 | logic?: string | object;
875 | expertSettings?: { [key: string]: unknown };
876 | returnAbGroup?: boolean;
877 | };
878 |
879 | queryParameters(): {};
880 | }
881 |
882 | /**
883 | * Recommends Segments from a [Segmentation](https://docs.recombee.com/segmentations.html) that are the most relevant to a particular item.
884 | * Based on the used Segmentation, this endpoint can be used for example for:
885 | * - Recommending the related categories
886 | * - Recommending the related genres
887 | * - Recommending the related brands
888 | * - Recommending the related artists
889 | * You need to set the used Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.
890 | * The returned segments are sorted by relevance (first segment being the most relevant).
891 | * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
892 | */
893 | export class RecommendItemSegmentsToItem extends Request {
894 | /**
895 | * @param itemId - ID of the item for which the recommendations are to be generated.
896 | * @param targetUserId - ID of the user who will see the recommendations.
897 | * Specifying the *targetUserId* is beneficial because:
898 | * * It makes the recommendations personalized
899 | * * Allows the calculation of Actions and Conversions
900 | * in the graphical user interface,
901 | * as Recombee can pair the user who got recommendations
902 | * and who afterward viewed/purchased an item.
903 | * If you insist on not specifying the user, pass `null`
904 | * (`None`, `nil`, `NULL` etc., depending on the language) to *targetUserId*.
905 | * Do not create some special dummy user for getting recommendations,
906 | * as it could mislead the recommendation models,
907 | * and result in wrong recommendations.
908 | * For anonymous/unregistered users, it is possible to use, for example, their session ID.
909 | * @param count - Number of item segments to be recommended (N for the top-N recommendation).
910 | * @param optional - Optional parameters given as an object.
911 | */
912 | constructor(
913 | itemId: string,
914 | targetUserId: string,
915 | count: number,
916 | optional?: {
917 | /** Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". */
918 | scenario?: string;
919 | /** If the user 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 user, as the user will be already known to the system. */
920 | cascadeCreate?: boolean;
921 | /** Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended segments based on the `segmentationId`. */
922 | filter?: string;
923 | /** Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`. */
924 | booster?: string;
925 | /** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. */
926 | logic?: string | object;
927 | /** Dictionary of custom options. */
928 | expertSettings?: { [key: string]: unknown };
929 | /** If there is a custom AB-testing running, return the name of the group to which the request belongs. */
930 | returnAbGroup?: boolean;
931 | },
932 | );
933 |
934 | itemId: string;
935 | targetUserId: string;
936 | count: number;
937 | scenario?: string;
938 | cascadeCreate?: boolean;
939 | filter?: string;
940 | booster?: string;
941 | logic?: string | object;
942 | expertSettings?: { [key: string]: unknown };
943 | returnAbGroup?: boolean;
944 | protected __response_type: RecommendationResponse;
945 |
946 | bodyParameters(): {
947 | targetUserId: string;
948 | count: number;
949 | scenario?: string;
950 | cascadeCreate?: boolean;
951 | filter?: string;
952 | booster?: string;
953 | logic?: string | object;
954 | expertSettings?: { [key: string]: unknown };
955 | returnAbGroup?: boolean;
956 | };
957 |
958 | queryParameters(): {};
959 | }
960 |
961 | /**
962 | * 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.
963 | * Based on the used Segmentations, this endpoint can be used for example for:
964 | * - Recommending the related brands to particular brand
965 | * - Recommending the related brands to particular category
966 | * - Recommending the related artists to a particular genre (assuming songs are the Items)
967 | * 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.
968 | * The returned segments are sorted by relevance (first segment being the most relevant).
969 | * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
970 | */
971 | export class RecommendItemSegmentsToItemSegment extends Request {
972 | /**
973 | * @param contextSegmentId - ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.
974 | * @param targetUserId - ID of the user who will see the recommendations.
975 | * Specifying the *targetUserId* is beneficial because:
976 | * * It makes the recommendations personalized
977 | * * Allows the calculation of Actions and Conversions
978 | * in the graphical user interface,
979 | * as Recombee can pair the user who got recommendations
980 | * and who afterward viewed/purchased an item.
981 | * If you insist on not specifying the user, pass `null`
982 | * (`None`, `nil`, `NULL` etc., depending on the language) to *targetUserId*.
983 | * Do not create some special dummy user for getting recommendations,
984 | * as it could mislead the recommendation models,
985 | * and result in wrong recommendations.
986 | * For anonymous/unregistered users, it is possible to use, for example, their session ID.
987 | * @param count - Number of item segments to be recommended (N for the top-N recommendation).
988 | * @param optional - Optional parameters given as an object.
989 | */
990 | constructor(
991 | contextSegmentId: string,
992 | targetUserId: string,
993 | count: number,
994 | optional?: {
995 | /** Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". */
996 | scenario?: string;
997 | /** If the user 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 user, as the user will be already known to the system. */
998 | cascadeCreate?: boolean;
999 | /** Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended segments based on the `segmentationId`. */
1000 | filter?: string;
1001 | /** Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`. */
1002 | booster?: string;
1003 | /** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. */
1004 | logic?: string | object;
1005 | /** Dictionary of custom options. */
1006 | expertSettings?: { [key: string]: unknown };
1007 | /** If there is a custom AB-testing running, return the name of the group to which the request belongs. */
1008 | returnAbGroup?: boolean;
1009 | },
1010 | );
1011 |
1012 | contextSegmentId: string;
1013 | targetUserId: string;
1014 | count: number;
1015 | scenario?: string;
1016 | cascadeCreate?: boolean;
1017 | filter?: string;
1018 | booster?: string;
1019 | logic?: string | object;
1020 | expertSettings?: { [key: string]: unknown };
1021 | returnAbGroup?: boolean;
1022 | protected __response_type: RecommendationResponse;
1023 |
1024 | bodyParameters(): {
1025 | contextSegmentId: string;
1026 | targetUserId: string;
1027 | count: number;
1028 | scenario?: string;
1029 | cascadeCreate?: boolean;
1030 | filter?: string;
1031 | booster?: string;
1032 | logic?: string | object;
1033 | expertSettings?: { [key: string]: unknown };
1034 | returnAbGroup?: boolean;
1035 | };
1036 |
1037 | queryParameters(): {};
1038 | }
1039 |
1040 | /**
1041 | * 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).
1042 | * All the string and set item properties are indexed by the search engine.
1043 | * This endpoint should be used in a search box on your website/app. It can be called multiple times as the user is typing the query in order to get the most viable suggestions based on the current state of the query, or once after submitting the whole query.
1044 | * The returned items are sorted by relevance (the first item being the most relevant).
1045 | * Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to:
1046 | * - Let Recombee know that this search was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui.html#reported-metrics).
1047 | * - Get subsequent search results when the user scrolls down or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api.html#recommend-next-items).
1048 | * It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.
1049 | */
1050 | export class SearchItems extends Request {
1051 | /**
1052 | * @param userId - ID of the user for whom personalized search will be performed.
1053 | * @param searchQuery - Search query provided by the user. It is used for the full-text search.
1054 | * @param count - Number of items to be returned (N for the top-N results).
1055 | * @param optional - Optional parameters given as an object.
1056 | */
1057 | constructor(
1058 | userId: string,
1059 | searchQuery: string,
1060 | count: number,
1061 | optional?: {
1062 | /** Scenario defines a particular search field in your user interface. */
1063 | scenario?: string;
1064 | /** If the user does not exist in the database, returns a list of non-personalized search results and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system. */
1065 | cascadeCreate?: boolean;
1066 | /** 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. */
1067 | returnProperties?: boolean;
1068 | /** Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. */
1069 | includedProperties?: string[];
1070 | /** Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression, which allows you to filter recommended items based on the values of their attributes. */
1071 | filter?: string;
1072 | /** 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. */
1073 | booster?: string;
1074 | /** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. */
1075 | logic?: string | object;
1076 | /** Dictionary of custom options. */
1077 | expertSettings?: { [key: string]: unknown };
1078 | /** If there is a custom AB-testing running, return the name of the group to which the request belongs. */
1079 | returnAbGroup?: boolean;
1080 | },
1081 | );
1082 |
1083 | userId: string;
1084 | searchQuery: string;
1085 | count: number;
1086 | scenario?: string;
1087 | cascadeCreate?: boolean;
1088 | returnProperties?: boolean;
1089 | includedProperties?: string[];
1090 | filter?: string;
1091 | booster?: string;
1092 | logic?: string | object;
1093 | expertSettings?: { [key: string]: unknown };
1094 | returnAbGroup?: boolean;
1095 | protected __response_type: SearchResponse;
1096 |
1097 | bodyParameters(): {
1098 | searchQuery: string;
1099 | count: number;
1100 | scenario?: string;
1101 | cascadeCreate?: boolean;
1102 | returnProperties?: boolean;
1103 | includedProperties?: string[];
1104 | filter?: string;
1105 | booster?: string;
1106 | logic?: string | object;
1107 | expertSettings?: { [key: string]: unknown };
1108 | returnAbGroup?: boolean;
1109 | };
1110 |
1111 | queryParameters(): {};
1112 | }
1113 |
1114 | /**
1115 | * Full-text personalized search that returns Segments from a Segmentation. The results are based on the provided `searchQuery` and also on the user's past interactions (purchases, ratings, etc.).
1116 | * Based on the used Segmentation, this endpoint can be used for example for:
1117 | * - Searching within categories or brands
1118 | * - Searching within genres or artists
1119 | * For example if the user is searching for "iPhone" this endpoint can return "cell phones" category.
1120 | * You need to set the used Segmentation the Admin UI in the Scenario settings prior to using this endpoint.
1121 | * The returned segments are sorted by relevance (first segment being the most relevant).
1122 | * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
1123 | */
1124 | export class SearchItemSegments extends Request {
1125 | /**
1126 | * @param userId - ID of the user for whom personalized search will be performed.
1127 | * @param searchQuery - Search query provided by the user. It is used for the full-text search.
1128 | * @param count - Number of segments to be returned (N for the top-N results).
1129 | * @param optional - Optional parameters given as an object.
1130 | */
1131 | constructor(
1132 | userId: string,
1133 | searchQuery: string,
1134 | count: number,
1135 | optional?: {
1136 | /** Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". */
1137 | scenario?: string;
1138 | /** If the user 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 user, as the user will be already known to the system. */
1139 | cascadeCreate?: boolean;
1140 | /** Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended segments based on the `segmentationId`. */
1141 | filter?: string;
1142 | /** Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`. */
1143 | booster?: string;
1144 | /** Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. */
1145 | logic?: string | object;
1146 | /** Dictionary of custom options. */
1147 | expertSettings?: { [key: string]: unknown };
1148 | /** If there is a custom AB-testing running, return the name of the group to which the request belongs. */
1149 | returnAbGroup?: boolean;
1150 | },
1151 | );
1152 |
1153 | userId: string;
1154 | searchQuery: string;
1155 | count: number;
1156 | scenario?: string;
1157 | cascadeCreate?: boolean;
1158 | filter?: string;
1159 | booster?: string;
1160 | logic?: string | object;
1161 | expertSettings?: { [key: string]: unknown };
1162 | returnAbGroup?: boolean;
1163 | protected __response_type: SearchResponse;
1164 |
1165 | bodyParameters(): {
1166 | searchQuery: string;
1167 | count: number;
1168 | scenario?: string;
1169 | cascadeCreate?: boolean;
1170 | filter?: string;
1171 | booster?: string;
1172 | logic?: string | object;
1173 | expertSettings?: { [key: string]: unknown };
1174 | returnAbGroup?: boolean;
1175 | };
1176 |
1177 | queryParameters(): {};
1178 | }
1179 | }
1180 |
--------------------------------------------------------------------------------
/src/index.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | exports.ApiClient = require('./api-client').ApiClient;
7 | exports.ApiError = require('./errors/api-error').ApiError;
8 | exports.ResponseError = require('./errors/response-error').ResponseError;
9 | exports.TimeoutError = require('./errors/timeout-error').TimeoutError;
10 | exports.MergeUsers = require('./requests/merge-users').MergeUsers;
11 | exports.AddDetailView = require('./requests/add-detail-view').AddDetailView;
12 | exports.AddPurchase = require('./requests/add-purchase').AddPurchase;
13 | exports.AddRating = require('./requests/add-rating').AddRating;
14 | exports.AddCartAddition = require('./requests/add-cart-addition').AddCartAddition;
15 | exports.AddBookmark = require('./requests/add-bookmark').AddBookmark;
16 | exports.SetViewPortion = require('./requests/set-view-portion').SetViewPortion;
17 | exports.RecommendItemsToUser = require('./requests/recommend-items-to-user').RecommendItemsToUser;
18 | exports.RecommendItemsToItem = require('./requests/recommend-items-to-item').RecommendItemsToItem;
19 | exports.RecommendItemsToItemSegment =
20 | require('./requests/recommend-items-to-item-segment').RecommendItemsToItemSegment;
21 | exports.RecommendNextItems = require('./requests/recommend-next-items').RecommendNextItems;
22 | exports.RecommendItemSegmentsToUser =
23 | require('./requests/recommend-item-segments-to-user').RecommendItemSegmentsToUser;
24 | exports.RecommendItemSegmentsToItem =
25 | require('./requests/recommend-item-segments-to-item').RecommendItemSegmentsToItem;
26 | exports.RecommendItemSegmentsToItemSegment =
27 | require('./requests/recommend-item-segments-to-item-segment').RecommendItemSegmentsToItemSegment;
28 | exports.SearchItems = require('./requests/search-items').SearchItems;
29 | exports.SearchItemSegments = require('./requests/search-item-segments').SearchItemSegments;
30 | exports.Batch = require('./requests/batch').Batch;
31 |
--------------------------------------------------------------------------------
/src/requests/add-bookmark.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * Adds a bookmark of the given item made by the given user.
10 | */
11 | class AddBookmark extends rqs.Request {
12 | /**
13 | * Construct the request
14 | * @param {string} userId - User who bookmarked the item
15 | * @param {string} itemId - Bookmarked item
16 | * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
17 | * - Allowed parameters:
18 | * - *timestamp*
19 | * - Type: string | number
20 | * - Description: UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
21 | * - *cascadeCreate*
22 | * - Type: boolean
23 | * - Description: Sets whether the given user/item should be created if not present in the database.
24 | * - *recommId*
25 | * - Type: string
26 | * - Description: If this bookmark is based on a recommendation request, `recommId` is the id of the clicked recommendation.
27 | * - *additionalData*
28 | * - Type: object
29 | * - Description: A dictionary of additional data for the interaction.
30 | */
31 | constructor(userId, itemId, optional) {
32 | super('POST', '/bookmarks/', 9000, false);
33 | this.userId = userId;
34 | this.itemId = itemId;
35 | optional = optional || {};
36 | this.timestamp = optional.timestamp;
37 | this.cascadeCreate = optional.cascadeCreate;
38 | this.recommId = optional.recommId;
39 | this.additionalData = optional.additionalData;
40 | }
41 |
42 | /**
43 | * Get body parameters
44 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
45 | */
46 | bodyParameters() {
47 | const params = {};
48 | params.userId = this.userId;
49 | params.itemId = this.itemId;
50 |
51 | if (this.timestamp !== undefined) params.timestamp = this.timestamp;
52 |
53 | if (this.cascadeCreate !== undefined) params.cascadeCreate = this.cascadeCreate;
54 |
55 | if (this.recommId !== undefined) params.recommId = this.recommId;
56 |
57 | if (this.additionalData !== undefined) params.additionalData = this.additionalData;
58 |
59 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
60 | return params;
61 | }
62 | }
63 |
64 | exports.AddBookmark = AddBookmark;
65 |
--------------------------------------------------------------------------------
/src/requests/add-cart-addition.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * Adds a cart addition of the given item made by the given user.
10 | */
11 | class AddCartAddition extends rqs.Request {
12 | /**
13 | * Construct the request
14 | * @param {string} userId - User who added the item to the cart
15 | * @param {string} itemId - Item added to the cart
16 | * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
17 | * - Allowed parameters:
18 | * - *timestamp*
19 | * - Type: string | number
20 | * - Description: UTC timestamp of the cart addition as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
21 | * - *cascadeCreate*
22 | * - Type: boolean
23 | * - Description: Sets whether the given user/item should be created if not present in the database.
24 | * - *amount*
25 | * - Type: number
26 | * - Description: Amount (number) added to cart. The default is 1. For example, if `user-x` adds two `item-y` during a single order (session...), the `amount` should equal 2.
27 | * - *price*
28 | * - Type: number
29 | * - Description: Price of the added item. If `amount` is greater than 1, the sum of prices of all the items should be given.
30 | * - *recommId*
31 | * - Type: string
32 | * - Description: If this cart addition is based on a recommendation request, `recommId` is the id of the clicked recommendation.
33 | * - *additionalData*
34 | * - Type: object
35 | * - Description: A dictionary of additional data for the interaction.
36 | */
37 | constructor(userId, itemId, optional) {
38 | super('POST', '/cartadditions/', 9000, false);
39 | this.userId = userId;
40 | this.itemId = itemId;
41 | optional = optional || {};
42 | this.timestamp = optional.timestamp;
43 | this.cascadeCreate = optional.cascadeCreate;
44 | this.amount = optional.amount;
45 | this.price = optional.price;
46 | this.recommId = optional.recommId;
47 | this.additionalData = optional.additionalData;
48 | }
49 |
50 | /**
51 | * Get body parameters
52 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
53 | */
54 | bodyParameters() {
55 | const params = {};
56 | params.userId = this.userId;
57 | params.itemId = this.itemId;
58 |
59 | if (this.timestamp !== undefined) params.timestamp = this.timestamp;
60 |
61 | if (this.cascadeCreate !== undefined) params.cascadeCreate = this.cascadeCreate;
62 |
63 | if (this.amount !== undefined) params.amount = this.amount;
64 |
65 | if (this.price !== undefined) params.price = this.price;
66 |
67 | if (this.recommId !== undefined) params.recommId = this.recommId;
68 |
69 | if (this.additionalData !== undefined) params.additionalData = this.additionalData;
70 |
71 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
72 | return params;
73 | }
74 | }
75 |
76 | exports.AddCartAddition = AddCartAddition;
77 |
--------------------------------------------------------------------------------
/src/requests/add-detail-view.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * Adds a detail view of the given item made by the given user.
10 | */
11 | class AddDetailView extends rqs.Request {
12 | /**
13 | * Construct the request
14 | * @param {string} userId - User who viewed the item
15 | * @param {string} itemId - Viewed item
16 | * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
17 | * - Allowed parameters:
18 | * - *timestamp*
19 | * - Type: string | number
20 | * - Description: UTC timestamp of the view as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
21 | * - *duration*
22 | * - Type: number
23 | * - Description: Duration of the view
24 | * - *cascadeCreate*
25 | * - Type: boolean
26 | * - Description: Sets whether the given user/item should be created if not present in the database.
27 | * - *recommId*
28 | * - Type: string
29 | * - Description: If this detail view is based on a recommendation request, `recommId` is the id of the clicked recommendation.
30 | * - *additionalData*
31 | * - Type: object
32 | * - Description: A dictionary of additional data for the interaction.
33 | */
34 | constructor(userId, itemId, optional) {
35 | super('POST', '/detailviews/', 9000, false);
36 | this.userId = userId;
37 | this.itemId = itemId;
38 | optional = optional || {};
39 | this.timestamp = optional.timestamp;
40 | this.duration = optional.duration;
41 | this.cascadeCreate = optional.cascadeCreate;
42 | this.recommId = optional.recommId;
43 | this.additionalData = optional.additionalData;
44 | }
45 |
46 | /**
47 | * Get body parameters
48 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
49 | */
50 | bodyParameters() {
51 | const params = {};
52 | params.userId = this.userId;
53 | params.itemId = this.itemId;
54 |
55 | if (this.timestamp !== undefined) params.timestamp = this.timestamp;
56 |
57 | if (this.duration !== undefined) params.duration = this.duration;
58 |
59 | if (this.cascadeCreate !== undefined) params.cascadeCreate = this.cascadeCreate;
60 |
61 | if (this.recommId !== undefined) params.recommId = this.recommId;
62 |
63 | if (this.additionalData !== undefined) params.additionalData = this.additionalData;
64 |
65 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
66 | return params;
67 | }
68 | }
69 |
70 | exports.AddDetailView = AddDetailView;
71 |
--------------------------------------------------------------------------------
/src/requests/add-purchase.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * Adds a purchase of the given item made by the given user.
10 | */
11 | class AddPurchase extends rqs.Request {
12 | /**
13 | * Construct the request
14 | * @param {string} userId - User who purchased the item
15 | * @param {string} itemId - Purchased item
16 | * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
17 | * - Allowed parameters:
18 | * - *timestamp*
19 | * - Type: string | number
20 | * - Description: UTC timestamp of the purchase as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
21 | * - *cascadeCreate*
22 | * - Type: boolean
23 | * - Description: Sets whether the given user/item should be created if not present in the database.
24 | * - *amount*
25 | * - Type: number
26 | * - Description: Amount (number) of purchased items. The default is 1. For example, if `user-x` purchases two `item-y` during a single order (session...), the `amount` should equal 2.
27 | * - *price*
28 | * - Type: number
29 | * - Description: Price paid by the user for the item. If `amount` is greater than 1, the sum of prices of all the items should be given.
30 | * - *profit*
31 | * - Type: number
32 | * - Description: Your profit from the purchased item. The profit is natural in the e-commerce domain (for example, if `user-x` purchases `item-y` for $100 and the gross margin is 30 %, then the profit is $30) but is also applicable in other domains (for example, at a news company it may be income from a displayed advertisement on article page). If `amount` is greater than 1, the sum of profit of all the items should be given.
33 | * - *recommId*
34 | * - Type: string
35 | * - Description: If this purchase is based on a recommendation request, `recommId` is the id of the clicked recommendation.
36 | * - *additionalData*
37 | * - Type: object
38 | * - Description: A dictionary of additional data for the interaction.
39 | */
40 | constructor(userId, itemId, optional) {
41 | super('POST', '/purchases/', 9000, false);
42 | this.userId = userId;
43 | this.itemId = itemId;
44 | optional = optional || {};
45 | this.timestamp = optional.timestamp;
46 | this.cascadeCreate = optional.cascadeCreate;
47 | this.amount = optional.amount;
48 | this.price = optional.price;
49 | this.profit = optional.profit;
50 | this.recommId = optional.recommId;
51 | this.additionalData = optional.additionalData;
52 | }
53 |
54 | /**
55 | * Get body parameters
56 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
57 | */
58 | bodyParameters() {
59 | const params = {};
60 | params.userId = this.userId;
61 | params.itemId = this.itemId;
62 |
63 | if (this.timestamp !== undefined) params.timestamp = this.timestamp;
64 |
65 | if (this.cascadeCreate !== undefined) params.cascadeCreate = this.cascadeCreate;
66 |
67 | if (this.amount !== undefined) params.amount = this.amount;
68 |
69 | if (this.price !== undefined) params.price = this.price;
70 |
71 | if (this.profit !== undefined) params.profit = this.profit;
72 |
73 | if (this.recommId !== undefined) params.recommId = this.recommId;
74 |
75 | if (this.additionalData !== undefined) params.additionalData = this.additionalData;
76 |
77 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
78 | return params;
79 | }
80 | }
81 |
82 | exports.AddPurchase = AddPurchase;
83 |
--------------------------------------------------------------------------------
/src/requests/add-rating.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * Adds a rating of the given item made by the given user.
10 | */
11 | class AddRating extends rqs.Request {
12 | /**
13 | * Construct the request
14 | * @param {string} userId - User who submitted the rating
15 | * @param {string} itemId - Rated item
16 | * @param {number} rating - Rating rescaled to interval [-1.0,1.0], where -1.0 means the worst rating possible, 0.0 means neutral, and 1.0 means absolutely positive rating. For example, in the case of 5-star evaluations, rating = (numStars-3)/2 formula may be used for the conversion.
17 | * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
18 | * - Allowed parameters:
19 | * - *timestamp*
20 | * - Type: string | number
21 | * - Description: UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
22 | * - *cascadeCreate*
23 | * - Type: boolean
24 | * - Description: Sets whether the given user/item should be created if not present in the database.
25 | * - *recommId*
26 | * - Type: string
27 | * - Description: If this rating is based on a recommendation request, `recommId` is the id of the clicked recommendation.
28 | * - *additionalData*
29 | * - Type: object
30 | * - Description: A dictionary of additional data for the interaction.
31 | */
32 | constructor(userId, itemId, rating, optional) {
33 | super('POST', '/ratings/', 9000, false);
34 | this.userId = userId;
35 | this.itemId = itemId;
36 | this.rating = rating;
37 | optional = optional || {};
38 | this.timestamp = optional.timestamp;
39 | this.cascadeCreate = optional.cascadeCreate;
40 | this.recommId = optional.recommId;
41 | this.additionalData = optional.additionalData;
42 | }
43 |
44 | /**
45 | * Get body parameters
46 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
47 | */
48 | bodyParameters() {
49 | const params = {};
50 | params.userId = this.userId;
51 | params.itemId = this.itemId;
52 | params.rating = this.rating;
53 |
54 | if (this.timestamp !== undefined) params.timestamp = this.timestamp;
55 |
56 | if (this.cascadeCreate !== undefined) params.cascadeCreate = this.cascadeCreate;
57 |
58 | if (this.recommId !== undefined) params.recommId = this.recommId;
59 |
60 | if (this.additionalData !== undefined) params.additionalData = this.additionalData;
61 |
62 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
63 | return params;
64 | }
65 | }
66 |
67 | exports.AddRating = AddRating;
68 |
--------------------------------------------------------------------------------
/src/requests/batch.js:
--------------------------------------------------------------------------------
1 | 'use strict';
2 | const rqs = require('./request');
3 |
4 | const sum_timeouts = (requests) => {
5 | return requests.map((r) => r.timeout).reduce((a, b) => a + b, 0);
6 | };
7 |
8 | /**
9 | * Batch processing allows you to submit any sequence of requests within a single HTTPS request.
10 | *
11 | * Any type of request from this SDK may be used in the Batch, and the Batch may combine different types of requests arbitrarily as well.
12 | *
13 | * Using Batch requests can be beneficial in situations such as synchronizing the catalog of items or uploading historical interaction data,
14 | * as sending the data in Batch is considerably faster than sending the individual requests (thanks to optimizations and reducing network and HTTPS overhead).
15 | *
16 | * @note The status code of the batch request itself is 200 even if the individual requests result in an error – you have to inspect the code values in the resulting array.
17 | */
18 | class Batch extends rqs.Request {
19 | /**
20 | * Construct the request
21 | * @param {Request[]} requests - Array containing the requests.
22 | * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
23 | * - Allowed parameters:
24 | * - *distinctRecomms*
25 | * - Type: boolean
26 | * - Description: Makes all the recommended items for a certain user distinct among multiple recommendation requests in the batch.
27 | */
28 | constructor(requests, optional) {
29 | super('POST', '/batch/', sum_timeouts(requests), true);
30 | this.requests = requests;
31 | optional = optional || {};
32 | this.distinctRecomms = optional.distinctRecomms;
33 | }
34 |
35 | /**
36 | * Get body parameters
37 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
38 | */
39 | bodyParameters() {
40 | const reqs = this.requests.map((r) => this._request_to_batch_object(r));
41 | const result = { requests: reqs };
42 |
43 | if (this.distinctRecomms !== undefined) result.distinctRecomms = this.distinctRecomms;
44 |
45 | return result;
46 | }
47 |
48 | _request_to_batch_object(req) {
49 | const bodyParameters = req.bodyParameters();
50 | return {
51 | method: req.method,
52 | path: req.path,
53 | params: Object.keys(bodyParameters).length ? bodyParameters : undefined,
54 | };
55 | }
56 | }
57 |
58 | exports.Batch = Batch;
59 |
--------------------------------------------------------------------------------
/src/requests/merge-users.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * Merges interactions (purchases, ratings, bookmarks, detail views ...) of two different users under a single user ID. This is especially useful for online e-commerce applications working with anonymous users identified by unique tokens such as the session ID. In such applications, it may often happen that a user owns a persistent account, yet accesses the system anonymously while, e.g., putting items into a shopping cart. At some point in time, such as when the user wishes to confirm the purchase, (s)he logs into the system using his/her username and password. The interactions made under anonymous session ID then become connected with the persistent account, and merging these two becomes desirable.
10 | * Merging happens between two users referred to as the *target* and the *source*. After the merge, all the interactions of the source user are attributed to the target user, and the source user is **deleted**.
11 | */
12 | class MergeUsers extends rqs.Request {
13 | /**
14 | * Construct the request
15 | * @param {string} targetUserId - ID of the target user.
16 | * @param {string} sourceUserId - ID of the source user.
17 | * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
18 | * - Allowed parameters:
19 | * - *cascadeCreate*
20 | * - Type: boolean
21 | * - Description: Sets whether the user *targetUserId* should be created if not present in the database.
22 | */
23 | constructor(targetUserId, sourceUserId, optional) {
24 | super(
25 | 'PUT',
26 | `/users/${encodeURIComponent(targetUserId)}/merge/${encodeURIComponent(sourceUserId)}`,
27 | 30000,
28 | false,
29 | );
30 | this.targetUserId = targetUserId;
31 | this.sourceUserId = sourceUserId;
32 | optional = optional || {};
33 | this.cascadeCreate = optional.cascadeCreate;
34 | }
35 |
36 | /**
37 | * Get body parameters
38 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
39 | */
40 | bodyParameters() {
41 | const params = {};
42 |
43 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
44 | return params;
45 | }
46 | }
47 |
48 | exports.MergeUsers = MergeUsers;
49 |
--------------------------------------------------------------------------------
/src/requests/recommend-item-segments-to-item-segment.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * 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.
10 | * Based on the used Segmentations, this endpoint can be used for example for:
11 | * - Recommending the related brands to particular brand
12 | * - Recommending the related brands to particular category
13 | * - Recommending the related artists to a particular genre (assuming songs are the Items)
14 | * 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.
15 | * The returned segments are sorted by relevance (first segment being the most relevant).
16 | * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
17 | */
18 | class RecommendItemSegmentsToItemSegment extends rqs.Request {
19 | /**
20 | * Construct the request
21 | * @param {string} contextSegmentId - ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.
22 | * @param {string} targetUserId - ID of the user who will see the recommendations.
23 | * Specifying the *targetUserId* is beneficial because:
24 | * * It makes the recommendations personalized
25 | * * Allows the calculation of Actions and Conversions
26 | * in the graphical user interface,
27 | * as Recombee can pair the user who got recommendations
28 | * and who afterward viewed/purchased an item.
29 | * If you insist on not specifying the user, pass `null`
30 | * (`None`, `nil`, `NULL` etc., depending on the language) to *targetUserId*.
31 | * Do not create some special dummy user for getting recommendations,
32 | * as it could mislead the recommendation models,
33 | * and result in wrong recommendations.
34 | * For anonymous/unregistered users, it is possible to use, for example, their session ID.
35 | * @param {number} count - Number of item segments 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 | * - *scenario*
39 | * - Type: string
40 | * - Description: Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
41 | * You can set various settings to the [scenario](https://docs.recombee.com/scenarios.html) 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.
42 | * 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.
43 | * - *cascadeCreate*
44 | * - Type: boolean
45 | * - Description: If the user 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 user, as the user will be already known to the system.
46 | * - *filter*
47 | * - Type: string
48 | * - Description: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended segments based on the `segmentationId`.
49 | * - *booster*
50 | * - Type: string
51 | * - Description: Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`.
52 | * - *logic*
53 | * - Type: string | object
54 | * - Description: Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
55 | * See [this section](https://docs.recombee.com/recommendation_logics.html) for a list of available logics and other details.
56 | * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
57 | * Logic can also be set to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
58 | * - *expertSettings*
59 | * - Type: object
60 | * - Description: Dictionary of custom options.
61 | * - *returnAbGroup*
62 | * - Type: boolean
63 | * - Description: If there is a custom AB-testing running, return the name of the group to which the request belongs.
64 | */
65 | constructor(contextSegmentId, targetUserId, count, optional) {
66 | super('POST', '/recomms/item-segments/item-segments/', 9000, false);
67 | this.contextSegmentId = contextSegmentId;
68 | this.targetUserId = targetUserId;
69 | this.count = count;
70 | optional = optional || {};
71 | this.scenario = optional.scenario;
72 | this.cascadeCreate = optional.cascadeCreate;
73 | this.filter = optional.filter;
74 | this.booster = optional.booster;
75 | this.logic = optional.logic;
76 | this.expertSettings = optional.expertSettings;
77 | this.returnAbGroup = optional.returnAbGroup;
78 | }
79 |
80 | /**
81 | * Get body parameters
82 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
83 | */
84 | bodyParameters() {
85 | const params = {};
86 | params.contextSegmentId = this.contextSegmentId;
87 | params.targetUserId = this.targetUserId;
88 | params.count = this.count;
89 |
90 | if (this.scenario !== undefined) params.scenario = this.scenario;
91 |
92 | if (this.cascadeCreate !== undefined) params.cascadeCreate = this.cascadeCreate;
93 |
94 | if (this.filter !== undefined) params.filter = this.filter;
95 |
96 | if (this.booster !== undefined) params.booster = this.booster;
97 |
98 | if (this.logic !== undefined) params.logic = this.logic;
99 |
100 | if (this.expertSettings !== undefined) params.expertSettings = this.expertSettings;
101 |
102 | if (this.returnAbGroup !== undefined) params.returnAbGroup = this.returnAbGroup;
103 |
104 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
105 | return params;
106 | }
107 | }
108 |
109 | exports.RecommendItemSegmentsToItemSegment = RecommendItemSegmentsToItemSegment;
110 |
--------------------------------------------------------------------------------
/src/requests/recommend-item-segments-to-item.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * Recommends Segments from a [Segmentation](https://docs.recombee.com/segmentations.html) that are the most relevant to a particular item.
10 | * Based on the used Segmentation, this endpoint can be used for example for:
11 | * - Recommending the related categories
12 | * - Recommending the related genres
13 | * - Recommending the related brands
14 | * - Recommending the related artists
15 | * You need to set the used Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.
16 | * The returned segments are sorted by relevance (first segment being the most relevant).
17 | * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
18 | */
19 | class RecommendItemSegmentsToItem extends rqs.Request {
20 | /**
21 | * Construct the request
22 | * @param {string} itemId - ID of the item for which the recommendations are to be generated.
23 | * @param {string} targetUserId - ID of the user who will see the recommendations.
24 | * Specifying the *targetUserId* is beneficial because:
25 | * * It makes the recommendations personalized
26 | * * Allows the calculation of Actions and Conversions
27 | * in the graphical user interface,
28 | * as Recombee can pair the user who got recommendations
29 | * and who afterward viewed/purchased an item.
30 | * If you insist on not specifying the user, pass `null`
31 | * (`None`, `nil`, `NULL` etc., depending on the language) to *targetUserId*.
32 | * Do not create some special dummy user for getting recommendations,
33 | * as it could mislead the recommendation models,
34 | * and result in wrong recommendations.
35 | * For anonymous/unregistered users, it is possible to use, for example, their session ID.
36 | * @param {number} count - Number of item segments to be recommended (N for the top-N recommendation).
37 | * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
38 | * - Allowed parameters:
39 | * - *scenario*
40 | * - Type: string
41 | * - Description: Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
42 | * You can set various settings to the [scenario](https://docs.recombee.com/scenarios.html) 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.
43 | * 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.
44 | * - *cascadeCreate*
45 | * - Type: boolean
46 | * - Description: If the user 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 user, as the user will be already known to the system.
47 | * - *filter*
48 | * - Type: string
49 | * - Description: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended segments based on the `segmentationId`.
50 | * - *booster*
51 | * - Type: string
52 | * - Description: Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`.
53 | * - *logic*
54 | * - Type: string | object
55 | * - Description: Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
56 | * See [this section](https://docs.recombee.com/recommendation_logics.html) for a list of available logics and other details.
57 | * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
58 | * Logic can also be set to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
59 | * - *expertSettings*
60 | * - Type: object
61 | * - Description: Dictionary of custom options.
62 | * - *returnAbGroup*
63 | * - Type: boolean
64 | * - Description: If there is a custom AB-testing running, return the name of the group to which the request belongs.
65 | */
66 | constructor(itemId, targetUserId, count, optional) {
67 | super('POST', `/recomms/items/${encodeURIComponent(itemId)}/item-segments/`, 9000, false);
68 | this.itemId = itemId;
69 | this.targetUserId = targetUserId;
70 | this.count = count;
71 | optional = optional || {};
72 | this.scenario = optional.scenario;
73 | this.cascadeCreate = optional.cascadeCreate;
74 | this.filter = optional.filter;
75 | this.booster = optional.booster;
76 | this.logic = optional.logic;
77 | this.expertSettings = optional.expertSettings;
78 | this.returnAbGroup = optional.returnAbGroup;
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 | const params = {};
87 | params.targetUserId = this.targetUserId;
88 | params.count = this.count;
89 |
90 | if (this.scenario !== undefined) params.scenario = this.scenario;
91 |
92 | if (this.cascadeCreate !== undefined) params.cascadeCreate = this.cascadeCreate;
93 |
94 | if (this.filter !== undefined) params.filter = this.filter;
95 |
96 | if (this.booster !== undefined) params.booster = this.booster;
97 |
98 | if (this.logic !== undefined) params.logic = this.logic;
99 |
100 | if (this.expertSettings !== undefined) params.expertSettings = this.expertSettings;
101 |
102 | if (this.returnAbGroup !== undefined) params.returnAbGroup = this.returnAbGroup;
103 |
104 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
105 | return params;
106 | }
107 | }
108 |
109 | exports.RecommendItemSegmentsToItem = RecommendItemSegmentsToItem;
110 |
--------------------------------------------------------------------------------
/src/requests/recommend-item-segments-to-user.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * Recommends the top Segments from a [Segmentation](https://docs.recombee.com/segmentations.html) for a particular user, based on the user's past interactions.
10 | * Based on the used Segmentation, this endpoint can be used for example for:
11 | * - Recommending the top categories for the user
12 | * - Recommending the top genres for the user
13 | * - Recommending the top brands for the user
14 | * - Recommending the top artists for the user
15 | * You need to set the used Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.
16 | * The returned segments are sorted by relevance (first segment being the most relevant).
17 | * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
18 | */
19 | class RecommendItemSegmentsToUser extends rqs.Request {
20 | /**
21 | * Construct the request
22 | * @param {string} userId - ID of the user for whom personalized recommendations are to be generated.
23 | * @param {number} count - Number of item segments to be recommended (N for the top-N recommendation).
24 | * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
25 | * - Allowed parameters:
26 | * - *scenario*
27 | * - Type: string
28 | * - Description: Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
29 | * You can set various settings to the [scenario](https://docs.recombee.com/scenarios.html) 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.
30 | * 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.
31 | * - *cascadeCreate*
32 | * - Type: boolean
33 | * - Description: If the user 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 user, as the user will be already known to the system.
34 | * - *filter*
35 | * - Type: string
36 | * - Description: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended segments based on the `segmentationId`.
37 | * - *booster*
38 | * - Type: string
39 | * - Description: Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`.
40 | * - *logic*
41 | * - Type: string | object
42 | * - Description: Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
43 | * See [this section](https://docs.recombee.com/recommendation_logics.html) for a list of available logics and other details.
44 | * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
45 | * Logic can also be set to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
46 | * - *expertSettings*
47 | * - Type: object
48 | * - Description: Dictionary of custom options.
49 | * - *returnAbGroup*
50 | * - Type: boolean
51 | * - Description: If there is a custom AB-testing running, return the name of the group to which the request belongs.
52 | */
53 | constructor(userId, count, optional) {
54 | super('POST', `/recomms/users/${encodeURIComponent(userId)}/item-segments/`, 9000, false);
55 | this.userId = userId;
56 | this.count = count;
57 | optional = optional || {};
58 | this.scenario = optional.scenario;
59 | this.cascadeCreate = optional.cascadeCreate;
60 | this.filter = optional.filter;
61 | this.booster = optional.booster;
62 | this.logic = optional.logic;
63 | this.expertSettings = optional.expertSettings;
64 | this.returnAbGroup = optional.returnAbGroup;
65 | }
66 |
67 | /**
68 | * Get body parameters
69 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
70 | */
71 | bodyParameters() {
72 | const params = {};
73 | params.count = this.count;
74 |
75 | if (this.scenario !== undefined) params.scenario = this.scenario;
76 |
77 | if (this.cascadeCreate !== undefined) params.cascadeCreate = this.cascadeCreate;
78 |
79 | if (this.filter !== undefined) params.filter = this.filter;
80 |
81 | if (this.booster !== undefined) params.booster = this.booster;
82 |
83 | if (this.logic !== undefined) params.logic = this.logic;
84 |
85 | if (this.expertSettings !== undefined) params.expertSettings = this.expertSettings;
86 |
87 | if (this.returnAbGroup !== undefined) params.returnAbGroup = this.returnAbGroup;
88 |
89 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
90 | return params;
91 | }
92 | }
93 |
94 | exports.RecommendItemSegmentsToUser = RecommendItemSegmentsToUser;
95 |
--------------------------------------------------------------------------------
/src/requests/recommend-items-to-item-segment.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * Recommends Items that are the most relevant to a particular Segment from a context [Segmentation](https://docs.recombee.com/segmentations.html).
10 | * Based on the used Segmentation, this endpoint can be used for example for:
11 | * - Recommending articles related to a particular topic
12 | * - Recommending songs belonging to a particular genre
13 | * - Recommending products produced by a particular brand
14 | * 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.
15 | * The returned items are sorted by relevance (the first item being the most relevant).
16 | * 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.
17 | */
18 | class RecommendItemsToItemSegment extends rqs.Request {
19 | /**
20 | * Construct the request
21 | * @param {string} contextSegmentId - ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.
22 | * @param {string} targetUserId - ID of the user who will see the recommendations.
23 | * Specifying the *targetUserId* is beneficial because:
24 | * * It makes the recommendations personalized
25 | * * Allows the calculation of Actions and Conversions
26 | * in the graphical user interface,
27 | * as Recombee can pair the user who got recommendations
28 | * and who afterward viewed/purchased an item.
29 | * If you insist on not specifying the user, pass `null`
30 | * (`None`, `nil`, `NULL` etc., depending on the language) to *targetUserId*.
31 | * Do not create some special dummy user for getting recommendations,
32 | * as it could mislead the recommendation models,
33 | * and result in wrong recommendations.
34 | * For anonymous/unregistered users, it is possible to use, for example, their session ID.
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 | * - *scenario*
39 | * - Type: string
40 | * - Description: Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
41 | * You can set various settings to the [scenario](https://docs.recombee.com/scenarios.html) 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.
42 | * 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.
43 | * - *cascadeCreate*
44 | * - Type: boolean
45 | * - Description: 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.
46 | * - *returnProperties*
47 | * - Type: boolean
48 | * - 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.
49 | * Example response:
50 | * ```json
51 | * {
52 | * "recommId": "0c6189e7-dc1a-429a-b613-192696309361",
53 | * "recomms":
54 | * [
55 | * {
56 | * "id": "tv-178",
57 | * "values": {
58 | * "description": "4K TV with 3D feature",
59 | * "categories": ["Electronics", "Televisions"],
60 | * "price": 342,
61 | * "url": "myshop.com/tv-178"
62 | * }
63 | * },
64 | * {
65 | * "id": "mixer-42",
66 | * "values": {
67 | * "description": "Stainless Steel Mixer",
68 | * "categories": ["Home & Kitchen"],
69 | * "price": 39,
70 | * "url": "myshop.com/mixer-42"
71 | * }
72 | * }
73 | * ],
74 | * "numberNextRecommsCalls": 0
75 | * }
76 | * ```
77 | * - *includedProperties*
78 | * - Type: string[]
79 | * - Description: Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.
80 | * Example response for `includedProperties=description,price`:
81 | * ```json
82 | * {
83 | * "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80",
84 | * "recomms":
85 | * [
86 | * {
87 | * "id": "tv-178",
88 | * "values": {
89 | * "description": "4K TV with 3D feature",
90 | * "price": 342
91 | * }
92 | * },
93 | * {
94 | * "id": "mixer-42",
95 | * "values": {
96 | * "description": "Stainless Steel Mixer",
97 | * "price": 39
98 | * }
99 | * }
100 | * ],
101 | * "numberNextRecommsCalls": 0
102 | * }
103 | * ```
104 | * - *filter*
105 | * - Type: string
106 | * - Description: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression, which allows you to filter recommended items based on the values of their attributes.
107 | * Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
108 | * - *booster*
109 | * - Type: string
110 | * - Description: 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.
111 | * Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
112 | * - *logic*
113 | * - Type: string | object
114 | * - Description: Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
115 | * See [this section](https://docs.recombee.com/recommendation_logics.html) for a list of available logics and other details.
116 | * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
117 | * Logic can also be set to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
118 | * - *minRelevance*
119 | * - Type: string
120 | * - 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.
121 | * - *rotationRate*
122 | * - Type: number
123 | * - Description: **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.
124 | * - *rotationTime*
125 | * - Type: number
126 | * - Description: **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.
127 | * - *expertSettings*
128 | * - Type: object
129 | * - Description: Dictionary of custom options.
130 | * - *returnAbGroup*
131 | * - Type: boolean
132 | * - Description: If there is a custom AB-testing running, return the name of the group to which the request belongs.
133 | */
134 | constructor(contextSegmentId, targetUserId, count, optional) {
135 | super('POST', '/recomms/item-segments/items/', 9000, false);
136 | this.contextSegmentId = contextSegmentId;
137 | this.targetUserId = targetUserId;
138 | this.count = count;
139 | optional = optional || {};
140 | this.scenario = optional.scenario;
141 | this.cascadeCreate = optional.cascadeCreate;
142 | this.returnProperties = optional.returnProperties;
143 | this.includedProperties = optional.includedProperties;
144 | this.filter = optional.filter;
145 | this.booster = optional.booster;
146 | this.logic = optional.logic;
147 | this.minRelevance = optional.minRelevance;
148 | this.rotationRate = optional.rotationRate;
149 | this.rotationTime = optional.rotationTime;
150 | this.expertSettings = optional.expertSettings;
151 | this.returnAbGroup = optional.returnAbGroup;
152 | }
153 |
154 | /**
155 | * Get body parameters
156 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
157 | */
158 | bodyParameters() {
159 | const params = {};
160 | params.contextSegmentId = this.contextSegmentId;
161 | params.targetUserId = this.targetUserId;
162 | params.count = this.count;
163 |
164 | if (this.scenario !== undefined) params.scenario = this.scenario;
165 |
166 | if (this.cascadeCreate !== undefined) params.cascadeCreate = this.cascadeCreate;
167 |
168 | if (this.returnProperties !== undefined) params.returnProperties = this.returnProperties;
169 |
170 | if (this.includedProperties !== undefined) params.includedProperties = this.includedProperties;
171 |
172 | if (this.filter !== undefined) params.filter = this.filter;
173 |
174 | if (this.booster !== undefined) params.booster = this.booster;
175 |
176 | if (this.logic !== undefined) params.logic = this.logic;
177 |
178 | if (this.minRelevance !== undefined) params.minRelevance = this.minRelevance;
179 |
180 | if (this.rotationRate !== undefined) params.rotationRate = this.rotationRate;
181 |
182 | if (this.rotationTime !== undefined) params.rotationTime = this.rotationTime;
183 |
184 | if (this.expertSettings !== undefined) params.expertSettings = this.expertSettings;
185 |
186 | if (this.returnAbGroup !== undefined) params.returnAbGroup = this.returnAbGroup;
187 |
188 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
189 | return params;
190 | }
191 | }
192 |
193 | exports.RecommendItemsToItemSegment = RecommendItemsToItemSegment;
194 |
--------------------------------------------------------------------------------
/src/requests/recommend-items-to-item.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * Recommends a set of items that are somehow related to one given item, *X*. A typical scenario is when the user *A* is viewing *X*. Then you may display items to the user that he might also be interested in. Recommend items to item request gives you Top-N such items, optionally taking the target user *A* into account.
10 | * The returned items are sorted by relevance (the first item being the most relevant).
11 | * Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to:
12 | * - Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui.html#reported-metrics).
13 | * - Get subsequent recommended items when the user scrolls down (*infinite scroll*) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api.html#recommend-next-items).
14 | * It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.
15 | */
16 | class RecommendItemsToItem extends rqs.Request {
17 | /**
18 | * Construct the request
19 | * @param {string} itemId - ID of the item for which the recommendations are to be generated.
20 | * @param {string} targetUserId - ID of the user who will see the recommendations.
21 | * Specifying the *targetUserId* is beneficial because:
22 | * * It makes the recommendations personalized
23 | * * Allows the calculation of Actions and Conversions
24 | * in the graphical user interface,
25 | * as Recombee can pair the user who got recommendations
26 | * and who afterward viewed/purchased an item.
27 | * If you insist on not specifying the user, pass `null`
28 | * (`None`, `nil`, `NULL` etc., depending on the language) to *targetUserId*.
29 | * Do not create some special dummy user for getting recommendations,
30 | * as it could mislead the recommendation models,
31 | * and result in wrong recommendations.
32 | * For anonymous/unregistered users, it is possible to use, for example, their session ID.
33 | * @param {number} count - Number of items to be recommended (N for the top-N recommendation).
34 | * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
35 | * - Allowed parameters:
36 | * - *scenario*
37 | * - Type: string
38 | * - Description: Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
39 | * You can set various settings to the [scenario](https://docs.recombee.com/scenarios.html) 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.
40 | * 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.
41 | * - *cascadeCreate*
42 | * - Type: boolean
43 | * - Description: 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.
44 | * - *returnProperties*
45 | * - Type: boolean
46 | * - 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.
47 | * Example response:
48 | * ```json
49 | * {
50 | * "recommId": "0c6189e7-dc1a-429a-b613-192696309361",
51 | * "recomms":
52 | * [
53 | * {
54 | * "id": "tv-178",
55 | * "values": {
56 | * "description": "4K TV with 3D feature",
57 | * "categories": ["Electronics", "Televisions"],
58 | * "price": 342,
59 | * "url": "myshop.com/tv-178"
60 | * }
61 | * },
62 | * {
63 | * "id": "mixer-42",
64 | * "values": {
65 | * "description": "Stainless Steel Mixer",
66 | * "categories": ["Home & Kitchen"],
67 | * "price": 39,
68 | * "url": "myshop.com/mixer-42"
69 | * }
70 | * }
71 | * ],
72 | * "numberNextRecommsCalls": 0
73 | * }
74 | * ```
75 | * - *includedProperties*
76 | * - Type: string[]
77 | * - Description: Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.
78 | * Example response for `includedProperties=description,price`:
79 | * ```json
80 | * {
81 | * "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80",
82 | * "recomms":
83 | * [
84 | * {
85 | * "id": "tv-178",
86 | * "values": {
87 | * "description": "4K TV with 3D feature",
88 | * "price": 342
89 | * }
90 | * },
91 | * {
92 | * "id": "mixer-42",
93 | * "values": {
94 | * "description": "Stainless Steel Mixer",
95 | * "price": 39
96 | * }
97 | * }
98 | * ],
99 | * "numberNextRecommsCalls": 0
100 | * }
101 | * ```
102 | * - *filter*
103 | * - Type: string
104 | * - Description: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression, which allows you to filter recommended items based on the values of their attributes.
105 | * Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
106 | * - *booster*
107 | * - Type: string
108 | * - Description: 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.
109 | * Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
110 | * - *logic*
111 | * - Type: string | object
112 | * - Description: Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
113 | * See [this section](https://docs.recombee.com/recommendation_logics.html) for a list of available logics and other details.
114 | * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
115 | * Logic can also be set to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
116 | * - *userImpact*
117 | * - Type: number
118 | * - 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`.
119 | * - *diversity*
120 | * - Type: number
121 | * - 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.
122 | * - *minRelevance*
123 | * - Type: string
124 | * - 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.
125 | * - *rotationRate*
126 | * - Type: number
127 | * - Description: **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.
128 | * - *rotationTime*
129 | * - Type: number
130 | * - Description: **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.
131 | * - *expertSettings*
132 | * - Type: object
133 | * - Description: Dictionary of custom options.
134 | * - *returnAbGroup*
135 | * - Type: boolean
136 | * - Description: If there is a custom AB-testing running, return the name of the group to which the request belongs.
137 | */
138 | constructor(itemId, targetUserId, count, optional) {
139 | super('POST', `/recomms/items/${encodeURIComponent(itemId)}/items/`, 9000, false);
140 | this.itemId = itemId;
141 | this.targetUserId = targetUserId;
142 | this.count = count;
143 | optional = optional || {};
144 | this.scenario = optional.scenario;
145 | this.cascadeCreate = optional.cascadeCreate;
146 | this.returnProperties = optional.returnProperties;
147 | this.includedProperties = optional.includedProperties;
148 | this.filter = optional.filter;
149 | this.booster = optional.booster;
150 | this.logic = optional.logic;
151 | this.userImpact = optional.userImpact;
152 | this.diversity = optional.diversity;
153 | this.minRelevance = optional.minRelevance;
154 | this.rotationRate = optional.rotationRate;
155 | this.rotationTime = optional.rotationTime;
156 | this.expertSettings = optional.expertSettings;
157 | this.returnAbGroup = optional.returnAbGroup;
158 | }
159 |
160 | /**
161 | * Get body parameters
162 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
163 | */
164 | bodyParameters() {
165 | const params = {};
166 | params.targetUserId = this.targetUserId;
167 | params.count = this.count;
168 |
169 | if (this.scenario !== undefined) params.scenario = this.scenario;
170 |
171 | if (this.cascadeCreate !== undefined) params.cascadeCreate = this.cascadeCreate;
172 |
173 | if (this.returnProperties !== undefined) params.returnProperties = this.returnProperties;
174 |
175 | if (this.includedProperties !== undefined) params.includedProperties = this.includedProperties;
176 |
177 | if (this.filter !== undefined) params.filter = this.filter;
178 |
179 | if (this.booster !== undefined) params.booster = this.booster;
180 |
181 | if (this.logic !== undefined) params.logic = this.logic;
182 |
183 | if (this.userImpact !== undefined) params.userImpact = this.userImpact;
184 |
185 | if (this.diversity !== undefined) params.diversity = this.diversity;
186 |
187 | if (this.minRelevance !== undefined) params.minRelevance = this.minRelevance;
188 |
189 | if (this.rotationRate !== undefined) params.rotationRate = this.rotationRate;
190 |
191 | if (this.rotationTime !== undefined) params.rotationTime = this.rotationTime;
192 |
193 | if (this.expertSettings !== undefined) params.expertSettings = this.expertSettings;
194 |
195 | if (this.returnAbGroup !== undefined) params.returnAbGroup = this.returnAbGroup;
196 |
197 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
198 | return params;
199 | }
200 | }
201 |
202 | exports.RecommendItemsToItem = RecommendItemsToItem;
203 |
--------------------------------------------------------------------------------
/src/requests/recommend-items-to-user.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * Based on the user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for the given user.
10 | * The most typical use cases are recommendations on the homepage, in some "Picked just for you" section, or in email.
11 | * The returned items are sorted by relevance (the first item being the most relevant).
12 | * Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to:
13 | * - Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui.html#reported-metrics).
14 | * - Get subsequent recommended items when the user scrolls down (*infinite scroll*) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api.html#recommend-next-items).
15 | * It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.
16 | */
17 | class RecommendItemsToUser extends rqs.Request {
18 | /**
19 | * Construct the request
20 | * @param {string} userId - ID of the user for whom personalized recommendations are to be generated.
21 | * @param {number} count - Number of items to be recommended (N for the top-N recommendation).
22 | * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
23 | * - Allowed parameters:
24 | * - *scenario*
25 | * - Type: string
26 | * - Description: Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
27 | * You can set various settings to the [scenario](https://docs.recombee.com/scenarios.html) 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.
28 | * 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.
29 | * - *cascadeCreate*
30 | * - Type: boolean
31 | * - Description: If the user 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 user, as the user will be already known to the system.
32 | * - *returnProperties*
33 | * - Type: boolean
34 | * - 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.
35 | * Example response:
36 | * ```json
37 | * {
38 | * "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
39 | * "recomms":
40 | * [
41 | * {
42 | * "id": "tv-178",
43 | * "values": {
44 | * "description": "4K TV with 3D feature",
45 | * "categories": ["Electronics", "Televisions"],
46 | * "price": 342,
47 | * "url": "myshop.com/tv-178"
48 | * }
49 | * },
50 | * {
51 | * "id": "mixer-42",
52 | * "values": {
53 | * "description": "Stainless Steel Mixer",
54 | * "categories": ["Home & Kitchen"],
55 | * "price": 39,
56 | * "url": "myshop.com/mixer-42"
57 | * }
58 | * }
59 | * ],
60 | * "numberNextRecommsCalls": 0
61 | * }
62 | * ```
63 | * - *includedProperties*
64 | * - Type: string[]
65 | * - Description: Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.
66 | * Example response for `includedProperties=description,price`:
67 | * ```json
68 | * {
69 | * "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b",
70 | * "recomms":
71 | * [
72 | * {
73 | * "id": "tv-178",
74 | * "values": {
75 | * "description": "4K TV with 3D feature",
76 | * "price": 342
77 | * }
78 | * },
79 | * {
80 | * "id": "mixer-42",
81 | * "values": {
82 | * "description": "Stainless Steel Mixer",
83 | * "price": 39
84 | * }
85 | * }
86 | * ],
87 | * "numberNextRecommsCalls": 0
88 | * }
89 | * ```
90 | * - *filter*
91 | * - Type: string
92 | * - Description: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression, which allows you to filter recommended items based on the values of their attributes.
93 | * Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
94 | * - *booster*
95 | * - Type: string
96 | * - Description: 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.
97 | * Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
98 | * - *logic*
99 | * - Type: string | object
100 | * - Description: Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
101 | * See [this section](https://docs.recombee.com/recommendation_logics.html) for a list of available logics and other details.
102 | * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
103 | * Logic can also be set to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
104 | * - *diversity*
105 | * - Type: number
106 | * - 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.
107 | * - *minRelevance*
108 | * - Type: string
109 | * - Description: **Expert option** 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 to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such a 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.
110 | * - *rotationRate*
111 | * - Type: number
112 | * - Description: **Expert option** 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. Default: `0`.
113 | * - *rotationTime*
114 | * - Type: number
115 | * - Description: **Expert option** 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. Default: `7200.0`.
116 | * - *expertSettings*
117 | * - Type: object
118 | * - Description: Dictionary of custom options.
119 | * - *returnAbGroup*
120 | * - Type: boolean
121 | * - Description: If there is a custom AB-testing running, return the name of the group to which the request belongs.
122 | */
123 | constructor(userId, count, optional) {
124 | super('POST', `/recomms/users/${encodeURIComponent(userId)}/items/`, 9000, false);
125 | this.userId = userId;
126 | this.count = count;
127 | optional = optional || {};
128 | this.scenario = optional.scenario;
129 | this.cascadeCreate = optional.cascadeCreate;
130 | this.returnProperties = optional.returnProperties;
131 | this.includedProperties = optional.includedProperties;
132 | this.filter = optional.filter;
133 | this.booster = optional.booster;
134 | this.logic = optional.logic;
135 | this.diversity = optional.diversity;
136 | this.minRelevance = optional.minRelevance;
137 | this.rotationRate = optional.rotationRate;
138 | this.rotationTime = optional.rotationTime;
139 | this.expertSettings = optional.expertSettings;
140 | this.returnAbGroup = optional.returnAbGroup;
141 | }
142 |
143 | /**
144 | * Get body parameters
145 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
146 | */
147 | bodyParameters() {
148 | const params = {};
149 | params.count = this.count;
150 |
151 | if (this.scenario !== undefined) params.scenario = this.scenario;
152 |
153 | if (this.cascadeCreate !== undefined) params.cascadeCreate = this.cascadeCreate;
154 |
155 | if (this.returnProperties !== undefined) params.returnProperties = this.returnProperties;
156 |
157 | if (this.includedProperties !== undefined) params.includedProperties = this.includedProperties;
158 |
159 | if (this.filter !== undefined) params.filter = this.filter;
160 |
161 | if (this.booster !== undefined) params.booster = this.booster;
162 |
163 | if (this.logic !== undefined) params.logic = this.logic;
164 |
165 | if (this.diversity !== undefined) params.diversity = this.diversity;
166 |
167 | if (this.minRelevance !== undefined) params.minRelevance = this.minRelevance;
168 |
169 | if (this.rotationRate !== undefined) params.rotationRate = this.rotationRate;
170 |
171 | if (this.rotationTime !== undefined) params.rotationTime = this.rotationTime;
172 |
173 | if (this.expertSettings !== undefined) params.expertSettings = this.expertSettings;
174 |
175 | if (this.returnAbGroup !== undefined) params.returnAbGroup = this.returnAbGroup;
176 |
177 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
178 | return params;
179 | }
180 | }
181 |
182 | exports.RecommendItemsToUser = RecommendItemsToUser;
183 |
--------------------------------------------------------------------------------
/src/requests/recommend-next-items.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * 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.
10 | * 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`).
11 | * The base request can be one of:
12 | * - [Recommend Items to Item](https://docs.recombee.com/api.html#recommend-items-to-item)
13 | * - [Recommend Items to User](https://docs.recombee.com/api.html#recommend-items-to-user)
14 | * - [Recommend Items to Item Segment](https://docs.recombee.com/api.html#recommend-items-to-item-segment)
15 | * - [Search Items](https://docs.recombee.com/api.html#search-items)
16 | * All the other parameters are inherited from the base request.
17 | * *Recommend next items* can be called many times for a single `recommId` and each call returns different (previously not recommended) items.
18 | * The number of *Recommend next items* calls performed so far is returned in the `numberNextRecommsCalls` field.
19 | * *Recommend next items* can be requested up to 30 minutes after the base request or a previous *Recommend next items* call.
20 | * For billing purposes, each call to *Recommend next items* is counted as a separate recommendation request.
21 | */
22 | class RecommendNextItems extends rqs.Request {
23 | /**
24 | * Construct the request
25 | * @param {string} recommId - ID of the base recommendation request for which next recommendations should be returned
26 | * @param {number} count - Number of items to be recommended
27 | */
28 | constructor(recommId, count) {
29 | super('POST', `/recomms/next/items/${encodeURIComponent(recommId)}`, 9000, false);
30 | this.recommId = recommId;
31 | this.count = count;
32 | }
33 |
34 | /**
35 | * Get body parameters
36 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
37 | */
38 | bodyParameters() {
39 | const params = {};
40 | params.count = this.count;
41 |
42 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
43 | return params;
44 | }
45 | }
46 |
47 | exports.RecommendNextItems = RecommendNextItems;
48 |
--------------------------------------------------------------------------------
/src/requests/request.js:
--------------------------------------------------------------------------------
1 | 'use strict';
2 |
3 | /**
4 | * Base class for all the requests
5 | */
6 | class Request {
7 | /**
8 | * Construct the basis of request
9 | * @param {string} method - GET/PUT/POST/DELETE
10 | * @param {string} path - Path to the endpoint
11 | * @param {number} timeout - Timeout in milliseconds
12 | * @param {boolean} ensureHttps - If true, always use HTTPS.
13 | */
14 | constructor(method, path, timeout, ensureHttps) {
15 | this.method = method;
16 | this.path = path;
17 | this.timeout = timeout;
18 | this.ensureHttps = ensureHttps;
19 | }
20 | }
21 |
22 | exports.Request = Request;
23 |
--------------------------------------------------------------------------------
/src/requests/search-item-segments.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * Full-text personalized search that returns Segments from a Segmentation. The results are based on the provided `searchQuery` and also on the user's past interactions (purchases, ratings, etc.).
10 | * Based on the used Segmentation, this endpoint can be used for example for:
11 | * - Searching within categories or brands
12 | * - Searching within genres or artists
13 | * For example if the user is searching for "iPhone" this endpoint can return "cell phones" category.
14 | * You need to set the used Segmentation the Admin UI in the Scenario settings prior to using this endpoint.
15 | * The returned segments are sorted by relevance (first segment being the most relevant).
16 | * It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
17 | */
18 | class SearchItemSegments extends rqs.Request {
19 | /**
20 | * Construct the request
21 | * @param {string} userId - ID of the user for whom personalized search will be performed.
22 | * @param {string} searchQuery - Search query provided by the user. It is used for the full-text search.
23 | * @param {number} count - Number of segments to be returned (N for the top-N results).
24 | * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
25 | * - Allowed parameters:
26 | * - *scenario*
27 | * - Type: string
28 | * - Description: Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
29 | * You can set various settings to the [scenario](https://docs.recombee.com/scenarios.html) 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.
30 | * 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.
31 | * - *cascadeCreate*
32 | * - Type: boolean
33 | * - Description: If the user 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 user, as the user will be already known to the system.
34 | * - *filter*
35 | * - Type: string
36 | * - Description: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended segments based on the `segmentationId`.
37 | * - *booster*
38 | * - Type: string
39 | * - Description: Number-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`.
40 | * - *logic*
41 | * - Type: string | object
42 | * - Description: Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
43 | * See [this section](https://docs.recombee.com/recommendation_logics.html) for a list of available logics and other details.
44 | * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
45 | * Logic can also be set to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
46 | * - *expertSettings*
47 | * - Type: object
48 | * - Description: Dictionary of custom options.
49 | * - *returnAbGroup*
50 | * - Type: boolean
51 | * - Description: If there is a custom AB-testing running, return the name of the group to which the request belongs.
52 | */
53 | constructor(userId, searchQuery, count, optional) {
54 | super('POST', `/search/users/${encodeURIComponent(userId)}/item-segments/`, 9000, false);
55 | this.userId = userId;
56 | this.searchQuery = searchQuery;
57 | this.count = count;
58 | optional = optional || {};
59 | this.scenario = optional.scenario;
60 | this.cascadeCreate = optional.cascadeCreate;
61 | this.filter = optional.filter;
62 | this.booster = optional.booster;
63 | this.logic = optional.logic;
64 | this.expertSettings = optional.expertSettings;
65 | this.returnAbGroup = optional.returnAbGroup;
66 | }
67 |
68 | /**
69 | * Get body parameters
70 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
71 | */
72 | bodyParameters() {
73 | const params = {};
74 | params.searchQuery = this.searchQuery;
75 | params.count = this.count;
76 |
77 | if (this.scenario !== undefined) params.scenario = this.scenario;
78 |
79 | if (this.cascadeCreate !== undefined) params.cascadeCreate = this.cascadeCreate;
80 |
81 | if (this.filter !== undefined) params.filter = this.filter;
82 |
83 | if (this.booster !== undefined) params.booster = this.booster;
84 |
85 | if (this.logic !== undefined) params.logic = this.logic;
86 |
87 | if (this.expertSettings !== undefined) params.expertSettings = this.expertSettings;
88 |
89 | if (this.returnAbGroup !== undefined) params.returnAbGroup = this.returnAbGroup;
90 |
91 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
92 | return params;
93 | }
94 | }
95 |
96 | exports.SearchItemSegments = SearchItemSegments;
97 |
--------------------------------------------------------------------------------
/src/requests/search-items.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * 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).
10 | * All the string and set item properties are indexed by the search engine.
11 | * This endpoint should be used in a search box on your website/app. It can be called multiple times as the user is typing the query in order to get the most viable suggestions based on the current state of the query, or once after submitting the whole query.
12 | * The returned items are sorted by relevance (the first item being the most relevant).
13 | * Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to:
14 | * - Let Recombee know that this search was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui.html#reported-metrics).
15 | * - Get subsequent search results when the user scrolls down or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api.html#recommend-next-items).
16 | * It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.
17 | */
18 | class SearchItems extends rqs.Request {
19 | /**
20 | * Construct the request
21 | * @param {string} userId - ID of the user for whom personalized search will be performed.
22 | * @param {string} searchQuery - Search query provided by the user. It is used for the full-text search.
23 | * @param {number} count - Number of items to be returned (N for the top-N results).
24 | * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
25 | * - Allowed parameters:
26 | * - *scenario*
27 | * - Type: string
28 | * - Description: Scenario defines a particular search field in your user interface.
29 | * You can set various settings to the [scenario](https://docs.recombee.com/scenarios.html) 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 field performs.
30 | * 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.
31 | * - *cascadeCreate*
32 | * - Type: boolean
33 | * - Description: If the user does not exist in the database, returns a list of non-personalized search results and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.
34 | * - *returnProperties*
35 | * - Type: boolean
36 | * - 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.
37 | * Example response:
38 | * ```json
39 | * {
40 | * "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
41 | * "recomms":
42 | * [
43 | * {
44 | * "id": "tv-178",
45 | * "values": {
46 | * "description": "4K TV with 3D feature",
47 | * "categories": ["Electronics", "Televisions"],
48 | * "price": 342,
49 | * "url": "myshop.com/tv-178"
50 | * }
51 | * },
52 | * {
53 | * "id": "mixer-42",
54 | * "values": {
55 | * "description": "Stainless Steel Mixer",
56 | * "categories": ["Home & Kitchen"],
57 | * "price": 39,
58 | * "url": "myshop.com/mixer-42"
59 | * }
60 | * }
61 | * ],
62 | * "numberNextRecommsCalls": 0
63 | * }
64 | * ```
65 | * - *includedProperties*
66 | * - Type: string[]
67 | * - Description: Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.
68 | * Example response for `includedProperties=description,price`:
69 | * ```json
70 | * {
71 | * "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b",
72 | * "recomms":
73 | * [
74 | * {
75 | * "id": "tv-178",
76 | * "values": {
77 | * "description": "4K TV with 3D feature",
78 | * "price": 342
79 | * }
80 | * },
81 | * {
82 | * "id": "mixer-42",
83 | * "values": {
84 | * "description": "Stainless Steel Mixer",
85 | * "price": 39
86 | * }
87 | * }
88 | * ],
89 | * "numberNextRecommsCalls": 0
90 | * }
91 | * ```
92 | * - *filter*
93 | * - Type: string
94 | * - Description: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression, which allows you to filter recommended items based on the values of their attributes.
95 | * Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
96 | * - *booster*
97 | * - Type: string
98 | * - Description: 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.
99 | * Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
100 | * - *logic*
101 | * - Type: string | object
102 | * - Description: Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
103 | * See [this section](https://docs.recombee.com/recommendation_logics.html) for a list of available logics and other details.
104 | * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.
105 | * Logic can also be set to a [scenario](https://docs.recombee.com/scenarios.html) in the [Admin UI](https://admin.recombee.com).
106 | * - *expertSettings*
107 | * - Type: object
108 | * - Description: Dictionary of custom options.
109 | * - *returnAbGroup*
110 | * - Type: boolean
111 | * - Description: If there is a custom AB-testing running, return the name of the group to which the request belongs.
112 | */
113 | constructor(userId, searchQuery, count, optional) {
114 | super('POST', `/search/users/${encodeURIComponent(userId)}/items/`, 9000, false);
115 | this.userId = userId;
116 | this.searchQuery = searchQuery;
117 | this.count = count;
118 | optional = optional || {};
119 | this.scenario = optional.scenario;
120 | this.cascadeCreate = optional.cascadeCreate;
121 | this.returnProperties = optional.returnProperties;
122 | this.includedProperties = optional.includedProperties;
123 | this.filter = optional.filter;
124 | this.booster = optional.booster;
125 | this.logic = optional.logic;
126 | this.expertSettings = optional.expertSettings;
127 | this.returnAbGroup = optional.returnAbGroup;
128 | }
129 |
130 | /**
131 | * Get body parameters
132 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
133 | */
134 | bodyParameters() {
135 | const params = {};
136 | params.searchQuery = this.searchQuery;
137 | params.count = this.count;
138 |
139 | if (this.scenario !== undefined) params.scenario = this.scenario;
140 |
141 | if (this.cascadeCreate !== undefined) params.cascadeCreate = this.cascadeCreate;
142 |
143 | if (this.returnProperties !== undefined) params.returnProperties = this.returnProperties;
144 |
145 | if (this.includedProperties !== undefined) params.includedProperties = this.includedProperties;
146 |
147 | if (this.filter !== undefined) params.filter = this.filter;
148 |
149 | if (this.booster !== undefined) params.booster = this.booster;
150 |
151 | if (this.logic !== undefined) params.logic = this.logic;
152 |
153 | if (this.expertSettings !== undefined) params.expertSettings = this.expertSettings;
154 |
155 | if (this.returnAbGroup !== undefined) params.returnAbGroup = this.returnAbGroup;
156 |
157 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
158 | return params;
159 | }
160 | }
161 |
162 | exports.SearchItems = SearchItems;
163 |
--------------------------------------------------------------------------------
/src/requests/set-view-portion.js:
--------------------------------------------------------------------------------
1 | /*
2 | This file is auto-generated, do not edit
3 | */
4 |
5 | 'use strict';
6 | const rqs = require('./request');
7 |
8 | /**
9 | * Sets viewed portion of an item (for example a video or article) by a user (at a session).
10 | * If you send a new request with the same (`userId`, `itemId`, `sessionId`), the portion gets updated.
11 | */
12 | class SetViewPortion extends rqs.Request {
13 | /**
14 | * Construct the request
15 | * @param {string} userId - User who viewed a portion of the item
16 | * @param {string} itemId - Viewed item
17 | * @param {number} portion - Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the actual viewed part of the item, no matter the seeking. For example, if the user seeked immediately to half of the item and then viewed 10% of the item, the `portion` should still be `0.1`.
18 | * @param {Object} optional - Optional parameters given as an object with structure name of the parameter: value
19 | * - Allowed parameters:
20 | * - *sessionId*
21 | * - Type: string
22 | * - Description: ID of the session in which the user viewed the item. Default is `null` (`None`, `nil`, `NULL` etc., depending on the language).
23 | * - *timestamp*
24 | * - Type: string | number
25 | * - Description: UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
26 | * - *cascadeCreate*
27 | * - Type: boolean
28 | * - Description: Sets whether the given user/item should be created if not present in the database.
29 | * - *recommId*
30 | * - Type: string
31 | * - Description: If this view portion is based on a recommendation request, `recommId` is the id of the clicked recommendation.
32 | * - *additionalData*
33 | * - Type: object
34 | * - Description: A dictionary of additional data for the interaction.
35 | */
36 | constructor(userId, itemId, portion, optional) {
37 | super('POST', '/viewportions/', 9000, false);
38 | this.userId = userId;
39 | this.itemId = itemId;
40 | this.portion = portion;
41 | optional = optional || {};
42 | this.sessionId = optional.sessionId;
43 | this.timestamp = optional.timestamp;
44 | this.cascadeCreate = optional.cascadeCreate;
45 | this.recommId = optional.recommId;
46 | this.additionalData = optional.additionalData;
47 | }
48 |
49 | /**
50 | * Get body parameters
51 | * @return {Object} The values of body parameters (name of parameter: value of the parameter)
52 | */
53 | bodyParameters() {
54 | const params = {};
55 | params.userId = this.userId;
56 | params.itemId = this.itemId;
57 | params.portion = this.portion;
58 |
59 | if (this.sessionId !== undefined) params.sessionId = this.sessionId;
60 |
61 | if (this.timestamp !== undefined) params.timestamp = this.timestamp;
62 |
63 | if (this.cascadeCreate !== undefined) params.cascadeCreate = this.cascadeCreate;
64 |
65 | if (this.recommId !== undefined) params.recommId = this.recommId;
66 |
67 | if (this.additionalData !== undefined) params.additionalData = this.additionalData;
68 |
69 | params.cascadeCreate = this.cascadeCreate !== undefined ? this.cascadeCreate : true;
70 | return params;
71 | }
72 | }
73 |
74 | exports.SetViewPortion = SetViewPortion;
75 |
--------------------------------------------------------------------------------
/tests/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Recombee JS API Client Tests
6 |
7 |
8 |
9 |
10 |
11 |
12 |
13 |
14 |
15 |
16 |
--------------------------------------------------------------------------------
/tests/tests.js:
--------------------------------------------------------------------------------
1 | if (typeof recombee === 'undefined') {
2 | alert('recombee-js-api-client was not found.\n\nDid you run `pnpm build`?');
3 | }
4 |
5 | function createClient(useFetch = false) {
6 | return new recombee.ApiClient(
7 | 'tst-public-key',
8 | 'dIuCAwTeXn87m24HYE6uAIwSVzgEkTrQflrYlDBeIoeTIrhG1FVqj1v0h6u3nNSu',
9 | { region: 'eu-west', future_v6_fetch: useFetch },
10 | );
11 | }
12 |
13 | QUnit.module('Interactions', () => {
14 | function testInteractionPromise(assert, interactionReq) {
15 | assert.timeout(5000);
16 | const done = assert.async();
17 |
18 | const client = createClient();
19 | client
20 | .send(interactionReq)
21 | .then((res) => {
22 | assert.ok(res == 'ok', 'Interaction sent using Promise');
23 | done();
24 | })
25 | .catch((err) => {
26 | assert.notOk(err, 'Sending interaction should not throw');
27 | done();
28 | });
29 | }
30 |
31 | function testInteractionCallback(assert, interactionReq) {
32 | assert.timeout(5000);
33 | const done = assert.async();
34 |
35 | function callback(err, res) {
36 | if (err) {
37 | assert.notOk(err, 'Sending interaction should not throw');
38 | done();
39 | } else {
40 | assert.ok(res == 'ok', 'Interaction sent using callback');
41 | done();
42 | }
43 | }
44 |
45 | const client = createClient();
46 | client.send(interactionReq, callback);
47 | }
48 |
49 | function testInteractionFetch(assert, interactionReq) {
50 | assert.timeout(5000);
51 | const done = assert.async();
52 |
53 | const client = createClient(true);
54 | client
55 | .send(interactionReq)
56 | .then((res) => {
57 | assert.ok(res == 'ok', 'Interaction sent using fetch');
58 | done();
59 | })
60 | .catch((err) => {
61 | assert.notOk(err, 'Sending interaction should not throw');
62 | done();
63 | });
64 | }
65 |
66 | function testInteraction(assert, getInteraction) {
67 | testInteractionPromise(assert, getInteraction('test-promise'));
68 | testInteractionCallback(assert, getInteraction('test-callback'));
69 | testInteractionFetch(assert, getInteraction('test-fetch'));
70 | }
71 |
72 | QUnit.test('AddBookmark test', (assert) => {
73 | testInteraction(assert, (testName) => new recombee.AddBookmark('user-1', testName));
74 | });
75 |
76 | QUnit.test('AddCartAddition test', (assert) => {
77 | testInteraction(assert, (testName) => new recombee.AddCartAddition('user-1', testName));
78 | });
79 |
80 | QUnit.test('AddDetailView test', (assert) => {
81 | testInteraction(assert, (testName) => new recombee.AddDetailView('user-1', testName));
82 | });
83 |
84 | QUnit.test('AddPurchase test', (assert) => {
85 | testInteraction(assert, (testName) => new recombee.AddPurchase('user-1', testName));
86 | });
87 |
88 | QUnit.test('AddRating test', (assert) => {
89 | testInteraction(assert, (testName) => new recombee.AddRating('user-1', testName, -1));
90 | });
91 |
92 | QUnit.test('SetViewPortion test', (assert) => {
93 | testInteraction(
94 | assert,
95 | (testName) =>
96 | new recombee.SetViewPortion(Math.random().toString(36).substring(7), testName, 0.1),
97 | );
98 | });
99 | });
100 |
101 | function testRecommendationsPromise(assert, recommendationReq) {
102 | assert.timeout(5000);
103 | const done = assert.async();
104 |
105 | const client = createClient();
106 | client
107 | .send(recommendationReq)
108 | .then((res) => {
109 | assert.equal(res.recomms.length, 5, 'Recommendations received using Promise');
110 | done();
111 | })
112 | .catch((err) => {
113 | assert.notOk(err, 'Getting recommendations should not throw');
114 | done();
115 | });
116 | }
117 |
118 | function testRecommendationsCallback(assert, recommendationReq) {
119 | assert.timeout(5000);
120 | const done = assert.async();
121 |
122 | function callback(err, res) {
123 | if (err) {
124 | assert.notOk(err, 'Getting recommendations should not throw');
125 | done();
126 | } else {
127 | assert.equal(res.recomms.length, 5, 'Recommendations received using callback');
128 | done();
129 | }
130 | }
131 |
132 | const client = createClient();
133 | client.send(recommendationReq, callback);
134 | }
135 |
136 | function testRecommendationsFetch(assert, recommendationReq) {
137 | assert.timeout(5000);
138 | const done = assert.async();
139 |
140 | const client = createClient(true);
141 | client
142 | .send(recommendationReq)
143 | .then((res) => {
144 | assert.equal(res.recomms.length, 5, 'Recommendations received using fetch');
145 | done();
146 | })
147 | .catch((err) => {
148 | assert.notOk(err, 'Getting recommendations should not throw');
149 | done();
150 | });
151 | }
152 |
153 | function testRecommendations(assert, recommendationReq) {
154 | testRecommendationsPromise(assert, recommendationReq);
155 | testRecommendationsCallback(assert, recommendationReq);
156 | testRecommendationsFetch(assert, recommendationReq);
157 | }
158 |
159 | QUnit.module('Recommendations', () => {
160 | QUnit.module('Items', () => {
161 | QUnit.test('RecommendItemsToUser test', (assert) => {
162 | testRecommendations(assert, new recombee.RecommendItemsToUser('user-1', 5));
163 | });
164 |
165 | QUnit.test('RecommendItemsToItem test', (assert) => {
166 | testRecommendations(assert, new recombee.RecommendItemsToItem('item-1', 'user-1', 5));
167 | });
168 |
169 | QUnit.test('RecommendItemsToItemSegment test', (assert) => {
170 | testRecommendations(
171 | assert,
172 | new recombee.RecommendItemsToItemSegment('5', 'user-1', 5, {
173 | scenario: 'i-to-is',
174 | }),
175 | );
176 | });
177 |
178 | QUnit.test('RecommendNextItems test', (assert) => {
179 | assert.timeout(5000);
180 | const done = assert.async();
181 | const client = createClient();
182 | client
183 | .send(new recombee.RecommendItemsToUser('user-1', 5, { returnProperties: true }))
184 | .then((res) => {
185 | testRecommendations(assert, new recombee.RecommendNextItems(res.recommId, 5));
186 | done();
187 | });
188 | });
189 | });
190 |
191 | QUnit.module('Item Segments', () => {
192 | QUnit.test('RecommendItemSegmentsToUser test', (assert) => {
193 | testRecommendations(
194 | assert,
195 | new recombee.RecommendItemSegmentsToUser('user-1', 5, {
196 | scenario: 'is-to-u',
197 | }),
198 | );
199 | });
200 |
201 | QUnit.test('RecommendItemSegmentsToItem test', (assert) => {
202 | testRecommendations(
203 | assert,
204 | new recombee.RecommendItemSegmentsToItem('item-1', 'user-1', 5, {
205 | scenario: 'is-to-i',
206 | }),
207 | );
208 | });
209 |
210 | QUnit.test('RecommendItemSegmentsToItemSegment test', (assert) => {
211 | testRecommendations(
212 | assert,
213 | new recombee.RecommendItemSegmentsToItemSegment('5', 'user-1', 5, {
214 | scenario: 'is-to-is',
215 | }),
216 | );
217 | });
218 | });
219 | });
220 |
221 | QUnit.module('Search', () => {
222 | QUnit.test('SearchItems test', (assert) => {
223 | testRecommendations(assert, new recombee.SearchItems('user-1', 'computer', 5));
224 | });
225 |
226 | QUnit.test('SearchItemSegments test', (assert) => {
227 | testRecommendations(
228 | assert,
229 | new recombee.SearchItemSegments('user-1', 'computer', 5, {
230 | scenario: 's-is',
231 | }),
232 | );
233 | });
234 | });
235 |
236 | QUnit.module('Batch', () => {
237 | function send(client, assert, done) {
238 | const req = new recombee.Batch([
239 | new recombee.AddBookmark('user-1', 'item-1'),
240 | new recombee.AddCartAddition('user-1', 'item-1'),
241 | new recombee.AddDetailView('user-1', 'item-1'),
242 | new recombee.AddPurchase('user-1', 'item-1'),
243 | new recombee.AddRating('user-1', 'item-1', -1),
244 | new recombee.RecommendItemsToUser('user-1', 5),
245 | new recombee.RecommendItemsToItem('item-1', 'user-1', 5),
246 | new recombee.RecommendItemsToItemSegment('5', 'user-1', 5, {
247 | scenario: 'i-to-is',
248 | }),
249 | new recombee.RecommendItemSegmentsToUser('user-1', 5, {
250 | scenario: 'is-to-u',
251 | }),
252 | new recombee.RecommendItemSegmentsToItem('item-1', 'user-1', 5, {
253 | scenario: 'is-to-i',
254 | }),
255 | new recombee.RecommendItemSegmentsToItemSegment('5', 'user-1', 5, {
256 | scenario: 'is-to-is',
257 | }),
258 | new recombee.SearchItems('user-1', 'computer', 5),
259 | new recombee.SearchItemSegments('user-1', 'computer', 5, {
260 | scenario: 's-is',
261 | }),
262 | ]);
263 |
264 | client
265 | .send(req)
266 | .then((res) => {
267 | res.forEach((requestRes, idx) =>
268 | assert.ok(
269 | 200 <= requestRes.code && requestRes.code <= 299,
270 | `${req.requests[idx].path}: Response code 2XX = OK`,
271 | ),
272 | );
273 | done();
274 | })
275 | .catch((err) => {
276 | assert.notOk(err, 'Batch should not throw');
277 | done();
278 | });
279 | }
280 |
281 | QUnit.test('Using Promise', (assert) => {
282 | assert.timeout(5000);
283 | const done = assert.async();
284 |
285 | const client = createClient();
286 | send(client, assert, done);
287 | });
288 |
289 | QUnit.test('Using fetch', (assert) => {
290 | assert.timeout(5000);
291 | const done = assert.async();
292 |
293 | const client = createClient(true);
294 | send(client, assert, done);
295 | });
296 | });
297 |
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "compilerOptions": {
3 | "esModuleInterop": true,
4 | "skipLibCheck": false,
5 | "target": "es2022",
6 | "allowJs": true,
7 | "resolveJsonModule": true,
8 | "moduleDetection": "force",
9 | "isolatedModules": true,
10 | "verbatimModuleSyntax": true,
11 |
12 | "strict": true,
13 | "noUncheckedIndexedAccess": true,
14 | "noImplicitOverride": true,
15 |
16 | "module": "preserve",
17 | "noEmit": true,
18 |
19 | "lib": ["es2022", "dom", "dom.iterable"]
20 | }
21 | }
22 |
--------------------------------------------------------------------------------
/webpack.config.js:
--------------------------------------------------------------------------------
1 | const path = require('path');
2 |
3 | const commonConfig = {
4 | entry: './src/index.js', // Adjust this path if needed
5 | output: {
6 | path: path.resolve(__dirname, 'dist'),
7 | library: 'recombee',
8 | libraryTarget: 'umd',
9 | },
10 | module: {
11 | rules: [
12 | {
13 | test: /\.js$/,
14 | exclude: /node_modules/,
15 | use: {
16 | loader: 'babel-loader',
17 | options: {
18 | presets: ['@babel/preset-env'],
19 | },
20 | },
21 | },
22 | ],
23 | },
24 | resolve: {
25 | extensions: ['.js'],
26 | },
27 | };
28 |
29 | const minimizedConfig = {
30 | ...commonConfig,
31 | output: {
32 | ...commonConfig.output,
33 | filename: 'recombee-api-client.min.js',
34 | },
35 | mode: 'production',
36 | devtool: 'source-map', // Generates a source map for the minimized build
37 | };
38 |
39 | const nonMinimizedConfig = {
40 | ...commonConfig,
41 | output: {
42 | ...commonConfig.output,
43 | filename: 'recombee-api-client.js',
44 | },
45 | mode: 'development',
46 | devtool: 'source-map', // Generates a source map for the non-minimized build
47 | };
48 |
49 | module.exports = [minimizedConfig, nonMinimizedConfig];
50 |
--------------------------------------------------------------------------------
3 | 
