@stacksee/analytics 0.4.5 → 0.5.0

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

@@ -8,7 +8,13 @@ export interface BaseEvent {
     sessionId?: string;
     properties?: Record<string, unknown>;
 }
-export interface EventContext {
+export interface UserContext<TTraits extends Record<string, unknown> = Record<string, unknown>> {
+    userId?: string;
+    email?: string;
+    traits?: TTraits;
+}
+export interface EventContext<TTraits extends Record<string, unknown> = Record<string, unknown>> {
+    user?: UserContext<TTraits>;
     page?: {
         path: string;
         title?: string;

package/dist/providers/client.js

@@ -1,5 +1,5 @@
 import { B as e } from "../base.provider-AfFL5W_P.js";
-import { P as t } from "../client-RZPcOfAk.js";
+import { P as t } from "../client-DTHZYkxx.js";
 export {
   e as BaseAnalyticsProvider,
   t as PostHogClientProvider

package/dist/providers/server.js

@@ -1,5 +1,5 @@
 import { B as e } from "../base.provider-AfFL5W_P.js";
-import { P as a } from "../server-CMRw9K0d.js";
+import { P as a } from "../server-DjEk1fUD.js";
 export {
   e as BaseAnalyticsProvider,
   a as PostHogServerProvider

package/dist/server-DjEk1fUD.js

@@ -0,0 +1,88 @@
+var p = Object.defineProperty;
+var u = (r, e, s) => e in r ? p(r, e, { enumerable: !0, configurable: !0, writable: !0, value: s }) : r[e] = s;
+var a = (r, e, s) => u(r, typeof e != "symbol" ? e + "" : e, s);
+import { B as g } from "./base.provider-AfFL5W_P.js";
+import { PostHog as n } from "posthog-node";
+class y extends g {
+  constructor(s) {
+    super({ debug: s.debug, enabled: s.enabled });
+    a(this, "name", "PostHog-Server");
+    a(this, "client");
+    a(this, "initialized", !1);
+    a(this, "config");
+    this.config = s;
+  }
+  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: s, ...i } = this.config;
+        this.client = new n(s, {
+          host: "https://app.posthog.com",
+          flushAt: 20,
+          flushInterval: 1e4,
+          ...i
+        }), this.initialized = !0, this.log("Initialized successfully", this.config);
+      } catch (s) {
+        throw console.error("[PostHog-Server] Failed to initialize:", s), s;
+      }
+    }
+  }
+  identify(s, i) {
+    !this.isEnabled() || !this.initialized || !this.client || (this.client.identify({
+      distinctId: s,
+      properties: i
+    }), this.log("Identified user", { userId: s, traits: i }));
+  }
+  track(s, i) {
+    var t, h, d;
+    if (!this.isEnabled() || !this.initialized || !this.client) return;
+    const l = {
+      ...s.properties,
+      category: s.category,
+      timestamp: s.timestamp ? new Date(s.timestamp) : /* @__PURE__ */ new Date(),
+      ...s.sessionId && { sessionId: s.sessionId },
+      ...(i == null ? void 0 : i.page) && {
+        $current_url: i.page.path,
+        $page_title: i.page.title,
+        $referrer: i.page.referrer
+      },
+      ...(i == null ? void 0 : i.device) && { device: i.device },
+      ...(i == null ? void 0 : i.utm) && { utm: i.utm },
+      // Include user email and traits as regular event properties
+      ...((t = i == null ? void 0 : i.user) == null ? void 0 : t.email) && { user_email: i.user.email },
+      ...((h = i == null ? void 0 : i.user) == null ? void 0 : h.traits) && { user_traits: i.user.traits }
+    };
+    this.client.capture({
+      distinctId: s.userId || ((d = i == null ? void 0 : i.user) == null ? void 0 : d.userId) || "anonymous",
+      event: s.action,
+      properties: l
+    }), this.log("Tracked event", { event: s, context: i });
+  }
+  pageView(s, i) {
+    if (!this.isEnabled() || !this.initialized || !this.client) return;
+    const l = {
+      ...s,
+      ...(i == null ? void 0 : i.page) && {
+        path: i.page.path,
+        title: i.page.title,
+        referrer: i.page.referrer
+      }
+    };
+    this.client.capture({
+      distinctId: "anonymous",
+      event: "$pageview",
+      properties: l
+    }), this.log("Tracked page view", { properties: s, context: i });
+  }
+  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 {
+  y as P
+};

package/dist/server.d.ts

@@ -34,5 +34,5 @@ export interface ServerAnalyticsConfig {
  * }, { userId: 'user-123' });
  * ```
  */
-export declare function createServerAnalytics<TEvents = never>(config: ServerAnalyticsConfig): ServerAnalytics<EventMapFromCollection<TEvents>>;
+export declare function createServerAnalytics<TEvents = never, TUserTraits extends Record<string, unknown> = Record<string, unknown>>(config: ServerAnalyticsConfig): ServerAnalytics<EventMapFromCollection<TEvents>, TUserTraits>;
 export { ServerAnalytics };

package/dist/server.js

@@ -1,9 +1,9 @@
-var l = Object.defineProperty;
-var f = (r, e, t) => e in r ? l(r, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : r[e] = t;
-var s = (r, e, t) => f(r, typeof e != "symbol" ? e + "" : e, t);
-import { P as m } from "./server-CMRw9K0d.js";
-import { B as x } from "./base.provider-AfFL5W_P.js";
-class u {
+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);
+import { P as w } from "./server-DjEk1fUD.js";
+import { B as z } from "./base.provider-AfFL5W_P.js";
+class v {
   /**
    * Creates a new ServerAnalytics instance for server-side event tracking.
    * 
@@ -129,28 +129,33 @@ class u {
    * }
    * ```
    */
-  identify(e, t) {
-    for (const i of this.providers)
-      i.identify(e, t);
+  identify(e, r) {
+    for (const t of this.providers)
+      t.identify(e, r);
   }
   /**
    * 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.
-   * 
+   *
+   * **User Context (New):** You can now pass user data (email, traits) with each event
+   * via `options.user` or `options.context.user`. This is useful for providers like
+   * Loops, Customer.io, or Intercom that require user identifiers.
+   *
    * @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 Optional configuration including user ID, session ID, user context, and additional 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
+   * @param options.user User context including email and traits (automatically included in event context)
+   * @param options.context Additional context for this event (page, device, etc.)
    * @returns Promise that resolves when tracking is complete for all providers
-   * 
+   *
    * @example
    * ```typescript
    * // Basic event tracking
@@ -161,10 +166,10 @@ class u {
    *   statusCode: 200
    * });
    * ```
-   * 
+   *
    * @example
    * ```typescript
-   * // Track with user context
+   * // Track with user context (recommended for email-based providers)
    * await analytics.track('purchase_completed', {
    *   orderId: 'order-123',
    *   amount: 99.99,
@@ -172,40 +177,68 @@ class u {
    *   itemCount: 3
    * }, {
    *   userId: 'user-456',
-   *   sessionId: 'session-789',
+   *   user: {
+   *     email: 'user@example.com',
+   *     traits: {
+   *       plan: 'pro',
+   *       company: 'Acme Corp'
+   *     }
+   *   },
    *   context: {
    *     page: { path: '/checkout/complete' },
-   *     device: { userAgent: req.headers['user-agent'] },
-   *     ip: req.ip
+   *     device: { userAgent: req.headers['user-agent'] }
    *   }
    * });
+   * // Providers receive: context.user = { email: 'user@example.com', traits: {...} }
    * ```
-   * 
+   *
+   * @example
+   * ```typescript
+   * // Alternative: Pass user via context.user
+   * await analytics.track('feature_used', {
+   *   featureName: 'export'
+   * }, {
+   *   userId: 'user-123',
+   *   context: {
+   *     user: {
+   *       email: 'user@example.com'
+   *     },
+   *     page: { path: '/dashboard' }
+   *   }
+   * });
+   * ```
+   *
    * @example
    * ```typescript
-   * // In an Express.js route handler
+   * // In an Express.js route handler with user data
    * app.post('/api/users', async (req, res) => {
    *   const user = await createUser(req.body);
-   *   
-   *   // Track user creation with server context
+   *
+   *   // Track user creation with full user context
    *   await analytics.track('user_created', {
    *     userId: user.id,
    *     email: user.email,
    *     plan: user.plan
    *   }, {
    *     userId: user.id,
+   *     user: {
+   *       email: user.email,
+   *       traits: {
+   *         name: user.name,
+   *         plan: user.plan,
+   *         company: user.company
+   *       }
+   *     },
    *     context: {
    *       page: { path: req.path },
-   *       device: { userAgent: req.headers['user-agent'] },
-   *       ip: req.ip,
-   *       server: { version: process.env.APP_VERSION }
+   *       device: { userAgent: req.headers['user-agent'] }
    *     }
    *   });
-   *   
+   *
    *   res.json(user);
    * });
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // Error handling in tracking
@@ -221,7 +254,8 @@ class u {
    * }
    * ```
    */
-  async track(e, t, i) {
+  async track(e, r, t) {
+    var n;
     if (!this.initialized) {
       console.warn("[Analytics] Not initialized. Call initialize() first.");
       return;
@@ -229,24 +263,25 @@ class u {
     const a = {
       action: e,
       category: this.getCategoryFromEventName(e),
-      properties: t,
+      properties: r,
       timestamp: Date.now(),
-      userId: i == null ? void 0 : i.userId,
-      sessionId: i == null ? void 0 : i.sessionId
-    }, c = {
+      userId: t == null ? void 0 : t.userId,
+      sessionId: t == null ? void 0 : t.sessionId
+    }, d = {
       ...this.config.defaultContext,
-      ...i == null ? void 0 : i.context
-    }, o = this.providers.map(async (n) => {
+      ...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) => {
       try {
-        await n.track(a, c);
-      } catch (d) {
+        await c.track(a, d);
+      } catch (f) {
         console.error(
-          `[Analytics] Provider ${n.name} failed to track event:`,
-          d
+          `[Analytics] Provider ${c.name} failed to track event:`,
+          f
         );
       }
     });
-    await Promise.all(o);
+    await Promise.all(l);
   }
   /**
    * Tracks a page view event from the server side.
@@ -308,14 +343,14 @@ class u {
    * }
    * ```
    */
-  pageView(e, t) {
+  pageView(e, r) {
     if (!this.initialized) return;
-    const i = {
+    const t = {
       ...this.config.defaultContext,
-      ...t == null ? void 0 : t.context
+      ...r == null ? void 0 : r.context
     };
     for (const a of this.providers)
-      a.pageView(e, i);
+      a.pageView(e, t);
   }
   /**
    * Tracks when a user leaves a page from the server side.
@@ -376,14 +411,14 @@ class u {
    * }
    * ```
    */
-  pageLeave(e, t) {
+  pageLeave(e, r) {
     if (!this.initialized) return;
-    const i = {
+    const t = {
       ...this.config.defaultContext,
-      ...t == null ? void 0 : t.context
+      ...r == null ? void 0 : r.context
     };
     for (const a of this.providers)
-      a.pageLeave && a.pageLeave(e, i);
+      a.pageLeave && a.pageLeave(e, t);
   }
   /**
    * Shuts down all analytics providers and flushes pending events.
@@ -470,27 +505,25 @@ class u {
    * ```
    */
   async shutdown() {
-    const e = this.providers.map((t) => "shutdown" in t && typeof t.shutdown == "function" ? t.shutdown() : Promise.resolve());
+    const e = this.providers.map((r) => "shutdown" in r && typeof r.shutdown == "function" ? r.shutdown() : Promise.resolve());
     await Promise.all(e);
   }
   getCategoryFromEventName(e) {
-    const t = e.split("_");
-    return t.length > 1 && t[0] ? t[0] : "engagement";
+    const r = e.split("_");
+    return r.length > 1 && r[0] ? r[0] : "engagement";
   }
 }
-function h(r) {
+function g(i) {
   const e = {
-    providers: r.providers || [],
-    debug: r.debug,
-    enabled: r.enabled
-  }, t = new u(
-    e
-  );
-  return t.initialize(), t;
+    providers: i.providers || [],
+    debug: i.debug,
+    enabled: i.enabled
+  }, r = new v(e);
+  return r.initialize(), r;
 }
 export {
-  x as BaseAnalyticsProvider,
-  m as PostHogServerProvider,
-  u as ServerAnalytics,
-  h as createServerAnalytics
+  z as BaseAnalyticsProvider,
+  w as PostHogServerProvider,
+  v as ServerAnalytics,
+  g as createServerAnalytics
 };

package/package.json

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