@stacksee/analytics 0.4.3 → 0.4.4

package/dist/client-CyvENC-f.js

@@ -1,577 +0,0 @@
-var c = Object.defineProperty;
-var u = (t, e, i) => e in t ? c(t, e, { enumerable: !0, configurable: !0, writable: !0, value: i }) : t[e] = i;
-var s = (t, e, i) => u(t, typeof e != "symbol" ? e + "" : e, i);
-import { i as h } from "./environment-Bnc8FqHv.js";
-class p {
-  /**
-   * Creates a new BrowserAnalytics instance for client-side event tracking.
-   * 
-   * Automatically generates a session ID and sets up the analytics context.
-   * The instance will be ready to track events once initialized.
-   * 
-   * @param config Analytics configuration including providers and default context
-   * @param config.providers Array of analytics provider instances (e.g., PostHogClientProvider)
-   * @param config.defaultContext Optional default context to include with all events
-   * 
-   * @example
-   * ```typescript
-   * import { BrowserAnalytics } from '@stacksee/analytics/client';
-   * import { PostHogClientProvider } from '@stacksee/analytics/providers/posthog';
-   * 
-   * const analytics = new BrowserAnalytics({
-   *   providers: [
-   *     new PostHogClientProvider({
-   *       apiKey: 'your-posthog-api-key',
-   *       host: 'https://app.posthog.com'
-   *     })
-   *   ],
-   *   defaultContext: {
-   *     app: { version: '1.0.0' }
-   *   }
-   * });
-   * 
-   * await analytics.initialize();
-   * ```
-   */
-  constructor(e) {
-    s(this, "providers", []);
-    s(this, "context", {});
-    s(this, "userId");
-    s(this, "sessionId");
-    s(this, "initialized", !1);
-    s(this, "initializePromise");
-    this.providers = e.providers, e.defaultContext && (this.context = { ...e.defaultContext }), this.sessionId = this.generateSessionId();
-  }
-  /**
-   * Initializes all analytics providers and sets up browser context.
-   * 
-   * This method must be called before tracking events. It initializes all configured
-   * providers and automatically captures browser context including page information,
-   * device type, OS, and browser details.
-   * 
-   * The method is safe to call multiple times and will not re-initialize if already done.
-   * If called while initialization is in progress, it returns the existing promise.
-   * 
-   * @returns Promise that resolves when initialization is complete
-   * 
-   * @example
-   * ```typescript
-   * const analytics = new BrowserAnalytics({ providers: [] });
-   * 
-   * // Initialize before tracking events
-   * await analytics.initialize();
-   * 
-   * // Now ready to track events
-   * analytics.track('page_viewed', { page: '/dashboard' });
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // Safe to call multiple times
-   * await analytics.initialize(); // First call does the work
-   * await analytics.initialize(); // Subsequent calls return immediately
-   * ```
-   */
-  async initialize() {
-    if (h() && !this.initialized)
-      return this.initializePromise ? this.initializePromise : (this.initializePromise = this._doInitialize(), this.initializePromise);
-  }
-  async _doInitialize() {
-    const e = this.providers.map(
-      (i) => i.initialize()
-    );
-    await Promise.all(e), this.initialized = !0, this.updateContext({
-      page: {
-        path: window.location.pathname,
-        title: document.title,
-        referrer: document.referrer
-      },
-      device: {
-        type: this.getDeviceType(),
-        os: this.getOS(),
-        browser: this.getBrowser()
-      }
-    });
-  }
-  async ensureInitialized() {
-    !this.initialized && !this.initializePromise ? await this.initialize() : this.initializePromise && await this.initializePromise;
-  }
-  /**
-   * Identifies a user with optional traits.
-   * 
-   * Associates subsequent events with the specified user ID and optionally
-   * sets user properties. This method should be called when a user logs in
-   * or when you want to associate events with a known user.
-   * 
-   * The method automatically ensures initialization but doesn't block execution
-   * if initialization is still in progress.
-   * 
-   * @param userId Unique identifier for the user (e.g., database ID, email)
-   * @param traits Optional user properties and characteristics
-   * 
-   * @example
-   * ```typescript
-   * // Basic user identification
-   * analytics.identify('user-123');
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // Identify with user traits
-   * analytics.identify('user-123', {
-   *   email: 'john@example.com',
-   *   name: 'John Doe',
-   *   plan: 'pro',
-   *   signupDate: '2024-01-15',
-   *   preferences: {
-   *     newsletter: true,
-   *     notifications: false
-   *   }
-   * });
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // In a login handler
-   * async function handleLogin(email: string, password: string) {
-   *   const user = await login(email, password);
-   *   
-   *   analytics.identify(user.id, {
-   *     email: user.email,
-   *     name: user.name,
-   *     lastLogin: new Date().toISOString()
-   *   });
-   * }
-   * ```
-   */
-  identify(e, i) {
-    this.userId = e, this.ensureInitialized().catch((r) => {
-      console.error("[Analytics] Failed to initialize during identify:", r);
-    });
-    for (const r of this.providers)
-      r.identify(e, i);
-  }
-  /**
-   * Tracks a custom event with properties.
-   * 
-   * This is the main method for tracking user interactions and business events.
-   * The method ensures initialization before tracking and sends the event to all
-   * configured providers. Events are enriched with context information like
-   * timestamp, user ID, session ID, and browser context.
-   * 
-   * If providers are configured, the method waits for all providers to complete
-   * tracking. Failed providers don't prevent others from succeeding.
-   * 
-   * @param eventName Name of the event to track (must match your event definitions)
-   * @param properties Event-specific properties and data
-   * @returns Promise that resolves when tracking is complete for all providers
-   * 
-   * @example
-   * ```typescript
-   * // Track a simple event
-   * await analytics.track('button_clicked', {
-   *   buttonId: 'signup-cta',
-   *   page: '/landing'
-   * });
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // Track a purchase event
-   * await analytics.track('purchase_completed', {
-   *   orderId: 'order-123',
-   *   amount: 99.99,
-   *   currency: 'USD',
-   *   items: [
-   *     { id: 'item-1', name: 'Product A', price: 49.99 },
-   *     { id: 'item-2', name: 'Product B', price: 49.99 }
-   *   ],
-   *   paymentMethod: 'credit_card'
-   * });
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // Fire-and-forget for non-critical events (client-side typical usage)
-   * analytics.track('feature_viewed', { feature: 'dashboard' });
-   * // Don't await - let it track in the background
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // Error handling
-   * try {
-   *   await analytics.track('critical_event', { data: 'important' });
-   * } catch (error) {
-   *   // Individual provider failures are handled internally
-   *   // This catch would only trigger for initialization failures
-   *   console.error('Failed to track event:', error);
-   * }
-   * ```
-   */
-  async track(e, i) {
-    await this.ensureInitialized();
-    const r = {
-      action: e,
-      category: this.getCategoryFromEventName(e),
-      properties: i,
-      timestamp: Date.now(),
-      userId: this.userId,
-      sessionId: this.sessionId
-    }, o = this.providers.map(async (d) => {
-      try {
-        await d.track(r, this.context);
-      } catch (l) {
-        console.error(
-          `[Analytics] Provider ${d.name} failed to track event:`,
-          l
-        );
-      }
-    });
-    await Promise.all(o);
-  }
-  /**
-   * Tracks a page view event.
-   * 
-   * Automatically captures current page information (path, title, referrer) and
-   * updates the analytics context. This method should be called when users
-   * navigate to a new page or view.
-   * 
-   * The method automatically ensures initialization but doesn't block execution
-   * if initialization is still in progress.
-   * 
-   * @param properties Optional properties to include with the page view
-   * 
-   * @example
-   * ```typescript
-   * // Basic page view tracking
-   * analytics.pageView();
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // Page view with additional properties
-   * analytics.pageView({
-   *   category: 'product',
-   *   productId: 'prod-123',
-   *   loadTime: 1200,
-   *   source: 'organic_search'
-   * });
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // In a SvelteKit app with automatic navigation tracking
-   * import { afterNavigate } from '$app/navigation';
-   * 
-   * afterNavigate(() => {
-   *   analytics.pageView({
-   *     timestamp: Date.now(),
-   *     userAgent: navigator.userAgent
-   *   });
-   * });
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // In a React app with React Router
-   * import { useEffect } from 'react';
-   * import { useLocation } from 'react-router-dom';
-   * 
-   * function usePageTracking() {
-   *   const location = useLocation();
-   *   
-   *   useEffect(() => {
-   *     analytics.pageView({
-   *       path: location.pathname,
-   *       search: location.search
-   *     });
-   *   }, [location]);
-   * }
-   * ```
-   */
-  pageView(e) {
-    this.ensureInitialized().catch((i) => {
-      console.error("[Analytics] Failed to initialize during pageView:", i);
-    }), this.updateContext({
-      page: {
-        path: window.location.pathname,
-        title: document.title,
-        referrer: document.referrer
-      }
-    });
-    for (const i of this.providers)
-      i.pageView(e, this.context);
-  }
-  /**
-   * Tracks when a user leaves a page.
-   * 
-   * This method should be called before navigation to track user engagement
-   * and session duration. It's useful for understanding how long users spend
-   * on different pages and their navigation patterns.
-   * 
-   * Note: Not all analytics providers support page leave events. The method
-   * will only call providers that implement the pageLeave method.
-   * 
-   * @param properties Optional properties to include with the page leave event
-   * 
-   * @example
-   * ```typescript
-   * // Basic page leave tracking
-   * analytics.pageLeave();
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // Page leave with engagement metrics
-   * analytics.pageLeave({
-   *   timeOnPage: 45000, // 45 seconds
-   *   scrollDepth: 80, // percentage
-   *   interactions: 3, // number of clicks/interactions
-   *   exitIntent: true // detected exit intent
-   * });
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // In a SvelteKit app with automatic navigation tracking
-   * import { beforeNavigate } from '$app/navigation';
-   * 
-   * let pageStartTime = Date.now();
-   * 
-   * beforeNavigate(() => {
-   *   analytics.pageLeave({
-   *     duration: Date.now() - pageStartTime,
-   *     exitType: 'navigation'
-   *   });
-   * });
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // Track page leave on browser unload
-   * window.addEventListener('beforeunload', () => {
-   *   analytics.pageLeave({
-   *     exitType: 'browser_close',
-   *     sessionDuration: Date.now() - sessionStartTime
-   *   });
-   * });
-   * ```
-   */
-  pageLeave(e) {
-    this.ensureInitialized().catch((i) => {
-      console.error("[Analytics] Failed to initialize during pageLeave:", i);
-    });
-    for (const i of this.providers)
-      i.pageLeave && i.pageLeave(e, this.context);
-  }
-  /**
-   * Resets the analytics state, clearing user ID and generating a new session.
-   * 
-   * This method should be called when a user logs out or when you want to
-   * start tracking a new user session. It clears the current user ID,
-   * generates a new session ID, and calls reset on all providers.
-   * 
-   * Use this method to ensure user privacy and accurate session tracking
-   * when users switch accounts or log out.
-   * 
-   * @example
-   * ```typescript
-   * // Basic reset on logout
-   * analytics.reset();
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // In a logout handler
-   * async function handleLogout() {
-   *   // Track logout event before resetting
-   *   await analytics.track('user_logged_out', {
-   *     sessionDuration: Date.now() - sessionStartTime
-   *   });
-   *   
-   *   // Reset analytics state
-   *   analytics.reset();
-   *   
-   *   // Clear user data and redirect
-   *   clearUserData();
-   *   window.location.href = '/login';
-   * }
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // Account switching scenario
-   * async function switchAccount(newUserId: string) {
-   *   // Reset to clear previous user
-   *   analytics.reset();
-   *   
-   *   // Identify the new user
-   *   analytics.identify(newUserId);
-   *   
-   *   // Track account switch
-   *   analytics.track('account_switched', {
-   *     newUserId,
-   *     timestamp: Date.now()
-   *   });
-   * }
-   * ```
-   */
-  reset() {
-    this.userId = void 0, this.sessionId = this.generateSessionId();
-    for (const e of this.providers)
-      e.reset();
-  }
-  /**
-   * Updates the analytics context with new information.
-   * 
-   * The context is included with all tracked events and provides additional
-   * metadata about the user's environment, current page, device, and other
-   * relevant information. This method merges new context with existing context.
-   * 
-   * Context typically includes page information, device details, UTM parameters,
-   * and custom application context.
-   * 
-   * @param context Partial context to merge with existing context
-   * @param context.page Page-related context (path, title, referrer)
-   * @param context.device Device-related context (type, OS, browser)
-   * @param context.utm UTM campaign tracking parameters
-   * @param context.app Application-specific context
-   * 
-   * @example
-   * ```typescript
-   * // Update page context
-   * analytics.updateContext({
-   *   page: {
-   *     path: '/dashboard',
-   *     title: 'User Dashboard',
-   *     referrer: 'https://google.com'
-   *   }
-   * });
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // Add UTM parameters from URL
-   * const urlParams = new URLSearchParams(window.location.search);
-   * analytics.updateContext({
-   *   utm: {
-   *     source: urlParams.get('utm_source') || undefined,
-   *     medium: urlParams.get('utm_medium') || undefined,
-   *     campaign: urlParams.get('utm_campaign') || undefined,
-   *     term: urlParams.get('utm_term') || undefined,
-   *     content: urlParams.get('utm_content') || undefined
-   *   }
-   * });
-   * ```
-   * 
-   * @example
-   * ```typescript
-   * // Update application context
-   * analytics.updateContext({
-   *   app: {
-   *     version: '2.1.0',
-   *     feature: 'beta-dashboard',
-   *     theme: 'dark'
-   *   },
-   *   device: {
-   *     screenWidth: window.innerWidth,
-   *     screenHeight: window.innerHeight,
-   *     timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
-   *   }
-   * });
-   * ```
-   */
-  updateContext(e) {
-    var i, r, o;
-    this.context = {
-      ...this.context,
-      ...e,
-      page: e.page ? {
-        path: e.page.path || ((i = this.context.page) == null ? void 0 : i.path) || window.location.pathname,
-        title: e.page.title || ((r = this.context.page) == null ? void 0 : r.title),
-        referrer: e.page.referrer || ((o = this.context.page) == null ? void 0 : o.referrer)
-      } : this.context.page,
-      device: {
-        ...this.context.device,
-        ...e.device
-      },
-      utm: {
-        ...this.context.utm,
-        ...e.utm
-      }
-    };
-  }
-  getCategoryFromEventName(e) {
-    const i = e.split("_");
-    return i.length > 1 && i[0] ? i[0] : "engagement";
-  }
-  generateSessionId() {
-    return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
-  }
-  getDeviceType() {
-    const e = navigator.userAgent;
-    return /tablet|ipad|playbook|silk/i.test(e) ? "tablet" : /mobile|iphone|ipod|android|blackberry|opera|mini|windows\sce|palm|smartphone|iemobile/i.test(
-      e
-    ) ? "mobile" : "desktop";
-  }
-  getOS() {
-    const e = navigator.userAgent;
-    return e.indexOf("Win") !== -1 ? "Windows" : e.indexOf("Mac") !== -1 ? "macOS" : e.indexOf("Linux") !== -1 ? "Linux" : e.indexOf("Android") !== -1 ? "Android" : e.indexOf("iOS") !== -1 ? "iOS" : "Unknown";
-  }
-  getBrowser() {
-    const e = navigator.userAgent;
-    return e.indexOf("Chrome") !== -1 ? "Chrome" : e.indexOf("Safari") !== -1 ? "Safari" : e.indexOf("Firefox") !== -1 ? "Firefox" : e.indexOf("Edge") !== -1 ? "Edge" : "Unknown";
-  }
-}
-let n = null;
-function m(t) {
-  if (n)
-    return console.warn("[Analytics] Already initialized"), n;
-  const e = {
-    providers: t.providers || [],
-    debug: t.debug,
-    enabled: t.enabled
-  };
-  return n = new p(
-    e
-  ), n.initialize().catch((i) => {
-    console.error("[Analytics] Failed to initialize:", i);
-  }), n;
-}
-function a() {
-  if (!n)
-    throw new Error(
-      "[Analytics] Not initialized. Call createAnalytics() first."
-    );
-  return n;
-}
-function v(t, e) {
-  return a().track(t, e);
-}
-function y(t, e) {
-  a().identify(t, e);
-}
-function w(t) {
-  a().pageView(t);
-}
-function z(t) {
-  a().pageLeave(t);
-}
-function x() {
-  a().reset();
-}
-function A() {
-  n = null;
-}
-export {
-  p as B,
-  z as a,
-  A as b,
-  m as c,
-  a as g,
-  y as i,
-  w as p,
-  x as r,
-  v as t
-};

