@seekora-ai/search-sdk 0.2.7 → 0.2.12

package/dist/client.d.ts

@@ -66,6 +66,46 @@ export interface SeekoraClientConfig {
         time_range?: '7d' | '30d' | '90d';
         [key: string]: unknown;
     };
+    /**
+     * Automatically track search result impressions
+     * When enabled, impression events are sent for all items in search results
+     * @default true
+     */
+    autoTrackImpressions?: boolean;
+    /**
+     * Delay before tracking impressions (ms)
+     * Useful to ensure items are actually visible to the user
+     * @default 0
+     */
+    impressionTrackingDelay?: number;
+    /**
+     * Enable event deduplication (industry standard: Segment, Amplitude pattern)
+     * When enabled, generates insert_id for backend deduplication
+     *
+     * Philosophy: Track everything by default, provide tools for deduplication
+     * - false (default): Track all events, no client-side filtering
+     * - true: Generate insert_id for optional backend deduplication
+     *
+     * @default false
+     */
+    enableDeduplication?: boolean;
+    /**
+     * Deduplication time window in milliseconds
+     * Events with same user+event_type+item within this window get same insert_id
+     *
+     * Industry standards:
+     * - Segment: 10 minutes (600000ms)
+     * - Mixpanel: 5 days (but we use shorter for engagement events)
+     * - Amplitude: 7 days (for all events)
+     *
+     * Recommended by event type:
+     * - Engagement (click, view, share): 5 minutes (300000ms)
+     * - Conversion (add_to_cart, wishlist): 5 minutes (300000ms)
+     * - Purchase: 30 days (2592000000ms) - handled separately
+     *
+     * @default 300000 (5 minutes)
+     */
+    deduplicationWindow?: number;
 }
 /**
  * Search context containing identifiers for linking events to searches
@@ -78,6 +118,8 @@ export interface SearchContext {
     correlationId: string;
     /** Search ID from backend (if present in response) */
     searchId?: string;
+    /** Journey ID for session-level tracking */
+    journey_id?: string;
     /** User ID if authenticated */
     userId?: string;
     /** Anonymous user ID */
