@studious-lms/server 1.5.0 → 1.7.0

package/src/pipelines/pdfToWorksheet.ts

@@ -1,13 +1,25 @@
 /**
  * PDF URL → worksheet: send a remote PDF URL to structured inference,
  * then persist a Worksheet and WorksheetQuestion rows.
+ *
+ * Normally driven by a BullMQ worker, so the producer (e.g.
+ * `createWorksheetFromUploadedPdf`) creates a placeholder Worksheet row up
+ * front and passes its id in via `worksheetId`. The pipeline broadcasts
+ * `Worksheet.status` transitions on the per-worksheet job Pusher channel
+ * (`set-pending` / `set-completed` / `set-failed` / `set-cancelled`) — same
+ * convention as `gradeWorksheet`.
+ *
+ * The legacy `pdfToWorksheet(gcsUrl, classId)` signature is preserved for
+ * direct/synchronous callers (such as tests): when no `worksheetId` is
+ * supplied the pipeline creates the row itself.
  */
 import { z } from "zod";
 import type { ResponseInput } from "openai/resources/responses/responses.js";
-import { Prisma } from "@prisma/client";
+import { JobStatus, Prisma } from "@prisma/client";
 import { prisma } from "../lib/prisma.js";
 import { inference } from "../utils/inference.js";
 import { logger } from "../utils/logger.js";
+import { pusher, worksheetJobChannel } from "../lib/pusher.js";
 
 /** Restrict remote fetches to Google-hosted object URLs. */
 function isProbablyGoogleCloudUrl(url: string): boolean {
@@ -42,6 +54,61 @@ function sanitizeUrlForLogs(url: string): string {
   }
 }
 
