Browser SDK

Lightweight browser SDK focused on recommendations, real-time event tracking, and scenario attribution. Designed for client-side React, Vue, or vanilla JavaScript applications.

Installation

npm install @recomnext/browser

Setup

import { RecomnextBrowserClient } from '@recomnext/browser';

const recomnext = new RecomnextBrowserClient({
  baseUrl: '/api',          // API gateway or proxy
  tenantId: 'my-tenant',
  userId: 'user-123',       // Optional, sessionId used if missing
});

Unified Recommend API

// The preferred way to fetch recommendations
const response = await recomnext.recommend({
  scenario: 'homepage-for-you',
  count: 8,
  returnProperties: true,
  includedProperties: ['attributes.name', 'attributes.price', 'attributes.image', 'category'],
});

for (const item of response.items) {
  console.log(item.itemId);
}

Lean Projection Mode

// Lean mode for minimal payload transfer
const lean = await recomnext.recommend({
  scenario: 'pdp-similar',
  count: 10,
  returnProperties: false,
});

for (const item of lean.items) {
  const scoreLabel = item.score != null ? item.score.toFixed(2) : 'N/A';
  console.log(item.itemId, scoreLabel);
}

Signed Request Placement (publicToken)

Browser signing follows strict placement: GET recommendation routes sign projection in query, and POST items-to-items signs projection in the JSON body.

Omit projection keys for backward-compatible full payloads. Set returnProperties=false for lean identity-first payloads when your UI does not require attributes.

Event Tracking & Attribution

All tracking methods accept an optional `scenarioSlug` parameter. Providing this attributes the interaction to the specific recommendation scenario that surfaced the item, enabling full funnel analytics.

// Track item view with scenario attribution
recomnext.trackView('prod-001', 'homepage-for-you');

// Track cart addition
recomnext.trackCart('prod-001', 'pdp-related');

// Track purchase
recomnext.trackPurchase('prod-001', 'cart-upsell');

Impression Tracking

Uses `IntersectionObserver` to automatically detect when recommendation cards become visible. Impressions are batched and flushed every 2 seconds for efficiency.

const cleanup = recomnext.trackImpressions(document.querySelector('.recs'), {
  scenario: 'home-for-you',
  itemSelector: '[data-item-id]', // CSS selector for individual item cards
  threshold: 0.5,                // 50% visibility required
  once: true,                     // Only track the first time an item is seen
});

// Call cleanup when the component unmounts
cleanup();

Key Methods

Projection and Type Notes

Node.js SDK

Server-side Node.js/TypeScript SDK with built-in retry logic, timeouts, and full coverage of the engine REST API. Requires Node.js 18+ for native fetch support.

Installation

npm install @recomnext/node

Setup

import { RecomnextClient } from '@recomnext/node';

const client = new RecomnextClient({
  baseUrl: 'http://localhost:3000',
  tenantId: 'my-tenant',
  retries: 3,           // default: 3
  timeout: 10000,        // default: 10s
});

API Namespaces

Tenant settings APIs are currently documented in the HTTP API reference (GET/PUT /catalog/tenant-settings). The Node SDK catalog namespace does not yet expose dedicated helpers for these endpoints.

Bulk Ingestion Example

// Sync items to RecomNext
await client.ingestion.upsertItems([
  {
    externalId: 'prod-001', // catalog identity key (not deprecated for ingestion)
    category: 'electronics',
    attributes: {
      name: 'Smartphone Pro',
      price: 999.99,
      tags: ['5g', 'high-performance']
    }
  }
]);

// Log batch of interactions
await client.ingestion.logInteractions([
  { userId: 'user-1', itemId: 'prod-001', type: 'view' },
  { userId: 'user-2', itemId: 'prod-001', type: 'purchase', weight: 10 }
]);

Recommendation Projection Example

const response = await client.recommendations.recommend({
  scenario: 'pdp-similar',
  itemId: 'prod-001',
  count: 6,
  returnProperties: true,
  includedProperties: ['attributes.name', 'attributes.price', 'attributes.image', 'category'],
});

for (const item of response.items) {
  const scoreLabel = item.score != null ? item.score.toFixed(3) : 'N/A';
  console.log(item.itemId, scoreLabel);
}

Signed Request Placement Contract

When using signing tokens, SDKs keep projection placement aligned with engine verification: GET recommendation routes sign projection in query, while POST items-to-items signs projection in the request body.

Scenario Management Example

// Create a scenario programmatically
const scenario = await client.scenarios.create({
  name: 'Search Boosted Results',
  slug: 'search-boosted',
  logicType: 'user-to-item',
  filter: "'stock' > 0",
  boosters: ["boost by 1.5 where 'promo' = true"],
  constraints: { maxPerCategory: 2 }
});

// Update an existing scenario
await client.scenarios.update('search-boosted', {
  minItems: 4
});