@studious-lms/server 1.19.0 → 1.21.0

package/src/services/aiUsage.ts

@@ -0,0 +1,202 @@
+import { TRPCError } from "@trpc/server";
+import { prisma } from "../lib/prisma.js";
+import { findActiveSchoolAdminMembership } from "../models/school.js";
+
+export interface UsageLogRow {
+  userId: string | null;
+  model: string;
+  operation: string;
+  totalTokens: number | null;
+  promptTokens: number | null;
+  completionTokens: number | null;
+  createdAt: Date;
+}
+
+export interface UsageBucket {
+  requests: number;
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+export interface UsageAggregation {
+  totals: UsageBucket;
+  byDay: Array<{ day: string } & UsageBucket>;
+  byModel: Array<{ model: string } & UsageBucket>;
+  byOperation: Array<{ operation: string } & UsageBucket>;
+}
+
+const emptyBucket = (): UsageBucket => ({
+  requests: 0,
+  promptTokens: 0,
+  completionTokens: 0,
+  totalTokens: 0,
+});
+
+function addToBucket(bucket: UsageBucket, row: UsageLogRow) {
+  bucket.requests += 1;
+  bucket.promptTokens += row.promptTokens ?? 0;
+  bucket.completionTokens += row.completionTokens ?? 0;
+  bucket.totalTokens += row.totalTokens ?? 0;
+}
+
+/** UTC calendar day (YYYY-MM-DD) for a timestamp. */
+export function usageDayKey(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+/** Aggregate raw usage rows into totals and by-day / by-model / by-operation buckets. */
+export function aggregateUsage(rows: UsageLogRow[]): UsageAggregation {
+  const totals = emptyBucket();
+  const byDay = new Map<string, UsageBucket>();
+  const byModel = new Map<string, UsageBucket>();
+  const byOperation = new Map<string, UsageBucket>();
+
+  for (const row of rows) {
+    addToBucket(totals, row);
+
+    const dayKey = usageDayKey(row.createdAt);
+    for (const [map, key] of [
+      [byDay, dayKey],
+      [byModel, row.model],
+      [byOperation, row.operation],
+    ] as const) {
+      let bucket = map.get(key);
+      if (!bucket) {
+        bucket = emptyBucket();
+        map.set(key, bucket);
+      }
+      addToBucket(bucket, row);
+    }
+  }
+
+  return {
+    totals,
+    byDay: [...byDay.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([day, bucket]) => ({ day, ...bucket })),
+    byModel: [...byModel.entries()]
+      .sort(([, a], [, b]) => b.totalTokens - a.totalTokens)
+      .map(([model, bucket]) => ({ model, ...bucket })),
+    byOperation: [...byOperation.entries()]
+      .sort(([, a], [, b]) => b.totalTokens - a.totalTokens)
+      .map(([operation, bucket]) => ({ operation, ...bucket })),
+  };
+}
+
+/** Rank users by total token usage, descending. Rows without a userId are skipped. */
+export function aggregateTopUsers(
+  rows: UsageLogRow[],
+  limit: number,
+): Array<{ userId: string } & UsageBucket> {
+  const byUser = new Map<string, UsageBucket>();
+  for (const row of rows) {
+    if (!row.userId) continue;
+    let bucket = byUser.get(row.userId);
+    if (!bucket) {
+      bucket = emptyBucket();
+      byUser.set(row.userId, bucket);
+    }
+    addToBucket(bucket, row);
+  }
+
+  return [...byUser.entries()]
+    .sort(([, a], [, b]) => b.totalTokens - a.totalTokens)
+    .slice(0, limit)
+    .map(([userId, bucket]) => ({ userId, ...bucket }));
+}
+
+const USAGE_ROW_SELECT = {
+  userId: true,
+  model: true,
+  operation: true,
+  totalTokens: true,
+  promptTokens: true,
+  completionTokens: true,
+  createdAt: true,
+} as const;
+
+function createdAtRange(startDate?: Date, endDate?: Date) {
+  if (!startDate && !endDate) return undefined;
+  return {
+    ...(startDate ? { gte: startDate } : {}),
+    ...(endDate ? { lte: endDate } : {}),
+  };
+}
+
+/**
+ * Per-school aggregate AI usage over a date range. School admins only.
+ */
+export async function getSchoolAiUsage(
+  userId: string,
+  input: {
+    schoolId: string;
+    startDate?: Date;
+    endDate?: Date;
+    topUsersLimit?: number;
+  },
+) {
+  const membership = await findActiveSchoolAdminMembership(
+    input.schoolId,
+    userId,
+  );
+  if (!membership) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Only school admins can view school AI usage",
+    });
+  }
+
+  const rows = await prisma.aiUsageLog.findMany({
+    where: {
+      schoolId: input.schoolId,
+      ...(createdAtRange(input.startDate, input.endDate)
+        ? { createdAt: createdAtRange(input.startDate, input.endDate) }
+        : {}),
+    },
+    select: USAGE_ROW_SELECT,
+  });
+
+  const topUsers = aggregateTopUsers(rows, input.topUsersLimit ?? 10);
+  const userIds = topUsers.map((entry) => entry.userId);
+  const users = userIds.length
+    ? await prisma.user.findMany({
+        where: { id: { in: userIds } },
+        select: {
+          id: true,
+          username: true,
+          profile: { select: { displayName: true } },
+        },
+      })
+    : [];
+  const userById = new Map(users.map((user) => [user.id, user]));
+
+  return {
+    ...aggregateUsage(rows),
+    topUsers: topUsers.map((entry) => ({
+      ...entry,
+      username: userById.get(entry.userId)?.username ?? null,
+      displayName: userById.get(entry.userId)?.profile?.displayName ?? null,
+    })),
+  };
+}
+
+/**
+ * The calling user's own AI usage over a date range.
+ */
+export async function getMyAiUsage(
+  userId: string,
+  input: { startDate?: Date; endDate?: Date } = {},
+) {
+  const rows = await prisma.aiUsageLog.findMany({
+    where: {
+      userId,
+      ...(createdAtRange(input.startDate, input.endDate)
+        ? { createdAt: createdAtRange(input.startDate, input.endDate) }
+        : {}),
+    },
+    select: USAGE_ROW_SELECT,
+  });
+
+  return aggregateUsage(rows);
+}

