aurea-tracking-sdk 1.1.1 → 1.2.0

package/dist/index.d.mts

@@ -2,6 +2,13 @@
  * Aurea Tracking SDK
  * Standalone tracking SDK for external funnels
  */
+type EventCategory = 'viewing' | 'engagement' | 'intent' | 'conversion' | 'custom' | string;
+interface EventCategoryConfig {
+    category: EventCategory;
+    advanceTo?: string;
+    value?: number;
+    description?: string;
+}
 interface AureaConfig {
     apiKey: string;
     funnelId: string;
@@ -17,6 +24,51 @@ interface AureaConfig {
     anonymizeIp?: boolean;
     batchSize?: number;
     batchInterval?: number;
+    eventCategories?: {
+        [eventName: string]: EventCategoryConfig;
+    };
+    autoAdvanceStages?: boolean;
+    customStages?: string[];
+}
+interface TrackingEvent {
+    eventId: string;
+    eventName: string;
+    properties?: Record<string, any>;
+    context: {
+        page?: {
+            url: string;
+            path: string;
+            title?: string;
+            referrer?: string;
+        };
+        utm?: {
+            source?: string;
+            medium?: string;
+            campaign?: string;
+            term?: string;
+            content?: string;
+        };
+        user?: {
+            userId?: string;
+            anonymousId?: string;
+        };
+        session: {
+            sessionId: string;
+        };
+        device?: {
+            userAgent?: string;
+            deviceType?: string;
+            browserName?: string;
+            browserVersion?: string;
+            osName?: string;
+            osVersion?: string;
+            screenWidth?: number;
+            screenHeight?: number;
+            language?: string;
+            timezone?: string;
+        };
+    };
+    timestamp: number;
 }
 interface ConversionData {
     type: string;
@@ -25,6 +77,38 @@ interface ConversionData {
     orderId?: string;
     properties?: Record<string, any>;
 }
+type FunnelStage = 'awareness' | 'interest' | 'desire' | 'checkout' | 'purchase' | 'abandoned' | string;
+interface CheckoutProduct {
+    productId: string;
+    productName?: string;
+    price: number;
+    currency?: string;
+    quantity?: number;
+    variant?: string;
+}
+interface CheckoutCompletedData {
+    orderId: string;
+    revenue: number;
+    currency?: string;
+    products?: CheckoutProduct[];
+    paymentMethod?: string;
+}
+interface MicroConversion {
+    type: string;
+    value: number;
+    properties?: Record<string, any>;
+}
+interface CheckoutContext {
+    originalSessionId: string;
+    anonymousId: string;
+    checkoutStartedAt: number;
+    product: CheckoutProduct;
+    currentStage: FunnelStage;
+    priorStages: FunnelStage[];
+    utmSource?: string;
+    utmCampaign?: string;
+    utmMedium?: string;
+}
 declare class AureaSDK {
     private config;
     private sessionId;
@@ -39,6 +123,12 @@ declare class AureaSDK {
     private lastActiveTimestamp;
     private isPageVisible;
     private webVitalsCollected;
+    private currentStage;
+    private stageHistory;
+    private microConversions;
+    private isInCheckout;
+    private checkoutStartedAt?;
+    private eventCategoryStats;
     constructor(config: AureaConfig);
     /**
      * Initialize the SDK
@@ -60,6 +150,120 @@ declare class AureaSDK {
      * Track a conversion event
      */
     conversion(data: ConversionData): void;
+    /**
+     * Register custom event categories
+     * Allows users to define their own event categorization and auto-stage progression
+     *
+     * @example
+     * aurea.registerEventCategories({
+     *   'video_started': {
+     *     category: 'engagement',
+     *     advanceTo: 'interest',
+     *     value: 30,
+     *     description: 'User started watching sales video'
+     *   },
+     *   'pricing_viewed': {
+     *     category: 'intent',
+     *     advanceTo: 'desire',
+     *     value: 60
+     *   },
+     *   'buy_button_clicked': {
+     *     category: 'conversion',
+     *     value: 90
+     *   }
+     * })
+     */
+    registerEventCategories(categories: {
+        [eventName: string]: EventCategoryConfig;
+    }): void;
+    /**
+     * Track a categorized event with automatic stage progression
+     * This is the recommended way to track events - user defines their own event names
+     *
+     * @param eventName - User-defined event name (e.g., 'video_started', 'pricing_clicked')
+     * @param properties - Additional event properties
+     * @param options - Override category/value/stage for this specific event
+     *
+     * @example
+     * // Using pre-registered category
+     * aurea.trackEvent('video_started', { duration: 120 })
+     *
+     * // One-off event with inline category
+     * aurea.trackEvent('custom_action', { foo: 'bar' }, {
+     *   category: 'engagement',
+     *   value: 40,
+     *   advanceTo: 'interest'
+     * })
+     */
+    trackEvent(eventName: string, properties?: Record<string, any>, options?: {
+        category?: EventCategory;
+        value?: number;
+        advanceTo?: FunnelStage;
+        description?: string;
+    }): void;
+    /**
+     * Get current event category statistics
+     */
+    getCategoryStats(): Record<EventCategory, number>;
+    /**
+     * Get current funnel stage
+     */
+    getCurrentStage(): FunnelStage;
+    /**
+     * Get stage history
+     */
+    getStageHistory(): Array<{
+        stage: FunnelStage;
+        enteredAt: number;
+        durationMs?: number;
+    }>;
+    /**
+     * Enter a new funnel stage
+     */
+    enterStage(stage: FunnelStage): void;
+    /**
+     * Track micro-conversion (engagement signals)
+     *
+     * @deprecated Use trackEvent() instead for more flexibility
+     * This method is kept for backward compatibility
+     *
+     * @param type - Type of micro-conversion (e.g., 'video_played', 'faq_opened')
+     * @param value - Impact score 0-100 (how strong this signal is)
+     * @param properties - Additional metadata
+     * @param autoAdvanceStage - Whether to automatically advance funnel stage (default: true)
+     */
+    trackMicroConversion(type: string, value?: number, properties?: Record<string, any>, autoAdvanceStage?: boolean): void;
+    /**
+     * Determine suggested funnel stage based on micro-conversion type
+     * This uses common patterns to automatically progress users through the funnel
+     */
+    private getSuggestedStageFromMicroConversion;
+    /**
+     * Get funnel stage order for comparison
+     */
+    private getFunnelStageOrder;
+    /**
+     * Track checkout started (user clicked buy button)
+     * This DOES NOT end the session - preserves context for when user returns
+     */
+    checkoutStarted(product: CheckoutProduct): void;
+    /**
+     * Track checkout completed (purchase successful)
+     * Links back to original session if user returned from external checkout
+     */
+    checkoutCompleted(data: CheckoutCompletedData): void;
+    /**
+     * Track checkout abandoned (user left without completing)
+     */
+    checkoutAbandoned(reason?: string): void;
+    /**
+     * Get time spent in a specific stage (in seconds)
+     */
+    private getTimeInCurrentStage;
+    /**
+     * Get UTM parameter from current URL
+     */
+    private getUTMParam;
     /**
      * Get or create session ID
      */
@@ -125,6 +329,11 @@ declare class AureaSDK {
      * Track session timing (active time, duration)
      */
     private trackSessionTiming;
+    /**
+     * Initialize funnel tracking
+     * Checks for returning checkout users and sets initial stage
+     */
+    private initializeFunnelTracking;
     /**
      * Generate unique ID
      */
@@ -159,4 +368,4 @@ declare function trackConversion(data: ConversionData): void;
  */
 declare function trackPage(name?: string, properties?: Record<string, any>): void;
 
-export { getAurea, identifyUser, initAurea, trackConversion, trackEvent, trackPage };
+export { type AureaConfig, AureaSDK, type CheckoutCompletedData, type CheckoutContext, type CheckoutProduct, type ConversionData, type EventCategory, type EventCategoryConfig, type FunnelStage, type MicroConversion, type TrackingEvent, getAurea, identifyUser, initAurea, trackConversion, trackEvent, trackPage };

package/dist/index.d.ts

@@ -2,6 +2,13 @@
  * Aurea Tracking SDK
  * Standalone tracking SDK for external funnels
  */
+type EventCategory = 'viewing' | 'engagement' | 'intent' | 'conversion' | 'custom' | string;
+interface EventCategoryConfig {
+    category: EventCategory;
+    advanceTo?: string;
+    value?: number;
+    description?: string;
+}
 interface AureaConfig {
     apiKey: string;
     funnelId: string;
@@ -17,6 +24,51 @@ interface AureaConfig {
     anonymizeIp?: boolean;
     batchSize?: number;
     batchInterval?: number;
+    eventCategories?: {
+        [eventName: string]: EventCategoryConfig;
+    };
+    autoAdvanceStages?: boolean;
+    customStages?: string[];
+}
+interface TrackingEvent {
+    eventId: string;
+    eventName: string;
+    properties?: Record<string, any>;
+    context: {
+        page?: {
+            url: string;
+            path: string;
+            title?: string;
+            referrer?: string;
+        };
+        utm?: {
+            source?: string;
+            medium?: string;
+            campaign?: string;
+            term?: string;
+            content?: string;
+        };
+        user?: {
+            userId?: string;
+            anonymousId?: string;
+        };
+        session: {
+            sessionId: string;
+        };
+        device?: {
+            userAgent?: string;
+            deviceType?: string;
+            browserName?: string;
+            browserVersion?: string;
+            osName?: string;
+            osVersion?: string;
+            screenWidth?: number;
+            screenHeight?: number;
+            language?: string;
+            timezone?: string;
+        };
+    };
+    timestamp: number;
 }
 interface ConversionData {
     type: string;
@@ -25,6 +77,38 @@ interface ConversionData {
     orderId?: string;
     properties?: Record<string, any>;
 }
+type FunnelStage = 'awareness' | 'interest' | 'desire' | 'checkout' | 'purchase' | 'abandoned' | string;
+interface CheckoutProduct {
+    productId: string;
+    productName?: string;
+    price: number;
+    currency?: string;
+    quantity?: number;
+    variant?: string;
+}
+interface CheckoutCompletedData {
+    orderId: string;
+    revenue: number;
+    currency?: string;
+    products?: CheckoutProduct[];
+    paymentMethod?: string;
+}
+interface MicroConversion {
+    type: string;
+    value: number;
+    properties?: Record<string, any>;
+}
+interface CheckoutContext {
+    originalSessionId: string;
+    anonymousId: string;
+    checkoutStartedAt: number;
+    product: CheckoutProduct;
+    currentStage: FunnelStage;
+    priorStages: FunnelStage[];
+    utmSource?: string;
+    utmCampaign?: string;
+    utmMedium?: string;
+}
 declare class AureaSDK {
     private config;
     private sessionId;
@@ -39,6 +123,12 @@ declare class AureaSDK {
     private lastActiveTimestamp;
     private isPageVisible;
     private webVitalsCollected;
+    private currentStage;
+    private stageHistory;
+    private microConversions;
+    private isInCheckout;
+    private checkoutStartedAt?;
+    private eventCategoryStats;
     constructor(config: AureaConfig);
     /**
      * Initialize the SDK
@@ -60,6 +150,120 @@ declare class AureaSDK {
      * Track a conversion event
      */
     conversion(data: ConversionData): void;
+    /**
+     * Register custom event categories
+     * Allows users to define their own event categorization and auto-stage progression
+     *
+     * @example
+     * aurea.registerEventCategories({
+     *   'video_started': {
+     *     category: 'engagement',
+     *     advanceTo: 'interest',
+     *     value: 30,
+     *     description: 'User started watching sales video'
+     *   },
+     *   'pricing_viewed': {
+     *     category: 'intent',
+     *     advanceTo: 'desire',
+     *     value: 60
+     *   },
+     *   'buy_button_clicked': {
+     *     category: 'conversion',
+     *     value: 90
+     *   }
+     * })
+     */
+    registerEventCategories(categories: {
+        [eventName: string]: EventCategoryConfig;
+    }): void;
+    /**
+     * Track a categorized event with automatic stage progression
+     * This is the recommended way to track events - user defines their own event names
+     *
+     * @param eventName - User-defined event name (e.g., 'video_started', 'pricing_clicked')
+     * @param properties - Additional event properties
+     * @param options - Override category/value/stage for this specific event
+     *
+     * @example
+     * // Using pre-registered category
+     * aurea.trackEvent('video_started', { duration: 120 })
+     *
+     * // One-off event with inline category
+     * aurea.trackEvent('custom_action', { foo: 'bar' }, {
+     *   category: 'engagement',
+     *   value: 40,
+     *   advanceTo: 'interest'
+     * })
+     */
+    trackEvent(eventName: string, properties?: Record<string, any>, options?: {
+        category?: EventCategory;
+        value?: number;
+        advanceTo?: FunnelStage;
+        description?: string;
+    }): void;
+    /**
+     * Get current event category statistics
+     */
+    getCategoryStats(): Record<EventCategory, number>;
+    /**
+     * Get current funnel stage
+     */
+    getCurrentStage(): FunnelStage;
+    /**
+     * Get stage history
+     */
+    getStageHistory(): Array<{
+        stage: FunnelStage;
+        enteredAt: number;
+        durationMs?: number;
+    }>;
+    /**
+     * Enter a new funnel stage
+     */
+    enterStage(stage: FunnelStage): void;
+    /**
+     * Track micro-conversion (engagement signals)
+     *
+     * @deprecated Use trackEvent() instead for more flexibility
+     * This method is kept for backward compatibility
+     *
+     * @param type - Type of micro-conversion (e.g., 'video_played', 'faq_opened')
+     * @param value - Impact score 0-100 (how strong this signal is)
+     * @param properties - Additional metadata
+     * @param autoAdvanceStage - Whether to automatically advance funnel stage (default: true)
+     */
+    trackMicroConversion(type: string, value?: number, properties?: Record<string, any>, autoAdvanceStage?: boolean): void;
+    /**
+     * Determine suggested funnel stage based on micro-conversion type
+     * This uses common patterns to automatically progress users through the funnel
+     */
+    private getSuggestedStageFromMicroConversion;
+    /**
+     * Get funnel stage order for comparison
+     */
+    private getFunnelStageOrder;
+    /**
+     * Track checkout started (user clicked buy button)
+     * This DOES NOT end the session - preserves context for when user returns
+     */
+    checkoutStarted(product: CheckoutProduct): void;
+    /**
+     * Track checkout completed (purchase successful)
+     * Links back to original session if user returned from external checkout
+     */
+    checkoutCompleted(data: CheckoutCompletedData): void;
+    /**
+     * Track checkout abandoned (user left without completing)
+     */
+    checkoutAbandoned(reason?: string): void;
+    /**
+     * Get time spent in a specific stage (in seconds)
+     */
+    private getTimeInCurrentStage;
+    /**
+     * Get UTM parameter from current URL
+     */
+    private getUTMParam;
     /**
      * Get or create session ID
      */
@@ -125,6 +329,11 @@ declare class AureaSDK {
      * Track session timing (active time, duration)
      */
     private trackSessionTiming;
+    /**
+     * Initialize funnel tracking
+     * Checks for returning checkout users and sets initial stage
+     */
+    private initializeFunnelTracking;
     /**
      * Generate unique ID
      */
@@ -159,4 +368,4 @@ declare function trackConversion(data: ConversionData): void;
  */
 declare function trackPage(name?: string, properties?: Record<string, any>): void;
 
-export { getAurea, identifyUser, initAurea, trackConversion, trackEvent, trackPage };
+export { type AureaConfig, AureaSDK, type CheckoutCompletedData, type CheckoutContext, type CheckoutProduct, type ConversionData, type EventCategory, type EventCategoryConfig, type FunnelStage, type MicroConversion, type TrackingEvent, getAurea, identifyUser, initAurea, trackConversion, trackEvent, trackPage };