@studious-lms/server 1.23.0 → 1.24.0

package/src/lib/feePdf.ts

@@ -0,0 +1,199 @@
+/**
+ * Fee invoice / receipt PDF generation.
+ *
+ * Stamps content onto the school's uploaded letterhead when present:
+ * - PDF letterhead → reuse first page as background
+ * - Image letterhead (png/jpeg) → draw full-page background then text
+ * - No letterhead → plain A4 page with school name header
+ */
+import {
+  PDFDocument,
+  StandardFonts,
+  rgb,
+  degrees,
+} from "pdf-lib";
+import fontkit from "@pdf-lib/fontkit";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { bucket } from "./googleCloudStorage.js";
+import { logger } from "../utils/logger.js";
+import { formatNpr, monthLabel } from "./feePdfFormat.js";
+
+export { formatNpr, monthLabel };
+
+export type FeePdfLine = { label: string; value: string };
+
+export interface FeePdfDocumentInput {
+  schoolName: string;
+  title: string;
+  subtitle?: string;
+  lines: FeePdfLine[];
+  footerNote?: string;
+  letterhead?: {
+    path: string;
+    type: string;
+  } | null;
+}
+
+async function loadUnicodeFonts(pdfDoc: PDFDocument) {
+  pdfDoc.registerFontkit(fontkit);
+  const fontDir = join(process.cwd(), "src", "lib");
+  try {
+    const regular = readFileSync(join(fontDir, "NotoSans-Regular.ttf"));
+    const bold = readFileSync(join(fontDir, "NotoSans-Bold.ttf"));
+    return {
+      regular: await pdfDoc.embedFont(regular),
+      bold: await pdfDoc.embedFont(bold),
+    };
+  } catch (err) {
+    logger.warn(`feePdf: falling back to Helvetica fonts: ${err}`);
+    return {
+      regular: await pdfDoc.embedFont(StandardFonts.Helvetica),
+      bold: await pdfDoc.embedFont(StandardFonts.HelveticaBold),
+    };
+  }
+}
+
+async function loadLetterheadBytes(path: string): Promise<Uint8Array | null> {
+  try {
+    const [bytes] = await bucket.file(path).download();
+    return bytes;
+  } catch (err) {
+    logger.warn(`feePdf: failed to download letterhead ${path}: ${err}`);
+    return null;
+  }
+}
+
+async function preparePage(
+  pdfDoc: PDFDocument,
+  letterhead?: FeePdfDocumentInput["letterhead"]
+) {
+  if (letterhead?.path) {
+    const bytes = await loadLetterheadBytes(letterhead.path);
+    if (bytes) {
+      const type = (letterhead.type || "").toLowerCase();
+      if (type.includes("pdf") || letterhead.path.toLowerCase().endsWith(".pdf")) {
+        const src = await PDFDocument.load(bytes);
+        const [page] = await pdfDoc.copyPages(src, [0]);
+        pdfDoc.addPage(page);
+        return pdfDoc.getPage(0);
+      }
+      if (
+        type.includes("png") ||
+        type.includes("jpeg") ||
+        type.includes("jpg")
+      ) {
+        const page = pdfDoc.addPage();
+        const { width, height } = page.getSize();
+        try {
+          const image = type.includes("png")
+            ? await pdfDoc.embedPng(bytes)
+            : await pdfDoc.embedJpg(bytes);
+          page.drawImage(image, { x: 0, y: 0, width, height });
+          return page;
+        } catch (err) {
+          logger.warn(`feePdf: could not embed letterhead image: ${err}`);
+        }
+      }
+    }
+  }
+
+  return pdfDoc.addPage();
+}
+
+export async function buildFeePdf(
+  input: FeePdfDocumentInput
+): Promise<Uint8Array> {
+  const pdfDoc = await PDFDocument.create();
+  const fonts = await loadUnicodeFonts(pdfDoc);
+  const page = await preparePage(pdfDoc, input.letterhead);
+  const { width, height } = page.getSize();
+
+  const left = 56;
+  const right = width - 56;
+  let y = height - 120;
+
+  // When no letterhead, print school name as a simple header.
+  if (!input.letterhead?.path) {
+    page.drawText(input.schoolName, {
+      x: left,
+      y: height - 56,
+      size: 16,
+      font: fonts.bold,
+      color: rgb(0.1, 0.1, 0.1),
+    });
+    y = height - 96;
+  }
+
+  page.drawText(input.title, {
+    x: left,
+    y,
+    size: 18,
+    font: fonts.bold,
+    color: rgb(0.08, 0.08, 0.08),
+  });
+  y -= 22;
+
+  if (input.subtitle) {
+    page.drawText(input.subtitle, {
+      x: left,
+      y,
+      size: 11,
+      font: fonts.regular,
+      color: rgb(0.3, 0.3, 0.3),
+    });
+    y -= 28;
+  } else {
+    y -= 12;
+  }
+
+  page.drawLine({
+    start: { x: left, y },
+    end: { x: right, y },
+    thickness: 0.75,
+    color: rgb(0.75, 0.75, 0.75),
+  });
+  y -= 28;
+
+  for (const line of input.lines) {
+    page.drawText(line.label, {
+      x: left,
+      y,
+      size: 10,
+      font: fonts.regular,
+      color: rgb(0.35, 0.35, 0.35),
+    });
+    const valueWidth = fonts.bold.widthOfTextAtSize(line.value, 11);
+    page.drawText(line.value, {
+      x: Math.max(left + 160, right - valueWidth),
+      y,
+      size: 11,
+      font: fonts.bold,
+      color: rgb(0.1, 0.1, 0.1),
+    });
+    y -= 22;
+    if (y < 80) break;
+  }
+
+  if (input.footerNote) {
+    page.drawText(input.footerNote, {
+      x: left,
+      y: 48,
+      size: 9,
+      font: fonts.regular,
+      color: rgb(0.45, 0.45, 0.45),
+    });
+  }
+
+  // Light watermark so blank letterheads still look intentional.
+  page.drawText("Studious", {
+    x: width / 2 - 40,
+    y: 28,
+    size: 8,
+    font: fonts.regular,
+    color: rgb(0.7, 0.7, 0.7),
+    rotate: degrees(0),
+  });
+
+  return pdfDoc.save();
+}

