@stacksee/analytics 0.4.6 → 0.5.0

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

package/readme.md

@@ -1,6 +1,6 @@
 # @stacksee/analytics
 
-A highly typed, provider-agnostic analytics library for TypeScript applications. Works seamlessly on both client and server sides with full type safety for your custom events.
+A highly typed, zero-dependency, provider-agnostic analytics library for TypeScript applications. Works seamlessly on both client and server sides with full type safety for your custom events.
 
 ## Table of Contents
 
@@ -39,9 +39,9 @@ A highly typed, provider-agnostic analytics library for TypeScript applications.
 - 🎯 **Type-safe events**: Define your own strongly typed events with full IntelliSense support
 - 🔌 **Plugin architecture**: Easily add analytics providers by passing them as plugins
 - 🌐 **Universal**: Same API works on both client (browser) and server (Node.js)
-- 📦 **Lightweight**: Zero dependencies on the core library
-- 🏗️ **Framework agnostic**: Use with any JavaScript framework
-- 🌎 **Edge ready**: The server client is compatible with edge runtime (e.g. Cloudflare Workers)
+- 👤 **User context**: Automatically attach user data (email, traits) to all events
+- 🏗️ **Framework agnostic**: Use with any JavaScript framework. Can also be used only on the client.
+- 🌎 **Edge ready**: The server client is compatible with edge runtime (e.g. Cloudflare Workers, Vercel Edge functions)
 - 🔧 **Extensible**: Simple interface to add new providers
 
 ## Installation
