@studious-lms/server 1.19.0 → 1.21.0

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([]);
+  });
+});