package/src/lib/feePdfFormat.ts

@@ -0,0 +1,14 @@
+/** Pure formatting helpers for fee invoices / receipts (no I/O). */
+
+export function formatNpr(amount: number) {
+  return `NPR ${amount.toLocaleString("en-NP")}`;
+}
+
+export function monthLabel(year: number, month: number) {
+  const d = new Date(Date.UTC(year, month - 1, 1));
+  return d.toLocaleString("en-GB", {
+    month: "long",
+    year: "numeric",
+    timeZone: "UTC",
+  });
+}

package/src/lib/idCardPdf.ts

@@ -0,0 +1,336 @@
+/**
+ * Student ID card PDF generation (front-side, CR80) via pdf-lib.
+ */
+import fontkit from "@pdf-lib/fontkit";
+import { readFileSync } from "fs";
+import { join } from "path";
+import {
+  PDFDocument,
+  PDFFont,
+  PDFImage,
+  PDFPage,
+  StandardFonts,
+  rgb,
+  type RGB,
+} from "pdf-lib";
+import sharp from "sharp";
+import { logger } from "../utils/logger.js";
+
+/** CR80 ID card size in PDF points (3.375" × 2.125"). */
+export const ID_CARD_WIDTH = 243;
+export const ID_CARD_HEIGHT = 153;
+
+export const DEFAULT_BRAND_COLOR = "#1E3A5F";
+
+export type IdCardStudent = {
+  displayName: string;
+  username: string;
+  /** Class / grade label, e.g. "Grade 5 · Section A". */
+  classLabel: string | null;
+  /** Hex accent from class/department branding when available. */
+  brandColor: string | null;
+  profilePictureUrl: string | null;
+};
+
+export type IdCardSchool = {
+  name: string;
+  logoPath: string | null;
+};
+
+function hexToRgb(cleaned: string): RGB {
+  const r = parseInt(cleaned.slice(0, 2), 16) / 255;
+  const g = parseInt(cleaned.slice(2, 4), 16) / 255;
+  const b = parseInt(cleaned.slice(4, 6), 16) / 255;
+  return rgb(r, g, b);
+}
+
+export function parseHexColor(hex: string | null | undefined): RGB {
+  const fallback = hexToRgb(DEFAULT_BRAND_COLOR.replace(/^#/, ""));
+  if (!hex) return fallback;
+  const cleaned = hex.trim().replace(/^#/, "");
+  if (!/^[0-9a-fA-F]{6}$/.test(cleaned)) return fallback;
+  return hexToRgb(cleaned);
+}
+
+function contrastTextColor(bg: RGB): RGB {
+  const luminance = 0.2126 * bg.red + 0.7152 * bg.green + 0.0722 * bg.blue;
+  return luminance > 0.55 ? rgb(0.1, 0.1, 0.1) : rgb(1, 1, 1);
+}
+
+async function loadFonts(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 (error) {
+    logger.warn(`idCardPdf: falling back to Helvetica fonts: ${error}`);
+    return {
+      regular: await pdfDoc.embedFont(StandardFonts.Helvetica),
+      bold: await pdfDoc.embedFont(StandardFonts.HelveticaBold),
+    };
+  }
+}
+
+async function fetchBytesFromUrl(url: string): Promise<Buffer | null> {
+  try {
+    const response = await fetch(url);
+    if (!response.ok) return null;
+    return Buffer.from(await response.arrayBuffer());
+  } catch (error) {
+    logger.warn(`idCardPdf: failed to fetch image URL: ${error}`);
+    return null;
+  }
+}
+
+async function loadGcsBytes(path: string): Promise<Buffer | null> {
+  try {
+    // Dynamic import keeps unit tests free of GCS/env bootstrap.
+    const { bucket } = await import("./googleCloudStorage.js");
+    const [bytes] = await bucket.file(path).download();
+    return Buffer.from(bytes);
+  } catch (error) {
+    logger.warn(`idCardPdf: failed to download GCS object ${path}: ${error}`);
+    return null;
+  }
+}
+
+/** Convert arbitrary image bytes (incl. SVG/WebP) to PNG for pdf-lib. */
+export async function toPngBytes(input: Buffer): Promise<Uint8Array | null> {
+  try {
+    const png = await sharp(input).rotate().png().toBuffer();
+    return new Uint8Array(png);
+  } catch (error) {
+    logger.warn(`idCardPdf: sharp conversion failed: ${error}`);
+    return null;
+  }
+}
+
+async function embedImage(
+  pdfDoc: PDFDocument,
+  bytes: Buffer | null
+): Promise<PDFImage | null> {
+  if (!bytes || bytes.length === 0) return null;
+  const png = await toPngBytes(bytes);
+  if (!png) return null;
+  try {
+    return await pdfDoc.embedPng(png);
+  } catch (error) {
+    logger.warn(`idCardPdf: embedPng failed: ${error}`);
+    return null;
+  }
+}
+
+function truncateToWidth(
+  text: string,
+  font: PDFFont,
+  size: number,
+  maxWidth: number
+): string {
+  if (font.widthOfTextAtSize(text, size) <= maxWidth) return text;
+  let truncated = text;
+  const ellipsis = "…";
+  while (
+    truncated.length > 1 &&
+    font.widthOfTextAtSize(truncated + ellipsis, size) > maxWidth
+  ) {
+    truncated = truncated.slice(0, -1);
+  }
+  return truncated + ellipsis;
+}
+
+function drawCard(
+  page: PDFPage,
+  fonts: { regular: PDFFont; bold: PDFFont },
+  school: IdCardSchool,
+  student: IdCardStudent,
+  logo: PDFImage | null,
+  photo: PDFImage | null
+) {
+  const brand = parseHexColor(student.brandColor ?? DEFAULT_BRAND_COLOR);
+  const onBrand = contrastTextColor(brand);
+  const muted = rgb(0.4, 0.45, 0.5);
+  const ink = rgb(0.12, 0.14, 0.18);
+  const border = rgb(0.85, 0.87, 0.9);
+
+  page.drawRectangle({
+    x: 0,
+    y: 0,
+    width: ID_CARD_WIDTH,
+    height: ID_CARD_HEIGHT,
+    color: rgb(1, 1, 1),
+  });
+
+  const headerH = 36;
+  page.drawRectangle({
+    x: 0,
+    y: ID_CARD_HEIGHT - headerH,
+    width: ID_CARD_WIDTH,
+    height: headerH,
+    color: brand,
+  });
+
+  page.drawRectangle({
+    x: 0,
+    y: 0,
+    width: ID_CARD_WIDTH,
+    height: 6,
+    color: brand,
+  });
+
+  page.drawRectangle({
+    x: 0.5,
+    y: 0.5,
+    width: ID_CARD_WIDTH - 1,
+    height: ID_CARD_HEIGHT - 1,
+    borderColor: border,
+    borderWidth: 0.75,
+  });
+
+  const logoSize = 22;
+  let schoolNameX = 12;
+  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: 10,
+      y: ID_CARD_HEIGHT - headerH + (headerH - h) / 2,
+      width: w,
+      height: h,
+    });
+    schoolNameX = 10 + w + 8;
+  }
+
+  const schoolName = truncateToWidth(
+    school.name,
+    fonts.bold,
+    11,
+    ID_CARD_WIDTH - schoolNameX - 10
+  );
+  page.drawText(schoolName, {
+    x: schoolNameX,
+    y: ID_CARD_HEIGHT - headerH + 13,
+    size: 11,
+    font: fonts.bold,
+    color: onBrand,
+  });
+
+  const photoX = 12;
+  const photoY = 22;
+  const photoW = 64;
+  const photoH = 80;
+  page.drawRectangle({
+    x: photoX,
+    y: photoY,
+    width: photoW,
+    height: photoH,
+    color: rgb(0.94, 0.95, 0.97),
+    borderColor: border,
+    borderWidth: 0.5,
+  });
+  if (photo) {
+    const scale = Math.min(photoW / photo.width, photoH / photo.height);
+    const w = photo.width * scale;
+    const h = photo.height * scale;
+    page.drawImage(photo, {
+      x: photoX + (photoW - w) / 2,
+      y: photoY + (photoH - h) / 2,
+      width: w,
+      height: h,
+    });
+  } else {
+    const initials = student.displayName
+      .split(/\s+/)
+      .filter(Boolean)
+      .slice(0, 2)
+      .map((p) => p[0]?.toUpperCase() ?? "")
+      .join("");
+    const initialsSize = 18;
+    const iw = fonts.bold.widthOfTextAtSize(initials || "?", initialsSize);
+    page.drawText(initials || "?", {
+      x: photoX + (photoW - iw) / 2,
+      y: photoY + photoH / 2 - initialsSize / 3,
+      size: initialsSize,
+      font: fonts.bold,
+      color: muted,
+    });
+  }
+
+  const textX = photoX + photoW + 12;
+  const maxTextW = ID_CARD_WIDTH - textX - 10;
+  let y = ID_CARD_HEIGHT - headerH - 22;
+
+  const drawField = (label: string, value: string, valueSize = 10) => {
+    page.drawText(label, {
+      x: textX,
+      y,
+      size: 7,
+      font: fonts.regular,
+      color: muted,
+    });
+    y -= 12;
+    const line = truncateToWidth(value, fonts.bold, valueSize, maxTextW);
+    page.drawText(line, {
+      x: textX,
+      y,
+      size: valueSize,
+      font: fonts.bold,
+      color: ink,
+    });
+    y -= 16;
+  };
+
+  drawField("Name", student.displayName || student.username, 11);
+  drawField("Student ID", student.username, 10);
+  drawField("Class / Grade", student.classLabel || "—", 9);
+
+  page.drawText("STUDENT", {
+    x: textX,
+    y: 14,
+    size: 7,
+    font: fonts.bold,
+    color: brand,
+  });
+}
+
+/**
+ * Build a multi-page PDF: one CR80 front-side ID card per student.
+ */
+export async function buildIdCardsPdf(
+  school: IdCardSchool,
+  students: IdCardStudent[]
+): Promise<Uint8Array> {
+  if (students.length === 0) {
+    throw new Error("No students provided for ID card generation");
+  }
+
+  const pdfDoc = await PDFDocument.create();
+  const fonts = await loadFonts(pdfDoc);
+
+  let logoBytes: Buffer | null = null;
+  if (school.logoPath) {
+    logoBytes = await loadGcsBytes(school.logoPath);
+  }
+  const logo = await embedImage(pdfDoc, logoBytes);
+
+  for (const student of students) {
+    let photoBytes: Buffer | null = null;
+    if (student.profilePictureUrl) {
+      photoBytes = await fetchBytesFromUrl(student.profilePictureUrl);
+    }
+    const photo = await embedImage(pdfDoc, photoBytes);
+
+    const page = pdfDoc.addPage([ID_CARD_WIDTH, ID_CARD_HEIGHT]);
+    drawCard(page, fonts, school, student, logo, photo);
+  }
+
+  return pdfDoc.save();
+}

