@outlit/browser 0.2.2 → 0.4.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { i as init, t as track, a as identify, g as getInstance, O as Outlit, e as enableTracking, b as isTrackingEnabled } from './tracker-DFcTv3EM.mjs';
-export { c as OutlitOptions } from './tracker-DFcTv3EM.mjs';
-export { BrowserIdentifyOptions, BrowserTrackOptions, TrackerConfig, UtmParams } from '@outlit/core';
+import { i as init, t as track, a as identify, g as getInstance, O as Outlit, e as enableTracking, b as isTrackingEnabled, s as setUser, c as clearUser, d as activate, f as engaged, p as paid, h as churned } from './tracker-DK-2gYCi.mjs';
+export { j as OutlitOptions, U as UserIdentity } from './tracker-DK-2gYCi.mjs';
+export { BrowserIdentifyOptions, BrowserTrackOptions, ExplicitJourneyStage, TrackerConfig, UtmParams } from '@outlit/core';
 
 declare const _default: {
     init: typeof init;
@@ -10,6 +10,12 @@ declare const _default: {
     Outlit: typeof Outlit;
     enableTracking: typeof enableTracking;
     isTrackingEnabled: typeof isTrackingEnabled;
+    setUser: typeof setUser;
+    clearUser: typeof clearUser;
+    activate: typeof activate;
+    engaged: typeof engaged;
+    paid: typeof paid;
+    churned: typeof churned;
 };
 
-export { Outlit, _default as default, enableTracking, getInstance, identify, init, isTrackingEnabled, track };
+export { Outlit, activate, churned, clearUser, _default as default, enableTracking, engaged, getInstance, identify, init, isTrackingEnabled, paid, setUser, track };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { i as init, t as track, a as identify, g as getInstance, O as Outlit, e as enableTracking, b as isTrackingEnabled } from './tracker-DFcTv3EM.js';
-export { c as OutlitOptions } from './tracker-DFcTv3EM.js';
-export { BrowserIdentifyOptions, BrowserTrackOptions, TrackerConfig, UtmParams } from '@outlit/core';
+import { i as init, t as track, a as identify, g as getInstance, O as Outlit, e as enableTracking, b as isTrackingEnabled, s as setUser, c as clearUser, d as activate, f as engaged, p as paid, h as churned } from './tracker-DK-2gYCi.js';
+export { j as OutlitOptions, U as UserIdentity } from './tracker-DK-2gYCi.js';
+export { BrowserIdentifyOptions, BrowserTrackOptions, ExplicitJourneyStage, TrackerConfig, UtmParams } from '@outlit/core';
 
 declare const _default: {
     init: typeof init;
@@ -10,6 +10,12 @@ declare const _default: {
     Outlit: typeof Outlit;
     enableTracking: typeof enableTracking;
     isTrackingEnabled: typeof isTrackingEnabled;
+    setUser: typeof setUser;
+    clearUser: typeof clearUser;
+    activate: typeof activate;
+    engaged: typeof engaged;
+    paid: typeof paid;
+    churned: typeof churned;
 };
 
-export { Outlit, _default as default, enableTracking, getInstance, identify, init, isTrackingEnabled, track };
+export { Outlit, activate, churned, clearUser, _default as default, enableTracking, engaged, getInstance, identify, init, isTrackingEnabled, paid, setUser, track };

package/dist/index.js

@@ -21,12 +21,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   Outlit: () => Outlit,
+  activate: () => activate,
+  churned: () => churned,
+  clearUser: () => clearUser,
   default: () => src_default,
   enableTracking: () => enableTracking,
+  engaged: () => engaged,
   getInstance: () => getInstance,
   identify: () => identify,
   init: () => init,
   isTrackingEnabled: () => isTrackingEnabled,
+  paid: () => paid,
+  setUser: () => setUser,
   track: () => track
 });
 module.exports = __toCommonJS(src_exports);
@@ -251,6 +257,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 {
@@ -295,7 +302,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 = (0, import_core2.buildEngagementEvent)({
         url: this.state.currentUrl,
         referrer: document.referrer,
@@ -481,6 +489,7 @@ var SessionTracker = class {
       this.checkSessionExpiry();
       this.state.lastActiveTime = Date.now();
       this.state.hasEmittedEngagement = false;
+      this.updateSessionActivity();
     }
   }
   /**
@@ -636,6 +645,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 ?? import_core3.DEFAULT_API_HOST;
@@ -681,9 +693,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();
     }
@@ -694,6 +704,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.
@@ -720,12 +734,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 = (0, import_core3.buildIdentifyEvent)({
       url: window.location.href,
       referrer: document.referrer,
@@ -735,6 +758,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 = (0, import_core3.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.
@@ -770,8 +885,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
     });
@@ -842,7 +957,9 @@ var Outlit = class {
   async sendEvents(events) {
     if (events.length === 0) return;
     if (!this.visitorId) return;
-    const payload = (0, import_core3.buildIngestPayload)(this.visitorId, "client", events);
+    const userIdentity = this.currentUser ?? void 0;
+    const sessionId = this.sessionTracker?.getSessionId();
+    const payload = (0, import_core3.buildIngestPayload)(this.visitorId, "client", events, userIdentity, sessionId);
     const url = `${this.apiHost}/api/i/v1/${this.publicKey}/events`;
     try {
       if (typeof navigator !== "undefined" && navigator.sendBeacon) {
@@ -890,6 +1007,24 @@ function enableTracking() {
 function isTrackingEnabled() {
   return getInstance().isEnabled();
 }
+function setUser(identity) {
+  getInstance().setUser(identity);
+}
+function clearUser() {
+  getInstance().clearUser();
+}
+function activate(properties) {
+  getInstance().activate(properties);
+}
+function engaged(properties) {
+  getInstance().engaged(properties);
+}
+function paid(properties) {
+  getInstance().paid(properties);
+}
+function churned(properties) {
+  getInstance().churned(properties);
+}
 
 // src/index.ts
 var src_default = {
@@ -899,16 +1034,28 @@ var src_default = {
   getInstance,
   Outlit,
   enableTracking,
-  isTrackingEnabled
+  isTrackingEnabled,
+  setUser,
+  clearUser,
+  activate,
+  engaged,
+  paid,
+  churned
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Outlit,
+  activate,
+  churned,
+  clearUser,
   enableTracking,
+  engaged,
   getInstance,
   identify,
   init,
   isTrackingEnabled,
+  paid,
+  setUser,
   track
 });
 //# sourceMappingURL=index.js.map