TypeScript SDK

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);

const { AlanaSearchClient } = require("@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,
});

curl -X POST https://app.alana.shopping/api/v1/search \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "running shoes", "page": 0, "hitsPerPage": 20}'

`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"]],
});

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" }],
});

await client.trackEvent({
  events: [{ type: "detail-page-view", objectID: "sku-123", userId: "u1" }],
});

await client.trackEvent({
  events: [{
    type: "purchase-complete",
    orderID: "ord-789",
    items: [{ objectID: "sku-123", quantity: 1, price: 99.99 }],
    revenue: 99.99,
    currency: "USD",
    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:

Status	Behavior
`429 Too Many Requests`	Retry using `Retry-After` header value (or exponential backoff)
`500`, `502`, `503`, `504`	Retry with exponential backoff
`400`, `401`, `403`, `404`	Throw immediately — no retry
Network errors	Retry 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

Getting Started

Core Concepts

Guides

Installation

Quick Start

Constructor

Methods

`search(params)`

`autocomplete(params)`

`browse(params)`

`trackEvent(params)`

Error Handling

Retry Behavior

TypeScript Types

Package

​Installation

​Quick Start

​Constructor

​Methods

​search(params)

​autocomplete(params)

​browse(params)

​recommend(params)

​trackEvent(params)

​Error Handling

​Retry Behavior

​TypeScript Types

​Package

Installation

Quick Start

Constructor

Methods

`search(params)`

`autocomplete(params)`

`browse(params)`

`recommend(params)`

`trackEvent(params)`

Error Handling

Retry Behavior

TypeScript Types

Package