npm package: @seekora/search-sdk
Description: Seekora Search SDK for JavaScript/TypeScript
Author: Seekora
Latest version: 1.0.0

# Seekora Search SDK

JavaScript/TypeScript SDK for the Seekora Search API.

## Installation

```bash
npm install @seekora/search-sdk
```

## Quick Start

```typescript
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

```typescript
// 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:

```bash
# 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

```typescript
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

```typescript
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

```typescript
// 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):**

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
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