@stacksee/analytics 0.4.6 → 0.7.0

package/dist/_commonjsHelpers-B4e78b8K.js

@@ -0,0 +1,28 @@
+var u = typeof globalThis < "u" ? globalThis : typeof window < "u" ? window : typeof global < "u" ? global : typeof self < "u" ? self : {};
+function f(e) {
+  return e && e.__esModule && Object.prototype.hasOwnProperty.call(e, "default") ? e.default : e;
+}
+function l(e) {
+  if (Object.prototype.hasOwnProperty.call(e, "__esModule")) return e;
+  var r = e.default;
+  if (typeof r == "function") {
+    var t = function o() {
+      return this instanceof o ? Reflect.construct(r, arguments, this.constructor) : r.apply(this, arguments);
+    };
+    t.prototype = r.prototype;
+  } else t = {};
+  return Object.defineProperty(t, "__esModule", { value: !0 }), Object.keys(e).forEach(function(o) {
+    var n = Object.getOwnPropertyDescriptor(e, o);
+    Object.defineProperty(t, o, n.get ? n : {
+      enumerable: !0,
+      get: function() {
+        return e[o];
+      }
+    });
+  }), t;
+}
+export {
+  l as a,
+  u as c,
+  f as g
+};

package/dist/adapters/client/browser-analytics.d.ts

@@ -1,10 +1,11 @@
 import { AnalyticsConfig, EventContext } from '../../core/events/types.js';
 type DefaultEventMap = Record<string, Record<string, unknown>>;
