@seekora-ai/search-sdk 0.2.12 → 0.2.14

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;
     /**
@@ -78,6 +79,14 @@ export interface SeekoraClientConfig {
      * @default 0
      */
     impressionTrackingDelay?: number;
+    /**
+     * A/B test experiment ID to include in all analytics events
+     */
+    abTestId?: string;
+    /**
+     * A/B test variant to include in all analytics events
+     */
+    abVariant?: string;
     /**
      * Enable event deduplication (industry standard: Segment, Amplitude pattern)
      * When enabled, generates insert_id for backend deduplication
@@ -147,6 +156,10 @@ export interface ExtendedEventPayload extends DataTypesEventPayload {
     insert_id?: string;
     /** Conversion type for conversion events (add_to_cart, wishlist, purchase, etc.) */
     conversion_type?: string;
+    /** A/B test experiment ID */
+    ab_test_id?: string;
+    /** A/B test variant */
+    ab_variant?: string;
 }
 export interface SearchOptions {
     q: string;
@@ -314,6 +327,8 @@ export declare class SeekoraClient {
     private storesApi;
     private documentsApi;
     private schemaApi;
+    private filtersApi;
+    private experimentsApi;
     private storeId;
     private readSecret;
     private writeSecret?;
@@ -330,6 +345,8 @@ export declare class SeekoraClient {
     private clientConfig;
     private enableDeduplication;
     private deduplicationWindow;
+    private abTestId?;
+    private abVariant?;
     constructor(config?: SeekoraClientConfig);
     /**
      * Search for documents
@@ -394,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
@@ -743,6 +769,18 @@ export declare class SeekoraClient {
         anonId: string;
         sessionId: string;
     };
+    /**
+     * Set A/B test experiment ID and variant for all subsequent analytics events.
+     * Call this when experiment assignments are fetched.
+     */
+    setAbTest(abTestId?: string, abVariant?: string): void;
+    /**
+     * Get current A/B test fields
+     */
+    getAbTest(): {
+        abTestId?: string;
+        abVariant?: string;
+    };
     /**
      * Get the event queue instance (if enabled)
      */
@@ -787,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

@@ -42,6 +42,8 @@ class SeekoraClient {
         this.anonId = config.anonId || (0, utils_1.getOrCreateAnonId)();
         this.sessionId = config.sessionId || (0, utils_1.getOrCreateSessionId)();
         this.autoTrackSearch = config.autoTrackSearch || false;
+        this.abTestId = config.abTestId;
+        this.abVariant = config.abVariant;
         // Initialize context collection
         this.enableContextCollection = config.enableContextCollection !== false; // Default to true
         this.contextCollector = new context_collector_1.ContextCollector(config.contextCollector);
@@ -49,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);
@@ -97,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');
     }
     /**
@@ -540,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
@@ -1235,6 +1270,13 @@ class SeekoraClient {
             payload.is_tablet = ctx.is_tablet ? 1 : 0;
             payload.is_touch_device = ctx.is_touch_device;
         }
+        // Inject A/B test fields from client config (event-level values take precedence)
+        if (this.abTestId && !payload.ab_test_id) {
+            payload.ab_test_id = this.abTestId;
+        }
+        if (this.abVariant && !payload.ab_variant) {
+            payload.ab_variant = this.abVariant;
+        }
         // Generate insert_id for deduplication (industry standard: Segment/Amplitude pattern)
         // Always enable for purchase events (revenue must be accurate)
         // Optional for other events based on config
@@ -1631,6 +1673,21 @@ class SeekoraClient {
             sessionId: this.sessionId,
         };
     }
+    /**
+     * Set A/B test experiment ID and variant for all subsequent analytics events.
+     * Call this when experiment assignments are fetched.
+     */
+    setAbTest(abTestId, abVariant) {
+        this.abTestId = abTestId;
+        this.abVariant = abVariant;
+        this.logger.verbose('A/B test fields updated', { abTestId, abVariant });
+    }
+    /**
+     * Get current A/B test fields
+     */
+    getAbTest() {
+        return { abTestId: this.abTestId, abVariant: this.abVariant };
+    }
     /**
      * Get the event queue instance (if enabled)
      */
@@ -1764,6 +1821,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