@studious-lms/server 1.23.0 → 1.25.0

package/src/lib/transcriptPdf.ts

@@ -0,0 +1,502 @@
+/**
+ * Branded transcript / progress-report PDF builder (pdf-lib).
+ *
+ * Variants:
+ * - `letter` — percentage + letter-grade style transcript
+ * - `level` — CDC Annex-4 style progress report (Below Basic / Basic /
+ *   Proficient / Advanced) when grading boundaries are level-based
+ *
+ * School branding uses name + optional logo. Letterhead is not in the School
+ * schema yet — when added, callers can pass `letterheadBytes` without blocking.
+ */
+
+import { PDFDocument, PDFFont, PDFPage, PDFImage, rgb, StandardFonts } from "pdf-lib";
+import fontkit from "@pdf-lib/fontkit";
+import { readFileSync } from "fs";
+import { join } from "path";
+
+export type TranscriptReportVariant = "letter" | "level";
+
+export interface TranscriptClassRow {
+  className: string;
+  subject: string;
+  section: string;
+  percentage: number | null;
+  gradeLabel: string | null;
+  categorySummaries: { name: string; average: number | null }[];
+}
+
+export interface TranscriptAttendanceSummary {
+  present: number;
+  late: number;
+  absent: number;
+  total: number;
+  /** (present + late) / total * 100, or null when total is 0. */
+  percent: number | null;
+}
+
+export interface TranscriptPdfInput {
+  schoolName: string;
+  studentName: string;
+  studentUsername?: string | null;
+  /** Free-text school year (no AcademicTerm model yet — see C1). */
+  schoolYear?: string | null;
+  periodLabel?: string | null;
+  variant: TranscriptReportVariant;
+  classes: TranscriptClassRow[];
+  attendance: TranscriptAttendanceSummary;
+  logoBytes?: Uint8Array | null;
+  logoContentType?: string | null;
+  /** Optional future letterhead image; ignored when null/undefined. */
+  letterheadBytes?: Uint8Array | null;
+  letterheadContentType?: string | null;
+  generatedAt?: Date;
+}
+
+const PAGE_WIDTH = 595.28; // A4
+const PAGE_HEIGHT = 841.89;
+const MARGIN = 48;
+const CONTENT_WIDTH = PAGE_WIDTH - MARGIN * 2;
+
+const LEVEL_ORDER = [
+  "Below Basic",
+  "Basic",
+  "Proficient",
+  "Advanced",
+] as const;
+
+const LEVEL_COLORS: Record<(typeof LEVEL_ORDER)[number], ReturnType<typeof rgb>> = {
+  "Below Basic": rgb(0.75, 0.22, 0.17),
+  Basic: rgb(0.85, 0.55, 0.13),
+  Proficient: rgb(0.2, 0.45, 0.7),
+  Advanced: rgb(0.13, 0.55, 0.35),
+};
+
+async function embedFonts(pdfDoc: PDFDocument): Promise<{
+  regular: PDFFont;
+  bold: PDFFont;
+}> {
+  pdfDoc.registerFontkit(fontkit);
+  const fontDir = join(process.cwd(), "src", "lib");
+  try {
+    const regularBytes = readFileSync(join(fontDir, "NotoSans-Regular.ttf"));
+    const boldBytes = readFileSync(join(fontDir, "NotoSans-Bold.ttf"));
+    return {
+      regular: await pdfDoc.embedFont(regularBytes),
+      bold: await pdfDoc.embedFont(boldBytes),
+    };
+  } catch {
+    return {
+      regular: await pdfDoc.embedFont(StandardFonts.Helvetica),
+      bold: await pdfDoc.embedFont(StandardFonts.HelveticaBold),
+    };
+  }
+}
+
+async function embedImage(
+  pdfDoc: PDFDocument,
+  bytes: Uint8Array | null | undefined,
+  contentType?: string | null
+): Promise<PDFImage | null> {
+  if (!bytes || bytes.length === 0) return null;
+  const type = (contentType ?? "").toLowerCase();
+  try {
+    if (type.includes("png") || (!type && looksLikePng(bytes))) {
+      return await pdfDoc.embedPng(bytes);
+    }
+    return await pdfDoc.embedJpg(bytes);
+  } catch {
+    try {
+      return await pdfDoc.embedPng(bytes);
+    } catch {
+      try {
+        return await pdfDoc.embedJpg(bytes);
+      } catch {
+        return null;
+      }
+    }
+  }
+}
+
+function looksLikePng(bytes: Uint8Array): boolean {
+  return (
+    bytes.length >= 8 &&
+    bytes[0] === 0x89 &&
+    bytes[1] === 0x50 &&
+    bytes[2] === 0x4e &&
+    bytes[3] === 0x47
+  );
+}
+
+function formatPercent(value: number | null): string {
+  if (value === null || Number.isNaN(value)) return "—";
+  return `${value.toFixed(1)}%`;
+}
+
+function drawText(
+  page: PDFPage,
+  text: string,
+  x: number,
+  y: number,
+  font: PDFFont,
+  size: number,
+  color = rgb(0.12, 0.12, 0.14)
+) {
+  page.drawText(text, { x, y, size, font, color });
+}
+
+function truncateToWidth(
+  text: string,
+  font: PDFFont,
+  size: number,
+  maxWidth: number
+): string {
+  if (font.widthOfTextAtSize(text, size) <= maxWidth) return text;
+  let truncated = text;
+  while (truncated.length > 1) {
+    truncated = truncated.slice(0, -1);
+    if (font.widthOfTextAtSize(`${truncated}…`, size) <= maxWidth) {
+      return `${truncated}…`;
+    }
+  }
+  return "…";
+}
+
+/**
+ * Detects CDC Annex-4 style level boundaries from a GradingBoundary
+ * `structured` JSON payload.
+ */
+export function isLevelBasedBoundary(structured: string | null | undefined): boolean {
+  if (!structured) return false;
+  try {
+    const parsed = JSON.parse(structured) as {
+      boundaries?: { grade?: string }[];
+    };
+    if (!Array.isArray(parsed.boundaries) || parsed.boundaries.length === 0) {
+      return false;
+    }
+    const grades = parsed.boundaries
+      .map((b) => (b.grade ?? "").trim().toLowerCase())
+      .filter(Boolean);
+    if (grades.length === 0) return false;
+
+    const levelSet = new Set(LEVEL_ORDER.map((g) => g.toLowerCase()));
+    const matches = grades.filter((g) => levelSet.has(g));
+    return matches.length >= Math.ceil(grades.length * 0.5);
+  } catch {
+    return false;
+  }
+}
+
+export async function buildTranscriptPdf(
+  input: TranscriptPdfInput
+): Promise<Uint8Array> {
+  const pdfDoc = await PDFDocument.create();
+  const { regular, bold } = await embedFonts(pdfDoc);
+  const logo = await embedImage(pdfDoc, input.logoBytes, input.logoContentType);
+  const letterhead = await embedImage(
+    pdfDoc,
+    input.letterheadBytes,
+    input.letterheadContentType
+  );
+
+  let page = pdfDoc.addPage([PAGE_WIDTH, PAGE_HEIGHT]);
+  let y = PAGE_HEIGHT - MARGIN;
+
+  if (letterhead) {
+    const lhHeight = 72;
+    const scale = Math.min(
+      CONTENT_WIDTH / letterhead.width,
+      lhHeight / letterhead.height
+    );
+    const w = letterhead.width * scale;
+    const h = letterhead.height * scale;
+    page.drawImage(letterhead, {
+      x: MARGIN + (CONTENT_WIDTH - w) / 2,
+      y: y - h,
+      width: w,
+      height: h,
+    });
+    y -= h + 16;
+  }
+
+  const logoSize = 48;
+  let textLeft = MARGIN;
+  if (logo) {
+    const scale = Math.min(logoSize / logo.width, logoSize / logo.height);
+    const w = logo.width * scale;
+    const h = logo.height * scale;
+    page.drawImage(logo, {
+      x: MARGIN,
+      y: y - h,
+      width: w,
+      height: h,
+    });
+    textLeft = MARGIN + w + 14;
+  }
+
+  const title =
+    input.variant === "level"
+      ? "Student Progress Report"
+      : "Academic Transcript";
+
+  drawText(page, input.schoolName, textLeft, y - 16, bold, 16);
+  drawText(page, title, textLeft, y - 34, regular, 11, rgb(0.35, 0.35, 0.4));
+  y -= logo || letterhead ? 64 : 48;
+
+  page.drawLine({
+    start: { x: MARGIN, y },
+    end: { x: PAGE_WIDTH - MARGIN, y },
+    thickness: 1,
+    color: rgb(0.82, 0.82, 0.85),
+  });
+  y -= 22;
+
+  drawText(page, "Student", MARGIN, y, regular, 9, rgb(0.45, 0.45, 0.5));
+  y -= 14;
+  drawText(page, input.studentName, MARGIN, y, bold, 13);
+  y -= 16;
+  if (input.studentUsername) {
+    drawText(
+      page,
+      `@${input.studentUsername}`,
+      MARGIN,
+      y,
+      regular,
+      9,
+      rgb(0.4, 0.4, 0.45)
+    );
+    y -= 14;
+  }
+
+  const metaParts: string[] = [];
+  if (input.schoolYear?.trim()) {
+    metaParts.push(`School year: ${input.schoolYear.trim()}`);
+  }
+  if (input.periodLabel?.trim()) {
+    metaParts.push(`Period: ${input.periodLabel.trim()}`);
+  }
+  if (metaParts.length === 0) {
+    metaParts.push("Period: All recorded grades & attendance");
+  }
+  drawText(
+    page,
+    metaParts.join("  ·  "),
+    MARGIN,
+    y,
+    regular,
+    9,
+    rgb(0.35, 0.35, 0.4)
+  );
+  y -= 24;
+
+  y = drawAttendanceBlock(page, y, input.attendance, regular, bold);
+
+  if (input.variant === "level") {
+    y = drawLevelLegend(page, y, regular, bold);
+  }
+
+  const reportTitle =
+    input.variant === "level" ? "Subject progress" : "Course grades";
+  drawText(page, reportTitle, MARGIN, y, bold, 11);
+  y -= 16;
+
+  y = drawTableHeader(page, y, input.variant, bold);
+
+  if (input.classes.length === 0) {
+    drawText(
+      page,
+      "No enrolled classes with grade data for this period.",
+      MARGIN,
+      y,
+      regular,
+      9,
+      rgb(0.45, 0.45, 0.5)
+    );
+    y -= 18;
+  } else {
+    for (const row of input.classes) {
+      if (y < MARGIN + 80) {
+        page = pdfDoc.addPage([PAGE_WIDTH, PAGE_HEIGHT]);
+        y = PAGE_HEIGHT - MARGIN;
+        y = drawTableHeader(page, y, input.variant, bold);
+      }
+      y = drawClassRow(page, y, row, input.variant, regular, bold);
+    }
+  }
+
+  const generated = input.generatedAt ?? new Date();
+  const footer = `Generated ${generated.toISOString().slice(0, 10)} · Studious LMS`;
+  drawText(
+    page,
+    footer,
+    MARGIN,
+    MARGIN - 8,
+    regular,
+    8,
+    rgb(0.55, 0.55, 0.58)
+  );
+
+  drawText(
+    page,
+    "Note: Academic terms (C1) are not modelled yet; period filters use dates or a school-year label.",
+    MARGIN,
+    MARGIN - 20,
+    regular,
+    7,
+    rgb(0.6, 0.6, 0.62)
+  );
+
+  return pdfDoc.save();
+}
+
+function drawAttendanceBlock(
+  page: PDFPage,
+  y: number,
+  attendance: TranscriptAttendanceSummary,
+  regular: PDFFont,
+  bold: PDFFont
+): number {
+  drawText(page, "Attendance", MARGIN, y, bold, 11);
+  y -= 14;
+
+  const line = [
+    `Present: ${attendance.present}`,
+    `Late: ${attendance.late}`,
+    `Absent: ${attendance.absent}`,
+    `Rate: ${formatPercent(attendance.percent)}`,
+  ].join("   ·   ");
+
+  drawText(page, line, MARGIN, y, regular, 9, rgb(0.25, 0.25, 0.3));
+  y -= 8;
+  drawText(
+    page,
+    "Rate = (present + late) / (present + late + absent). Excused status is not modelled in this report path.",
+    MARGIN,
+    y,
+    regular,
+    7,
+    rgb(0.55, 0.55, 0.58)
+  );
+  return y - 20;
+}
+
+function drawLevelLegend(
+  page: PDFPage,
+  y: number,
+  regular: PDFFont,
+  bold: PDFFont
+): number {
+  drawText(page, "Achievement levels (CDC Annex-4 style)", MARGIN, y, bold, 10);
+  y -= 14;
+  let x = MARGIN;
+  for (const level of LEVEL_ORDER) {
+    const color = LEVEL_COLORS[level];
+    page.drawRectangle({
+      x,
+      y: y - 2,
+      width: 8,
+      height: 8,
+      color,
+    });
+    drawText(page, level, x + 12, y - 1, regular, 8, color);
+    x += level.length * 8 * 0.52 + 28;
+  }
+  return y - 22;
+}
+
+function drawTableHeader(
+  page: PDFPage,
+  y: number,
+  variant: TranscriptReportVariant,
+  bold: PDFFont
+): number {
+  const gradeCol = variant === "level" ? "Level" : "Grade";
+  page.drawRectangle({
+    x: MARGIN,
+    y: y - 4,
+    width: CONTENT_WIDTH,
+    height: 18,
+    color: rgb(0.94, 0.95, 0.97),
+  });
+  drawText(page, "Subject / Class", MARGIN + 6, y, bold, 8);
+  drawText(page, "Section", MARGIN + 250, y, bold, 8);
+  drawText(page, "Score", MARGIN + 320, y, bold, 8);
+  drawText(page, gradeCol, MARGIN + 390, y, bold, 8);
+  return y - 20;
+}
+
+function drawClassRow(
+  page: PDFPage,
+  y: number,
+  row: TranscriptClassRow,
+  variant: TranscriptReportVariant,
+  regular: PDFFont,
+  bold: PDFFont
+): number {
+  const label = truncateToWidth(
+    row.subject?.trim()
+      ? `${row.subject} — ${row.className}`
+      : row.className,
+    regular,
+    9,
+    230
+  );
+  drawText(page, label, MARGIN + 6, y, regular, 9);
+  drawText(
+    page,
+    truncateToWidth(row.section || "—", regular, 9, 60),
+    MARGIN + 250,
+    y,
+    regular,
+    9
+  );
+  drawText(page, formatPercent(row.percentage), MARGIN + 320, y, regular, 9);
+
+  const grade = row.gradeLabel?.trim() || "—";
+  const levelKey = LEVEL_ORDER.find(
+    (l) => l.toLowerCase() === grade.toLowerCase()
+  );
+  const gradeColor =
+    variant === "level" && levelKey
+      ? LEVEL_COLORS[levelKey]
+      : rgb(0.12, 0.12, 0.14);
+  drawText(
+    page,
+    truncateToWidth(grade, bold, 9, 120),
+    MARGIN + 390,
+    y,
+    bold,
+    9,
+    gradeColor
+  );
+
+  y -= 14;
+
+  if (row.categorySummaries.length > 0) {
+    const cats = row.categorySummaries
+      .filter((c) => c.average !== null)
+      .map((c) => `${c.name}: ${formatPercent(c.average)}`)
+      .join("  ·  ");
+    if (cats) {
+      drawText(
+        page,
+        truncateToWidth(cats, regular, 7, CONTENT_WIDTH - 12),
+        MARGIN + 6,
+        y,
+        regular,
+        7,
+        rgb(0.45, 0.45, 0.5)
+      );
+      y -= 12;
+    }
+  }
+
+  page.drawLine({
+    start: { x: MARGIN, y: y + 4 },
+    end: { x: PAGE_WIDTH - MARGIN, y: y + 4 },
+    thickness: 0.5,
+    color: rgb(0.9, 0.9, 0.92),
+  });
+  return y - 6;
+}

