{"id":16190,"library":"recombee-js-api-client","title":"Recombee JavaScript API Client","description":"The `recombee-js-api-client` is a client-side JavaScript SDK designed for seamless integration with the Recombee recommendation API. Currently at version 6.2.1, it provides a thin wrapper around the Recombee API, enabling applications to send user-item interactions (such as detail views, purchases, or cart additions) and request personalized recommendations or search results. The library exhibits an active release cadence, with multiple minor and major versions released recently, indicating ongoing development and improvements. Key differentiators include its UMD compatibility, built-in TypeScript definitions, and its specific design for browser-based or other client-side environments like React Native or NativeScript. It is crucial to note that this client-side SDK focuses on data collection and recommendation retrieval using a public token and does not support catalog management operations for security reasons, which are handled by a separate server-side Node.js SDK.","status":"active","version":"6.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/Recombee/js-api-client","tags":["javascript","recombee","recommendation engine","recommender engine","recommender as a service","machine learning","API","SDK","typescript"],"install":[{"cmd":"npm install recombee-js-api-client","lang":"bash","label":"npm"},{"cmd":"yarn add recombee-js-api-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add recombee-js-api-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library provides a default export object named `recombee` which contains all client classes and request constructors.","wrong":"import { recombee } from 'recombee-js-api-client';","symbol":"recombee","correct":"import recombee from 'recombee-js-api-client';"},{"note":"The `ApiClient` constructor is a property of the default `recombee` export, not a direct named export from the package. Access it as `recombee.ApiClient` after importing the default object.","wrong":"import { ApiClient } from 'recombee-js-api-client';","symbol":"ApiClient","correct":"import recombee from 'recombee-js-api-client'; const client = new recombee.ApiClient(...);"},{"note":"All interaction and recommendation request constructors (e.g., `AddDetailView`, `RecommendItemsToItem`, `Batch`) are properties of the default `recombee` export.","wrong":"import { AddDetailView } from 'recombee-js-api-client';","symbol":"AddDetailView (and other request types)","correct":"import recombee from 'recombee-js-api-client'; const request = new recombee.AddDetailView(...);"}],"quickstart":{"code":"import recombee from 'recombee-js-api-client';\n\nconst RECOMBEE_DATABASE_ID = process.env.RECOMBEE_DATABASE_ID ?? 'your-database-id';\nconst RECOMBEE_PUBLIC_TOKEN = process.env.RECOMBEE_PUBLIC_TOKEN ?? 'your-db-public-token';\nconst RECOMBEE_REGION = process.env.RECOMBEE_REGION ?? 'eu-west'; // e.g., 'us-west', 'eu-west'\n\n// Initialize the API client with your database ID and PUBLIC token\nexport const client = new recombee.ApiClient(\n  RECOMBEE_DATABASE_ID,\n  RECOMBEE_PUBLIC_TOKEN,\n  {\n    region: RECOMBEE_REGION,\n    // Optional: Increase default timeout if needed, e.g., 10 seconds\n    // timeout: 10000,\n  },\n);\n\n// Send interactions (e.g., AddDetailView, AddCartAddition, AddPurchase)\nclient.send(\n  new recombee.AddDetailView('user-4395', 'item-129', {\n    cascadeCreate: true, // Creates user/item if they don't exist\n    recommId: '23eaa09b-0e24-4487-ba9c-8e255feb01bb', // Optional: Link to a previous recommendation\n  }),\n).then(() => {\n  console.log('Detail view interaction sent successfully.');\n}).catch((error) => {\n  console.error('Failed to send detail view interaction:', error);\n});\n\n// Request recommendations (e.g., RecommendItemsToItem, RecommendItemsToUser)\nasync function getRecommendations() {\n  try {\n    const response = await client.send(\n      new recombee.RecommendItemsToItem('item-356', 'user-13434', 5, {\n        returnProperties: true, // Include item properties in the response\n        includedProperties: ['title', 'imageUrl'], // Specify which properties to return\n      }),\n    );\n\n    console.log('Recommendation ID:', response.recommId);\n\n    // The `recomms` array contains recommended items with their IDs and properties\n    response.recomms.forEach((item) => {\n      console.log(`Recommended Item ID: ${item.id}, Title: ${item.values?.title}, Image: ${item.values?.imageUrl}`);\n    });\n  } catch (error) {\n    console.error('Error requesting recommendations:', error);\n    // Implement fallback logic here, e.g., show popular items\n  }\n}\n\ngetRecommendations();","lang":"typescript","description":"Demonstrates initializing the Recombee client, sending a user-item interaction (a detail view), and requesting item-to-item recommendations with specified properties, including basic error handling."},"warnings":[{"fix":"Always consult the official Recombee JavaScript API Client documentation for the relevant version's upgrade guide before performing a major version update.","message":"Major versions (e.g., v5.0.0, v6.0.0) often introduce breaking changes to the API client's interface, request parameters, or underlying API interactions. This can necessitate updates to your code when upgrading.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"For server-side Node.js applications or catalog management, use the dedicated `recombee-api-client` package. Ensure server-side logic handles all operations that require a private token.","message":"This library (`recombee-js-api-client`) is specifically designed for client-side (browser, mobile apps) usage. For server-side integrations, use the separate `recombee-api-client` Node.js library. Using the client-side SDK for sensitive operations like modifying the item catalog is not supported and will be prevented for security reasons.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Obtain and use your Recombee public token from the Admin UI for all client-side integrations. Private tokens are strictly for secure server-side environments.","message":"Ensure you are using your Recombee database's *public* token when initializing this client-side API client. Never expose your *private* token in client-side code, as it grants full administrative access to your Recombee database.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js environment to version 18 or newer to ensure compatibility and proper functioning of the library.","message":"Starting with versions in the 6.x series, this package requires Node.js version 18 or greater as specified in its `engines` field. Deployments on older Node.js versions may lead to installation failures or runtime issues.","severity":"breaking","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Import the default `recombee` object first (`import recombee from 'recombee-js-api-client';`), then access `ApiClient` as a property (`new recombee.ApiClient(...)`). If using CommonJS, use `const recombee = require('recombee-js-api-client');`.","cause":"Attempting to import `ApiClient` as a named export (`import { ApiClient } from 'recombee-js-api-client'`) or trying to use `require()` with incompatible syntax.","error":"TypeError: recombee.ApiClient is not a constructor"},{"fix":"Double-check your Recombee database ID and public token in the Recombee Admin UI. Ensure the public token is used for client-side applications and is still valid.","cause":"The provided database ID or public token is incorrect, expired, or a private token was mistakenly used client-side.","error":"Recombee API Error: Invalid token"},{"fix":"If using a `<script>` tag, verify the path to the `recombee-api-client.min.js` file and ensure it loads before any consuming scripts. If using a module bundler, ensure `import recombee from 'recombee-js-api-client';` is at the top of your file.","cause":"The library's global `recombee` object is not available, often due to an incorrect `<script>` tag path, improper loading order, or a module import being missed.","error":"ReferenceError: recombee is not defined"},{"fix":"Implement robust error handling with fallbacks for API requests. You can also increase the timeout duration by providing a `timeout` option during `ApiClient` initialization, e.g., `new recombee.ApiClient(dbId, token, { timeout: 10000 })` for a 10-second timeout.","cause":"The API request exceeded the default timeout period (typically 3 seconds) due to network latency, large data payloads, or high API load.","error":"Client did not get response within [X] ms"}],"ecosystem":"npm"}