@outlit/browser 0.2.1 → 0.3.0

package/dist/react/index.d.mts

@@ -1,9 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { c as OutlitOptions, O as Outlit } from '../tracker-DFcTv3EM.mjs';
+import { j as OutlitOptions, U as UserIdentity, O as Outlit } from '../tracker-DK-2gYCi.mjs';
 import { BrowserTrackOptions, BrowserIdentifyOptions } from '@outlit/core';
-export { BrowserIdentifyOptions, BrowserTrackOptions, TrackerConfig } from '@outlit/core';
+export { BrowserIdentifyOptions, BrowserTrackOptions, ExplicitJourneyStage, TrackerConfig } from '@outlit/core';
 
 interface OutlitContextValue {
     outlit: Outlit | null;
@@ -26,6 +26,29 @@ interface OutlitProviderProps extends Omit<OutlitOptions, "trackPageviews"> {
      * @default true
      */
     autoTrack?: boolean;
+    /**
+     * Current user identity.
+     * When provided with email or userId, calls setUser() to identify the user.
+     * When null, undefined, or missing identity fields, calls clearUser().
+     *
+     * This is the recommended way to handle user identity in server-rendered apps:
+     * pass the user from your auth system as a prop.
+     *
+     * @example
+     * ```tsx
+     * // Server component (layout.tsx)
+     * const session = await auth()
+     * return (
+     *   <OutlitProvider
+     *     publicKey="pk_xxx"
+     *     user={session?.user ? { email: session.user.email, userId: session.user.id } : null}
+     *   >
+     *     {children}
+     *   </OutlitProvider>
+     * )
+     * ```
+     */
+    user?: UserIdentity | null;
 }
 /**
  * Outlit Provider component.
@@ -67,7 +90,7 @@ interface OutlitProviderProps extends Omit<OutlitOptions, "trackPageviews"> {
  * }
  * ```
  */
-declare function OutlitProvider({ children, publicKey, apiHost, trackPageviews, trackForms, formFieldDenylist, flushInterval, autoTrack, autoIdentify, }: OutlitProviderProps): react_jsx_runtime.JSX.Element;
+declare function OutlitProvider({ children, publicKey, apiHost, trackPageviews, trackForms, formFieldDenylist, flushInterval, autoTrack, autoIdentify, user, }: OutlitProviderProps): react_jsx_runtime.JSX.Element;
 
 interface UseOutlitReturn {
     /**
@@ -84,6 +107,35 @@ interface UseOutlitReturn {
      * Returns null if tracking is not enabled.
      */
     getVisitorId: () => string | null;
+    /**
+     * Set the current user identity.
+     * Use this for persistent identity after login.
+     */
+    setUser: (identity: UserIdentity) => void;
+    /**
+     * Clear the current user identity (on logout).
+     */
+    clearUser: () => void;
+    /**
+     * Mark the current user as activated.
+     * Call after a user completes onboarding or activation milestone.
+     */
+    activate: (properties?: Record<string, string | number | boolean | null>) => void;
+    /**
+     * Mark the current user as engaged.
+     * Call when user reaches a usage milestone.
+     */
+    engaged: (properties?: Record<string, string | number | boolean | null>) => void;
+    /**
+     * Mark the current user as paid.
+     * Call after successful payment/subscription.
+     */
+    paid: (properties?: Record<string, string | number | boolean | null>) => void;
+    /**
+     * Mark the current user as churned.
+     * Call when subscription is cancelled.
+     */
+    churned: (properties?: Record<string, string | number | boolean | null>) => void;
     /**
      * Whether Outlit is initialized.
      */
@@ -167,4 +219,4 @@ declare function useTrack(): (eventName: string, properties?: BrowserTrackOption
  */
 declare function useIdentify(): (options: BrowserIdentifyOptions) => void;
 
-export { OutlitContext, type OutlitContextValue, OutlitProvider, type OutlitProviderProps, type UseOutlitReturn, useIdentify, useOutlit, useTrack };
+export { OutlitContext, type OutlitContextValue, OutlitProvider, type OutlitProviderProps, type UseOutlitReturn, UserIdentity, useIdentify, useOutlit, useTrack };

package/dist/react/index.d.ts

@@ -1,9 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { c as OutlitOptions, O as Outlit } from '../tracker-DFcTv3EM.js';
+import { j as OutlitOptions, U as UserIdentity, O as Outlit } from '../tracker-DK-2gYCi.js';
 import { BrowserTrackOptions, BrowserIdentifyOptions } from '@outlit/core';
-export { BrowserIdentifyOptions, BrowserTrackOptions, TrackerConfig } from '@outlit/core';
+export { BrowserIdentifyOptions, BrowserTrackOptions, ExplicitJourneyStage, TrackerConfig } from '@outlit/core';
 
 interface OutlitContextValue {
     outlit: Outlit | null;
@@ -26,6 +26,29 @@ interface OutlitProviderProps extends Omit<OutlitOptions, "trackPageviews"> {
      * @default true
      */
     autoTrack?: boolean;
+    /**
+     * Current user identity.
+     * When provided with email or userId, calls setUser() to identify the user.
+     * When null, undefined, or missing identity fields, calls clearUser().
+     *
+     * This is the recommended way to handle user identity in server-rendered apps:
+     * pass the user from your auth system as a prop.
+     *
+     * @example
+     * ```tsx
+     * // Server component (layout.tsx)
+     * const session = await auth()
+     * return (
+     *   <OutlitProvider
+     *     publicKey="pk_xxx"
+     *     user={session?.user ? { email: session.user.email, userId: session.user.id } : null}
+     *   >
+     *     {children}
+     *   </OutlitProvider>
+     * )
+     * ```
+     */
+    user?: UserIdentity | null;
 }
 /**
  * Outlit Provider component.
@@ -67,7 +90,7 @@ interface OutlitProviderProps extends Omit<OutlitOptions, "trackPageviews"> {
  * }
  * ```
  */
-declare function OutlitProvider({ children, publicKey, apiHost, trackPageviews, trackForms, formFieldDenylist, flushInterval, autoTrack, autoIdentify, }: OutlitProviderProps): react_jsx_runtime.JSX.Element;
+declare function OutlitProvider({ children, publicKey, apiHost, trackPageviews, trackForms, formFieldDenylist, flushInterval, autoTrack, autoIdentify, user, }: OutlitProviderProps): react_jsx_runtime.JSX.Element;
 
 interface UseOutlitReturn {
     /**
@@ -84,6 +107,35 @@ interface UseOutlitReturn {
      * Returns null if tracking is not enabled.
      */
     getVisitorId: () => string | null;
+    /**
+     * Set the current user identity.
+     * Use this for persistent identity after login.
+     */
+    setUser: (identity: UserIdentity) => void;
+    /**
+     * Clear the current user identity (on logout).
+     */
+    clearUser: () => void;
+    /**
+     * Mark the current user as activated.
+     * Call after a user completes onboarding or activation milestone.
+     */
+    activate: (properties?: Record<string, string | number | boolean | null>) => void;
+    /**
+     * Mark the current user as engaged.
+     * Call when user reaches a usage milestone.
+     */
+    engaged: (properties?: Record<string, string | number | boolean | null>) => void;
+    /**
+     * Mark the current user as paid.
+     * Call after successful payment/subscription.
+     */
+    paid: (properties?: Record<string, string | number | boolean | null>) => void;
+    /**
+     * Mark the current user as churned.
+     * Call when subscription is cancelled.
+     */
+    churned: (properties?: Record<string, string | number | boolean | null>) => void;
     /**
      * Whether Outlit is initialized.
      */
@@ -167,4 +219,4 @@ declare function useTrack(): (eventName: string, properties?: BrowserTrackOption
  */
 declare function useIdentify(): (options: BrowserIdentifyOptions) => void;
 
-export { OutlitContext, type OutlitContextValue, OutlitProvider, type OutlitProviderProps, type UseOutlitReturn, useIdentify, useOutlit, useTrack };
+export { OutlitContext, type OutlitContextValue, OutlitProvider, type OutlitProviderProps, type UseOutlitReturn, UserIdentity, useIdentify, useOutlit, useTrack };

package/dist/react/index.js

@@ -251,6 +251,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 +296,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,
@@ -636,6 +638,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;
@@ -694,6 +699,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 +729,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 +753,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.
@@ -842,7 +952,8 @@ 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 payload = (0, import_core3.buildIngestPayload)(this.visitorId, "client", events, userIdentity);
     const url = `${this.apiHost}/api/i/v1/${this.publicKey}/events`;
     try {
       if (typeof navigator !== "undefined" && navigator.sendBeacon) {
@@ -882,7 +993,8 @@ function OutlitProvider({
   formFieldDenylist,
   flushInterval,
   autoTrack = true,
-  autoIdentify = true
+  autoIdentify = true,
+  user
 }) {
   const outlitRef = (0, import_react.useRef)(null);
   const initializedRef = (0, import_react.useRef)(false);
@@ -914,6 +1026,14 @@ function OutlitProvider({
     autoTrack,
     autoIdentify
   ]);
+  (0, import_react.useEffect)(() => {
+    if (!outlitRef.current) return;
+    if (user && (user.email || user.userId)) {
+      outlitRef.current.setUser(user);
+    } else {
+      outlitRef.current.clearUser();
+    }
+  }, [user]);
   const enableTracking = (0, import_react.useCallback)(() => {
     if (outlitRef.current) {
       outlitRef.current.enableTracking();
@@ -962,10 +1082,73 @@ function useOutlit() {
     if (!outlit) return null;
     return outlit.getVisitorId();
   }, [outlit]);
+  const setUser = (0, import_react2.useCallback)(
+    (identity) => {
+      if (!outlit) {
+        console.warn("[Outlit] Not initialized. Make sure OutlitProvider is mounted.");
+        return;
+      }
+      outlit.setUser(identity);
+    },
+    [outlit]
+  );
+  const clearUser = (0, import_react2.useCallback)(() => {
+    if (!outlit) {
+      console.warn("[Outlit] Not initialized. Make sure OutlitProvider is mounted.");
+      return;
+    }
+    outlit.clearUser();
+  }, [outlit]);
+  const activate = (0, import_react2.useCallback)(
+    (properties) => {
+      if (!outlit) {
+        console.warn("[Outlit] Not initialized. Make sure OutlitProvider is mounted.");
+        return;
+      }
+      outlit.activate(properties);
+    },
+    [outlit]
+  );
+  const engaged = (0, import_react2.useCallback)(
+    (properties) => {
+      if (!outlit) {
+        console.warn("[Outlit] Not initialized. Make sure OutlitProvider is mounted.");
+        return;
+      }
+      outlit.engaged(properties);
+    },
+    [outlit]
+  );
+  const paid = (0, import_react2.useCallback)(
+    (properties) => {
+      if (!outlit) {
+        console.warn("[Outlit] Not initialized. Make sure OutlitProvider is mounted.");
+        return;
+      }
+      outlit.paid(properties);
+    },
+    [outlit]
+  );
+  const churned = (0, import_react2.useCallback)(
+    (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