@hed-hog/lms 0.0.349 → 0.0.351

package/src/enterprise/training/training-student.controller.ts

@@ -1,5 +1,5 @@
 import { Role, User } from '@hed-hog/api';
-import { Controller, Get, Param, ParseIntPipe, Query } from '@nestjs/common';
+import { Body, Controller, Get, Param, ParseIntPipe, Post, Query } from '@nestjs/common';
 import { TrainingStudentService } from './training-student.service';
 
 @Role()
@@ -62,4 +62,20 @@ export class TrainingStudentController {
   ) {
     return this.trainingStudentService.getMyEvaluations(userId, classGroupId);
   }
+
+  @Get('streak')
+  getStreak(
+    @User('id') userId: number,
+    @Query('days', new ParseIntPipe({ optional: true })) days?: number,
+  ) {
+    return this.trainingStudentService.getStreak(userId, days);
+  }
+
+  @Post('streak/activities')
+  registerStreakActivity(
+    @User('id') userId: number,
+    @Body() body?: { activityType?: string; source?: string; activityDateKey?: string },
+  ) {
+    return this.trainingStudentService.registerStreakActivity(userId, body);
+  }
 }

package/src/enterprise/training/training-student.mcp-tools.ts

@@ -0,0 +1,136 @@
+import { McpContext, McpTool } from '@hed-hog/core';
+import { Injectable } from '@nestjs/common';
+import { TrainingStudentService } from './training-student.service';
+
+@Injectable()
+export class LmsTrainingStudentMcpTools {
+  constructor(private readonly trainingStudentService: TrainingStudentService) {}
+
+  @McpTool({
+    name: 'lms.training-student.dashboard',
+    description: 'Returns the training dashboard summary for the authenticated student.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        enterpriseId: { type: 'number', description: 'Enterprise ID (optional; inferred from user if omitted)' },
+      },
+    },
+    readOnly: true,
+  })
+  async getDashboard(args: { enterpriseId?: number }, context: McpContext): Promise<any> {
+    return this.trainingStudentService.getDashboard(context.userId, args.enterpriseId);
+  }
+
+  @McpTool({
+    name: 'lms.training-student.class-groups.list',
+    description: 'Lists class groups in which the authenticated student is enrolled.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        enterpriseId: { type: 'number', description: 'Enterprise ID' },
+        search: { type: 'string', description: 'Search term' },
+        status: { type: 'string', description: 'Filter by status (open|ongoing|completed|cancelled)' },
+        deliveryMode: { type: 'string', description: 'Filter by delivery mode (presential|online|hybrid)' },
+      },
+    },
+    readOnly: true,
+  })
+  async getClassGroups(args: Record<string, any>, context: McpContext): Promise<any> {
+    return this.trainingStudentService.getClassGroups(context.userId, args);
+  }
+
+  @McpTool({
+    name: 'lms.training-student.class-groups.get',
+    description: 'Returns details of a specific class group for the authenticated student.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        classGroupId: { type: 'number', description: 'Class group ID' },
+      },
+      required: ['classGroupId'],
+    },
+    readOnly: true,
+  })
+  async getClassGroupDetail(args: { classGroupId: number }, context: McpContext): Promise<any> {
+    return this.trainingStudentService.getClassGroupDetail(context.userId, args.classGroupId);
+  }
+
+  @McpTool({
+    name: 'lms.training-student.class-groups.sessions',
+    description: 'Lists sessions for a class group (student view).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        classGroupId: { type: 'number', description: 'Class group ID' },
+      },
+      required: ['classGroupId'],
+    },
+    readOnly: true,
+  })
+  async getClassGroupSessions(args: { classGroupId: number }, context: McpContext): Promise<any> {
+    return this.trainingStudentService.getClassGroupSessions(context.userId, args.classGroupId);
+  }
+
+  @McpTool({
+    name: 'lms.training-student.class-groups.materials',
+    description: 'Lists materials for a class group (student view).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        classGroupId: { type: 'number', description: 'Class group ID' },
+      },
+      required: ['classGroupId'],
+    },
+    readOnly: true,
+  })
+  async getClassGroupMaterials(args: { classGroupId: number }, context: McpContext): Promise<any> {
+    return this.trainingStudentService.getClassGroupMaterials(context.userId, args.classGroupId);
+  }
+
+  @McpTool({
+    name: 'lms.training-student.class-groups.my-evaluations',
+    description: 'Returns the evaluations submitted by the authenticated student for a class group.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        classGroupId: { type: 'number', description: 'Class group ID' },
+      },
+      required: ['classGroupId'],
+    },
+    readOnly: true,
+  })
+  async getMyEvaluations(args: { classGroupId: number }, context: McpContext): Promise<any> {
+    return this.trainingStudentService.getMyEvaluations(context.userId, args.classGroupId);
+  }
+
+  @McpTool({
+    name: 'lms.training-student.streak.get',
+    description: 'Returns the learning streak data for the authenticated student.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: { type: 'number', description: 'Number of days to include (default: 30)' },
+      },
+    },
+    readOnly: true,
+  })
+  async getStreak(args: { days?: number }, context: McpContext): Promise<any> {
+    return this.trainingStudentService.getStreak(context.userId, args.days);
+  }
+
+  @McpTool({
+    name: 'lms.training-student.streak.register-activity',
+    description: 'Registers a learning activity for the authenticated student (updates streak).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        activityType: { type: 'string', description: 'Type of activity' },
+        source: { type: 'string', description: 'Activity source identifier' },
+        activityDateKey: { type: 'string', description: 'Date key for the activity (YYYY-MM-DD)' },
+      },
+    },
+  })
+  async registerStreakActivity(args: Record<string, any>, context: McpContext): Promise<any> {
+    return this.trainingStudentService.registerStreakActivity(context.userId, args);
+  }
+}

