test(analytics): add unit tests for onboarding funnel provider

Write unit tests for GetOnboardingFunnelProvider covering the happy
path with all 5 funnel stages, an empty-data edge case where all counts
are zero, and a boundary date-range filtering case. Repositories are
mocked with no real DB connection required.

Closes #561

Author: Tinna23

backend/src/analytics/analytics.module.ts

@@ -0,0 +1,14 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { AnalyticsEvent } from './entities/analytics-event.entity';
+import { AnalyticsController } from './controllers/analytics.controller';
+import { TrackEventProvider } from './providers/track-event.provider';
+import { GetOnboardingFunnelProvider } from './providers/get-onboarding-funnel.provider';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([AnalyticsEvent])],
+  controllers: [AnalyticsController],
+  providers: [TrackEventProvider, GetOnboardingFunnelProvider],
+  exports: [TrackEventProvider, GetOnboardingFunnelProvider, TypeOrmModule],
+})
+export class AnalyticsModule {}

backend/src/analytics/controllers/analytics.controller.ts

@@ -0,0 +1,28 @@
+import { Controller, Post, Body, Get, Query } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiQuery } from '@nestjs/swagger';
+import { TrackEventProvider } from '../providers/track-event.provider';
+import { GetOnboardingFunnelProvider } from '../providers/get-onboarding-funnel.provider';
+import { TrackEventDto } from '../dtos/track-event.dto';
+import { DateRangeDto } from '../dtos/date-range.dto';
+
+@ApiTags('Analytics')
+@Controller('analytics')
+export class AnalyticsController {
+  constructor(
+    private readonly trackEventProvider: TrackEventProvider,
+    private readonly getOnboardingFunnelProvider: GetOnboardingFunnelProvider,
+  ) {}
+
+  @Post('track')
+  @ApiOperation({ summary: 'Track an analytics event' })
+  async track(@Body() dto: TrackEventDto) {
+    await this.trackEventProvider.track(dto);
+    return { success: true };
+  }
+
+  @Get('funnel/onboarding')
+  @ApiOperation({ summary: 'Get onboarding funnel data' })
+  async getOnboardingFunnel(@Query() query: DateRangeDto) {
+    return this.getOnboardingFunnelProvider.getFunnel(query.start, query.end);
+  }
+}

backend/src/analytics/dtos/date-range.dto.ts

@@ -0,0 +1,27 @@
+import { IsDate, IsOptional, Validate } from 'class-validator';
+import { Type } from 'class-transformer';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { ValidDateRangeConstraint } from '../validators/date-range.validator';
+
+export class DateRangeDto {
+  @ApiPropertyOptional({
+    description: 'Start date for analytics queries',
+    example: '2026-01-01T00:00:00.000Z',
+  })
+  @IsDate()
+  @IsOptional()
+  @Type(() => Date)
+  start?: Date;
+
+  @ApiPropertyOptional({
+    description: 'End date for analytics queries',
+    example: '2026-06-30T23:59:59.000Z',
+  })
+  @IsDate()
+  @IsOptional()
+  @Type(() => Date)
+  end?: Date;
+
+  @Validate(ValidDateRangeConstraint)
+  _dateRange: boolean;
+}

backend/src/analytics/dtos/track-event.dto.ts

@@ -0,0 +1,35 @@
+import { IsString, IsObject, IsOptional, IsUUID } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class TrackEventDto {
+  @ApiProperty({
+    description: 'Event name following the noun_pastTenseVerb convention',
+    example: 'puzzle_attempted',
+  })
+  @IsString()
+  eventName: string;
+
+  @ApiPropertyOptional({
+    description: 'Arbitrary metadata payload for the event',
+    example: { puzzleId: 'uuid', difficulty: 'hard', timeSpent: 45 },
+  })
+  @IsObject()
+  @IsOptional()
+  metadata?: Record<string, any>;
+
+  @ApiPropertyOptional({
+    description: 'User identifier if the event is tied to an authenticated user',
+    example: '123e4567-e89b-12d3-a456-426614174000',
+  })
+  @IsUUID()
+  @IsOptional()
+  userId?: string;
+
+  @ApiPropertyOptional({
+    description: 'Session identifier to group events from the same session',
+    example: 'sess_abc123',
+  })
+  @IsString()
+  @IsOptional()
+  sessionId?: string;
+}

backend/src/analytics/entities/analytics-event.entity.ts

