aurea-tracking-sdk 1.1.2 → 1.3.0

package/dist/index.js

@@ -19,6 +19,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AureaSDK: () => AureaSDK,
   getAurea: () => getAurea,
   identifyUser: () => identifyUser,
   initAurea: () => initAurea,
@@ -45,6 +46,15 @@ var AureaSDK = class {
       fcp: false,
       ttfb: false
     };
+    // NEW: Funnel tracking
+    this.currentStage = "awareness";
+    this.stageHistory = [];
+    this.microConversions = [];
+    this.isInCheckout = false;
+    // NEW: Event categorization tracking
+    this.eventCategoryStats = /* @__PURE__ */ new Map();
+    // NEW: Track which events have been fired (for trackOnce behavior)
+    this.trackedOnceEvents = /* @__PURE__ */ new Set();
     this.config = {
       apiUrl: "http://localhost:3000/api",
       debug: false,
@@ -98,11 +108,13 @@ var AureaSDK = class {
     this.startPurchasePolling();
     this.trackWebVitals();
     this.trackSessionTiming();
+    this.initializeFunnelTracking();
     if (this.config.debug) {
       console.log("[Aurea SDK] Initialized", {
         sessionId: this.sessionId,
         anonymousId: this.anonymousId,
-        userId: this.userId
+        userId: this.userId,
+        currentStage: this.currentStage
       });
     }
   }
@@ -180,6 +192,372 @@ var AureaSDK = class {
       console.log("[Aurea SDK] Conversion tracked:", data);
     }
   }