package/src/enterprise/training/training-student.service.ts

@@ -1,10 +1,73 @@
 import { PrismaService } from '@hed-hog/api-prisma';
-import { Injectable, NotFoundException } from '@nestjs/common';
+import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
 
 @Injectable()
 export class TrainingStudentService {
   constructor(private readonly prisma: PrismaService) {}
 
+  async registerStreakActivity(
+    userId: number,
+    payload?: { activityType?: string; source?: string; activityDateKey?: string },
+  ) {
+    const personId = await this.resolvePersonIdFromUser(userId);
+    const activityDateKey = this.normalizeActivityDateKey(payload?.activityDateKey);
+    const activityType = this.normalizeText(payload?.activityType, 100);
+    const source = this.normalizeText(payload?.source, 100) ?? 'class-app';
+
+    await this.prisma.$executeRaw`
+      INSERT INTO "student_activity_streak" (
+        "person_id",
+        "activity_date_key",
+        "activity_type",
+        "source",
+        "last_activity_at"
+      )
+      VALUES (
+        ${personId},
+        ${activityDateKey},
+        ${activityType},
+        ${source},
+        NOW()
+      )
+      ON CONFLICT ("person_id", "activity_date_key")
+      DO UPDATE SET
+        "activity_type" = COALESCE(EXCLUDED."activity_type", "student_activity_streak"."activity_type"),
+        "source" = COALESCE(EXCLUDED."source", "student_activity_streak"."source"),
+        "last_activity_at" = NOW(),
+        "updated_at" = NOW();
+    `;
+
+    return this.getStreak(userId, 14);
+  }
+
+  async getStreak(userId: number, days = 14) {
+    const safeDays = Number.isFinite(days) ? Math.max(7, Math.min(60, Math.trunc(days))) : 14;
+    const personId = await this.resolvePersonIdFromUser(userId);
+
+    const rows = await this.prisma.$queryRaw<Array<{ activity_date_key: string }>>`
+      SELECT "activity_date_key"
+      FROM "student_activity_streak"
+      WHERE "person_id" = ${personId}
+      ORDER BY "activity_date_key" DESC;
+    `;
+
+    const uniqueKeys = Array.from(
+      new Set(rows.map((row) => row.activity_date_key).filter((key): key is string => !!key)),
+    ).sort((a, b) => b.localeCompare(a));
+
+    const currentStreak = this.calculateCurrentStreak(uniqueKeys);
+    const bestStreak = this.calculateBestStreak(uniqueKeys);
+    const calendar = this.buildStreakCalendar(uniqueKeys, safeDays);
+
+    return {
+      currentStreak,
+      bestStreak,
+      totalActiveDays: uniqueKeys.length,
+      lastActivityDate: uniqueKeys[0] ?? null,
+      days: calendar,
+    };
+  }
+
   async getDashboard(userId: number, enterpriseId?: number) {
     const personUser = await this.prisma.person_user.findFirst({
       where: { user_id: userId },
@@ -759,4 +822,107 @@ export class TrainingStudentService {
     result.setDate(result.getDate() + diff);
     return result;
   }
+
+  private toDateKey(date: Date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+  }
+
+  private dateFromKey(key: string) {
+    return new Date(`${key}T00:00:00`);
+  }
+
+  private normalizeActivityDateKey(activityDateKey?: string) {
+    if (!activityDateKey) {
+      return this.toDateKey(new Date());
+    }
+
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(activityDateKey)) {
+      throw new BadRequestException('activityDateKey must use the YYYY-MM-DD format');
+    }
+
+    return activityDateKey;
+  }
+
+  private normalizeText(value: string | undefined, maxLength: number) {
+    if (!value) {
+      return null;
+    }
+
+    const normalized = value.trim();
+    if (!normalized) {
+      return null;
+    }
+
+    return normalized.slice(0, maxLength);
+  }
+
+  private calculateCurrentStreak(dateKeysDesc: string[]) {
+    if (dateKeysDesc.length === 0) {
+      return 0;
+    }
+
+    let streak = 0;
+    let cursor = this.startOfDay(new Date());
+    for (const dateKey of dateKeysDesc) {
+      const value = this.startOfDay(this.dateFromKey(dateKey));
+      const diff = Math.round((cursor.getTime() - value.getTime()) / 86400000);
+      if (diff > 1) {
+        break;
+      }
+      streak += 1;
+      cursor = value;
+    }
+
+    return streak;
+  }
+
+  private calculateBestStreak(dateKeysDesc: string[]) {
+    if (dateKeysDesc.length === 0) {
+      return 0;
+    }
+
+    const dateKeysAsc = [...dateKeysDesc].sort((a, b) => a.localeCompare(b));
+    let best = 1;
+    let current = 1;
+
+    for (let i = 1; i < dateKeysAsc.length; i += 1) {
+      const previous = this.startOfDay(this.dateFromKey(dateKeysAsc[i - 1]));
+      const next = this.startOfDay(this.dateFromKey(dateKeysAsc[i]));
+      const diff = Math.round((next.getTime() - previous.getTime()) / 86400000);
+      if (diff === 1) {
+        current += 1;
+      } else {
+        current = 1;
+      }
+      if (current > best) {
+        best = current;
+      }
+    }
+
+    return best;
+  }
+
+  private buildStreakCalendar(dateKeysDesc: string[], days: number) {
+    const dateKeySet = new Set(dateKeysDesc);
+    const today = this.startOfDay(new Date());
+
+    return Array.from({ length: days }, (_, index) => {
+      const offset = days - index - 1;
+      const date = this.startOfDay(this.addDays(today, -offset));
+      const key = this.toDateKey(date);
+      return {
+        date: key,
+        completed: dateKeySet.has(key),
+      };
+    });
+  }
+
+  private startOfDay(date: Date) {
+    const result = new Date(date);
+    result.setHours(0, 0, 0, 0);
+    return result;
+  }
 }

package/src/evaluation/evaluation.mcp-tools.ts

@@ -0,0 +1,155 @@
+import { McpContext, McpTool } from '@hed-hog/core';
+import { Injectable } from '@nestjs/common';
+import { EvaluationService } from './evaluation.service';
+
+@Injectable()
+export class LmsEvaluationMcpTools {
+  constructor(private readonly evaluationService: EvaluationService) {}
+
+  @McpTool({
+    name: 'lms.evaluations.list',
+    description: 'Lists evaluations with optional filters (course, class, instructor, evaluator, date range).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page: { type: 'number', description: 'Page number (default: 1)' },
+        pageSize: { type: 'number', description: 'Items per page (default: 20)' },
+        search: { type: 'string', description: 'Search term' },
+        courseId: { type: 'number', description: 'Filter by course ID' },
+        classId: { type: 'number', description: 'Filter by class group ID' },
+        instructorId: { type: 'number', description: 'Filter by instructor ID' },
+        evaluatorId: { type: 'number', description: 'Filter by evaluator ID' },
+        dateFrom: { type: 'string', description: 'Start date filter (ISO8601)' },
+        dateTo: { type: 'string', description: 'End date filter (ISO8601)' },
+      },
+    },
+    readOnly: true,
+  })
+  async listEvaluations(args: Record<string, any>, _context: McpContext): Promise<any> {
+    return this.evaluationService.list(args);
+  }
+
+  @McpTool({
+    name: 'lms.evaluations.stats',
+    description: 'Returns aggregate evaluation statistics.',
+    inputSchema: { type: 'object', properties: {} },
+    readOnly: true,
+  })
+  async getStats(_args: Record<string, any>, _context: McpContext): Promise<any> {
+    return this.evaluationService.stats();
+  }
+
+  @McpTool({
+    name: 'lms.evaluations.filter-options',
+    description: 'Returns available filter options for the evaluations list (courses, instructors, evaluators).',
+    inputSchema: { type: 'object', properties: {} },
+    readOnly: true,
+  })
+  async getFilterOptions(_args: Record<string, any>, _context: McpContext): Promise<any> {
+    return this.evaluationService.filterOptions();
+  }
+
+  @McpTool({
+    name: 'lms.evaluations.topics.list',
+    description: 'Lists evaluation topics with optional pagination and filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page: { type: 'number', description: 'Page number' },
+        pageSize: { type: 'number', description: 'Items per page' },
+        search: { type: 'string', description: 'Search term' },
+        targetType: { type: 'string', description: 'Filter by target type' },
+      },
+    },
+    readOnly: true,
+  })
+  async listTopics(args: Record<string, any>, _context: McpContext): Promise<any> {
+    return this.evaluationService.listTopics(args);
+  }
+
+  @McpTool({
+    name: 'lms.evaluations.topics.get',
+    description: 'Returns a single evaluation topic by ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Topic ID' },
+      },
+      required: ['id'],
+    },
+    readOnly: true,
+  })
+  async getTopic(args: { id: number }, _context: McpContext): Promise<any> {
+    return this.evaluationService.getTopicById(args.id);
+  }
+
+  @McpTool({
+    name: 'lms.evaluations.topics.create',
+    description: 'Creates a new evaluation topic.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Topic name (required, max 255)' },
+        description: { type: 'string', description: 'Topic description' },
+        targetType: { type: 'string', description: 'Target type (COURSE|COURSE_LESSON|COURSE_CLASS_SESSION|QUESTION|EXAM)' },
+        order: { type: 'number', description: 'Display order' },
+        isActive: { type: 'boolean', description: 'Whether the topic is active' },
+      },
+      required: ['name', 'targetType'],
+    },
+  })
+  async createTopic(args: Record<string, any>, _context: McpContext): Promise<any> {
+    return this.evaluationService.createTopic(args as any);
+  }
+
+  @McpTool({
+    name: 'lms.evaluations.topics.update',
+    description: 'Updates an existing evaluation topic.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Topic ID' },
+        name: { type: 'string', description: 'Topic name' },
+        description: { type: 'string', description: 'Topic description' },
+        targetType: { type: 'string', description: 'Target type' },
+        order: { type: 'number', description: 'Display order' },
+        isActive: { type: 'boolean', description: 'Whether the topic is active' },
+      },
+      required: ['id'],
+    },
+  })
+  async updateTopic(args: { id: number; [key: string]: any }, _context: McpContext): Promise<any> {
+    const { id, ...dto } = args;
+    return this.evaluationService.updateTopic(id, dto as any);
+  }
+
+  @McpTool({
+    name: 'lms.evaluations.topics.delete',
+    description: 'Deletes an evaluation topic by ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Topic ID' },
+      },
+      required: ['id'],
+    },
+  })
+  async deleteTopic(args: { id: number }, _context: McpContext): Promise<any> {
+    return this.evaluationService.deleteTopic(args.id);
+  }
+
+  @McpTool({
+    name: 'lms.evaluations.topics.reorder',
+    description: 'Reorders evaluation topics.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ids: { type: 'array', description: 'Topic IDs in the desired order', items: { type: 'number' } },
+      },
+      required: ['ids'],
+    },
+  })
+  async reorderTopics(args: { ids: number[] }, _context: McpContext): Promise<any> {
+    return this.evaluationService.reorderTopics(args.ids);
+  }
+}