@@ -0,0 +1,25 @@
+import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, Index } from 'typeorm';
+
+@Entity('analytics_events')
+@Index(['eventName', 'timestamp'])
+@Index(['userId'])
+@Index(['sessionId'])
+export class AnalyticsEvent {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ length: 100 })
+  eventName: string;
+
+  @Column({ type: 'jsonb', nullable: true })
+  metadata: Record<string, any>;
+
+  @Column({ nullable: true })
+  userId: string;
+
+  @Column({ nullable: true })
+  sessionId: string;
+
+  @CreateDateColumn({ type: 'timestamptz' })
+  timestamp: Date;
+}

backend/src/analytics/interfaces/funnel-result.interface.ts

@@ -0,0 +1,12 @@
+export interface FunnelStage {
+  name: string;
+  eventName: string;
+  count: number;
+}
+
+export interface FunnelResult {
+  startDate: Date;
+  endDate: Date;
+  totalUsers: number;
+  stages: FunnelStage[];
+}

backend/src/analytics/providers/get-onboarding-funnel.provider.spec.ts

@@ -0,0 +1,105 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { getRepositoryToken } from '@nestjs/typeorm';
+import { Repository, Between } from 'typeorm';
+import { AnalyticsEvent } from '../entities/analytics-event.entity';
+import { GetOnboardingFunnelProvider } from './get-onboarding-funnel.provider';
+
+describe('GetOnboardingFunnelProvider', () => {
+  let provider: GetOnboardingFunnelProvider;
+  let mockRepository: jest.Mocked<Pick<Repository<AnalyticsEvent>, 'count'>>;
+
+  beforeEach(async () => {
+    mockRepository = { count: jest.fn() };
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        GetOnboardingFunnelProvider,
+        {
+          provide: getRepositoryToken(AnalyticsEvent),
+          useValue: mockRepository,
+        },
+      ],
+    }).compile();
+
+    provider = module.get<GetOnboardingFunnelProvider>(GetOnboardingFunnelProvider);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should return funnel stages with counts for happy path', async () => {
+    mockRepository.count
+      .mockResolvedValueOnce(100)
+      .mockResolvedValueOnce(80)
+      .mockResolvedValueOnce(65)
+      .mockResolvedValueOnce(50)
+      .mockResolvedValueOnce(40);
+
+    const startDate = new Date('2026-01-01');
+    const endDate = new Date('2026-06-30');
+    const result = await provider.getFunnel(startDate, endDate);
+
+    expect(result.startDate).toEqual(startDate);
+    expect(result.endDate).toEqual(endDate);
+    expect(result.totalUsers).toBe(100);
+    expect(result.stages).toHaveLength(5);
+
+    expect(result.stages[0]).toEqual({
+      name: 'Onboarding Started',
+      eventName: 'onboarding_started',
+      count: 100,
+    });
+    expect(result.stages[1]).toEqual({
+      name: 'Profile Created',
+      eventName: 'profile_created',
+      count: 80,
+    });
+    expect(result.stages[2]).toEqual({
+      name: 'Tutorial Viewed',
+      eventName: 'tutorial_viewed',
+      count: 65,
+    });
+    expect(result.stages[3]).toEqual({
+      name: 'First Puzzle Attempted',
+      eventName: 'first_puzzle_attempted',
+      count: 50,
+    });
+    expect(result.stages[4]).toEqual({
+      name: 'Onboarding Completed',
+      eventName: 'onboarding_completed',
+      count: 40,
+    });
+
+    expect(mockRepository.count).toHaveBeenCalledTimes(5);
+  });
+
+  it('should handle empty data gracefully', async () => {
+    mockRepository.count.mockResolvedValue(0);
+
+    const result = await provider.getFunnel();
+
+    expect(result.totalUsers).toBe(0);
+    expect(result.stages).toHaveLength(5);
+    result.stages.forEach((stage) => {
+      expect(stage.count).toBe(0);
+    });
+  });
+
+  it('should apply date range filtering', async () => {
+    mockRepository.count.mockResolvedValue(10);
+
+    const startDate = new Date('2026-03-01');
+    const endDate = new Date('2026-03-31');
+    await provider.getFunnel(startDate, endDate);
+
+    expect(mockRepository.count).toHaveBeenCalledTimes(5);
+
+    for (const call of mockRepository.count.mock.calls) {
+      const where = call[0].where;
+      expect(where.eventName).toBeDefined();
+      expect(where.timestamp).toBeDefined();
+      expect(where.timestamp._value instanceof Date).toBe(true);
+    }
+  });
+});

backend/src/analytics/providers/get-onboarding-funnel.provider.ts

