@citolab/qti-backend-firebase 0.0.3

package/dist/api/qti-teacher.js

@@ -0,0 +1,807 @@
+import { authenticateTeacher, getAppId } from "../helpers/request-headers";
+import { createSession, createSessionByIdentifications, deleteStudent, getApplication, getItemsStats, getPlannedStudents, resetSession, updateItemStatResponseScore, updateStudent, updateStudentSessionState, } from "./../helpers/logic";
+import { getDatabase } from "../helpers/db";
+import { getFirestore } from "../helpers/firebase";
+import { body, param, query } from "express-validator";
+import { generalRateLimit, handleValidationErrors, heavyOperationLimit, sendError, sendSuccess, validateAssessmentId, } from "../helpers/endpoint-helpers";
+import { dateId, createCode } from "../helpers";
+import { BaseImplementation } from "./app-specific/baseImplementation";
+// Teacher authentication middleware
+export const requireTeacherAuth = async (req, res, next) => {
+    try {
+        const result = await authenticateTeacher(req, res);
+        if (!result || result.handled) {
+            return sendError(res, 401, "Teacher authentication required");
+        }
+        req.user = result.user;
+        req.appId = getAppId(req);
+        next();
+    }
+    catch (error) {
+        console.error("Teacher authentication error:", error);
+        return sendError(res, 500, "Authentication failed");
+    }
+};
+const checkCode = async (db, groupCode) => {
+    try {
+        const firestore = getFirestore();
+        const doc = await firestore.doc(db.GROUP_DELIVERY.DOC(groupCode)).get();
+        return doc.exists;
+    }
+    catch (error) {
+        console.error("Error checking code:", error);
+        return false;
+    }
+};
+const createDelivery = async (db) => {
+    try {
+        let groupCode = createCode(4);
+        let exists = await checkCode(db, groupCode);
+        while (exists || groupCode.toLowerCase() === "aaaa") {
+            groupCode = createCode(4);
+            exists = await checkCode(db, groupCode);
+        }
+        return groupCode;
+    }
+    catch (error) {
+        console.error("Error creating activity:", error);
+        return null;
+    }
+};
+// Validation helpers
+const validateCode = (code) => {
+    return (typeof code === "string" &&
+        code.length > 0 &&
+        code.length <= 50 &&
+        /^[a-zA-Z0-9_-]+$/.test(code));
+};
+const validateTarget = (target) => {
+    return target === "teacher" || target === "reviewer";
+};
+const parseScore = (scoreValue) => {
+    if (scoreValue === null || scoreValue === undefined || scoreValue === "") {
+        return null;
+    }
+    if (typeof scoreValue === "number") {
+        return isFinite(scoreValue) ? scoreValue : null;
+    }
+    if (typeof scoreValue === "string") {
+        // Valid integer (positive or negative)
+        if (/^-?\d+$/.test(scoreValue)) {
+            return parseInt(scoreValue, 10);
+        }
+        // Valid float
+        if (/^-?\d*\.\d+$/.test(scoreValue)) {
+            return parseFloat(scoreValue);
+        }
+    }
+    return null;
+};
+export function addQtiTeacherEndpoints(app, specificImplementation = new BaseImplementation()) {
+    /**
+     * @openapi
+     * /teacher/startGroupDelivery:
+     *   post:
+     *     tags:
+     *       - Teacher
+     *     summary: Create a new group delivery/activity
+     *     description: Creates a new activity code for group delivery sessions.
+     *     requestBody:
+     *       required: true
+     *       content:
+     *         application/json:
+     *           schema:
+     *             type: object
+     *             required:
+     *               - assessmentId
+     *             properties:
+     *               assessmentId:
+     *                 type: string
+     *                 description: The ID of the assessment for this group delivery
+     *     responses:
+     *       200:
+     *         description: Returns the created activity code
+     *         content:
+     *           application/json:
+     *             schema:
+     *               type: object
+     *               properties:
+     *                 groupCode:
+     *                   type: string
+     *                   description: The generated activity code
+     *                 assessmentId:
+     *                   type: string
+     *                   description: The assessment ID
+     *       401:
+     *         description: Unauthorized
+     *       500:
+     *         description: Internal server error
+     */
+    app.post("/teacher/startGroupDelivery", [
+        heavyOperationLimit,
+        body("assessmentId").notEmpty().withMessage("Assessment ID is required"),
+        handleValidationErrors,
+        requireTeacherAuth,
+    ], async (req, res) => {
+        try {
+            const { assessmentId } = req.body;
+            const db = getDatabase(req.appId);
+            const code = await createDelivery(db);
+            if (!code) {
+                return sendError(res, 500, "Failed to create activity code");
+            }
+            const firestore = getFirestore();
+            // Create the activity document
+            await firestore.doc(db.GROUP_DELIVERY.DOC(code)).set({
+                groupCode: code,
+                assessmentId,
+                created: new Date().toISOString(),
+                teacherId: req.user.uid,
+                appId: req.appId,
+            });
+            return sendSuccess(res, { groupCode: code, assessmentId }, "Group delivery created successfully");
+        }
+        catch (error) {
+            console.error("Error creating group delivery:", error);
+            return sendError(res, 500, "Failed to create group delivery");
+        }
+    });
+    /**
+     * @openapi
+     * /teacher/assessments:
+     *   get:
+     *     tags:
+     *       - Teacher
+     *     summary: Get all assessments
+     *     responses:
+     *       200:
+     *         description: Returns all assessments
+     *       401:
+     *         description: Unauthorized
+     *       404:
+     *         description: Application not found
+     *       500:
+     *         description: Internal server error
+     */
+    app.get("/teacher/assessments", [generalRateLimit, requireTeacherAuth], async (req, res) => {
+        try {
+            const db = getDatabase(req.appId);
+            const application = await getApplication(db);
+            if (!application) {
+                return sendError(res, 404, "Application not found");
+            }
+            return sendSuccess(res, { assessments: application.assessments });
+        }
+        catch (error) {
+            console.error("Error retrieving assessments:", error);
+            return sendError(res, 500, "Failed to retrieve assessments");
+        }
+    });
+    /**
+     * @openapi
+     * /teacher/students:
+     *   get:
+     *     tags:
+     *       - Teacher
+     *     summary: Get planned sessions
+     *     responses:
+     *       200:
+     *         description: Returns planned sessions
+     *       401:
+     *         description: Unauthorized
+     *       500:
+     *         description: Internal server error
+     */
+    app.get("/teacher/students", [generalRateLimit, requireTeacherAuth], async (req, res) => {
+        try {
+            const db = getDatabase(req.appId);
+            const studentSessionInfos = await getPlannedStudents(db, req.user.uid);
+            return sendSuccess(res, studentSessionInfos);
+        }
+        catch (error) {
+            console.error("Error retrieving planned students:", error);
+            return sendError(res, 500, "Failed to retrieve planned students");
+        }
+    });
+    app.get("/teacher/assessment/:assessmentId/itemStats", [
+        generalRateLimit,
+        param("assessmentId").custom((value) => {
+            if (!validateAssessmentId(value)) {
+                throw new Error("Invalid assessment ID format");
+            }
+            return true;
+        }),
+        query("role").optional().isIn(["teacher", "reviewer"]),
+        handleValidationErrors,
+        requireTeacherAuth, // You might want to make this more generic
+    ], async (req, res) => {
+        try {
+            const { assessmentId } = req.params;
+            const role = req.query.role || "teacher"; // default to teacher
+            const db = getDatabase(req.appId);
+            const studentSessionInfos = await getItemsStats(db, req.user.uid, assessmentId, role);
+            return sendSuccess(res, studentSessionInfos);
+        }
+        catch (error) {
+            console.error("Error retrieving item stats:", error);
+            return sendError(res, 500, "Failed to retrieve item statistics");
+        }
+    });
+    /**
+     * @openapi
+     * /teacher/log:
+     *   post:
+     *     tags:
+     *       - Teacher
+     *     summary: Log teacher activity
+     *     description: Logs teacher activity data for debugging and analytics purposes.
+     *     requestBody:
+     *       required: true
+     *       content:
+     *         application/json:
+     *           schema:
+     *             type: object
+     *             required:
+     *               - type
+     *               - data
+     *             properties:
+     *               type:
+     *                 type: string
+     *                 minLength: 1
+     *                 maxLength: 100
+     *                 description: The type/category of the log entry
+     *               data:
+     *                 description: Any data to be logged
+     *     responses:
+     *       200:
+     *         description: Successfully logged the data.
+     *       400:
+     *         description: Invalid request data
+     *       401:
+     *         description: Unauthorized
+     *       500:
+     *         description: Internal server error
+     */
+    app.post("/teacher/log", [
+        generalRateLimit,
+        body("type")
+            .isString()
+            .trim()
+            .isLength({ min: 1, max: 100 })
+            .withMessage("Type must be a string between 1-100 characters"),
+        body("data").exists().withMessage("Data field is required"),
+        handleValidationErrors,
+        requireTeacherAuth,
+    ], async (req, res) => {
+        try {
+            const { type, data } = req.body;
+            const db = getDatabase(req.appId);
+            // Create log entry with timestamp and teacher ID
+            const logEntry = {
+                type,
+                data,
+                timestamp: new Date().toISOString(),
+                teacherId: req.user.uid,
+                appId: req.appId,
+            };
+            const firestore = getFirestore();
+            await firestore
+                .doc(db.TEACHER.LOG.DOC(req.user.uid, dateId()))
+                .set(logEntry);
+            return sendSuccess(res, undefined, "Log entry created successfully");
+        }
+        catch (error) {
+            console.error("Error creating log entry:", error);
+            return sendError(res, 500, "Failed to create log entry");
+        }
+    });
+    /**
+     * @openapi
+     * /teacher/plan:
+     *   post:
+     *     tags:
+     *       - Teacher
+     *     summary: Plan sessions
+     *     requestBody:
+     *       required: true
+     *       content:
+     *         application/json:
+     *           schema:
+     *             type: object
+     *             properties:
+     *               count:
+     *                 type: number
+     *                 minimum: 1
+     *                 maximum: 100
+     *               assessmentIds:
+     *                 type: array
+     *                 items:
+     *                   type: string
+     *                 maxItems: 20
+     *     responses:
+     *       200:
+     *         description: Returns planned sessions
+     *       400:
+     *         description: Invalid request data
+     *       401:
+     *         description: Unauthorized
+     *       404:
+     *         description: Application not found
+     *       500:
+     *         description: Internal server error
+     */
+    app.post("/teacher/plan", [
+        heavyOperationLimit,
+        body("count")
+            .optional()
+            .isInt({ min: 1, max: 100 })
+            .withMessage("Count must be between 1 and 100"),
+        body("assessmentIds")
+            .optional()
+            .isArray({ max: 20 })
+            .withMessage("Assessment IDs must be an array with max 20 items"),
+        body("assessmentIds.*")
+            .optional()
+            .custom((value) => {
+            if (!validateAssessmentId(value)) {
+                throw new Error("Invalid assessment ID format");
+            }
+            return true;
+        }),
+        handleValidationErrors,
+        requireTeacherAuth,
+    ], async (req, res) => {
+        try {
+            const { count = 1, assessmentIds = [] } = req.body;
+            const db = getDatabase(req.appId);
+            const application = await getApplication(db);
+            if (!application) {
+                return sendError(res, 404, "Application not found");
+            }
+            const assessmentsToPlan = application.assessments.filter((a) => {
+                return (assessmentIds.length === 0 || assessmentIds.includes(a.assessmentId));
+            });
+            if (assessmentIds.length > 0 && assessmentsToPlan.length === 0) {
+                return sendError(res, 400, "No valid assessments found for the provided IDs");
+            }
+            const studentSessionInfos = await createSession(req.user.uid, db, count, assessmentsToPlan);
+            return sendSuccess(res, studentSessionInfos, "Sessions planned successfully");
+        }
+        catch (error) {
+            console.error("Error planning sessions:", error);
+            return sendError(res, 500, "Failed to plan sessions");
+        }
+    });
+    /**
+     * @openapi
+     * /teacher/planByIdentification:
+     *   post:
+     *     tags:
+     *       - Teacher
+     *     summary: Plan sessions by identification e.g. student number
+     *     requestBody:
+     *       required: true
+     *       content:
+     *         application/json:
+     *           schema:
+     *             type: object
+     *             required:
+     *               - identifications
+     *             properties:
+     *               identifications:
+     *                 type: array
+     *                 items:
+     *                   type: string
+     *                 minItems: 1
+     *                 maxItems: 100
+     *               assessmentIds:
+     *                 type: array
+     *                 items:
+     *                   type: string
+     *                 maxItems: 20
+     *     responses:
+     *       200:
+     *         description: Returns planned sessions
+     *       400:
+     *         description: Invalid request data
+     *       401:
+     *         description: Unauthorized
+     *       404:
+     *         description: Application not found
+     *       500:
+     *         description: Internal server error
+     */
+    app.post("/teacher/planByIdentification", [
+        heavyOperationLimit,
+        body("identifications")
+            .isArray({ min: 1, max: 100 })
+            .withMessage("Identifications must be an array with 1-100 items"),
+        body("identifications.*")
+            .isString()
+            .trim()
+            .isLength({ min: 1, max: 100 })
+            .withMessage("Each identification must be 1-100 characters"),
+        body("assessmentIds")
+            .optional()
+            .isArray({ max: 20 })
+            .withMessage("Assessment IDs must be an array with max 20 items"),
+        body("assessmentIds.*")
+            .optional()
+            .custom((value) => {
+            if (!validateAssessmentId(value)) {
+                throw new Error("Invalid assessment ID format");
+            }
+            return true;
+        }),
+        handleValidationErrors,
+        requireTeacherAuth,
+    ], async (req, res) => {
+        try {
+            const { identifications, assessmentIds = [] } = req.body;
+            const db = getDatabase(req.appId);
+            const application = await getApplication(db);
+            if (!application) {
+                return sendError(res, 404, "Application not found");
+            }
+            const assessmentsToPlan = application.assessments.filter((a) => {
+                return (assessmentIds.length === 0 || assessmentIds.includes(a.assessmentId));
+            });
+            if (assessmentIds.length > 0 && assessmentsToPlan.length === 0) {
+                return sendError(res, 400, "No valid assessments found for the provided IDs");
+            }
+            const studentSessionInfos = await createSessionByIdentifications(req.user.uid, db, identifications.map((i) => ({ identifier: i })), "not_started", assessmentsToPlan);
+            return sendSuccess(res, studentSessionInfos, "Sessions planned by identification successfully");
+        }
+        catch (error) {
+            console.error("Error planning sessions by identification:", error);
+            return sendError(res, 500, "Failed to plan sessions by identification");
+        }
+    });
+    /**
+     * @openapi
+     * /teacher/assessment/:assessmentId/itemStats/:itemIdentifier:
+     *   post:
+     *     tags:
+     *       - Teacher
+     *     summary: Set score for an item response
+     *     parameters:
+     *       - in: path
+     *         name: itemIdentifier
+     *         required: true
+     *         schema:
+     *           type: string
+     *     -   in: path
+     *         name: assessmentId
+     *         required: true
+     *         schema:
+     *          type: string
+     *     requestBody:
+     *       required: true
+     *       content:
+     *         application/json:
+     *           schema:
+     *             type: object
+     *             required:
+     *               - responseId
+     *             properties:
+     *               responseId:
+     *                 type: string
+     *               scoreExternal:
+     *                 oneOf:
+     *                   - type: number
+     *                   - type: string
+     *                   - type: 'null'
+     *               target:
+     *                 type: string
+     *                 enum: [teacher, reviewer]
+     *     responses:
+     *       200:
+     *         description: Score updated successfully
+     *       400:
+     *         description: Invalid request data
+     *       401:
+     *         description: Unauthorized
+     *       500:
+     *         description: Internal server error
+     */
+    app.post("/teacher/assessment/:assessmentId/itemStats/:itemIdentifier", [
+        generalRateLimit,
+        param("itemIdentifier")
+            .isString()
+            .trim()
+            .isLength({ min: 1, max: 100 })
+            .matches(/^[a-zA-Z0-9_.-]+$/)
+            .withMessage("Item identifier must be alphanumeric with dots, dashes and underscores only"),
+        param("assessmentId").custom((value) => {
+            if (!validateAssessmentId(value)) {
+                throw new Error("Invalid assessment ID format");
+            }
+            return true;
+        }),
+        body("responseId")
+            .isString()
+            .trim()
+            .isLength({ min: 1, max: 100 })
+            .withMessage("Response ID is required and must be 1-100 characters"),
+        body("target")
+            .optional()
+            .custom((value) => {
+            if (value && !validateTarget(value)) {
+                throw new Error('Target must be either "teacher" or "reviewer"');
+            }
+            return true;
+        }),
+        handleValidationErrors,
+        requireTeacherAuth,
+    ], async (req, res) => {
+        try {
+            const { assessmentId, itemIdentifier } = req.params;
+            const { responseId, scoreExternal: scoreRawValue, target = "teacher", } = req.body;
+            if (!validateTarget(target)) {
+                return sendError(res, 400, 'Invalid target. Must be "teacher" or "reviewer"');
+            }
+            const scoreExternal = parseScore(scoreRawValue);
+            const db = getDatabase(req.appId);
+            await updateItemStatResponseScore(db, req.user.uid, assessmentId, itemIdentifier, responseId, scoreExternal, target);
+            return sendSuccess(res, undefined, "Score updated successfully");
+        }
+        catch (error) {
+            console.error("Error updating item score:", error);
+            return sendError(res, 500, "Failed to update item score");
+        }
+    });
+    /**
+     * @openapi
+     * /teacher/access:
+     *   post:
+     *     tags:
+     *       - Teacher
+     *     summary: Check if the teacher has access
+     *     description: Authenticates the teacher and checks if they have access.
+     *     responses:
+     *       200:
+     *         description: Returns if the teacher has access.
+     *       401:
+     *         description: Unauthorized
+     */
+    app.post("/teacher/access", [generalRateLimit, requireTeacherAuth], async (req, res) => {
+        return sendSuccess(res, { hasAccess: true });
+    });
+    /**
+     * @openapi
+     * /teacher/session/update:
+     *   post:
+     *     tags:
+     *       - Teacher
+     *     summary: Update a student session
+     *     description: Updates the session information for a student.
+     *     requestBody:
+     *       required: true
+     *       content:
+     *         application/json:
+     *           schema:
+     *             type: object
+     *             required:
+     *               - assessmentId
+     *               - code
+     *               - session
+     *             properties:
+     *               assessmentId:
+     *                 type: string
+     *               code:
+     *                 type: string
+     *               session:
+     *                 $ref: '#/components/schemas/SessionInfoTeacher'
+     *     responses:
+     *       200:
+     *         description: Successfully updated the session.
+     *       400:
+     *         description: Invalid request data
+     *       401:
+     *         description: Unauthorized
+     *       500:
+     *         description: Internal server error
+     */
+    app.post("/teacher/session/update", [
+        generalRateLimit,
+        body("assessmentId").custom((value) => {
+            if (!validateAssessmentId(value)) {
+                throw new Error("Invalid assessment ID format");
+            }
+            return true;
+        }),
+        body("code").custom((value) => {
+            if (!validateCode(value)) {
+                throw new Error("Invalid code format");
+            }
+            return true;
+        }),
+        body("session").isObject().withMessage("Session must be an object"),
+        handleValidationErrors,
+        requireTeacherAuth,
+    ], async (req, res) => {
+        try {
+            const { assessmentId, code, session } = req.body;
+            const db = getDatabase(req.appId);
+            const firestore = getFirestore();
+            const batch = firestore.batch();
+            await Promise.all([
+                specificImplementation.updatePlannedSession(req.user.uid, code, session, batch),
+                updateStudentSessionState(db, code, session.assessmentId, session.sessionState, batch),
+            ]);
+            await batch.commit();
+            return sendSuccess(res, undefined, "Session updated successfully");
+        }
+        catch (error) {
+            console.error("Error updating session:", error);
+            return sendError(res, 500, "Failed to update session");
+        }
+    });
+    /**
+     * @openapi
+     * /teacher/session/{code}:
+     *   delete:
+     *     tags:
+     *       - Teacher
+     *     summary: Delete a students session
+     *     description: Deletes a specific session for a student.
+     *     parameters:
+     *       - in: path
+     *         name: code
+     *         required: true
+     *         schema:
+     *           type: string
+     *         description: The session code.
+     *     responses:
+     *       200:
+     *         description: Successfully deleted the session.
+     *       400:
+     *         description: Invalid code format
+     *       401:
+     *         description: Unauthorized
+     *       500:
+     *         description: Internal server error
+     */
+    app.delete("/teacher/session/:code", [
+        generalRateLimit,
+        param("code").custom((value) => {
+            if (!validateCode(value)) {
+                throw new Error("Invalid code format");
+            }
+            return true;
+        }),
+        handleValidationErrors,
+        requireTeacherAuth,
+    ], async (req, res) => {
+        try {
+            const { code } = req.params;
+            const db = getDatabase(req.appId);
+            await deleteStudent(db, req.user.uid, code);
+            return sendSuccess(res, undefined, "Session deleted successfully");
+        }
+        catch (error) {
+            console.error("Error deleting session:", error);
+            return sendError(res, 500, "Failed to delete session");
+        }
+    });
+    /**
+     * @openapi
+     * /teacher/session/reset:
+     *   post:
+     *     tags:
+     *       - Teacher
+     *     summary: Reset a teacher's session
+     *     description: Resets the session information for a student.
+     *     requestBody:
+     *       required: true
+     *       content:
+     *         application/json:
+     *           schema:
+     *             type: object
+     *             required:
+     *               - code
+     *               - assessmentId
+     *             properties:
+     *               code:
+     *                 type: string
+     *               assessmentId:
+     *                 type: string
+     *     responses:
+     *       200:
+     *         description: Successfully reset the session.
+     *       400:
+     *         description: Invalid request data
+     *       401:
+     *         description: Unauthorized
+     *       500:
+     *         description: Internal server error
+     */
+    app.post("/teacher/session/reset", [
+        generalRateLimit,
+        body("code").custom((value) => {
+            if (!validateCode(value)) {
+                throw new Error("Invalid code format");
+            }
+            return true;
+        }),
+        body("assessmentId").custom((value) => {
+            if (!validateAssessmentId(value)) {
+                throw new Error("Invalid assessment ID format");
+            }
+            return true;
+        }),
+        handleValidationErrors,
+        requireTeacherAuth,
+    ], async (req, res) => {
+        try {
+            const { code, assessmentId } = req.body;
+            const db = getDatabase(req.appId);
+            await resetSession(db, req.user.uid, code, assessmentId);
+            return sendSuccess(res, undefined, "Session reset successfully");
+        }
+        catch (error) {
+            console.error("Error resetting session:", error);
+            return sendError(res, 500, "Failed to reset session");
+        }
+    });
+    /**
+     * @openapi
+     * /teacher/student/update:
+     *   post:
+     *     tags:
+     *       - Teacher
+     *     summary: Update student information
+     *     description: Updates student information for a specific session.
+     *     requestBody:
+     *       required: true
+     *       content:
+     *         application/json:
+     *           schema:
+     *             type: object
+     *             required:
+     *               - code
+     *               - studentId
+     *             properties:
+     *               code:
+     *                 type: string
+     *               studentId:
+     *                 type: string
+     *     responses:
+     *       200:
+     *         description: Successfully updated student information.
+     *       400:
+     *         description: Invalid request data
+     *       401:
+     *         description: Unauthorized
+     *       500:
+     *         description: Internal server error
+     */
+    app.post("/teacher/student/update", [
+        generalRateLimit,
+        body("code").custom((value) => {
+            if (!validateCode(value)) {
+                throw new Error("Invalid code format");
+            }
+            return true;
+        }),
+        body("identification")
+            .isString()
+            .trim()
+            .isLength({ min: 1, max: 100 })
+            .withMessage("identification must be 1-100 characters"),
+        handleValidationErrors,
+        requireTeacherAuth,
+    ], async (req, res) => {
+        try {
+            const { code, identification } = req.body;
+            const db = getDatabase(req.appId);
+            await updateStudent(db, req.user.uid, code, identification);
+            return sendSuccess(res, undefined, "Student updated successfully");
+        }
+        catch (error) {
+            console.error("Error updating student:", error);
+            return sendError(res, 500, "Failed to update student");
+        }
+    });
+}
+//# sourceMappingURL=qti-teacher.js.map