@seekora-ai/search-sdk 0.2.8 → 0.2.13

package/dist/client.d.ts

@@ -78,6 +78,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 +155,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;
@@ -330,6 +342,8 @@ export declare class SeekoraClient {
     private clientConfig;
     private enableDeduplication;
     private deduplicationWindow;
+    private abTestId?;
+    private abVariant?;
     constructor(config?: SeekoraClientConfig);
     /**
      * Search for documents
@@ -345,11 +359,17 @@ export declare class SeekoraClient {
     /**
      * 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).
+     * **NEW:** Full GET/POST parity! Automatically chooses the best method:
+     * - GET: Default for simple requests, including filtered_tabs with ≤5 tabs (faster, cacheable)
+     * - POST: Used for complex filtered_tabs (>5 tabs) or when explicitly requested via options.method = 'POST'
+     *
+     * With returnFullResponse: true returns full shape including extensions (dropdown_recommendations with trending products, filtered_tabs).
      *
      * @param query - Partial query to get suggestions for
      * @param options - Optional parameters for suggestions
+     * @param options.filtered_tabs - Tab configurations (now supported in GET!)
+     * @param options.include_dropdown_recommendations - Include rich dropdown data
+     * @param options.method - Explicitly set 'POST' to force POST method
      * @returns Suggestion hits array, or QuerySuggestionsFullResponse when returnFullResponse is true
      */
     getSuggestions(query: string, options?: {
@@ -737,6 +757,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)
      */

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);
@@ -325,11 +327,17 @@ class SeekoraClient {
     /**
      * 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).
+     * **NEW:** Full GET/POST parity! Automatically chooses the best method:
+     * - GET: Default for simple requests, including filtered_tabs with ≤5 tabs (faster, cacheable)
+     * - POST: Used for complex filtered_tabs (>5 tabs) or when explicitly requested via options.method = 'POST'
+     *
+     * With returnFullResponse: true returns full shape including extensions (dropdown_recommendations with trending products, filtered_tabs).
      *
      * @param query - Partial query to get suggestions for
      * @param options - Optional parameters for suggestions
+     * @param options.filtered_tabs - Tab configurations (now supported in GET!)
+     * @param options.include_dropdown_recommendations - Include rich dropdown data
+     * @param options.method - Explicitly set 'POST' to force POST method
      * @returns Suggestion hits array, or QuerySuggestionsFullResponse when returnFullResponse is true
      */
     async getSuggestions(query, options) {
@@ -345,10 +353,14 @@ class SeekoraClient {
                 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 ||
-                options?.include_dropdown_product_list === false ||
-                options?.include_filtered_tabs === false;
+            // Use POST for:
+            // - Complex filtered_tabs (5+ tabs or very long JSON would exceed URL limits)
+            // - Explicit preference for POST (options.method === 'POST')
+            // Use GET for everything else (including simple filtered_tabs)
+            const hasComplexFilteredTabs = options?.filtered_tabs &&
+                options.filtered_tabs.length > 5;
+            const usePost = hasComplexFilteredTabs ||
+                options?.method === 'POST'; // Allow explicit POST preference
             const defaults = this.clientConfig?.suggestionsDefaults;
             const buildRequestBody = () => {
                 const body = {
@@ -406,15 +418,27 @@ class SeekoraClient {
                 });
                 return suggestions;
             }
-            // GET for simple requests (no filtered_tabs, no include_dropdown_recommendations)
+            // GET for simple requests and simple filtered_tabs (URL-encoded JSON)
             this.logger.verbose('Using GET endpoint', {
                 endpoint: '/api/v1/suggestions/queries',
                 query,
+                hasFilteredTabs: !!(options?.filtered_tabs && options.filtered_tabs.length > 0),
             });
             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 });
+            // Encode filtered_tabs as JSON string for URL parameter
+            const filteredTabsParam = options?.filtered_tabs
+                ? JSON.stringify(options.filtered_tabs)
+                : undefined;
+            const response = await this.suggestionsApi.v1SuggestionsQueriesGet(this.storeId, this.readSecret, this.userId, this.anonId, this.sessionId, query, // query parameter
+            undefined, // q parameter (alias for query)
+            options?.hitsPerPage || 5, options?.page, analyticsTags, options?.tags_match_mode, options?.include_categories, options?.include_facets, options?.include_dropdown_recommendations, options?.include_dropdown_product_list, options?.include_filtered_tabs, undefined, // include_empty_query_recommendations
+            options?.max_categories, options?.max_facets, options?.min_popularity, options?.time_range, options?.disable_typo_tolerance, filteredTabsParam, // filtered_tabs as JSON string
+            undefined, // userId (using header instead)
+            undefined, // anonId (using header instead)
+            undefined, // sessionId (using header instead)
+            { headers });
             const responseData = response.data?.data || response.data;
             const suggestions = responseData?.results?.[0]?.hits || responseData?.hits || [];
             if (options?.returnFullResponse) {
@@ -1213,6 +1237,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
@@ -1609,6 +1640,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)
      */