+/**
+ * Pusher event names mirror `gradeWorksheet`'s convention so clients can
+ * share the same JobStatus → event-name mapping.
+ */
+const STATUS_EVENT_NAMES: Record<JobStatus, string> = {
+  NOT_STARTED: 'set-not-started',
+  PENDING: 'set-pending',
+  COMPLETED: 'set-completed',
+  FAILED: 'set-failed',
+  CANCELLED: 'set-cancelled',
+};
+
+/**
+ * Realtime payload for the per-worksheet job channel.
+ *
+ * On COMPLETED we ship the new title and question count so clients can
+ * patch their card optimistically and side-step replica lag on the next
+ * refetch. Error strings are intentionally NOT broadcast — they may carry
+ * server internals; the full error stays on `RunJob.error` for ops only.
+ */
+export interface WorksheetJobStatusEvent {
+  worksheetId: string;
+  status: JobStatus;
+  /** Filled on COMPLETED so clients can avoid a replica-lagged refetch. */
+  name?: string;
+  questionCount?: number;
+}
+
+/**
+ * Fire-and-forget broadcast of a `Worksheet.status` transition. We never let
+ * a Pusher outage break the actual pipeline: the persisted `Worksheet.status`
+ * is the source of truth, the channel just nudges clients.
+ */
+async function emitStatus(
+  worksheetId: string | undefined,
+  status: JobStatus,
+  extras: Pick<WorksheetJobStatusEvent, 'name' | 'questionCount'> = {},
+): Promise<void> {
+  if (!worksheetId) return;
+
+  try {
+    await pusher.trigger(
+      worksheetJobChannel(worksheetId),
+      STATUS_EVENT_NAMES[status],
+      { worksheetId, status, ...extras } satisfies WorksheetJobStatusEvent,
+    );
+  } catch (error) {
+    logger.warn('pdfToWorksheet: failed to broadcast status update', {
+      worksheetId,
+      status,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
 /** LLM output shape (validated by inference). */
 const worksheetDraftSchema = z.object({
   title: z.string(),
@@ -105,36 +172,72 @@ const schemaInstructions = `Return ONLY valid JSON matching this schema:
 Rules: "questions" is an array ([] if none). Non-MCQ "options" can be []. Use "order" 1,2,3,… in reading order. No markdown or extra keys.
 If no answer is provided for a multiple-choice or true/false question, determine the answer from the options.`;
 
+export interface PdfToWorksheetOptions {
+  /**
+   * Pre-existing Worksheet row id. When supplied, the pipeline fills in this
+   * row instead of creating a new one and broadcasts progress on its job
+   * channel. This is the path used by the BullMQ worker.
+   */
+  worksheetId?: string;
+}
+
 /**
  * Sends a PDF URL to the model for remote retrieval, extracts a worksheet via
- * structured inference, and inserts worksheet + questions in one DB transaction.
+ * structured inference, and inserts (or back-fills) worksheet + questions.
+ *
+ * When called with `options.worksheetId` the pipeline:
+ *   - keeps that row's id stable (the client already routed to it),
+ *   - drives `status` PENDING → COMPLETED / FAILED,
+ *   - fans out `set-*` Pusher events on `worksheetJobChannel`.
  */
-export async function pdfToWorksheet(gcsUrl: string, classId: string) {
+export async function pdfToWorksheet(
+  gcsUrl: string,
+  classId: string,
+  options: PdfToWorksheetOptions = {},
+) {
   const sourceUrl = sanitizeUrlForLogs(gcsUrl);
+  const placeholderWorksheetId = options.worksheetId;
+
+  await emitStatus(placeholderWorksheetId, JobStatus.PENDING);
 
   if (!isProbablyGoogleCloudUrl(gcsUrl)) {
     logger.warn("pdfToWorksheet: rejected unsupported PDF URL", {
       sanitizedUrl: sourceUrl,
     });
+    await markWorksheetFailed(
+      placeholderWorksheetId,
+      "Only Google Cloud Storage URLs are supported",
+    );
     throw new Error("Only Google Cloud Storage URLs are supported");
   }
 
-  const existingWorksheet = await prisma.worksheet.findUnique({
-    where: {
-      classId_sourceUrl: {
-        classId,
-        sourceUrl,
-      },
-    },
+  // Look for a previously-completed worksheet pointing at the same source PDF.
+  // If there is one (and it's not the placeholder we were handed) we reuse it,
+  // mark the placeholder CANCELLED so the editor stops spinning, and return
+  // the canonical worksheet.
+  const existingForSource = await prisma.worksheet.findUnique({
+    where: { classId_sourceUrl: { classId, sourceUrl } },
   });
 
-  if (existingWorksheet) {
+  if (existingForSource && existingForSource.id !== placeholderWorksheetId) {
     logger.info("pdfToWorksheet: reusing existing worksheet for source PDF", {
-      worksheetId: existingWorksheet.id,
+      worksheetId: existingForSource.id,
       classId,
       sourceUrl,
     });
-    return existingWorksheet;
+
+    if (placeholderWorksheetId) {
+      await prisma.worksheet
+        .update({
+          where: { id: placeholderWorksheetId },
+          data: { status: JobStatus.CANCELLED },
+        })
+        .catch(() => undefined);
+
+      await emitStatus(placeholderWorksheetId, JobStatus.CANCELLED);
+    }
+
+    return existingForSource;
   }
 
   const filename = getFilenameFromUrl(gcsUrl);
@@ -151,33 +254,67 @@ export async function pdfToWorksheet(gcsUrl: string, classId: string) {
     },
   ];
 
-  const draft = await inference<WorksheetDraft>(
-    input,
-    worksheetDraftSchema,
-    {
-      reason: 'pdf_to_worksheet_draft',
-      metadata: {
-        classId,
-        filename,
-      },
-    }
-  );
+  let draft: WorksheetDraft | null;
+  try {
+    draft = await inference<WorksheetDraft>(
+      input,
+      worksheetDraftSchema,
+      {
+        reason: 'pdf_to_worksheet_draft',
+        metadata: {
+          classId,
+          filename,
+        },
+      }
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    await markWorksheetFailed(placeholderWorksheetId, message);
+    throw error;
+  }
 
   if (!draft) {
     logger.warn("pdfToWorksheet: no model output", { filename });
+    await markWorksheetFailed(
+      placeholderWorksheetId,
+      "Model returned no parseable worksheet output",
+    );
     return null;
   }
 
   try {
-    return await prisma.$transaction(async (tx) => {
-      const worksheet = await tx.worksheet.create({
-        data: { classId, name: draft.title, sourceUrl },
-      });
+    const worksheet = await prisma.$transaction(async (tx) => {
+      const created = placeholderWorksheetId
+        ? await tx.worksheet.update({
+            where: { id: placeholderWorksheetId },
+            data: {
+              classId,
+              name: draft!.title,
+              sourceUrl,
+              status: JobStatus.PENDING,
+            },
+          })
+        : await tx.worksheet.create({
+            data: {
+              classId,
+              name: draft!.title,
+              sourceUrl,
+              status: JobStatus.PENDING,
+            },
+          });
+
+      if (draft!.questions.length > 0) {
+        // When re-running against an existing placeholder, drop any prior
+        // questions so we don't accumulate duplicates from retries.
+        if (placeholderWorksheetId) {
+          await tx.worksheetQuestion.deleteMany({
+            where: { worksheetId: created.id },
+          });
+        }
 
-      if (draft.questions.length > 0) {
         await tx.worksheetQuestion.createMany({
-          data: draft.questions.map((question) => ({
-            worksheetId: worksheet.id,
+          data: draft!.questions.map((question) => ({
+            worksheetId: created.id,
             type: question.type,
             question: question.question,
             answer: question.answer,
@@ -192,8 +329,18 @@ export async function pdfToWorksheet(gcsUrl: string, classId: string) {
         });
       }
 
-      return worksheet;
+      return tx.worksheet.update({
+        where: { id: created.id },
+        data: { status: JobStatus.COMPLETED },
+      });
+    });
+
+    await emitStatus(placeholderWorksheetId, JobStatus.COMPLETED, {
+      name: worksheet.name,
+      questionCount: draft.questions.length,
     });
+
+    return worksheet;
   } catch (error) {
     if (
       error instanceof Prisma.PrismaClientKnownRequestError &&
@@ -214,10 +361,55 @@ export async function pdfToWorksheet(gcsUrl: string, classId: string) {
           classId,
           sourceUrl,
         });
+
+        if (placeholderWorksheetId && placeholderWorksheetId !== worksheet.id) {
+          await prisma.worksheet
+            .update({
+              where: { id: placeholderWorksheetId },
+              data: { status: JobStatus.CANCELLED },
+            })
+            .catch(() => undefined);
+
+          await emitStatus(placeholderWorksheetId, JobStatus.CANCELLED);
+        }
+
         return worksheet;
       }
     }
 
+    const message = error instanceof Error ? error.message : String(error);
+    await markWorksheetFailed(placeholderWorksheetId, message);
     throw error;
   }
 }
+
+async function markWorksheetFailed(
+  worksheetId: string | undefined,
+  errorMessage: string,
+) {
+  if (!worksheetId) return;
+
+  await prisma.worksheet
+    .update({
+      where: { id: worksheetId },
+      data: { status: JobStatus.FAILED },
+    })
+    .catch((updateError) => {
+      logger.error('pdfToWorksheet: failed to mark worksheet FAILED', {
+        worksheetId,
+        error:
+          updateError instanceof Error
+            ? updateError.message
+            : String(updateError),
+      });
+    });
+
+  // The full error is logged + persisted on `RunJob.error`; the broadcast
+  // intentionally carries no error payload to avoid leaking internals.
+  logger.error('pdfToWorksheet: marking worksheet FAILED', {
+    worksheetId,
+    error: errorMessage,
+  });
+
+  await emitStatus(worksheetId, JobStatus.FAILED);
+}

package/src/routers/assignment.ts

@@ -5,7 +5,6 @@ import { prisma } from "../lib/prisma.js";
 import { createDirectUploadFiles, type DirectUploadFile, confirmDirectUpload, updateUploadProgress, type UploadedFile } from "../lib/fileUpload.js";
 import { deleteFile } from "../lib/googleCloudStorage.js";
 import { logger } from "../utils/logger.js";
-import { gradeWorksheetPipeline } from "../pipelines/gradeWorksheet.js";
 import {
   classMemberOrSchoolAdminWhere,
   classTeacherOrSchoolAdminWhere,
@@ -35,6 +34,15 @@ import {
 } from "../services/assignment.js";
 import { sendToMultiple } from "../services/notification.js";
 
+function getCommenterName(comment: {
+  author: {
+    username: string;
+    profile: { displayName: string | null } | null;
+  };
+}) {
+  return comment.author.profile?.displayName || comment.author.username;
+}
+
 // DEPRECATED: This schema is no longer used - files are uploaded directly to GCS
 // Use directFileSchema instead
 
@@ -369,7 +377,18 @@ export const assignmentRouter = createTRPCRouter({
     .mutation(async ({ ctx, input }) => {
       const assignment = await prisma.assignment.findFirst({
         where: { id: input.assignmentId, classId: input.classId },
-        select: { id: true },
+        select: {
+          id: true,
+          title: true,
+          class: {
+            select: {
+              id: true,
+              name: true,
+              students: { select: { id: true } },
+              teachers: { select: { id: true } },
+            },
+          },
+        },
       });
       if (!assignment) {
         throw new TRPCError({
@@ -405,6 +424,24 @@ export const assignmentRouter = createTRPCRouter({
         include: commentInclude,
       });
 
+      const authorId = ctx.user!.id;
+      const receiverIds = Array.from(
+        new Set([
+          ...assignment.class.students.map((s) => s.id),
+          ...assignment.class.teachers.map((t) => t.id),
+        ])
+      ).filter((id) => id !== authorId);
+
+      if (receiverIds.length > 0) {
+        sendToMultiple({
+          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})`,
+        }).catch((error) => {
+          logger.error("Failed to send assignment comment notifications:", error);
+        });
+      }
+
       return { comment };
     }),
 
@@ -458,7 +495,23 @@ export const assignmentRouter = createTRPCRouter({
             { assignment: { class: classTeacherOrSchoolAdminWhere(ctx.user!.id) } },
           ],
         },
-        select: { id: true },
+        select: {
+          id: true,
+          studentId: true,
+          assignment: {
+            select: {
+              id: true,
+              title: true,
+              class: {
+                select: {
+                  id: true,
+                  name: true,
+                  teachers: { select: { id: true } },
+                },
+              },
+            },
+          },
+        },
       });
       if (!submission) {
         throw new TRPCError({
@@ -493,6 +546,24 @@ export const assignmentRouter = createTRPCRouter({
         include: commentInclude,
       });
 
+      const authorId = ctx.user!.id;
+      const receiverIds = Array.from(
+        new Set([
+          submission.studentId,
+          ...submission.assignment.class.teachers.map((t) => t.id),
+        ])
+      ).filter((id) => id !== authorId);
+
+      if (receiverIds.length > 0) {
+        sendToMultiple({
+          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})`,
+        }).catch((error) => {
+          logger.error("Failed to send submission comment notifications:", error);
+        });
+      }
+
       return { comment };
     }),
 

package/src/routers/conversation.ts

@@ -7,6 +7,7 @@ import {
   addMemberToConversation,
   hideConversation,
   removeMemberFromConversation,
+  searchConversationMembers,
 } from "../services/conversation.js";
 
 export const conversationRouter = createTRPCRouter({
@@ -14,6 +15,12 @@ export const conversationRouter = createTRPCRouter({
     listConversations(ctx.user!.id)
   ),
 
+  searchMembers: protectedProcedure
+    .input(z.object({ query: z.string().max(100) }))
+    .query(({ ctx, input }) =>
+      searchConversationMembers(ctx.user!.id, input.query)
+    ),
+
   create: protectedProcedure
     .input(
       z.object({

package/src/routers/worksheet.ts

@@ -127,8 +127,18 @@ export const worksheetRouter = createTRPCRouter({
     ),
 
   createFromPdf: protectedTeacherProcedure
-    .input(z.object({ classId: z.string(), url: z.string().url() }))
-    .mutation(({ input }) => createWorksheetFromPdf(input.classId, input.url)),
+    .input(
+      z.object({
+        classId: z.string(),
+        url: z.string().url(),
+        name: z.string().optional(),
+      }),
+    )
+    .mutation(({ ctx, input }) =>
+      createWorksheetFromPdf(input.classId, input.url, ctx.user!.id, {
+        name: input.name,
+      }),
+    ),
 
   getWorksheetUploadUrls: protectedTeacherProcedure
     .input(getWorksheetUploadUrlsSchema)
@@ -190,9 +200,20 @@ export const worksheetRouter = createTRPCRouter({
     }),
 
   createFromUploadedPdf: protectedTeacherProcedure
-    .input(z.object({ classId: z.string(), fileId: z.string() }))
+    .input(
+      z.object({
+        classId: z.string(),
+        fileId: z.string(),
+        name: z.string().optional(),
+      }),
+    )
     .mutation(({ ctx, input }) =>
-      createWorksheetFromUploadedPdf(input.classId, input.fileId, ctx.user!.id)
+      createWorksheetFromUploadedPdf(
+        input.classId,
+        input.fileId,
+        ctx.user!.id,
+        { name: input.name },
+      )
     ),
 
   addQuestion: protectedProcedure

package/src/services/announcement.ts

@@ -121,8 +121,8 @@ export async function createAnnouncementRecord(
 
   sendToMultiple({
     receiverIds: classData.students.map((s) => s.id),
-    title: `🔔 Announcement for ${classData.name}`,
-    content: remarks,
+    title: `New announcement in ${classData.name}`,
+    content: `${remarks}\n\n[View announcement](/class/${classId})`,
   }).catch((error) => {
     logger.error("Failed to send announcement notifications:", error);
   });

package/src/services/assignment.ts

@@ -23,8 +23,8 @@ import {
 } from "../models/assignment.js";
 import { createDirectUploadFiles, type UploadedFile } from "../lib/fileUpload.js";
 import { deleteFile } from "../lib/googleCloudStorage.js";
-import { gradeWorksheetPipeline } from "../pipelines/gradeWorksheet.js";
 import { sendToMultiple } from "./notification.js";
+import { enqueueRunJob } from "../workers/queues.js";
 import { logger } from "../utils/logger.js";
 
 export async function assignmentExists(id: string) {
@@ -312,8 +312,8 @@ export async function createAssignmentRecord(
 
   sendToMultiple({
     receiverIds: (studentIds && studentIds.length > 0) ? studentIds : classData.students.map((s) => s.id),
-    title: `New assignment for ${classData.name}`,
-    content: `The assignment "${title}" has been created in ${classData.name}.\nDue date: ${new Date(dueDate).toLocaleDateString()}.\n[Link to assignment](/class/${classId}/assignments/${assignment.id})`,
+    title: `New assignment in ${classData.name}`,
+    content: `"${title}" is due ${new Date(dueDate).toLocaleDateString()}.\n\n[View assignment](/class/${classId}/assignments/${assignment.id})`,
   }).catch((error) => {
     logger.error("Failed to send assignment notifications:", error);
   });
@@ -664,9 +664,22 @@ export async function updateSubmissionRecord(
     ) {
       const worksheetResponses = await prisma.studentWorksheetResponse.findMany({
         where: { submissionId: submission.id },
+        select: { id: true },
       });
       for (const wr of worksheetResponses) {
-        gradeWorksheetPipeline(wr.id);
+        try {
+          await enqueueRunJob(
+            "GRADE_WORKSHEET",
+            { worksheetResponseId: wr.id },
+            { classId: submission.assignment.classId, userId },
+          );
+        } catch (error) {
+          logger.error("Failed to enqueue worksheet grading on submit", {
+            error,
+            worksheetResponseId: wr.id,
+            submissionId: submission.id,
+          });
+        }
       }
     }
     return prisma.submission.update({

package/src/services/attendance.ts

@@ -14,6 +14,8 @@ import {
   createAttendanceForEvent,
   updateAttendance,
 } from "../models/attendance.js";
+import { sendToMultiple } from "./notification.js";
+import { logger } from "../utils/logger.js";
 
 /** Get attendance for a class (optionally filtered by event). Creates missing records. */
 export async function getAttendance(classId: string, eventId?: string) {
@@ -66,20 +68,103 @@ export async function updateAttendanceRecord(
   const presentIds = attendance.present.map((s) => s.id);
   const lateIds = attendance.late.map((s) => s.id);
   const absentIds = attendance.absent.map((s) => s.id);
+  const previousLateIds = new Set(existing?.late.map((student) => student.id) ?? []);
+  const previousAbsentIds = new Set(existing?.absent.map((student) => student.id) ?? []);
+  const classStudentIds = new Set(classData.students.map((student) => student.id));
 
   if (!existing) {
-    return createAttendance({
+    const created = await createAttendance({
       classId,
       eventId: eventId ?? null,
       presentIds,
       lateIds,
       absentIds,
     });
+    await notifyMarkedLateOrAbsent({
+      classId,
+      className: classData.name,
+      eventId: eventId ?? null,
+      eventName: created.event?.name ?? null,
+      classStudentIds,
+      lateIds,
+      absentIds,
+      previousLateIds,
+      previousAbsentIds,
+    });
+    return created;
   }
 
-  return updateAttendance(existing.id, {
+  const updated = await updateAttendance(existing.id, {
     presentIds,
     lateIds,
     absentIds,
   });
+  await notifyMarkedLateOrAbsent({
+    classId,
+    className: classData.name,
+    eventId: eventId ?? null,
+    eventName: existing.event?.name ?? null,
+    classStudentIds,
+    lateIds,
+    absentIds,
+    previousLateIds,
+    previousAbsentIds,
+  });
+  return updated;
+}
+
+/** Notify only students whose late or absent status is newly added. */
+async function notifyMarkedLateOrAbsent(input: {
+  classId: string;
+  className: string;
+  eventId: string | null;
+  eventName: string | null;
+  classStudentIds: Set<string>;
+  lateIds: string[];
+  absentIds: string[];
+  previousLateIds: Set<string>;
+  previousAbsentIds: Set<string>;
+}) {
+  const lateReceiverIds = [...new Set(input.lateIds)].filter(
+    (id) => input.classStudentIds.has(id) && !input.previousLateIds.has(id)
+  );
+  const absentReceiverIds = [...new Set(input.absentIds)].filter(
+    (id) => input.classStudentIds.has(id) && !input.previousAbsentIds.has(id)
+  );
+  const link = input.eventId
+    ? `/class/${input.classId}/attendance/${input.eventId}`
+    : `/class/${input.classId}/attendance`;
+  const attendanceLabel = input.eventName
+    ? `"${input.eventName}" in ${input.className}`
+    : input.className;
+
+  await Promise.all([
+    sendAttendanceNotification({
+      receiverIds: lateReceiverIds,
+      title: `Marked late in ${input.className}`,
+      content: `You were marked late for ${attendanceLabel}.\n[View attendance](${link})`,
+    }),
+    sendAttendanceNotification({
+      receiverIds: absentReceiverIds,
+      title: `Marked absent in ${input.className}`,
+      content: `You were marked absent for ${attendanceLabel}.\n[View attendance](${link})`,
+    }),
+  ]);
+}
+
+/** Send attendance notifications without failing the attendance update itself. */
+async function sendAttendanceNotification(input: {
+  receiverIds: string[];
+  title: string;
+  content: string;
+}) {
+  if (input.receiverIds.length === 0) {
+    return;
+  }
+
+  try {
+    await sendToMultiple(input);
+  } catch (error) {
+    logger.error("Failed to send attendance notifications:", { error });
+  }
 }