@seekora-ai/search-sdk 1.0.0

package/README.md

@@ -0,0 +1,213 @@
+# 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
+

package/cdn/.htaccess

@@ -0,0 +1,37 @@
+# Apache configuration for CDN bundle
+# Place this file in your CDN directory if using Apache
+
+# Enable CORS
+<IfModule mod_headers.c>
+    Header set Access-Control-Allow-Origin "*"
+    Header set Access-Control-Allow-Methods "GET, HEAD, OPTIONS"
+    Header set Access-Control-Allow-Headers "*"
+</IfModule>
+
+# Cache control for production bundle
+<FilesMatch "\.min\.js$">
+    Header set Cache-Control "public, max-age=31536000, immutable"
+    Header set Content-Type "application/javascript; charset=utf-8"
+</FilesMatch>
+
+# Cache control for development bundle
+<FilesMatch "seekora-sdk\.js$">
+    Header set Cache-Control "public, max-age=3600"
+    Header set Content-Type "application/javascript; charset=utf-8"
+</FilesMatch>
+
+# Gzip compression
+<IfModule mod_deflate.c>
+    AddOutputFilterByType DEFLATE application/javascript
+</IfModule>
+
+# Enable CORS preflight
+<IfModule mod_rewrite.c>
+    RewriteEngine On
+    RewriteCond %{REQUEST_METHOD} OPTIONS
+    RewriteRule ^(.*)$ $1 [R=200,L]
+</IfModule>
+
+
+
+

package/cdn/README.md

