feat(player-events): event sourcing + audit log for player actions

src/achievements/achievements.module.ts

@@ -3,13 +3,14 @@ import { TypeOrmModule } from '@nestjs/typeorm';
 
 import { AchievementsService } from './achievements.service';
 import { AchievementsController } from './achievements.controller';
+import { PlayerEventsModule } from '../player-events/player-events.module';
 import { Achievement } from './entities/achievement.entity';
 import { UserAchievement } from './entities/user-achievement.entity';
 import { NotificationsModule } from '../notifications/notifications.module';
 import { AchievementConditionEngine } from './achievement-condition.engine';
 
 @Module({
-  imports: [TypeOrmModule.forFeature([Achievement, UserAchievement]), NotificationsModule],
+  imports: [TypeOrmModule.forFeature([Achievement, UserAchievement]), NotificationsModule, PlayerEventsModule],
   controllers: [AchievementsController],
   providers: [AchievementsService, AchievementConditionEngine],
   exports: [AchievementsService],

src/app.module.ts

@@ -50,6 +50,7 @@ import { EnergyModule } from './energy/energy.module';
 import { SkillRatingModule } from './skill-rating/skill-rating.module';
 import { WalletAuthModule } from './auth/wallet-auth.module';
 import { XpModule } from './xp/xp.module';
+import { PlayerEventsModule } from './player-events/player-events.module';
 
 @Module({
   imports: [
@@ -128,8 +129,7 @@ import { XpModule } from './xp/xp.module';
     PuzzleModule,
     EventModule,
     SeasonalEventsModule,
-    MultiplayerModule,
-    RecommendationsModule,
+    MultiplayerModule,    PlayerEventsModule,    RecommendationsModule,
     AntiCheatModule,
     QuestsModule,
     IntegrationsModule,

src/game-session/game-session.module.ts

@@ -1,15 +1,16 @@
-import { Module } from '@nestjs/common';
+import { Module, forwardRef } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 import { GameSession } from './entities/game-session.entity';
 import { Spectator } from './entities/spectator.entity';
+import { PlayerEventsModule } from '../player-events/player-events.module';
 import { GameSessionService } from './services/game-session.service';
 import { SpectatorService } from './services/spectator.service';
 import { CleanupSessionJob } from './services/cleanup-session.job';
 import { AutosaveSessionJob } from './services/autosave-session.job';
 import { GameSessionController } from './controllers/game-session.controller';
 
 @Module({
-  imports: [TypeOrmModule.forFeature([GameSession, Spectator])],
+  imports: [TypeOrmModule.forFeature([GameSession, Spectator]), forwardRef(() => PlayerEventsModule)],
   controllers: [GameSessionController],
   providers: [
     GameSessionService,

src/game-session/services/game-session.service.ts

@@ -3,12 +3,14 @@ import { Injectable, NotFoundException } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Repository, LessThan } from 'typeorm';
 import { GameSession } from '../entities/game-session.entity';
+import { PlayerEventsService } from '../../player-events/player-events.service';
 
 @Injectable()
 export class GameSessionService {
   constructor(
     @InjectRepository(GameSession)
     private readonly sessionRepo: Repository<GameSession>,
+    private readonly playerEventsService: PlayerEventsService,
   ) {}
 
   async create(userId: string) {
@@ -18,7 +20,19 @@ export class GameSessionService {
       state: {},
       lastActiveAt: new Date(),
     });
-    return this.sessionRepo.save(session);
+    const savedSession = await this.sessionRepo.save(session);
+
+    await this.playerEventsService.emitPlayerEvent({
+      userId,
+      sessionId: savedSession.id,
+      eventType: 'puzzle.started',
+      payload: {
+        sessionId: savedSession.id,
+        startedAt: savedSession.createdAt || new Date(),
+      },
+    });
+
+    return savedSession;
   }
 
   async updateState(sessionId: string, partialState: Record<string, any>) {
@@ -44,10 +58,29 @@ export class GameSessionService {
     session.status = status;
     session.lastActiveAt = new Date();
 
-    return this.sessionRepo.save(session);
+    const savedSession = await this.sessionRepo.save(session);
+
+    if (status === 'ABANDONED') {
+      await this.playerEventsService.emitPlayerEvent({
+        userId: savedSession.userId,
+        sessionId: savedSession.id,
+        eventType: 'puzzle.abandoned',
+        payload: {
+          sessionId: savedSession.id,
+          reason: 'session ended as abandoned',
+          endedAt: savedSession.lastActiveAt,
+        },
+      });
+    }
+
+    return savedSession;
   }
 
   async getActiveSessions() {
     return this.sessionRepo.find({ where: { status: 'IN_PROGRESS' } });
   }
+
+  async getById(sessionId: string) {
+    return this.sessionRepo.findOne({ where: { id: sessionId } });
+  }
 }

src/hints/hints.module.ts

@@ -2,6 +2,7 @@ import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 import { HintsService } from './hints.service';
 import { HintsController } from './hints.controller';
+import { PlayerEventsModule } from '../player-events/player-events.module';
 import { Hint } from './entities/hint.entity';
 import { HintUsage } from './entities/hint-usage.entity';
 import { HintTemplate } from './entities/hint-template.entity';
@@ -11,6 +12,7 @@ import { PuzzlesModule } from '../puzzles/puzzles.module';
   imports: [
     TypeOrmModule.forFeature([Hint, HintUsage, HintTemplate]),
     PuzzlesModule,
+    PlayerEventsModule,
   ],
   controllers: [HintsController],
   providers: [HintsService],

src/hints/hints.service.ts

@@ -1,6 +1,7 @@
 import { Injectable, BadRequestException, ForbiddenException } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Repository, FindOptionsWhere, MoreThanOrEqual } from 'typeorm';
+import { PlayerEventsService } from '../player-events/player-events.service';
 import { Hint } from './entities/hint.entity';
 import { HintUsage } from './entities/hint-usage.entity';
 import { HintTemplate } from './entities/hint-template.entity';
@@ -18,6 +19,7 @@ export class HintsService {
     private readonly usageRepo: Repository<HintUsage>,
     @InjectRepository(HintTemplate)
     private readonly templateRepo: Repository<HintTemplate>,
+    private readonly playerEventsService: PlayerEventsService,
   ) {}
 
   async createHint(dto: CreateHintDto): Promise<Hint> {
@@ -92,6 +94,21 @@ export class HintsService {
       },
     });
 
+    // Emit audit event for hint usage
+    void this.playerEventsService.emitPlayerEvent({
+      userId: dto.userId,
+      sessionId: null,
+      eventType: 'hint.used',
+      payload: {
+        puzzleId: dto.puzzleId,
+        hintId: selected.id,
+        attemptNumber: dto.attemptNumber,
+        timeSpent: dto.timeSpent,
+        puzzleState: dto.puzzleState,
+        playerState: dto.playerState,
+      },
+    });
+
     return selected;
   }
 

src/player-events/dto/player-action-event.dto.ts

@@ -0,0 +1,33 @@
+import { IsUUID, IsEnum, IsObject, IsOptional, IsNumber, Min, Max, IsString } from 'class-validator';
+import { Type } from 'class-transformer';
+import { PlayerActionEventType } from '../entities/player-action-event.entity';
+
+export class CreatePlayerActionEventDto {
+  @IsUUID()
+  userId: string;
+
+  @IsUUID()
+  @IsOptional()
+  sessionId?: string;
+
+  @IsEnum(['puzzle.started', 'puzzle.solved', 'puzzle.abandoned', 'hint.used', 'answer.submitted', 'achievement.unlocked'])
+  eventType: PlayerActionEventType;
+
+  @IsObject()
+  payload: Record<string, any>;
+}
+
+export class PagedQueryDto {
+  @IsOptional()
+  @Type(() => Number)
+  @IsNumber()
+  @Min(1)
+  page?: number = 1;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsNumber()
+  @Min(1)
+  @Max(100)
+  limit?: number = 20;
+}

src/player-events/entities/player-action-event.entity.ts

@@ -0,0 +1,35 @@
+import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, Index } from 'typeorm';
+
+export type PlayerActionEventType =
+  | 'puzzle.started'
+  | 'puzzle.solved'
+  | 'puzzle.abandoned'
+  | 'hint.used'
+  | 'answer.submitted'
+  | 'achievement.unlocked';
+
+@Entity('player_action_events')
+@Index(['userId', 'eventType', 'timestamp'])
+export class PlayerActionEvent {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ type: 'uuid' })
+  @Index()
+  userId: string;
+
+  @Column({ type: 'uuid', nullable: true })
+  @Index()
+  sessionId: string;
+
+  @Column({ type: 'varchar', length: 50 })
+  @Index()
+  eventType: PlayerActionEventType;
+
+  @Column({ type: 'jsonb', default: {} })
+  payload: Record<string, any>;
+
+  @CreateDateColumn({ type: 'timestamptz' })
+  @Index()
+  timestamp: Date;
+}

src/player-events/player-events.controller.ts

@@ -0,0 +1,45 @@
+import { Controller, Get, Param, Query, Request, UseGuards, ForbiddenException } from '@nestjs/common';
+import { PlayerEventsService } from './player-events.service';
+import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RolesGuard } from '../auth/guards/roles.guard';
+import { Roles } from '../auth/decorators/roles.decorator';
+import { UserRole } from '../auth/constants';
+import { GameSessionService } from '../game-session/services/game-session.service';
+import { PagedQueryDto } from './dto/player-action-event.dto';
+
+@Controller()
+@UseGuards(JwtAuthGuard, RolesGuard)
+export class PlayerEventsController {
+  constructor(
+    private readonly playerEventsService: PlayerEventsService,
+    private readonly gameSessionService: GameSessionService,
+  ) {}
+
+  @Get('players/:id/events')
+  @Roles(UserRole.ADMIN)
+  async getPlayerEvents(@Param('id') userId: string, @Query() query: PagedQueryDto) {
+    const page = query.page || 1;
+    const limit = query.limit || 20;
+    return this.playerEventsService.getEventsByPlayer(userId, page, limit);
+  }
+
+  @Get('sessions/:id/events')
+  async getSessionEvents(@Param('id') sessionId: string, @Query() query: PagedQueryDto, @Request() req: any) {
+    const page = query.page || 1;
+    const limit = query.limit || 50;
+
+    // Only admins or the session owner can fetch session events
+    const session = await this.gameSessionService.getById(sessionId);
+    if (!session) {
+      throw new ForbiddenException('Session not found or access denied');
+    }
+
+    const requester = req.user;
+    const isAdmin = requester?.role?.name === UserRole.ADMIN;
+    if (!isAdmin && session.userId !== requester.id) {
+      throw new ForbiddenException('Access denied');
+    }
+
+    return this.playerEventsService.getEventsBySession(sessionId, page, limit);
+  }
+}

src/player-events/player-events.module.ts

@@ -0,0 +1,15 @@
+import { Module, forwardRef } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { PlayerEventsService } from './player-events.service';
+import { PlayerEventsController } from './player-events.controller';
+import { PlayerActionEvent } from './entities/player-action-event.entity';
+import { GameSession } from '../game-session/entities/game-session.entity';
+import { GameSessionModule } from '../game-session/game-session.module';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([PlayerActionEvent, GameSession]), forwardRef(() => GameSessionModule)],
+  controllers: [PlayerEventsController],
+  providers: [PlayerEventsService],
+  exports: [PlayerEventsService],
+})
+export class PlayerEventsModule {}