@outlit/browser 1.3.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 { h as OutlitOptions, U as UserIdentity, O as Outlit, B as BillingOptions } from '../tracker-OMgVDwlV.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';
 
@@ -13,20 +13,8 @@ interface OutlitContextValue {
     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.
@@ -52,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 {
     /**

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 { h as OutlitOptions, U as UserIdentity, O as Outlit, B as BillingOptions } from '../tracker-OMgVDwlV.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';
 
@@ -13,20 +13,8 @@ interface OutlitContextValue {
     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.
@@ -52,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 {
     /**

package/dist/react/index.js

@@ -1073,48 +1073,78 @@ var OutlitContext = (0, import_react.createContext)({
   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)) {
@@ -1140,7 +1170,7 @@ function OutlitProvider({
     {
       value: {
         outlit: outlitRef.current,
-        isInitialized: initializedRef.current,
+        isInitialized,
         isTrackingEnabled,
         enableTracking,
         disableTracking