@studious-lms/server 1.1.24 → 1.2.6

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/trpc.ts

@@ -7,6 +7,7 @@ import { createAuthMiddleware } from './middleware/auth.js';
 import { Request, Response } from 'express';
 import { z } from 'zod';
 import { handlePrismaError, PrismaErrorInfo } from './utils/prismaErrorHandler.js';
+import { generalLimiter } from './middleware/security.js';
 
 interface CreateContextOptions {
   req: Request;
@@ -89,11 +90,14 @@ const { isAuthed, isMemberInClass, isTeacherInClass } = createAuthMiddleware(t);
 export const createTRPCRouter = t.router;
 export const publicProcedure = t.procedure.use(loggingMiddleware);
 
+
 // Protected procedures
 export const protectedProcedure = publicProcedure.use(isAuthed);
+
 export const protectedClassMemberProcedure = protectedProcedure
   .input(z.object({ classId: z.string() }).passthrough())
   .use(isMemberInClass);
+
 export const protectedTeacherProcedure = protectedProcedure
   .input(z.object({ classId: z.string() }).passthrough())
   .use(isTeacherInClass);

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,11 +1,40 @@
+/**
+ * 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;
+  subject: string;
+  text: string;
+};
+
 
 export const transport = nodemailer.createTransport({
-    host: process.env.EMAIL_HOST,
-    port: 587,
+    host: env.EMAIL_HOST,
+    port: env.EMAIL_PORT,
     secure: false,
     auth: {
-      user: process.env.EMAIL_USER,
-      pass: process.env.EMAIL_PASS,
+      user: env.EMAIL_USER,
+      pass: env.EMAIL_PASS,
     },
   });
+
+
+export const sendMail = async ({ from, to, subject, text }: sendMailProps) => {
+  // Wrapper function for sending emails
+  if (env.EMAIL_DRY_RUN == "true") {
+    logger.info(`Email dry run enabled. Would have sent email to ${to} from ${from} with subject ${subject} and text ${text}`);
+    return;
+  }
+  
+  await transport.sendMail({
+    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,19 +1,24 @@
+/**
+ * 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';
+import { zodTextFormat } from "openai/helpers/zod";
 
-// Initialize inference client (Cohere via OpenAI SDK)
 
-logger.info('Inference API Key', { apiKey: process.env.INFERENCE_API_KEY });
-logger.info('Inference API Base URL', { baseURL: process.env.INFERENCE_API_BASE_URL });
 
 export const inferenceClient = new OpenAI({
-  apiKey: process.env.INFERENCE_API_KEY,
-  baseURL: process.env.INFERENCE_API_BASE_URL,
+  apiKey: env.INFERENCE_API_KEY,
+  baseURL: env.INFERENCE_API_BASE_URL,
 });
 
+export const openAIClient = new OpenAI();
+
 // Types for lab chat context
 export interface LabChatContext {
   subject: string;
@@ -46,6 +51,7 @@ export async function sendAIMessage(
     attachments?: {
       connect: { id: string }[];
     };
+    meta?: Record<string, any>;
     customSender?: {
       displayName: string;
       profilePicture?: string | null;
@@ -57,6 +63,7 @@ export async function sendAIMessage(
   senderId: string;
   conversationId: string;
   createdAt: Date;
+  meta?: Record<string, any>;
 }> {
   // Ensure AI user exists
   await ensureAIUserExists();
@@ -72,6 +79,9 @@ export async function sendAIMessage(
           connect: options.attachments.connect,
         },
       }),
+      ...(options.meta && {
+        meta: options.meta,
+      }),
     },
     include: {
       attachments: true,
@@ -96,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(),
@@ -104,6 +114,7 @@ export async function sendAIMessage(
       createdAt: aiMessage.createdAt,
       sender: senderInfo,
       mentionedUserIds: [],
+      meta: aiMessage.meta,
       attachments: aiMessage.attachments.map(attachment => ({
         id: attachment.id,
         attachmentId: attachment.id,
@@ -123,9 +134,77 @@ export async function sendAIMessage(
     senderId: getAIUserId(),
     conversationId: aiMessage.conversationId,
     createdAt: aiMessage.createdAt,
+    meta: aiMessage.meta as Record<string, any>,
   };
 }
 
+export async function inference<T>(
+  content: string | OpenAI.Chat.Completions.ChatCompletionMessageParam[],
+  format?: ZodSchema
+): Promise<T> {
+  try {
+
+    if (!format) {
+      const completion = await openAIClient.chat.completions.create({
+        model: 'gpt-5-nano',
+        messages: typeof content === 'string' ? [
+          {
+            role: 'user',
+            content: content,
+          },
+        ] : content as Array<{ role: 'user' | 'assistant' | 'system'; content: string }>,
+      });
+
+      return completion.choices[0]?.message?.content as T;
+    }
+
+    const completion = await openAIClient.responses.parse({
+      model: 'gpt-5-nano',
+      input: typeof content === 'string' ? [
+        {
+          role: 'user',
+          content: content,
+        },
+      ] : content as Array<{ role: 'user' | 'assistant' | 'system'; content: string }>,
+      ...(format ? { text: {
+          format: zodTextFormat(format, "newton_response_format"),
+        },
+      } : {}),
+    });
+
+    console.log({
+      model: 'gpt-5-nano',
+      input: typeof content === 'string' ? [
+        {
+          role: 'user',
+          content: content,
+        },
+      ] : content as Array<{ role: 'user' | 'assistant' | 'system'; content: string }>,
+      ...(format ? { text: {
+          format: zodTextFormat(format, "newton_response_format"),
+        },
+      } : {}),
+    });
+
+
+    if (!completion) {
+      throw new Error('No response generated from inference API');
+    }
+
+    // if (format) {
+    //   if (typeof completion.output === 'string') {
+    //     return JSON.parse(completion.output);
+    //   }
+    //   return JSON.parse(completion.output);
+    // }
+
+    return completion.output_parsed;
+  } catch (error) {
+    logger.error('Failed to generate inference response', { error });
+    throw error;
+  }
+}
+
 /**
  * Simple inference function for general use
  */
@@ -137,10 +216,10 @@ export async function generateInferenceResponse(
     maxTokens?: number;
   } = {}
 ): Promise<InferenceResponse> {
-  const { model = 'command-r-plus', maxTokens = 500 } = options;
+  const { model = 'gpt-5-nano', maxTokens = 500 } = options;
 
   try {
-    const completion = await inferenceClient.chat.completions.create({
+    const completion = await openAIClient.chat.completions.create({
       model,
       messages: [
         {
@@ -180,7 +259,7 @@ export async function generateInferenceResponse(
  * Validate inference configuration
  */
 export function validateInferenceConfig(): boolean {
-  if (!process.env.INFERENCE_API_KEY) {
+  if (!env.INFERENCE_API_KEY) {
     logger.error('Inference API key not configured for Cohere');
     return false;
   }

package/src/utils/logger.ts

@@ -1,3 +1,6 @@
+/**
+ * Logger util – structured logging with levels, modes, and colored output.
+ */
 export enum LogLevel {
   INFO = 'info',
   WARN = 'warn',
@@ -26,7 +29,24 @@ const colors = {
   magenta: '\x1b[35m',
   cyan: '\x1b[36m',
   white: '\x1b[37m',
-  gray: '\x1b[90m'
+  gray: '\x1b[90m',
+  // Background colors
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+  bgBlue: '\x1b[44m',
+  bgMagenta: '\x1b[45m',
+  bgCyan: '\x1b[46m',
+  bgWhite: '\x1b[47m',
+  bgGray: '\x1b[100m',
+  // Bright background colors
+  bgBrightRed: '\x1b[101m',
+  bgBrightGreen: '\x1b[102m',
+  bgBrightYellow: '\x1b[103m',
+  bgBrightBlue: '\x1b[104m',
+  bgBrightMagenta: '\x1b[105m',
+  bgBrightCyan: '\x1b[106m',
+  bgBrightWhite: '\x1b[107m'
 };
 
 class Logger {
@@ -34,6 +54,7 @@ class Logger {
   private isDevelopment: boolean;
   private mode: LogMode;
   private levelColors: Record<LogLevel, string>;
+  private levelBgColors: Record<LogLevel, string>;
   private levelEmojis: Record<LogLevel, string>;
 
   private constructor() {
@@ -41,7 +62,7 @@ class Logger {
     // this.isDevelopment = process.env.NODE_ENV === 'development';
     this.isDevelopment = true;
 
-    this.mode = (process.env.LOG_MODE as LogMode) || 'normal';
+    this.mode = (process.env.NODE_ENV === 'test' ? 'silent' : ((process.env.LOG_MODE as LogMode) || 'normal'));
     
 
     this.levelColors = {
@@ -51,6 +72,13 @@ class Logger {
       [LogLevel.DEBUG]: colors.magenta
     };
 
+    this.levelBgColors = {
+      [LogLevel.INFO]: colors.bgBlue,
+      [LogLevel.WARN]: colors.bgYellow,
+      [LogLevel.ERROR]: colors.bgRed,
+      [LogLevel.DEBUG]: colors.bgMagenta
+    };
+
     this.levelEmojis = {
       [LogLevel.INFO]: 'ℹ️',
       [LogLevel.WARN]: '⚠️',
@@ -95,10 +123,12 @@ class Logger {
   private formatMessage(logMessage: LogMessage): string {
     const { level, message, timestamp, context } = logMessage;
     const color = this.levelColors[level];
+    const bgColor = this.levelBgColors[level];
     const emoji = this.levelEmojis[level];
     
     const timestampStr = colors.gray + `[${timestamp}]` + colors.reset;
-    const levelStr = color + `[${level.toUpperCase()}]` + colors.reset;
+    // Use background color for level badge like Vitest
+    const levelStr = colors.white + bgColor + ` ${level.toUpperCase()} ` + colors.reset;
     const emojiStr = emoji + ' ';
     const messageStr = colors.bright + message + colors.reset;
     

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,