Seekora Search SDK

JavaScript/TypeScript SDK for the Seekora Search API.

Installation

npm install @seekora/search-sdk

Quick Start

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

const client = new SeekoraClient({
    storeId: 'your-store-id',
    readSecret: 'your-read-secret',
    writeSecret: 'your-write-secret', // Optional, required for config updates
});

// Search
const results = await client.search('laptop', {
    per_page: 20,
    filter_by: 'price:100-500',
});

// Track events
await client.trackClick('prod_123', 1, results.searchId);

Environment Configuration

The SDK supports different environments for development, staging, and production.

Option 1: Environment Parameter

// Local development
const client = new SeekoraClient({
    storeId: 'your-store-id',
    readSecret: 'your-read-secret',
    environment: 'local', // Uses http://localhost:3000
});

// Staging
const client = new SeekoraClient({
    storeId: 'your-store-id',
    readSecret: 'your-read-secret',
    environment: 'stage', // Uses https://stage-api.seekora.ai
});

// Production
const client = new SeekoraClient({
    storeId: 'your-store-id',
    readSecret: 'your-read-secret',
    environment: 'production', // Uses https://api.seekora.com
});

Option 2: Environment Variable

Set the SEEKORA_ENV environment variable:

# Local development
SEEKORA_ENV=local node your-app.js

# Staging (default)
SEEKORA_ENV=stage node your-app.js

# Production
SEEKORA_ENV=production node your-app.js

Option 3: Custom Base URL

const client = new SeekoraClient({
    storeId: 'your-store-id',
    readSecret: 'your-read-secret',
    baseUrl: 'https://custom-api.example.com', // Custom base URL
});

Available Environments

| Environment | Base URL | Description | |------------|----------|-------------| | local | http://localhost:3000 | Local development | | stage | https://stage-api.seekora.ai | Staging (default) | | production | https://api.seekora.com | Production |

Default: stage (staging environment)

API Methods

Search

const results = await client.search('laptop', {
    per_page: 20,
    page: 1,
    filter_by: 'price:100-500',
    facet_by: 'category',
    sort_by: 'price:asc',
    analytics_tags: ['campaign:summer_sale'],
});

Query Suggestions

// Basic: get suggestion hits (default returns array of hits)
const suggestions = await client.getSuggestions('lap', { hitsPerPage: 5 });

// With options: time range, categories/facets, analytics tags
const suggestions = await client.getSuggestions('lap', {
    hitsPerPage: 10,
    time_range: '30d',
    include_categories: true,
    include_facets: true,
    analytics_tags: ['campaign:summer'],
});

// Dropdown recommendations (trending/top/related searches, filtered_tabs) — uses POST so include_dropdown_recommendations is sent
const withRecs = await client.getSuggestions('lap', {
    include_dropdown_recommendations: true,
    returnFullResponse: true,
}) as QuerySuggestionsFullResponse;
// withRecs.suggestions = hits; withRecs.extensions = { trending_searches, top_searches, related_searches, popular_brands, filtered_tabs }

// Filtered tabs (product lists per tab) — POST only
const withTabs = await client.getSuggestions('lap', {
    filtered_tabs: [{ label: 'All', filter: '' }, { label: 'Category', filter: 'category:Electronics' }],
    returnFullResponse: true,
});

Query suggestions config (store-level):

// Get query suggestions config (read secret)
const config = await client.getSuggestionsConfig();

// Update query suggestions config (write secret required)
await client.updateQuerySuggestionsConfig({
    enabled: true,
    max_suggestions: 20,
    minimum_letters: 2,
    enable_personalization: false,
});

By default getSuggestions() returns an array of suggestion hits. Pass returnFullResponse: true to get QuerySuggestionsFullResponse with suggestions, results, and extensions (dropdown recommendations, filtered_tabs).

Configuration Management

// Get config (read secret)
const config = await client.getConfig();

// Update config (write secret required)
await client.updateConfig({
    num_typos: 2,
    typo_tolerance: 'medium',
});

// Get config schema
const schema = await client.getConfigSchema();

Analytics Events

// Single event
await client.trackEvent({
    event_name: 'search',
    query: 'laptop',
    results_count: 20,
});

// Batch events
await client.trackEvents([
    { event_name: 'click', clicked_item_id: 'prod_123' },
    { event_name: 'view', clicked_item_id: 'prod_456' },
]);

// Convenience methods
await client.trackClick('prod_123', 1, searchId);
await client.trackView('prod_123', searchId);
await client.trackConversion('prod_123', 99.99, 'USD', searchId);

Error Handling

try {
    const results = await client.search('laptop');
} catch (error) {
    console.error('Search failed:', error.message);
    // Error format: [operation] message (status)
}

TypeScript Support

Full TypeScript support with type definitions included.

License

MIT