@seekora-ai/search-sdk 1.0.0

package/dist/client.js

@@ -0,0 +1,991 @@
+"use strict";
+/**
+ * Seekora SDK Client
+ * High-level wrapper around generated OpenAPI client
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SeekoraClient = void 0;
+const generated_1 = require("../generated");
+const axios_1 = __importDefault(require("axios"));
+const config_1 = require("./config");
+const logger_1 = require("./logger");
+const config_loader_1 = require("./config-loader");
+const utils_1 = require("./utils");
+/**
+ * Seekora SDK Client
+ *
+ * Provides a clean, easy-to-use interface for the Seekora Search API
+ */
+class SeekoraClient {
+    constructor(config = {}) {
+        // Load configuration from file, env, and code (in that order)
+        const mergedConfig = (0, config_loader_1.loadConfig)(config);
+        this.storeId = mergedConfig.storeId;
+        this.readSecret = mergedConfig.readSecret;
+        this.writeSecret = mergedConfig.writeSecret;
+        // Initialize logger FIRST (before using it)
+        const logLevel = mergedConfig.logLevel || config.logLevel || (0, logger_1.getLogLevelFromEnv)();
+        this.logger = (0, logger_1.createLogger)({
+            level: logLevel,
+            ...config.logger,
+        });
+        // Initialize identifiers
+        this.userId = config.userId;
+        this.anonId = config.anonId || (0, utils_1.getOrCreateAnonId)();
+        this.sessionId = config.sessionId || (0, utils_1.getOrCreateSessionId)();
+        this.autoTrackSearch = config.autoTrackSearch || false;
+        // Log identifier initialization
+        this.logger.verbose('Client identifiers initialized', {
+            hasUserId: !!this.userId,
+            anonId: this.anonId.substring(0, 8) + '...', // Log partial ID for privacy
+            sessionId: this.sessionId.substring(0, 8) + '...',
+            autoTrackSearch: this.autoTrackSearch
+        });
+        this.logger.verbose('Initializing SeekoraClient', {
+            storeId: this.storeId,
+            environment: mergedConfig.environment,
+            logLevel,
+        });
+        // Get base URL from environment or config
+        const baseUrl = (0, config_1.getBaseUrl)(mergedConfig.environment, mergedConfig.baseUrl);
+        this.logger.verbose('Using base URL', { baseUrl });
+        // Create configuration with base URL
+        this.config = new generated_1.Configuration({
+            basePath: baseUrl,
+            baseOptions: {
+                timeout: mergedConfig.timeout || 30000,
+                headers: {
+                    'x-storeid': this.storeId,
+                    'x-storesecret': this.readSecret,
+                }
+            }
+        });
+        // Initialize API clients
+        this.searchApi = new generated_1.SearchApi(this.config);
+        this.suggestionsApi = new generated_1.QuerySuggestionsApi(this.config);
+        this.suggestionsConfigApi = new generated_1.SDKQuerySuggestionsConfigApi(this.config);
+        this.analyticsApi = new generated_1.AnalyticsEventsApi(this.config);
+        this.storesApi = new generated_1.SDKStoreConfigApi(this.config);
+        this.logger.info('SeekoraClient initialized successfully');
+    }
+    /**
+     * Search for documents
+     *
+     * Generates a new correlation_id for this search and returns SearchContext
+     * for linking subsequent events (clicks, conversions) to this search.
+     *
+     * @param query - Search query string
+     * @param options - Search options (pagination, filters, facets, etc.)
+     * @returns SearchResponse with results and SearchContext
+     */
+    async search(query, options) {
+        // Convert empty query to wildcard
+        const searchQuery = query.trim() || '*';
+        // Generate correlation_id for this search journey
+        const correlationId = (0, utils_1.generateUUID)();
+        this.logger.verbose('Executing search', {
+            originalQuery: query,
+            searchQuery,
+            correlationId,
+            options
+        });
+        const searchRequest = {
+            q: searchQuery,
+            per_page: options?.per_page || 10,
+            page: options?.page || 1,
+            filter: options?.filter || options?.filter_by,
+            facet_by: options?.facet_by,
+            sort: options?.sort || options?.sort_by,
+            analytics_tags: options?.analytics_tags,
+            widget_mode: options?.widget_mode || false,
+            // New advanced parameters
+            search_fields: options?.search_fields,
+            field_weights: options?.field_weights,
+            return_fields: options?.return_fields,
+            omit_fields: options?.omit_fields,
+            snippet_fields: options?.snippet_fields,
+            full_snippet_fields: options?.full_snippet_fields,
+            snippet_prefix: options?.snippet_prefix,
+            snippet_suffix: options?.snippet_suffix,
+            snippet_token_limit: options?.snippet_token_limit,
+            snippet_min_len: options?.snippet_min_len,
+            include_snippets: options?.include_snippets,
+            group_field: options?.group_field,
+            group_size: options?.group_size,
+            prefix_mode: options?.prefix_mode,
+            infix_mode: options?.infix_mode,
+            typo_max: options?.typo_max,
+            typo_min_len_1: options?.typo_min_len_1,
+            typo_min_len_2: options?.typo_min_len_2,
+            search_timeout_ms: options?.search_timeout_ms,
+            require_all_terms: options?.require_all_terms,
+            exact_match_boost: options?.exact_match_boost,
+            cache_results: options?.cache_results,
+            apply_rules: options?.apply_rules,
+            preset_name: options?.preset_name,
+            facet_search_text: options?.facet_search_text,
+            include_suggestions: options?.include_suggestions,
+            suggestions_limit: options?.suggestions_limit,
+            max_facet_values: options?.max_facet_values,
+            stopword_sets: options?.stopword_sets,
+            synonym_sets: options?.synonym_sets,
+        };
+        // Log search request details (verbose level for debugging)
+        this.logger.verbose('Search request prepared', {
+            filter: searchRequest.filter,
+            filterType: typeof searchRequest.filter,
+            fullRequest: searchRequest
+        });
+        try {
+            // Log API request start
+            this.logger.verbose('Sending search API request', {
+                endpoint: '/api/v1/search',
+                method: 'POST',
+                storeId: this.storeId
+            });
+            // Build headers with personalization support
+            const headers = {
+                'x-storeid': this.storeId,
+                'x-storesecret': this.readSecret,
+            };
+            // Add personalization headers if available
+            if (this.userId) {
+                headers['x-user-id'] = this.userId;
+            }
+            if (this.anonId) {
+                headers['x-anon-id'] = this.anonId;
+            }
+            if (this.sessionId) {
+                headers['x-session-id'] = this.sessionId;
+            }
+            const response = await this.searchApi.v1SearchPost(this.storeId, this.readSecret, searchRequest, this.userId, this.anonId, this.sessionId, {
+                headers
+            });
+            // Log API response received
+            this.logger.verbose('Search API response received', {
+                status: response.status,
+                hasData: !!response.data
+            });
+            // Extract search results
+            const data = response.data;
+            const facets = data?.data?.facets || [];
+            // Log API response (verbose level for detailed debugging)
+            this.logger.verbose('API response received', {
+                status: response.status,
+                totalResults: data?.data?.total_results || 0,
+                resultsCount: data?.data?.results?.length || 0,
+                facetsType: Array.isArray(facets) ? 'array' : typeof facets,
+                facetsCount: Array.isArray(facets) ? facets.length : Object.keys(facets || {}).length
+            });
+            // Convert facets array to a more accessible object format
+            const facetsMap = {};
+            if (Array.isArray(facets)) {
+                this.logger.verbose('Processing facets as array', { facetsCount: facets.length });
+                facets.forEach((facet, index) => {
+                    // Handle different facet formats
+                    const fieldName = facet?.field_name || facet?.fieldName || facet?.name || `facet_${index}`;
+                    if (fieldName && (facet?.counts || facet?.values || Array.isArray(facet))) {
+                        facetsMap[fieldName] = {
+                            field_name: fieldName,
+                            counts: facet.counts || facet.values || (Array.isArray(facet) ? facet : []),
+                            stats: facet.stats || {}
+                        };
+                        this.logger.verbose('Processed facet', { fieldName, index, counts: facetsMap[fieldName].counts?.length || 0 });
+                    }
+                });
+            }
+            else if (facets && typeof facets === 'object' && !Array.isArray(facets)) {
+                this.logger.verbose('Processing facets as object', { facetKeys: Object.keys(facets) });
+                // If facets is already an object, use it directly but ensure field_name is set
+                Object.keys(facets).forEach((key) => {
+                    const facetData = facets[key];
+                    if (facetData) {
+                        facetsMap[key] = {
+                            field_name: facetData.field_name || key,
+                            counts: facetData.counts || facetData.values || [],
+                            stats: facetData.stats || {}
+                        };
+                    }
+                });
+            }
+            this.logger.verbose('Facets processed', {
+                facetFields: Object.keys(facetsMap),
+                totalFacetFields: Object.keys(facetsMap).length
+            });
+            // Extract search_id from response (if present)
+            const searchId = data?.data?.search_id;
+            // Create search context for linking events
+            const context = {
+                correlationId,
+                searchId,
+                userId: this.userId,
+                anonId: this.anonId,
+                sessionId: this.sessionId,
+            };
+            const results = {
+                results: data?.data?.results || [],
+                totalResults: data?.data?.total_results || 0,
+                searchId, // Keep for backward compatibility
+                context, // New: search context for event linking
+                facets: facetsMap,
+                facet_counts: facetsMap, // Alias for backward compatibility
+                ...data
+            };
+            this.logger.info('Search completed', {
+                query: searchQuery,
+                originalQuery: query,
+                totalResults: results.totalResults,
+                searchId: results.searchId,
+                correlationId,
+            });
+            // Automatically track search event if enabled
+            if (this.autoTrackSearch) {
+                this.trackSearch({
+                    query: searchQuery,
+                    resultsCount: results.totalResults,
+                    context,
+                }).catch((err) => {
+                    // Log but don't fail the search if tracking fails
+                    this.logger.warn('Failed to auto-track search event', { error: err.message });
+                });
+            }
+            return results;
+        }
+        catch (error) {
+            // Log detailed error information
+            const errorDetails = {
+                query: searchQuery,
+                originalQuery: query,
+                error: error.message,
+            };
+            if (error.response) {
+                errorDetails.status = error.response.status;
+                errorDetails.responseData = error.response.data;
+                errorDetails.requestUrl = error.config?.url;
+                errorDetails.requestMethod = error.config?.method;
+            }
+            else if (error.request) {
+                errorDetails.networkError = true;
+                errorDetails.requestConfig = {
+                    url: error.config?.url,
+                    method: error.config?.method,
+                };
+            }
+            this.logger.error('Search failed', errorDetails);
+            throw this.handleError(error, 'search');
+        }
+    }
+    /**
+     * Get query suggestions
+     *
+     * Uses POST when filtered_tabs or include_dropdown_recommendations is set (GET does not send include_dropdown_recommendations).
+     * With returnFullResponse: true returns full shape including extensions (trending_searches, top_searches, related_searches, popular_brands, filtered_tabs).
+     *
+     * @param query - Partial query to get suggestions for
+     * @param options - Optional parameters for suggestions
+     * @returns Suggestion hits array, or QuerySuggestionsFullResponse when returnFullResponse is true
+     */
+    async getSuggestions(query, options) {
+        this.logger.verbose('Getting query suggestions', { query, options });
+        try {
+            const headers = {
+                'x-storeid': this.storeId,
+                'x-storesecret': this.readSecret,
+            };
+            if (this.userId)
+                headers['x-user-id'] = this.userId;
+            if (this.anonId)
+                headers['x-anon-id'] = this.anonId;
+            if (this.sessionId)
+                headers['x-session-id'] = this.sessionId;
+            const usePost = (options?.filtered_tabs && options.filtered_tabs.length > 0) ||
+                options?.include_dropdown_recommendations === true;
+            const buildRequestBody = () => {
+                const body = {
+                    query,
+                    hitsPerPage: options?.hitsPerPage || 5,
+                    page: options?.page,
+                    include_categories: options?.include_categories,
+                    include_facets: options?.include_facets,
+                    max_categories: options?.max_categories,
+                    max_facets: options?.max_facets,
+                    min_popularity: options?.min_popularity,
+                    time_range: options?.time_range,
+                    disable_typo_tolerance: options?.disable_typo_tolerance,
+                    include_dropdown_recommendations: options?.include_dropdown_recommendations,
+                    filtered_tabs: options?.filtered_tabs,
+                };
+                if (options?.analytics_tags) {
+                    body.analytics_tags = Array.isArray(options.analytics_tags)
+                        ? options.analytics_tags
+                        : [options.analytics_tags];
+                }
+                if (options?.tags_match_mode)
+                    body.tags_match_mode = options.tags_match_mode;
+                return body;
+            };
+            if (usePost) {
+                this.logger.verbose('Using POST endpoint (filtered_tabs or include_dropdown_recommendations)', {
+                    endpoint: '/api/v1/suggestions/queries',
+                    query,
+                });
+                const requestBody = buildRequestBody();
+                const response = await this.suggestionsApi.v1SuggestionsQueriesPost(this.storeId, this.readSecret, this.userId, this.anonId, this.sessionId, requestBody, { headers });
+                const responseData = response.data?.data || response.data;
+                const suggestions = responseData?.results?.[0]?.hits || responseData?.hits || [];
+                const extensions = responseData?.results?.[1]?.extensions ?? responseData?.results?.[0]?.extensions;
+                if (options?.returnFullResponse) {
+                    this.logger.info('Query suggestions retrieved (POST, full response)', {
+                        query,
+                        count: suggestions.length,
+                        status: response.status,
+                    });
+                    return {
+                        suggestions,
+                        results: responseData?.results,
+                        extensions: extensions ?? undefined,
+                        raw: responseData,
+                    };
+                }
+                this.logger.info('Query suggestions retrieved (POST)', {
+                    query,
+                    count: suggestions.length,
+                    status: response.status,
+                });
+                return suggestions;
+            }
+            // GET for simple requests (no filtered_tabs, no include_dropdown_recommendations)
+            this.logger.verbose('Using GET endpoint', {
+                endpoint: '/api/v1/suggestions/queries',
+                query,
+            });
+            const analyticsTags = Array.isArray(options?.analytics_tags)
+                ? options.analytics_tags.join(',')
+                : options?.analytics_tags;
+            const response = await this.suggestionsApi.v1SuggestionsQueriesGet(this.storeId, this.readSecret, this.userId, this.anonId, this.sessionId, query, options?.hitsPerPage || 5, options?.page, analyticsTags, options?.tags_match_mode, options?.include_categories, options?.include_facets, options?.max_categories, options?.max_facets, options?.min_popularity, options?.time_range, options?.disable_typo_tolerance, { headers });
+            const responseData = response.data?.data || response.data;
+            const suggestions = responseData?.results?.[0]?.hits || responseData?.hits || [];
+            if (options?.returnFullResponse) {
+                const extensions = responseData?.results?.[1]?.extensions ?? responseData?.results?.[0]?.extensions;
+                this.logger.info('Query suggestions retrieved (GET, full response)', {
+                    query,
+                    count: suggestions.length,
+                    status: response.status,
+                });
+                return {
+                    suggestions,
+                    results: responseData?.results,
+                    extensions: extensions ?? undefined,
+                    raw: responseData,
+                };
+            }
+            this.logger.info('Query suggestions retrieved (GET)', {
+                query,
+                count: suggestions.length,
+                status: response.status,
+            });
+            return suggestions;
+        }
+        catch (error) {
+            this.logger.error('Failed to get suggestions', { query, error: error.message });
+            throw this.handleError(error, 'getSuggestions');
+        }
+    }
+    /**
+     * Get query suggestions configuration (store-specific).
+     * Uses GET /api/v1/stores/{storeId}/query-suggestions/config via SDKQuerySuggestionsConfigApi.
+     */
+    async getSuggestionsConfig() {
+        this.logger.verbose('Getting suggestions configuration');
+        try {
+            const headers = {
+                'x-storeid': this.storeId,
+                'x-storesecret': this.readSecret,
+            };
+            try {
+                const response = await this.suggestionsConfigApi.apiV1StoresXStoreIDQuerySuggestionsConfigGet(this.storeId, this.readSecret, this.storeId, { headers });
+                const data = response.data?.data;
+                const config = data?.metadata?.config ?? data?.config ?? data;
+                this.logger.info('Suggestions configuration retrieved', {
+                    configKeys: config ? Object.keys(config) : [],
+                    status: response.status,
+                });
+                return config;
+            }
+            catch (e) {
+                this.logger.verbose('Store config endpoint failed, trying legacy endpoint', { message: e?.message });
+                const response = await this.suggestionsApi.v1SuggestionsConfigGet(this.storeId, this.readSecret, { headers });
+                const config = response.data?.data;
+                this.logger.info('Suggestions configuration retrieved (legacy)', {
+                    configKeys: config ? Object.keys(config) : [],
+                    status: response.status,
+                });
+                return config;
+            }
+        }
+        catch (error) {
+            this.logger.error('Failed to get suggestions config', { error: error.message });
+            throw this.handleError(error, 'getSuggestionsConfig');
+        }
+    }
+    /**
+     * Get store configuration
+     * Returns store search configuration and onboarding status
+     */
+    async getConfig() {
+        this.logger.verbose('Getting store configuration');
+        try {
+            this.logger.verbose('Fetching store configuration', {
+                endpoint: `/api/v1/stores/${this.storeId}/config`
+            });
+            // Build headers with personalization support
+            const headers = {
+                'x-storeid': this.storeId,
+                'x-storesecret': this.readSecret,
+            };
+            // Add personalization headers if available
+            if (this.userId) {
+                headers['x-user-id'] = this.userId;
+            }
+            if (this.anonId) {
+                headers['x-anon-id'] = this.anonId;
+            }
+            if (this.sessionId) {
+                headers['x-session-id'] = this.sessionId;
+            }
+            const response = await this.storesApi.apiV1StoresXStoreIDConfigGet(this.storeId, this.readSecret, this.storeId, { headers });
+            const config = response.data?.data;
+            this.logger.info('Store configuration retrieved', {
+                status: response.status,
+                hasConfig: !!config
+            });
+            return config;
+        }
+        catch (error) {
+            this.logger.error('Failed to get store config', { error: error.message });
+            throw this.handleError(error, 'getConfig');
+        }
+    }
+    /**
+     * Get store information
+     * Returns store metadata including name, status, and configuration details
+     *
+     * Note: This extracts information from the store config response.
+     * Store name may be derived from config fields if not directly available.
+     *
+     * @returns Store information object
+     */
+    async getStoreInfo() {
+        this.logger.verbose('Getting store information');
+        try {
+            const configResponse = await this.getConfig();
+            // Extract store info from config response
+            const storeInfo = {
+                storeId: this.storeId,
+            };
+            // The config response structure: { config: IndexConfig, onboarding_status: string }
+            if (configResponse) {
+                // Handle different response structures
+                const config = configResponse.config || configResponse;
+                const onboardingStatus = configResponse.onboarding_status;
+                if (onboardingStatus) {
+                    storeInfo.onboardingStatus = onboardingStatus;
+                }
+                if (config) {
+                    // Extract store name from various possible fields
+                    storeInfo.storeName =
+                        config.store_name ||
+                            config.storeName ||
+                            config.name ||
+                            config.title ||
+                            config.collection_name ||
+                            `Store ${this.storeId.substring(0, 8).toUpperCase()}`;
+                    // Extract query and facet fields
+                    if (config.query_by) {
+                        storeInfo.queryFields = Array.isArray(config.query_by)
+                            ? config.query_by
+                            : [config.query_by];
+                    }
+                    if (config.facet_by) {
+                        storeInfo.facetFields = Array.isArray(config.facet_by)
+                            ? config.facet_by
+                            : [config.facet_by];
+                    }
+                    if (config.primary_text) {
+                        storeInfo.primaryField = config.primary_text;
+                    }
+                    // Store the full config for reference
+                    storeInfo.config = config;
+                }
+            }
+            this.logger.info('Store information retrieved', {
+                storeId: storeInfo.storeId,
+                storeName: storeInfo.storeName
+            });
+            return storeInfo;
+        }
+        catch (error) {
+            this.logger.error('Failed to get store info', { error: error.message });
+            throw this.handleError(error, 'getStoreInfo');
+        }
+    }
+    /**
+     * Update store configuration (requires write secret)
+     */
+    async updateConfig(config) {
+        this.logger.verbose('Updating store configuration', { configKeys: Object.keys(config) });
+        if (!this.writeSecret) {
+            this.logger.error('Write secret required but not provided', {
+                operation: 'updateConfig',
+                storeId: this.storeId
+            });
+            throw new Error('Write secret is required for updateConfig');
+        }
+        try {
+            this.logger.verbose('Updating store configuration', {
+                endpoint: `/api/v1/stores/${this.storeId}/config`,
+                configKeys: Object.keys(config)
+            });
+            // Build headers with write secret
+            const headers = {
+                'x-storeid': this.storeId,
+                'x-storesecret': this.readSecret,
+                'x-store-write-secret': this.writeSecret,
+            };
+            const response = await this.storesApi.apiV1StoresXStoreIDConfigPut(this.storeId, this.writeSecret, this.storeId, config, { headers });
+            const updatedConfig = response.data?.data;
+            this.logger.info('Store configuration updated successfully', {
+                status: response.status,
+                hasConfig: !!updatedConfig
+            });
+            return updatedConfig;
+        }
+        catch (error) {
+            this.logger.error('Failed to update store config', { error: error.message });
+            throw this.handleError(error, 'updateConfig');
+        }
+    }
+    /**
+     * Update query suggestions configuration (requires write secret).
+     * Uses PUT /api/v1/stores/{xStoreID}/query-suggestions/config via SDKQuerySuggestionsConfigApi.
+     */
+    async updateQuerySuggestionsConfig(config) {
+        this.logger.verbose('Updating query suggestions configuration', { configKeys: Object.keys(config) });
+        if (!this.writeSecret) {
+            this.logger.error('Write secret required but not provided', {
+                operation: 'updateQuerySuggestionsConfig',
+                storeId: this.storeId,
+            });
+            throw new Error('Write secret is required for updateQuerySuggestionsConfig');
+        }
+        try {
+            const headers = {
+                'x-storeid': this.storeId,
+                'x-store-write-secret': this.writeSecret,
+                'Content-Type': 'application/json',
+            };
+            try {
+                const response = await this.suggestionsConfigApi.apiV1StoresXStoreIDQuerySuggestionsConfigPut(this.storeId, this.writeSecret, this.storeId, config, { headers });
+                const data = response.data?.data;
+                const updatedConfig = data?.metadata?.config ?? data?.config ?? data;
+                this.logger.info('Query suggestions configuration updated successfully', {
+                    status: response.status,
+                    hasConfig: !!updatedConfig,
+                });
+                return updatedConfig;
+            }
+            catch (apiError) {
+                this.logger.verbose('PUT via generated API failed, using direct HTTP', { message: apiError?.message });
+                const axiosInstance = this.suggestionsConfigApi.axios ?? this.suggestionsApi.axios ?? axios_1.default;
+                const baseUrl = this.config.basePath ?? 'https://api.seekora.com/api';
+                const response = await axiosInstance.put(`${baseUrl}/v1/stores/${this.storeId}/query-suggestions/config`, config, { headers });
+                const data = response.data?.data;
+                const updatedConfig = data?.metadata?.config ?? data?.config ?? data;
+                this.logger.info('Query suggestions configuration updated successfully', {
+                    status: response.status,
+                    hasConfig: !!updatedConfig,
+                });
+                return updatedConfig;
+            }
+        }
+        catch (error) {
+            this.logger.error('Failed to update query suggestions config', { error: error.message });
+            throw this.handleError(error, 'updateQuerySuggestionsConfig');
+        }
+    }
+    /**
+     * Get configuration schema
+     */
+    async getConfigSchema() {
+        this.logger.verbose('Getting configuration schema');
+        try {
+            const response = await this.storesApi.apiV1StoresXStoreIDConfigSchemaGet(this.storeId, this.readSecret, this.storeId, {
+                headers: {
+                    'x-storeid': this.storeId,
+                    'x-storesecret': this.readSecret,
+                }
+            });
+            const schema = response.data?.data;
+            this.logger.verbose('Configuration schema retrieved', { schemaKeys: schema ? Object.keys(schema) : [] });
+            return schema;
+        }
+        catch (error) {
+            this.logger.error('Failed to get config schema', { error: error.message });
+            throw this.handleError(error, 'getConfigSchema');
+        }
+    }
+    /**
+     * Build event payload with identifiers
+     * Ensures user_id or anon_id is present, and sets correlation_id/search_id at top level
+     */
+    buildEventPayload(event, context) {
+        const payload = {
+            ...event,
+            // Set identifiers from context or fall back to client defaults
+            user_id: event.user_id || context?.userId || this.userId,
+            anon_id: event.anon_id || context?.anonId || this.anonId,
+            session_id: event.session_id || context?.sessionId || this.sessionId,
+            // Set correlation_id at top level if provided (per identifier spec)
+            correlation_id: event.correlation_id || context?.correlationId,
+            // Set search_id at top level (not just in metadata) if provided (per identifier spec)
+            search_id: event.search_id || context?.searchId,
+        };
+        // Ensure either user_id or anon_id is present
+        if (!payload.user_id && !payload.anon_id) {
+            // This should not happen as we always have anonId, but add check for safety
+            payload.anon_id = this.anonId;
+        }
+        // Also include search_id in metadata for backward compatibility
+        if (payload.search_id && !payload.metadata) {
+            payload.metadata = {};
+        }
+        if (payload.search_id && payload.metadata && !payload.metadata.search_id) {
+            payload.metadata.search_id = payload.search_id;
+        }
+        return payload;
+    }
+    /**
+     * Track a single analytics event
+     *
+     * @param event - Event payload (partial, will be enriched with identifiers)
+     * @param context - Optional search context for linking events to searches
+     */
+    async trackEvent(event, context) {
+        this.logger.verbose('Tracking analytics event', {
+            eventName: event.event_name,
+            hasContext: !!context
+        });
+        const payload = this.buildEventPayload(event, context);
+        try {
+            this.logger.verbose('Sending analytics event', {
+                endpoint: '/api/analytics/event',
+                eventName: event.event_name
+            });
+            // Cast to DataTypesEventPayload for API call (backend accepts extended fields)
+            const response = await this.analyticsApi.analyticsEventPost(this.storeId, this.readSecret, payload, // Type assertion needed as generated types may not include correlation_id/search_id yet
+            {
+                headers: {
+                    'x-storeid': this.storeId,
+                    'x-storesecret': this.readSecret,
+                }
+            });
+            this.logger.verbose('Analytics event tracked successfully', {
+                eventName: event.event_name,
+                status: response.status
+            });
+        }
+        catch (error) {
+            this.logger.error('Failed to track event', { eventName: event.event_name, error: error.message });
+            throw this.handleError(error, 'trackEvent');
+        }
+    }
+    /**
+     * Track multiple analytics events (batch)
+     *
+     * Note: Events should already have identifiers set. Consider using individual trackEvent()
+     * calls or buildEventPayload() to ensure identifiers are properly set.
+     *
+     * @param events - Array of event payloads (should have identifiers already set)
+     */
+    async trackEvents(events, context) {
+        this.logger.verbose('Tracking batch analytics events', {
+            count: events.length,
+            hasContext: !!context
+        });
+        if (events.length > 100) {
+            this.logger.error('Batch size exceeds maximum', { count: events.length, max: 100 });
+            throw new Error('Maximum 100 events per batch');
+        }
+        try {
+            this.logger.verbose('Sending batch analytics events', {
+                endpoint: '/api/analytics/batch',
+                eventCount: events.length
+            });
+            // Build full event payloads with identifiers
+            const enrichedEvents = events.map(event => this.buildEventPayload(event, context));
+            const batchRequest = {
+                events: enrichedEvents // Type assertion for extended payloads
+            };
+            const response = await this.analyticsApi.analyticsBatchPost(this.storeId, this.readSecret, batchRequest, {
+                headers: {
+                    'x-storeid': this.storeId,
+                    'x-storesecret': this.readSecret,
+                }
+            });
+            this.logger.info('Batch analytics events tracked successfully', {
+                count: events.length,
+                status: response.status
+            });
+        }
+        catch (error) {
+            this.logger.error('Failed to track batch events', { count: events.length, error: error.message });
+            throw this.handleError(error, 'trackEvents');
+        }
+    }
+    /**
+     * Track a search event
+     *
+     * @param params - Search tracking parameters
+     */
+    async trackSearch(params) {
+        this.logger.verbose('Tracking search event', {
+            query: params.query,
+            resultsCount: params.resultsCount,
+            hasContext: !!params.context
+        });
+        await this.trackEvent({
+            event_name: 'search.performed',
+            query: params.query,
+            results_count: params.resultsCount,
+            analytics_tags: params.analyticsTags,
+            metadata: params.metadata,
+        }, params.context);
+    }
+    /**
+     * Track an impression event
+     *
+     * @param params - Impression tracking parameters
+     */
+    async trackImpression(params) {
+        this.logger.verbose('Tracking impression event', {
+            itemId: params.itemId,
+            position: params.position,
+            hasContext: !!params.context
+        });
+        await this.trackEvent({
+            event_name: 'impression',
+            clicked_item_id: params.itemId,
+            metadata: {
+                position: params.position,
+                list_type: params.listType,
+                search_query: params.searchQuery,
+                ...params.metadata,
+            },
+        }, params.context);
+    }
+    async trackClick(itemId, position, contextOrSearchId) {
+        this.logger.verbose('Tracking click event', {
+            itemId,
+            position,
+            hasContext: !!contextOrSearchId
+        });
+        // Handle backward compatibility: if third param is string, treat as searchId
+        const context = typeof contextOrSearchId === 'string'
+            ? { correlationId: '', searchId: contextOrSearchId, anonId: this.anonId, sessionId: this.sessionId }
+            : contextOrSearchId;
+        await this.trackEvent({
+            event_name: 'product_click',
+            clicked_item_id: itemId,
+            metadata: {
+                position,
+            },
+        }, context);
+    }
+    async trackView(itemId, contextOrSearchId) {
+        this.logger.verbose('Tracking view event', {
+            itemId,
+            hasContext: !!contextOrSearchId
+        });
+        // Handle backward compatibility: if second param is string, treat as searchId
+        const context = typeof contextOrSearchId === 'string'
+            ? { correlationId: '', searchId: contextOrSearchId, anonId: this.anonId, sessionId: this.sessionId }
+            : contextOrSearchId;
+        await this.trackEvent({
+            event_name: 'view',
+            clicked_item_id: itemId,
+        }, context);
+    }
+    async trackConversion(itemId, value, currency, contextOrSearchId) {
+        this.logger.verbose('Tracking conversion event', {
+            itemId,
+            value,
+            currency,
+            hasContext: !!contextOrSearchId
+        });
+        // Handle backward compatibility: if fourth param is string, treat as searchId
+        const context = typeof contextOrSearchId === 'string'
+            ? { correlationId: '', searchId: contextOrSearchId, anonId: this.anonId, sessionId: this.sessionId }
+            : contextOrSearchId;
+        await this.trackEvent({
+            event_name: 'conversion',
+            clicked_item_id: itemId,
+            value,
+            currency,
+        }, context);
+    }
+    /**
+     * Track a custom event
+     *
+     * @param eventName - Custom event name
+     * @param payload - Additional event data
+     * @param context - Optional search context for linking events to searches
+     */
+    async trackCustom(eventName, payload = {}, context) {
+        this.logger.verbose('Tracking custom event', {
+            eventName,
+            hasContext: !!context
+        });
+        await this.trackEvent({
+            ...payload,
+            event_name: eventName,
+        }, context);
+    }
+    /**
+     * Validate an event payload before sending
+     * Useful for debugging and ensuring events are properly formatted
+     *
+     * @param event - Event payload to validate
+     * @returns Validation result with success status and any error messages
+     */
+    async validateEvent(event) {
+        this.logger.verbose('Validating event payload', { eventName: event.event_name });
+        try {
+            this.logger.verbose('Validating event payload', {
+                endpoint: '/api/analytics/validate',
+                eventName: event.event_name
+            });
+            const payload = this.buildEventPayload(event);
+            const response = await this.analyticsApi.analyticsValidatePost(this.storeId, this.readSecret, payload, {
+                headers: {
+                    'x-storeid': this.storeId,
+                    'x-storesecret': this.readSecret,
+                }
+            });
+            const result = response.data?.data || response.data;
+            const isValid = result?.valid !== false && response.status === 200;
+            this.logger.verbose('Event validation result', {
+                valid: isValid,
+                eventName: event.event_name,
+                message: result?.message
+            });
+            return {
+                valid: isValid,
+                message: result?.message || (isValid ? 'Event is valid' : 'Event validation failed'),
+                errors: result?.errors,
+            };
+        }
+        catch (error) {
+            this.logger.error('Event validation failed', { error: error.message });
+            return {
+                valid: false,
+                message: error.response?.data?.message || error.message || 'Validation request failed',
+                errors: error.response?.data?.errors || error.response?.data,
+            };
+        }
+    }
+    /**
+     * Get event schema
+     * Returns the JSON schema for event payloads, useful for understanding required/optional fields
+     *
+     * @returns Event schema with field definitions, types, and validation rules
+     */
+    async getEventSchema() {
+        this.logger.verbose('Getting event schema');
+        try {
+            const response = await this.analyticsApi.analyticsSchemaGet(this.storeId, this.readSecret, {
+                headers: {
+                    'x-storeid': this.storeId,
+                    'x-storesecret': this.readSecret,
+                }
+            });
+            const schema = response.data?.data || response.data;
+            this.logger.verbose('Event schema retrieved', { schemaKeys: schema ? Object.keys(schema) : [] });
+            return schema;
+        }
+        catch (error) {
+            this.logger.error('Failed to get event schema', { error: error.message });
+            throw this.handleError(error, 'getEventSchema');
+        }
+    }
+    /**
+     * Set user ID (call this when user logs in)
+     *
+     * @param userId - Authenticated user ID
+     */
+    setUserId(userId) {
+        this.userId = userId;
+        this.logger.info('User ID updated', { userId });
+    }
+    /**
+     * Clear user ID (call this when user logs out)
+     */
+    clearUserId() {
+        this.userId = undefined;
+        this.logger.info('User ID cleared');
+    }
+    /**
+     * Get current identifiers
+     * Useful for debugging or custom event tracking
+     */
+    getIdentifiers() {
+        return {
+            userId: this.userId,
+            anonId: this.anonId,
+            sessionId: this.sessionId,
+        };
+    }
+    /**
+     * Handle errors consistently
+     */
+    handleError(error, operation) {
+        if (error.response) {
+            const status = error.response.status;
+            const data = error.response.data;
+            const message = data?.message || `API request failed with status ${status}`;
+            // Log based on status code
+            if (status >= 500) {
+                this.logger.error('API server error', { operation, status, message });
+            }
+            else if (status === 401 || status === 403) {
+                this.logger.error('Authentication error', { operation, status, message });
+            }
+            else if (status === 429) {
+                this.logger.warn('Rate limit exceeded', { operation, status, message });
+            }
+            else {
+                this.logger.error('API request failed', { operation, status, message });
+            }
+            return new Error(`[${operation}] ${message} (${status})`);
+        }
+        else if (error.request) {
+            this.logger.error('Network error', { operation, error: error.message });
+            return new Error(`[${operation}] Network error: ${error.message}`);
+        }
+        else {
+            this.logger.error('Request error', { operation, error: error.message });
+            return new Error(`[${operation}] ${error.message}`);
+        }
+    }
+    /**
+     * Get the logger instance
+     */
+    getLogger() {
+        return this.logger;
+    }
+}
+exports.SeekoraClient = SeekoraClient;
+// Export default
+exports.default = SeekoraClient;