@outlit/browser 1.2.0 → 1.4.0

package/dist/react/index.d.mts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { f as OutlitOptions, U as UserIdentity, O as Outlit, B as BillingOptions } from '../tracker-BTkkFb0f.mjs';
+import { U as UserIdentity, h as OutlitOptions, O as Outlit, B as BillingOptions } from '../tracker-OMgVDwlV.mjs';
 import { BrowserTrackOptions, BrowserIdentifyOptions } from '@outlit/core';
 export { BrowserIdentifyOptions, BrowserTrackOptions, CustomerIdentifier, ExplicitJourneyStage, TrackerConfig } from '@outlit/core';
 
@@ -10,22 +10,11 @@ interface OutlitContextValue {
     isInitialized: boolean;
     isTrackingEnabled: boolean;
     enableTracking: () => void;
+    disableTracking: () => void;
 }
 declare const OutlitContext: react.Context<OutlitContextValue>;
-interface OutlitProviderProps extends Omit<OutlitOptions, "trackPageviews"> {
+interface OutlitProviderBaseProps {
     children: ReactNode;
-    /**
-     * Whether to automatically track pageviews.
-     * When true (default), tracks pageviews on route changes.
-     */
-    trackPageviews?: boolean;
-    /**
-     * Whether to start tracking automatically on mount.
-     * Set to false if you need to wait for user consent.
-     * Call enableTracking() (from useOutlit hook) after consent is obtained.
-     * @default true
-     */
-    autoTrack?: boolean;
     /**
      * Current user identity.
      * When provided with email or userId, calls setUser() to identify the user.
@@ -51,46 +40,83 @@ interface OutlitProviderProps extends Omit<OutlitOptions, "trackPageviews"> {
     user?: UserIdentity | null;
 }
 /**
- * Outlit Provider component.
- * Initializes the client and provides it to child components via context.
+ * Props for using a pre-existing Outlit instance.
+ * The provider will use this instance directly without creating a new one.
+ * The caller owns the instance lifecycle — shutdown() will NOT be called on unmount.
  *
  * @example
  * ```tsx
- * // layout.tsx - Auto tracking (default)
+ * import { Outlit } from '@outlit/browser'
  * import { OutlitProvider } from '@outlit/browser/react'
  *
- * export default function RootLayout({ children }) {
+ * const outlit = new Outlit({ publicKey: 'pk_xxx', trackPageviews: false })
+ *
+ * function App() {
+ *   const user = useAuth()
  *   return (
- *     <OutlitProvider publicKey="pk_xxx" trackPageviews>
+ *     <OutlitProvider client={outlit} user={user ? { email: user.email } : null}>
  *       {children}
  *     </OutlitProvider>
  *   )
  * }
  * ```
+ */
+type NeverOutlitOptions = {
+    [K in keyof OutlitOptions]?: never;
+};
+interface OutlitProviderClientProps extends OutlitProviderBaseProps, NeverOutlitOptions {
+    /** An existing Outlit instance to use. Config props are ignored when this is provided. */
+    client: Outlit;
+}
+/**
+ * Props for creating a new Outlit instance internally.
+ * This is the default behavior — the provider creates and owns the instance.
+ */
+interface OutlitProviderConfigProps extends OutlitProviderBaseProps, Omit<OutlitOptions, "trackPageviews"> {
+    client?: never;
+    /**
+     * Whether to automatically track pageviews.
+     * When true (default), tracks pageviews on route changes.
+     */
+    trackPageviews?: boolean;
+    /**
+     * Whether to start tracking automatically on mount.
+     * Set to false if you need to wait for user consent.
+     * Call enableTracking() (from useOutlit hook) after consent is obtained.
+     * @default true
+     */
+    autoTrack?: boolean;
+}
+type OutlitProviderProps = OutlitProviderClientProps | OutlitProviderConfigProps;
+/**
+ * Outlit Provider component.
+ * Initializes the client and provides it to child components via context.
+ *
+ * Can be used in two ways:
+ *
+ * 1. **Config mode** (default): Pass `publicKey` and config options to create a new instance.
+ * 2. **Client mode**: Pass an existing `client` instance for shared imperative + React usage.
  *
  * @example
  * ```tsx
- * // layout.tsx - With consent management
- * import { OutlitProvider } from '@outlit/browser/react'
- *
- * export default function RootLayout({ children }) {
- *   return (
- *     <OutlitProvider publicKey="pk_xxx" autoTrack={false}>
- *       {children}
- *     </OutlitProvider>
- *   )
- * }
+ * // Config mode — provider creates and owns the instance
+ * <OutlitProvider publicKey="pk_xxx" trackPageviews>
+ *   {children}
+ * </OutlitProvider>
+ * ```
  *
- * // ConsentBanner.tsx
- * import { useOutlit } from '@outlit/browser/react'
+ * @example
+ * ```tsx
+ * // Client mode — use an existing instance
+ * const outlit = new Outlit({ publicKey: 'pk_xxx' })
+ * outlit.track('pageview') // imperative usage
  *
- * function ConsentBanner() {
- *   const { enableTracking } = useOutlit()
- *   return <button onClick={enableTracking}>Accept Cookies</button>
- * }
+ * <OutlitProvider client={outlit} user={user}>
+ *   {children}
+ * </OutlitProvider>
  * ```
  */
-declare function OutlitProvider({ children, publicKey, apiHost, trackPageviews, trackForms, formFieldDenylist, flushInterval, autoTrack, autoIdentify, user, }: OutlitProviderProps): react_jsx_runtime.JSX.Element;
+declare function OutlitProvider(props: OutlitProviderProps): react_jsx_runtime.JSX.Element;
 
 interface UseOutlitReturn {
     /**
@@ -147,6 +173,11 @@ interface UseOutlitReturn {
      * Only needed if you initialized with autoTrack: false.
      */
     enableTracking: () => void;
+    /**
+     * Disable tracking and persist the opt-out decision.
+     * Call this when a user revokes consent.
+     */
+    disableTracking: () => void;
 }
 /**
  * Hook to access the Outlit client.

package/dist/react/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { f as OutlitOptions, U as UserIdentity, O as Outlit, B as BillingOptions } from '../tracker-BTkkFb0f.js';
+import { U as UserIdentity, h as OutlitOptions, O as Outlit, B as BillingOptions } from '../tracker-OMgVDwlV.js';
 import { BrowserTrackOptions, BrowserIdentifyOptions } from '@outlit/core';
 export { BrowserIdentifyOptions, BrowserTrackOptions, CustomerIdentifier, ExplicitJourneyStage, TrackerConfig } from '@outlit/core';
 
@@ -10,22 +10,11 @@ interface OutlitContextValue {
     isInitialized: boolean;
     isTrackingEnabled: boolean;
     enableTracking: () => void;
+    disableTracking: () => void;
 }
 declare const OutlitContext: react.Context<OutlitContextValue>;
-interface OutlitProviderProps extends Omit<OutlitOptions, "trackPageviews"> {
+interface OutlitProviderBaseProps {
     children: ReactNode;
-    /**
-     * Whether to automatically track pageviews.
-     * When true (default), tracks pageviews on route changes.
-     */
-    trackPageviews?: boolean;
-    /**
-     * Whether to start tracking automatically on mount.
-     * Set to false if you need to wait for user consent.
-     * Call enableTracking() (from useOutlit hook) after consent is obtained.
-     * @default true
-     */
-    autoTrack?: boolean;
     /**
      * Current user identity.
      * When provided with email or userId, calls setUser() to identify the user.
@@ -51,46 +40,83 @@ interface OutlitProviderProps extends Omit<OutlitOptions, "trackPageviews"> {
     user?: UserIdentity | null;
 }
 /**
- * Outlit Provider component.
- * Initializes the client and provides it to child components via context.
+ * Props for using a pre-existing Outlit instance.
+ * The provider will use this instance directly without creating a new one.
+ * The caller owns the instance lifecycle — shutdown() will NOT be called on unmount.
  *
  * @example
  * ```tsx
- * // layout.tsx - Auto tracking (default)
+ * import { Outlit } from '@outlit/browser'
  * import { OutlitProvider } from '@outlit/browser/react'
  *
- * export default function RootLayout({ children }) {
+ * const outlit = new Outlit({ publicKey: 'pk_xxx', trackPageviews: false })
+ *
+ * function App() {
+ *   const user = useAuth()
  *   return (
- *     <OutlitProvider publicKey="pk_xxx" trackPageviews>
+ *     <OutlitProvider client={outlit} user={user ? { email: user.email } : null}>
  *       {children}
  *     </OutlitProvider>
  *   )
  * }
  * ```
+ */
+type NeverOutlitOptions = {
+    [K in keyof OutlitOptions]?: never;
+};
+interface OutlitProviderClientProps extends OutlitProviderBaseProps, NeverOutlitOptions {
+    /** An existing Outlit instance to use. Config props are ignored when this is provided. */
+    client: Outlit;
+}
+/**
+ * Props for creating a new Outlit instance internally.
+ * This is the default behavior — the provider creates and owns the instance.
+ */
+interface OutlitProviderConfigProps extends OutlitProviderBaseProps, Omit<OutlitOptions, "trackPageviews"> {
+    client?: never;
+    /**
+     * Whether to automatically track pageviews.
+     * When true (default), tracks pageviews on route changes.
+     */
+    trackPageviews?: boolean;
+    /**
+     * Whether to start tracking automatically on mount.
+     * Set to false if you need to wait for user consent.
+     * Call enableTracking() (from useOutlit hook) after consent is obtained.
+     * @default true
+     */
+    autoTrack?: boolean;
+}
+type OutlitProviderProps = OutlitProviderClientProps | OutlitProviderConfigProps;
+/**
+ * Outlit Provider component.
+ * Initializes the client and provides it to child components via context.
+ *
+ * Can be used in two ways:
+ *
+ * 1. **Config mode** (default): Pass `publicKey` and config options to create a new instance.
+ * 2. **Client mode**: Pass an existing `client` instance for shared imperative + React usage.
  *
  * @example
  * ```tsx
- * // layout.tsx - With consent management
- * import { OutlitProvider } from '@outlit/browser/react'
- *
- * export default function RootLayout({ children }) {
- *   return (
- *     <OutlitProvider publicKey="pk_xxx" autoTrack={false}>
- *       {children}
- *     </OutlitProvider>
- *   )
- * }
+ * // Config mode — provider creates and owns the instance
+ * <OutlitProvider publicKey="pk_xxx" trackPageviews>
+ *   {children}
+ * </OutlitProvider>
+ * ```
  *
- * // ConsentBanner.tsx
- * import { useOutlit } from '@outlit/browser/react'
+ * @example
+ * ```tsx
+ * // Client mode — use an existing instance
+ * const outlit = new Outlit({ publicKey: 'pk_xxx' })
+ * outlit.track('pageview') // imperative usage
  *
- * function ConsentBanner() {
- *   const { enableTracking } = useOutlit()
- *   return <button onClick={enableTracking}>Accept Cookies</button>
- * }
+ * <OutlitProvider client={outlit} user={user}>
+ *   {children}
+ * </OutlitProvider>
  * ```
  */
-declare function OutlitProvider({ children, publicKey, apiHost, trackPageviews, trackForms, formFieldDenylist, flushInterval, autoTrack, autoIdentify, user, }: OutlitProviderProps): react_jsx_runtime.JSX.Element;
+declare function OutlitProvider(props: OutlitProviderProps): react_jsx_runtime.JSX.Element;
 
 interface UseOutlitReturn {
     /**
@@ -147,6 +173,11 @@ interface UseOutlitReturn {
      * Only needed if you initialized with autoTrack: false.
      */
     enableTracking: () => void;
+    /**
+     * Disable tracking and persist the opt-out decision.
+     * Call this when a user revokes consent.
+     */
+    disableTracking: () => void;
 }
 /**
  * Hook to access the Outlit client.

package/dist/react/index.js

@@ -625,6 +625,27 @@ function setCookie(name, value, days) {
   }
   document.cookie = cookie;
 }
+var CONSENT_KEY = "outlit_consent";
+function getConsentState() {
+  try {
+    const stored = localStorage.getItem(CONSENT_KEY);
+    if (stored === "1") return true;
+    if (stored === "0") return false;
+  } catch {
+  }
+  const cookieValue = getCookie(CONSENT_KEY);
+  if (cookieValue === "1") return true;
+  if (cookieValue === "0") return false;
+  return null;
+}
+function setConsentState(granted) {
+  const value = granted ? "1" : "0";
+  try {
+    localStorage.setItem(CONSENT_KEY, value);
+  } catch {
+  }
+  setCookie(CONSENT_KEY, value, 365);
+}
 
 // src/tracker.ts
 var MAX_PENDING_STAGE_EVENTS = 10;
@@ -667,7 +688,8 @@ var Outlit = class {
       window.addEventListener("beforeunload", handleExit);
     }
     this.isInitialized = true;
-    if (options.autoTrack !== false) {
+    const consent = getConsentState();
+    if (consent === true || consent === null && options.autoTrack !== false) {
       this.enableTracking();
     }
   }
@@ -700,11 +722,38 @@ var Outlit = class {
       this.initCalendarTracking();
     }
     this.isTrackingEnabled = true;
+    setConsentState(true);
     if (this.pendingUser) {
       this.applyUser(this.pendingUser);
       this.pendingUser = null;
     }
   }
+  /**
+   * Disable tracking. Call this when a user revokes consent.
+   * This will:
+   * - Flush any pending events (captured while user had consent)
+   * - Stop the flush timer, pageview tracking, form tracking, and session tracking
+   * - Persist the opt-out decision so it's remembered across sessions
+   *
+   * The SDK instance remains usable — enableTracking() can be called again to re-enable.
+   */
+  async disableTracking() {
+    if (!this.isTrackingEnabled) {
+      setConsentState(false);
+      return;
+    }
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    stopAutocapture();
+    stopCalendarTracking();
+    stopSessionTracking();
+    await this.flush();
+    this.sessionTracker = null;
+    this.isTrackingEnabled = false;
+    setConsentState(false);
+  }
   /**
    * Check if tracking is currently enabled.
    */
@@ -1020,50 +1069,82 @@ var OutlitContext = (0, import_react.createContext)({
   isInitialized: false,
   isTrackingEnabled: false,
   enableTracking: () => {
+  },
+  disableTracking: () => {
   }
 });
-function OutlitProvider({
-  children,
-  publicKey,
-  apiHost,
-  trackPageviews = true,
-  trackForms = true,
-  formFieldDenylist,
-  flushInterval,
-  autoTrack = true,
-  autoIdentify = true,
-  user
-}) {
+function OutlitProvider(props) {
+  const { children, user } = props;
   const outlitRef = (0, import_react.useRef)(null);
   const initializedRef = (0, import_react.useRef)(false);
+  const isExternalClientRef = (0, import_react.useRef)(false);
+  const [isInitialized, setIsInitialized] = (0, import_react.useState)(false);
   const [isTrackingEnabled, setIsTrackingEnabled] = (0, import_react.useState)(false);
   (0, import_react.useEffect)(() => {
     if (initializedRef.current) return;
-    outlitRef.current = new Outlit({
-      publicKey,
-      apiHost,
-      trackPageviews,
-      trackForms,
-      formFieldDenylist,
-      flushInterval,
-      autoTrack,
-      autoIdentify
-    });
+    if (props.client) {
+      if (process.env.NODE_ENV !== "production") {
+        const configKeys = [
+          "publicKey",
+          "apiHost",
+          "trackPageviews",
+          "trackForms",
+          "formFieldDenylist",
+          "flushInterval",
+          "autoTrack",
+          "autoIdentify",
+          "trackCalendarEmbeds",
+          "trackEngagement",
+          "idleTimeout"
+        ];
+        const conflicting = configKeys.filter(
+          (k) => k in props && props[k] !== void 0
+        );
+        if (conflicting.length > 0) {
+          console.warn(
+            `[Outlit] Both \`client\` and config props (${conflicting.join(", ")}) were provided to OutlitProvider. The \`client\` instance will be used and config props will be ignored.`
+          );
+        }
+      }
+      outlitRef.current = props.client;
+      isExternalClientRef.current = true;
+    } else {
+      const {
+        publicKey,
+        apiHost,
+        trackPageviews = true,
+        trackForms = true,
+        formFieldDenylist,
+        flushInterval,
+        autoTrack = true,
+        autoIdentify = true,
+        trackCalendarEmbeds,
+        trackEngagement,
+        idleTimeout
+      } = props;
+      outlitRef.current = new Outlit({
+        publicKey,
+        apiHost,
+        trackPageviews,
+        trackForms,
+        formFieldDenylist,
+        flushInterval,
+        autoTrack,
+        autoIdentify,
+        trackCalendarEmbeds,
+        trackEngagement,
+        idleTimeout
+      });
+    }
     initializedRef.current = true;
+    setIsInitialized(true);
     setIsTrackingEnabled(outlitRef.current.isEnabled());
     return () => {
-      outlitRef.current?.shutdown();
+      if (!isExternalClientRef.current) {
+        outlitRef.current?.shutdown();
+      }
     };
-  }, [
-    publicKey,
-    apiHost,
-    trackPageviews,
-    trackForms,
-    formFieldDenylist,
-    flushInterval,
-    autoTrack,
-    autoIdentify
-  ]);
+  }, []);
   (0, import_react.useEffect)(() => {
     if (!outlitRef.current) return;
     if (user && (user.email || user.userId)) {
@@ -1078,14 +1159,21 @@ function OutlitProvider({
       setIsTrackingEnabled(true);
     }
   }, []);
+  const disableTracking = (0, import_react.useCallback)(() => {
+    if (outlitRef.current) {
+      outlitRef.current.disableTracking();
+      setIsTrackingEnabled(false);
+    }
+  }, []);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
     OutlitContext.Provider,
     {
       value: {
         outlit: outlitRef.current,
-        isInitialized: initializedRef.current,
+        isInitialized,
         isTrackingEnabled,
-        enableTracking
+        enableTracking,
+        disableTracking
       },
       children
     }
@@ -1095,7 +1183,7 @@ function OutlitProvider({
 // src/react/hooks.ts
 var import_react2 = require("react");
 function useOutlit() {
-  const { outlit, isInitialized, isTrackingEnabled, enableTracking } = (0, import_react2.useContext)(OutlitContext);
+  const { outlit, isInitialized, isTrackingEnabled, enableTracking, disableTracking } = (0, import_react2.useContext)(OutlitContext);
   const track = (0, import_react2.useCallback)(
     (eventName, properties) => {
       if (!outlit) {
@@ -1226,7 +1314,8 @@ function useOutlit() {
     },
     isInitialized,
     isTrackingEnabled,
-    enableTracking
+    enableTracking,
+    disableTracking
   };
 }
 function useTrack() {