@stacksee/analytics 0.9.7 → 0.10.0

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.7",
+  "version": "0.10.0",
   "description": "A highly typed, provider-agnostic analytics library for TypeScript applications",
   "type": "module",
   "exports": {