@studious-lms/server 1.2.53 → 1.3.0

package/src/services/worksheet.ts

@@ -0,0 +1,358 @@
+/**
+ * Worksheet service – CRUD for worksheets, questions, submissions, and AI grading.
+ * Integrates with gradeWorksheet pipeline for auto-grading.
+ */
+import { TRPCError } from "@trpc/server";
+import { GenerationStatus, type WorksheetQuestionType } from "@prisma/client";
+import { prisma } from "../lib/prisma.js";
+import { cancelGradePipeline, regradeWorksheetPipeline } from "../pipelines/gradeWorksheet.js";
+import {
+  findWorksheetById,
+  findWorksheetByIdMinimal,
+  findWorksheetsByClassId,
+  createWorksheet,
+  updateWorksheet,
+  deleteWorksheet,
+  findQuestionsByWorksheetId,
+  createWorksheetQuestion,
+  updateWorksheetQuestion,
+  deleteWorksheetQuestion,
+  findSubmissionById,
+  findOrCreateWorksheetResponse,
+  findWorksheetResponseWithResponses,
+  findWorksheetQuestionById,
+  updateStudentQuestionProgress,
+  createStudentQuestionProgress,
+  findStudentQuestionProgress,
+  updateStudentQuestionProgressForGrading,
+  createStudentQuestionProgressForGrading,
+  createComment,
+} from "../models/worksheet.js";
+
+type MCQOptions = { id: string; text: string; isCorrect: boolean }[];
+
+/** Get worksheet with questions and mark schemes. */
+export async function getWorksheet(worksheetId: string) {
+  const worksheet = await findWorksheetById(worksheetId);
+  if (!worksheet) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Worksheet not found",
+    });
+  }
+  return worksheet;
+}
+
+/** Check if worksheet exists. */
+export async function worksheetExists(id: string) {
+  const worksheet = await findWorksheetByIdMinimal(id);
+  return !!worksheet;
+}
+
+export async function listWorksheets(classId: string) {
+  const worksheets = await findWorksheetsByClassId(classId);
+  return worksheets.map((w) => ({
+    ...w,
+    questionCount: w.questions.length,
+  }));
+}
+
+export async function updateWorksheetRecord(
+  worksheetId: string,
+  data: { name?: string }
+) {
+  return updateWorksheet(worksheetId, data);
+}
+
+export async function deleteWorksheetRecord(worksheetId: string) {
+  return deleteWorksheet(worksheetId);
+}
+
+export async function createWorksheetRecord(classId: string, name: string) {
+  return createWorksheet({ classId, name });
+}
+
+export async function addQuestionToWorksheet(
+  worksheetId: string,
+  data: {
+    question: string;
+    answer: string;
+    points?: number;
+    options?: object;
+    markScheme?: object;
+    type: WorksheetQuestionType;
+  }
+) {
+  const worksheet = await findWorksheetByIdMinimal(worksheetId);
+  if (!worksheet) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Worksheet not found",
+    });
+  }
+  return createWorksheetQuestion({
+    worksheetId,
+    ...data,
+  });
+}
+
+export async function reorderWorksheetQuestions(
+  worksheetId: string,
+  movedId: string,
+  position: "before" | "after",
+  targetId: string
+) {
+  const worksheet = await findWorksheetByIdMinimal(worksheetId);
+  if (!worksheet) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Worksheet not found",
+    });
+  }
+
+  const questions = await findQuestionsByWorksheetId(worksheetId);
+  const movedIdx = questions.findIndex((q) => q.id === movedId);
+  if (movedIdx === -1) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Moved question not found",
+    });
+  }
+  const targetIdx = questions.findIndex((q) => q.id === targetId);
+  if (targetIdx === -1) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Target question not found",
+    });
+  }
+
+  const withoutMoved = questions.filter((q) => q.id !== movedId);
+  const next =
+    position === "before"
+      ? [
+          ...withoutMoved.slice(0, targetIdx).map((item) => ({ id: item.id })),
+          { id: movedId },
+          ...withoutMoved.slice(targetIdx).map((item) => ({ id: item.id })),
+        ]
+      : [
+          ...withoutMoved
+            .slice(0, targetIdx + 1)
+            .map((item) => ({ id: item.id })),
+          { id: movedId },
+          ...withoutMoved
+            .slice(targetIdx + 1)
+            .map((item) => ({ id: item.id })),
+        ];
+
+  await prisma.$transaction(
+    next.map((item, index) =>
+      prisma.worksheetQuestion.update({
+        where: { id: item.id },
+        data: { order: index },
+      })
+    )
+  );
+  return next;
+}
+
+export async function updateWorksheetQuestionRecord(
+  worksheetId: string,
+  questionId: string,
+  data: {
+    question?: string;
+    answer?: string;
+    points?: number;
+    options?: object;
+    markScheme?: object;
+    type?: WorksheetQuestionType;
+  }
+) {
+  const worksheet = await findWorksheetByIdMinimal(worksheetId);
+  if (!worksheet) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Worksheet not found",
+    });
+  }
+  return updateWorksheetQuestion(questionId, data);
+}
+
+export async function deleteWorksheetQuestionRecord(
+  worksheetId: string,
+  questionId: string
+) {
+  const worksheet = await findWorksheetByIdMinimal(worksheetId);
+  if (!worksheet) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Worksheet not found",
+    });
+  }
+  return deleteWorksheetQuestion(questionId);
+}
+
+export async function getWorksheetSubmission(
+  worksheetId: string,
+  submissionId: string
+) {
+  const submission = await findSubmissionById(submissionId);
+  if (!submission) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Submission not found",
+    });
+  }
+  return findOrCreateWorksheetResponse(
+    submissionId,
+    worksheetId,
+    submission.studentId
+  );
+}
+
+export async function answerWorksheetQuestion(
+  worksheetResponseId: string,
+  questionId: string,
+  response: string,
+  userId: string
+) {
+  const worksheetResponse = await findWorksheetResponseWithResponses(
+    worksheetResponseId,
+    questionId
+  );
+  if (!worksheetResponse) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Worksheet response not found",
+    });
+  }
+
+  const question = await findWorksheetQuestionById(questionId);
+  const isMarkableByAlgo =
+    question?.type === "MULTIPLE_CHOICE" || question?.type === "TRUE_FALSE";
+  const marksAwardedIfCorrect = question?.points || 0;
+  const correctAnswer = isMarkableByAlgo
+    ? question?.type === "MULTIPLE_CHOICE"
+      ? (question?.options as MCQOptions)?.find((o) => o.isCorrect)?.id
+      : question?.answer?.toString()
+    : null;
+
+  const existingResponse = worksheetResponse.responses[0];
+
+  if (existingResponse) {
+    await updateStudentQuestionProgress(existingResponse.id, {
+      response,
+      ...(isMarkableByAlgo && {
+        isCorrect: response === correctAnswer,
+      }),
+      ...(isMarkableByAlgo && {
+        points: response === correctAnswer ? marksAwardedIfCorrect : 0,
+      }),
+      status: GenerationStatus.NOT_STARTED,
+    });
+  } else {
+    await createStudentQuestionProgress({
+      studentId: worksheetResponse.studentId,
+      questionId,
+      response,
+      studentWorksheetResponseId: worksheetResponseId,
+      ...(isMarkableByAlgo && {
+        isCorrect: response === correctAnswer,
+      }),
+      ...(isMarkableByAlgo && {
+        points: response === correctAnswer ? marksAwardedIfCorrect : 0,
+      }),
+    });
+  }
+
+  const updated = await prisma.studentWorksheetResponse.findUnique({
+    where: { id: worksheetResponseId },
+    include: { responses: true },
+  });
+  return updated!;
+}
+
+export async function cancelGrading(
+  worksheetResponseId: string,
+  progressId: string
+) {
+  return cancelGradePipeline(worksheetResponseId, progressId);
+}
+
+export async function regradeQuestion(
+  worksheetResponseId: string,
+  progressId: string
+) {
+  return regradeWorksheetPipeline(worksheetResponseId, progressId);
+}
+
+export async function gradeAnswer(
+  questionId: string,
+  studentWorksheetResponseId: string,
+  data: {
+    responseId?: string;
+    response?: string;
+    isCorrect: boolean;
+    feedback?: string;
+    markschemeState?: object;
+    points?: number;
+  }
+) {
+  if (data.responseId) {
+    return updateStudentQuestionProgressForGrading(data.responseId, {
+      isCorrect: data.isCorrect,
+      feedback: data.feedback,
+      markschemeState: data.markschemeState,
+      points: data.points,
+    });
+  }
+
+  const worksheetResponse = await prisma.studentWorksheetResponse.findUnique({
+    where: { id: studentWorksheetResponseId },
+    select: { studentId: true },
+  });
+  if (!worksheetResponse) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Student worksheet response not found",
+    });
+  }
+
+  const existing = await findStudentQuestionProgress(
+    worksheetResponse.studentId,
+    questionId,
+    studentWorksheetResponseId
+  );
+
+  if (existing) {
+    return updateStudentQuestionProgressForGrading(existing.id, {
+      isCorrect: data.isCorrect,
+      response: data.response,
+      feedback: data.feedback,
+      markschemeState: data.markschemeState,
+      points: data.points,
+    });
+  }
+
+  return createStudentQuestionProgressForGrading({
+    studentId: worksheetResponse.studentId,
+    questionId,
+    studentWorksheetResponseId,
+    response: data.response || "",
+    isCorrect: data.isCorrect,
+    feedback: data.feedback,
+    markschemeState: data.markschemeState,
+    points: data.points || 0,
+  });
+}
+
+export async function addCommentToResponse(
+  responseId: string,
+  comment: string,
+  authorId: string
+) {
+  return createComment({
+    studentQuestionProgressId: responseId,
+    content: comment,
+    authorId,
+  });
+}

