@studious-lms/server 1.22.0 → 1.24.0

package/src/services/transcript.ts

@@ -0,0 +1,313 @@
+/**
+ * School-admin branded transcripts / progress reports (A4 — Nepal pilot).
+ *
+ * Aggregates per-class gradebook grades + grading boundaries + attendance %
+ * into a pdf-lib PDF. Branding: school name + logo (letterhead optional when
+ * present on School; schema does not include it yet — do not block).
+ *
+ * AcademicTerm (C1) is not modelled yet — accept `from`/`to` date range and/or
+ * a free-text `schoolYear` string for the report header.
+ *
+ * Attendance is read via the existing present/late/absent M2M lists only
+ * (same shaping as getStudentTimeline). Do not conflict with A1 Attendance
+ * refactor — rate math lives in attendanceRate.ts.
+ */
+
+import { TRPCError } from "@trpc/server";
+import { prisma } from "../lib/prisma.js";
+import { bucket } from "../lib/googleCloudStorage.js";
+import {
+  buildTranscriptPdf,
+  isLevelBasedBoundary,
+  type TranscriptClassRow,
+  type TranscriptReportVariant,
+} from "../lib/transcriptPdf.js";
+import {
+  findActiveSchoolAdminMembership,
+  getSchoolById,
+} from "../models/school.js";
+import { computeAttendanceRate } from "./attendanceRate.js";
+import { computeStudentGradeInClass } from "./gradebook.js";
+
+const MAX_BULK = 50;
+
+export interface GenerateTranscriptInput {
+  schoolId: string;
+  studentId: string;
+  from?: Date;
+  to?: Date;
+  /**
+   * Free-text school year label (e.g. "2082 BS", "2025–2026").
+   * Prefer AcademicTerm (C1) once available.
+   */
+  schoolYear?: string;
+}
+
+async function requireSchoolAdmin(schoolId: string, userId: string) {
+  const membership = await findActiveSchoolAdminMembership(schoolId, userId);
+  if (!membership) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Only school admins can generate transcripts",
+    });
+  }
+  return membership;
+}
+
+async function loadFileBytes(
+  path: string | null | undefined
+): Promise<Uint8Array | null> {
+  if (!path) return null;
+  try {
+    const [bytes] = await bucket.file(path).download();
+    return new Uint8Array(bytes);
+  } catch {
+    return null;
+  }
+}
+
+function formatPeriodLabel(from?: Date, to?: Date): string | null {
+  if (!from && !to) return null;
+  const fmt = (d: Date) => d.toISOString().slice(0, 10);
+  if (from && to) return `${fmt(from)} – ${fmt(to)}`;
+  if (from) return `From ${fmt(from)}`;
+  return `Through ${fmt(to!)}`;
+}
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 48);
+}
+
+async function fetchStudentAttendance(
+  studentId: string,
+  from?: Date,
+  to?: Date
+) {
+  const range = {
+    ...(from ? { gte: from } : {}),
+    ...(to ? { lte: to } : {}),
+  };
+  const hasRange = Object.keys(range).length > 0;
+
+  // Same M2M present/late/absent read path as getStudentTimeline (A1-safe).
+  const attendance = await prisma.attendance.findMany({
+    where: {
+      OR: [
+        { present: { some: { id: studentId } } },
+        { late: { some: { id: studentId } } },
+        { absent: { some: { id: studentId } } },
+      ],
+      ...(hasRange ? { date: range } : {}),
+    },
+    select: {
+      id: true,
+      present: { where: { id: studentId }, select: { id: true } },
+      late: { where: { id: studentId }, select: { id: true } },
+      absent: { where: { id: studentId }, select: { id: true } },
+    },
+  });
+
+  return attendance.map((record) => ({
+    status: record.present.length
+      ? ("PRESENT" as const)
+      : record.late.length
+        ? ("LATE" as const)
+        : ("ABSENT" as const),
+  }));
+}
+
+async function buildClassRows(
+  schoolId: string,
+  studentId: string
+): Promise<{ rows: TranscriptClassRow[]; variant: TranscriptReportVariant }> {
+  const classes = await prisma.class.findMany({
+    where: {
+      schoolId,
+      students: { some: { id: studentId } },
+    },
+    select: {
+      id: true,
+      name: true,
+      subject: true,
+      section: true,
+    },
+    orderBy: [{ subject: "asc" }, { name: "asc" }],
+  });
+
+  const rows: TranscriptClassRow[] = [];
+  let levelVotes = 0;
+  let letterVotes = 0;
+
+  for (const cls of classes) {
+    const grade = await computeStudentGradeInClass(cls.id, studentId);
+    if (!grade) continue;
+
+    if (isLevelBasedBoundary(grade.gradingBoundary?.structured)) {
+      levelVotes += 1;
+    } else if (grade.gradingBoundary) {
+      letterVotes += 1;
+    }
+
+    rows.push({
+      className: cls.name,
+      subject: cls.subject,
+      section: cls.section,
+      percentage: grade.result.percentage,
+      gradeLabel: grade.letterGrade,
+      categorySummaries: grade.result.categories.map((c) => ({
+        name: c.name,
+        average: c.average,
+      })),
+    });
+  }
+
+  const variant: TranscriptReportVariant =
+    levelVotes > 0 && levelVotes >= letterVotes ? "level" : "letter";
+
+  return { rows, variant };
+}
+
+export async function generateTranscript(
+  userId: string,
+  input: GenerateTranscriptInput
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+
+  const school = await getSchoolById(input.schoolId);
+  if (!school) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "School not found" });
+  }
+
+  const membership = await prisma.schoolMembership.findFirst({
+    where: {
+      schoolId: input.schoolId,
+      userId: input.studentId,
+      status: "ACTIVE",
+      role: "STUDENT",
+    },
+    select: {
+      user: {
+        select: {
+          id: true,
+          username: true,
+          profile: { select: { displayName: true } },
+        },
+      },
+    },
+  });
+  if (!membership) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Student is not an active student in this school",
+    });
+  }
+
+  const studentName =
+    membership.user.profile?.displayName || membership.user.username;
+
+  const [{ rows, variant }, attendanceStatuses, logoBytes] = await Promise.all([
+    buildClassRows(input.schoolId, input.studentId),
+    fetchStudentAttendance(input.studentId, input.from, input.to),
+    loadFileBytes(school.logo?.path),
+  ]);
+
+  // Soft letterhead support when schema later adds it — never required.
+  const schoolAny = school as {
+    letterhead?: { path?: string | null; type?: string | null } | null;
+    letterheadPath?: string | null;
+    letterheadType?: string | null;
+  };
+  const letterheadPath =
+    schoolAny.letterhead?.path ?? schoolAny.letterheadPath ?? null;
+  const letterheadType =
+    schoolAny.letterhead?.type ?? schoolAny.letterheadType ?? null;
+  const letterheadBytes = await loadFileBytes(letterheadPath);
+
+  const attendance = computeAttendanceRate(attendanceStatuses);
+  const generatedAt = new Date();
+
+  const pdfBytes = await buildTranscriptPdf({
+    schoolName: school.name,
+    studentName,
+    studentUsername: membership.user.username,
+    schoolYear: input.schoolYear ?? null,
+    periodLabel: formatPeriodLabel(input.from, input.to),
+    variant,
+    classes: rows,
+    attendance,
+    logoBytes,
+    logoContentType: school.logo?.type ?? null,
+    letterheadBytes,
+    letterheadContentType: letterheadType,
+    generatedAt,
+  });
+
+  const yearSlug = input.schoolYear
+    ? slugify(input.schoolYear)
+    : generatedAt.toISOString().slice(0, 10);
+  const fileName = `progress-report-${slugify(studentName) || membership.user.username}-${yearSlug}.pdf`;
+
+  return {
+    pdfBase64: Buffer.from(pdfBytes).toString("base64"),
+    fileName,
+    variant,
+    studentId: input.studentId,
+    studentName,
+    /** C1 blocker: AcademicTerm model does not exist yet. */
+    academicTermSupported: false as const,
+    attendance,
+    classCount: rows.length,
+  };
+}
+
+export async function generateTranscripts(
+  userId: string,
+  input: {
+    schoolId: string;
+    studentIds: string[];
+    from?: Date;
+    to?: Date;
+    schoolYear?: string;
+  }
+) {
+  await requireSchoolAdmin(input.schoolId, userId);
+
+  const uniqueIds = [...new Set(input.studentIds)].slice(0, MAX_BULK);
+  if (uniqueIds.length === 0) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Select at least one student",
+    });
+  }
+
+  type TranscriptResult = Awaited<ReturnType<typeof generateTranscript>>;
+  const results: TranscriptResult[] = [];
+  const errors: { studentId: string; message: string }[] = [];
+
+  for (const studentId of uniqueIds) {
+    try {
+      const result = await generateTranscript(userId, {
+        schoolId: input.schoolId,
+        studentId,
+        from: input.from,
+        to: input.to,
+        schoolYear: input.schoolYear,
+      });
+      results.push(result);
+    } catch (error) {
+      const message =
+        error instanceof TRPCError
+          ? error.message
+          : error instanceof Error
+            ? error.message
+            : "Failed to generate transcript";
+      errors.push({ studentId, message });
+    }
+  }
+
+  return { transcripts: results, errors };
+}

