@stacksee/analytics 0.4.2 → 0.4.3

package/dist/providers.js

@@ -1,6 +1,87 @@
-import { B as e, P as s, a } from "./server-BKqARaUf.js";
+var l = Object.defineProperty;
+var h = (r, s, i) => s in r ? l(r, s, { enumerable: !0, configurable: !0, writable: !0, value: i }) : r[s] = i;
+var t = (r, s, i) => h(r, typeof s != "symbol" ? s + "" : s, i);
+import { B as n } from "./client-MwIAm9fk.js";
+import { P as m } from "./client-MwIAm9fk.js";
+import { PostHog as p } from "posthog-node";
+class u extends n {
+  constructor(i) {
+    super({ debug: i.debug, enabled: i.enabled });
+    t(this, "name", "PostHog-Server");
+    t(this, "client");
+    t(this, "initialized", !1);
+    t(this, "config");
+    this.config = i;
+  }
+  initialize() {
+    if (this.isEnabled() && !this.initialized) {
+      if (!this.config.apiKey || typeof this.config.apiKey != "string")
+        throw new Error("PostHog requires an apiKey");
+      try {
+        const { apiKey: i, ...e } = this.config;
+        this.client = new p(i, {
+          host: "https://app.posthog.com",
+          flushAt: 20,
+          flushInterval: 1e4,
+          ...e
+        }), this.initialized = !0, this.log("Initialized successfully", this.config);
+      } catch (i) {
+        throw console.error("[PostHog-Server] Failed to initialize:", i), i;
+      }
+    }
+  }
+  identify(i, e) {
+    !this.isEnabled() || !this.initialized || !this.client || (this.client.identify({
+      distinctId: i,
+      properties: e
+    }), this.log("Identified user", { userId: i, traits: e }));
+  }
+  track(i, e) {
+    if (!this.isEnabled() || !this.initialized || !this.client) return;
+    const a = {
+      ...i.properties,
+      category: i.category,
+      timestamp: i.timestamp ? new Date(i.timestamp) : /* @__PURE__ */ new Date(),
+      ...i.sessionId && { sessionId: i.sessionId },
+      ...(e == null ? void 0 : e.page) && {
+        $current_url: e.page.path,
+        $page_title: e.page.title,
+        $referrer: e.page.referrer
+      },
+      ...(e == null ? void 0 : e.device) && { device: e.device },
+      ...(e == null ? void 0 : e.utm) && { utm: e.utm }
+    };
+    this.client.capture({
+      distinctId: i.userId || "anonymous",
+      event: i.action,
+      properties: a
+    }), this.log("Tracked event", { event: i, context: e });
+  }
+  pageView(i, e) {
+    if (!this.isEnabled() || !this.initialized || !this.client) return;
+    const a = {
+      ...i,
+      ...(e == null ? void 0 : e.page) && {
+        path: e.page.path,
+        title: e.page.title,
+        referrer: e.page.referrer
+      }
+    };
+    this.client.capture({
+      distinctId: "anonymous",
+      event: "$pageview",
+      properties: a
+    }), this.log("Tracked page view", { properties: i, context: e });
+  }
+  async reset() {
+    !this.isEnabled() || !this.initialized || !this.client || (await this.client.flush(), this.log("Flushed pending events"));
+  }
+  async shutdown() {
+    this.client && (await this.client.shutdown(), this.log("Shutdown complete"));
+  }
+}
 export {
-  e as BaseAnalyticsProvider,
-  s as PostHogClientProvider,
-  a as PostHogServerProvider
+  n as BaseAnalyticsProvider,
+  m as PostHogClientProvider,
+  u as PostHogServerProvider
 };

package/dist/server.js

