@seekora-ai/search-sdk 0.2.13 → 0.2.15

package/dist/client.d.ts

@@ -2,7 +2,7 @@
  * Seekora SDK Client
  * High-level wrapper around generated OpenAPI client
  */
-import type { DataTypesIndexConfig, DataTypesEventPayload } from './generated';
+import type { DataTypesIndexConfig, DataTypesEventPayload, DataTypesFiltersResponse, DataTypesFacetValuesSearchResponse, DataTypesFiltersSchemaResponse, DataTypesFilterField, DataTypesFilterValue, DataTypesFilterStats, DataTypesFilterSchemaField, DataTypesExperimentAssignmentResponse } from './generated';
 import { type SeekoraEnvironment } from './config';
 import { Logger, type LogLevel, type LoggerConfig } from './logger';
 import { type ContextCollectorConfig, type BrowserContext } from './context-collector';
@@ -46,8 +46,9 @@ export interface SeekoraClientConfig {
      */
     contextCollector?: ContextCollectorConfig;
     /**
-     * Enable event queue for offline buffering and retry
-     * @default false
+     * Enable event queue for batching, offline buffering, and retry
+     * Batches events automatically (default: 10 events or 5s interval) for better performance
+     * @default true
      */
     enableEventQueue?: boolean;
     /**
@@ -326,6 +327,8 @@ export declare class SeekoraClient {
     private storesApi;
     private documentsApi;
     private schemaApi;
+    private filtersApi;
+    private experimentsApi;
     private storeId;
     private readSecret;
     private writeSecret?;
@@ -408,6 +411,15 @@ export declare class SeekoraClient {
      * Returns store search configuration and onboarding status
      */
     getConfig(): Promise<DataTypesIndexConfig>;
+    /**
+     * Get experiment assignments for the current user
+     *
+     * Returns variant assignments for all running experiments.
+     * Uses hash-based consistent assignment on the backend.
+     *
+     * @returns ExperimentAssignmentResponse with assignments array
+     */
+    getExperimentAssignment(): Promise<DataTypesExperimentAssignmentResponse>;
     /**
      * Get store information
      * Returns store metadata including name, status, and configuration details
@@ -813,5 +825,62 @@ export declare class SeekoraClient {
      * Get the logger instance
      */
     getLogger(): Logger;
+    /**
+     * Get filter values and counts for configured facets.
+     * Use this to build faceted navigation UIs without performing a full search.
+     * Supports disjunctive faceting for OR-based filter combinations.
+     *
+     * @param options - Filter options (query, filters, facet_by, max_facet_values, disjunctive_facets)
+     * @returns Filter values with counts grouped by field
+     */
+    getFilters(options?: FilterOptions): Promise<DataTypesFiltersResponse>;
+    /**
+     * Search within a single facet's values.
+     * Useful for facets with many values (e.g., brands) where you need typeahead/autocomplete.
+     *
+     * @param facetName - The facet field name to search within (e.g., "brand", "category")
+     * @param options - Search options including facetQuery (required), optional q, filter, maxValues
+     * @returns Matching facet values with counts
+     */
+    searchFacetValues(facetName: string, options: FacetSearchOptions): Promise<DataTypesFacetValuesSearchResponse>;
+    /**
+     * Get available filter field metadata (schema).
+     * Returns information about all facetable fields including types, sortability, and configured ranges.
+     * Useful for dynamically building filter UIs.
+     *
+     * @returns Filter field metadata with types, default facets, and max values
+     */
+    getFiltersSchema(): Promise<DataTypesFiltersSchemaResponse>;
+}
+/** Options for getFilters() — high-level wrapper with camelCase fields */
+export interface FilterOptions {
+    /** Search query to scope filters */
+    q?: string;
+    /** Active filter string (Typesense filter_by syntax) */
+    filter?: string;
+    /** Comma-separated facet fields to return (defaults to store config) */
+    facetBy?: string;
+    /** Maximum number of values per facet */
+    maxFacetValues?: number;
+    /** Fields that should use disjunctive (OR) faceting */
+    disjunctiveFacets?: string[];
+}
+/** Options for searchFacetValues() — high-level wrapper with camelCase fields */
+export interface FacetSearchOptions {
+    /** Search query to scope the facet values */
+    q?: string;
+    /** Active filter string */
+    filter?: string;
+    /** Query to search within facet values (required) */
+    facetQuery: string;
+    /** Maximum values to return */
+    maxValues?: number;
 }
+export type FilterValue = DataTypesFilterValue;
+export type FilterStats = DataTypesFilterStats;
+export type FilterField = DataTypesFilterField;
+export type FiltersResponse = DataTypesFiltersResponse;
+export type FacetValuesSearchResponse = DataTypesFacetValuesSearchResponse;
+export type FilterSchemaField = DataTypesFilterSchemaField;
+export type FiltersSchemaResponse = DataTypesFiltersSchemaResponse;
 export default SeekoraClient;

package/dist/client.js

