@stacksee/analytics 0.9.7 → 0.10.0

package/dist/adapters/client/browser-analytics.d.ts

@@ -1,7 +1,7 @@
 import { AnalyticsConfig, EventContext } from '../../core/events/types.js';
 type DefaultEventMap = Record<string, Record<string, unknown>>;
 export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = DefaultEventMap, TUserTraits extends Record<string, unknown> = Record<string, unknown>> {
-    private providers;
+    private providerConfigs;
     private context;
     private userId?;
     private sessionId?;
@@ -39,6 +39,14 @@ export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = Defaul
      * ```
      */
     constructor(config: AnalyticsConfig);
+    /**
+     * Normalizes provider configurations into a consistent internal format
+     */
+    private normalizeProviders;
+    /**
+     * Checks if a method should be called on a provider based on routing configuration
+     */
+    private shouldCallMethod;
     /**
      * Initializes all analytics providers and sets up browser context.
      *

package/dist/adapters/server/server-analytics.d.ts

@@ -1,7 +1,7 @@
 import { AnalyticsConfig, EventContext, UserContext } from '../../core/events/types.js';
 type DefaultEventMap = Record<string, Record<string, unknown>>;
 export declare class ServerAnalytics<TEventMap extends Record<string, Record<string, unknown>> = DefaultEventMap, TUserTraits extends Record<string, unknown> = Record<string, unknown>> {
-    private providers;
+    private providerConfigs;
     private config;
     private initialized;
     /**
@@ -35,6 +35,14 @@ export declare class ServerAnalytics<TEventMap extends Record<string, Record<str
      * ```
      */
     constructor(config: AnalyticsConfig);
+    /**
+     * Normalizes provider configurations into a consistent internal format
+     */
+    private normalizeProviders;
+    /**
+     * Checks if a method should be called on a provider based on routing configuration
+     */
+    private shouldCallMethod;
     /**
      * Initializes all analytics providers.
      *

package/dist/client.js

@@ -1,25 +1,25 @@
-var u = Object.defineProperty;
-var h = (t, e, i) => e in t ? u(t, e, { enumerable: !0, configurable: !0, writable: !0, value: i }) : t[e] = i;
-var s = (t, e, i) => h(t, typeof e != "symbol" ? e + "" : e, i);
-import { i as p } from "./client-DTHZYkxx.js";
-import { P as b } from "./client-DTHZYkxx.js";
-import { B as C } from "./base.provider-AfFL5W_P.js";
-class f {
+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 f } from "./client-DTHZYkxx.js";
+import { P } from "./client-DTHZYkxx.js";
+import { B as k } 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({
@@ -31,43 +31,85 @@ class f {
    *     app: { version: '1.0.0' }
    *   }
    * });
-   * 
+   *
    * await analytics.initialize();
    * ```
    */
   constructor(e) {
-    s(this, "providers", []);
+    s(this, "providerConfigs", []);
     s(this, "context", {});
     s(this, "userId");
     s(this, "sessionId");
     s(this, "userTraits");
     s(this, "initialized", !1);
     s(this, "initializePromise");
-    this.providers = e.providers, e.defaultContext && (this.context = { ...e.defaultContext }), this.sessionId = this.generateSessionId();
+    this.providerConfigs = this.normalizeProviders(e.providers), e.defaultContext && (this.context = { ...e.defaultContext }), this.sessionId = this.generateSessionId();
+  }
+  /**
+   * Normalizes provider configurations into a consistent internal format
+   */
+  normalizeProviders(e) {
+    const i = [
+      "initialize",
+      "identify",
+      "track",
+      "pageView",
+      "pageLeave",
+      "reset"
+    ];
+    return e.map((r) => {
+      if ("initialize" in r && "track" in r)
+        return {
+          provider: r,
+          enabledMethods: new Set(i)
+        };
+      const n = r;
+      n.methods && n.exclude && console.warn(
+        `[Analytics] Provider ${n.provider.name} has both 'methods' and 'exclude' specified. Using 'methods' and ignoring 'exclude'.`
+      );
+      let o;
+      return n.methods ? o = new Set(n.methods) : n.exclude ? o = new Set(
+        i.filter(
+          (d) => {
+            var h;
+            return !((h = n.exclude) != null && h.includes(d));
+          }
+        )
+      ) : o = new Set(i), {
+        provider: n.provider,
+        enabledMethods: o
+      };
+    });
+  }
+  /**
+   * Checks if a method should be called on a provider based on routing configuration
+   */
+  shouldCallMethod(e, i) {
+    return e.enabledMethods.has(i);
   }
   /**
    * 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
@@ -76,12 +118,12 @@ class f {
    * ```
    */
   async initialize() {
-    if (p() && !this.initialized)
+    if (f() && !this.initialized)
       return this.initializePromise ? this.initializePromise : (this.initializePromise = this._doInitialize(), this.initializePromise);
   }
   async _doInitialize() {
-    const e = this.providers.map(
-      (i) => i.initialize()
+    const e = this.providerConfigs.map(
+      (i) => i.provider.initialize()
     );
     await Promise.all(e), this.initialized = !0, this.updateContext({
       page: {
@@ -170,8 +212,8 @@ class f {
     this.userId = e, this.userTraits = i, this.ensureInitialized().catch((r) => {
       console.error("[Analytics] Failed to initialize during identify:", r);
     });
-    for (const r of this.providers)
-      r.identify(e, i);
+    for (const r of this.providerConfigs)
+      this.shouldCallMethod(r, "identify") && r.provider.identify(e, i);
   }
   /**
    * Tracks a custom event with properties.
@@ -191,7 +233,7 @@ class f {
    * @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
@@ -257,43 +299,43 @@ class f {
       timestamp: Date.now(),
       userId: this.userId,
       sessionId: this.sessionId
-    }, o = {
+    }, n = {
       ...this.context,
       user: this.userId || this.userTraits ? {
         userId: this.userId,
         email: this.userTraits && "email" in this.userTraits ? this.userTraits.email : void 0,
         traits: this.userTraits
       } : void 0
-    }, l = this.providers.map(async (d) => {
+    }, o = this.providerConfigs.filter((d) => this.shouldCallMethod(d, "track")).map(async (d) => {
       try {
-        await d.track(r, o);
-      } catch (c) {
+        await d.provider.track(r, n);
+      } catch (h) {
         console.error(
-          `[Analytics] Provider ${d.name} failed to track event:`,
-          c
+          `[Analytics] Provider ${d.provider.name} failed to track event:`,
+          h
         );
       }
     });
-    await Promise.all(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
@@ -304,12 +346,12 @@ class f {
    *   source: 'organic_search'
    * });
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // In a SvelteKit app with automatic navigation tracking
    * import { afterNavigate } from '$app/navigation';
-   * 
+   *
    * afterNavigate(() => {
    *   analytics.pageView({
    *     timestamp: Date.now(),
@@ -317,16 +359,16 @@ class f {
    *   });
    * });
    * ```
-   * 
+   *
    * @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,
@@ -346,27 +388,27 @@ class f {
         referrer: document.referrer
       }
     });
-    for (const i of this.providers)
-      i.pageView(e, this.context);
+    for (const i of this.providerConfigs)
+      this.shouldCallMethod(i, "pageView") && i.provider.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
@@ -377,14 +419,14 @@ class f {
    *   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,
@@ -392,7 +434,7 @@ class f {
    *   });
    * });
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // Track page leave on browser unload
@@ -406,27 +448,30 @@ class f {
    */
   pageLeave(e) {
     this.ensureInitialized().catch((i) => {
-      console.error("[Analytics] Failed to initialize during pageLeave:", i);
+      console.error(
+        "[Analytics] Failed to initialize during pageLeave:",
+        i
+      );
     });
-    for (const i of this.providers)
-      i.pageLeave && i.pageLeave(e, this.context);
+    for (const i of this.providerConfigs)
+      this.shouldCallMethod(i, "pageLeave") && i.provider.pageLeave && i.provider.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
@@ -435,26 +480,26 @@ class f {
    *   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,
@@ -465,25 +510,25 @@ class f {
    */
   reset() {
     this.userId = void 0, this.userTraits = void 0, this.sessionId = this.generateSessionId();
-    for (const e of this.providers)
-      e.reset();
+    for (const e of this.providerConfigs)
+      this.shouldCallMethod(e, "reset") && e.provider.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
@@ -495,7 +540,7 @@ class f {
    *   }
    * });
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // Add UTM parameters from URL
@@ -510,7 +555,7 @@ class f {
    *   }
    * });
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // Update application context
@@ -529,14 +574,14 @@ class f {
    * ```
    */
   updateContext(e) {
-    var i, r, o;
+    var i, r, n;
     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)
+        referrer: e.page.referrer || ((n = this.context.page) == null ? void 0 : n.referrer)
       } : this.context.page,
       device: {
         ...this.context.device,
@@ -570,51 +615,51 @@ class f {
     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;
+let a = null;
 function v(t) {
-  if (n)
-    return console.warn("[Analytics] Already initialized"), n;
+  if (a)
+    return console.warn("[Analytics] Already initialized"), a;
   const e = {
     providers: t.providers || [],
     debug: t.debug,
     enabled: t.enabled
   };
-  return n = new f(e), n.initialize().catch((i) => {
+  return a = new p(e), a.initialize().catch((i) => {
     console.error("[Analytics] Failed to initialize:", i);
-  }), n;
+  }), a;
 }
-function a() {
-  if (!n)
+function l() {
+  if (!a)
     throw new Error(
       "[Analytics] Not initialized. Call createAnalytics() first."
     );
-  return n;
-}
-function y(t, e) {
-  return a().track(t, e);
+  return a;
 }
 function w(t, e) {
-  a().identify(t, e);
+  return l().track(t, e);
+}
+function y(t, e) {
+  l().identify(t, e);
 }
 function x(t) {
-  a().pageView(t);
+  l().pageView(t);
 }
 function z(t) {
-  a().pageLeave(t);
+  l().pageLeave(t);
 }
-function I() {
-  a().reset();
+function C() {
+  l().reset();
 }
 export {
-  C as BaseAnalyticsProvider,
-  f as BrowserAnalytics,
-  b as PostHogClientProvider,
+  k as BaseAnalyticsProvider,
+  p as BrowserAnalytics,
+  P as PostHogClientProvider,
   v as createAnalytics,
   v as createClientAnalytics,
-  a as getAnalytics,
-  w as identify,
+  l as getAnalytics,
+  y as identify,
   z as pageLeave,
   x as pageView,
-  I as reset,
-  y as track
+  C as reset,
+  w as track
 };

package/dist/core/events/types.d.ts

@@ -13,6 +13,17 @@ export interface UserContext<TTraits extends Record<string, unknown> = Record<st
     email?: string;
     traits?: TTraits;
 }
+/**
+ * Server-side context enrichment
+ * Used by server analytics to add request-specific metadata
+ */
+export interface ServerContext {
+    userAgent?: string;
+    ip?: string;
+    requestId?: string;
+    timestamp?: number;
+    [key: string]: unknown;
+}
 export interface EventContext<TTraits extends Record<string, unknown> = Record<string, unknown>> {
     user?: UserContext<TTraits>;
     page?: {
@@ -31,6 +42,7 @@ export interface EventContext<TTraits extends Record<string, unknown> = Record<s
         userAgent?: string;
         language?: string;
         timezone?: string;
+        ip?: string;
         screen?: {
             width?: number;
             height?: number;
@@ -45,6 +57,7 @@ export interface EventContext<TTraits extends Record<string, unknown> = Record<s
         medium?: string;
         name?: string;
     };
+    server?: ServerContext;
 }
 export interface AnalyticsProvider {
     name: string;
@@ -55,8 +68,57 @@ export interface AnalyticsProvider {
     pageLeave?(properties?: Record<string, unknown>, context?: EventContext): Promise<void> | void;
     reset(): Promise<void> | void;
 }
+/**
+ * Provider methods that can be selectively enabled/disabled through routing
+ */
+export type ProviderMethod = "initialize" | "identify" | "track" | "pageView" | "pageLeave" | "reset";
+/**
+ * Configuration for selective provider method routing.
+ * Allows you to control which methods are called on a specific provider.
+ *
+ * @example
+ * ```typescript
+ * // Only call track and identify, skip pageView
+ * {
+ *   provider: new BentoClientProvider({...}),
+ *   methods: ['track', 'identify']
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Call all methods except pageView
+ * {
+ *   provider: new GoogleAnalyticsProvider({...}),
+ *   exclude: ['pageView']
+ * }
+ * ```
+ */
+export interface ProviderConfig {
+    /**
+     * The analytics provider instance
+     */
+    provider: AnalyticsProvider;
+    /**
+     * Only call these methods on this provider.
+     * If specified, all other methods will be skipped.
+     * Mutually exclusive with `exclude`.
+     */
+    methods?: ProviderMethod[];
+    /**
+     * Skip these methods on this provider.
+     * All other methods will be called normally.
+     * Mutually exclusive with `methods`.
+     */
+    exclude?: ProviderMethod[];
+}
+/**
+ * Provider configuration - supports both simple provider instances
+ * and advanced routing configurations
+ */
+export type ProviderConfigOrProvider = AnalyticsProvider | ProviderConfig;
 export interface AnalyticsConfig {
-    providers: AnalyticsProvider[];
+    providers: ProviderConfigOrProvider[];
     debug?: boolean;
     enabled?: boolean;
     defaultContext?: Partial<EventContext>;