@stacksee/analytics 0.4.3 → 0.4.5

package/dist/client.js

@@ -1,12 +1,578 @@
-import { c as s, c as t, g as c, i, a as n, p as r, r as l, b as y, t as g } from "./client-CyvENC-f.js";
+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 n = (t, e, i) => u(t, typeof e != "symbol" ? e + "" : e, i);
+import { i as h } from "./client-RZPcOfAk.js";
+import { P } from "./client-RZPcOfAk.js";
+import { B as O } from "./base.provider-AfFL5W_P.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) {
+    n(this, "providers", []);
+    n(this, "context", {});
+    n(this, "userId");
+    n(this, "sessionId");
+    n(this, "initialized", !1);
+    n(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 s = null;
+function m(t) {
+  if (s)
+    return console.warn("[Analytics] Already initialized"), s;
+  const e = {
+    providers: t.providers || [],
+    debug: t.debug,
+    enabled: t.enabled
+  };
+  return s = new p(
+    e
+  ), s.initialize().catch((i) => {
+    console.error("[Analytics] Failed to initialize:", i);
+  }), s;
+}
+function a() {
+  if (!s)
+    throw new Error(
+      "[Analytics] Not initialized. Call createAnalytics() first."
+    );
+  return s;
+}
+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();
+}
 export {
-  s as createAnalytics,
-  t as createClientAnalytics,
-  c as getAnalytics,
-  i as identify,
-  n as pageLeave,
-  r as pageView,
-  l as reset,
-  y as resetAnalyticsInstance,
-  g as track
+  O as BaseAnalyticsProvider,
+  p as BrowserAnalytics,
+  P as PostHogClientProvider,
+  m as createAnalytics,
+  m as createClientAnalytics,
+  a as getAnalytics,
+  y as identify,
+  z as pageLeave,
+  w as pageView,
+  x as reset,
+  v as track
 };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export * from './src/index'
-export {}
+export type { EventCategory, BaseEvent, EventContext, AnalyticsProvider, AnalyticsConfig, } from './core/events/types.js';
+export type { CreateEventDefinition, ExtractEventNames, ExtractEventPropertiesFromCollection, EventCollection, AnyEventName, AnyEventProperties, EventMapFromCollection, } from './core/events/index.js';

package/dist/index.js

@@ -1,14 +1 @@
-import { B as t, c as s, g as i, i as r, a as n, p as l, r as o, t as c } from "./client-CyvENC-f.js";
-import { B as g, P as p } from "./client-MwIAm9fk.js";
-export {
-  g as BaseAnalyticsProvider,
-  t as BrowserAnalytics,
-  p as PostHogClientProvider,
-  s as createClientAnalytics,
-  i as getAnalytics,
-  r as identifyClient,
-  n as pageLeaveClient,
-  l as pageViewClient,
-  o as resetClient,
-  c as trackClient
-};
+

package/dist/providers/client.js

@@ -0,0 +1,6 @@
+import { B as e } from "../base.provider-AfFL5W_P.js";
+import { P as t } from "../client-RZPcOfAk.js";
+export {
+  e as BaseAnalyticsProvider,
+  t as PostHogClientProvider
+};

package/dist/{src/providers/index.d.ts → providers/server.d.ts}

@@ -1,5 +1,3 @@
 export { BaseAnalyticsProvider } from './base.provider.js';
-export { PostHogClientProvider } from './posthog/client.js';
 export { PostHogServerProvider } from './posthog/server.js';
-export type { PostHogConfig } from 'posthog-js';
 export type { PostHogOptions } from 'posthog-node';

package/dist/providers/server.js

@@ -0,0 +1,6 @@
+import { B as e } from "../base.provider-AfFL5W_P.js";
+import { P as a } from "../server-CMRw9K0d.js";
+export {
+  e as BaseAnalyticsProvider,
+  a as PostHogServerProvider
+};

package/dist/{providers.js → server-CMRw9K0d.js}

@@ -1,8 +1,7 @@
 var l = Object.defineProperty;
 var h = (r, s, i) => s in r ? l(r, s, { enumerable: !0, configurable: !0, writable: !0, value: i }) : r[s] = i;
 var t = (r, s, i) => h(r, typeof s != "symbol" ? s + "" : s, i);
-import { B as n } from "./client-MwIAm9fk.js";
-import { P as m } from "./client-MwIAm9fk.js";
+import { B as n } from "./base.provider-AfFL5W_P.js";
 import { PostHog as p } from "posthog-node";
 class u extends n {
   constructor(i) {
@@ -81,7 +80,5 @@ class u extends n {
   }
 }
 export {
-  n as BaseAnalyticsProvider,
-  m as PostHogClientProvider,
-  u as PostHogServerProvider
+  u as P
 };

package/dist/server.d.ts

@@ -1,2 +1,38 @@
-export * from './src/server'
-export {}
+import { ServerAnalytics } from './adapters/server/server-analytics.js';
+import { AnalyticsProvider } from './core/events/types.js';
+import { EventMapFromCollection } from './core/events/index.js';
+export interface ServerAnalyticsConfig {
+    providers?: AnalyticsProvider[];
+    debug?: boolean;
+    enabled?: boolean;
+}
+/**
+ * Create a server analytics instance
+ *
+ * @example
+ * ```typescript
+ * import { createServerAnalytics } from '@stacksee/analytics/server';
+ * import { PostHogServerProvider } from '@stacksee/analytics/providers/posthog';
+ * import { AppEvents } from './events';
+ *
+ * const analytics = createServerAnalytics<typeof AppEvents>({
+ *   providers: [
+ *     new PostHogServerProvider({
+ *       apiKey: process.env.POSTHOG_API_KEY,
+ *       host: process.env.POSTHOG_HOST
+ *     })
+ *   ],
+ *   debug: true,
+ *   enabled: true
+ * });
+ *
+ * // Now event names and properties are fully typed!
+ * await analytics.track('user_signed_up', {
+ *   userId: 'user-123',
+ *   email: 'user@example.com',
+ *   plan: 'pro'
+ * }, { userId: 'user-123' });
+ * ```
+ */
+export declare function createServerAnalytics<TEvents = never>(config: ServerAnalyticsConfig): ServerAnalytics<EventMapFromCollection<TEvents>>;
+export { ServerAnalytics };