@@ -51,8 +51,8 @@ class SeekoraClient {
         if (this.enableContextCollection) {
             this.collectContextAsync();
         }
-        // Initialize event queue if enabled
-        this.enableEventQueue = config.enableEventQueue || false;
+        // Initialize event queue (enabled by default for batching and offline support)
+        this.enableEventQueue = config.enableEventQueue ?? true;
         if (this.enableEventQueue) {
             this.eventQueue = new event_queue_1.EventQueue(config.eventQueue);
             this.eventQueue.setLogger(this.logger);
@@ -99,6 +99,8 @@ class SeekoraClient {
         this.storesApi = new generated_1.SDKStoreConfigApi(this.config);
         this.documentsApi = new generated_1.SDKDocumentsApi(this.config);
         this.schemaApi = new generated_1.SDKSchemaApi(this.config);
+        this.filtersApi = new generated_1.FiltersApi(this.config);
+        this.experimentsApi = new generated_1.SDKExperimentsApi(this.config);
         this.logger.info('SeekoraClient initialized successfully');
     }
     /**
@@ -542,6 +544,37 @@ class SeekoraClient {
             throw this.handleError(error, 'getConfig');
         }
     }
+    /**
+     * Get experiment assignments for the current user
+     *
+     * Returns variant assignments for all running experiments.
+     * Uses hash-based consistent assignment on the backend.
+     *
+     * @returns ExperimentAssignmentResponse with assignments array
+     */
+    async getExperimentAssignment() {
+        this.logger.verbose('Getting experiment assignments');
+        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;
+            const response = await this.experimentsApi.v1ExperimentsAssignmentGet(this.storeId, this.readSecret, this.userId, this.anonId, { headers });
+            const data = response.data;
+            this.logger.info('Experiment assignments retrieved', {
+                count: data?.assignments?.length ?? 0,
+            });
+            return data;
+        }
+        catch (error) {
+            this.logger.error('Failed to get experiment assignments', { error: error.message });
+            throw this.handleError(error, 'getExperimentAssignment');
+        }
+    }
     /**
      * Get store information
      * Returns store metadata including name, status, and configuration details
@@ -1416,6 +1449,7 @@ class SeekoraClient {
         await this.trackEvent({
             event_name: 'product_click',
             clicked_item_id: itemId,
+            position,
             metadata: {
                 position,
             },
@@ -1788,6 +1822,96 @@ class SeekoraClient {
     getLogger() {
         return this.logger;
     }
+    // =========================================================================
+    // Filters API
+    // =========================================================================
+    /**
+     * Get filter values and counts for configured facets.
+     * Use this to build faceted navigation UIs without performing a full search.
+     * Supports disjunctive faceting for OR-based filter combinations.
+     *
+     * @param options - Filter options (query, filters, facet_by, max_facet_values, disjunctive_facets)
+     * @returns Filter values with counts grouped by field
+     */
+    async getFilters(options) {
+        this.logger.verbose('Getting filters', { options });
+        try {
+            const req = {
+                q: options?.q,
+                filter: options?.filter,
+                facet_by: options?.facetBy,
+                max_facet_values: options?.maxFacetValues,
+                disjunctive_facets: options?.disjunctiveFacets,
+            };
+            const response = await this.filtersApi.v1FiltersPost(this.storeId, this.readSecret, req);
+            const wrapper = response.data;
+            const data = wrapper?.data || response.data;
+            this.logger.info('Filters retrieved successfully', {
+                filterCount: data?.filters?.length,
+                totalResults: data?.total_results,
+            });
+            return data;
+        }
+        catch (error) {
+            this.logger.error('Failed to get filters', { error: error.message });
+            throw this.handleError(error, 'getFilters');
+        }
+    }
+    /**
+     * Search within a single facet's values.
+     * Useful for facets with many values (e.g., brands) where you need typeahead/autocomplete.
+     *
+     * @param facetName - The facet field name to search within (e.g., "brand", "category")
+     * @param options - Search options including facetQuery (required), optional q, filter, maxValues
+     * @returns Matching facet values with counts
+     */
+    async searchFacetValues(facetName, options) {
+        this.logger.verbose('Searching facet values', { facetName, options });
+        try {
+            const req = {
+                facet_query: options.facetQuery,
+                q: options?.q,
+                filter: options?.filter,
+                max_values: options?.maxValues,
+            };
+            const response = await this.filtersApi.v1FiltersFacetNameValuesPost(this.storeId, this.readSecret, facetName, req);
+            const wrapper = response.data;
+            const data = wrapper?.data || response.data;
+            this.logger.info('Facet values retrieved', {
+                facetName,
+                valueCount: data?.values?.length,
+            });
+            return data;
+        }
+        catch (error) {
+            this.logger.error('Failed to search facet values', { facetName, error: error.message });
+            throw this.handleError(error, 'searchFacetValues');
+        }
+    }
+    /**
+     * Get available filter field metadata (schema).
+     * Returns information about all facetable fields including types, sortability, and configured ranges.
+     * Useful for dynamically building filter UIs.
+     *
+     * @returns Filter field metadata with types, default facets, and max values
+     */
+    async getFiltersSchema() {
+        this.logger.verbose('Getting filters schema');
+        try {
+            const response = await this.filtersApi.v1FiltersSchemaGet(this.storeId, this.readSecret);
+            const wrapper = response.data;
+            const data = wrapper?.data || response.data;
+            this.logger.info('Filters schema retrieved', {
+                fieldCount: data?.fields?.length,
+                defaultFacets: data?.default_facets?.length,
+            });
+            return data;
+        }
+        catch (error) {
+            this.logger.error('Failed to get filters schema', { error: error.message });
+            throw this.handleError(error, 'getFiltersSchema');
+        }
+    }
 }
 exports.SeekoraClient = SeekoraClient;
 // Export default