@studious-lms/server 1.14.0 → 1.15.0

package/src/services/openaiDocumentGen.ts

@@ -0,0 +1,319 @@
+/**
+ * Generate files via OpenAI Code Interpreter (Responses API).
+ * Supports every format the sandbox can produce (pdf, docx, xlsx, pptx, …).
+ */
+import OpenAI from 'openai';
+import type { Response } from 'openai/resources/responses/responses.js';
+import { logger } from '../utils/logger.js';
+
+const DOCUMENT_GEN_MODEL = 'gpt-4o-mini';
+
+/**
+ * Extensions OpenAI Code Interpreter can read/write in its sandbox.
+ * @see https://developers.openai.com/api/docs/guides/tools-code-interpreter
+ */
+export const SUPPORTED_DOCUMENT_FORMATS = [
+  'pdf',
+  'docx',
+  'doc',
+  'xlsx',
+  'pptx',
+  'csv',
+  'md',
+  'html',
+  'txt',
+  'json',
+  'xml',
+  'tex',
+  'png',
+  'jpeg',
+  'jpg',
+  'gif',
+  'zip',
+  'tar',
+  'py',
+  'js',
+  'ts',
+  'css',
+  'sh',
+] as const;
+
+export type DocumentFormat = (typeof SUPPORTED_DOCUMENT_FORMATS)[number];
+
+const FORMAT_MIME: Record<DocumentFormat, string> = {
+  pdf: 'application/pdf',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  doc: 'application/msword',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  csv: 'text/csv',
+  md: 'text/markdown',
+  html: 'text/html',
+  txt: 'text/plain',
+  json: 'application/json',
+  xml: 'application/xml',
+  tex: 'text/x-tex',
+  png: 'image/png',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  gif: 'image/gif',
+  zip: 'application/zip',
+  tar: 'application/x-tar',
+  py: 'text/x-python',
+  js: 'text/javascript',
+  ts: 'application/typescript',
+  css: 'text/css',
+  sh: 'application/x-sh',
+};
+
+const FORMAT_HINTS: Record<DocumentFormat, string> = {
+  pdf: 'fpdf2 or reportlab — structured document with headings and body text',
+  docx: 'python-docx — Word document with headings and paragraphs',
+  doc: 'python-docx saving as .doc if supported, otherwise .docx',
+  xlsx: 'openpyxl or pandas — spreadsheet with labelled columns/rows',
+  pptx: 'python-pptx — slides with title + bullet content per slide',
+  csv: 'pandas or csv module — tabular data with headers',
+  md: 'write the markdown file directly',
+  html: 'write a complete, styled HTML page',
+  txt: 'write plain text with clear section breaks',
+  json: 'json.dumps with readable indentation',
+  xml: 'well-formed XML document',
+  tex: 'LaTeX source that compiles to the requested content',
+  png: 'matplotlib or Pillow — chart, diagram, or visual',
+  jpeg: 'matplotlib or Pillow — save as JPEG',
+  jpg: 'matplotlib or Pillow — save as JPEG',
+  gif: 'matplotlib or Pillow — save as GIF',
+  zip: 'zipfile — bundle multiple related files if needed',
+  tar: 'tarfile — archive if multiple files are required',
+  py: 'valid Python source code file',
+  js: 'valid JavaScript source file',
+  ts: 'valid TypeScript source file',
+  css: 'stylesheet file',
+  sh: 'shell script file',
+};
+
+export interface GenerateDocumentInput {
+  title: string;
+  /** Markdown or plain-text source material for the output file. */
+  content: string;
+  /** Output format. Defaults to pdf. */
+  format?: DocumentFormat | string;
+}
+
+export interface GeneratedDocumentResult {
+  bytes: Buffer;
+  filename: string;
+  mimeType: string;
+  format: DocumentFormat;
+}
+
+export interface ContainerGeneratedFile {
+  containerId: string;
+  fileId: string;
+  filename: string;
+}
+
+export function normalizeDocumentFormat(
+  format?: string | null,
+): DocumentFormat {
+  const raw = (format ?? 'pdf').toLowerCase().replace(/^\./, '');
+  if ((SUPPORTED_DOCUMENT_FORMATS as readonly string[]).includes(raw)) {
+    return raw as DocumentFormat;
+  }
+  return 'pdf';
+}
+
+export function mimeTypeForFormat(format: DocumentFormat): string {
+  return FORMAT_MIME[format];
+}
+
+export function extensionForFormat(format: DocumentFormat): string {
+  return format === 'jpg' ? 'jpg' : format;
+}
+
+/** Pull generated-file citations for a given extension out of a Responses output. */
+export function extractContainerGeneratedFiles(
+  response: Response,
+  extension: DocumentFormat,
+): ContainerGeneratedFile[] {
+  const seen = new Set<string>();
+  const files: ContainerGeneratedFile[] = [];
+  const suffix = `.${extension}`;
+
+  const add = (containerId: string, fileId: string, filename: string) => {
+    const key = `${containerId}:${fileId}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    files.push({ containerId, fileId, filename });
+  };
+
+  for (const item of response.output ?? []) {
+    if (item.type !== 'message') continue;
+    for (const block of item.content ?? []) {
+      if (block.type !== 'output_text') continue;
+      for (const ann of block.annotations ?? []) {
+        if (ann.type !== 'container_file_citation') continue;
+        const name = ann.filename?.toLowerCase() ?? '';
+        if (name.endsWith(suffix)) {
+          add(ann.container_id, ann.file_id, ann.filename);
+        }
+      }
+    }
+  }
+
+  return files;
+}
+
+function containerIdFromResponse(response: Response): string | undefined {
+  for (const item of response.output ?? []) {
+    if (item.type === 'code_interpreter_call' && item.container_id) {
+      return item.container_id;
+    }
+  }
+  return undefined;
+}
+
+async function listContainerGeneratedFiles(
+  client: OpenAI,
+  containerId: string,
+  extension: DocumentFormat,
+): Promise<ContainerGeneratedFile[]> {
+  const suffix = `.${extension}`;
+  const files: ContainerGeneratedFile[] = [];
+  for await (const file of client.containers.files.list(containerId)) {
+    const path = file.path?.toLowerCase() ?? '';
+    if (path.endsWith(suffix) && file.source === 'assistant') {
+      files.push({
+        containerId,
+        fileId: file.id,
+        filename: file.path.split('/').pop() ?? file.path,
+      });
+    }
+  }
+  return files;
+}
+
+async function downloadContainerFile(
+  client: OpenAI,
+  file: ContainerGeneratedFile,
+): Promise<Buffer | null> {
+  try {
+    const res = await client.containers.files.content.retrieve(file.fileId, {
+      container_id: file.containerId,
+    });
+    const bytes = await res.arrayBuffer();
+    return Buffer.from(bytes);
+  } catch (error) {
+    logger.error('Failed to download container file', { error, file });
+    return null;
+  }
+}
+
+function safeBasename(title: string): string {
+  const base = title
+    .replace(/[^a-zA-Z0-9\s\-_]/g, '')
+    .replace(/\s+/g, '_')
+    .substring(0, 60);
+  return base || 'document';
+}
+
+function buildDocumentGenInstructions(format: DocumentFormat): string {
+  return [
+    'You are a document generator for K-12 and university teachers.',
+    'When given a title, output format, and source content:',
+    '1. Use the python tool to create exactly ONE output file of the requested type.',
+    `2. For this format use: ${FORMAT_HINTS[format]}.`,
+    `3. You MUST output a ${format.toUpperCase()} file — not any other format.`,
+    `4. The saved filename MUST end with .${extensionForFormat(format)}.`,
+    '5. Structure content clearly — headings, sections, lists, tables/charts as appropriate.',
+    '6. Include the document title prominently where the format allows.',
+    '7. Put ONLY the educational content in the file — no meta commentary.',
+    '8. You MUST save the file to disk in the working directory before you finish.',
+    ...(format !== 'pdf'
+      ? [`9. Do NOT create a PDF when ${format.toUpperCase()} was requested.`]
+      : []),
+  ].join(' ');
+}
+
+/** Generate a file via OpenAI Code Interpreter. */
+export async function generateDocumentWithOpenAI(
+  input: GenerateDocumentInput,
+): Promise<GeneratedDocumentResult | null> {
+  const client = new OpenAI();
+  const format = normalizeDocumentFormat(input.format);
+  const ext = extensionForFormat(format);
+  const filename = `${safeBasename(input.title)}.${ext}`;
+
+  try {
+    const response = await client.responses.create({
+      model: DOCUMENT_GEN_MODEL,
+      instructions: buildDocumentGenInstructions(format),
+      tools: [
+        {
+          type: 'code_interpreter',
+          container: { type: 'auto' },
+        },
+      ],
+      tool_choice: 'required',
+      input: [
+        `Create a ${ext.toUpperCase()} file using the python tool.`,
+        `Output filename (exact): ${filename}`,
+        `Output format: ${ext}`,
+        `Document title: ${input.title}`,
+        'Source content (markdown or plain text — adapt to the output format):',
+        input.content,
+      ].join('\n\n'),
+    });
+
+    let matches = extractContainerGeneratedFiles(response, format);
+
+    if (matches.length === 0) {
+      const containerId = containerIdFromResponse(response);
+      if (containerId) {
+        matches = await listContainerGeneratedFiles(client, containerId, format);
+      }
+    }
+
+    if (matches.length === 0) {
+      logger.error('OpenAI document gen produced no matching files', {
+        title: input.title,
+        format,
+        outputTypes: (response.output ?? []).map((o) => o.type),
+      });
+      return null;
+    }
+
+    const preferred =
+      matches.find((f) => f.filename.toLowerCase() === filename.toLowerCase()) ??
+      matches[0];
+
+    const bytes = await downloadContainerFile(client, preferred);
+    if (!bytes) return null;
+
+    return {
+      bytes,
+      filename: preferred.filename,
+      mimeType: mimeTypeForFormat(format),
+      format,
+    };
+  } catch (error) {
+    logger.error('OpenAI document generation failed', {
+      error,
+      title: input.title,
+      format,
+    });
+    return null;
+  }
+}
+
+/** @deprecated Use {@link generateDocumentWithOpenAI} */
+export async function generatePdfWithOpenAI(
+  input: Omit<GenerateDocumentInput, 'format'>,
+): Promise<Buffer | null> {
+  const result = await generateDocumentWithOpenAI({ ...input, format: 'pdf' });
+  return result?.bytes ?? null;
+}
+
+/** @deprecated Use {@link extractContainerGeneratedFiles} */
+export const extractContainerPdfFiles = (response: Response) =>
+  extractContainerGeneratedFiles(response, 'pdf');

package/src/services/search.ts

@@ -11,7 +11,9 @@ type SearchScope =
   | "worksheet"
   | "file"
   | "announcement"
-  | "section";
+  | "section"
+  | "discussion"
+  | "submission";
 
 type SearchResult = {
   id: string;
@@ -61,6 +63,8 @@ const trimResults = (results: SearchResult[], limit: number) =>
         file: 5,
         announcement: 6,
         section: 7,
+        discussion: 8,
+        submission: 9,
       };
       const priorityDiff = priority[a.type] - priority[b.type];
       if (priorityDiff !== 0) return priorityDiff;
@@ -405,6 +409,9 @@ const SOURCE_TYPE_TO_SCOPE: Record<EmbeddingSourceType, SearchScope> = {
   ANNOUNCEMENT: "announcement",
   FILE: "file",
   SECTION: "section",
+  DISCUSSION: "discussion",
+  SUBMISSION: "submission",
+  SYLLABUS: "syllabus",
 };
 
 const MIN_SIMILARITY = 0.25;
@@ -517,6 +524,23 @@ export async function searchSemanticGlobal(
       });
       title = section?.name ?? title;
       href = `/class/${hit.classId}/assignments`;
+    } else if (scope === "discussion") {
+      const discussion = await prisma.discussion.findUnique({
+        where: { id: hit.sourceId },
+        select: { title: true },
+      });
+      title = discussion?.title ?? title;
+      href = `/class/${hit.classId}/discussions/${hit.sourceId}`;
+    } else if (scope === "submission") {
+      const submission = await prisma.submission.findUnique({
+        where: { id: hit.sourceId },
+        select: { assignment: { select: { title: true, id: true } } },
+      });
+      title = submission?.assignment.title ? `Submission: ${submission.assignment.title}` : title;
+      href = submission?.assignment.id ? `/class/${hit.classId}/assignment/${submission.assignment.id}` : href;
+    } else if (scope === "syllabus") {
+      title = `${className} Syllabus`;
+      href = `/class/${hit.classId}/syllabus`;
     }
 
     results.push({

package/src/services/userPrivacy.ts

@@ -0,0 +1,196 @@
+/**
+ * User privacy service — data export and account erasure (anonymization).
+ */
+import { TRPCError } from "@trpc/server";
+import { randomBytes } from "node:crypto";
+import { hash } from "bcryptjs";
+import { prisma } from "../lib/prisma.js";
+import { deleteSessionsByUserId } from "../models/auth.js";
+
+async function assertAccountCanBeErased(userId: string) {
+  const user = await prisma.user.findUnique({
+    where: { id: userId },
+    select: {
+      id: true,
+      teacherIn: {
+        select: {
+          id: true,
+          name: true,
+          _count: { select: { students: true } },
+        },
+      },
+      _count: {
+        select: {
+          assignments: true,
+          createdLabChats: true,
+        },
+      },
+    },
+  });
+
+  if (!user) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "User not found" });
+  }
+
+  const classesWithStudents = user.teacherIn.filter(
+    (cls) => cls._count.students > 0,
+  );
+  if (classesWithStudents.length > 0) {
+    throw new TRPCError({
+      code: "PRECONDITION_FAILED",
+      message:
+        "Delete or transfer your classes before deleting your account.",
+    });
+  }
+
+  if (user._count.assignments > 0) {
+    throw new TRPCError({
+      code: "PRECONDITION_FAILED",
+      message:
+        "Remove or reassign your assignments before deleting your account.",
+    });
+  }
+
+  if (user._count.createdLabChats > 0) {
+    throw new TRPCError({
+      code: "PRECONDITION_FAILED",
+      message: "Remove your AI lab chats before deleting your account.",
+    });
+  }
+}
+
+/** Export a portable snapshot of the authenticated user's personal data. */
+export async function exportUserData(userId: string) {
+  const user = await prisma.user.findUnique({
+    where: { id: userId },
+    select: {
+      id: true,
+      username: true,
+      email: true,
+      verified: true,
+      termsAcceptedAt: true,
+      termsVersion: true,
+      profile: true,
+      teacherIn: {
+        select: { id: true, name: true, subject: true, section: true },
+      },
+      studentIn: {
+        select: { id: true, name: true, subject: true, section: true },
+      },
+      schoolMemberships: {
+        select: {
+          role: true,
+          status: true,
+          school: { select: { id: true, name: true } },
+        },
+      },
+      submissions: {
+        select: {
+          id: true,
+          createdAt: true,
+          submittedAt: true,
+          gradeReceived: true,
+          extendedResponse: true,
+          assignment: { select: { id: true, title: true, classId: true } },
+        },
+      },
+      events: {
+        select: {
+          id: true,
+          name: true,
+          startTime: true,
+          endTime: true,
+          location: true,
+          remarks: true,
+        },
+      },
+      sentMessages: {
+        select: {
+          id: true,
+          content: true,
+          createdAt: true,
+          conversationId: true,
+        },
+        take: 500,
+        orderBy: { createdAt: "desc" },
+      },
+      notificationsReceived: {
+        select: {
+          id: true,
+          title: true,
+          content: true,
+          read: true,
+          createdAt: true,
+        },
+        take: 200,
+        orderBy: { createdAt: "desc" },
+      },
+    },
+  });
+
+  if (!user) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "User not found" });
+  }
+
+  return {
+    exportedAt: new Date().toISOString(),
+    user,
+  };
+}
+
+/**
+ * Erase personal account data by anonymizing the user record and removing
+ * sessions and memberships. Educational records tied to classes (e.g.
+ * submissions) remain with an anonymized identity where required.
+ */
+export async function deleteUserAccount(userId: string) {
+  await assertAccountCanBeErased(userId);
+  await deleteSessionsByUserId(userId);
+
+  const anonUsername = `deleted_${userId.slice(0, 8)}`;
+  const anonEmail = `deleted+${userId}@studious.invalid`;
+  const randomPassword = await hash(randomBytes(32).toString("hex"), 10);
+
+  await prisma.$transaction([
+    prisma.conversationMember.deleteMany({ where: { userId } }),
+    prisma.notification.deleteMany({
+      where: { OR: [{ senderId: userId }, { receiverId: userId }] },
+    }),
+    prisma.schoolMembership.deleteMany({ where: { userId } }),
+    prisma.permission.deleteMany({
+      where: { OR: [{ userId }, { grantedById: userId }] },
+    }),
+    prisma.user.update({
+      where: { id: userId },
+      data: {
+        teacherIn: { set: [] },
+        studentIn: { set: [] },
+        departments: { set: [] },
+        tags: { set: [] },
+        specificAssignments: { set: [] },
+        presentAttendance: { set: [] },
+        lateAttendance: { set: [] },
+        absentAttendance: { set: [] },
+        schoolId: null,
+        username: anonUsername,
+        email: anonEmail,
+        password: randomPassword,
+        verified: false,
+        termsAcceptedAt: null,
+        termsVersion: null,
+        profile: {
+          update: {
+            displayName: null,
+            bio: null,
+            location: null,
+            website: null,
+            profilePicture: null,
+            profilePictureThumbnail: null,
+          },
+        },
+      },
+    }),
+  ]);
+
+  return { success: true };
+}

package/src/services/worksheet.ts

@@ -3,7 +3,7 @@
  * Integrates with gradeWorksheet pipeline for auto-grading.
  */
 import { TRPCError } from "@trpc/server";
-import { JobStatus, type WorksheetQuestionType } from "@prisma/client";
+import { JobStatus, Prisma, type WorksheetQuestionType } from "@prisma/client";
 import { prisma } from "../lib/prisma.js";
 import { getFileUrl } from "../lib/fileUpload.js";
 import { cancelGradePipeline, regradeWorksheetPipeline } from "../pipelines/gradeWorksheet.js";
@@ -323,6 +323,73 @@ export async function addQuestionToWorksheet(
   });
 }
 
+/** A question's full editable state as captured before an AI modifier run. */
+export interface WorksheetQuestionSnapshot {
+  id: string;
+  type: WorksheetQuestionType;
+  question: string;
+  answer: string;
+  options: unknown;
+  markScheme: unknown;
+  points: number;
+  order: number | null;
+}
+
+const toJsonInput = (value: unknown) =>
+  value === null || value === undefined
+    ? Prisma.JsonNull
+    : (value as Prisma.InputJsonValue);
+
+/**
+ * Restore a worksheet's questions to a snapshot: deletes questions not in the
+ * snapshot, re-creates deleted ones (with their original ids), and reverts
+ * edited ones. Used by AI modifier undo.
+ */
+export async function restoreWorksheetQuestions(
+  worksheetId: string,
+  userId: string,
+  questions: WorksheetQuestionSnapshot[]
+) {
+  const worksheet = await findWorksheetByIdForTeacher(worksheetId, userId);
+  if (!worksheet) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Only class teachers can modify worksheet questions",
+    });
+  }
+
+  await prisma.$transaction([
+    prisma.worksheetQuestion.deleteMany({
+      where: { worksheetId, id: { notIn: questions.map((q) => q.id) } },
+    }),
+    ...questions.map((q) =>
+      prisma.worksheetQuestion.upsert({
+        where: { id: q.id },
+        create: {
+          id: q.id,
+          worksheetId,
+          type: q.type,
+          question: q.question,
+          answer: q.answer,
+          options: toJsonInput(q.options),
+          markScheme: toJsonInput(q.markScheme),
+          points: q.points,
+          order: q.order,
+        },
+        update: {
+          type: q.type,
+          question: q.question,
+          answer: q.answer,
+          options: toJsonInput(q.options),
+          markScheme: toJsonInput(q.markScheme),
+          points: q.points,
+          order: q.order,
+        },
+      })
+    ),
+  ]);
+}
+
 export async function reorderWorksheetQuestions(
   worksheetId: string,
   userId: string,

package/src/utils/email.ts

@@ -27,7 +27,11 @@ export const transport = nodemailer.createTransport({
 export const sendMail = async ({ from, to, subject, text }: sendMailProps) => {
   // Wrapper function for sending emails
   if (env.EMAIL_DRY_RUN == "true") {
-    logger.info(`Email dry run enabled. Would have sent email to ${to} from ${from} with subject ${subject} and text ${text}`);
+    logger.info("Email dry run enabled. Would have sent email", {
+      to,
+      from,
+      subject,
+    });
     return;
   }