JavaScript SDK - NeuronSearchLab

The SDK is a lightweight TypeScript client with built-in event batching, automatic retries, and structured logging for the NeuronSearchLab API.Need PHP instead? View the PHP SDK guide or install it from Packagist.

Installation

npm install @neuronsearchlab/sdk

The SDK ships with TypeScript declarations - no additional type packages needed.

Initialize the client

The SDK uses a Bearer token for authentication. Obtain an access token by exchanging your SDK credentials and pass it when creating the client:

import NeuronSDK from "@neuronsearchlab/sdk";

const sdk = new NeuronSDK({
  baseUrl: "https://api.neuronsearchlab.com/v1",
  accessToken: "<your_access_token>",
});

Configuration options

Option	Type	Default	Description
`baseUrl`	string	required	API base URL
`accessToken`	string	required	Bearer token from the auth token endpoint
`timeoutMs`	number	`10000`	HTTP request timeout in ms
`maxRetries`	number	`2`	Retry count on 429/5xx/timeouts
`collateWindowSeconds`	number	`3`	Buffer events for this many seconds before flushing
`maxBatchSize`	number	`200`	Flush immediately when buffer reaches this size
`maxBufferedEvents`	number	`5000`	Drop oldest events beyond this limit
`propagateRecommendationRequestId`	boolean	`true`	Auto-attach `request_id` from recommendations to subsequent events
`autoSessionId`	boolean	`true`	Auto-generate a session UUID

Get recommendations

const result = await sdk.getRecommendations({
  userId: "user-123",
  contextId: 101,
  limit: 10,
});

console.log(result.recommendations);
// [{ id, object, item_id, rank, score, item, metadata }, ...]

Each recommendation includes id, object, item_id, rank, score, and an embedded item object with the metadata you stored. The response also includes a request_id for event attribution.

Search

Use search when the user supplies a free-text query and you want ranked catalog items back through the Core API data plane:

const results = await sdk.search({
  query: "waterproof trail shoes",
  userId: "user-123",
  contextId: 101,
  limit: 10,
  filter: ["category:footwear"],
});

console.log(results.data);

The SDK posts to https://api.neuronsearchlab.com/v1/search, not the console Platform API. Search responses use the same item shape as recommendations and include query, request_id, data, and recommendations.

Search-to-click loop

For search-backed surfaces, treat search and events as one attribution loop:

Run search with the user’s query and optional context.
Render results from data or recommendations.
Capture request_id from the search response.
Send that requestId back with the click, view, or purchase event.

This keeps attribution tied to the exact result set the user saw.

const search = await sdk.search({
  query: "wireless headphones",
  userId: "user-123",
  limit: 8,
});

const first = search.data[0];

if (first) {
  await sdk.trackEvent({
    eventId: 42,
    userId: "user-123",
    itemId: first.item_id,
    requestId: search.request_id,
  });
}

Auto-generated sections

Use getAutoRecommendations for paginated, auto-titled recommendation sections - ideal for infinite-scroll feeds:

const section = await sdk.getAutoRecommendations({
  userId: "user-123",
  limit: 5,
  windowDays: 7,
});

console.log(section.section?.title);
// e.g. "Because you liked Running Shoes"

// Load next section
if (section.next_cursor) {
  const next = await sdk.getAutoRecommendations({
    userId: "user-123",
    cursor: section.next_cursor,
  });
}

Track events

Events provide the feedback loop that powers personalization. The SDK buffers events in memory and flushes them in batches for efficiency.

await sdk.trackEvent({
  eventId: 42,
  userId: "user-123",
  itemId: 3187,
});

How batching works

Buffer events

Events are buffered with a timestamp that maps to occurred_at in the API.

Flush on window or batch size

The buffer flushes when the collate window elapses (default 3s) or the buffer reaches maxBatchSize.

Flush during page unload

On page unload (beforeunload, pagehide), remaining events are flushed automatically.

Retry failed sends

Failed sends are retried with exponential backoff.

You can flush manually at any time:

await sdk.flushEvents();

Request ID propagation

When propagateRecommendationRequestId is enabled (the default), the SDK captures the request_id from getRecommendations() or search() and automatically attaches it to subsequent trackEvent() calls. This links events back to the result set that produced them.

const recs = await sdk.getRecommendations({ userId: "user-123", limit: 5 });

// request_id is auto-attached - no need to pass it
await sdk.trackEvent({
  eventId: 42,
  userId: "user-123",
  itemId: recs.recommendations[0].item_id,
});

Manage catalog items

Create an item

const item = await sdk.upsertItem({
  name: "Nike Running Shoes",
  description: "High-performance running shoes for daily training.",
  metadata: { category: "Footwear", brand: "Nike", price: 109.99 },
});

The description field is used to generate embeddings for similarity matching. NSL generates item.id; persist that integer alongside your source record.

Update an item

await sdk.patchItem({
  itemId: 3187,
  active: false, // disable the item
});

Or use the convenience helper:

await sdk.setItemActive(3187, false);

Delete items

await sdk.deleteItems({ itemId: 3187 });

// Batch delete
await sdk.deleteItems([
  { itemId: 3187 },
  { itemId: 3188 },
]);

Error handling

The SDK exports two error classes:

import NeuronSDK, { SDKHttpError, SDKTimeoutError } from "@neuronsearchlab/sdk";

try {
  await sdk.getRecommendations({ userId: "user-123" });
} catch (err) {
  if (err instanceof SDKHttpError) {
    console.error(`HTTP ${err.status}: ${err.statusText}`, err.body);
  } else if (err instanceof SDKTimeoutError) {
    console.error(`Request timed out after ${err.timeoutMs}ms`);
  }
}

Transient errors (429, 5xx, timeouts) are retried automatically with exponential backoff up to maxRetries times.

Logging

Configure structured logging for debugging and observability:

import { configureLogger } from "@neuronsearchlab/sdk";

configureLogger({
  level: "DEBUG",
  enableNetworkBodyLogging: true,
  enablePerformanceLogging: true,
});

Available log levels: TRACE, DEBUG, INFO (default), WARN, ERROR, FATAL. You can also provide a custom transport to send logs to your own logging infrastructure:

configureLogger({
  level: "WARN",
  transport: (entry) => {
    // entry: { level, message, timestamp, context }
    myLogger.log(entry);
  },
});

Session management

The SDK auto-generates a session UUID on initialization (when autoSessionId is true). All events include the session ID automatically. You can override or read it:

sdk.setSessionId("custom-session-id");
console.log(sdk.getSessionId());

Next steps

View the PHP SDK guide if you are integrating from Laravel or another PHP service.
View the API documentation for the underlying REST endpoints.
Set up the MCP integration to use NeuronSearchLab from AI assistants like Claude.
Reach out to contact@neuronsearchlab.com if you need help.

​Installation

​Initialize the client

​Configuration options

​Get recommendations

​Search

​Search-to-click loop

​Auto-generated sections

​Track events

​How batching works

​Request ID propagation

​Manage catalog items

​Create an item

​Update an item

​Delete items

​Error handling

​Logging

​Session management

​Next steps

Installation

Initialize the client

Configuration options

Get recommendations

Search

Search-to-click loop

Auto-generated sections

Track events

How batching works

Request ID propagation

Manage catalog items

Create an item

Update an item

Delete items

Error handling

Logging

Session management

Next steps