package/src/services/worksheet.ts

@@ -308,6 +308,7 @@ export async function addQuestionToWorksheet(
     markScheme?: object;
     type: WorksheetQuestionType;
     order?: number;
+    parentQuestionId?: string | null;
   }
 ) {
   const worksheet = await findWorksheetByIdForTeacher(worksheetId, userId);
@@ -317,6 +318,24 @@ export async function addQuestionToWorksheet(
       message: "Only class teachers can modify worksheet questions",
     });
   }
+  if (data.parentQuestionId) {
+    const parent = await findWorksheetQuestionByIdInWorksheet(
+      data.parentQuestionId,
+      worksheetId
+    );
+    if (!parent) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "Parent question not found in this worksheet",
+      });
+    }
+    if (parent.parentQuestionId) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "Subquestions cannot themselves have children",
+      });
+    }
+  }
   return createWorksheetQuestion({
     worksheetId,
     ...data,
@@ -459,6 +478,7 @@ export async function updateWorksheetQuestionRecord(
     options?: object;
     markScheme?: object;
     type?: WorksheetQuestionType;
+    parentQuestionId?: string | null;
   }
 ) {
   const question = await findWorksheetQuestionByIdForTeacher(questionId, userId);
@@ -468,9 +488,100 @@ export async function updateWorksheetQuestionRecord(
       message: "Only class teachers can update worksheet questions",
     });
   }
