Cimulate Search API Client

TypeScript client for interacting with the Cimulate Search API (v1.4.0).

Features

• Strongly typed request and response objects
• Automatic retries with exponential backoff
• Comprehensive error handling
• Reconnection logic for handling network issues
• Zero dependencies (uses native Fetch API)
• Logging capabilities

Why Fetch?

This client uses the native Fetch API because it provides zero dependencies, uses modern standards, offers a promise-based interface, and is available in all modern browsers and Node.js (v18+) environments.

Installation

npm install @cimulate/search-sdk

Quick Start

import { CimulateSearchClient } from '@cimulate/search-sdk';
import { SearchRequest } from '@cimulate/search-sdk';

// Initialize with API key or token
const client = new CimulateSearchClient({
  apiKey: 'your-api-key-here',
  // OR token: 'your-bearer-token',
  baseURL: 'https://prod.search.cimulate.ai/api/v1',
  options: {
    maxRetries: 5,        // Default: 3
    baseDelay: 500,       // Default: 300ms
    timeout: 30000,       // Default: 10000ms
    enableLogging: true   // Default: false
  }
});

// Connect and verify API credentials
await client.connect();
const version = await client.getVersion();
console.log(`API Version: ${version.version}`);

// Perform a search
const results = await client.search({ query: 'running shoes' });
console.log(`Found ${results.total_hits} products`);

API Methods

The client provides methods for all Cimulate Search API endpoints:

• getVersion(): Get the API version
• search(request): Perform a search
• getFacets(request): Get facet data
• getSuggestions(request): Get search suggestions
• rerankProducts(request): Rerank search results
• getProductsByIds(request): Get products by IDs
• createSession(request): Create a user session
• getSessionById(id): Get session details
• updateSessionById(id, request): Update a session
• deleteSessionById(id): Delete a session
• createEvent(sessionId, request): Create session event
• getAllEventsBySessionId(sessionId): Get all session events
• getEventById(sessionId, eventId): Get specific event
• deleteEventById(sessionId, eventId): Delete event
• getRecommendations(request): Get recommendations
• getRecommendationsGroups(): Get available recommendation groups

Search Examples

import { SearchRequest } from '@cimulate/search-sdk';

// Simple search
const basicSearch: SearchRequest = {
  query: 'running shoes'
};

// Advanced search with filters and facets
const advancedSearch: SearchRequest = {
  query: 'running shoes',
  page: 1,
  page_size: 20,
  include_facets: true,
  range_filters: [
    {
      field: 'price',
      max: 200,
      min: 50
    }
  ],
  facet_filters: {
    category: ["shoes", "clothing"],
    brand: ["Nike", "Adidas", "Puma"],
    color: ["red", "black", "white"]
  },
  sorting_options: ["newest"],
  session_data: {
    ga_session_id: "ga-session-123",
    session_id: "user-session-123",
    sfcc_sid: "sfcc-sid-456"
  }
};

Facet, Suggestion, and Rerank Examples

// Facets request
const facetRequest = {
  query: 'running shoes',
  max_size: 10,
  range_filters: [{ field: 'price', max: 200, min: 50 }],
  facet_filters: { category: ["shoes", "clothing"] }
};

// Suggestions request
const suggestRequest = {
  query: 'run',
  size: 5
};

// Rerank request
const rerankRequest = {
  query: 'Lil Wayne',
  results: [{ productId: '448479100' }],
  referrer: 'search_page',
  pinned_ranks: { "246675600": 1 }
};

// Get products by ID
const idRequest = {
  ids: ['478942125']
};

Session and Event Management

// Create a session
const session = await client.createSession({
  data: { 
    products_in_cart: 3,
    ga_session_id: "ga-session-123",
    ga_pseudo_user_id: "ga-user-123"
  },
  metadata: { source: 'web', device: 'mobile' }
});

// Session operations
const sessionDetails = await client.getSessionById(session.id);
await client.updateSessionById(session.id, {
  data: { products_in_cart: 5 },
  metadata: { last_page: 'checkout' }
});

// Event operations
const event = await client.createEvent(session.id, {
  name: 'product_view',
  data: { product_id: '473174149', time_spent: 45 },
  metadata: { referrer: 'search' }
});
const events = await client.getAllEventsBySessionId(session.id);
await client.deleteEventById(session.id, event.id);

Error Handling

import { CimulateSearchClient } from '@cimulate/search-sdk';
import { CimulateSearchClientError, CimulateError } from '@cimulate/search-sdk';

try {
  const results = await client.search({ query: 'running shoes' });
} catch (error) {
  // If it's already one of our error types, use it directly
  if (CimulateSearchClientError.isCimulateError(error)) {
    console.error("Search client error", error.getDetailMessage());
    throw error; // Re-throw if needed
  }
}