@@ -126,12 +126,19 @@ analytics.track('user_signed_up', {
 // analytics.track('wrong_event', {}); // ❌ Error: Argument of type '"wrong_event"' is not assignable
 // analytics.track('user_signed_up', { wrongProp: 'value' }); // ❌ Error: Object literal may only specify known properties
 
-// Identify users
+// Identify users - user context is automatically included in all subsequent events
 analytics.identify('user-123', {
   email: 'user@example.com',
   name: 'John Doe',
   plan: 'pro'
 });
+
+// Now all tracked events automatically include user context
+analytics.track('feature_used', {
+  featureName: 'export-data',
+  userId: 'user-123'
+});
+// Providers receive: context.user = { userId: 'user-123', email: 'user@example.com', traits: {...} }
 ```
 
 ### 3. Server-Side Usage
@@ -155,24 +162,201 @@ const analytics = createServerAnalytics<AppEvents>({
   enabled: true
 });
 
-// Track events - now returns a Promise with full type safety
+// Track events with user context - now returns a Promise with full type safety
 await analytics.track('feature_used', {
   featureName: 'export-data',
   userId: 'user-123',
   duration: 1500
 }, {
   userId: 'user-123',
+  user: {
+    email: 'user@example.com',
+    traits: {
+      plan: 'pro',
+      company: 'Acme Corp'
+    }
+  },
   context: {
     page: {
       path: '/api/export',
     }
   }
 });
+// Providers receive: context.user = { userId: 'user-123', email: 'user@example.com', traits: {...} }
 
 // Important: Always call shutdown when done, some providers such as Posthog require flushing events.
 await analytics.shutdown();
 ```
 
+## User Context
+
+The library automatically manages user context, making it easy to include user data (email, traits) in all your analytics events. This is especially useful for providers like Loops or Intercom that require user identifiers.
+
+### How It Works
+
+**Client-Side (Stateful):**
+```typescript
+// 1. Identify the user once (typically after login)
+analytics.identify('user-123', {
+  email: 'user@example.com',
+  name: 'John Doe',
+  plan: 'pro',
+  company: 'Acme Corp'
+});
+
+// 2. Track events - user context is automatically included
+analytics.track('button_clicked', { buttonId: 'checkout' });
+
+// Behind the scenes, providers receive:
+// {
+//   event: { action: 'button_clicked', ... },
+//   context: {
+//     user: {
+//       userId: 'user-123',
+//       email: 'user@example.com',
+//       traits: { email: '...', name: '...', plan: '...', company: '...' }
+//     }
+//   }
+// }
+
+// 3. Reset on logout to clear user context
+analytics.reset();
+```
+
+**Server-Side (Stateless):**
+```typescript
+// Pass user context with each track call
+await analytics.track('api_request', {
+  endpoint: '/users',
+  method: 'POST'
+}, {
+  userId: 'user-123',
+  user: {
+    email: 'user@example.com',
+    traits: {
+      plan: 'pro',
+      company: 'Acme Corp'
+    }
+  }
+});
+
+// Alternatively, pass via context.user
+await analytics.track('api_request', { ... }, {
+  userId: 'user-123',
+  context: {
+    user: {
+      email: 'user@example.com'
+    }
+  }
+});
+```
+
+### Using User Context in Custom Providers
+
+When building custom providers, you can access user context from the `EventContext`:
+
+```typescript
+export class LoopsProvider extends BaseAnalyticsProvider {
+  name = 'Loops';
+
+  async track(event: BaseEvent, context?: EventContext): Promise<void> {
+    // Access user data from context
+    const email = context?.user?.email;
+    const userId = context?.user?.userId;
+    const traits = context?.user?.traits;
+
+    // Loops requires either email or userId
+    if (!email && !userId) {
+      this.log('Skipping event - Loops requires email or userId');
+      return;
+    }
+
+    await this.loops.sendEvent({
+      ...(email && { email }),
+      ...(userId && { userId }),
+      eventName: event.action,
+      eventProperties: event.properties,
+      // Optionally include all user traits
+      contactProperties: traits,
+    });
+  }
+}
+```
+
+### Security & Privacy
+
+User context is handled securely:
+
+- ✅ **Memory-only storage** - No localStorage, cookies, or persistence
+- ✅ **Session-scoped** - Cleared on `reset()` (logout)
+- ✅ **Provider-controlled** - Only sent to providers you configure
+- ✅ **No cross-session leaks** - Fresh state on each page load
+
+### Type-Safe User Traits
+
+You can define a custom interface for your user traits to get full type safety:
+
+```typescript
+// Define your user traits interface
+interface UserTraits {
+  email: string;
+  name: string;
+  plan: 'free' | 'pro' | 'enterprise';
+  company?: string;
+  role?: 'admin' | 'user' | 'viewer';
+}
+
+// Client-side with typed traits
+const analytics = createClientAnalytics<typeof AppEvents, UserTraits>({
+  providers: [/* ... */]
+});
+
+// Now identify() and traits are fully typed!
+analytics.identify('user-123', {
+  email: 'user@example.com',
+  name: 'John Doe',
+  plan: 'pro',  // ✅ Autocomplete works!
+  company: 'Acme Corp',
+  role: 'admin'
+});
+
+// TypeScript will error on invalid trait values
+analytics.identify('user-123', {
+  plan: 'invalid'  // ❌ Error: Type '"invalid"' is not assignable to type 'free' | 'pro' | 'enterprise'
+});
+
+// Server-side with typed traits
+const serverAnalytics = createServerAnalytics<typeof AppEvents, UserTraits>({
+  providers: [/* ... */]
+});
+
+await serverAnalytics.track('event', {}, {
+  user: {
+    email: 'user@example.com',
+    plan: 'pro',  // ✅ Fully typed!
+    traits: {
+      company: 'Acme Corp'
+    }
+  }
+});
+```
+
+**Benefits:**
+- ✅ Full IntelliSense/autocomplete for user traits
+- ✅ Compile-time type checking prevents typos
+- ✅ Self-documenting code
+- ✅ Refactoring safety
+
+### Client vs Server Differences
+
+| Feature | Client (Browser) | Server (Node.js) |
+|---------|------------------|------------------|
+| **State Management** | Stateful - persists after `identify()` | Stateless - pass per request |
+| **Usage Pattern** | Call `identify()` once, track many times | Pass `user` option with each `track()` |
+| **Reset** | Call `reset()` on logout | No reset needed (stateless) |
+| **Use Case** | Single user per session | Multiple users per instance |
+| **Type Safety** | `createClientAnalytics<Events, Traits>` | `createServerAnalytics<Events, Traits>` |
+
 ### Async Tracking: When to await vs fire-and-forget
 
 The `track()` method now returns a `Promise<void>`, giving you control over how to handle event tracking:
@@ -567,7 +751,7 @@ const analytics = await createClientAnalytics<typeof AppEvents>({
 **Important**: To avoid bundling Node.js dependencies in your client code, always use the environment-specific provider imports:
 
 - **Client-side**: `@stacksee/analytics/providers/client` - Only includes browser-compatible providers
-- **Server-side**: `@stacksee/analytics/providers/server` - Only includes Node.js providers  
+- **Server-side**: `@stacksee/analytics/providers/server` - Only includes Node.js providers
 - **Both**: `@stacksee/analytics/providers` - Includes all providers (may cause bundling issues in browsers)
 
 Some analytics libraries are designed to work only in specific environments. For example:
@@ -799,11 +983,11 @@ const analytics = createClientAnalytics<typeof AppEvents>({
 ```
 
 #### `BrowserAnalytics<TEventMap>`
-- `track(eventName, properties): Promise<void>` - Track an event with type-safe event names and properties
-- `identify(userId, traits)` - Identify a user
+- `track(eventName, properties): Promise<void>` - Track an event with type-safe event names and properties. User context from `identify()` is automatically included.
+- `identify(userId, traits)` - Identify a user and store their traits. All subsequent `track()` calls will include this user context.
 - `pageView(properties)` - Track a page view
 - `pageLeave(properties)` - Track a page leave event
-- `reset()` - Reset user session
+- `reset()` - Reset user session, clearing userId and user traits
 - `updateContext(context)` - Update event context
 
 ### Server API
@@ -825,8 +1009,12 @@ const analytics = createServerAnalytics<AppEvents>({
 ```
 
 #### `ServerAnalytics<TEventMap>`
-- `track(eventName, properties, options): Promise<void>` - Track an event with type-safe event names and properties
-- `identify(userId, traits)` - Identify a user
+- `track(eventName, properties, options): Promise<void>` - Track an event with type-safe event names and properties. Pass user context via `options.user` or `options.context.user`.
+  - `options.userId` - User ID for this event
+  - `options.sessionId` - Session ID for this event
+  - `options.user` - User context (email, traits) for this event
+  - `options.context` - Additional event context (page, device, etc.)
+- `identify(userId, traits)` - Identify a user (sends to providers but doesn't persist on server)
 - `pageView(properties, options)` - Track a page view
 - `pageLeave(properties, options)` - Track a page leave event
 - `shutdown()` - Flush pending events and cleanup