+  if (data.parentQuestionId) {
+    if (data.parentQuestionId === questionId) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "A question cannot be its own parent",
+      });
+    }
+    const parent = await findWorksheetQuestionByIdInWorksheet(
+      data.parentQuestionId,
+      worksheetId
+    );
+    if (!parent) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "Parent question not found in this worksheet",
+      });
+    }
+    if (parent.parentQuestionId) {
+      throw new TRPCError({
+        code: "BAD_REQUEST",
+        message: "Subquestions cannot themselves have children",
+      });
+    }
+  }
   return updateWorksheetQuestion(questionId, data);
 }
 
+/** Answering statistics for each question — shown in the teacher worksheet editor. */
+export async function getWorksheetQuestionStats(
+  worksheetId: string,
+  userId: string
+) {
+  const worksheet = await findWorksheetByIdForTeacher(worksheetId, userId);
+  if (!worksheet) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Only class teachers can view worksheet answering statistics",
+    });
+  }
+
+  const questions = await prisma.worksheetQuestion.findMany({
+    where: { worksheetId },
+    select: {
+      id: true,
+      parentQuestionId: true,
+      order: true,
+      points: true,
+      question: true,
+      type: true,
+      studentResponses: {
+        select: {
+          id: true,
+          isCorrect: true,
+          points: true,
+          response: true,
+          studentWorksheetResponse: {
+            select: { submitted: true },
+          },
+        },
+      },
+    },
+    orderBy: { order: "asc" },
+  });
+
+  return questions.map((q) => {
+    const responses = q.studentResponses;
+    const answered = responses.filter(
+      (r) => r.response !== null && r.response !== ""
+    );
+    const submitted = responses.filter(
+      (r) => r.studentWorksheetResponse?.submitted
+    );
+    const correct = answered.filter((r) => r.isCorrect).length;
+    return {
+      questionId: q.id,
+      parentQuestionId: q.parentQuestionId,
+      order: q.order,
+      type: q.type,
+      points: q.points,
+      promptPreview: q.question.slice(0, 120),
+      totalResponses: responses.length,
+      answeredCount: answered.length,
+      submittedCount: submitted.length,
+      correctCount: correct,
+      averagePoints:
+        answered.length === 0
+          ? null
+          : answered.reduce((sum, r) => sum + (r.points ?? 0), 0) /
+            answered.length,
+      correctRate: answered.length === 0 ? null : correct / answered.length,
+    };
+  });
+}
+
 export async function deleteWorksheetQuestionRecord(
   worksheetId: string,
   questionId: string,

package/src/trpc.ts

@@ -7,7 +7,7 @@ import { Request, Response } from 'express';
 import { z } from 'zod';
 import { handlePrismaError, PrismaErrorInfo } from './utils/prismaErrorHandler.js';
 import { findUserBySessionToken } from './models/auth.js';
-import { assertAdminPanelUser } from './utils/adminPanelAccess.js';
+import { assertAdminPanelPassword } from './utils/adminPanelAccess.js';
 
 interface CreateContextOptions {
   req: Request;
@@ -96,11 +96,11 @@ const adminPanelMiddleware = t.middleware(({ ctx, next }) => {
       message: 'Not authenticated',
     });
   }
-  assertAdminPanelUser(ctx.user.id);
+  assertAdminPanelPassword(ctx.req);
   return next({ ctx });
 });
 