-export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = DefaultEventMap> {
+export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = DefaultEventMap, TUserTraits extends Record<string, unknown> = Record<string, unknown>> {
     private providers;
     private context;
     private userId?;
     private sessionId?;
+    private userTraits?;
     private initialized;
     private initializePromise?;
     /**
@@ -78,11 +79,16 @@ export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = Defaul
      * sets user properties. This method should be called when a user logs in
      * or when you want to associate events with a known user.
      *
+     * **User Context (New):** User data (userId, email, traits) is automatically stored
+     * and included in all subsequent `track()` calls. This makes it easy for providers
+     * like Loops, Customer.io, or Intercom to access user information without passing
+     * it manually each time. The data is cleared when `reset()` is called (e.g., on logout).
+     *
      * The method automatically ensures initialization but doesn't block execution
      * if initialization is still in progress.
      *
      * @param userId Unique identifier for the user (e.g., database ID, email)
-     * @param traits Optional user properties and characteristics
+     * @param traits Optional user properties and characteristics (email, name, plan, etc.)
      *
      * @example
      * ```typescript
@@ -92,7 +98,7 @@ export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = Defaul
      *
      * @example
      * ```typescript
-     * // Identify with user traits
+     * // Identify with user traits (recommended - enables email-based providers)
      * analytics.identify('user-123', {
      *   email: 'john@example.com',
      *   name: 'John Doe',
@@ -103,6 +109,10 @@ export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = Defaul
      *     notifications: false
      *   }
      * });
+     *
+     * // Now all subsequent track() calls automatically include user context
+     * analytics.track('button_clicked', { buttonId: 'checkout' });
+     * // Providers receive: context.user = { userId: 'user-123', email: 'john@example.com', traits: {...} }
      * ```
      *
      * @example
@@ -111,15 +121,25 @@ export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = Defaul
      * async function handleLogin(email: string, password: string) {
      *   const user = await login(email, password);
      *
+     *   // Identify user with full traits
      *   analytics.identify(user.id, {
      *     email: user.email,
      *     name: user.name,
+     *     plan: user.plan,
+     *     company: user.company,
      *     lastLogin: new Date().toISOString()
      *   });
+     *
+     *   // All subsequent events now include this user context automatically
+     * }
+     *
+     * // In a logout handler - clear user context
+     * async function handleLogout() {
+     *   analytics.reset(); // Clears userId and traits
      * }
      * ```
      */
-    identify(userId: string, traits?: Record<string, unknown>): void;
+    identify(userId: string, traits?: TUserTraits): void;
     /**
      * Tracks a custom event with properties.
      *
@@ -128,6 +148,10 @@ export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = Defaul
      * configured providers. Events are enriched with context information like
      * timestamp, user ID, session ID, and browser context.
      *
+     * **User Context (New):** If `identify()` was called previously, user data (userId,
+     * email, traits) is automatically included in the event context sent to all providers.
+     * This happens transparently - you don't need to pass user data manually.
+     *
      * If providers are configured, the method waits for all providers to complete
      * tracking. Failed providers don't prevent others from succeeding.
      *
@@ -146,6 +170,19 @@ export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = Defaul
      *
      * @example
      * ```typescript
+     * // User context is automatically included after identify()
+     * analytics.identify('user-123', {
+     *   email: 'user@example.com',
+     *   plan: 'pro'
+     * });
+     *
+     * // Now all events automatically include user context
+     * analytics.track('button_clicked', { buttonId: 'checkout' });
+     * // Providers receive: context.user = { userId: 'user-123', email: 'user@example.com', traits: {...} }
+     * ```
+     *
+     * @example
+     * ```typescript
      * // Track a purchase event
      * await analytics.track('purchase_completed', {
      *   orderId: 'order-123',
@@ -409,7 +446,7 @@ export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = Defaul
      * });
      * ```
      */
-    updateContext(context: Partial<EventContext>): void;
+    updateContext(context: Partial<EventContext<TUserTraits>>): void;
     private getCategoryFromEventName;
     private generateSessionId;
     private getDeviceType;

package/dist/adapters/server/server-analytics.d.ts

@@ -1,6 +1,6 @@
-import { AnalyticsConfig, EventContext } from '../../core/events/types.js';
+import { AnalyticsConfig, EventContext, UserContext } from '../../core/events/types.js';
 type DefaultEventMap = Record<string, Record<string, unknown>>;
-export declare class ServerAnalytics<TEventMap extends Record<string, Record<string, unknown>> = DefaultEventMap> {
+export declare class ServerAnalytics<TEventMap extends Record<string, Record<string, unknown>> = DefaultEventMap, TUserTraits extends Record<string, unknown> = Record<string, unknown>> {
     private providers;
     private config;
     private initialized;
@@ -129,12 +129,17 @@ export declare class ServerAnalytics<TEventMap extends Record<string, Record<str
      * 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
@@ -150,7 +155,7 @@ export declare class ServerAnalytics<TEventMap extends Record<string, Record<str
      *
      * @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,
@@ -158,33 +163,61 @@ export declare class ServerAnalytics<TEventMap extends Record<string, Record<str
      *   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
-     * // In an Express.js route handler
+     * // 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 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'] }
      *     }
      *   });
      *
@@ -210,7 +243,8 @@ export declare class ServerAnalytics<TEventMap extends Record<string, Record<str
     track<TEventName extends string>(eventName: TEventName, properties: TEventName extends keyof TEventMap ? TEventMap[TEventName] : Record<string, unknown>, options?: {
         userId?: string;
         sessionId?: string;
-        context?: EventContext;
+        context?: EventContext<TUserTraits>;
+        user?: UserContext<TUserTraits>;
     }): Promise<void>;
     /**
      * Tracks a page view event from the server side.
@@ -273,7 +307,7 @@ export declare class ServerAnalytics<TEventMap extends Record<string, Record<str
      * ```
      */
     pageView(properties?: Record<string, unknown>, options?: {
-        context?: EventContext;
+        context?: EventContext<TUserTraits>;
     }): void;
     /**
      * Tracks when a user leaves a page from the server side.
@@ -335,7 +369,7 @@ export declare class ServerAnalytics<TEventMap extends Record<string, Record<str
      * ```
      */
     pageLeave(properties?: Record<string, unknown>, options?: {
-        context?: EventContext;
+        context?: EventContext<TUserTraits>;
     }): void;
     /**
      * Shuts down all analytics providers and flushes pending events.