@stacksee/analytics 0.9.8 → 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

@@ -68,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>;

package/dist/providers/client.js

@@ -58,7 +58,7 @@ class w extends u {
     const s = (i == null ? void 0 : i.email) || e;
     if (this.bento.identify(s), i) {
       const t = { ...i };
-      delete t.email, Object.keys(t).length > 0 && this.bento.updateFields(t);
+      t.email = void 0, Object.keys(t).length > 0 && this.bento.updateFields(t);
     }
     this.log("Identified user", { userId: e, email: s, traits: i });
   }
@@ -139,7 +139,9 @@ class w extends u {
     this.bento.track("$pageleave", s), this.log("Tracked page leave", { properties: e, context: i });
   }
   reset() {
-    !this.isEnabled() || !this.initialized || !this.bento || !a() || this.log("Reset user session - Note: Bento doesn't have a native reset method");
+    !this.isEnabled() || !this.initialized || !this.bento || !a() || this.log(
+      "Reset user session - Note: Bento doesn't have a native reset method"
+    );
   }
   // ============================================================================
   // Bento-Specific Utility Methods
@@ -389,7 +391,7 @@ class v extends u {
     r(this, "retryAttempts");
     r(this, "retryBackoff");
     r(this, "retryInitialDelay");
-    this.config = e, this.batchSize = ((i = e.batch) == null ? void 0 : i.size) ?? 10, this.batchInterval = ((s = e.batch) == null ? void 0 : s.interval) ?? 5e3, this.retryAttempts = ((t = e.retry) == null ? void 0 : t.attempts) ?? 3, this.retryBackoff = ((n = e.retry) == null ? void 0 : n.backoff) ?? "exponential", this.retryInitialDelay = ((l = e.retry) == null ? void 0 : l.initialDelay) ?? 1e3, typeof window < "u" && (window.addEventListener("beforeunload", () => {
+    this.config = e, this.batchSize = ((i = e.batch) == null ? void 0 : i.size) ?? 10, this.batchInterval = ((s = e.batch) == null ? void 0 : s.interval) ?? 2e3, this.retryAttempts = ((t = e.retry) == null ? void 0 : t.attempts) ?? 3, this.retryBackoff = ((n = e.retry) == null ? void 0 : n.backoff) ?? "exponential", this.retryInitialDelay = ((l = e.retry) == null ? void 0 : l.initialDelay) ?? 1e3, typeof window < "u" && (window.addEventListener("beforeunload", () => {
       this.flush(!0);
     }), document.addEventListener("visibilitychange", () => {
       document.visibilityState === "hidden" && this.flush(!0);
@@ -442,11 +444,11 @@ class v extends u {
       });
       return;
     }
-    this.flushTimer || (this.flushTimer = setTimeout(() => {
+    this.flushTimer && clearTimeout(this.flushTimer), this.flushTimer = setTimeout(() => {
       this.flush().catch((i) => {
         console.error("[Proxy] Failed to flush events:", i);
       });
-    }, this.batchInterval));
+    }, this.batchInterval);
   }
   async sendEvents(e, i = !1) {
     const s = { events: e };

package/dist/providers/server.d.ts

@@ -2,7 +2,7 @@ export { BaseAnalyticsProvider } from './base.provider.js';
 export { PostHogServerProvider } from './posthog/server.js';
 export type { PostHogOptions } from 'posthog-node';
 export { BentoServerProvider } from './bento/server.js';
-export type { BentoServerConfig, BentoAnalyticsOptions } from './bento/server.js';
+export type { BentoServerConfig, BentoAnalyticsOptions, } from './bento/server.js';
 export { PirschServerProvider } from './pirsch/server.js';
 export type { PirschServerConfig } from './pirsch/server.js';
 export { ingestProxyEvents, createProxyHandler } from './proxy/server.js';

package/dist/providers/server.js

@@ -39,12 +39,15 @@ class N extends V {
     if (!this.isEnabled() || !this.initialized || !this.client) return;
     const r = (e == null ? void 0 : e.email) || i;
     if (!r || !r.includes("@")) {
-      this.log("Skipping identify - invalid or missing email", { userId: i, traits: e });
+      this.log("Skipping identify - invalid or missing email", {
+        userId: i,
+        traits: e
+      });
       return;
     }
     this.currentUserEmail = r;
     const h = e ? { ...e } : {};
-    delete h.email, this.client.V1.addSubscriber({
+    h.email = void 0, this.client.V1.addSubscriber({
       email: r,
       fields: h
     }).catch((s) => {
@@ -192,11 +195,14 @@ class W extends V {
     if (!this.isEnabled() || !this.initialized || !this.client) return;
     const r = e, h = ((a = r == null ? void 0 : r.device) == null ? void 0 : a.ip) || ((o = r == null ? void 0 : r.server) == null ? void 0 : o.ip), s = ((f = r == null ? void 0 : r.server) == null ? void 0 : f.userAgent) || ((y = r == null ? void 0 : r.device) == null ? void 0 : y.userAgent);
     if (!h || !s) {
-      this.log("Skipping event - missing required IP or user-agent from context", {
-        hasIp: !!h,
-        hasUserAgent: !!s,
-        event: i.action
-      });
+      this.log(
+        "Skipping event - missing required IP or user-agent from context",
+        {
+          hasIp: !!h,
+          hasUserAgent: !!s,
+          event: i.action
+        }
+      );
       return;
     }
     const g = {
@@ -205,11 +211,21 @@ class W extends V {
       user_agent: s,
       ...((k = e == null ? void 0 : e.page) == null ? void 0 : k.title) && { title: e.page.title },
       ...((I = e == null ? void 0 : e.page) == null ? void 0 : I.referrer) && { referrer: e.page.referrer },
-      ...((E = (_ = e == null ? void 0 : e.device) == null ? void 0 : _.screen) == null ? void 0 : E.width) && { screen_width: e.device.screen.width },
-      ...((z = (P = e == null ? void 0 : e.device) == null ? void 0 : P.screen) == null ? void 0 : z.height) && { screen_height: e.device.screen.height },
-      ...((A = (B = e == null ? void 0 : e.device) == null ? void 0 : B.viewport) == null ? void 0 : A.width) && { sec_ch_viewport_width: String(e.device.viewport.width) },
-      ...((F = e == null ? void 0 : e.device) == null ? void 0 : F.language) && { accept_language: e.device.language },
-      ...((v = e == null ? void 0 : e.device) == null ? void 0 : v.type) && { sec_ch_ua_mobile: e.device.type === "mobile" || e.device.type === "tablet" ? "?1" : "?0" },
+      ...((E = (_ = e == null ? void 0 : e.device) == null ? void 0 : _.screen) == null ? void 0 : E.width) && {
+        screen_width: e.device.screen.width
+      },
+      ...((z = (P = e == null ? void 0 : e.device) == null ? void 0 : P.screen) == null ? void 0 : z.height) && {
+        screen_height: e.device.screen.height
+      },
+      ...((A = (B = e == null ? void 0 : e.device) == null ? void 0 : B.viewport) == null ? void 0 : A.width) && {
+        sec_ch_viewport_width: String(e.device.viewport.width)
+      },
+      ...((F = e == null ? void 0 : e.device) == null ? void 0 : F.language) && {
+        accept_language: e.device.language
+      },
+      ...((v = e == null ? void 0 : e.device) == null ? void 0 : v.type) && {
+        sec_ch_ua_mobile: e.device.type === "mobile" || e.device.type === "tablet" ? "?1" : "?0"
+      },
       ...(($ = e == null ? void 0 : e.device) == null ? void 0 : $.os) && { sec_ch_ua_platform: e.device.os }
     }, l = {
       ...Object.fromEntries(
@@ -236,10 +252,13 @@ class W extends V {
     if (!this.isEnabled() || !this.initialized || !this.client) return;
     const r = e, h = ((n = r == null ? void 0 : r.device) == null ? void 0 : n.ip) || ((l = r == null ? void 0 : r.server) == null ? void 0 : l.ip), s = ((a = r == null ? void 0 : r.server) == null ? void 0 : a.userAgent) || ((o = r == null ? void 0 : r.device) == null ? void 0 : o.userAgent);
     if (!h || !s) {
-      this.log("Skipping pageView - missing required IP or user-agent from context", {
-        hasIp: !!h,
-        hasUserAgent: !!s
-      });
+      this.log(
+        "Skipping pageView - missing required IP or user-agent from context",
+        {
+          hasIp: !!h,
+          hasUserAgent: !!s
+        }
+      );
       return;
     }
     const g = {
@@ -248,11 +267,21 @@ class W extends V {
       user_agent: s,
       ...((b = e == null ? void 0 : e.page) == null ? void 0 : b.title) && { title: e.page.title },
       ...((S = e == null ? void 0 : e.page) == null ? void 0 : S.referrer) && { referrer: e.page.referrer },
-      ...((I = (k = e == null ? void 0 : e.device) == null ? void 0 : k.screen) == null ? void 0 : I.width) && { screen_width: e.device.screen.width },
-      ...((E = (_ = e == null ? void 0 : e.device) == null ? void 0 : _.screen) == null ? void 0 : E.height) && { screen_height: e.device.screen.height },
-      ...((z = (P = e == null ? void 0 : e.device) == null ? void 0 : P.viewport) == null ? void 0 : z.width) && { sec_ch_viewport_width: String(e.device.viewport.width) },
-      ...((B = e == null ? void 0 : e.device) == null ? void 0 : B.language) && { accept_language: e.device.language },
-      ...((A = e == null ? void 0 : e.device) == null ? void 0 : A.type) && { sec_ch_ua_mobile: e.device.type === "mobile" || e.device.type === "tablet" ? "?1" : "?0" },
+      ...((I = (k = e == null ? void 0 : e.device) == null ? void 0 : k.screen) == null ? void 0 : I.width) && {
+        screen_width: e.device.screen.width
+      },
+      ...((E = (_ = e == null ? void 0 : e.device) == null ? void 0 : _.screen) == null ? void 0 : E.height) && {
+        screen_height: e.device.screen.height
+      },
+      ...((z = (P = e == null ? void 0 : e.device) == null ? void 0 : P.viewport) == null ? void 0 : z.width) && {
+        sec_ch_viewport_width: String(e.device.viewport.width)
+      },
+      ...((B = e == null ? void 0 : e.device) == null ? void 0 : B.language) && {
+        accept_language: e.device.language
+      },
+      ...((A = e == null ? void 0 : e.device) == null ? void 0 : A.type) && {
+        sec_ch_ua_mobile: e.device.type === "mobile" || e.device.type === "tablet" ? "?1" : "?0"
+      },
       ...((F = e == null ? void 0 : e.device) == null ? void 0 : F.os) && { sec_ch_ua_platform: e.device.os },
       ...i && {
         tags: Object.fromEntries(

package/dist/server.js

@@ -1,24 +1,24 @@
-var u = Object.defineProperty;
-var o = (i, e, r) => e in i ? u(i, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : i[e] = r;
-var s = (i, e, r) => o(i, typeof e != "symbol" ? e + "" : e, r);
+var h = Object.defineProperty;
+var f = (a, r, e) => r in a ? h(a, r, { enumerable: !0, configurable: !0, writable: !0, value: e }) : a[r] = e;
+var o = (a, r, e) => f(a, typeof r != "symbol" ? r + "" : r, e);
 import { P as w } from "./server-DjEk1fUD.js";
-import { B as z } from "./base.provider-AfFL5W_P.js";
+import { B as x } from "./base.provider-AfFL5W_P.js";
 class v {
   /**
    * Creates a new ServerAnalytics instance for server-side event tracking.
-   * 
+   *
    * The server analytics instance is designed for Node.js environments including
    * long-running servers, serverless functions, and edge computing environments.
-   * 
+   *
    * @param config Analytics configuration including providers and default context
    * @param config.providers Array of analytics provider instances (e.g., PostHogServerProvider)
    * @param config.defaultContext Optional default context to include with all events
-   * 
+   *
    * @example
    * ```typescript
    * import { ServerAnalytics } from '@stacksee/analytics/server';
    * import { PostHogServerProvider } from '@stacksee/analytics/providers/posthog';
-   * 
+   *
    * const analytics = new ServerAnalytics({
    *   providers: [
    *     new PostHogServerProvider({
@@ -30,75 +30,117 @@ class v {
    *     app: { version: '1.0.0', environment: 'production' }
    *   }
    * });
-   * 
+   *
    * analytics.initialize();
    * ```
    */
-  constructor(e) {
-    s(this, "providers", []);
-    s(this, "config");
-    s(this, "initialized", !1);
-    this.config = e, this.providers = e.providers;
+  constructor(r) {
+    o(this, "providerConfigs", []);
+    o(this, "config");
+    o(this, "initialized", !1);
+    this.config = r, this.providerConfigs = this.normalizeProviders(r.providers);
+  }
+  /**
+   * Normalizes provider configurations into a consistent internal format
+   */
+  normalizeProviders(r) {
+    const e = [
+      "initialize",
+      "identify",
+      "track",
+      "pageView",
+      "pageLeave",
+      "reset"
+    ];
+    return r.map((i) => {
+      if ("initialize" in i && "track" in i)
+        return {
+          provider: i,
+          enabledMethods: new Set(e)
+        };
+      const t = i;
+      t.methods && t.exclude && console.warn(
+        `[Analytics] Provider ${t.provider.name} has both 'methods' and 'exclude' specified. Using 'methods' and ignoring 'exclude'.`
+      );
+      let n;
+      return t.methods ? n = new Set(t.methods) : t.exclude ? n = new Set(
+        e.filter(
+          (l) => {
+            var d;
+            return !((d = t.exclude) != null && d.includes(l));
+          }
+        )
+      ) : n = new Set(e), {
+        provider: t.provider,
+        enabledMethods: n
+      };
+    });
+  }
+  /**
+   * Checks if a method should be called on a provider based on routing configuration
+   */
+  shouldCallMethod(r, e) {
+    return r.enabledMethods.has(e);
   }
   /**
    * Initializes all analytics providers.
-   * 
+   *
    * This method must be called before tracking events. It initializes all configured
    * providers synchronously. Unlike the browser version, server initialization is
    * typically synchronous as providers don't need to load external scripts.
-   * 
+   *
    * The method is safe to call multiple times and will not re-initialize if already done.
-   * 
+   *
    * @example
    * ```typescript
    * const analytics = new ServerAnalytics({ providers: [] });
-   * 
+   *
    * // Initialize before tracking events
    * analytics.initialize();
-   * 
+   *
    * // Now ready to track events
    * await analytics.track('api_request', { endpoint: '/users' });
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // In a serverless function
    * export async function handler(req, res) {
    *   const analytics = new ServerAnalytics({ providers: [] });
    *   analytics.initialize(); // Quick synchronous initialization
-   *   
+   *
    *   await analytics.track('function_invoked', {
    *     path: req.path,
    *     method: req.method
    *   });
-   *   
+   *
    *   await analytics.shutdown(); // Important for serverless
    * }
    * ```
    */
   initialize() {
     if (!this.initialized) {
-      for (const e of this.providers)
-        e.initialize();
+      for (const r of this.providerConfigs)
+        r.provider.initialize();
       this.initialized = !0;
     }
   }
   /**
    * Identifies a user with optional traits.
-   * 
+   *
    * Associates subsequent events with the specified user ID and optionally
    * sets user properties. This method is typically called when processing
    * authentication or when you have user context available on the server.
-   * 
+   *
    * @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 from database
@@ -111,27 +153,27 @@ class v {
    *   lastSeenAt: new Date().toISOString()
    * });
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // In an API authentication middleware
    * async function authMiddleware(req, res, next) {
    *   const user = await getUserFromToken(req.headers.authorization);
-   *   
+   *
    *   analytics.identify(user.id, {
    *     email: user.email,
    *     role: user.role,
    *     organization: user.organization
    *   });
-   *   
+   *
    *   req.user = user;
    *   next();
    * }
    * ```
    */
-  identify(e, r) {
-    for (const t of this.providers)
-      t.identify(e, r);
+  identify(r, e) {
+    for (const i of this.providerConfigs)
+      this.shouldCallMethod(i, "identify") && i.provider.identify(r, e);
   }
   /**
    * Tracks a custom event with properties and optional context.
@@ -254,30 +296,30 @@ class v {
    * }
    * ```
    */
-  async track(e, r, t) {
-    var n;
+  async track(r, e, i) {
+    var d;
     if (!this.initialized) {
       console.warn("[Analytics] Not initialized. Call initialize() first.");
       return;
     }
-    const a = {
-      action: e,
-      category: this.getCategoryFromEventName(e),
-      properties: r,
+    const t = {
+      action: r,
+      category: this.getCategoryFromEventName(r),
+      properties: e,
       timestamp: Date.now(),
-      userId: t == null ? void 0 : t.userId,
-      sessionId: t == null ? void 0 : t.sessionId
-    }, d = {
+      userId: i == null ? void 0 : i.userId,
+      sessionId: i == null ? void 0 : i.sessionId
+    }, n = {
       ...this.config.defaultContext,
-      ...t == null ? void 0 : t.context,
-      user: (t == null ? void 0 : t.user) || ((n = t == null ? void 0 : t.context) == null ? void 0 : n.user)
-    }, l = this.providers.map(async (c) => {
+      ...i == null ? void 0 : i.context,
+      user: (i == null ? void 0 : i.user) || ((d = i == null ? void 0 : i.context) == null ? void 0 : d.user)
+    }, l = this.providerConfigs.filter((s) => this.shouldCallMethod(s, "track")).map(async (s) => {
       try {
-        await c.track(a, d);
-      } catch (f) {
+        await s.provider.track(t, n);
+      } catch (c) {
         console.error(
-          `[Analytics] Provider ${c.name} failed to track event:`,
-          f
+          `[Analytics] Provider ${s.provider.name} failed to track event:`,
+          c
         );
       }
     });
@@ -285,21 +327,21 @@ class v {
   }
   /**
    * Tracks a page view event from the server side.
-   * 
+   *
    * Server-side page view tracking is useful for server-rendered applications,
    * SSR frameworks, or when you want to ensure page views are tracked even
    * if client-side JavaScript fails.
-   * 
+   *
    * @param properties Optional properties to include with the page view
    * @param options Optional configuration including context
    * @param options.context Additional context for this page view
-   * 
+   *
    * @example
    * ```typescript
    * // Basic server-side page view
    * analytics.pageView();
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // Page view with server context
@@ -323,7 +365,7 @@ class v {
    *   }
    * });
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // In a Next.js API route or middleware
@@ -343,35 +385,35 @@ class v {
    * }
    * ```
    */
-  pageView(e, r) {
+  pageView(r, e) {
     if (!this.initialized) return;
-    const t = {
+    const i = {
       ...this.config.defaultContext,
-      ...r == null ? void 0 : r.context
+      ...e == null ? void 0 : e.context
     };
-    for (const a of this.providers)
-      a.pageView(e, t);
+    for (const t of this.providerConfigs)
+      this.shouldCallMethod(t, "pageView") && t.provider.pageView(r, i);
   }
   /**
    * Tracks when a user leaves a page from the server side.
-   * 
+   *
    * Server-side page leave tracking is less common than client-side but can be
    * useful in certain scenarios like tracking session timeouts, or when combined
    * with server-side session management.
-   * 
+   *
    * 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
    * @param options Optional configuration including context
    * @param options.context Additional context for this page leave
-   * 
+   *
    * @example
    * ```typescript
    * // Basic page leave tracking
    * analytics.pageLeave();
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // Page leave with session context
@@ -392,63 +434,63 @@ class v {
    *   }
    * });
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // In a session cleanup job
    * async function cleanupExpiredSessions() {
    *   const expiredSessions = await getExpiredSessions();
-   *   
+   *
    *   for (const session of expiredSessions) {
    *     analytics.pageLeave({
    *       sessionId: session.id,
    *       duration: session.duration,
    *       reason: 'expired'
    *     });
-   *     
+   *
    *     await removeSession(session.id);
    *   }
    * }
    * ```
    */
-  pageLeave(e, r) {
+  pageLeave(r, e) {
     if (!this.initialized) return;
-    const t = {
+    const i = {
       ...this.config.defaultContext,
-      ...r == null ? void 0 : r.context
+      ...e == null ? void 0 : e.context
     };
-    for (const a of this.providers)
-      a.pageLeave && a.pageLeave(e, t);
+    for (const t of this.providerConfigs)
+      this.shouldCallMethod(t, "pageLeave") && t.provider.pageLeave && t.provider.pageLeave(r, i);
   }
   /**
    * Shuts down all analytics providers and flushes pending events.
-   * 
+   *
    * This method is crucial for server environments, especially serverless functions,
    * as it ensures all events are sent before the process terminates. Some providers
    * batch events and need an explicit flush to send them.
-   * 
+   *
    * Always call this method before your server shuts down or before a serverless
    * function completes execution.
-   * 
+   *
    * @returns Promise that resolves when all providers have been shut down
-   * 
+   *
    * @example
    * ```typescript
    * // Basic shutdown
    * await analytics.shutdown();
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // In a serverless function
    * export async function handler(event, context) {
    *   const analytics = new ServerAnalytics({ providers: [] });
    *   analytics.initialize();
-   *   
+   *
    *   try {
    *     // Process the event
    *     await processEvent(event);
-   *     
+   *
    *     // Track completion
    *     await analytics.track('function_completed', {
    *       duration: Date.now() - startTime,
@@ -463,20 +505,20 @@ class v {
    *     // Always shutdown to flush events
    *     await analytics.shutdown();
    *   }
-   *   
+   *
    *   return { statusCode: 200 };
    * }
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // In an Express.js server
    * const server = app.listen(3000);
-   * 
+   *
    * // Graceful shutdown
    * process.on('SIGTERM', async () => {
    *   console.log('Shutting down gracefully...');
-   *   
+   *
    *   server.close(async () => {
    *     // Flush analytics events before exit
    *     await analytics.shutdown();
@@ -484,45 +526,45 @@ class v {
    *   });
    * });
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // With Vercel's waitUntil
    * import { waitUntil } from '@vercel/functions';
-   * 
+   *
    * export default async function handler(req, res) {
    *   // Process request
    *   const result = await processRequest(req);
-   *   
+   *
    *   // Track in background without blocking response
    *   waitUntil(
    *     analytics.track('api_request', { endpoint: req.url })
    *       .then(() => analytics.shutdown())
    *   );
-   *   
+   *
    *   return res.json(result);
    * }
    * ```
    */
   async shutdown() {
-    const e = this.providers.map((r) => "shutdown" in r && typeof r.shutdown == "function" ? r.shutdown() : Promise.resolve());
-    await Promise.all(e);
+    const r = this.providerConfigs.map((e) => "shutdown" in e.provider && typeof e.provider.shutdown == "function" ? e.provider.shutdown() : Promise.resolve());
+    await Promise.all(r);
   }
-  getCategoryFromEventName(e) {
-    const r = e.split("_");
-    return r.length > 1 && r[0] ? r[0] : "engagement";
+  getCategoryFromEventName(r) {
+    const e = r.split("_");
+    return e.length > 1 && e[0] ? e[0] : "engagement";
   }
 }
-function g(i) {
-  const e = {
-    providers: i.providers || [],
-    debug: i.debug,
-    enabled: i.enabled
-  }, r = new v(e);
-  return r.initialize(), r;
+function g(a) {
+  const r = {
+    providers: a.providers || [],
+    debug: a.debug,
+    enabled: a.enabled
+  }, e = new v(r);
+  return e.initialize(), e;
 }
 export {
-  z as BaseAnalyticsProvider,
+  x as BaseAnalyticsProvider,
   w as PostHogServerProvider,
   v as ServerAnalytics,
   g as createServerAnalytics

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacksee/analytics",
-  "version": "0.9.8",
+  "version": "0.10.0",
   "description": "A highly typed, provider-agnostic analytics library for TypeScript applications",
   "type": "module",
   "exports": {