-/** Authenticated + env allowlist (see `assertAdminPanelUser`). */
+/** Authenticated + fixed admin password header (see `assertAdminPanelPassword`). */
 export const adminProcedure = protectedProcedure.use(adminPanelMiddleware);
 
 export const protectedClassMemberProcedure = protectedProcedure

package/src/utils/adminPanelAccess.ts

@@ -1,46 +1,23 @@
 import { TRPCError } from '@trpc/server';
-import { env } from '../lib/config/env.js';
+import type { Request } from 'express';
 
-function parseAdminUserIds(raw: string | undefined): Set<string> {
-  if (!raw?.trim()) return new Set();
-  return new Set(
-    raw
-      .split(/[\s,]+/)
-      .map((s) => s.trim())
-      .filter(Boolean),
-  );
-}
+/** Fixed password gating the admin tRPC routes. */
+const ADMIN_PANEL_PASSWORD = 'alan6767';
+
+const ADMIN_PASSWORD_HEADER = 'x-admin-password';
 
 /**
- * Admin tRPC routes: in production `ADMIN_PANEL_USER_IDS` must be a non-empty
- * comma/whitespace-separated list of user UUIDs. In non-production, an empty
- * unset value allows any authenticated user (local ops); a non-empty list is
- * still enforced.
+ * Admin tRPC routes require the fixed admin password in the
+ * `x-admin-password` header (sent by the admin panel).
  */