+  /**
+   * 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) {
+    if (!this.config.eventCategories) {
+      this.config.eventCategories = {};
+    }
+    this.config.eventCategories = {
+      ...this.config.eventCategories,
+      ...categories
+    };
+    if (this.config.debug) {
+      console.log("[Aurea SDK] Event categories registered:", categories);
+    }
+  }
+  /**
+   * 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, properties, options) {
+    const categoryConfig = this.config.eventCategories?.[eventName];
+    const category = options?.category || categoryConfig?.category || "custom";
+    const value = options?.value ?? categoryConfig?.value ?? 50;
+    const advanceTo = options?.advanceTo || categoryConfig?.advanceTo;
+    const description = options?.description || categoryConfig?.description;
+    const trackOnce = categoryConfig?.trackOnce ?? false;
+    if (trackOnce) {
+      if (this.trackedOnceEvents.has(eventName)) {
+        if (this.config.debug) {
+          console.log(`[Aurea SDK] Event skipped (already tracked once): ${eventName}`);
+        }
+        return;
+      }
+      this.trackedOnceEvents.add(eventName);
+    }
+    this.eventCategoryStats.set(
+      category,
+      (this.eventCategoryStats.get(category) || 0) + 1
+    );
+    const autoAdvance = this.config.autoAdvanceStages !== false;
+    if (autoAdvance && advanceTo && advanceTo !== this.currentStage) {
+      this.enterStage(advanceTo);
+    }
+    this.track(eventName, {
+      ...properties,
+      // Add categorization metadata
+      _category: category,
+      _value: value,
+      _description: description,
+      _currentStage: this.currentStage,
+      _categoryStats: Object.fromEntries(this.eventCategoryStats),
+      _trackedOnce: trackOnce
+      // Include for backend reference
+    });
+    if (this.config.debug) {
+      console.log(`[Aurea SDK] Event tracked: ${eventName} [${category}] (value: ${value}, stage: ${this.currentStage}${trackOnce ? ", once-only" : ""})`);
+    }
+  }
+  /**
+   * Get current event category statistics
+   */
+  getCategoryStats() {
+    return Object.fromEntries(this.eventCategoryStats);
+  }
+  /**
+   * Get current funnel stage
+   */
+  getCurrentStage() {
+    return this.currentStage;
+  }
+  /**
+   * Get stage history
+   */
+  getStageHistory() {
+    return this.stageHistory.map((entry, index) => {
+      const nextEntry = this.stageHistory[index + 1];
+      const durationMs = nextEntry ? nextEntry.enteredAt - entry.enteredAt : Date.now() - entry.enteredAt;
+      return {
+        stage: entry.stage,
+        enteredAt: entry.enteredAt,
+        durationMs
+      };
+    });
+  }
+  /**
+   * Enter a new funnel stage
+   */
+  enterStage(stage) {
+    const previousStage = this.currentStage;
+    this.currentStage = stage;
+    this.stageHistory.push({
+      stage,
+      enteredAt: Date.now()
+    });
+    this.track("funnel_stage_entered", {
+      stage,
+      previousStage,
+      stageHistory: this.stageHistory,
+      timeInPreviousStage: this.getTimeInCurrentStage(previousStage)
+    });
+    if (this.config.debug) {
+      console.log(`[Aurea SDK] Entered funnel stage: ${previousStage} \u2192 ${stage}`);
+    }
+  }
+  /**
+   * 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, value = 50, properties, autoAdvanceStage = true) {
+    const microConversion = {
+      type,
+      value,
+      properties
+    };
+    this.microConversions.push(microConversion);
+    const categoryConfig = this.config.eventCategories?.[type];
+    if (autoAdvanceStage) {
+      if (categoryConfig?.advanceTo && categoryConfig.advanceTo !== this.currentStage) {
+        this.enterStage(categoryConfig.advanceTo);
+      } else {
+        const suggestedStage = this.getSuggestedStageFromMicroConversion(type, value);
+        if (suggestedStage && suggestedStage !== this.currentStage) {
+          this.enterStage(suggestedStage);
+        }
+      }
+    }
+    this.track("micro_conversion", {
+      microConversionType: type,
+      value,
+      category: categoryConfig?.category || "custom",
+      currentStage: this.currentStage,
+      totalMicroConversions: this.microConversions.length,
+      ...properties
+    });
+    if (this.config.debug) {
+      console.log(`[Aurea SDK] Micro-conversion: ${type} (value: ${value}, stage: ${this.currentStage})`);
+    }
+  }
+  /**
+   * Determine suggested funnel stage based on micro-conversion type
+   * This uses common patterns to automatically progress users through the funnel
+   */
+  getSuggestedStageFromMicroConversion(type, value) {
+    const currentStageIndex = this.getFunnelStageOrder().indexOf(this.currentStage);
+    const interestSignals = [
+      "video_played",
+      "video_started",
+      "video_25_percent",
+      "video_50_percent",
+      "scroll_depth_25",
+      "scroll_depth_50",
+      "page_section_viewed",
+      "testimonial_viewed",
+      "feature_section_viewed"
+    ];
+    const desireSignals = [
+      "video_75_percent",
+      "video_completed",
+      "faq_opened",
+      "pricing_viewed",
+      "cta_section_viewed",
+      "scroll_depth_75",
+      "comparison_table_viewed",
+      "guarantee_section_viewed",
+      "bonus_section_viewed"
+    ];
+    const checkoutIntentSignals = [
+      "buy_button_hovered",
+      "checkout_button_clicked",
+      "add_to_cart",
+      "pricing_tier_selected"
+    ];
+    if (interestSignals.includes(type) && currentStageIndex < 1) {
+      return "interest";
+    }
+    if (desireSignals.includes(type) && currentStageIndex < 2) {
+      return "desire";
+    }
+    if (checkoutIntentSignals.includes(type) && currentStageIndex < 3) {
+      if (this.config.debug) {
+        console.log(`[Aurea SDK] High checkout intent detected: ${type}`);
+      }
+    }
+    if (value >= 80 && currentStageIndex < 2) {
+      return "desire";
+    }
+    return null;
+  }
+  /**
+   * Get funnel stage order for comparison
+   */
+  getFunnelStageOrder() {
+    return ["awareness", "interest", "desire", "checkout", "purchase", "abandoned"];
+  }
+  /**
+   * Track checkout started (user clicked buy button)
+   * This DOES NOT end the session - preserves context for when user returns
+   */
+  checkoutStarted(product) {
+    this.isInCheckout = true;
+    this.checkoutStartedAt = Date.now();
+    this.enterStage("checkout");
+    const checkoutContext = {
+      originalSessionId: this.sessionId,
+      anonymousId: this.anonymousId,
+      checkoutStartedAt: this.checkoutStartedAt,
+      product,
+      currentStage: this.currentStage,
+      priorStages: this.stageHistory.map((h) => h.stage),
+      utmSource: this.getUTMParam("utm_source"),
+      utmCampaign: this.getUTMParam("utm_campaign"),
+      utmMedium: this.getUTMParam("utm_medium")
+    };
+    if (typeof localStorage !== "undefined") {
+      localStorage.setItem("aurea_checkout_context", JSON.stringify(checkoutContext));
+    }
+    this.track("checkout_started", {
+      productId: product.productId,
+      productName: product.productName,
+      price: product.price,
+      currency: product.currency || "USD",
+      quantity: product.quantity || 1,
+      variant: product.variant,
+      sessionDurationSoFar: Math.floor((Date.now() - this.sessionStartTime) / 1e3),
+      microConversionsCount: this.microConversions.length,
+      priorStages: this.stageHistory.map((h) => h.stage)
+    });
+    if (this.config.debug) {
+      console.log("[Aurea SDK] Checkout started:", product);
+      console.log("[Aurea SDK] Session context preserved for return journey");
+    }
+  }
+  /**
+   * Track checkout completed (purchase successful)
+   * Links back to original session if user returned from external checkout
+   */
+  checkoutCompleted(data) {
+    let checkoutContext = null;
+    let checkoutDuration;
+    if (typeof localStorage !== "undefined") {
+      const stored = localStorage.getItem("aurea_checkout_context");
+      if (stored) {
+        try {
+          checkoutContext = JSON.parse(stored);
+          checkoutDuration = Math.floor((Date.now() - checkoutContext.checkoutStartedAt) / 1e3);
+          localStorage.removeItem("aurea_checkout_context");
+        } catch (e) {
+          console.error("[Aurea SDK] Failed to parse checkout context:", e);
+        }
+      }
+    }
+    this.enterStage("purchase");
+    this.track("checkout_completed", {
+      orderId: data.orderId,
+      revenue: data.revenue,
+      currency: data.currency || "USD",
+      paymentMethod: data.paymentMethod,
+      products: data.products,
+      // Link to original session if available
+      originalSessionId: checkoutContext?.originalSessionId,
+      checkoutDuration,
+      totalSessionDuration: Math.floor((Date.now() - this.sessionStartTime) / 1e3),
+      // Attribution data from original session
+      originalUtmSource: checkoutContext?.utmSource,
+      originalUtmCampaign: checkoutContext?.utmCampaign,
+      originalUtmMedium: checkoutContext?.utmMedium,
+      priorStages: checkoutContext?.priorStages || this.stageHistory.map((h) => h.stage),
+      // Engagement data
+      microConversionsCount: this.microConversions.length,
+      microConversions: this.microConversions
+    });
+    this.conversion({
+      type: "purchase",
+      revenue: data.revenue,
+      currency: data.currency,
+      orderId: data.orderId
+    });
+    if (this.config.debug) {
+      console.log("[Aurea SDK] Checkout completed:", data);
+      if (checkoutContext) {
+        console.log("[Aurea SDK] Session bridged - linked to original session:", checkoutContext.originalSessionId);
+      }
+    }
+  }
+  /**
+   * Track checkout abandoned (user left without completing)
+   */
+  checkoutAbandoned(reason) {
+    if (!this.isInCheckout) {
+      return;
+    }
+    const checkoutDuration = this.checkoutStartedAt ? Math.floor((Date.now() - this.checkoutStartedAt) / 1e3) : void 0;
+    this.enterStage("abandoned");
+    this.track("checkout_abandoned", {
+      reason: reason || "unknown",
+      checkoutDuration,
+      sessionDuration: Math.floor((Date.now() - this.sessionStartTime) / 1e3),
+      microConversionsCount: this.microConversions.length,
+      priorStages: this.stageHistory.map((h) => h.stage)
+    });
+    this.isInCheckout = false;
+    if (this.config.debug) {
+      console.log("[Aurea SDK] Checkout abandoned:", reason);
+    }
+  }
+  /**
+   * Get time spent in a specific stage (in seconds)
+   */
+  getTimeInCurrentStage(stage) {
+    const stageEntries = this.stageHistory.filter((h) => h.stage === stage);
+    if (stageEntries.length === 0) return 0;
+    const lastEntry = stageEntries[stageEntries.length - 1];
+    const nextEntry = this.stageHistory.find((h) => h.enteredAt > lastEntry.enteredAt);
+    const endTime = nextEntry ? nextEntry.enteredAt : Date.now();
+    return Math.floor((endTime - lastEntry.enteredAt) / 1e3);
+  }
+  /**
+   * Get UTM parameter from current URL
+   */
+  getUTMParam(param) {
+    if (typeof window === "undefined") return void 0;
+    const urlParams = new URLSearchParams(window.location.search);
+    return urlParams.get(param) || void 0;
+  }
   /**
    * Get or create session ID
    */
