@studious-lms/server 1.20.0 → 1.22.0

package/src/routers/assignment.ts

@@ -180,6 +180,30 @@ const confirmAnnotationUploadSchema = z.object({
   errorMessage: z.string().optional(),
 });
 
+const listFileAnnotationsSchema = z.object({
+  classId: z.string(),
+  submissionId: z.string(),
+  fileId: z.string(),
+});
+
+const upsertFileAnnotationSchema = z.object({
+  classId: z.string(),
+  submissionId: z.string(),
+  fileId: z.string(),
+  id: z.string().optional(),
+  page: z.number().int().min(1),
+  type: z.enum(["HIGHLIGHT", "INK", "COMMENT", "TEXT"]),
+  geometry: z.record(z.string(), z.unknown()),
+  text: z.string().optional(),
+  color: z.string().optional(),
+});
+
+const deleteFileAnnotationSchema = z.object({
+  classId: z.string(),
+  submissionId: z.string(),
+  id: z.string(),
+});
+
 const updateUploadProgressSchema = z.object({
   fileId: z.string(),
   progress: z.number().min(0).max(100),
@@ -966,6 +990,186 @@ export const assignmentRouter = createTRPCRouter({
       };
     }),
 
+  listFileAnnotations: protectedClassMemberProcedure
+    .input(listFileAnnotationsSchema)
+    .query(async ({ ctx, input }) => {
+      const { classId, submissionId, fileId } = input;
+
+      const submission = await prisma.submission.findFirst({
+        where: {
+          id: submissionId,
+          assignment: { classId },
+        },
+        select: {
+          id: true,
+          studentId: true,
+          returned: true,
+          assignment: {
+            select: {
+              class: {
+                select: {
+                  teachers: { where: { id: ctx.user!.id }, select: { id: true } },
+                },
+              },
+            },
+          },
+        },
+      });
+
+      if (!submission) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "Submission not found",
+        });
+      }
+
+      const isTeacher = submission.assignment.class.teachers.length > 0;
+      const isOwningStudent = submission.studentId === ctx.user!.id;
+
+      if (!isTeacher && !(isOwningStudent && submission.returned)) {
+        throw new TRPCError({
+          code: "FORBIDDEN",
+          message: "You don't have access to these annotations",
+        });
+      }
+
+      const annotations = await prisma.fileAnnotation.findMany({
+        where: { submissionId, fileId },
+        orderBy: { createdAt: "asc" },
+        include: {
+          author: {
+            select: {
+              id: true,
+              username: true,
+              profile: { select: { displayName: true } },
+            },
+          },
+        },
+      });
+
+      return { annotations };
+    }),
+
+  upsertFileAnnotation: protectedTeacherProcedure
+    .input(upsertFileAnnotationSchema)
+    .mutation(async ({ ctx, input }) => {
+      const { classId, submissionId, fileId, id, page, type, geometry, text, color } = input;
+
+      const submission = await prisma.submission.findFirst({
+        where: {
+          id: submissionId,
+          assignment: {
+            classId,
+            class: {
+              teachers: {
+                some: { id: ctx.user!.id },
+              },
+            },
+          },
+        },
+        select: { id: true },
+      });
+
+      if (!submission) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "Submission not found or you are not a teacher of this class",
+        });
+      }
+
+      const file = await prisma.file.findFirst({
+        where: {
+          id: fileId,
+          OR: [{ submissionId }, { annotationId: submissionId }],
+        },
+        select: { id: true },
+      });
+
+      if (!file) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "File does not belong to this submission",
+        });
+      }
+
+      if (id) {
+        const existing = await prisma.fileAnnotation.findFirst({
+          where: { id, submissionId, fileId },
+          select: { id: true },
+        });
+
+        if (!existing) {
+          throw new TRPCError({
+            code: "NOT_FOUND",
+            message: "Annotation not found",
+          });
+        }
+
+        const annotation = await prisma.fileAnnotation.update({
+          where: { id },
+          data: {
+            page,
+            type,
+            geometry: geometry as object,
+            text: text ?? null,
+            color: color ?? null,
+          },
+        });
+
+        return { annotation };
+      }
+
+      const annotation = await prisma.fileAnnotation.create({
+        data: {
+          fileId,
+          submissionId,
+          authorId: ctx.user!.id,
+          page,
+          type,
+          geometry: geometry as object,
+          text: text ?? null,
+          color: color ?? null,
+        },
+      });
+
+      return { annotation };
+    }),
+
+  deleteFileAnnotation: protectedTeacherProcedure
+    .input(deleteFileAnnotationSchema)
+    .mutation(async ({ ctx, input }) => {
+      const { classId, submissionId, id } = input;
+
+      const annotation = await prisma.fileAnnotation.findFirst({
+        where: {
+          id,
+          submissionId,
+          submission: {
+            assignment: {
+              classId,
+              class: {
+                teachers: {
+                  some: { id: ctx.user!.id },
+                },
+              },
+            },
+          },
+        },
+        select: { id: true },
+      });
+
+      if (!annotation) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "Annotation not found or you are not a teacher of this class",
+        });
+      }
+
+      await prisma.fileAnnotation.delete({ where: { id } });
+
+      return { success: true };
+    }),
+
   updateUploadProgress: protectedProcedure
     .input(updateUploadProgressSchema)
     .mutation(async ({ ctx, input }) => {

package/src/routers/file.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
+import { TRPCError } from "@trpc/server";
 import { createTRPCRouter, protectedProcedure } from "../trpc.js";
+import { prisma } from "../lib/prisma.js";
 import {
   deleteFileGeneric,
   getFileSignedUrl,
@@ -7,6 +9,31 @@ import {
   renameFileScoped,
 } from "../services/file.js";
 
+const upsertAnnotationSchema = z.object({
+  fileId: z.string(),
+  id: z.string().optional(),
+  page: z.number().int().min(1),
+  type: z.enum(["HIGHLIGHT", "INK", "COMMENT", "TEXT"]),
+  geometry: z.record(z.string(), z.unknown()),
+  text: z.string().optional(),
+  color: z.string().optional(),
+});
+
+/** @throws NOT_FOUND unless the file exists and is owned by the user. */
+async function requireOwnedFile(userId: string, fileId: string) {
+  const file = await prisma.file.findFirst({
+    where: { id: fileId, userId },
+    select: { id: true },
+  });
+
+  if (!file) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "File not found or you don't own it",
+    });
+  }
+}
+
 /**
  * File router. Backed by the same unified scope-aware permission model as the
  * folder router. The class files page and the cloud-storage page (personal /
@@ -55,4 +82,105 @@ export const fileRouter = createTRPCRouter({
     .mutation(({ ctx, input }) =>
       deleteFileGeneric(ctx.user!.id, input.fileId)
     ),
+
+  // PDF annotations on files the user owns (personal cloud storage). The
+  // submission review flow uses the annotation endpoints on the assignment
+  // router instead; these are owner-only and carry no submission context.
+  listAnnotations: protectedProcedure
+    .input(z.object({ fileId: z.string() }))
+    .query(async ({ ctx, input }) => {
+      await requireOwnedFile(ctx.user!.id, input.fileId);
+
+      const annotations = await prisma.fileAnnotation.findMany({
+        where: { fileId: input.fileId, submissionId: null },
+        orderBy: { createdAt: "asc" },
+        include: {
+          author: {
+            select: {
+              id: true,
+              username: true,
+              profile: { select: { displayName: true } },
+            },
+          },
+        },
+      });
+
+      return { annotations };
+    }),
+
+  upsertAnnotation: protectedProcedure
+    .input(upsertAnnotationSchema)
+    .mutation(async ({ ctx, input }) => {
+      const { fileId, id, page, type, geometry, text, color } = input;
+
+      await requireOwnedFile(ctx.user!.id, fileId);
+
+      if (id) {
+        const existing = await prisma.fileAnnotation.findFirst({
+          where: { id, fileId, submissionId: null, authorId: ctx.user!.id },
+          select: { id: true },
+        });
+
+        if (!existing) {
+          throw new TRPCError({
+            code: "NOT_FOUND",
+            message: "Annotation not found",
+          });
+        }
+
+        const annotation = await prisma.fileAnnotation.update({
+          where: { id },
+          data: {
+            page,
+            type,
+            geometry: geometry as object,
+            text: text ?? null,
+            color: color ?? null,
+          },
+        });
+
+        return { annotation };
+      }
+
+      const annotation = await prisma.fileAnnotation.create({
+        data: {
+          fileId,
+          authorId: ctx.user!.id,
+          page,
+          type,
+          geometry: geometry as object,
+          text: text ?? null,
+          color: color ?? null,
+        },
+      });
+
+      return { annotation };
+    }),
+
+  deleteAnnotation: protectedProcedure
+    .input(z.object({ fileId: z.string(), id: z.string() }))
+    .mutation(async ({ ctx, input }) => {
+      await requireOwnedFile(ctx.user!.id, input.fileId);
+
+      const annotation = await prisma.fileAnnotation.findFirst({
+        where: {
+          id: input.id,
+          fileId: input.fileId,
+          submissionId: null,
+          authorId: ctx.user!.id,
+        },
+        select: { id: true },
+      });
+
+      if (!annotation) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "Annotation not found",
+        });
+      }
+
+      await prisma.fileAnnotation.delete({ where: { id: input.id } });
+
+      return { success: true };
+    }),
 });

package/src/routers/gradebook.ts

@@ -0,0 +1,173 @@
+import { z } from "zod";
+import {
+  createTRPCRouter,
+  protectedTeacherProcedure,
+  protectedClassMemberProcedure,
+} from "../trpc.js";
+import {
+  listGradeCategories,
+  createGradeCategory,
+  updateGradeCategory,
+  deleteGradeCategory,
+  assignAssignmentCategory,
+  listCustomGradeColumns,
+  createCustomGradeColumn,
+  updateCustomGradeColumn,
+  deleteCustomGradeColumn,
+  setCustomGradeEntry,
+  getGradePolicies,
+  updateGradePolicies,
+  getComputedGradebook,
+  exportGradebookCsv,
+} from "../services/gradebook.js";
+
+const roundingModeSchema = z.enum(["NONE", "HALF_UP", "FLOOR", "CEILING"]);
+
+export const gradebookRouter = createTRPCRouter({
+  listCategories: protectedClassMemberProcedure
+    .input(z.object({ classId: z.string() }))
+    .query(({ input }) => listGradeCategories(input.classId)),
+
+  createCategory: protectedTeacherProcedure
+    .input(
+      z.object({
+        classId: z.string(),
+        name: z.string().min(1),
+        weight: z.number().min(0),
+        dropLowest: z.number().int().min(0).optional(),
+        position: z.number().int().min(0).optional(),
+      })
+    )
+    .mutation(({ input }) => {
+      const { classId, ...data } = input;
+      return createGradeCategory(classId, data);
+    }),
+
+  updateCategory: protectedTeacherProcedure
+    .input(
+      z.object({
+        classId: z.string(),
+        categoryId: z.string(),
+        name: z.string().min(1).optional(),
+        weight: z.number().min(0).optional(),
+        dropLowest: z.number().int().min(0).optional(),
+        position: z.number().int().min(0).optional(),
+      })
+    )
+    .mutation(({ input }) => {
+      const { classId, categoryId, ...data } = input;
+      return updateGradeCategory(categoryId, classId, data);
+    }),
+
+  deleteCategory: protectedTeacherProcedure
+    .input(z.object({ classId: z.string(), categoryId: z.string() }))
+    .mutation(({ input }) =>
+      deleteGradeCategory(input.categoryId, input.classId)
+    ),
+
+  assignCategory: protectedTeacherProcedure
+    .input(
+      z.object({
+        classId: z.string(),
+        assignmentId: z.string(),
+        gradeCategoryId: z.string().nullable(),
+      })
+    )
+    .mutation(({ input }) =>
+      assignAssignmentCategory(
+        input.classId,
+        input.assignmentId,
+        input.gradeCategoryId
+      )
+    ),
+
+  listColumns: protectedClassMemberProcedure
+    .input(z.object({ classId: z.string() }))
+    .query(({ input }) => listCustomGradeColumns(input.classId)),
+
+  createColumn: protectedTeacherProcedure
+    .input(
+      z.object({
+        classId: z.string(),
+        name: z.string().min(1),
+        maxPoints: z.number().positive(),
+        gradeCategoryId: z.string().nullable().optional(),
+        position: z.number().int().min(0).optional(),
+      })
+    )
+    .mutation(({ input }) => {
+      const { classId, ...data } = input;
+      return createCustomGradeColumn(classId, data);
+    }),
+
+  updateColumn: protectedTeacherProcedure
+    .input(
+      z.object({
+        classId: z.string(),
+        columnId: z.string(),
+        name: z.string().min(1).optional(),
+        maxPoints: z.number().positive().optional(),
+        gradeCategoryId: z.string().nullable().optional(),
+        position: z.number().int().min(0).optional(),
+      })
+    )
+    .mutation(({ input }) => {
+      const { classId, columnId, ...data } = input;
+      return updateCustomGradeColumn(columnId, classId, data);
+    }),
+
+  deleteColumn: protectedTeacherProcedure
+    .input(z.object({ classId: z.string(), columnId: z.string() }))
+    .mutation(({ input }) =>
+      deleteCustomGradeColumn(input.columnId, input.classId)
+    ),
+
+  setEntry: protectedTeacherProcedure
+    .input(
+      z.object({
+        classId: z.string(),
+        columnId: z.string(),
+        studentId: z.string(),
+        points: z.number().min(0).nullable(),
+        note: z.string().nullable().optional(),
+      })
+    )
+    .mutation(({ input }) =>
+      setCustomGradeEntry(
+        input.classId,
+        input.columnId,
+        input.studentId,
+        input.points,
+        input.note
+      )
+    ),
+
+  getPolicies: protectedClassMemberProcedure
+    .input(z.object({ classId: z.string() }))
+    .query(({ input }) => getGradePolicies(input.classId)),
+
+  updatePolicies: protectedTeacherProcedure
+    .input(
+      z.object({
+        classId: z.string(),
+        treatMissingAsZero: z.boolean().optional(),
+        gradeRoundingMode: roundingModeSchema.optional(),
+      })
+    )
+    .mutation(({ input }) => {
+      const { classId, ...data } = input;
+      return updateGradePolicies(classId, data);
+    }),
+
+  getComputed: protectedClassMemberProcedure
+    .input(z.object({ classId: z.string() }))
+    .query(({ ctx, input }) =>
+      getComputedGradebook(input.classId, ctx.user?.id ?? "")
+    ),
+
+  exportCsv: protectedTeacherProcedure
+    .input(z.object({ classId: z.string() }))
+    .query(({ ctx, input }) =>
+      exportGradebookCsv(input.classId, ctx.user?.id ?? "")
+    ),
+});

package/src/services/adminInstitution.ts

@@ -1,4 +1,5 @@
 import type { Prisma } from '@prisma/client';
+import { TRPCError } from '@trpc/server';
 import { prisma } from '../lib/prisma.js';
 
 export async function listSchoolsForAdmin(input: {
@@ -45,6 +46,57 @@ export async function listSchoolsForAdmin(input: {
   };
 }
 
+export async function getSchoolForAdmin(id: string) {
+  const school = await prisma.school.findUnique({
+    where: { id },
+    include: {
+      _count: {
+        select: { memberships: true, classes: true, departments: true },
+      },
+      memberships: {
+        orderBy: { createdAt: 'desc' },
+        take: 100,
+        select: {
+          id: true,
+          role: true,
+          status: true,
+          createdAt: true,
+          user: {
+            select: { id: true, username: true, email: true, verified: true },
+          },
+        },
+      },
+      classes: {
+        orderBy: { name: 'asc' },
+        take: 100,
+        select: {
+          id: true,
+          name: true,
+          subject: true,
+          section: true,
+          color: true,
+          department: { select: { id: true, name: true } },
+          _count: { select: { students: true, teachers: true } },
+        },
+      },
+      departments: {
+        orderBy: { name: 'asc' },
+        select: {
+          id: true,
+          name: true,
+          color: true,
+          _count: { select: { classes: true, members: true } },
+        },
+      },
+    },
+  });
+
+  if (!school) {
+    throw new TRPCError({ code: 'NOT_FOUND', message: 'School not found' });
+  }
+  return school;
+}
+
 export async function listDepartmentsForAdmin(input: {
   page: number;
   pageSize: number;

package/src/services/adminMetrics.ts

@@ -0,0 +1,46 @@
+import { prisma } from '../lib/prisma.js';
+
+export async function getOverviewMetricsForAdmin() {
+  const dayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
+
+  const [
+    schools,
+    users,
+    verifiedUsers,
+    classes,
+    departments,
+    runJobsByStatus,
+    failedRunJobsLast24h,
+    earlyAccessRequests,
+    pendingDevProgramApplications,
+  ] = await Promise.all([
+    prisma.school.count(),
+    prisma.user.count(),
+    prisma.user.count({ where: { verified: true } }),
+    prisma.class.count(),
+    prisma.department.count(),
+    prisma.runJob.groupBy({ by: ['status'], _count: { _all: true } }),
+    prisma.runJob.count({
+      where: { status: 'FAILED', createdAt: { gte: dayAgo } },
+    }),
+    prisma.earlyAccessRequest.count(),
+    prisma.schoolDevelopementProgram.count({ where: { status: 'PENDING' } }),
+  ]);
+
+  return {
+    schools,
+    users,
+    verifiedUsers,
+    classes,
+    departments,
+    runJobs: {
+      byStatus: runJobsByStatus.map((row) => ({
+        status: row.status,
+        count: row._count._all,
+      })),
+      failedLast24h: failedRunJobsLast24h,
+    },
+    earlyAccessRequests,
+    pendingDevProgramApplications,
+  };
+}

package/src/services/adminRunJob.ts

@@ -1,6 +1,7 @@
 import type { Prisma, RunJobStatus, RunJobType } from '@prisma/client';
 import { TRPCError } from '@trpc/server';
 import { prisma } from '../lib/prisma.js';
+import { enqueueRunJob, type JobInputs } from '../workers/queues.js';
 
 export async function listRunJobsForAdmin(input: {
   page: number;
@@ -44,3 +45,26 @@ export async function getRunJobForAdmin(id: string) {
   }
   return job;
 }
+
+/**
+ * Re-enqueue a FAILED or CANCELLED job as a fresh RunJob row with the same
+ * type/input. The original row is left untouched for audit purposes.
+ */
+export async function retryRunJobForAdmin(id: string) {
+  const job = await getRunJobForAdmin(id);
+
+  if (job.status !== 'FAILED' && job.status !== 'CANCELLED') {
+    throw new TRPCError({
+      code: 'PRECONDITION_FAILED',
+      message: `Only FAILED or CANCELLED jobs can be retried (status: ${job.status})`,
+    });
+  }
+
+  const { runJobId, bullJobId } = await enqueueRunJob(
+    job.type,
+    job.input as JobInputs[typeof job.type],
+    { classId: job.classId, userId: job.userId },
+  );
+
+  return { runJobId, bullJobId, retriedFrom: job.id };
+}