package/src/evaluation/evaluation.module.ts

@@ -1,12 +1,13 @@
 import { PrismaModule } from '@hed-hog/api-prisma';
 import { forwardRef, Module } from '@nestjs/common';
 import { EvaluationController } from './evaluation.controller';
+import { LmsEvaluationMcpTools } from './evaluation.mcp-tools';
 import { EvaluationService } from './evaluation.service';
 
 @Module({
   imports: [forwardRef(() => PrismaModule)],
   controllers: [EvaluationController],
-  providers: [EvaluationService],
+  providers: [EvaluationService, LmsEvaluationMcpTools],
   exports: [forwardRef(() => EvaluationService)],
 })
 export class EvaluationModule {}

package/src/evaluation/evaluation.service.ts

@@ -114,7 +114,14 @@ export class EvaluationService {
       sessionWhere.course_class_group_id = params.classId;
     }
     if (params.instructorId) {
-      sessionWhere.course_class_group = { instructor_id: params.instructorId };
+      sessionWhere.OR = [
+        { course_class_group: { instructor_id: params.instructorId } },
+        {
+          course_class_session_instructor: {
+            some: { instructor_id: params.instructorId },
+          },
+        },
+      ];
     }
     if (Object.keys(sessionWhere).length > 0) {
       topicWhere.course_class_session = sessionWhere;
@@ -252,7 +259,7 @@ export class EvaluationService {
         }
         if (group.instructor?.person) {
           instructorName = group.instructor.person.name;
-          instructorId = group.instructor.person.id;
+          instructorId = group.instructor.id;
         }
       }
     } else if (targetType === 'question' && topic.question) {

package/src/exam/dto/create-exam-question.dto.ts

@@ -68,10 +68,18 @@ export class MatchingPairDto {
 }
 
 export class CreateExamQuestionDto {
+  @IsInt()
+  @Min(1)
+  subjectId: number;
+
   @IsString()
   @IsNotEmpty()
   statement: string;
 
+  @IsString()
+  @IsOptional()
+  explanation?: string;
+
   @IsString()
   @IsIn(EXAM_QUESTION_TYPES)
   @IsOptional()

package/src/exam/dto/create-exam.dto.ts

@@ -25,6 +25,14 @@ export class CreateExamDto {
   @IsOptional()
   shuffle?: boolean;
 
+  @IsBoolean()
+  @IsOptional()
+  showAnswerKeyAfterFinish?: boolean;
+
+  @IsEnum(['beginner', 'intermediate', 'advanced'])
+  @IsOptional()
+  level?: 'beginner' | 'intermediate' | 'advanced';
+
   @IsEnum(['draft', 'published', 'closed', 'archived'])
   @IsOptional()
   status?: 'draft' | 'published' | 'closed' | 'archived';

package/src/exam/dto/create-question-subject.dto.ts

@@ -0,0 +1,12 @@
+import { IsNotEmpty, IsOptional, IsString, MaxLength } from 'class-validator';
+
+export class CreateQuestionSubjectDto {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  name: string;
+
+  @IsString()
+  @IsOptional()
+  description?: string;
+}

package/src/exam/exam-attempt.service.ts

@@ -1,8 +1,11 @@
 import { PrismaService } from '@hed-hog/api-prisma';
+import { IntegrationDeveloperApiService } from '@hed-hog/core';
 import {
     BadRequestException,
+    Inject,
     Injectable,
     NotFoundException,
+    forwardRef,
 } from '@nestjs/common';
 import {
     OBJECTIVE_EXAM_QUESTION_TYPES,
@@ -14,7 +17,11 @@ import { SubmitExamAttemptDto } from './dto/submit-exam-attempt.dto';
 
 @Injectable()
 export class ExamAttemptService {
-  constructor(private readonly prisma: PrismaService) {}
+  constructor(
+    private readonly prisma: PrismaService,
+    @Inject(forwardRef(() => IntegrationDeveloperApiService))
+    private readonly integrationApi: IntegrationDeveloperApiService,
+  ) {}
 
   async getAttemptState(
     examId: number,
@@ -117,6 +124,26 @@ export class ExamAttemptService {
     await this.persistAnswers(attempt.id, exam, dto.answers ?? []);
     const completed = await this.completeAttempt(exam, attempt.id, dto.force ?? false);
 
+    const minScore = exam.min_score ?? 0;
+    const passed = completed.score !== null && completed.score !== undefined
+      ? completed.score >= minScore
+      : null;
+
+    await this.integrationApi.publishEvent({
+      eventName: 'lms.exam.attempt.submitted',
+      sourceModule: 'lms',
+      aggregateType: 'exam_attempt',
+      aggregateId: String(completed.id),
+      payload: {
+        examId: exam.id,
+        attemptId: completed.id,
+        studentId,
+        score: completed.score ?? null,
+        passed,
+        attemptNumber: completed.attempt_number,
+      },
+    }).catch(() => null);
+
     return this.buildAttemptPayload(exam, studentId, completed);
   }
 
@@ -435,6 +462,7 @@ export class ExamAttemptService {
           exam.require_all_questions_answered_to_finish,
         ),
         showResult: Boolean(exam.show_result ?? true),
+        showAnswerKeyAfterFinish: Boolean(exam.show_answer_key ?? false),
       },
       attempts: {
         allowed: attemptsAllowed,
@@ -496,19 +524,23 @@ export class ExamAttemptService {
         const answer = answersByQuestion.get(item.question_id);
         return this.requiresManualReview(item.question?.question_type) && Boolean(answer);
       }).length,
-      answersSummary: (exam.exam_question ?? []).map((item: any) => {
-        const answer = answersByQuestion.get(item.question_id);
-        return {
-          questionId: item.question_id,
-          hasAnswer: Boolean(answer),
-          isCorrect:
-            typeof answer?.is_correct === 'boolean' ? Boolean(answer.is_correct) : null,
-          pointsAwarded: answer?.points_awarded ?? 0,
-          requiresManualReview: this.requiresManualReview(
-            item.question?.question_type,
-          ),
-        };
-      }),
+      answersSummary: Boolean(exam.show_answer_key ?? false)
+        ? (exam.exam_question ?? []).map((item: any) => {
+            const answer = answersByQuestion.get(item.question_id);
+            return {
+              questionId: item.question_id,
+              hasAnswer: Boolean(answer),
+              isCorrect:
+                typeof answer?.is_correct === 'boolean'
+                  ? Boolean(answer.is_correct)
+                  : null,
+              pointsAwarded: answer?.points_awarded ?? 0,
+              requiresManualReview: this.requiresManualReview(
+                item.question?.question_type,
+              ),
+            };
+          })
+        : [],
     };
   }