platform-codebase/@packages/@plugins/analytics/README.md

# @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

```bash
pnpm add @lilith/analytics
```

## Usage

### Core Client (Browser)

```typescript
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)

```typescript
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

```tsx
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

```typescript
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

```typescript
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