package/src/services/announcement.ts

@@ -124,6 +124,11 @@ export async function createAnnouncementRecord(
     receiverIds: classData.students.map((s) => s.id),
     title: `New announcement in ${classData.name}`,
     content: `${remarks}\n\n[View announcement](/class/${classId})`,
+    senderId: userId,
+    type: "ANNOUNCEMENT",
+    entityType: "ANNOUNCEMENT",
+    entityId: announcement.id,
+    classId,
   }).catch((error) => {
     logger.error("Failed to send announcement notifications:", error);
   });

package/src/services/assignment.ts

@@ -23,7 +23,7 @@ import {
 } from "../models/assignment.js";
 import { createDirectUploadFiles, type UploadedFile } from "../lib/fileUpload.js";
 import { deleteFile } from "../lib/googleCloudStorage.js";
-import { sendToMultiple } from "./notification.js";
+import { sendNotification, sendToMultiple } from "./notification.js";
 import { enqueueRunJob } from "../workers/queues.js";
 import { logger } from "../utils/logger.js";
 import { invalidateStudentProgressInferenceCache } from "./studentProgressInferenceCache.js";
@@ -317,6 +317,11 @@ export async function createAssignmentRecord(
       receiverIds: (studentIds && studentIds.length > 0) ? studentIds : classData.students.map((s) => s.id),
       title: `New assignment in ${classData.name}`,
       content: `"${title}" is due ${new Date(dueDate).toLocaleDateString()}.\n\n[View assignment](/class/${classId}/assignments/${assignment.id})`,
+      senderId: userId,
+      type: "ASSIGNMENT_POSTED",
+      entityType: "ASSIGNMENT",
+      entityId: assignment.id,
+      classId,
     }).catch((error) => {
       logger.error("Failed to send assignment notifications:", error);
     });