package/dist/client-MwIAm9fk.js

@@ -1,96 +0,0 @@
-var d = Object.defineProperty;
-var g = (r, s, i) => s in r ? d(r, s, { enumerable: !0, configurable: !0, writable: !0, value: i }) : r[s] = i;
-var t = (r, s, i) => g(r, typeof s != "symbol" ? s + "" : s, i);
-import { i as h } from "./environment-Bnc8FqHv.js";
-class o {
-  constructor(s) {
-    t(this, "debug", !1);
-    t(this, "enabled", !0);
-    (s == null ? void 0 : s.debug) !== void 0 && (this.debug = s.debug), (s == null ? void 0 : s.enabled) !== void 0 && (this.enabled = s.enabled);
-  }
-  log(s, i) {
-    this.debug && console.log(`[${this.name}] ${s}`, i);
-  }
-  isEnabled() {
-    return this.enabled;
-  }
-}
-class n extends o {
-  constructor(i) {
-    super({ debug: i.debug, enabled: i.enabled });
-    t(this, "name", "PostHog-Client");
-    t(this, "posthog");
-    t(this, "initialized", !1);
-    t(this, "config");
-    this.config = i;
-  }
-  async initialize() {
-    if (this.isEnabled() && !this.initialized) {
-      if (!h()) {
-        this.log("Skipping initialization - not in browser environment");
-        return;
-      }
-      if (!this.config.token || typeof this.config.token != "string")
-        throw new Error("PostHog requires a token");
-      try {
-        const { default: i } = await import("posthog-js"), { token: e, debug: a, ...l } = this.config;
-        i.init(e, {
-          ...l,
-          debug: a ?? this.debug
-        }), this.posthog = i, this.initialized = !0, this.log("Initialized successfully", this.config);
-      } catch (i) {
-        throw console.error("[PostHog-Client] Failed to initialize:", i), i;
-      }
-    }
-  }
-  identify(i, e) {
-    !this.isEnabled() || !this.initialized || !this.posthog || (this.posthog.identify(i, e), this.log("Identified user", { userId: i, traits: e }));
-  }
-  track(i, e) {
-    if (!this.isEnabled() || !this.initialized || !this.posthog) return;
-    const a = {
-      ...i.properties,
-      category: i.category,
-      timestamp: i.timestamp || Date.now(),
-      ...i.userId && { userId: i.userId },
-      ...i.sessionId && { sessionId: i.sessionId },
-      ...(e == null ? void 0 : e.page) && { $current_url: e.page.path },
-      ...(e == null ? void 0 : e.device) && { device: e.device },
-      ...(e == null ? void 0 : e.utm) && { utm: e.utm }
-    };
-    this.posthog.capture(i.action, a), this.log("Tracked event", { event: i, context: e });
-  }
-  pageView(i, e) {
-    if (!this.isEnabled() || !this.initialized || !this.posthog || !h())
-      return;
-    const a = {
-      ...i,
-      ...(e == null ? void 0 : e.page) && {
-        path: e.page.path,
-        title: e.page.title,
-        referrer: e.page.referrer
-      }
-    };
-    this.posthog.capture("$pageview", a), this.log("Tracked page view", { properties: i, context: e });
-  }
-  pageLeave(i, e) {
-    if (!this.isEnabled() || !this.initialized || !this.posthog || !h())
-      return;
-    const a = {
-      ...i,
-      ...(e == null ? void 0 : e.page) && {
-        path: e.page.path,
-        title: e.page.title,
-        referrer: e.page.referrer
-      }
-    };
-    this.posthog.capture("$pageleave", a), this.log("Tracked page leave", { properties: i, context: e });
-  }
-  reset() {
-    !this.isEnabled() || !this.initialized || !this.posthog || !h() || (this.posthog.reset(), this.log("Reset user session"));
-  }
-}
-export {
-  o as B,
-  n as P
-};

package/dist/providers.d.ts

@@ -1,2 +0,0 @@
-export * from './src/providers/index'
-export {}