@seekora-ai/search-sdk 0.2.7 → 0.2.8

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
@@ -473,6 +521,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 +535,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 +652,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) {
@@ -1026,6 +1047,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 +1107,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 +1213,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 +1439,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