package/src/utils/aiUser.ts

@@ -1,11 +1,12 @@
+/**
+ * AI user util – ensures AI assistant user exists, provides ID and isAIUser check.
+ */
 import { prisma } from '../lib/prisma.js';
 import { logger } from './logger.js';
 
 const AI_USER_ID = 'AI_ASSISTANT';
 
-/**
- * Ensure AI assistant user exists in the database
- */
+/** Ensure AI assistant user exists in the database. */
 export async function ensureAIUserExists(): Promise<void> {
   try {
     // Check if AI user already exists

package/src/utils/email.ts

@@ -1,8 +1,10 @@
+/**
+ * Email util – nodemailer transport and sendMail wrapper. Supports EMAIL_DRY_RUN.
+ */
 import nodemailer from 'nodemailer';
 import { env } from '../lib/config/env.js';
 import { logger } from './logger.js';
 
-
 type sendMailProps = {
   from: string;
   to: string;
@@ -13,7 +15,7 @@ type sendMailProps = {
 
 export const transport = nodemailer.createTransport({
     host: env.EMAIL_HOST,
-    port: 587,
+    port: env.EMAIL_PORT,
     secure: false,
     auth: {
       user: env.EMAIL_USER,
@@ -30,7 +32,7 @@ export const sendMail = async ({ from, to, subject, text }: sendMailProps) => {
   }
   
   await transport.sendMail({
-    from,
+    from: `"Studious" <${from}>`,
     to,
     subject,
     text,

package/src/utils/generateInviteCode.ts

@@ -1,8 +1,6 @@
 /**
- * Generates a random invite code
- * @returns {string} The invite code with length 5
+ * Generate invite code util – random 5-char alphanumeric code for class invites.
  */
-
 export const generateInviteCode = () => {
     return (Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15)).slice(0, 5);
 }

package/src/utils/inference.ts

@@ -1,7 +1,10 @@
+/**
+ * Inference util – OpenAI client, inference() for structured output, sendAIMessage for chat.
+ */
 import OpenAI from 'openai';
 import { logger } from './logger.js';
 import { prisma } from '../lib/prisma.js';
-import { pusher } from '../lib/pusher.js';
+import { chatChannel, pusher } from '../lib/pusher.js';
 import { ensureAIUserExists, getAIUserId } from './aiUser.js';
 import { env } from '../lib/config/env.js';
 import { ZodSchema } from 'zod';
@@ -103,7 +106,7 @@ export async function sendAIMessage(
 
   // Broadcast via Pusher
   try {
-    await pusher.trigger(`conversation-${conversationId}`, 'new-message', {
+    await pusher.trigger(chatChannel(conversationId), 'new-message', {
       id: aiMessage.id,
       content: aiMessage.content,
       senderId: getAIUserId(),

package/src/utils/logger.ts

@@ -1,4 +1,6 @@
-
+/**
+ * Logger util – structured logging with levels, modes, and colored output.
+ */
 export enum LogLevel {
   INFO = 'info',
   WARN = 'warn',

package/src/utils/prismaErrorHandler.ts

@@ -1,3 +1,6 @@
+/**
+ * Prisma error handler – maps Prisma errors to user-friendly messages and tRPC codes.
+ */
 import { 
   PrismaClientKnownRequestError, 
   PrismaClientUnknownRequestError, 

package/src/utils/prismaWrapper.ts

@@ -1,6 +1,10 @@
+/**
+ * Prisma wrapper – wraps Prisma operations with error handling and tRPC error mapping.
+ */
 import { TRPCError } from '@trpc/server';
 import { handlePrismaError } from './prismaErrorHandler.js';
 
+/** Execute a Prisma operation and convert errors to tRPC errors. */
 export async function withPrismaErrorHandling<T>(
   operation: () => Promise<T>,
   context: string = 'database operation'

package/tests/globalSetup.ts

@@ -0,0 +1,62 @@
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import type { TestProject } from 'vitest/node';
+
+config({ path: resolve(process.cwd(), '.env.test'), override: true });
+
+import { prisma } from '../src/lib/prisma';
+import { appRouter } from '../src/routers/_app';
+import { createTRPCContext } from '../src/trpc';
+import { clearDatabase } from '../src/seedDatabase';
+import { execSync } from 'child_process';
+
+async function runSetup() {
+  const ctx = await createTRPCContext({
+    req: { headers: {} } as any,
+    res: {} as any,
+  });
+  const caller = appRouter.createCaller(ctx);
+
+  execSync('npm run test:pre');
+
+  const user1 = await caller.auth.register({
+    username: 'testuser1',
+    email: 'test@studious.sh',
+    password: 'password_is_1234',
+    confirmPassword: 'password_is_1234',
+  });
+
+  const user2 = await caller.auth.register({
+    username: 'testuser2',
+    email: 'test2@studious.sh',
+    password: 'password_is_1234',
+    confirmPassword: 'password_is_1234',
+  });
+
+  const user3 = await caller.auth.register({
+    username: 'testuser3',
+    email: 'test3@studious.sh',
+    password: 'password_is_1234',
+    confirmPassword: 'password_is_1234',
+  });
+
+  const session1 = await prisma.session.findFirst({ where: { userId: user1.user.id } });
+  const session2 = await prisma.session.findFirst({ where: { userId: user2.user.id } });
+  const session3 = await prisma.session.findFirst({ where: { userId: user3.user.id } });
+
+  if (!session1 || !session2 || !session3) {
+    throw new Error('Failed to create sessions for test users');
+  }
+
+  await caller.auth.verify({ token: session1.id });
+  await caller.auth.verify({ token: session2.id });
+  await caller.auth.verify({ token: session3.id });
+
+  await prisma.$disconnect();
+}
+
+export default async function setup(project: TestProject) {
+  project.onTestsRerun(runSetup);
+  await runSetup();
+}
+

package/tests/helpers.ts

@@ -0,0 +1,22 @@
+import { createTRPCContext } from '../src/trpc';
+import { appRouter } from '../src/routers/_app';
+
+export async function createUnauthCaller() {
+  const ctx = await createTRPCContext({
+    req: { headers: {} } as any,
+    res: {} as any,
+  });
+  return appRouter.createCaller(ctx);
+}
+
+export const expectRejects = (fn: () => Promise<unknown>) =>
+  expect(fn()).rejects.toThrow();
+
+/** Expect a call to throw (e.g. unauthenticated). */
+export async function expectUnauth(call: (caller: Awaited<ReturnType<typeof createUnauthCaller>>) => Promise<unknown>) {
+  const unauth = await createUnauthCaller();
+  await expectRejects(() => call(unauth));
+}
+
+/** Expect a call to throw (e.g. not teacher, not member, forbidden). Same as expectRejects but semantic. */
+export const expectForbidden = expectRejects;

package/tests/middleware/security.test.ts

@@ -0,0 +1,42 @@
+import { describe, test, expect, beforeEach } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+import {
+  generalLimiter,
+  authLimiter,
+  uploadLimiter,
+  helmetConfig,
+} from '../../src/middleware/security.js';
+
+describe('security middleware', () => {
+  test('exports all middleware', () => {
+    expect(typeof generalLimiter).toBe('function');
+    expect(typeof authLimiter).toBe('function');
+    expect(typeof uploadLimiter).toBe('function');
+    expect(typeof helmetConfig).toBe('function');
+  });
+
+  describe('generalLimiter skip logic', () => {
+    let app: express.Application;
+
+    beforeEach(() => {
+      app = express();
+      app.use(generalLimiter);
+      app.get('/health', (_req, res) => res.status(200).json({ ok: true }));
+      app.get('/api/test', (_req, res) => res.status(200).json({ ok: true }));
+    });
+
+    test('/health is not rate limited (skip)', async () => {
+      const requests = Array(15)
+        .fill(null)
+        .map(() => request(app).get('/health'));
+      const responses = await Promise.all(requests);
+      expect(responses.every((r) => r.status === 200)).toBe(true);
+    });
+
+    test('OPTIONS is skipped', async () => {
+      const res = await request(app).options('/api/test');
+      expect(res.status).not.toBe(429);
+    });
+  });
+});