@@ -607,6 +612,11 @@ export async function updateAssignmentRecord(
       receiverIds,
       title: `New assignment in ${classData.name}`,
       content: `"${updatedAssignment.title}" is due ${new Date(updatedAssignment.dueDate).toLocaleDateString()}.\n\n[View assignment](/class/${classData.id}/assignments/${updatedAssignment.id})`,
+      senderId: userId,
+      type: "ASSIGNMENT_POSTED",
+      entityType: "ASSIGNMENT",
+      entityId: updatedAssignment.id,
+      classId: classData.id,
     }).catch((error) => {
       logger.error("Failed to send assignment publish notifications:", error);
     });
@@ -877,11 +887,28 @@ export async function updateSubmissionAsTeacherRecord(
   }
 
   if (returnSubmission !== undefined) {
-    return prisma.submission.update({
+    const updated = await prisma.submission.update({
       where: { id: submissionId },
       data: { returned: !submission.returned },
       include: submissionTeacherInclude,
     });
+
+    if (updated.returned) {
+      sendNotification({
+        receiverId: submission.studentId,
+        title: `Assignment returned in ${submission.assignment.class.name}`,
+        content: `"${submission.assignment.title}" has been returned.\n\n[View assignment](/class/${submission.assignment.class.id}/assignments/${submission.assignment.id})`,
+        senderId: teacherId,
+        type: "ASSIGNMENT_RETURNED",
+        entityType: "ASSIGNMENT",
+        entityId: submission.assignment.id,
+        classId: submission.assignment.class.id,
+      }).catch((error) => {
+        logger.error("Failed to send assignment returned notification:", error);
+      });
+    }
+
+    return updated;
   }
 
   if (existingFileIds?.length) {

package/src/services/attendance.ts

@@ -143,11 +143,19 @@ async function notifyMarkedLateOrAbsent(input: {
       receiverIds: lateReceiverIds,
       title: `Marked late in ${input.className}`,
       content: `You were marked late for ${attendanceLabel}.\n[View attendance](${link})`,
+      type: "ATTENDANCE",
+      entityType: "ATTENDANCE",
+      entityId: input.eventId,
+      classId: input.classId,
     }),
     sendAttendanceNotification({
       receiverIds: absentReceiverIds,
       title: `Marked absent in ${input.className}`,
       content: `You were marked absent for ${attendanceLabel}.\n[View attendance](${link})`,
+      type: "ATTENDANCE",
+      entityType: "ATTENDANCE",
+      entityId: input.eventId,
+      classId: input.classId,
     }),
   ]);
 }
@@ -157,6 +165,10 @@ async function sendAttendanceNotification(input: {
   receiverIds: string[];
   title: string;
   content: string;
+  type: "ATTENDANCE";
+  entityType: string;
+  entityId: string | null;
+  classId: string;
 }) {
   if (input.receiverIds.length === 0) {
     return;

package/src/services/class.ts

@@ -785,6 +785,10 @@ export async function publishLabDraft(
       receiverIds: classData.students.map((s) => s.id),
       title: `New assignment in ${classData.name}`,
       content: `"${published.title}" is due ${new Date(published.dueDate).toLocaleDateString()}.\n\n[View assignment](/class/${classId}/assignments/${published.id})`,
+      type: "ASSIGNMENT_POSTED",
+      entityType: "ASSIGNMENT",
+      entityId: published.id,
+      classId,
     }).catch((error) => {
       logger.error("Failed to send lab draft publish notifications:", error);
     });

package/src/services/discussion.ts

@@ -1,4 +1,4 @@
-import type { DiscussionType, Prisma, ReactionType } from "@prisma/client";
+import type { DiscussionType, NotificationType, Prisma, ReactionType } from "@prisma/client";
 import type { AppTransactionClient } from "../lib/prisma.js";
 import { TRPCError } from "@trpc/server";
 import { prisma } from "../lib/prisma.js";
@@ -266,14 +266,29 @@ function triggerDiscussionEvent(classId: string, event: string, payload: unknown
   });
 }
 