@@ -0,0 +1,130 @@
+# Seekora SDK - CDN Bundle
+
+This directory contains the browser-compatible CDN bundle of the Seekora Search SDK.
+
+## Building the CDN Bundle
+
+### Development Build
+```bash
+npm run build:cdn
+```
+
+This creates `cdn/seekora-sdk.js` (unminified, with source maps).
+
+### Production Build
+```bash
+npm run build:cdn:prod
+```
+
+This creates `cdn/seekora-sdk.min.js` (minified, optimized).
+
+## Usage
+
+### Basic HTML Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Seekora SDK Example</title>
+</head>
+<body>
+    <!-- Load the SDK -->
+    <script src="https://your-cdn-url.com/seekora-sdk.min.js"></script>
+    
+    <script>
+        // Access the SDK via global variable
+        const { SeekoraClient } = window.SeekoraSDK;
+        
+        // Initialize client
+        const client = new SeekoraClient({
+            storeId: 'your-store-id',
+            readSecret: 'your-read-secret',
+            environment: 'stage' // or 'production'
+        });
+        
+        // Perform search
+        async function search() {
+            const results = await client.search('laptop', {
+                per_page: 20
+            });
+            console.log('Results:', results);
+        }
+        
+        search();
+    </script>
+</body>
+</html>
+```
+
+### Using with ES Modules (if supported)
+
+```html
+<script type="module">
+    import { SeekoraClient } from 'https://your-cdn-url.com/seekora-sdk.esm.js';
+    
+    const client = new SeekoraClient({
+        storeId: 'your-store-id',
+        readSecret: 'your-read-secret'
+    });
+</script>
+```
+
+## Global Variable
+
+The SDK is exposed as `window.SeekoraSDK` with the following structure:
+
+```javascript
+window.SeekoraSDK = {
+    SeekoraClient: class SeekoraClient { ... },
+    default: SeekoraClient,
+    ENVIRONMENTS: { ... },
+    getBaseUrl: function() { ... },
+    getEnvironment: function() { ... },
+    Logger: class Logger { ... },
+    createLogger: function() { ... },
+    // ... other exports
+}
+```
+
+## Example
+
+See `example.html` for a complete working example.
+
+## File Sizes
+
+- Development build: ~646 KB (unminified, with source maps)
+- Production build: ~67 KB (minified)
+
+## Browser Support
+
+- Chrome 80+
+- Firefox 78+
+- Safari 14+
+- Edge 80+
+
+## Notes
+
+- All dependencies (including axios) are bundled
+- The bundle uses IIFE format for maximum compatibility
+- Source maps are included in development builds
+- The SDK automatically handles browser-specific features (localStorage, etc.)
+
+## UI SDK Integration
+
+For integrating with a UI SDK, see [CDN_UI_INTEGRATION.md](../CDN_UI_INTEGRATION.md).
+
+**Quick summary:**
+- Load Search SDK before UI SDK: `<script src="seekora-sdk.min.js"></script>`
+- UI SDK can access via `window.SeekoraSDK.SeekoraClient`
+- See `ui-sdk-integration-example.html` for a working example
+
+## Deployment
+
+For deployment instructions, see [DEPLOYMENT.md](../DEPLOYMENT.md).
+
+Quick deployment options:
+- **GitHub Pages**: Automatic via GitHub Actions on releases
+- **AWS S3**: Use `./scripts/deploy-cdn.sh s3`
+- **Cloudflare/Netlify/Vercel**: Upload `cdn/` directory (headers configured automatically)
+

package/cdn/_headers

@@ -0,0 +1,25 @@
+# Netlify/Vercel headers configuration
+# Place this file in your CDN directory
+
+# Production bundle - long cache
+/seekora-sdk.min.js
+  Access-Control-Allow-Origin: *
+  Access-Control-Allow-Methods: GET, HEAD, OPTIONS
+  Access-Control-Allow-Headers: *
+  Cache-Control: public, max-age=31536000, immutable
+  Content-Type: application/javascript; charset=utf-8
+
+# Development bundle - shorter cache
+/seekora-sdk.js
+  Access-Control-Allow-Origin: *
+  Access-Control-Allow-Methods: GET, HEAD, OPTIONS
+  Access-Control-Allow-Headers: *
+  Cache-Control: public, max-age=3600
+  Content-Type: application/javascript; charset=utf-8
+
+# Source maps
+/*.map
+  Access-Control-Allow-Origin: *
+  Cache-Control: public, max-age=3600
+  Content-Type: application/json; charset=utf-8
+

package/cdn/example.html

@@ -0,0 +1,299 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Seekora SDK - CDN Example</title>
+    <style>
+        /* CSS Variable Theme System */
+        :root {
+            /* Primary Colors */
+            --seekora-primary: #007bff;
+            --seekora-primary-dark: #0056b3;
+            
+            /* Text Colors */
+            --seekora-text-primary: #333;
+            --seekora-text-secondary: #666;
+            
+            /* Background Colors */
+            --seekora-bg-primary: #ffffff;
+            --seekora-bg-secondary: #f9f9f9;
+            --seekora-bg-tertiary: #f5f5f5;
+            --seekora-bg-config: #e9ecef;
+            
+            /* Border Colors */
+            --seekora-border: #ddd;
+            
+            /* Status Colors */
+            --seekora-error-text: #dc3545;
+            --seekora-error-bg: #f8d7da;
+            
+            /* Shadows */
+            --seekora-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+            
+            /* Border Radius */
+            --seekora-radius: 4px;
+            --seekora-radius-lg: 8px;
+            
+            /* Typography */
+            --seekora-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+        }
+
+        body {
+            font-family: var(--seekora-font-family);
+            max-width: 1200px;
+            margin: 0 auto;
+            padding: 20px;
+            background: var(--seekora-bg-tertiary);
+        }
+        .container {
+            background: var(--seekora-bg-primary);
+            padding: 30px;
+            border-radius: var(--seekora-radius-lg);
+            box-shadow: var(--seekora-shadow);
+        }
+        h1 {
+            color: var(--seekora-text-primary);
+            margin-top: 0;
+        }
+        .search-box {
+            display: flex;
+            gap: 10px;
+            margin-bottom: 20px;
+        }
+        input[type="text"] {
+            flex: 1;
+            padding: 12px;
+            font-size: 16px;
+            border: 2px solid var(--seekora-border);
+            border-radius: var(--seekora-radius);
+            transition: border-color 0.2s ease;
+        }
+        input[type="text"]:focus {
+            outline: none;
+            border-color: var(--seekora-primary);
+        }
+        button {
+            padding: 12px 24px;
+            font-size: 16px;
+            background: var(--seekora-primary);
+            color: white;
+            border: none;
+            border-radius: var(--seekora-radius);
+            cursor: pointer;
+            transition: background 0.2s ease;
+        }
+        button:hover {
+            background: var(--seekora-primary-dark);
+        }
+        button:disabled {
+            background: #ccc;
+            cursor: not-allowed;
+        }
+        .results {
+            margin-top: 20px;
+        }
+        .result-item {
+            padding: 15px;
+            border: 1px solid var(--seekora-border);
+            border-radius: var(--seekora-radius);
+            margin-bottom: 10px;
+            background: var(--seekora-bg-secondary);
+            cursor: pointer;
+            transition: box-shadow 0.2s ease, transform 0.2s ease;
+        }
+        .result-item:hover {
+            box-shadow: var(--seekora-shadow);
+            transform: translateY(-1px);
+        }
+        .result-item h3 {
+            margin-top: 0;
+            color: var(--seekora-primary);
+        }
+        .error {
+            color: var(--seekora-error-text);
+            padding: 10px;
+            background: var(--seekora-error-bg);
+            border-radius: var(--seekora-radius);
+            margin-top: 10px;
+        }
+        .loading {
+            text-align: center;
+            padding: 20px;
+            color: var(--seekora-text-secondary);
+        }
+        .config {
+            background: var(--seekora-bg-config);
+            padding: 15px;
+            border-radius: var(--seekora-radius);
+            margin-bottom: 20px;
+            font-family: monospace;
+            font-size: 12px;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>🔍 Seekora Search SDK - CDN Example</h1>
+        
+        <div class="config">
+            <strong>Configuration:</strong><br>
+            Store ID: <span id="store-id">your-store-id</span><br>
+            Environment: <span id="env">stage</span>
+        </div>
+
+        <div class="search-box">
+            <input 
+                type="text" 
+                id="search-input" 
+                placeholder="Search for products..." 
+                onkeypress="if(event.key === 'Enter') performSearch()"
+            >
+            <button onclick="performSearch()" id="search-btn">Search</button>
+        </div>
+
+        <div id="results" class="results"></div>
+    </div>
+
+    <!-- Load the SDK from CDN -->
+    <!-- Replace with your actual CDN URL -->
+    <script src="seekora-sdk.js"></script>
+    <!-- Or use the minified version: <script src="seekora-sdk.min.js"></script> -->
+
+    <script>
+        // Configuration - Update these with your actual credentials
+        const CONFIG = {
+            storeId: 'your-store-id',
+            readSecret: 'your-read-secret',
+            writeSecret: 'your-write-secret', // Optional
+            environment: 'stage' // 'local', 'stage', or 'production'
+        };
+
+        // Initialize the SDK client
+        let client;
+        let lastSearchContext = null; // Store search context for analytics correlation
+        
+        function initSDK() {
+            try {
+                // Access the SDK from the global variable
+                const { SeekoraClient } = window.SeekoraSDK;
+                
+                client = new SeekoraClient({
+                    storeId: CONFIG.storeId,
+                    readSecret: CONFIG.readSecret,
+                    writeSecret: CONFIG.writeSecret,
+                    environment: CONFIG.environment,
+                    logLevel: 'info'
+                });
+
+                console.log('✅ SDK initialized successfully');
+                document.getElementById('store-id').textContent = CONFIG.storeId;
+                document.getElementById('env').textContent = CONFIG.environment;
+            } catch (error) {
+                showError('Failed to initialize SDK: ' + error.message);
+                console.error('SDK initialization error:', error);
+            }
+        }
+
+        async function performSearch() {
+            const input = document.getElementById('search-input');
+            const query = input.value.trim();
+            const resultsDiv = document.getElementById('results');
+            const searchBtn = document.getElementById('search-btn');
+
+            if (!query) {
+                showError('Please enter a search query');
+                return;
+            }
+
+            if (!client) {
+                showError('SDK not initialized. Check console for errors.');
+                return;
+            }
+
+            // Disable button and show loading
+            searchBtn.disabled = true;
+            resultsDiv.innerHTML = '<div class="loading">Searching...</div>';
+
+            try {
+                // Perform search
+                const response = await client.search(query, {
+                    per_page: 10
+                });
+
+                // Store search context for analytics correlation
+                lastSearchContext = response.context || null;
+
+                // Display results
+                displayResults(response);
+                
+                // Log search context for debugging
+                if (response.context) {
+                    console.log('Search Context:', {
+                        correlationId: response.context.correlationId,
+                        searchId: response.context.searchId,
+                    });
+                }
+            } catch (error) {
+                showError('Search failed: ' + error.message);
+                console.error('Search error:', error);
+            } finally {
+                searchBtn.disabled = false;
+            }
+        }
+
+        function displayResults(response) {
+            const resultsDiv = document.getElementById('results');
+            
+            if (!response.results || response.results.length === 0) {
+                resultsDiv.innerHTML = '<div class="error">No results found</div>';
+                return;
+            }
+
+            let html = `<h2>Found ${response.total || response.results.length} results</h2>`;
+            
+            response.results.forEach((item, index) => {
+                html += `
+                    <div class="result-item" onclick="trackClick('${item.id || index}', ${index})">
+                        <h3>${item.title || item.name || 'Untitled'}</h3>
+                        ${item.description ? `<p>${item.description}</p>` : ''}
+                        ${item.price ? `<p><strong>Price: $${item.price}</strong></p>` : ''}
+                        <small>ID: ${item.id || 'N/A'}</small>
+                    </div>
+                `;
+            });
+
+            resultsDiv.innerHTML = html;
+        }
+
+        async function trackClick(productId, position) {
+            if (!client) return;
+            
+            try {
+                // Pass search context for proper analytics correlation
+                await client.trackClick(productId, position, lastSearchContext);
+                console.log('[Analytics] Click tracked:', {
+                    productId,
+                    position,
+                    correlationId: lastSearchContext?.correlationId,
+                    searchId: lastSearchContext?.searchId,
+                });
+            } catch (error) {
+                console.error('[Analytics] Failed to track click:', error);
+            }
+        }
+
+        function showError(message) {
+            const resultsDiv = document.getElementById('results');
+            resultsDiv.innerHTML = `<div class="error">${message}</div>`;
+        }
+
+        // Initialize SDK when page loads
+        window.addEventListener('DOMContentLoaded', initSDK);
+    </script>
+</body>
+</html>
+
+
+
+