Skip to main content

Quick Start

This guide will help you get up and running with the Seekora Search SDK in minutes.

Initialize the Client​

Create a new instance of SeekoraClient with your credentials:

import { SeekoraClient } from '@seekora-ai/search-sdk';

const client = new SeekoraClient({
  storeId: 'your-store-id',
  readSecret: 'your-read-secret',
  environment: 'production', // 'local' | 'stage' | 'production'
});

Use the search method to query your store:

async function performSearch() {
  const results = await client.search('laptop', {
    per_page: 20,
    page: 1,
  });

  console.log(`Found ${results.totalResults} results`);
  
  results.results.forEach((result, index) => {
    console.log(`${index + 1}. ${result.title}`);
  });
  
  return results;
}

Get Query Suggestions​

Implement autocomplete with query suggestions:

async function getSuggestions(query: string) {
  const suggestions = await client.getSuggestions(query, {
    hitsPerPage: 5,
  });
  
  console.log('Suggestions:', suggestions);
  return suggestions;
}

Track Events​

Track user interactions for analytics:

async function searchAndTrack() {
  // Perform search
  const results = await client.search('laptop');
  
  // User clicks on the first result
  const clickedItem = results.results[0];
  await client.trackClick(clickedItem.id, 1, results.context);
  
  // User views the product
  await client.trackView(clickedItem.id, results.context);
  
  // User makes a purchase
  await client.trackConversion(clickedItem.id, 999.99, 'USD', results.context);
}

Complete Example​

Here's a complete example combining search, suggestions, and analytics:

import { SeekoraClient } from '@seekora-ai/search-sdk';

const client = new SeekoraClient({
  storeId: 'your-store-id',
  readSecret: 'your-read-secret',
  environment: 'production',
});

// Search with filters and facets
async function searchProducts(query: string) {
  const results = await client.search(query, {
    per_page: 20,
    filter_by: 'category:Electronics',
    facet_by: 'brand,price_range',
    sort_by: 'relevance:desc',
  });

  // Display results
  console.log(`Found ${results.totalResults} products`);
  
  // Display facets
  if (results.facets) {
    Object.entries(results.facets).forEach(([field, facet]) => {
      console.log(`${field}:`, facet.counts);
    });
  }

  return results;
}

// Autocomplete
async function handleTyping(partialQuery: string) {
  if (partialQuery.length < 2) return [];
  
  const suggestions = await client.getSuggestions(partialQuery, {
    hitsPerPage: 10,
  });
  
  return suggestions;
}

// Track user journey
async function trackUserJourney(results: any) {
  const selectedProduct = results.results[0];
  
  // Track click
  await client.trackClick(selectedProduct.id, 1, results.context);
  
  // Track conversion
  await client.trackConversion(
    selectedProduct.id,
    selectedProduct.price,
    'USD',
    results.context
  );
}

// Run
searchProducts('laptop').then(trackUserJourney);

Error Handling​

Always wrap SDK calls in try-catch blocks:

async function safeSearch(query: string) {
  try {
    const results = await client.search(query);
    return results;
  } catch (error) {
    console.error('Search failed:', error.message);
    
    // Handle specific error types
    if (error.message.includes('401') || error.message.includes('403')) {
      console.error('Authentication error - check your credentials');
    } else if (error.message.includes('429')) {
      console.error('Rate limit exceeded - retry later');
    } else if (error.message.includes('Network error')) {
      console.error('Network issue - check your connection');
    }
    
    throw error;
  }
}

Next Steps​