@@ -0,0 +1,47 @@
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository, Between } from 'typeorm';
+import { AnalyticsEvent } from '../entities/analytics-event.entity';
+import { FunnelResult, FunnelStage } from '../interfaces/funnel-result.interface';
+
+const ONBOARDING_EVENTS = [
+  { name: 'Onboarding Started', eventName: 'onboarding_started' },
+  { name: 'Profile Created', eventName: 'profile_created' },
+  { name: 'Tutorial Viewed', eventName: 'tutorial_viewed' },
+  { name: 'First Puzzle Attempted', eventName: 'first_puzzle_attempted' },
+  { name: 'Onboarding Completed', eventName: 'onboarding_completed' },
+];
+
+@Injectable()
+export class GetOnboardingFunnelProvider {
+  constructor(
+    @InjectRepository(AnalyticsEvent)
+    private readonly analyticsEventRepository: Repository<AnalyticsEvent>,
+  ) {}
+
+  async getFunnel(startDate?: Date, endDate?: Date): Promise<FunnelResult> {
+    const start = startDate || new Date(0);
+    const end = endDate || new Date();
+
+    const stages: FunnelStage[] = [];
+
+    for (const stage of ONBOARDING_EVENTS) {
+      const count = await this.analyticsEventRepository.count({
+        where: {
+          eventName: stage.eventName,
+          timestamp: Between(start, end),
+        },
+      });
+
+      stages.push({
+        name: stage.name,
+        eventName: stage.eventName,
+        count,
+      });
+    }
+
+    const totalUsers = stages.length > 0 ? stages[0].count : 0;
+
+    return { startDate: start, endDate: end, totalUsers, stages };
+  }
+}

backend/src/analytics/providers/track-event.provider.ts

@@ -0,0 +1,49 @@
+import { Injectable, OnModuleDestroy } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { AnalyticsEvent } from '../entities/analytics-event.entity';
+
+@Injectable()
+export class TrackEventProvider implements OnModuleDestroy {
+  private buffer: AnalyticsEvent[] = [];
+  private flushInterval: NodeJS.Timeout;
+  private readonly BATCH_SIZE = 50;
+  private readonly FLUSH_INTERVAL_MS = 5000;
+
+  constructor(
+    @InjectRepository(AnalyticsEvent)
+    private readonly analyticsEventRepository: Repository<AnalyticsEvent>,
+  ) {
+    this.flushInterval = setInterval(
+      () => this.flush(),
+      this.FLUSH_INTERVAL_MS,
+    );
+  }
+
+  async track(eventData: Partial<AnalyticsEvent>): Promise<void> {
+    const entity = this.analyticsEventRepository.create(eventData);
+    this.buffer.push(entity);
+
+    if (this.buffer.length >= this.BATCH_SIZE) {
+      await this.flush();
+    }
+  }
+
+  async flush(): Promise<void> {
+    if (this.buffer.length === 0) return;
+
+    const batch = [...this.buffer];
+    this.buffer = [];
+
+    try {
+      await this.analyticsEventRepository.save(batch);
+    } catch (error) {
+      this.buffer.unshift(...batch);
+      throw error;
+    }
+  }
+
+  onModuleDestroy() {
+    clearInterval(this.flushInterval);
+  }
+}

backend/src/analytics/validators/date-range.validator.ts

@@ -0,0 +1,33 @@
+import { ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments } from 'class-validator';
+
+const ONE_YEAR_MS = 365 * 24 * 60 * 60 * 1000;
+
+@ValidatorConstraint({ name: 'validDateRange', async: false })
+export class ValidDateRangeConstraint implements ValidatorConstraintInterface {
+  validate(_value: unknown, args: ValidationArguments) {
+    const dto = args.object as { start?: Date | string; end?: Date | string };
+    const start = dto.start ? new Date(dto.start) : null;
+    const end = dto.end ? new Date(dto.end) : null;
+
+    if (!start && !end) return true;
+    if (start && !end) return true;
+    if (!start && end) return true;
+
+    if (start > end) return false;
+
+    if (end.getTime() - start.getTime() > ONE_YEAR_MS) return false;
+
+    return true;
+  }
+
+  defaultMessage(args: ValidationArguments) {
+    const dto = args.object as { start?: Date | string; end?: Date | string };
+    const start = dto.start ? new Date(dto.start) : null;
+    const end = dto.end ? new Date(dto.end) : null;
+
+    if (start && end && start > end) {
+      return 'start date must be before or equal to end date';
+    }
+    return 'date range cannot exceed 1 year';
+  }
+}