@outlit/browser 0.2.2 → 0.4.0

package/dist/react/index.mjs

@@ -9,7 +9,8 @@ import {
   buildFormEvent,
   buildIdentifyEvent,
   buildIngestPayload,
-  buildPageviewEvent
+  buildPageviewEvent,
+  buildStageEvent
 } from "@outlit/core";
 
 // src/autocapture.ts
@@ -229,6 +230,7 @@ var DEFAULT_IDLE_TIMEOUT = 3e4;
 var SESSION_TIMEOUT = 30 * 60 * 1e3;
 var TIME_UPDATE_INTERVAL = 1e3;
 var MIN_SPURIOUS_THRESHOLD = 50;
+var MIN_PAGE_TIME_FOR_ENGAGEMENT = 500;
 var SESSION_ID_KEY = "outlit_session_id";
 var SESSION_LAST_ACTIVITY_KEY = "outlit_session_last_activity";
 var SessionTracker = class {
@@ -273,7 +275,8 @@ var SessionTracker = class {
     this.updateActiveTime();
     const totalTimeMs = Date.now() - this.state.pageEntryTime;
     const isSpuriousEvent = this.state.activeTimeMs < MIN_SPURIOUS_THRESHOLD && totalTimeMs < MIN_SPURIOUS_THRESHOLD;
-    if (!isSpuriousEvent) {
+    const isTooSoonAfterNavigation = totalTimeMs < MIN_PAGE_TIME_FOR_ENGAGEMENT;
+    if (!isSpuriousEvent && !isTooSoonAfterNavigation) {
       const event = buildEngagementEvent({
         url: this.state.currentUrl,
         referrer: document.referrer,
@@ -459,6 +462,7 @@ var SessionTracker = class {
       this.checkSessionExpiry();
       this.state.lastActiveTime = Date.now();
       this.state.hasEmittedEngagement = false;
+      this.updateSessionActivity();
     }
   }
   /**
@@ -614,6 +618,9 @@ var Outlit = class {
   options;
   hasHandledExit = false;
   sessionTracker = null;
+  // User identity state for stage events
+  currentUser = null;
+  pendingUser = null;
   constructor(options) {
     this.publicKey = options.publicKey;
     this.apiHost = options.apiHost ?? DEFAULT_API_HOST;
@@ -659,9 +666,7 @@ var Outlit = class {
     }
     this.visitorId = getOrCreateVisitorId();
     this.startFlushTimer();
-    if (this.options.trackEngagement !== false) {
-      this.initSessionTracking();
-    }
+    this.initSessionTracking();
     if (this.options.trackPageviews !== false) {
       this.initPageviewTracking();
     }
@@ -672,6 +677,10 @@ var Outlit = class {
       this.initCalendarTracking();
     }
     this.isTrackingEnabled = true;
+    if (this.pendingUser) {
+      this.applyUser(this.pendingUser);
+      this.pendingUser = null;
+    }
   }
   /**
    * Check if tracking is currently enabled.
@@ -698,12 +707,21 @@ var Outlit = class {
   /**
    * Identify the current visitor.
    * Links the anonymous visitor to a known user.
+   *
+   * When email or userId is provided, also sets the current user identity
+   * for stage events (activate, engaged, paid).
    */
   identify(options) {
     if (!this.isTrackingEnabled) {
       console.warn("[Outlit] Tracking not enabled. Call enableTracking() first.");
       return;
     }
+    if (options.email || options.userId) {
+      this.currentUser = {
+        email: options.email,
+        userId: options.userId
+      };
+    }
     const event = buildIdentifyEvent({
       url: window.location.href,
       referrer: document.referrer,
@@ -713,6 +731,98 @@ var Outlit = class {
     });
     this.enqueue(event);
   }
+  /**
+   * Set the current user identity.
+   * This is useful for SPA applications where you know the user's identity
+   * after authentication. Calls identify() under the hood.
+   *
+   * If called before tracking is enabled, the identity is stored as pending
+   * and applied automatically when enableTracking() is called.
+   *
+   * Note: Both setUser() and identify() enable stage events. The difference is
+   * setUser() can be called before tracking is enabled (identity is queued),
+   * while identify() requires tracking to be enabled first.
+   */
+  setUser(identity) {
+    if (!identity.email && !identity.userId) {
+      console.warn("[Outlit] setUser requires at least email or userId");
+      return;
+    }
+    if (!this.isTrackingEnabled) {
+      this.pendingUser = identity;
+      return;
+    }
+    this.applyUser(identity);
+  }
+  /**
+   * Clear the current user identity.
+   * Call this when the user logs out.
+   */
+  clearUser() {
+    this.currentUser = null;
+    this.pendingUser = null;
+  }
+  /**
+   * Apply user identity and send identify event.
+   */
+  applyUser(identity) {
+    this.currentUser = identity;
+    this.identify({ email: identity.email, userId: identity.userId, traits: identity.traits });
+  }
+  /**
+   * Mark the current user as activated.
+   * This is typically called after a user completes onboarding or a key activation milestone.
+   * Requires the user to be identified (via setUser or identify with userId).
+   */
+  activate(properties) {
+    this.sendStageEvent("activated", properties);
+  }
+  /**
+   * Mark the current user as engaged.
+   * This is typically called when a user reaches a usage milestone.
+   * Can also be computed automatically by the engagement cron.
+   */
+  engaged(properties) {
+    this.sendStageEvent("engaged", properties);
+  }
+  /**
+   * Mark the current user as paid.
+   * This is typically called after a successful payment/subscription.
+   * Can also be triggered by Stripe integration.
+   */
+  paid(properties) {
+    this.sendStageEvent("paid", properties);
+  }
+  /**
+   * Mark the current user as churned.
+   * This is typically called when a subscription is cancelled.
+   * Can also be triggered by Stripe integration.
+   */
+  churned(properties) {
+    this.sendStageEvent("churned", properties);
+  }
+  /**
+   * Internal method to send a stage event.
+   */
+  sendStageEvent(stage, properties) {
+    if (!this.isTrackingEnabled) {
+      console.warn("[Outlit] Tracking not enabled. Call enableTracking() first.");
+      return;
+    }
+    if (!this.currentUser) {
+      console.warn(
+        `[Outlit] Cannot call ${stage}() without setting user identity. Call setUser() or identify() first.`
+      );
+      return;
+    }
+    const event = buildStageEvent({
+      url: window.location.href,
+      referrer: document.referrer,
+      stage,
+      properties
+    });
+    this.enqueue(event);
+  }
   /**
    * Get the current visitor ID.
    * Returns null if tracking is not enabled.
@@ -748,8 +858,8 @@ var Outlit = class {
   // ============================================
   initSessionTracking() {
     this.sessionTracker = initSessionTracking({
-      onEngagement: (event) => {
-        this.enqueue(event);
+      // Only emit engagement events when trackEngagement is enabled (default: true)
+      onEngagement: this.options.trackEngagement !== false ? (event) => this.enqueue(event) : () => {
       },
       idleTimeout: this.options.idleTimeout
     });
@@ -820,7 +930,9 @@ var Outlit = class {
   async sendEvents(events) {
     if (events.length === 0) return;
     if (!this.visitorId) return;
-    const payload = buildIngestPayload(this.visitorId, "client", events);
+    const userIdentity = this.currentUser ?? void 0;
+    const sessionId = this.sessionTracker?.getSessionId();
+    const payload = buildIngestPayload(this.visitorId, "client", events, userIdentity, sessionId);
     const url = `${this.apiHost}/api/i/v1/${this.publicKey}/events`;
     try {
       if (typeof navigator !== "undefined" && navigator.sendBeacon) {
@@ -860,7 +972,8 @@ function OutlitProvider({
   formFieldDenylist,
   flushInterval,
   autoTrack = true,
-  autoIdentify = true
+  autoIdentify = true,
+  user
 }) {
   const outlitRef = useRef(null);
   const initializedRef = useRef(false);
@@ -892,6 +1005,14 @@ function OutlitProvider({
     autoTrack,
     autoIdentify
   ]);
+  useEffect(() => {
+    if (!outlitRef.current) return;
+    if (user && (user.email || user.userId)) {
+      outlitRef.current.setUser(user);
+    } else {
+      outlitRef.current.clearUser();
+    }
+  }, [user]);
   const enableTracking = useCallback(() => {
     if (outlitRef.current) {
       outlitRef.current.enableTracking();
@@ -940,10 +1061,73 @@ function useOutlit() {
     if (!outlit) return null;
     return outlit.getVisitorId();
   }, [outlit]);
+  const setUser = useCallback2(
+    (identity) => {
+      if (!outlit) {
+        console.warn("[Outlit] Not initialized. Make sure OutlitProvider is mounted.");
+        return;
+      }
+      outlit.setUser(identity);
+    },
+    [outlit]
+  );
+  const clearUser = useCallback2(() => {
+    if (!outlit) {
+      console.warn("[Outlit] Not initialized. Make sure OutlitProvider is mounted.");
+      return;
+    }
+    outlit.clearUser();
+  }, [outlit]);
+  const activate = useCallback2(
+    (properties) => {
+      if (!outlit) {
+        console.warn("[Outlit] Not initialized. Make sure OutlitProvider is mounted.");
+        return;
+      }
+      outlit.activate(properties);
+    },
+    [outlit]
+  );
+  const engaged = useCallback2(
+    (properties) => {
+      if (!outlit) {
+        console.warn("[Outlit] Not initialized. Make sure OutlitProvider is mounted.");
+        return;
+      }
+      outlit.engaged(properties);
+    },
+    [outlit]
+  );
+  const paid = useCallback2(
+    (properties) => {
+      if (!outlit) {
+        console.warn("[Outlit] Not initialized. Make sure OutlitProvider is mounted.");
+        return;
+      }
+      outlit.paid(properties);
+    },
+    [outlit]
+  );
+  const churned = useCallback2(
+    (properties) => {
+      if (!outlit) {
+        console.warn("[Outlit] Not initialized. Make sure OutlitProvider is mounted.");
+        return;
+      }
+      outlit.churned(properties);
+    },
+    [outlit]
+  );
   return {
     track,
     identify,
     getVisitorId,
+    setUser,
+    clearUser,
+    activate,
+    engaged,
+    paid,
+    churned,
     isInitialized,
     isTrackingEnabled,
     enableTracking