@studious-lms/server 1.18.0 → 1.20.0

package/dist/workers/processors/gradeWorksheet.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1acdee19-3e17-56ee-ab44-55001b9460f2")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="777a2189-86f3-5317-9904-cac13606cce2")}catch(e){}}();
 import { gradeWorksheetPipeline } from '../../pipelines/gradeWorksheet.js';
 import { createRunJobWorker } from './createRunJobWorker.js';
 export const gradeWorksheetWorker = createRunJobWorker({
@@ -10,10 +10,10 @@ export const gradeWorksheetWorker = createRunJobWorker({
         // throughput modest until we measure real-world usage.
         limiter: { max: 5, duration: 60000 },
     },
-    run: async ({ worksheetResponseId }) => {
-        await gradeWorksheetPipeline(worksheetResponseId);
+    run: async ({ worksheetResponseId }, ctx) => {
+        await gradeWorksheetPipeline(worksheetResponseId, ctx.userId);
         return { worksheetResponseId };
     },
 });
 //# sourceMappingURL=gradeWorksheet.js.map
-//# debugId=1acdee19-3e17-56ee-ab44-55001b9460f2
+//# debugId=777a2189-86f3-5317-9904-cac13606cce2

package/dist/workers/processors/gradeWorksheet.js.map

@@ -1 +1 @@
-{"version":3,"file":"gradeWorksheet.js","sources":["workers/processors/gradeWorksheet.ts"],"sourceRoot":"/","sourcesContent":["import { gradeWorksheetPipeline } from '../../pipelines/gradeWorksheet.js';\nimport { createRunJobWorker } from './createRunJobWorker.js';\n\nexport const gradeWorksheetWorker = createRunJobWorker({\n  type: 'GRADE_WORKSHEET',\n  workerOptions: {\n    concurrency: 2,\n    // Each pipeline run can fan out to many per-question inferences; keep\n    // throughput modest until we measure real-world usage.\n    limiter: { max: 5, duration: 60_000 },\n  },\n  run: async ({ worksheetResponseId }) => {\n    await gradeWorksheetPipeline(worksheetResponseId);\n    return { worksheetResponseId };\n  },\n});\n"],"names":[],"mappings":";;AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;IACrD,IAAI,EAAE,iBAAiB;IACvB,aAAa,EAAE;QACb,WAAW,EAAE,CAAC;QACd,sEAAsE;QACtE,uDAAuD;QACvD,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAM,EAAE;KACtC;IACD,GAAG,EAAE,KAAK,EAAE,EAAE,mBAAmB,EAAE,EAAE,EAAE;QACrC,MAAM,sBAAsB,CAAC,mBAAmB,CAAC,CAAC;QAClD,OAAO,EAAE,mBAAmB,EAAE,CAAC;IACjC,CAAC;CACF,CAAC,CAAC","debug_id":"1acdee19-3e17-56ee-ab44-55001b9460f2"}
+{"version":3,"file":"gradeWorksheet.js","sources":["workers/processors/gradeWorksheet.ts"],"sourceRoot":"/","sourcesContent":["import { gradeWorksheetPipeline } from '../../pipelines/gradeWorksheet.js';\nimport { createRunJobWorker } from './createRunJobWorker.js';\n\nexport const gradeWorksheetWorker = createRunJobWorker({\n  type: 'GRADE_WORKSHEET',\n  workerOptions: {\n    concurrency: 2,\n    // Each pipeline run can fan out to many per-question inferences; keep\n    // throughput modest until we measure real-world usage.\n    limiter: { max: 5, duration: 60_000 },\n  },\n  run: async ({ worksheetResponseId }, ctx) => {\n    await gradeWorksheetPipeline(worksheetResponseId, ctx.userId);\n    return { worksheetResponseId };\n  },\n});\n"],"names":[],"mappings":";;AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;IACrD,IAAI,EAAE,iBAAiB;IACvB,aAAa,EAAE;QACb,WAAW,EAAE,CAAC;QACd,sEAAsE;QACtE,uDAAuD;QACvD,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAM,EAAE;KACtC;IACD,GAAG,EAAE,KAAK,EAAE,EAAE,mBAAmB,EAAE,EAAE,GAAG,EAAE,EAAE;QAC1C,MAAM,sBAAsB,CAAC,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC9D,OAAO,EAAE,mBAAmB,EAAE,CAAC;IACjC,CAAC;CACF,CAAC,CAAC","debug_id":"777a2189-86f3-5317-9904-cac13606cce2"}

package/dist/workers/processors/pdfToWorksheet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pdfToWorksheet.d.ts","sourceRoot":"/","sources":["workers/processors/pdfToWorksheet.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,oBAAoB;;;;;;eAa/B,CAAC"}
+{"version":3,"file":"pdfToWorksheet.d.ts","sourceRoot":"/","sources":["workers/processors/pdfToWorksheet.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,oBAAoB;;;;;;eAgB/B,CAAC"}

package/dist/workers/processors/pdfToWorksheet.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3beb4788-6c75-5aae-b6c1-3195cbdeffa3")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="83752754-be47-54a0-b136-1b4140250056")}catch(e){}}();
 import { pdfToWorksheet } from '../../pipelines/pdfToWorksheet.js';
 import { createRunJobWorker } from './createRunJobWorker.js';
 export const pdfToWorksheetWorker = createRunJobWorker({
@@ -9,12 +9,15 @@ export const pdfToWorksheetWorker = createRunJobWorker({
         // 5 jobs / minute, e.g. to stay under OpenAI rate limits.
         limiter: { max: 5, duration: 60000 },
     },
-    run: async ({ gcsUrl, classId, worksheetId }) => {
-        const worksheet = await pdfToWorksheet(gcsUrl, classId, { worksheetId });
+    run: async ({ gcsUrl, classId, worksheetId }, ctx) => {
+        const worksheet = await pdfToWorksheet(gcsUrl, classId, {
+            worksheetId,
+            userId: ctx.userId,
+        });
         return worksheet
             ? { worksheetId: worksheet.id, name: worksheet.name }
             : null;
     },
 });
 //# sourceMappingURL=pdfToWorksheet.js.map
-//# debugId=3beb4788-6c75-5aae-b6c1-3195cbdeffa3
+//# debugId=83752754-be47-54a0-b136-1b4140250056

package/dist/workers/processors/pdfToWorksheet.js.map

@@ -1 +1 @@
-{"version":3,"file":"pdfToWorksheet.js","sources":["workers/processors/pdfToWorksheet.ts"],"sourceRoot":"/","sourcesContent":["import { pdfToWorksheet } from '../../pipelines/pdfToWorksheet.js';\nimport { createRunJobWorker } from './createRunJobWorker.js';\n\nexport const pdfToWorksheetWorker = createRunJobWorker({\n  type: 'PDF_TO_WORKSHEET',\n  workerOptions: {\n    concurrency: 2,\n    // 5 jobs / minute, e.g. to stay under OpenAI rate limits.\n    limiter: { max: 5, duration: 60_000 },\n  },\n  run: async ({ gcsUrl, classId, worksheetId }) => {\n    const worksheet = await pdfToWorksheet(gcsUrl, classId, { worksheetId });\n    return worksheet\n      ? { worksheetId: worksheet.id, name: worksheet.name }\n      : null;\n  },\n});\n"],"names":[],"mappings":";;AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;IACrD,IAAI,EAAE,kBAAkB;IACxB,aAAa,EAAE;QACb,WAAW,EAAE,CAAC;QACd,0DAA0D;QAC1D,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAM,EAAE;KACtC;IACD,GAAG,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE;QAC9C,MAAM,SAAS,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;QACzE,OAAO,SAAS;YACd,CAAC,CAAC,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE;YACrD,CAAC,CAAC,IAAI,CAAC;IACX,CAAC;CACF,CAAC,CAAC","debug_id":"3beb4788-6c75-5aae-b6c1-3195cbdeffa3"}
+{"version":3,"file":"pdfToWorksheet.js","sources":["workers/processors/pdfToWorksheet.ts"],"sourceRoot":"/","sourcesContent":["import { pdfToWorksheet } from '../../pipelines/pdfToWorksheet.js';\nimport { createRunJobWorker } from './createRunJobWorker.js';\n\nexport const pdfToWorksheetWorker = createRunJobWorker({\n  type: 'PDF_TO_WORKSHEET',\n  workerOptions: {\n    concurrency: 2,\n    // 5 jobs / minute, e.g. to stay under OpenAI rate limits.\n    limiter: { max: 5, duration: 60_000 },\n  },\n  run: async ({ gcsUrl, classId, worksheetId }, ctx) => {\n    const worksheet = await pdfToWorksheet(gcsUrl, classId, {\n      worksheetId,\n      userId: ctx.userId,\n    });\n    return worksheet\n      ? { worksheetId: worksheet.id, name: worksheet.name }\n      : null;\n  },\n});\n"],"names":[],"mappings":";;AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;IACrD,IAAI,EAAE,kBAAkB;IACxB,aAAa,EAAE;QACb,WAAW,EAAE,CAAC;QACd,0DAA0D;QAC1D,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAM,EAAE;KACtC;IACD,GAAG,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,GAAG,EAAE,EAAE;QACnD,MAAM,SAAS,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE;YACtD,WAAW;YACX,MAAM,EAAE,GAAG,CAAC,MAAM;SACnB,CAAC,CAAC;QACH,OAAO,SAAS;YACd,CAAC,CAAC,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE;YACrD,CAAC,CAAC,IAAI,CAAC;IACX,CAAC;CACF,CAAC,CAAC","debug_id":"83752754-be47-54a0-b136-1b4140250056"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studious-lms/server",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "Backend server for Studious application",
   "main": "dist/exportType.js",
   "types": "dist/exportType.d.ts",

package/prisma/migrations/20260708011500_add_ai_usage_attribution/migration.sql

@@ -0,0 +1,13 @@
+-- AlterTable
+ALTER TABLE "AiUsageLog" ADD COLUMN "userId" TEXT,
+ADD COLUMN "schoolId" TEXT,
+ADD COLUMN "classId" TEXT;
+
+-- CreateIndex
+CREATE INDEX "AiUsageLog_userId_createdAt_idx" ON "AiUsageLog"("userId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "AiUsageLog_schoolId_createdAt_idx" ON "AiUsageLog"("schoolId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "AiUsageLog_classId_createdAt_idx" ON "AiUsageLog"("classId", "createdAt");

package/prisma/migrations/20260708013000_add_notification_type_and_entity/migration.sql

@@ -0,0 +1,14 @@
+-- CreateEnum
+CREATE TYPE "NotificationType" AS ENUM ('ASSIGNMENT_POSTED', 'ASSIGNMENT_RETURNED', 'COMMENT_REPLY', 'DISCUSSION_REPLY', 'DISCUSSION_MENTION', 'ANNOUNCEMENT', 'ATTENDANCE', 'SYSTEM');
+
+-- AlterTable
+ALTER TABLE "Notification" ADD COLUMN     "type" "NotificationType" NOT NULL DEFAULT 'SYSTEM',
+ADD COLUMN     "entityType" TEXT,
+ADD COLUMN     "entityId" TEXT,
+ADD COLUMN     "classId" TEXT;
+
+-- CreateIndex
+CREATE INDEX "Notification_receiverId_createdAt_idx" ON "Notification"("receiverId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "Notification_receiverId_read_idx" ON "Notification"("receiverId", "read");

package/prisma/schema.prisma

@@ -734,16 +734,34 @@ model Attendance {
   absent  User[] @relation("AbsentAttendance")
 }
 
+enum NotificationType {
+  ASSIGNMENT_POSTED
+  ASSIGNMENT_RETURNED
+  COMMENT_REPLY
+  DISCUSSION_REPLY
+  DISCUSSION_MENTION
+  ANNOUNCEMENT
+  ATTENDANCE
+  SYSTEM
+}
+
 model Notification {
-  id         String   @id @default(uuid())
+  id         String           @id @default(uuid())
   title      String
   content    String
-  createdAt  DateTime @default(now())
+  createdAt  DateTime         @default(now())
   senderId   String? // no ID means sys
   receiverId String
-  read       Boolean  @default(false)
-  sender     User?    @relation("SentNotifications", fields: [senderId], references: [id])
-  receiver   User     @relation("ReceivedNotifications", fields: [receiverId], references: [id], onDelete: Cascade)
+  read       Boolean          @default(false)
+  type       NotificationType @default(SYSTEM)
+  entityType String? // e.g. ASSIGNMENT, ANNOUNCEMENT, DISCUSSION, SUBMISSION
+  entityId   String?
+  classId    String?
+  sender     User?            @relation("SentNotifications", fields: [senderId], references: [id])
+  receiver   User             @relation("ReceivedNotifications", fields: [receiverId], references: [id], onDelete: Cascade)
+
+  @@index([receiverId, createdAt])
+  @@index([receiverId, read])
 }
 
 enum ConversationType {
@@ -837,9 +855,15 @@ model AiUsageLog {
   estimatedInputTokens Int?
   metadata             Json?    @default("{}")
   error                String?
+  userId               String?
+  schoolId             String?
+  classId              String?
   createdAt            DateTime @default(now())
 
   @@index([reason, createdAt])
+  @@index([userId, createdAt])
+  @@index([schoolId, createdAt])
+  @@index([classId, createdAt])
 }
 
 model Mention {

package/src/index.ts

@@ -272,6 +272,13 @@ app.post('/api/pusher/auth', async (req, res) => {
     //   }
     // }
 
+    // Per-user notification channel: only the user themselves may subscribe
+    if (channel_name.startsWith('private-user-')) {
+      if (channel_name !== `private-user-${user.id}-notifications`) {
+        return res.status(403).json({ error: 'No access to this user channel' });
+      }
+    }
+
     if (channel_name.startsWith('presence-')) {
       const authResponse = pusher.authorizeChannel(socket_id, channel_name, {
         user_id: user.id,

package/src/lib/pusher.ts

@@ -19,5 +19,7 @@ const discussionChannel = (classId: string) => `private-class-${classId}-discuss
  * worksheet-response channel so both can co-exist without auth collisions.
  */
 const worksheetJobChannel = (worksheetId: string) => `private-worksheet-job-${worksheetId}`;
+/** Per-user private channel for in-app notification pushes. */
+const userNotificationChannel = (userId: string) => `private-user-${userId}-notifications`;
 
-export { pusher, chatChannel, worksheetChannel, teacherChannel, discussionChannel, worksheetJobChannel };
+export { pusher, chatChannel, worksheetChannel, teacherChannel, discussionChannel, worksheetJobChannel, userNotificationChannel };

package/src/middleware/security.ts

@@ -20,7 +20,7 @@ const rateLimitHandler = (req: Request, res: Response) => {
 // General API rate limiter - applies to all routes
 export const generalLimiter = rateLimit({
   windowMs: 10 * 60 * 1000, // 10 minutes
-  max: 1000, // Limit each IP to 100 requests per windowMs
+  max: 10000, // Limit each IP to 10000 requests per windowMs (schools often share one NAT IP)
   message: 'Too many requests from this IP, please try again later.',
   standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
   legacyHeaders: false, // Disable the `X-RateLimit-*` headers
@@ -45,7 +45,7 @@ export const authLimiter = rateLimit({
 // File upload rate limiter
 export const uploadLimiter = rateLimit({
   windowMs: 30 * 60 * 1000, // 30 minutes
-  max: 50, // Limit each IP to 50 uploads per hour
+  max: 500, // Limit each IP to 500 uploads per windowMs (a whole class may submit at once behind one IP)
   message: 'Too many file uploads, please try again later.',
   standardHeaders: true,
   legacyHeaders: false,

package/src/models/class.ts

@@ -298,10 +298,11 @@ export function findSessionByClassCode(classCode: string) {
   });
 }
 
-/** @returns Session for a class. */
+/** @returns Invite session for a class. */
 export function findSessionByClassId(classId: string) {
   return prisma.session.findFirst({
-    where: { classId },
+    where: { classId, type: SessionType.CLASS_INVITE },
+    orderBy: { expiresAt: "desc" },
   });
 }
 

package/src/models/notification.ts

@@ -1,6 +1,7 @@
 /**
  * Notification model – in-app notifications, create, mark read.
  */
+import type { NotificationType } from "@prisma/client";
 import { prisma } from "../lib/prisma.js";
 
 const notificationInclude = {
@@ -8,11 +9,28 @@ const notificationInclude = {
   receiver: { select: { username: true } },
 };
 
-/** @returns Notifications for a receiver, newest first. */
-export function findNotificationsByReceiverId(receiverId: string) {
+export type NotificationCreateData = {
+  receiverId: string;
+  title: string;
+  content: string;
+  senderId?: string | null;
+  type?: NotificationType;
+  entityType?: string | null;
+  entityId?: string | null;
+  classId?: string | null;
+};
+
+/** @returns A page of notifications for a receiver, newest first. */
+export function findNotificationsByReceiverIdPaginated(
+  receiverId: string,
+  limit: number,
+  cursor?: string | null
+) {
   return prisma.notification.findMany({
     where: { receiverId },
-    orderBy: { createdAt: "desc" },
+    orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+    take: limit + 1,
+    ...(cursor ? { cursor: { id: cursor }, skip: 1 } : {}),
     include: notificationInclude,
   });
 }
@@ -25,23 +43,26 @@ export function findNotificationByIdForReceiver(id: string, receiverId: string)
   });
 }
 
+/** @returns Number of unread notifications for a receiver. */
+export function countUnreadNotifications(receiverId: string) {
+  return prisma.notification.count({
+    where: { receiverId, read: false },
+  });
+}
+
 /** Create a notification for one receiver. */
-export function createNotification(data: {
-  receiverId: string;
-  title: string;
-  content: string;
-}) {
+export function createNotification(data: NotificationCreateData) {
   return prisma.notification.create({
     data,
+    include: notificationInclude,
   });
 }
 
-/** Create multiple notifications in one call. */
-export function createManyNotifications(
-  data: Array<{ receiverId: string; title: string; content: string }>
-) {
-  return prisma.notification.createMany({
+/** Create multiple notifications in one call and return the created rows. */
+export function createManyNotifications(data: NotificationCreateData[]) {
+  return prisma.notification.createManyAndReturn({
     data,
+    include: notificationInclude,
   });
 }
 
@@ -58,3 +79,11 @@ export async function markNotificationAsReadForReceiver(id: string, receiverId:
 
   return findNotificationByIdForReceiver(id, receiverId);
 }
+
+/** Mark all of a receiver's notifications as read. */
+export function markAllNotificationsAsReadForReceiver(receiverId: string) {
+  return prisma.notification.updateMany({
+    where: { receiverId, read: false },
+    data: { read: true },
+  });
+}

package/src/models/worksheet.ts

@@ -70,7 +70,7 @@ export function findWorksheetsByClassId(classId: string) {
   return prisma.worksheet.findMany({
     where: { classId },
     include: {
-      questions: { select: { id: true } },
+      questions: { select: { id: true, question: true }, orderBy: { order: "asc" } },
       tags: true,
     },
     orderBy: { createdAt: "desc" },

package/src/pipelines/aiLabChat.ts

@@ -378,7 +378,7 @@ export const generateAndSendLabIntroduction = async (
   export const generateAndSendLabResponse = async (
     labChatId: string,
     teacherMessage: string,
-    emitOptions: { classId: string; aiMessageId: string }
+    emitOptions: { classId: string; aiMessageId: string; userId?: string | null }
   ): Promise<void> => {
     try {
       // Get lab context from database
@@ -499,6 +499,11 @@ export const generateAndSendLabIntroduction = async (
           model: AI_CHAT_MODEL,
           system,
           messages,
+          usageReason: 'lab_chat_response',
+          attribution: {
+            userId: emitOptions.userId ?? fullLabChat.createdById,
+            classId: emitOptions.classId,
+          },
           tools,
           temperature: 0.7,
           maxOutputTokens: 4096,

package/src/pipelines/aiNewtonChat.ts

@@ -99,6 +99,7 @@ export const generateAndSendNewtonIntroduction = async (
     conversationId: string,
     submissionId: string,
     aiMessageId: string,
+    actingUserId?: string | null,
   ): Promise<void> => {
     try {
       // Get submission details for context
@@ -109,6 +110,7 @@ export const generateAndSendNewtonIntroduction = async (
             select: {
               title: true,
               instructions: true,
+              classId: true,
               class: {
                 select: {
                   subject: true,
@@ -160,6 +162,11 @@ export const generateAndSendNewtonIntroduction = async (
         ],
         temperature: 0.8,
         maxOutputTokens: 400,
+        usageReason: 'newton_introduction',
+        attribution: {
+          userId: actingUserId,
+          classId: submission.assignment.classId,
+        },
       });
 
       if (!response) {
@@ -237,6 +244,7 @@ export const generateAndSendNewtonIntroduction = async (
       };
     },
     aiMessageId: string,
+    actingUserId?: string | null,
   ): Promise<void> => {
     try {
       // Get recent conversation history (excluding the empty AI placeholder
@@ -339,6 +347,8 @@ export const generateAndSendNewtonIntroduction = async (
         ...(newtonClassId ? { tools: aiTools(newtonClassId), maxSteps: 5 } : {}),
         temperature: 0.7,
         maxOutputTokens: 1200,
+        usageReason: 'newton_response',
+        attribution: { userId: actingUserId, classId: newtonClassId },
       });
       
       if (!response) {

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

@@ -437,6 +437,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 +564,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);
         });

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({