@@ -581,6 +959,9 @@ var AureaSDK = class {
     window.addEventListener("touchstart", resetInactivityTimer, { passive: true });
     window.addEventListener("beforeunload", () => {
       const now = Date.now();
+      if (this.isInCheckout && this.currentStage === "checkout") {
+        this.checkoutAbandoned("page_close");
+      }
       if (this.isPageVisible) {
         this.activeTime += now - this.lastActiveTimestamp;
       }
@@ -627,6 +1008,53 @@ var AureaSDK = class {
       console.log("[Aurea SDK] Session timing tracking enabled");
     }
   }
+  /**
+   * Initialize funnel tracking
+   * Checks for returning checkout users and sets initial stage
+   */
+  initializeFunnelTracking() {
+    if (typeof window === "undefined") return;
+    if (typeof localStorage !== "undefined") {
+      const checkoutContext = localStorage.getItem("aurea_checkout_context");
+      if (checkoutContext) {
+        try {
+          const context = JSON.parse(checkoutContext);
+          const urlParams = new URLSearchParams(window.location.search);
+          const purchased = urlParams.get("purchased") === "true";
+          if (purchased) {
+            if (this.config.debug) {
+              console.log(
+                "[Aurea SDK] Returning from successful checkout - awaiting checkoutCompleted() call"
+              );
+            }
+          } else {
+            const timeSinceCheckout = Date.now() - context.checkoutStartedAt;
+            const fifteenMinutes = 15 * 60 * 1e3;
+            if (timeSinceCheckout > fifteenMinutes) {
+              if (this.config.debug) {
+                console.log(
+                  "[Aurea SDK] Checkout abandoned (15+ min elapsed)"
+                );
+              }
+            }
+          }
+        } catch (err) {
+          console.error(
+            "[Aurea SDK] Failed to parse checkout context:",
+            err
+          );
+          localStorage.removeItem("aurea_checkout_context");
+        }
+      }
+    }
+    this.stageHistory.push({
+      stage: "awareness",
+      enteredAt: Date.now()
+    });
+    if (this.config.debug) {
+      console.log("[Aurea SDK] Funnel tracking initialized - Stage: awareness");
+    }
+  }
   /**
    * Generate unique ID
    */
@@ -690,6 +1118,7 @@ function trackPage(name, properties) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AureaSDK,
   getAurea,
   identifyUser,
   initAurea,