@stacksee/analytics 0.4.6 → 0.7.0

package/readme.md

@@ -1,10 +1,11 @@
 # @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
 
 - [Features](#features)
+- [Providers](#providers)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
   - [1. Define Your Events](#1-define-your-events)
@@ -39,11 +40,40 @@ 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
 
+## Providers
+
+The library includes built-in support for popular analytics services, with more coming soon:
+
+### Official Providers
+
+| Provider | Type | Documentation |
+|----------|------|---------------|
+| **PostHog** | Product Analytics | [docs/providers/posthog.md](./docs/providers/posthog.md) |
+| **Bento** | Email Marketing & Events | [docs/providers/bento.md](./docs/providers/bento.md) |
+| **Pirsch** | Privacy-Focused Web Analytics | [docs/providers/pirsch.md](./docs/providers/pirsch.md) |
+
+### Community & Custom Providers
+
+Want to use a different analytics service? Check out our guide:
+
+**[Creating Custom Providers →](./docs/providers/custom-providers.md)**
+
+You can easily create providers for:
+- Google Analytics
+- Mixpanel
+- Amplitude
+- Segment
+- Customer.io
+- Loops
+- Any analytics service with a JavaScript SDK
+
+**[View all provider documentation →](./docs/providers/)**
+
 ## Installation
 
 ```bash
@@ -51,8 +81,16 @@ pnpm install @stacksee/analytics
 
 # For PostHog support
 pnpm install posthog-js posthog-node
+
+# For Bento support (server-side only)
+pnpm install @bentonow/bento-node-sdk
+
+# For Pirsch support
+pnpm install pirsch-sdk
 ```
 
+> **See also:** [Provider Documentation](./docs/providers/) for detailed setup guides for each provider.
+
 ## Quick Start
 
 ### 1. Define Your Events
@@ -126,12 +164,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 +200,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:
@@ -521,32 +743,21 @@ export const appEvents = {
 
 ### Adding Custom Providers
 
-Implement the `AnalyticsProvider` interface to add support for other analytics services:
+Want to integrate with a different analytics service? See our comprehensive guide:
+
+**[Creating Custom Providers →](./docs/providers/custom-providers.md)**
+
+Quick example:
 
 ```typescript
 import { BaseAnalyticsProvider, BaseEvent, EventContext } from '@stacksee/analytics';
 
 export class GoogleAnalyticsProvider extends BaseAnalyticsProvider {
   name = 'GoogleAnalytics';
-  private measurementId: string;
-
-  constructor(config: { measurementId: string; debug?: boolean; enabled?: boolean }) {
-    super({ debug: config.debug, enabled: config.enabled });
-    this.measurementId = config.measurementId;
-  }
-
-  async initialize(): Promise<void> {
-    // Initialize GA
-  }
-
-  track(event: BaseEvent, context?: EventContext): void {
-    // Send event to GA
-  }
-
-  identify(userId: string, traits?: Record<string, unknown>): void {
-    // Set user properties in GA
-  }
 
+  async initialize(): Promise<void> { /* Initialize GA */ }
+  track(event: BaseEvent, context?: EventContext): void { /* Track event */ }
+  identify(userId: string, traits?: Record<string, unknown>): void { /* Identify user */ }
   // ... implement other required methods
 }
 ```
@@ -554,9 +765,9 @@ export class GoogleAnalyticsProvider extends BaseAnalyticsProvider {
 Then use it as a plugin in your configuration:
 
 ```typescript
-const analytics = await createClientAnalytics<typeof AppEvents>({
+const analytics = createClientAnalytics<typeof AppEvents>({
   providers: [
-    new PostHogClientProvider({ apiKey: 'xxx' }),
+    new PostHogClientProvider({ token: 'xxx' }),
     new GoogleAnalyticsProvider({ measurementId: 'xxx' })
   ]
 });
@@ -567,7 +778,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 +1010,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 +1036,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

package/dist/client-RZPcOfAk.js

@@ -1,86 +0,0 @@
-var h = Object.defineProperty;
-var p = (a, s, e) => s in a ? h(a, s, { enumerable: !0, configurable: !0, writable: !0, value: e }) : a[s] = e;
-var t = (a, s, e) => p(a, typeof s != "symbol" ? s + "" : s, e);
-import { B as d } from "./base.provider-AfFL5W_P.js";
-function o() {
-  return typeof window < "u" && typeof window.document < "u";
-}
-class u extends d {
-  constructor(e) {
-    super({ debug: e.debug, enabled: e.enabled });
-    t(this, "name", "PostHog-Client");
-    t(this, "posthog");
-    t(this, "initialized", !1);
-    t(this, "config");
-    this.config = e;
-  }
-  async initialize() {
-    if (this.isEnabled() && !this.initialized) {
-      if (!o()) {
-        this.log("Skipping initialization - not in browser environment");
-        return;
-      }
-      if (!this.config.token || typeof this.config.token != "string")
-        throw new Error("PostHog requires a token");
-      try {
-        const { default: e } = await import("posthog-js"), { token: i, debug: r, ...g } = this.config;
-        e.init(i, {
-          ...g,
-          debug: r ?? this.debug
-        }), this.posthog = e, this.initialized = !0, this.log("Initialized successfully", this.config);
-      } catch (e) {
-        throw console.error("[PostHog-Client] Failed to initialize:", e), e;
-      }
-    }
-  }
-  identify(e, i) {
-    !this.isEnabled() || !this.initialized || !this.posthog || (this.posthog.identify(e, i), this.log("Identified user", { userId: e, traits: i }));
-  }
-  track(e, i) {
-    if (!this.isEnabled() || !this.initialized || !this.posthog) return;
-    const r = {
-      ...e.properties,
-      category: e.category,
-      timestamp: e.timestamp || Date.now(),
-      ...e.userId && { userId: e.userId },
-      ...e.sessionId && { sessionId: e.sessionId },
-      ...(i == null ? void 0 : i.page) && { $current_url: i.page.path },
-      ...(i == null ? void 0 : i.device) && { device: i.device },
-      ...(i == null ? void 0 : i.utm) && { utm: i.utm }
-    };
-    this.posthog.capture(e.action, r), this.log("Tracked event", { event: e, context: i });
-  }
-  pageView(e, i) {
-    if (!this.isEnabled() || !this.initialized || !this.posthog || !o())
-      return;
-    const r = {
-      ...e,
-      ...(i == null ? void 0 : i.page) && {
-        path: i.page.path,
-        title: i.page.title,
-        referrer: i.page.referrer
-      }
-    };
-    this.posthog.capture("$pageview", r), this.log("Tracked page view", { properties: e, context: i });
-  }
-  pageLeave(e, i) {
-    if (!this.isEnabled() || !this.initialized || !this.posthog || !o())
-      return;
-    const r = {
-      ...e,
-      ...(i == null ? void 0 : i.page) && {
-        path: i.page.path,
-        title: i.page.title,
-        referrer: i.page.referrer
-      }
-    };
-    this.posthog.capture("$pageleave", r), this.log("Tracked page leave", { properties: e, context: i });
-  }
-  reset() {
-    !this.isEnabled() || !this.initialized || !this.posthog || !o() || (this.posthog.reset(), this.log("Reset user session"));
-  }
-}
-export {
-  u as P,
-  o as i
-};

package/dist/server-CMRw9K0d.js

@@ -1,84 +0,0 @@
-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 "./base.provider-AfFL5W_P.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 {
-  u as P
-};