package/src/lib/pdfLetterhead.ts

@@ -0,0 +1,124 @@
+/**
+ * Reusable PDF letterhead stamp helper (pdf-lib).
+ *
+ * Callers (transcripts, fee receipts, ID cards) load school letterhead bytes
+ * and pass them here to draw a header image on the first page.
+ */
+
+import { PDFDocument, PDFImage, PDFPage } from "pdf-lib";
+
+export interface StampLetterheadOptions {
+  /** Full page width (points). Defaults to A4 width. */
+  pageWidth?: number;
+  /** Top margin inset. Defaults to 24. */
+  topMargin?: number;
+  /** Max letterhead height in points. Defaults to 72. */
+  maxHeight?: number;
+  /** Horizontal inset from page edges. Defaults to 48. */
+  sideMargin?: number;
+}
+
+function looksLikePng(bytes: Uint8Array): boolean {
+  return (
+    bytes.length >= 8 &&
+    bytes[0] === 0x89 &&
+    bytes[1] === 0x50 &&
+    bytes[2] === 0x4e &&
+    bytes[3] === 0x47
+  );
+}
+
+async function embedImage(
+  pdfDoc: PDFDocument,
+  bytes: Uint8Array,
+  contentType?: string | null
+): Promise<PDFImage | null> {
+  if (!bytes.length) 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;
+      }
+    }
+  }
+}
+
+/**
+ * Draw letterhead on `page` and return the Y coordinate below the image
+ * (content should start at or below this value). Returns the original
+ * `contentTopY` when letterhead cannot be embedded.
+ */
+export async function stampLetterheadOnPage(input: {
+  pdfDoc: PDFDocument;
+  page: PDFPage;
+  letterheadBytes?: Uint8Array | null;
+  letterheadContentType?: string | null;
+  /** Current top Y for content (page height - top margin). */
+  contentTopY: number;
+  options?: StampLetterheadOptions;
+}): Promise<number> {
+  const {
+    pdfDoc,
+    page,
+    letterheadBytes,
+    letterheadContentType,
+    contentTopY,
+    options,
+  } = input;
+  if (!letterheadBytes?.length) return contentTopY;
+
+  const pageWidth = options?.pageWidth ?? page.getWidth();
+  const sideMargin = options?.sideMargin ?? 48;
+  const maxHeight = options?.maxHeight ?? 72;
+
+  const image = await embedImage(pdfDoc, letterheadBytes, letterheadContentType);
+  if (!image) return contentTopY;
+
+  const maxWidth = pageWidth - sideMargin * 2;
+  const scale = Math.min(maxWidth / image.width, maxHeight / image.height, 1);
+  const drawWidth = image.width * scale;
+  const drawHeight = image.height * scale;
+  const x = (pageWidth - drawWidth) / 2;
+  const y = contentTopY - drawHeight;
+
+  page.drawImage(image, { x, y, width: drawWidth, height: drawHeight });
+
+  // Leave a small gap under the letterhead.
+  return y - 16;
+}
+
+/**
+ * Convenience: load an existing PDF, stamp letterhead on page 0, return bytes.
+ */
+export async function stampLetterheadOnPdfBytes(input: {
+  pdfBytes: Uint8Array;
+  letterheadBytes?: Uint8Array | null;
+  letterheadContentType?: string | null;
+  options?: StampLetterheadOptions;
+}): Promise<Uint8Array> {
+  const pdfDoc = await PDFDocument.load(input.pdfBytes);
+  const page = pdfDoc.getPages()[0];
+  if (!page) return input.pdfBytes;
+
+  const topMargin = input.options?.topMargin ?? 24;
+  await stampLetterheadOnPage({
+    pdfDoc,
+    page,
+    letterheadBytes: input.letterheadBytes,
+    letterheadContentType: input.letterheadContentType,
+    contentTopY: page.getHeight() - topMargin,
+    options: input.options,
+  });
+
+  return pdfDoc.save();
+}