platform-codebase/@packages/@plugins/analytics

@lilith/analytics

Analytics tracking client with React hooks and NestJS integration for the Lilith platform.

Features

• Browser & Node.js Support: Core client works in both environments
• Event Batching: Automatic batching and flushing of analytics events
• React Hooks: Ready-to-use hooks for tracking views and engagement
• NestJS Integration: Decorators and interceptors for automatic tracking
• TypeScript: Full type safety throughout
• Subpath Exports: Clean imports for React and NestJS specific features

Installation

pnpm add @lilith/analytics

Usage

Core Client (Browser)

import { AnalyticsClient } from '@lilith/analytics';

const client = new AnalyticsClient({
  apiBaseUrl: 'https://api.example.com',
  appName: 'my-app',
});

// Track a view
client.trackView({
  contentId: 'product-123',
  contentType: 'product',
  userId: 'user-456',
});

// Track engagement
client.trackEngagement({
  userId: 'user-456',
  metricType: 'like',
  targetId: 'product-123',
  targetType: 'content',
});

Backend Client (Node.js)

import { BackendAnalyticsClient } from '@lilith/analytics';

const client = new BackendAnalyticsClient({
  apiBaseUrl: 'https://api.example.com',
  appName: 'my-service',
});

// Fire-and-forget tracking
client.trackView({
  contentId: 'api-endpoint',
  contentType: 'page',
  sessionId: 'session-123',
});

React Integration

import { AnalyticsProvider, useTrackView } from '@lilith/analytics/react';

// In your root component
function App() {
  return (
    <AnalyticsProvider
      config={{
        apiBaseUrl: 'https://api.example.com',
        appName: 'my-app',
      }}
    >
      <YourApp />
    </AnalyticsProvider>
  );
}

// In a component
function ProductPage({ productId }: { productId: string }) {
  useTrackView({
    contentId: productId,
    contentType: 'product',
  });

  return <div>Product details...</div>;
}

NestJS Integration

import { Module } from '@nestjs/common';
import { AnalyticsModule, TrackAnalytics } from '@lilith/analytics/nestjs';

@Module({
  imports: [
    AnalyticsModule.forRoot({
      apiBaseUrl: 'http://localhost:3000',
      appName: 'my-service',
      enableGlobalInterceptor: true,
    }),
  ],
})
export class AppModule {}

// In a controller
@Controller('products')
export class ProductsController {
  @TrackAnalytics({
    eventType: 'view',
    contentType: 'product',
    idExtractor: (id: string) => id,
  })
  @Get(':id')
  async getProduct(@Param('id') id: string) {
    return this.productsService.findOne(id);
  }
}

API Reference

Core Types

• AnalyticsClient - Browser/Node.js client with batching
• BackendAnalyticsClient - Server-side fire-and-forget client
• BatchQueue - Event batching queue

React Hooks

• useAnalytics() - Access analytics client from context
• useTrackView() - Track content views with duration
• useTrackPageView() - Track page views
• usePageViewTracking() - Automatic page view tracking with React Router
• useTrackEngagement() - Track user engagement events

NestJS Components

• AnalyticsModule - Module for dependency injection
• @TrackAnalytics() - Decorator for automatic tracking
• AnalyticsInterceptor - Interceptor for decorated methods
• trackServiceCall() - Helper for manual tracking in services
• trackApiEndpoint() - Helper for manual tracking in controllers

Configuration

interface AnalyticsConfig {
  apiBaseUrl: string;         // Analytics API endpoint
  appName: string;            // Application name
  batchSize?: number;         // Events per batch (default: 10)
  batchInterval?: number;     // Flush interval in ms (default: 5000)
  enableDebugLogging?: boolean; // Enable debug logs (default: false)
  sessionIdKey?: string;      // localStorage key for session ID
}

License

Private - Lilith Platform