@studious-lms/server 1.19.0 → 1.21.0

package/src/pipelines/gradeWorksheet.ts

@@ -79,7 +79,11 @@ INSTRUCTIONS:
 - Mark isCorrect=true only if the student earned full or near-full marks.`;
 }
 
-const gradeWorksheetQuestion = async (worksheetResponseId: string, worksheetQuestionProgressId: string) => {
+const gradeWorksheetQuestion = async (
+    worksheetResponseId: string,
+    worksheetQuestionProgressId: string,
+    actingUserId?: string | null,
+) => {
 
     await removeAllPreviousAIComments(worksheetQuestionProgressId);
 
@@ -155,6 +159,10 @@ const gradeWorksheetQuestion = async (worksheetResponseId: string, worksheetQues
                     questionId: worksheetQuestionProgressId,
                     studentId: worksheetResponse.studentId,
                 },
+                attribution: {
+                    userId: actingUserId ?? worksheetResponse.studentId,
+                    classId: worksheetResponse.worksheet.classId,
+                },
             },
         ).catch((error) => {
             logger.error('Failed to grade worksheet response', { error });
@@ -259,7 +267,10 @@ const gradeWorksheetQuestion = async (worksheetResponseId: string, worksheetQues
 
 const DO_NOT_INFERENCE_STATUSES = [JobStatus.CANCELLED, JobStatus.PENDING, JobStatus.COMPLETED];
 
-export const gradeWorksheetPipeline = async (worksheetResponseId: string) => {
+export const gradeWorksheetPipeline = async (
+    worksheetResponseId: string,
+    actingUserId?: string | null,
+) => {
     logger.info('Grading worksheet response', { worksheetResponseId });
     const worksheetResponse = await prisma.studentWorksheetResponse.findUnique({
         where: { id: worksheetResponseId },
@@ -349,7 +360,7 @@ export const gradeWorksheetPipeline = async (worksheetResponseId: string) => {
         }
 
         try {
-            await gradeWorksheetQuestion(worksheetResponseId, response.id);
+            await gradeWorksheetQuestion(worksheetResponseId, response.id, actingUserId);
         } catch (questionError) {
             logger.error('Failed to grade individual question, continuing with remaining questions', {
                 questionId: response.questionId,
@@ -387,7 +398,10 @@ export const cancelGradePipeline = async (worksheetResponseId: string, worksheet
     return updatedStudentQuestionProgress;
 };
 
-export const regradeAllPipeline = async (worksheetResponseId: string) => {
+export const regradeAllPipeline = async (
+    worksheetResponseId: string,
+    actingUserId?: string | null,
+) => {
     logger.info('Regrading all questions for worksheet response', { worksheetResponseId });
     const worksheetResponse = await prisma.studentWorksheetResponse.findUnique({
         where: { id: worksheetResponseId },
@@ -434,7 +448,7 @@ export const regradeAllPipeline = async (worksheetResponseId: string) => {
     // Re-grade each question sequentially
     for (const response of worksheetResponse.responses) {
         try {
-            await gradeWorksheetQuestion(worksheetResponseId, response.id);
+            await gradeWorksheetQuestion(worksheetResponseId, response.id, actingUserId);
         } catch (questionError) {
             logger.error('Failed to regrade question, continuing with remaining', {
                 questionId: response.questionId,
@@ -444,7 +458,11 @@ export const regradeAllPipeline = async (worksheetResponseId: string) => {
     }
 };
 
-export const regradeWorksheetPipeline = async (worksheetResponseId: string, worksheetQuestionProgressId: string) => {
+export const regradeWorksheetPipeline = async (
+    worksheetResponseId: string,
+    worksheetQuestionProgressId: string,
+    actingUserId?: string | null,
+) => {
     logger.info('Regrading worksheet response', { worksheetResponseId, worksheetQuestionProgressId });
     try {
     const worksheetResponse = await prisma.studentWorksheetResponse.findUnique({
@@ -479,7 +497,7 @@ export const regradeWorksheetPipeline = async (worksheetResponseId: string, work
         where: { id: worksheetQuestionProgressId },
     });
 
-    await gradeWorksheetQuestion(worksheetResponseId, worksheetQuestionProgressId);
+    await gradeWorksheetQuestion(worksheetResponseId, worksheetQuestionProgressId, actingUserId);
 
     return updatedStudentQuestionProgress;
     } catch (error) {

package/src/pipelines/pdfToWorksheet.ts

@@ -179,6 +179,8 @@ export interface PdfToWorksheetOptions {
    * channel. This is the path used by the BullMQ worker.
    */
   worksheetId?: string;
+  /** Acting user for AI usage attribution. */
+  userId?: string | null;
 }
 
 /**
@@ -265,6 +267,7 @@ export async function pdfToWorksheet(
           classId,
           filename,
         },
+        attribution: { userId: options.userId, classId },
       }
     );
   } catch (error) {

package/src/routers/announcement.ts

@@ -21,7 +21,6 @@ import { getReactions as getCommentReactions } from "../services/comment.js";
 import { logger } from "../utils/logger.js";
 import { createDirectUploadFiles, type UploadedFile, type DirectUploadFile, confirmDirectUpload } from "../lib/fileUpload.js";
 import { deleteFile } from "../lib/googleCloudStorage.js";
-import { sendToMultiple } from "../services/notification.js";
 
 // Schema for direct file uploads (no base64 data)
 const directFileSchema = z.object({

package/src/routers/assignment.ts

@@ -180,6 +180,30 @@ const confirmAnnotationUploadSchema = z.object({
   errorMessage: z.string().optional(),
 });
 
+const listFileAnnotationsSchema = z.object({
+  classId: z.string(),
+  submissionId: z.string(),
+  fileId: z.string(),
+});
+
+const upsertFileAnnotationSchema = z.object({
+  classId: z.string(),
+  submissionId: z.string(),
+  fileId: z.string(),
+  id: z.string().optional(),
+  page: z.number().int().min(1),
+  type: z.enum(["HIGHLIGHT", "INK", "COMMENT", "TEXT"]),
+  geometry: z.record(z.string(), z.unknown()),
+  text: z.string().optional(),
+  color: z.string().optional(),
+});
+
+const deleteFileAnnotationSchema = z.object({
+  classId: z.string(),
+  submissionId: z.string(),
+  id: z.string(),
+});
+
 const updateUploadProgressSchema = z.object({
   fileId: z.string(),
   progress: z.number().min(0).max(100),
@@ -437,6 +461,11 @@ export const assignmentRouter = createTRPCRouter({
           receiverIds,
           title: `New comment on ${assignment.title}`,
           content: `${getCommenterName(comment)} commented in ${assignment.class.name}:\n\n${input.content}\n\n[View assignment](/class/${assignment.class.id}/assignments/${assignment.id})`,
+          senderId: authorId,
+          type: "COMMENT_REPLY",
+          entityType: "ASSIGNMENT",
+          entityId: assignment.id,
+          classId: assignment.class.id,
         }).catch((error) => {
           logger.error("Failed to send assignment comment notifications:", error);
         });
@@ -559,6 +588,11 @@ export const assignmentRouter = createTRPCRouter({
           receiverIds,
           title: `New private comment on ${submission.assignment.title}`,
           content: `${getCommenterName(comment)} commented on a submission in ${submission.assignment.class.name}:\n\n${input.content}\n\n[View submission](/class/${submission.assignment.class.id}/assignments/${submission.assignment.id}/submissions/${submission.id})`,
+          senderId: authorId,
+          type: "COMMENT_REPLY",
+          entityType: "ASSIGNMENT",
+          entityId: submission.assignment.id,
+          classId: submission.assignment.class.id,
         }).catch((error) => {
           logger.error("Failed to send submission comment notifications:", error);
         });
@@ -956,6 +990,186 @@ export const assignmentRouter = createTRPCRouter({
       };
     }),
 
+  listFileAnnotations: protectedClassMemberProcedure
+    .input(listFileAnnotationsSchema)
+    .query(async ({ ctx, input }) => {
+      const { classId, submissionId, fileId } = input;
+
+      const submission = await prisma.submission.findFirst({
+        where: {
+          id: submissionId,
+          assignment: { classId },
+        },
+        select: {
+          id: true,
+          studentId: true,
+          returned: true,
+          assignment: {
+            select: {
+              class: {
+                select: {
+                  teachers: { where: { id: ctx.user!.id }, select: { id: true } },
+                },
+              },
+            },
+          },
+        },
+      });
+
+      if (!submission) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "Submission not found",
+        });
+      }
+
+      const isTeacher = submission.assignment.class.teachers.length > 0;
+      const isOwningStudent = submission.studentId === ctx.user!.id;
+
+      if (!isTeacher && !(isOwningStudent && submission.returned)) {
+        throw new TRPCError({
+          code: "FORBIDDEN",
+          message: "You don't have access to these annotations",
+        });
+      }
+
+      const annotations = await prisma.fileAnnotation.findMany({
+        where: { submissionId, fileId },
+        orderBy: { createdAt: "asc" },
+        include: {
+          author: {
+            select: {
+              id: true,
+              username: true,
+              profile: { select: { displayName: true } },
+            },
+          },
+        },
+      });
+
+      return { annotations };
+    }),
+
+  upsertFileAnnotation: protectedTeacherProcedure
+    .input(upsertFileAnnotationSchema)
+    .mutation(async ({ ctx, input }) => {
+      const { classId, submissionId, fileId, id, page, type, geometry, text, color } = input;
+
+      const submission = await prisma.submission.findFirst({
+        where: {
+          id: submissionId,
+          assignment: {
+            classId,
+            class: {
+              teachers: {
+                some: { id: ctx.user!.id },
+              },
+            },
+          },
+        },
+        select: { id: true },
+      });
+
+      if (!submission) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "Submission not found or you are not a teacher of this class",
+        });
+      }
+
+      const file = await prisma.file.findFirst({
+        where: {
+          id: fileId,
+          OR: [{ submissionId }, { annotationId: submissionId }],
+        },
+        select: { id: true },
+      });
+
+      if (!file) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "File does not belong to this submission",
+        });
+      }
+
+      if (id) {
+        const existing = await prisma.fileAnnotation.findFirst({
+          where: { id, submissionId, fileId },
+          select: { id: true },
+        });
+
+        if (!existing) {
+          throw new TRPCError({
+            code: "NOT_FOUND",
+            message: "Annotation not found",
+          });
+        }
+
+        const annotation = await prisma.fileAnnotation.update({
+          where: { id },
+          data: {
+            page,
+            type,
+            geometry: geometry as object,
+            text: text ?? null,
+            color: color ?? null,
+          },
+        });
+
+        return { annotation };
+      }
+
+      const annotation = await prisma.fileAnnotation.create({
+        data: {
+          fileId,
+          submissionId,
+          authorId: ctx.user!.id,
+          page,
+          type,
+          geometry: geometry as object,
+          text: text ?? null,
+          color: color ?? null,
+        },
+      });
+
+      return { annotation };
+    }),
+
+  deleteFileAnnotation: protectedTeacherProcedure
+    .input(deleteFileAnnotationSchema)
+    .mutation(async ({ ctx, input }) => {
+      const { classId, submissionId, id } = input;
+
+      const annotation = await prisma.fileAnnotation.findFirst({
+        where: {
+          id,
+          submissionId,
+          submission: {
+            assignment: {
+              classId,
+              class: {
+                teachers: {
+                  some: { id: ctx.user!.id },
+                },
+              },
+            },
+          },
+        },
+        select: { id: true },
+      });
+
+      if (!annotation) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "Annotation not found or you are not a teacher of this class",
+        });
+      }
+
+      await prisma.fileAnnotation.delete({ where: { id } });
+
+      return { success: true };
+    }),
+
   updateUploadProgress: protectedProcedure
     .input(updateUploadProgressSchema)
     .mutation(async ({ ctx, input }) => {

package/src/routers/notifications.ts

@@ -3,41 +3,43 @@ import { z } from "zod";
 import {
   listNotifications,
   getNotification,
-  sendNotification,
-  sendToMultiple,
+  getUnreadCount,
   markAsRead,
+  markAllAsRead,
 } from "../services/notification.js";
 
+/**
+ * Read-only notification API. Notifications are emitted exclusively by
+ * server-side domain services — there is intentionally no public "send"
+ * endpoint (the previous sendTo/sendToMultiple procedures allowed any logged-in
+ * user to notify arbitrary users and were removed).
+ */
 export const notificationRouter = createTRPCRouter({
-  list: protectedProcedure.query(({ ctx }) =>
-    listNotifications(ctx.user!.id)
-  ),
+  list: protectedProcedure
+    .input(
+      z
+        .object({
+          limit: z.number().int().min(1).max(100).default(20),
+          cursor: z.string().nullish(),
+        })
+        .optional()
+    )
+    .query(({ ctx, input }) =>
+      listNotifications(ctx.user!.id, {
+        limit: input?.limit,
+        cursor: input?.cursor,
+      })
+    ),
 
   get: protectedProcedure
     .input(z.object({ id: z.string() }))
     .query(({ ctx, input }) => getNotification(ctx.user!.id, input.id)),
 
-  sendTo: protectedProcedure
-    .input(
-      z.object({
-        receiverId: z.string(),
-        title: z.string(),
-        content: z.string(),
-      })
-    )
-    .mutation(({ input }) => sendNotification(input)),
-
-  sendToMultiple: protectedProcedure
-    .input(
-      z.object({
-        receiverIds: z.array(z.string()),
-        title: z.string(),
-        content: z.string(),
-      })
-    )
-    .mutation(({ input }) => sendToMultiple(input)),
+  unreadCount: protectedProcedure.query(({ ctx }) => getUnreadCount(ctx.user!.id)),
 
   markAsRead: protectedProcedure
     .input(z.object({ id: z.string() }))
     .mutation(({ ctx, input }) => markAsRead(ctx.user!.id, input.id)),
+
+  markAllAsRead: protectedProcedure.mutation(({ ctx }) => markAllAsRead(ctx.user!.id)),
 });

package/src/routers/school.ts

@@ -27,6 +27,7 @@ import {
   updateMemberRole,
   updateSchoolDetails,
 } from "../services/school.js";
+import { getSchoolAiUsage } from "../services/aiUsage.js";
 
 const schoolRoleSchema = z.enum(["ADMIN", "TEACHER", "STUDENT"]);
 
@@ -142,6 +143,17 @@ export const schoolRouter = createTRPCRouter({
     .input(schoolIdSchema)
     .query(({ ctx, input }) => getAdminOverview(ctx.user!.id, input.schoolId)),
 
+  getAiUsage: protectedProcedure
+    .input(
+      z.object({
+        schoolId: z.string(),
+        startDate: z.date().optional(),
+        endDate: z.date().optional(),
+        topUsersLimit: z.number().min(1).max(50).optional(),
+      })
+    )
+    .query(({ ctx, input }) => getSchoolAiUsage(ctx.user!.id, input)),
+
   listClasses: protectedProcedure
     .input(schoolIdSchema)
     .query(({ ctx, input }) => listClasses(ctx.user!.id, input.schoolId)),

package/src/routers/user.ts

@@ -10,6 +10,7 @@ import {
   deleteUserAccount,
   exportUserData,
 } from "../services/userPrivacy.js";
+import { getMyAiUsage } from "../services/aiUsage.js";
 
 const fileUploadSchema = z.object({
   filePath: z.string().min(1, "File path is required"),
@@ -89,6 +90,17 @@ export const userRouter = createTRPCRouter({
     exportUserData(ctx.user!.id),
   ),
 
+  getMyAiUsage: protectedProcedure
+    .input(
+      z
+        .object({
+          startDate: z.date().optional(),
+          endDate: z.date().optional(),
+        })
+        .optional(),
+    )
+    .query(({ ctx, input }) => getMyAiUsage(ctx.user!.id, input ?? {})),
+
   deleteAccount: protectedProcedure
     .input(
       z.object({

package/src/services/aiChatStream.ts

@@ -16,6 +16,7 @@ import { openai } from '@ai-sdk/openai';
 import { getRedis } from '../lib/redis.js';
 import { pusher, chatChannel } from '../lib/pusher.js';
 import { logger } from '../utils/logger.js';
+import { logInferenceUsage, type AiUsageAttribution } from '../utils/inference.js';
 
 const STREAM_REDIS_TTL = 600; // 10 minutes
 const STREAM_KEY_PREFIX = 'stream:';
@@ -179,6 +180,10 @@ export interface StreamChatOptions {
   maxOutputTokens?: number;
   /** Max agent steps (tool round-trips). Defaults to 6. */
   maxSteps?: number;
+  /** Reason recorded on the AiUsageLog row. Defaults to 'chat_stream'. */
+  usageReason?: string;
+  /** Who/what this usage is attributed to (user / school / class). */
+  attribution?: AiUsageAttribution;
 }
 
 export interface StreamChatResult {
@@ -207,6 +212,8 @@ export async function streamChatResponse(
     temperature = 0.7,
     maxOutputTokens = 4096,
     maxSteps = 6,
+    usageReason = 'chat_stream',
+    attribution,
   } = options;
 
   const redis = getRedis();
@@ -332,7 +339,35 @@ export async function streamChatResponse(
       }
     }
 
+    const usage = await Promise.resolve(result.totalUsage).catch(() => undefined);
+    await logInferenceUsage({
+      model,
+      operation: 'stream.text',
+      success: true,
+      estimatedInputTokens: 0,
+      reason: usageReason,
+      usage: usage
+        ? {
+            promptTokens: usage.inputTokens,
+            completionTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+          }
+        : undefined,
+      attribution,
+    });
+
     return { text: fullText, toolCalls, parts };
+  } catch (error) {
+    await logInferenceUsage({
+      model,
+      operation: 'stream.text',
+      success: false,
+      estimatedInputTokens: 0,
+      reason: usageReason,
+      error,
+      attribution,
+    });
+    throw error;
   } finally {
     if (redis) {
       await redis.del(streamKey).catch(() => {});

package/src/services/aiStream.ts

@@ -8,6 +8,7 @@ import { getRedis } from '../lib/redis.js';
 import { prisma } from '../lib/prisma.js';
 import { pusher, chatChannel } from '../lib/pusher.js';
 import { getAIUserId, ensureAIUserExists } from '../utils/aiUser.js';
+import { logInferenceUsage, type AiUsageAttribution } from '../utils/inference.js';
 import { logger } from '../utils/logger.js';
 import { JobStatus } from '@prisma/client';
 import { aiTools, type ToolCallResult } from './aiTools.js';
@@ -25,6 +26,10 @@ export interface StreamOptions {
   model?: string;
   temperature?: number;
   maxOutputTokens?: number;
+  /** Reason recorded on the AiUsageLog row. Defaults to 'ai_stream'. */
+  usageReason?: string;
+  /** Who/what this usage is attributed to (user / school / class). */
+  attribution?: AiUsageAttribution;
 }
 
 /**
@@ -42,6 +47,8 @@ export async function streamAIResponse(options: StreamOptions): Promise<void> {
     model = 'gpt-4o-mini',
     temperature = 0.7,
     maxOutputTokens = 4096,
+    usageReason = 'ai_stream',
+    attribution,
   } = options;
 
   await ensureAIUserExists();
@@ -146,6 +153,23 @@ export async function streamAIResponse(options: StreamOptions): Promise<void> {
       attachments: [],
     });
 
+    const usage = await Promise.resolve(result.totalUsage).catch(() => undefined);
+    await logInferenceUsage({
+      model,
+      operation: 'stream.text',
+      success: true,
+      estimatedInputTokens: 0,
+      reason: usageReason,
+      usage: usage
+        ? {
+            promptTokens: usage.inputTokens,
+            completionTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+          }
+        : undefined,
+      attribution: attribution ?? { classId },
+    });
+
     logger.info('AI stream completed', {
       aiMessageId,
       conversationId,
@@ -155,6 +179,16 @@ export async function streamAIResponse(options: StreamOptions): Promise<void> {
   } catch (error) {
     logger.error('AI stream failed', { error, aiMessageId, conversationId });
 
+    await logInferenceUsage({
+      model,
+      operation: 'stream.text',
+      success: false,
+      estimatedInputTokens: 0,
+      reason: usageReason,
+      error,
+      attribution: attribution ?? { classId },
+    });
+
     await prisma.message.update({
       where: { id: aiMessageId },
       data: { status: JobStatus.FAILED },