Registry / ai-ml / recombee-js-api-client

recombee-js-api-client

JSON →
library6.2.1jsnpmunverified

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.

npm install recombee-js-api-client
INSTALL
IMPORT
SIG · RECOMBEE-JS-API-CL
R
recombee-js-api-client
ai-mljavascriptv6.2.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

recombee
import recombee from 'recombee-js-api-client';
import { recombee } from 'recombee-js-api-client';
The library provides a default export object named `recombee` which contains all client classes and request constructors.
ApiClient
import recombee from 'recombee-js-api-client'; const client = new recombee.ApiClient(...);
import { ApiClient } from 'recombee-js-api-client';
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.
AddDetailView (and other request types)
import recombee from 'recombee-js-api-client'; const request = new recombee.AddDetailView(...);
import { AddDetailView } from 'recombee-js-api-client';
All interaction and recommendation request constructors (e.g., `AddDetailView`, `RecommendItemsToItem`, `Batch`) are properties of the default `recombee` export.

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.

import recombee from 'recombee-js-api-client'; const RECOMBEE_DATABASE_ID = process.env.RECOMBEE_DATABASE_ID ?? 'your-database-id'; const RECOMBEE_PUBLIC_TOKEN = process.env.RECOMBEE_PUBLIC_TOKEN ?? 'your-db-public-token'; const RECOMBEE_REGION = process.env.RECOMBEE_REGION ?? 'eu-west'; // e.g., 'us-west', 'eu-west' // Initialize the API client with your database ID and PUBLIC token export const client = new recombee.ApiClient( RECOMBEE_DATABASE_ID, RECOMBEE_PUBLIC_TOKEN, { region: RECOMBEE_REGION, // Optional: Increase default timeout if needed, e.g., 10 seconds // timeout: 10000, }, ); // Send interactions (e.g., AddDetailView, AddCartAddition, AddPurchase) client.send( new recombee.AddDetailView('user-4395', 'item-129', { cascadeCreate: true, // Creates user/item if they don't exist recommId: '23eaa09b-0e24-4487-ba9c-8e255feb01bb', // Optional: Link to a previous recommendation }), ).then(() => { console.log('Detail view interaction sent successfully.'); }).catch((error) => { console.error('Failed to send detail view interaction:', error); }); // Request recommendations (e.g., RecommendItemsToItem, RecommendItemsToUser) async function getRecommendations() { try { const response = await client.send( new recombee.RecommendItemsToItem('item-356', 'user-13434', 5, { returnProperties: true, // Include item properties in the response includedProperties: ['title', 'imageUrl'], // Specify which properties to return }), ); console.log('Recommendation ID:', response.recommId); // The `recomms` array contains recommended items with their IDs and properties response.recomms.forEach((item) => { console.log(`Recommended Item ID: ${item.id}, Title: ${item.values?.title}, Image: ${item.values?.imageUrl}`); }); } catch (error) { console.error('Error requesting recommendations:', error); // Implement fallback logic here, e.g., show popular items } } getRecommendations();
Debug
Known issues
breakingMajor 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.
fix
Always consult the official Recombee JavaScript API Client documentation for the relevant version's upgrade guide before performing a major version update.
affects: >=5.0.0
gotchaThis 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.
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.
affects: >=1.0.0
gotchaEnsure 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.
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.
affects: >=1.0.0
breakingStarting 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.
fix
Upgrade your Node.js environment to version 18 or newer to ensure compatibility and proper functioning of the library.
affects: >=6.0.0
Errors
Common errors & fixes
TypeError: recombee.ApiClient is not a constructor
Attempting to import `ApiClient` as a named export (`import { ApiClient } from 'recombee-js-api-client'`) or trying to use `require()` with incompatible syntax.
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');`.
Recombee API Error: Invalid token
The provided database ID or public token is incorrect, expired, or a private token was mistakenly used client-side.
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.
ReferenceError: recombee is not defined
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.
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.
Client did not get response within [X] ms
The API request exceeded the default timeout period (typically 3 seconds) due to network latency, large data payloads, or high API load.
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.
Upgrade
Version history
6.2.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
1
Resources
recombee-js-api-client — npm install recombee-js-api-client · libregistry