@@ -2,12 +2,78 @@ var o = Object.defineProperty;
 var f = (r, e, t) => e in r ? o(r, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : r[e] = t;
 var n = (r, e, t) => f(r, typeof e != "symbol" ? e + "" : e, t);
 class u {
+  /**
+   * 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({
+   *       apiKey: process.env.POSTHOG_API_KEY,
+   *       host: process.env.POSTHOG_HOST
+   *     })
+   *   ],
+   *   defaultContext: {
+   *     app: { version: '1.0.0', environment: 'production' }
+   *   }
+   * });
+   * 
+   * analytics.initialize();
+   * ```
+   */
   constructor(e) {
     n(this, "providers", []);
     n(this, "config");
     n(this, "initialized", !1);
     this.config = e, this.providers = e.providers;
   }
+  /**
+   * 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)
@@ -15,10 +81,144 @@ class u {
       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
+   * analytics.identify('user-123', {
+   *   email: 'john@example.com',
+   *   name: 'John Doe',
+   *   plan: 'enterprise',
+   *   company: 'Acme Corp',
+   *   createdAt: '2024-01-15T10:00:00Z',
+   *   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, t) {
     for (const i of this.providers)
       i.identify(e, t);
   }
+  /**
+   * Tracks a custom event with properties and optional context.
+   * 
+   * This is the main method for tracking business events on the server side.
+   * The method sends the event to all configured providers and waits for completion.
+   * Failed providers don't prevent others from succeeding.
+   * 
+   * Server-side tracking typically includes additional context like IP addresses,
+   * user agents, and server-specific metadata that isn't available on the client.
+   * 
+   * @param eventName Name of the event to track (must match your event definitions)
+   * @param properties Event-specific properties and data
+   * @param options Optional configuration including user ID, session ID, and context
+   * @param options.userId User ID to associate with this event
+   * @param options.sessionId Session ID to associate with this event
+   * @param options.context Additional context for this event
+   * @returns Promise that resolves when tracking is complete for all providers
+   * 
+   * @example
+   * ```typescript
+   * // Basic event tracking
+   * await analytics.track('api_request', {
+   *   endpoint: '/api/users',
+   *   method: 'GET',
+   *   responseTime: 150,
+   *   statusCode: 200
+   * });
+   * ```
+   * 
+   * @example
+   * ```typescript
+   * // Track with user context
+   * await analytics.track('purchase_completed', {
+   *   orderId: 'order-123',
+   *   amount: 99.99,
+   *   currency: 'USD',
+   *   itemCount: 3
+   * }, {
+   *   userId: 'user-456',
+   *   sessionId: 'session-789',
+   *   context: {
+   *     page: { path: '/checkout/complete' },
+   *     device: { userAgent: req.headers['user-agent'] },
+   *     ip: req.ip
+   *   }
+   * });
+   * ```
+   * 
+   * @example
+   * ```typescript
+   * // In an Express.js route handler
+   * app.post('/api/users', async (req, res) => {
+   *   const user = await createUser(req.body);
+   *   
+   *   // Track user creation with server context
+   *   await analytics.track('user_created', {
+   *     userId: user.id,
+   *     email: user.email,
+   *     plan: user.plan
+   *   }, {
+   *     userId: user.id,
+   *     context: {
+   *       page: { path: req.path },
+   *       device: { userAgent: req.headers['user-agent'] },
+   *       ip: req.ip,
+   *       server: { version: process.env.APP_VERSION }
+   *     }
+   *   });
+   *   
+   *   res.json(user);
+   * });
+   * ```
+   * 
+   * @example
+   * ```typescript
+   * // Error handling in tracking
+   * try {
+   *   await analytics.track('payment_processed', {
+   *     amount: 100,
+   *     currency: 'USD'
+   *   });
+   * } catch (error) {
+   *   // This only catches initialization errors
+   *   // Individual provider failures are logged but don't throw
+   *   console.error('Failed to track event:', error);
+   * }
+   * ```
+   */
   async track(e, t, i) {
     if (!this.initialized) {
       console.warn("[Analytics] Not initialized. Call initialize() first.");
@@ -46,6 +246,66 @@ class u {
     });
     await Promise.all(d);
   }
+  /**
+   * 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
+   * analytics.pageView({
+   *   loadTime: 250,
+   *   template: 'product-detail',
+   *   ssr: true
+   * }, {
+   *   context: {
+   *     page: {
+   *       path: '/products/widget-123',
+   *       title: 'Amazing Widget - Product Details'
+   *     },
+   *     device: {
+   *       userAgent: req.headers['user-agent']
+   *     },
+   *     server: {
+   *       renderTime: 45,
+   *       cacheHit: false
+   *     }
+   *   }
+   * });
+   * ```
+   * 
+   * @example
+   * ```typescript
+   * // In a Next.js API route or middleware
+   * export async function middleware(req) {
+   *   if (req.nextUrl.pathname.startsWith('/product/')) {
+   *     analytics.pageView({
+   *       category: 'product',
+   *       productId: req.nextUrl.pathname.split('/').pop()
+   *     }, {
+   *       context: {
+   *         page: { path: req.nextUrl.pathname },
+   *         device: { userAgent: req.headers.get('user-agent') },
+   *         referrer: req.headers.get('referer')
+   *       }
+   *     });
+   *   }
+   * }
+   * ```
+   */
   pageView(e, t) {
     if (!this.initialized) return;
     const i = {
@@ -55,6 +315,65 @@ class u {
     for (const a of this.providers)
       a.pageView(e, 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
+   * analytics.pageLeave({
+   *   sessionDuration: 45000, // 45 seconds
+   *   pagesViewed: 3,
+   *   exitReason: 'session_timeout'
+   * }, {
+   *   context: {
+   *     session: {
+   *       id: 'session-123',
+   *       startTime: sessionStartTime,
+   *       endTime: Date.now()
+   *     },
+   *     server: {
+   *       reason: 'inactivity_timeout'
+   *     }
+   *   }
+   * });
+   * ```
+   * 
+   * @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, t) {
     if (!this.initialized) return;
     const i = {
@@ -64,6 +383,90 @@ class u {
     for (const a of this.providers)
       a.pageLeave && a.pageLeave(e, 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,
+   *       success: true
+   *     });
+   *   } catch (error) {
+   *     await analytics.track('function_failed', {
+   *       error: error.message,
+   *       duration: Date.now() - startTime
+   *     });
+   *   } finally {
+   *     // 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();
+   *     process.exit(0);
+   *   });
+   * });
+   * ```
+   * 
+   * @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((t) => "shutdown" in t && typeof t.shutdown == "function" ? t.shutdown() : Promise.resolve());
     await Promise.all(e);