@stacksee/analytics 0.11.1 → 0.13.0

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

@@ -47,6 +47,10 @@ export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = Defaul
      * Checks if a method should be called on a provider based on routing configuration
      */
     private shouldCallMethod;
+    /**
+     * Checks if an event should be tracked on a provider based on event filtering configuration
+     */
+    private shouldTrackEvent;
     /**
      * Initializes all analytics providers and sets up browser context.
      *

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

@@ -43,6 +43,10 @@ export declare class ServerAnalytics<TEventMap extends Record<string, Record<str
      * Checks if a method should be called on a provider based on routing configuration
      */
     private shouldCallMethod;
+    /**
+     * Checks if an event should be tracked on a provider based on event filtering configuration
+     */
+    private shouldTrackEvent;
     /**
      * Initializes all analytics providers.
      *

package/dist/client.d.ts

@@ -1,8 +1,8 @@
 import { BrowserAnalytics } from './adapters/client/browser-analytics.js';
-import { AnalyticsProvider } from './core/events/types.js';
+import { ProviderConfigOrProvider } from './core/events/types.js';
 import { EventMapFromCollection } from './core/events/index.js';
 export interface ClientAnalyticsConfig {
-    providers?: AnalyticsProvider[];
+    providers?: ProviderConfigOrProvider[];
     debug?: boolean;
     enabled?: boolean;
 }

package/dist/client.js

@@ -1,10 +1,10 @@
-var c = Object.defineProperty;
-var u = (r, e, i) => e in r ? c(r, e, { enumerable: !0, configurable: !0, writable: !0, value: i }) : r[e] = i;
-var n = (r, e, i) => u(r, 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 {
+var f = Object.defineProperty;
+var p = (n, e, t) => e in n ? f(n, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : n[e] = t;
+var a = (n, e, t) => p(n, typeof e != "symbol" ? e + "" : e, t);
+import { i as g } from "./client-DTHZYkxx.js";
+import { P as k } from "./client-DTHZYkxx.js";
+import { B as O } from "./base.provider-AfFL5W_P.js";
+class m {
   /**
    * Creates a new BrowserAnalytics instance for client-side event tracking.
    *
@@ -36,20 +36,20 @@ class p {
    * ```
    */
   constructor(e) {
-    n(this, "providerConfigs", []);
-    n(this, "context", {});
-    n(this, "userId");
-    n(this, "sessionId");
-    n(this, "userTraits");
-    n(this, "initialized", !1);
-    n(this, "initializePromise");
+    a(this, "providerConfigs", []);
+    a(this, "context", {});
+    a(this, "userId");
+    a(this, "sessionId");
+    a(this, "userTraits");
+    a(this, "initialized", !1);
+    a(this, "initializePromise");
     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 = [
+    const t = [
       "initialize",
       "identify",
       "track",
@@ -57,35 +57,55 @@ class p {
       "pageLeave",
       "reset"
     ];
-    return e.map((t) => {
-      if ("initialize" in t && "track" in t)
+    return e.map((r) => {
+      if ("initialize" in r && "track" in r)
         return {
-          provider: t,
-          enabledMethods: new Set(i)
+          provider: r,
+          enabledMethods: new Set(t)
         };
-      const s = t;
-      s.methods && s.exclude && console.warn(
-        `[Analytics] Provider ${s.provider.name} has both 'methods' and 'exclude' specified. Using 'methods' and ignoring 'exclude'.`
+      const i = r;
+      i.methods && i.exclude && console.warn(
+        `[Analytics] Provider ${i.provider.name} has both 'methods' and 'exclude' specified. Using 'methods' and ignoring 'exclude'.`
+      ), i.events && i.excludeEvents && console.warn(
+        `[Analytics] Provider ${i.provider.name} has both 'events' and 'excludeEvents' specified. Using 'events' and ignoring 'excludeEvents'.`
+      ), i.events && i.eventPatterns && console.warn(
+        `[Analytics] Provider ${i.provider.name} has both 'events' and 'eventPatterns' specified. Using 'events' and ignoring 'eventPatterns'.`
+      ), i.excludeEvents && i.eventPatterns && console.warn(
+        `[Analytics] Provider ${i.provider.name} has both 'excludeEvents' and 'eventPatterns' specified. Using 'eventPatterns' and ignoring 'excludeEvents'.`
       );
-      let o;
-      return s.methods ? o = new Set(s.methods) : s.exclude ? o = new Set(
-        i.filter(
-          (d) => {
-            var h;
-            return !((h = s.exclude) != null && h.includes(d));
+      let d;
+      i.methods ? d = new Set(i.methods) : i.exclude ? d = new Set(
+        t.filter(
+          (u) => {
+            var c;
+            return !((c = i.exclude) != null && c.includes(u));
           }
         )
-      ) : o = new Set(i), {
-        provider: s.provider,
-        enabledMethods: o
+      ) : d = new Set(t);
+      let s, h, v;
+      return i.events && i.events.length > 0 ? s = new Set(i.events) : i.eventPatterns && i.eventPatterns.length > 0 ? v = i.eventPatterns.map((u) => {
+        const c = u.replace(/\*/g, ".*");
+        return new RegExp(`^${c}$`);
+      }) : i.excludeEvents && i.excludeEvents.length > 0 && (h = new Set(i.excludeEvents)), {
+        provider: i.provider,
+        enabledMethods: d,
+        enabledEvents: s,
+        excludedEvents: h,
+        eventPatterns: v
       };
     });
   }
   /**
    * Checks if a method should be called on a provider based on routing configuration
    */
-  shouldCallMethod(e, i) {
-    return e.enabledMethods.has(i);
+  shouldCallMethod(e, t) {
+    return e.enabledMethods.has(t);
+  }
+  /**
+   * Checks if an event should be tracked on a provider based on event filtering configuration
+   */
+  shouldTrackEvent(e, t) {
+    return !e.enabledEvents && !e.excludedEvents && !e.eventPatterns ? !0 : e.enabledEvents ? e.enabledEvents.has(t) : e.eventPatterns ? e.eventPatterns.some((r) => r.test(t)) : e.excludedEvents ? !e.excludedEvents.has(t) : !0;
   }
   /**
    * Initializes all analytics providers and sets up browser context.
@@ -118,12 +138,12 @@ class p {
    * ```
    */
   async initialize() {
-    if (f() && !this.initialized)
+    if (g() && !this.initialized)
       return this.initializePromise ? this.initializePromise : (this.initializePromise = this._doInitialize(), this.initializePromise);
   }
   async _doInitialize() {
     const e = this.providerConfigs.map(
-      (i) => i.provider.initialize()
+      (t) => t.provider.initialize()
     );
     await Promise.all(e), this.initialized = !0, this.updateContext({
       page: {
@@ -208,12 +228,12 @@ class p {
    * }
    * ```
    */
-  identify(e, i) {
-    this.userId = e, this.userTraits = i, this.ensureInitialized().catch((t) => {
-      console.error("[Analytics] Failed to initialize during identify:", t);
+  identify(e, t) {
+    this.userId = e, this.userTraits = t, this.ensureInitialized().catch((r) => {
+      console.error("[Analytics] Failed to initialize during identify:", r);
     });
-    for (const t of this.providerConfigs)
-      this.shouldCallMethod(t, "identify") && t.provider.identify(e, i);
+    for (const r of this.providerConfigs)
+      this.shouldCallMethod(r, "identify") && r.provider.identify(e, t);
   }
   /**
    * Tracks a custom event with properties.
@@ -290,33 +310,35 @@ class p {
    * }
    * ```
    */
-  async track(e, i) {
+  async track(e, t) {
     await this.ensureInitialized();
-    const t = {
+    const r = {
       action: e,
       category: this.getCategoryFromEventName(e),
-      properties: i,
+      properties: t,
       timestamp: Date.now(),
       userId: this.userId,
       sessionId: this.sessionId
-    }, s = {
+    }, i = {
       ...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
-    }, o = this.providerConfigs.filter((d) => this.shouldCallMethod(d, "track")).map(async (d) => {
+    }, d = this.providerConfigs.filter(
+      (s) => this.shouldCallMethod(s, "track") && this.shouldTrackEvent(s, e)
+    ).map(async (s) => {
       try {
-        await d.provider.track(t, s);
+        await s.provider.track(r, i);
       } catch (h) {
         console.error(
-          `[Analytics] Provider ${d.provider.name} failed to track event:`,
+          `[Analytics] Provider ${s.provider.name} failed to track event:`,
           h
         );
       }
     });
-    await Promise.all(o);
+    await Promise.all(d);
   }
   /**
    * Tracks a page view event.
@@ -379,8 +401,8 @@ class p {
    * ```
    */
   pageView(e) {
-    this.ensureInitialized().catch((i) => {
-      console.error("[Analytics] Failed to initialize during pageView:", i);
+    this.ensureInitialized().catch((t) => {
+      console.error("[Analytics] Failed to initialize during pageView:", t);
     }), this.updateContext({
       page: {
         path: window.location.pathname,
@@ -388,8 +410,8 @@ class p {
         referrer: document.referrer
       }
     });
-    for (const i of this.providerConfigs)
-      this.shouldCallMethod(i, "pageView") && i.provider.pageView(e, this.context);
+    for (const t of this.providerConfigs)
+      this.shouldCallMethod(t, "pageView") && t.provider.pageView(e, this.context);
   }
   /**
    * Tracks when a user leaves a page.
@@ -447,14 +469,14 @@ class p {
    * ```
    */
   pageLeave(e) {
-    this.ensureInitialized().catch((i) => {
+    this.ensureInitialized().catch((t) => {
       console.error(
         "[Analytics] Failed to initialize during pageLeave:",
-        i
+        t
       );
     });
-    for (const i of this.providerConfigs)
-      this.shouldCallMethod(i, "pageLeave") && i.provider.pageLeave && i.provider.pageLeave(e, this.context);
+    for (const t of this.providerConfigs)
+      this.shouldCallMethod(t, "pageLeave") && t.provider.pageLeave && t.provider.pageLeave(e, this.context);
   }
   /**
    * Resets the analytics state, clearing user ID and generating a new session.
@@ -549,18 +571,18 @@ class p {
    * ```
    */
   async flush(e = !1) {
-    const i = this.providerConfigs.map(async (t) => {
-      if (t.provider.flush && typeof t.provider.flush == "function")
+    const t = this.providerConfigs.map(async (r) => {
+      if (r.provider.flush && typeof r.provider.flush == "function")
         try {
-          await t.provider.flush(e);
-        } catch (s) {
+          await r.provider.flush(e);
+        } catch (i) {
           console.error(
-            `[Analytics] Provider ${t.provider.name} failed to flush:`,
-            s
+            `[Analytics] Provider ${r.provider.name} failed to flush:`,
+            i
           );
         }
     });
-    await Promise.all(i);
+    await Promise.all(t);
   }
   /**
    * Updates the analytics context with new information.
@@ -623,14 +645,14 @@ class p {
    * ```
    */
   updateContext(e) {
-    var i, t, s;
+    var t, r, i;
     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 || ((t = this.context.page) == null ? void 0 : t.title),
-        referrer: e.page.referrer || ((s = this.context.page) == null ? void 0 : s.referrer)
+        path: e.page.path || ((t = this.context.page) == null ? void 0 : t.path) || window.location.pathname,
+        title: e.page.title || ((r = this.context.page) == null ? void 0 : r.title),
+        referrer: e.page.referrer || ((i = this.context.page) == null ? void 0 : i.referrer)
       } : this.context.page,
       device: {
         ...this.context.device,
@@ -643,8 +665,8 @@ class p {
     };
   }
   getCategoryFromEventName(e) {
-    const i = e.split("_");
-    return i.length > 1 && i[0] ? i[0] : "engagement";
+    const t = e.split("_");
+    return t.length > 1 && t[0] ? t[0] : "engagement";
   }
   generateSessionId() {
     return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
@@ -664,51 +686,51 @@ class p {
     return e.indexOf("Chrome") !== -1 ? "Chrome" : e.indexOf("Safari") !== -1 ? "Safari" : e.indexOf("Firefox") !== -1 ? "Firefox" : e.indexOf("Edge") !== -1 ? "Edge" : "Unknown";
   }
 }
-let a = null;
-function v(r) {
-  if (a)
-    return console.warn("[Analytics] Already initialized"), a;
+let o = null;
+function y(n) {
+  if (o)
+    return console.warn("[Analytics] Already initialized"), o;
   const e = {
-    providers: r.providers || [],
-    debug: r.debug,
-    enabled: r.enabled
+    providers: n.providers || [],
+    debug: n.debug,
+    enabled: n.enabled
   };
-  return a = new p(e), a.initialize().catch((i) => {
-    console.error("[Analytics] Failed to initialize:", i);
-  }), a;
+  return o = new m(e), o.initialize().catch((t) => {
+    console.error("[Analytics] Failed to initialize:", t);
+  }), o;
 }
 function l() {
-  if (!a)
+  if (!o)
     throw new Error(
       "[Analytics] Not initialized. Call createAnalytics() first."
     );
-  return a;
+  return o;
 }
-function y(r, e) {
-  return l().track(r, e);
+function P(n, e) {
+  return l().track(n, e);
 }
-function w(r, e) {
-  l().identify(r, e);
+function z(n, e) {
+  l().identify(n, e);
 }
-function x(r) {
-  l().pageView(r);
+function C(n) {
+  l().pageView(n);
 }
-function z(r) {
-  l().pageLeave(r);
+function A(n) {
+  l().pageLeave(n);
 }
-function C() {
+function b() {
   l().reset();
 }
 export {
-  k as BaseAnalyticsProvider,
-  p as BrowserAnalytics,
-  P as PostHogClientProvider,
-  v as createAnalytics,
-  v as createClientAnalytics,
+  O as BaseAnalyticsProvider,
+  m as BrowserAnalytics,
+  k as PostHogClientProvider,
+  y as createAnalytics,
+  y as createClientAnalytics,
   l as getAnalytics,
-  w as identify,
-  z as pageLeave,
-  x as pageView,
-  C as reset,
-  y as track
+  z as identify,
+  A as pageLeave,
+  C as pageView,
+  b as reset,
+  P as track
 };

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

@@ -74,8 +74,9 @@ export interface AnalyticsProvider {
  */
 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.
+ * Configuration for selective provider method routing and event filtering.
+ * Allows you to control which methods are called on a specific provider
+ * and which events are tracked.
  *
  * @example
  * ```typescript
@@ -94,6 +95,33 @@ export type ProviderMethod = "initialize" | "identify" | "track" | "pageView" |
  *   exclude: ['pageView']
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Only track specific events (solves 1-to-50 problem)
+ * {
+ *   provider: new EmitKitServerProvider({...}),
+ *   events: ['newsletter_signup', 'user_registered']
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Track all events except specific ones
+ * {
+ *   provider: new PostHogServerProvider({...}),
+ *   excludeEvents: ['newsletter_signup']
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use glob patterns to match multiple events
+ * {
+ *   provider: new EmitKitServerProvider({...}),
+ *   eventPatterns: ['newsletter_*', 'user_*']
+ * }
+ * ```
  */
 export interface ProviderConfig {
     /**
@@ -112,6 +140,49 @@ export interface ProviderConfig {
      * Mutually exclusive with `methods`.
      */
     exclude?: ProviderMethod[];
+    /**
+     * Only track these specific event names on this provider.
+     * If specified, all other events will be skipped.
+     * Mutually exclusive with `excludeEvents`.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   provider: new EmitKitServerProvider({...}),
+     *   events: ['newsletter_signup'] // Only this event goes to EmitKit
+     * }
+     * ```
+     */
+    events?: string[];
+    /**
+     * Skip these specific event names on this provider.
+     * All other events will be tracked normally.
+     * Mutually exclusive with `events` and `eventPatterns`.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   provider: new BentoClientProvider({...}),
+     *   excludeEvents: ['page_view'] // Everything except page views
+     * }
+     * ```
+     */
+    excludeEvents?: string[];
+    /**
+     * Glob-style patterns to match event names.
+     * Supports wildcards (*) for flexible event routing.
+     * Mutually exclusive with `excludeEvents`.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   provider: new EmitKitServerProvider({...}),
+     *   eventPatterns: ['newsletter_*', 'user_registered']
+     *   // Matches: newsletter_signup, newsletter_unsubscribe, user_registered
+     * }
+     * ```
+     */
+    eventPatterns?: string[];
 }
 /**
  * Provider configuration - supports both simple provider instances

package/dist/providers/emitkit/server.d.ts

@@ -10,9 +10,29 @@ export interface EmitKitServerConfig {
     apiKey: string;
     /**
      * Default channel name for events
-     * @default 'analytics'
+     * @default 'general'
      */
     channelName?: string;
+    /**
+     * Map event categories to specific EmitKit channels.
+     * Allows automatic routing of events to appropriate channels based on category.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   'user': 'user-activity',
+     *   'engagement': 'product-usage',
+     *   'error': 'alerts',
+     *   'conversion': 'revenue'
+     * }
+     * ```
+     *
+     * Channel resolution priority:
+     * 1. Event property `__emitkit_channel` (highest priority)
+     * 2. Category mapping via `categoryChannelMap`
+     * 3. Default `channelName` (fallback, default: 'general')
+     */
+    categoryChannelMap?: Record<string, string>;
     /**
      * Send notification for events
      * @default true
@@ -59,4 +79,11 @@ export declare class EmitKitServerProvider extends BaseAnalyticsProvider {
      * Get an appropriate icon for the event category
      */
     private getEventIcon;
+    /**
+     * Resolve the channel name for an event based on priority:
+     * 1. Event property __emitkit_channel (highest priority)
+     * 2. Category mapping via categoryChannelMap
+     * 3. Default channelName (fallback, default: 'general')
+     */
+    private resolveChannelName;
 }