Skip to main content

​
Installation

npm install @alana-shopping/search-sdk

​
Quick Start

import { AlanaSearchClient } from "@alana-shopping/search-sdk";

const client = new AlanaSearchClient({ apiKey: "your-api-key" });

const results = await client.search({ query: "running shoes" });
console.log(results.hits);

​
Constructor

const client = new AlanaSearchClient({
  apiKey?: string;    // x-api-key header (API key auth)
  m2mToken?: string;  // Bearer token (Auth0 M2M — service-to-service)
  baseUrl?: string;   // Override base URL (default: https://app.alana.shopping)
});
If both apiKey and m2mToken are provided, m2mToken takes precedence.

​
Methods

​
search(params)

Full-text product search with faceting, sorting, and personalization. 
const { hits, nbHits, page, nbPages, facets } = await client.search({
  query: "running shoes",   // required
  page: 0,
  hitsPerPage: 20,
  sortBy: "price_asc",
  facets: ["brand", "size"],
  facetFilters: ["brand:Nike"],
  userId: "user-123",
  personalize: true,
});

​
autocomplete(params)

Query suggestions with optional product previews for search-as-you-type. 
const { suggestions, products } = await client.autocomplete({
  query: "run",
  limit: 5,
  includeProducts: true,
});

​
browse(params)

Category-based product listing — no free-text query required. 
const { hits, nbHits } = await client.browse({
  categoryPath: "shoes/running",
  page: 0,
  hitsPerPage: 24,
  sortBy: "price_asc",
  facets: ["brand", "color"],
  facetFilters: [["color:red", "color:blue"]],
});

​
recommend(params)

ML-powered product recommendations. 
const { hits, model, fallback } = await client.recommend({
  model: "related-products",
  productId: "sku-123",
  userId: "user-456",
  limit: 10,
});
Available models: related-products, frequently-bought-together, trending-items, trending-facet-values, personalized-trending, recently-viewed, bought-together, visually-similar

​
trackEvent(params)

Track user interactions for personalization and analytics. 
await client.trackEvent({
  events: [{ type: "search", query: "running shoes", userId: "u1" }],
});
Supported event types: home-page-view, search, category-view, detail-page-view, add-to-cart, shopping-cart-page-view, purchase-complete

​
Error Handling

import { AlanaSearchClient, AlanaApiError } from "@alana-shopping/search-sdk";

const client = new AlanaSearchClient({ apiKey: "your-key" });

try {
  const results = await client.search({ query: "shoes" });
} catch (err) {
  if (err instanceof AlanaApiError) {
    console.error(`API error ${err.status}:`, err.message);
    // err.body contains the full response body
  } else {
    // Network error, request timeout, etc.
    console.error("Network error:", err);
  }
}

​
Retry Behavior

The SDK retries automatically:
StatusBehavior
429 Too Many RequestsRetry using Retry-After header value (or exponential backoff)
500, 502, 503, 504Retry with exponential backoff
400, 401, 403, 404Throw immediately — no retry
Network errorsRetry with exponential backoff
Backoff schedule (without Retry-After): 100ms → 400ms → 1600ms (max 3 retries).

​
TypeScript Types

All request params and response shapes are fully typed. Key types: 
import type {
  SearchParams,
  SearchResponse,
  SearchHit,
  AutocompleteParams,
  AutocompleteResponse,
  BrowseParams,
  BrowseResponse,
  RecommendModel,
  RecommendParams,
  RecommendResponse,
  TrackEventParams,
  TrackEvent,
} from "@alana-shopping/search-sdk";

​
Package

  • npm: @alana-shopping/search-sdk
  • Zero runtime dependencies — uses native fetch (Node 18+, Edge, browser)
  • Dual ESM + CJS — works with both import and require
Last modified on March 18, 2026