-async function notify(receiverId: string | null | undefined, senderId: string, title: string, content: string) {
+async function notify(
+  receiverId: string | null | undefined,
+  senderId: string,
+  title: string,
+  content: string,
+  meta: { type: NotificationType; classId: string; discussionId: string }
+) {
   if (!receiverId || receiverId === senderId) return;
-  await sendNotification({ receiverId, title, content }).catch((error) => {
+  await sendNotification({
+    receiverId,
+    senderId,
+    title,
+    content,
+    type: meta.type,
+    entityType: "DISCUSSION",
+    entityId: meta.discussionId,
+    classId: meta.classId,
+  }).catch((error) => {
     logger.error("Failed to send discussion notification", { receiverId, error });
   });
 }
 
-async function notifyMentionedUsers(classId: string, senderId: string, body: string, link: string) {
+async function notifyMentionedUsers(classId: string, senderId: string, body: string, link: string, discussionId: string) {
   const usernames = [...new Set(Array.from(body.matchAll(/(^|\s)@([a-zA-Z0-9_.-]{2,32})/g)).map((match) => match[2]))];
   if (!usernames.length) return;
   const members = await prisma.user.findMany({
@@ -287,7 +302,15 @@ async function notifyMentionedUsers(classId: string, senderId: string, body: str
     },
     select: { id: true },
   });
-  await Promise.all(members.map((member) => notify(member.id, senderId, "You were mentioned in a discussion", link)));
+  await Promise.all(
+    members.map((member) =>
+      notify(member.id, senderId, "You were mentioned in a discussion", link, {
+        type: "DISCUSSION_MENTION",
+        classId,
+        discussionId,
+      })
+    )
+  );
 }
 
 async function unreadCountsForDiscussions(userId: string, discussionIds: string[]) {
@@ -441,7 +464,7 @@ export async function createDiscussion(userId: string, input: {
   });
 
   triggerDiscussionEvent(input.classId, "discussion-created", { discussion: serializeDiscussion(discussion, userId) });
-  await notifyMentionedUsers(input.classId, userId, input.body, `/class/${input.classId}/discussions/${discussion.id}`);
+  await notifyMentionedUsers(input.classId, userId, input.body, `/class/${input.classId}/discussions/${discussion.id}`, discussion.id);
 
   // Auto-index discussion for RAG search
   enqueueEmbedding(input.classId, 'DISCUSSION', discussion.id);
@@ -530,9 +553,17 @@ export async function replyToDiscussion(userId: string, input: {
   });
   const link = `/class/${discussion.classId}/discussions/${discussion.id}#${reply.id}`;
   await Promise.all([
-    notify(discussion.authorId, userId, "New reply to your discussion", link),
-    notify(parent?.authorId, userId, "New reply in a discussion thread", link),
-    notifyMentionedUsers(discussion.classId, userId, input.body, link),
+    notify(discussion.authorId, userId, "New reply to your discussion", link, {
+      type: "DISCUSSION_REPLY",
+      classId: discussion.classId,
+      discussionId: discussion.id,
+    }),
+    notify(parent?.authorId, userId, "New reply in a discussion thread", link, {
+      type: "DISCUSSION_REPLY",
+      classId: discussion.classId,
+      discussionId: discussion.id,
+    }),
+    notifyMentionedUsers(discussion.classId, userId, input.body, link, discussion.id),
   ]);
   triggerDiscussionEvent(discussion.classId, "reply-created", { discussionId: discussion.id, reply: serializeReply(reply, userId) });
 
@@ -582,7 +613,11 @@ export async function pinDiscussion(userId: string, discussionId: string, isPinn
   const { discussion, isTeacher } = await getDiscussionForUser(discussionId, userId);
   if (!isTeacher) throw new TRPCError({ code: "FORBIDDEN", message: "Only teachers can pin discussions" });
   const updated = await prisma.discussion.update({ where: { id: discussionId }, data: { isPinned }, include: discussionInclude });
-  await notify(discussion.authorId, userId, isPinned ? "Your discussion was pinned" : "Your discussion was unpinned", `/class/${discussion.classId}/discussions/${discussionId}`);
+  await notify(discussion.authorId, userId, isPinned ? "Your discussion was pinned" : "Your discussion was unpinned", `/class/${discussion.classId}/discussions/${discussionId}`, {
+    type: "DISCUSSION_REPLY",
+    classId: discussion.classId,
+    discussionId,
+  });
   triggerDiscussionEvent(discussion.classId, "discussion-updated", { discussion: serializeDiscussion(updated, userId) });
   return { discussion: serializeDiscussion(updated, userId) };
 }
@@ -611,7 +646,11 @@ export async function markAcceptedAnswer(userId: string, replyId: string, accept
     }
     return tx.discussionReply.update({ where: { id: replyId }, data: { isAcceptedAnswer: accepted }, include: replyInclude });
   });
-  await notify(reply.authorId, userId, accepted ? "Your answer was accepted" : "Your answer was unmarked", `/class/${reply.discussion.classId}/discussions/${reply.discussionId}#${replyId}`);
+  await notify(reply.authorId, userId, accepted ? "Your answer was accepted" : "Your answer was unmarked", `/class/${reply.discussion.classId}/discussions/${reply.discussionId}#${replyId}`, {
+    type: "DISCUSSION_REPLY",
+    classId: reply.discussion.classId,
+    discussionId: reply.discussionId,
+  });
   triggerDiscussionEvent(reply.discussion.classId, "reply-updated", { discussionId: reply.discussionId, reply: serializeReply(updated, userId) });
   return { reply: serializeReply(updated, userId) };
 }

package/src/services/discussionSummary.ts

@@ -215,6 +215,7 @@ export async function getDiscussionSummary(
     {
       reason: "discussion_summary",
       metadata: { discussionId, classId: discussion.classId },
+      attribution: { userId, classId: discussion.classId },
     },
   );
 

package/src/services/notification.ts

@@ -1,18 +1,63 @@
 /**
- * Notification service – list, send, and mark notifications as read.
+ * Notification service – list, emit, and mark notifications as read.
+ *
+ * Notifications are only emitted server-side by domain services (assignments,
+ * announcements, discussions, attendance, …); there is no public "send"
+ * endpoint. New notifications are also pushed in realtime over Pusher on the
+ * receiver's private per-user channel.
  */
 import { TRPCError } from "@trpc/server";
+import type { NotificationType } from "@prisma/client";
 import {
-  findNotificationsByReceiverId,
+  findNotificationsByReceiverIdPaginated,
   findNotificationByIdForReceiver,
+  countUnreadNotifications,
   createNotification,
   createManyNotifications,
   markNotificationAsReadForReceiver,
+  markAllNotificationsAsReadForReceiver,
+  type NotificationCreateData,
 } from "../models/notification.js";
+import { pusher, userNotificationChannel } from "../lib/pusher.js";
+import { logger } from "../utils/logger.js";
 
-/** List notifications for a user. */
-export async function listNotifications(userId: string) {
-  return findNotificationsByReceiverId(userId);
+export const NOTIFICATION_CREATED_EVENT = "notification-created";
+
+type CreatedNotification = Awaited<ReturnType<typeof createNotification>>;
+
+/** Pusher batch triggers accept at most 10 events per call. */
+const PUSHER_BATCH_SIZE = 10;
+
+async function pushNotifications(notifications: CreatedNotification[]) {
+  for (let i = 0; i < notifications.length; i += PUSHER_BATCH_SIZE) {
+    const batch = notifications.slice(i, i + PUSHER_BATCH_SIZE).map((notification) => ({
+      channel: userNotificationChannel(notification.receiverId),
+      name: NOTIFICATION_CREATED_EVENT,
+      data: notification,
+    }));
+    try {
+      await pusher.triggerBatch(batch);
+    } catch (error) {
+      logger.error("Failed to push notifications over Pusher", { error });
+    }
+  }
+}
+
+/** List notifications for a user, newest first, cursor-paginated. */
+export async function listNotifications(
+  userId: string,
+  input?: { limit?: number; cursor?: string | null }
+) {
+  const limit = input?.limit ?? 20;
+  const rows = await findNotificationsByReceiverIdPaginated(userId, limit, input?.cursor);
+
+  let nextCursor: string | null = null;
+  if (rows.length > limit) {
+    const nextItem = rows.pop();
+    nextCursor = nextItem!.id;
+  }
+
+  return { items: rows, nextCursor };
 }
 
 /** Get a single notification by ID for its receiver. */
@@ -29,29 +74,41 @@ export async function getNotification(userId: string, id: string) {
   return notification;
 }
 
-/** Send a notification to one user. */
-export async function sendNotification(input: {
-  receiverId: string;
-  title: string;
-  content: string;
-}) {
-  return createNotification(input);
+/** Number of unread notifications for a user. */
+export function getUnreadCount(userId: string) {
+  return countUnreadNotifications(userId);
+}
+
+/**
+ * Emit a notification to one user (server-side only) and push it over Pusher.
+ */
+export async function sendNotification(input: NotificationCreateData) {
+  const notification = await createNotification(input);
+  void pushNotifications([notification]);
+  return notification;
 }
 
-/** Send the same notification to multiple users. */
+/**
+ * Emit the same notification to multiple users (server-side only) and push
+ * each over Pusher.
+ */
 export async function sendToMultiple(input: {
   receiverIds: string[];
   title: string;
   content: string;
+  senderId?: string | null;
+  type?: NotificationType;
+  entityType?: string | null;
+  entityId?: string | null;
+  classId?: string | null;
 }) {
-  const result = await createManyNotifications(
-    input.receiverIds.map((receiverId) => ({
-      receiverId,
-      title: input.title,
-      content: input.content,
-    }))
+  const { receiverIds, ...rest } = input;
+  if (receiverIds.length === 0) return [];
+  const notifications = await createManyNotifications(
+    receiverIds.map((receiverId) => ({ receiverId, ...rest }))
   );
-  return result;
+  void pushNotifications(notifications);
+  return notifications;
 }
 
 /** Mark a notification as read for its receiver. */
@@ -67,3 +124,9 @@ export async function markAsRead(userId: string, id: string) {
 
   return notification;
 }
+
+/** Mark all notifications as read for a user. */
+export async function markAllAsRead(userId: string) {
+  const result = await markAllNotificationsAsReadForReceiver(userId);
+  return { count: result.count };
+}

package/src/services/studentProgress.ts

@@ -745,6 +745,7 @@ export async function getStudentProgressInsights(
     {
       reason: "student_progress_insights",
       metadata: { viewerId, classId, studentId },
+      attribution: { userId: viewerId, classId },
     },
   );
   setStudentProgressInferenceCache(
@@ -792,6 +793,7 @@ export async function getStudentProgressForecast(
     {
       reason: "student_progress_forecast",
       metadata: { viewerId, classId, studentId },
+      attribution: { userId: viewerId, classId },
     },
   );
   setStudentProgressInferenceCache(
@@ -839,6 +841,7 @@ export async function getStudentProgressFocus(
     {
       reason: "student_progress_focus",
       metadata: { viewerId, classId, studentId },
+      attribution: { userId: viewerId, classId },
     },
   );
   setStudentProgressInferenceCache(
@@ -901,6 +904,7 @@ export async function chatAboutStudentProgress(
         classId: input.classId,
         studentId: input.studentId,
       },
+      attribution: { userId: viewerId, classId: input.classId },
     });
     if (typeof response !== "string" || response.trim().length === 0) {
       throw new Error("Student progress chat returned an empty response");

package/src/services/userPrivacy.ts

@@ -121,6 +121,10 @@ export async function exportUserData(userId: string) {
           content: true,
           read: true,
           createdAt: true,
+          type: true,
+          entityType: true,
+          entityId: true,
+          classId: true,
         },
         take: 200,
         orderBy: { createdAt: "desc" },

package/src/services/worksheet.ts

@@ -626,7 +626,7 @@ export async function regradeQuestion(
       message: "Only class teachers can regrade worksheet answers",
     });
   }
-  return regradeWorksheetPipeline(worksheetResponseId, progressId);
+  return regradeWorksheetPipeline(worksheetResponseId, progressId, userId);
 }
 
 export async function regradeAll(
@@ -645,7 +645,7 @@ export async function regradeAll(
     });
   }
 
-  await regradeAllPipeline(worksheetResponseId);
+  await regradeAllPipeline(worksheetResponseId, userId);
 }
 
 export async function gradeAnswer(