-export function assertAdminPanelUser(userId: string): void {
-  const allowed = parseAdminUserIds(env.ADMIN_PANEL_USER_IDS);
-
-  if (env.NODE_ENV === 'production') {
-    if (allowed.size === 0) {
-      throw new TRPCError({
-        code: 'FORBIDDEN',
-        message:
-          'Admin API disabled: set ADMIN_PANEL_USER_IDS to a non-empty list of user ids.',
-      });
-    }
-    if (!allowed.has(userId)) {
-      throw new TRPCError({
-        code: 'FORBIDDEN',
-        message: 'You are not allowed to use the admin API.',
-      });
-    }
-    return;
-  }
+export function assertAdminPanelPassword(req: Request): void {
+  const header = req.headers[ADMIN_PASSWORD_HEADER];
+  const provided = typeof header === 'string' ? header : header?.[0];
 
-  if (allowed.size > 0 && !allowed.has(userId)) {
+  if (provided !== ADMIN_PANEL_PASSWORD) {
     throw new TRPCError({
       code: 'FORBIDDEN',
-      message: 'You are not allowed to use the admin API.',
+      message: 'Invalid admin password.',
     });
   }
 }

package/tests/unit/assignmentTypeDefaults.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import {
+  getAssignmentTypeDefaults,
+  resolveAssignmentBehavior,
+} from "../../src/lib/assignmentTypeDefaults.js";
+
+describe("getAssignmentTypeDefaults", () => {
+  it("configures QUIZ without late file spam by default", () => {
+    const quiz = getAssignmentTypeDefaults("QUIZ");
+    expect(quiz.acceptFiles).toBe(false);
+    expect(quiz.singleAttempt).toBe(true);
+    expect(quiz.allowLateSubmissions).toBe(false);
+    expect(quiz.acceptWorksheet).toBe(true);
+  });
+
+  it("configures ESSAY for extended response", () => {
+    const essay = getAssignmentTypeDefaults("ESSAY");
+    expect(essay.acceptExtendedResponse).toBe(true);
+    expect(essay.acceptFiles).toBe(false);
+    expect(essay.singleAttempt).toBe(false);
+  });
+});
+
+describe("resolveAssignmentBehavior", () => {
+  it("applies QUIZ defaults when fields omitted", () => {
+    const resolved = resolveAssignmentBehavior({ type: "QUIZ" });
+    expect(resolved.acceptFiles).toBe(false);
+    expect(resolved.singleAttempt).toBe(true);
+    expect(resolved.allowLateSubmissions).toBe(false);
+  });
+
+  it("lets teachers override QUIZ file acceptance", () => {
+    const resolved = resolveAssignmentBehavior({
+      type: "QUIZ",
+      acceptFiles: true,
+      acceptWorksheet: true,
+    });
+    expect(resolved.acceptFiles).toBe(true);
+  });
+
+  it("rejects zero deliverables", () => {
+    expect(() =>
+      resolveAssignmentBehavior({
+        type: "HOMEWORK",
+        acceptFiles: false,
+        acceptExtendedResponse: false,
+        acceptWorksheet: false,
+        applyTypeDefaults: false,
+      })
+    ).toThrow(/at least one deliverable/);
+  });
+});

package/tests/unit/lib/feePdf.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+import { formatNpr, monthLabel } from "../../../src/lib/feePdfFormat.js";
+
+describe("feePdfFormat helpers", () => {
+  it("formats NPR amounts", () => {
+    expect(formatNpr(1500)).toContain("1,500");
+    expect(formatNpr(1500)).toMatch(/^NPR /);
+  });
+
+  it("labels calendar months in UTC", () => {
+    expect(monthLabel(2026, 1)).toBe("January 2026");
+    expect(monthLabel(2026, 8)).toBe("August 2026");
+    expect(monthLabel(2026, 12)).toBe("December 2026");
+  });
+});

package/tests/unit/lib/idCardPdf.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_BRAND_COLOR,
+  ID_CARD_HEIGHT,
+  ID_CARD_WIDTH,
+  parseHexColor,
+  toPngBytes,
+} from "../../../src/lib/idCardPdf.js";
+
+describe("idCardPdf helpers", () => {
+  it("exposes CR80 card dimensions", () => {
+    expect(ID_CARD_WIDTH).toBe(243);
+    expect(ID_CARD_HEIGHT).toBe(153);
+  });
+
+  it("parses valid hex colors", () => {
+    const color = parseHexColor("#3B82F6");
+    expect(color.red).toBeCloseTo(0x3b / 255, 5);
+    expect(color.green).toBeCloseTo(0x82 / 255, 5);
+    expect(color.blue).toBeCloseTo(0xf6 / 255, 5);
+  });
+
+  it("falls back for invalid or missing hex", () => {
+    const fallback = parseHexColor(DEFAULT_BRAND_COLOR);
+    expect(parseHexColor(null)).toEqual(fallback);
+    expect(parseHexColor("not-a-color")).toEqual(fallback);
+    expect(parseHexColor("#fff")).toEqual(fallback);
+  });
+
+  it("converts a minimal PNG through sharp", async () => {
+    const tinyPng = Buffer.from(
+      "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
+      "base64"
+    );
+    const out = await toPngBytes(tinyPng);
+    expect(out).not.toBeNull();
+    expect(out!.byteLength).toBeGreaterThan(20);
+    expect(Buffer.from(out!.slice(0, 4)).toString("hex")).toBe("89504e47");
+  });
+});