@studious-lms/server 1.18.0 → 1.20.0

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(

package/src/utils/inference.ts

@@ -26,12 +26,23 @@ type InferenceMessage = {
   content: string;
 };
 
+/**
+ * Attribution context for AI usage logging. `schoolId` is resolved from
+ * `classId` at log time when not supplied by the caller.
+ */
+export interface AiUsageAttribution {
+  userId?: string | null;
+  schoolId?: string | null;
+  classId?: string | null;
+}
+
 export interface InferenceOptions {
   reason?: string;
   metadata?: Prisma.InputJsonValue;
   model?: string;
   temperature?: number;
   maxTokens?: number;
+  attribution?: AiUsageAttribution;
 }
 
 interface InferenceUsage {
@@ -42,13 +53,14 @@ interface InferenceUsage {
 
 interface InferenceAuditLog {
   model: string;
-  operation: 'chat.completions' | 'responses.parse';
+  operation: 'chat.completions' | 'responses.parse' | 'stream.text';
   success: boolean;
   estimatedInputTokens: number;
   reason: string;
   metadata?: Prisma.InputJsonValue;
   usage?: InferenceUsage;
   error?: unknown;
+  attribution?: AiUsageAttribution;
 }
 
 // Types for lab chat context
@@ -104,7 +116,25 @@ function serializeInferenceError(error: unknown) {
   }
 }
 
-async function logInferenceUsage({
+async function resolveAttribution(
+  attribution?: AiUsageAttribution,
+): Promise<{ userId: string | null; schoolId: string | null; classId: string | null }> {
+  const userId = attribution?.userId ?? null;
+  const classId = attribution?.classId ?? null;
+  let schoolId = attribution?.schoolId ?? null;
+
+  if (!schoolId && classId) {
+    const classRow = await prisma.class.findUnique({
+      where: { id: classId },
+      select: { schoolId: true },
+    });
+    schoolId = classRow?.schoolId ?? null;
+  }
+
+  return { userId, schoolId, classId };
+}
+
+export async function logInferenceUsage({
   model,
   operation,
   success,
@@ -113,6 +143,7 @@ async function logInferenceUsage({
   metadata,
   usage,
   error,
+  attribution,
 }: InferenceAuditLog) {
   const context = {
     reason,
@@ -128,6 +159,7 @@ async function logInferenceUsage({
   };
 
   try {
+    const resolved = await resolveAttribution(attribution);
     await prisma.aiUsageLog.create({
       data: {
         reason,
@@ -138,6 +170,9 @@ async function logInferenceUsage({
         promptTokens: usage?.promptTokens,
         completionTokens: usage?.completionTokens,
         totalTokens: usage?.totalTokens,
+        userId: resolved.userId,
+        schoolId: resolved.schoolId,
+        classId: resolved.classId,
         ...(metadata !== undefined ? { metadata } : {}),
         ...(error ? { error: serializeInferenceError(error) } : {}),
       },
@@ -587,6 +622,7 @@ export async function inference<T>(
         reason,
         metadata: options?.metadata,
         usage: getChatCompletionUsage(completion),
+        attribution: options?.attribution,
       });
 
       return completion.choices[0]?.message?.content as T;
@@ -613,6 +649,7 @@ export async function inference<T>(
       reason,
       metadata: options?.metadata,
       usage: getResponseUsage(completion),
+      attribution: options?.attribution,
     });
 
     return completion.output_parsed as T;
@@ -625,6 +662,7 @@ export async function inference<T>(
       reason,
       metadata: options?.metadata,
       error,
+      attribution: options?.attribution,
     });
 
     logger.error('Failed to generate inference response', {

package/src/workers/processors/aiLabChat.ts

@@ -14,7 +14,7 @@ export const aiLabChatWorker = createRunJobWorker({
     concurrency: 1,
     limiter: { max: 5, duration: 60_000 },
   },
-  run: async ({ conversationId, aiMessageId }) => {
+  run: async ({ conversationId, aiMessageId }, ctx) => {
     const labChat = await prisma.labChat.findFirst({
       where: { conversationId },
       select: {
@@ -58,6 +58,7 @@ export const aiLabChatWorker = createRunJobWorker({
     await generateAndSendLabResponse(labChat.id, triggeringMessage.content, {
       classId: labChat.classId,
       aiMessageId,
+      userId: ctx.userId ?? triggeringMessage.senderId,
     });
 
     return { labChatId: labChat.id, aiMessageId };

package/src/workers/processors/aiNewtonChat.ts

@@ -12,7 +12,7 @@ export const aiNewtonChatWorker = createRunJobWorker({
     concurrency: 2,
     limiter: { max: 10, duration: 60_000 },
   },
-  run: async ({ conversationId, aiMessageId }) => {
+  run: async ({ conversationId, aiMessageId }, ctx) => {
     const newtonChat = await prisma.newtonChat.findFirst({
       where: { conversationId },
       select: {
@@ -58,6 +58,7 @@ export const aiNewtonChatWorker = createRunJobWorker({
         conversationId,
         newtonChat.submission.id,
         aiMessageId,
+        ctx.userId,
       );
       return { newtonChatId: newtonChat.id, kind: 'introduction', aiMessageId };
     }
@@ -67,6 +68,7 @@ export const aiNewtonChatWorker = createRunJobWorker({
       conversationId,
       newtonChat.submission,
       aiMessageId,
+      ctx.userId ?? triggeringMessage.senderId,
     );
 
     return { newtonChatId: newtonChat.id, aiMessageId };

package/src/workers/processors/gradeWorksheet.ts

@@ -9,8 +9,8 @@ export const gradeWorksheetWorker = createRunJobWorker({
     // throughput modest until we measure real-world usage.
     limiter: { max: 5, duration: 60_000 },
   },
-  run: async ({ worksheetResponseId }) => {
-    await gradeWorksheetPipeline(worksheetResponseId);
+  run: async ({ worksheetResponseId }, ctx) => {
+    await gradeWorksheetPipeline(worksheetResponseId, ctx.userId);
     return { worksheetResponseId };
   },
 });

package/src/workers/processors/pdfToWorksheet.ts

@@ -8,8 +8,11 @@ export const pdfToWorksheetWorker = createRunJobWorker({
     // 5 jobs / minute, e.g. to stay under OpenAI rate limits.
     limiter: { max: 5, duration: 60_000 },
   },
-  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;

package/tests/integration/routers/notification.test.ts

@@ -1,37 +1,86 @@
-import { test, expect, describe } from 'vitest';
+import { test, expect, describe, vi } from 'vitest';
 import { user1Caller, user2Caller } from '../setup';
 import { expectUnauth } from '../helpers';
+import { sendNotification, sendToMultiple } from '../../../src/services/notification';
+
+vi.mock('../../../src/lib/pusher.js', async (importOriginal) => {
+  const original = await importOriginal<typeof import('../../../src/lib/pusher.js')>();
+  return {
+    ...original,
+    pusher: {
+      ...original.pusher,
+      trigger: vi.fn().mockResolvedValue(undefined),
+      triggerBatch: vi.fn().mockResolvedValue(undefined),
+    },
+  };
+});
 
 describe('Notification Router', () => {
   let notificationId: string;
   let user2Id: string;
 
-  test('should send notification to another user', async () => {
+  test('server-side emit creates a typed notification', async () => {
     const user2Profile = await user2Caller.user.getProfile();
     user2Id = user2Profile.id;
 
-    const notification = await user1Caller.notification.sendTo({
+    const notification = await sendNotification({
       receiverId: user2Id,
       title: 'Test Notification',
       content: 'This is a test notification',
+      type: 'ANNOUNCEMENT',
+      entityType: 'ANNOUNCEMENT',
+      entityId: 'announcement-1',
+      classId: 'class-1',
     });
 
     expect(notification).toBeDefined();
     expect(notification.title).toBe('Test Notification');
-    expect(notification.content).toBe('This is a test notification');
     expect(notification.receiverId).toBe(user2Id);
+    expect(notification.type).toBe('ANNOUNCEMENT');
+    expect(notification.entityType).toBe('ANNOUNCEMENT');
+    expect(notification.entityId).toBe('announcement-1');
+    expect(notification.classId).toBe('class-1');
     notificationId = notification.id;
   });
 
-  test('should list notifications for receiver', async () => {
-    const notifications = await user2Caller.notification.list();
+  test('there is no public send endpoint', () => {
+    expect((user1Caller.notification as Record<string, unknown>).sendTo).toBeUndefined();
+    expect(
+      (user1Caller.notification as Record<string, unknown>).sendToMultiple
+    ).toBeUndefined();
+  });
+
+  test('should list notifications for receiver with pagination shape', async () => {
+    const page = await user2Caller.notification.list({ limit: 50 });
 
-    expect(Array.isArray(notifications)).toBe(true);
-    const found = notifications.find((n) => n.id === notificationId);
+    expect(Array.isArray(page.items)).toBe(true);
+    const found = page.items.find((n) => n.id === notificationId);
     expect(found).toBeDefined();
     expect(found!.title).toBe('Test Notification');
   });
 
+  test('should paginate with cursor', async () => {
+    await sendToMultiple({
+      receiverIds: [user2Id, user2Id, user2Id],
+      title: 'Bulk Notification',
+      content: 'Sent in bulk',
+    });
+
+    const firstPage = await user2Caller.notification.list({ limit: 2 });
+    expect(firstPage.items.length).toBe(2);
+    expect(firstPage.nextCursor).toBeTruthy();
+
+    const secondPage = await user2Caller.notification.list({
+      limit: 2,
+      cursor: firstPage.nextCursor,
+    });
+    expect(secondPage.items.length).toBeGreaterThan(0);
+    const firstIds = new Set(firstPage.items.map((n) => n.id));
+    for (const item of secondPage.items) {
+      expect(firstIds.has(item.id)).toBe(false);
+    }
+  });
+
   test('should get a single notification', async () => {
     const notification = await user2Caller.notification.get({ id: notificationId });
 
@@ -40,13 +89,13 @@ describe('Notification Router', () => {
     expect(notification!.title).toBe('Test Notification');
   });
 
-  test('should not get another user\'s notification', async () => {
+  test("should not get another user's notification", async () => {
     await expect(
       user1Caller.notification.get({ id: notificationId })
     ).rejects.toMatchObject({ code: 'NOT_FOUND' });
   });
 
-  test('should not mark another user\'s notification as read', async () => {
+  test("should not mark another user's notification as read", async () => {
     await expect(
       user1Caller.notification.markAsRead({ id: notificationId })
     ).rejects.toMatchObject({ code: 'NOT_FOUND' });
@@ -58,21 +107,20 @@ describe('Notification Router', () => {
     expect(notification.read).toBe(true);
   });
 
-  test('should send to multiple users', async () => {
-    const user1Profile = await user1Caller.user.getProfile();
+  test('should report unread count and mark all as read', async () => {
+    const before = await user2Caller.notification.unreadCount();
+    expect(before).toBeGreaterThan(0);
 
-    const result = await user1Caller.notification.sendToMultiple({
-      receiverIds: [user2Id, user1Profile.id],
-      title: 'Bulk Notification',
-      content: 'Sent to multiple users',
-    });
+    const result = await user2Caller.notification.markAllAsRead();
+    expect(result.count).toBe(before);
 
-    expect(result.count).toBe(2);
+    const after = await user2Caller.notification.unreadCount();
+    expect(after).toBe(0);
   });
 
   test('should not list notifications meant for other users', async () => {
-    const notifications = await user1Caller.notification.list();
-    const foreignNotif = notifications.find((n) => n.id === notificationId);
+    const page = await user1Caller.notification.list();
+    const foreignNotif = page.items.find((n) => n.id === notificationId);
     expect(foreignNotif).toBeUndefined();
   });
 

package/tests/unit/services/aiUsage.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import {
+  aggregateTopUsers,
+  aggregateUsage,
+  usageDayKey,
+  type UsageLogRow,
+} from '../../../src/services/aiUsage.js';
+
+function row(overrides: Partial<UsageLogRow> = {}): UsageLogRow {
+  return {
+    userId: 'user-1',
+    model: 'gpt-4o-mini',
+    operation: 'chat.completions',
+    promptTokens: 100,
+    completionTokens: 50,
+    totalTokens: 150,
+    createdAt: new Date('2026-07-01T10:00:00Z'),
+    ...overrides,
+  };
+}
+
+describe('usageDayKey', () => {
+  it('returns the UTC calendar day', () => {
+    expect(usageDayKey(new Date('2026-07-01T23:59:59Z'))).toBe('2026-07-01');
+    expect(usageDayKey(new Date('2026-07-02T00:00:01Z'))).toBe('2026-07-02');
+  });
+});
+
+describe('aggregateUsage', () => {
+  it('returns empty aggregates for no rows', () => {
+    const result = aggregateUsage([]);
+    expect(result.totals).toEqual({
+      requests: 0,
+      promptTokens: 0,
+      completionTokens: 0,
+      totalTokens: 0,
+    });
+    expect(result.byDay).toEqual([]);
+    expect(result.byModel).toEqual([]);
+    expect(result.byOperation).toEqual([]);
+  });
+
+  it('sums totals across rows and treats null token counts as zero', () => {
+    const result = aggregateUsage([
+      row(),
+      row({ promptTokens: null, completionTokens: null, totalTokens: null }),
+    ]);
+    expect(result.totals).toEqual({
+      requests: 2,
+      promptTokens: 100,
+      completionTokens: 50,
+      totalTokens: 150,
+    });
+  });
+
+  it('buckets by UTC day in ascending order', () => {
+    const result = aggregateUsage([
+      row({ createdAt: new Date('2026-07-02T01:00:00Z'), totalTokens: 20 }),
+      row({ createdAt: new Date('2026-07-01T23:00:00Z'), totalTokens: 10 }),
+      row({ createdAt: new Date('2026-07-02T12:00:00Z'), totalTokens: 30 }),
+    ]);
+    expect(result.byDay.map((d) => d.day)).toEqual([
+      '2026-07-01',
+      '2026-07-02',
+    ]);
+    expect(result.byDay[0]).toMatchObject({ requests: 1, totalTokens: 10 });
+    expect(result.byDay[1]).toMatchObject({ requests: 2, totalTokens: 50 });
+  });
+
+  it('buckets by model and operation sorted by total tokens descending', () => {
+    const result = aggregateUsage([
+      row({ model: 'gpt-4o', operation: 'responses.parse', totalTokens: 500 }),
+      row({ model: 'gpt-4o-mini', operation: 'stream.text', totalTokens: 100 }),
+      row({ model: 'gpt-4o-mini', operation: 'stream.text', totalTokens: 100 }),
+    ]);
+    expect(result.byModel.map((m) => m.model)).toEqual([
+      'gpt-4o',
+      'gpt-4o-mini',
+    ]);
+    expect(result.byModel[1]).toMatchObject({ requests: 2, totalTokens: 200 });
+    expect(result.byOperation.map((o) => o.operation)).toEqual([
+      'responses.parse',
+      'stream.text',
+    ]);
+  });
+});
+
+describe('aggregateTopUsers', () => {
+  it('ranks users by total tokens descending and applies the limit', () => {
+    const rows = [
+      row({ userId: 'a', totalTokens: 100 }),
+      row({ userId: 'b', totalTokens: 300 }),
+      row({ userId: 'a', totalTokens: 250 }),
+      row({ userId: 'c', totalTokens: 50 }),
+    ];
+    const top = aggregateTopUsers(rows, 2);
+    expect(top.map((u) => u.userId)).toEqual(['a', 'b']);
+    expect(top[0]).toMatchObject({ requests: 2, totalTokens: 350 });
+  });
+
+  it('skips rows without a userId', () => {
+    const top = aggregateTopUsers([row({ userId: null })], 10);
+    expect(top).toEqual([]);
+  });
+});