package/src/models/academicCalendar.ts

@@ -0,0 +1,139 @@
+/**
+ * Academic year / term model helpers (C1).
+ */
+import { prisma } from "../lib/prisma.js";
+
+export function listAcademicYears(schoolId: string) {
+  return prisma.academicYear.findMany({
+    where: { schoolId },
+    orderBy: [{ isCurrent: "desc" }, { startDate: "desc" }],
+    include: {
+      terms: { orderBy: [{ isCurrent: "desc" }, { startDate: "asc" }] },
+    },
+  });
+}
+
+export function getAcademicYearById(id: string, schoolId: string) {
+  return prisma.academicYear.findFirst({
+    where: { id, schoolId },
+    include: {
+      terms: { orderBy: [{ isCurrent: "desc" }, { startDate: "asc" }] },
+    },
+  });
+}
+
+export function createAcademicYear(data: {
+  schoolId: string;
+  name: string;
+  startDate: Date;
+  endDate: Date;
+  isCurrent?: boolean;
+}) {
+  return prisma.$transaction(async (tx) => {
+    if (data.isCurrent) {
+      await tx.academicYear.updateMany({
+        where: { schoolId: data.schoolId, isCurrent: true },
+        data: { isCurrent: false },
+      });
+    }
+    return tx.academicYear.create({
+      data: {
+        schoolId: data.schoolId,
+        name: data.name,
+        startDate: data.startDate,
+        endDate: data.endDate,
+        isCurrent: data.isCurrent ?? false,
+      },
+      include: { terms: true },
+    });
+  });
+}
+
+export function updateAcademicYear(
+  id: string,
+  schoolId: string,
+  data: {
+    name?: string;
+    startDate?: Date;
+    endDate?: Date;
+    isCurrent?: boolean;
+  }
+) {
+  return prisma.$transaction(async (tx) => {
+    const existing = await tx.academicYear.findFirst({ where: { id, schoolId } });
+    if (!existing) return null;
+    if (data.isCurrent) {
+      await tx.academicYear.updateMany({
+        where: { schoolId, isCurrent: true, NOT: { id } },
+        data: { isCurrent: false },
+      });
+    }
+    return tx.academicYear.update({
+      where: { id },
+      data,
+      include: {
+        terms: { orderBy: [{ isCurrent: "desc" }, { startDate: "asc" }] },
+      },
+    });
+  });
+}
+
+export function deleteAcademicYear(id: string, schoolId: string) {
+  return prisma.academicYear.deleteMany({ where: { id, schoolId } });
+}
+
+export function createAcademicTerm(data: {
+  academicYearId: string;
+  name: string;
+  startDate: Date;
+  endDate: Date;
+  isCurrent?: boolean;
+}) {
+  return prisma.$transaction(async (tx) => {
+    if (data.isCurrent) {
+      await tx.academicTerm.updateMany({
+        where: { academicYearId: data.academicYearId, isCurrent: true },
+        data: { isCurrent: false },
+      });
+    }
+    return tx.academicTerm.create({ data: { ...data, isCurrent: data.isCurrent ?? false } });
+  });
+}
+
+export function updateAcademicTerm(
+  id: string,
+  academicYearId: string,
+  data: {
+    name?: string;
+    startDate?: Date;
+    endDate?: Date;
+    isCurrent?: boolean;
+  }
+) {
+  return prisma.$transaction(async (tx) => {
+    const existing = await tx.academicTerm.findFirst({
+      where: { id, academicYearId },
+    });
+    if (!existing) return null;
+    if (data.isCurrent) {
+      await tx.academicTerm.updateMany({
+        where: { academicYearId, isCurrent: true, NOT: { id } },
+        data: { isCurrent: false },
+      });
+    }
+    return tx.academicTerm.update({ where: { id }, data });
+  });
+}
+
+export function deleteAcademicTerm(id: string, academicYearId: string) {
+  return prisma.academicTerm.deleteMany({ where: { id, academicYearId } });
+}
+
+export function getCurrentAcademicYear(schoolId: string) {
+  return prisma.academicYear.findFirst({
+    where: { schoolId, isCurrent: true },
+    include: {
+      terms: { orderBy: [{ isCurrent: "desc" }, { startDate: "asc" }] },
+    },
+  });
+}