@@ -101,6 +143,10 @@ export interface ExtendedEventPayload extends DataTypesEventPayload {
     correlation_id?: string;
     /** Search ID at top level (also in metadata for backward compat) */
     search_id?: string;
+    /** Insert ID for event deduplication (industry standard: Segment/Amplitude pattern) */
+    insert_id?: string;
+    /** Conversion type for conversion events (add_to_cart, wishlist, purchase, etc.) */
+    conversion_type?: string;
 }
 export interface SearchOptions {
     q: string;
@@ -282,6 +328,8 @@ export declare class SeekoraClient {
     private enableEventQueue;
     private eventQueue;
     private clientConfig;
+    private enableDeduplication;
+    private deduplicationWindow;
     constructor(config?: SeekoraClientConfig);
     /**
      * Search for documents
@@ -297,11 +345,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?: {
@@ -473,6 +527,11 @@ export declare class SeekoraClient {
      * Send a batch of events directly to the backend (bypasses queue)
      */
     private sendEventsBatchDirect;
+    /**
+     * Automatically track search result impressions
+     * Creates a batch of view events for all items in search results
+     */
+    private autoTrackSearchImpressions;
     /**
      * Get browser context (sync if cached, otherwise returns null)
      * Use collectBrowserContext() for async collection
@@ -482,6 +541,19 @@ export declare class SeekoraClient {
      * Collect browser context asynchronously
      */
     collectBrowserContext(): Promise<BrowserContext>;
+    /**
+     * Generate insert_id for event deduplication (industry standard)
+     *
+     * Format: {user_key}_{event_type}_{item_id}_{timestamp_window}
+     * Similar to Segment, Amplitude, Mixpanel deduplication keys
+     *
+     * @param eventType - Event name (search, click, conversion, etc.)
+     * @param itemId - Item ID (optional, for item-specific events)
+     * @param userId - User ID or anonymous ID
+     * @param window - Deduplication window in milliseconds
+     * @returns insert_id string for backend deduplication
+     */
+    private generateInsertId;
     /**
      * Build event payload with identifiers and browser context
      * Ensures user_id or anon_id is present, and sets correlation_id/search_id at top level
@@ -586,6 +658,53 @@ export declare class SeekoraClient {
      * @param context - Optional search context for linking events to searches
      */
     trackCustom(eventName: string, payload?: Partial<DataTypesEventPayload>, context?: SearchContext): Promise<void>;
+    /**
+     * Track add to cart conversion event
+     *
+     * @param params - Add to cart parameters
+     * @param params.itemId - Item ID that was added to cart
+     * @param params.quantity - Quantity added (default: 1)
+     * @param params.value - Item value/price
+     * @param params.currency - Currency code (default: 'USD')
+     * @param params.position - Position in search results (if from search)
+     * @param params.searchContext - Search context for attribution
+     */
+    trackAddToCart(params: {
+        itemId: string;
+        quantity?: number;
+        value?: number;
+        currency?: string;
+        position?: number;
+        searchContext?: SearchContext;
+    }): Promise<void>;
+    /**
+     * Track add to wishlist conversion event
+     *
+     * @param params - Add to wishlist parameters
+     * @param params.itemId - Item ID that was added to wishlist
+     * @param params.position - Position in search results (if from search)
+     * @param params.searchContext - Search context for attribution
+     */
+    trackAddToWishlist(params: {
+        itemId: string;
+        position?: number;
+        searchContext?: SearchContext;
+    }): Promise<void>;
+    /**
+     * Track item share event
+     *
+     * @param params - Share parameters
+     * @param params.itemId - Item ID that was shared
+     * @param params.shareMethod - Share method (e.g., 'facebook', 'twitter', 'whatsapp', 'copy_link')
+     * @param params.position - Position in search results (if from search)
+     * @param params.searchContext - Search context for attribution
+     */
+    trackShare(params: {
+        itemId: string;
+        shareMethod?: string;
+        position?: number;
+        searchContext?: SearchContext;
+    }): Promise<void>;
     /**
      * Validate an event payload before sending
      * Useful for debugging and ensuring events are properly formatted

package/dist/client.js

@@ -56,6 +56,9 @@ class SeekoraClient {
             this.eventQueue.setLogger(this.logger);
             this.eventQueue.setSender(this.createQueueSender());
         }
+        // Initialize deduplication settings (industry standard: Segment/Amplitude pattern)
+        this.enableDeduplication = config.enableDeduplication || false;
+        this.deduplicationWindow = config.deduplicationWindow || 300000; // Default: 5 minutes
         // Log identifier initialization
         this.logger.verbose('Client identifiers initialized', {
             hasUserId: !!this.userId,
@@ -63,7 +66,9 @@ class SeekoraClient {
             sessionId: this.sessionId.substring(0, 8) + '...',
             autoTrackSearch: this.autoTrackSearch,
             enableContextCollection: this.enableContextCollection,
-            enableEventQueue: this.enableEventQueue
+            enableEventQueue: this.enableEventQueue,
+            enableDeduplication: this.enableDeduplication,
+            deduplicationWindow: this.deduplicationWindow
         });
         this.logger.verbose('Initializing SeekoraClient', {
             storeId: this.storeId,
@@ -275,6 +280,22 @@ class SeekoraClient {
                     this.logger.warn('Failed to auto-track search event', { error: err.message });
                 });
             }
+            // Automatically track search result impressions if enabled
+            if (this.clientConfig.autoTrackImpressions !== false && results.results && results.results.length > 0) {
+                const delay = this.clientConfig.impressionTrackingDelay || 0;
+                const trackImpressions = () => {
+                    this.autoTrackSearchImpressions(results, context).catch((err) => {
+                        // Log but don't fail the search if tracking fails
+                        this.logger.warn('Failed to auto-track impressions', { error: err.message });
+                    });
+                };
+                if (delay > 0) {
+                    setTimeout(trackImpressions, delay);
+                }
+                else {
+                    trackImpressions();
+                }
+            }
             return results;
         }
         catch (error) {
@@ -304,11 +325,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) {
@@ -324,10 +351,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 = {
@@ -385,15 +416,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) {
@@ -1026,6 +1069,52 @@ class SeekoraClient {
             throw new Error(`Failed to send batch events: ${response.status}`);
         }
     }
+    /**
+     * Automatically track search result impressions
+     * Creates a batch of view events for all items in search results
+     */
+    async autoTrackSearchImpressions(searchResponse, context) {
+        const items = searchResponse.results || [];
+        if (items.length === 0) {
+            return;
+        }
+        this.logger.verbose('Auto-tracking search impressions', {
+            itemCount: items.length,
+            query: searchResponse.query || searchResponse.data?.data?.query,
+            searchId: context.searchId
+        });
+        // Create batch impression events
+        const impressionEvents = items.map((item, index) => ({
+            event_name: 'view',
+            event_id: (0, utils_1.generateUUID)(),
+            event_ts: new Date().toISOString(),
+            // Link to search
+            search_id: context.searchId,
+            journey_id: context.journey_id,
+            correlation_id: context.correlationId,
+            session_id: context.sessionId || this.sessionId,
+            // User context
+            user_id: context.userId || this.userId,
+            anonymous_id: context.anonId || this.anonId,
+            // Item details
+            clicked_item_id: item.id,
+            position: index + 1,
+            query: searchResponse.query || searchResponse.data?.data?.query,
+            // Optional metadata
+            analytics_tags: ['source:search', 'auto_tracked:true']
+        }));
+        try {
+            await this.trackEvents(impressionEvents);
+            this.logger.debug('Auto-tracked search impressions', { count: impressionEvents.length });
+        }
+        catch (error) {
+            this.logger.error('Failed to auto-track impressions', {
+                error: error.message,
+                itemCount: items.length
+            });
+            throw error;
+        }
+    }
     /**
      * Get browser context (sync if cached, otherwise returns null)
      * Use collectBrowserContext() for async collection
@@ -1040,6 +1129,31 @@ class SeekoraClient {
         this.cachedBrowserContext = await this.contextCollector.collect();
         return this.cachedBrowserContext;
     }
+    /**
+     * Generate insert_id for event deduplication (industry standard)
+     *
+     * Format: {user_key}_{event_type}_{item_id}_{timestamp_window}
+     * Similar to Segment, Amplitude, Mixpanel deduplication keys
+     *
+     * @param eventType - Event name (search, click, conversion, etc.)
+     * @param itemId - Item ID (optional, for item-specific events)
+     * @param userId - User ID or anonymous ID
+     * @param window - Deduplication window in milliseconds
+     * @returns insert_id string for backend deduplication
+     */
+    generateInsertId(eventType, itemId, userId, window) {
+        // Round timestamp to nearest window (5 min default)
+        const timestamp = Math.floor(Date.now() / window);
+        // Format: userKey_eventType_itemId_timestampWindow
+        // Item ID is optional (not all events have items)
+        const parts = [
+            userId.replace(/[^a-zA-Z0-9]/g, '_'), // Sanitize user ID
+            eventType.replace(/[^a-zA-Z0-9]/g, '_'), // Sanitize event type
+            itemId ? itemId.replace(/[^a-zA-Z0-9]/g, '_') : 'null',
+            timestamp.toString()
+        ];
+        return parts.join('_');
+    }
     /**
      * Build event payload with identifiers and browser context
      * Ensures user_id or anon_id is present, and sets correlation_id/search_id at top level
@@ -1121,6 +1235,26 @@ class SeekoraClient {
             payload.is_tablet = ctx.is_tablet ? 1 : 0;
             payload.is_touch_device = ctx.is_touch_device;
         }
+        // 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
+        const isPurchaseEvent = payload.event_name === 'conversion' &&
+            (payload.conversion_type === 'purchase' || payload.conversion_type === 'checkout_completed');
+        if (this.enableDeduplication || isPurchaseEvent) {
+            const userKey = payload.user_id || payload.anon_id || this.anonId;
+            const eventType = payload.event_name || 'unknown';
+            const itemId = payload.clicked_item_id;
+            // Use longer window for purchase events (30 days)
+            const window = isPurchaseEvent ? 2592000000 : this.deduplicationWindow;
+            payload.insert_id = this.generateInsertId(eventType, itemId, userKey, window);
+            this.logger.verbose('Generated insert_id for deduplication', {
+                event_name: eventType,
+                item_id: itemId,
+                insert_id: payload.insert_id,
+                is_purchase: isPurchaseEvent,
+                window_ms: window
+            });
+        }
         return payload;
     }
     /**
@@ -1327,6 +1461,82 @@ class SeekoraClient {
             event_name: eventName,
         }, context);
     }
+    /**
+     * Track add to cart conversion event
+     *
+     * @param params - Add to cart parameters
+     * @param params.itemId - Item ID that was added to cart
+     * @param params.quantity - Quantity added (default: 1)
+     * @param params.value - Item value/price
+     * @param params.currency - Currency code (default: 'USD')
+     * @param params.position - Position in search results (if from search)
+     * @param params.searchContext - Search context for attribution
+     */
+    async trackAddToCart(params) {
+        this.logger.verbose('Tracking add to cart event', {
+            itemId: params.itemId,
+            quantity: params.quantity,
+            value: params.value
+        });
+        await this.trackEvent({
+            event_name: 'conversion',
+            conversion_type: 'add_to_cart',
+            clicked_item_id: params.itemId,
+            quantity: params.quantity || 1,
+            value: params.value,
+            currency: params.currency || 'USD',
+            position: params.position,
+            analytics_tags: ['action:add_to_cart'],
+        }, params.searchContext);
+    }
+    /**
+     * Track add to wishlist conversion event
+     *
+     * @param params - Add to wishlist parameters
+     * @param params.itemId - Item ID that was added to wishlist
+     * @param params.position - Position in search results (if from search)
+     * @param params.searchContext - Search context for attribution
+     */
+    async trackAddToWishlist(params) {
+        this.logger.verbose('Tracking add to wishlist event', {
+            itemId: params.itemId
+        });
+        await this.trackEvent({
+            event_name: 'conversion',
+            conversion_type: 'wishlist',
+            clicked_item_id: params.itemId,
+            position: params.position,
+            analytics_tags: ['action:add_to_wishlist'],
+        }, params.searchContext);
+    }
+    /**
+     * Track item share event
+     *
+     * @param params - Share parameters
+     * @param params.itemId - Item ID that was shared
+     * @param params.shareMethod - Share method (e.g., 'facebook', 'twitter', 'whatsapp', 'copy_link')
+     * @param params.position - Position in search results (if from search)
+     * @param params.searchContext - Search context for attribution
+     */
+    async trackShare(params) {
+        this.logger.verbose('Tracking share event', {
+            itemId: params.itemId,
+            shareMethod: params.shareMethod
+        });
+        await this.trackEvent({
+            event_name: 'custom',
+            clicked_item_id: params.itemId,
+            position: params.position,
+            analytics_tags: [
+                'action:share',
+                `share_method:${params.shareMethod || 'unknown'}`
+            ],
+            custom_json: JSON.stringify({
+                share_method: params.shareMethod,
+                action_type: 'share'
+            }),
+        }, params.searchContext);
+    }
     /**
      * Validate an event payload before sending
      * Useful for debugging and ensuring events are properly formatted