@mo7yw4ng/openape 1.0.3 → 1.0.5

package/esm/src/lib/moodle.js

@@ -1,5 +1,6 @@
 import * as dntShim from "../../_dnt.shims.js";
 import { stripHtmlTags, extractCourseName } from "./utils.js";
+import * as fs from "node:fs";
 // ── Core Moodle AJAX Wrapper ───────────────────────────────────────────
 /**
  * Moodle WS API functions that are known to work via /webservice/rest/server.php
@@ -9,6 +10,12 @@ const WS_API_FUNCTIONS = new Set([
     "mod_forum_get_forums_by_courses",
     "mod_forum_get_forum_discussions",
     "mod_forum_get_forum_discussion_posts",
+    "mod_forum_add_discussion",
+    "mod_forum_add_discussion_post",
+    "mod_forum_delete_post",
+    "core_files_upload",
+    "core_files_get_files",
+    "core_files_get_unused_draft_itemid",
     "gradereport_user_get_grade_items",
     "core_calendar_get_calendar_events",
     "core_course_get_contents",
@@ -19,18 +26,33 @@ const WS_API_FUNCTIONS = new Set([
     "mod_supervideo_progress_save_mobile",
     "mod_supervideo_view_supervideo",
     "mod_quiz_get_quizzes_by_courses",
+    "mod_quiz_start_attempt",
+    "mod_quiz_get_attempt_data",
     "mod_resource_get_resources_by_courses",
+    "mod_assign_get_assignments",
+    "mod_assign_save_submission",
+    "mod_assign_get_submission_status",
     "core_message_get_messages",
     "core_webservice_get_site_info",
 ]);
 /**
  * Convert args to URLSearchParams, handling arrays properly for Moodle WS API.
  * Moodle expects array parameters as: courseids[0]=1&courseids[1]=2
+ * For options array: options[0][name]=attachmentsid&options[0][value]=123
  */
 function buildWsParams(args) {
     const params = new URLSearchParams();
     for (const [key, value] of Object.entries(args)) {
-        if (Array.isArray(value)) {
+        if (key === "options" && Array.isArray(value)) {
+            // Special handling for options array: options[0][name]=xxx&options[0][value]=yyy
+            value.forEach((opt, i) => {
+                if (opt && typeof opt === "object" && "name" in opt && "value" in opt) {
+                    params.append(`${key}[${i}][name]`, String(opt.name));
+                    params.append(`${key}[${i}][value]`, String(opt.value));
+                }
+            });
+        }
+        else if (Array.isArray(value)) {
             // Array parameters: courseids[0]=1&courseids[1]=2
             value.forEach((v, i) => {
                 params.append(`${key}[${i}]`, String(v));
@@ -48,7 +70,7 @@ function buildWsParams(args) {
  */
 export async function moodleApiCall(session, methodname, args) {
     if (!session.wsToken) {
-        throw new Error(`WS Token required for API call: ${methodname}`);
+        throw new Error(`WS ${methodname} required for API call: ${methodname}`);
     }
     const params = buildWsParams(args);
     params.set("wstoken", session.wsToken);
@@ -222,6 +244,7 @@ export async function getForumsApi(session, courseIds) {
         id: f.id,
         cmid: f.cmid,
         name: f.name,
+        intro: f.intro,
         courseid: f.course, // API returns 'course' not 'courseid'
         timemodified: f.timemodified,
     }));
@@ -292,6 +315,88 @@ export async function getDiscussionPostsApi(session, discussionId) {
         return [];
     }
 }
+/**
+ * Delete a forum post. If the post is a discussion's topic post,
+ * the entire discussion is deleted.
+ */
+export async function deleteForumPostApi(session, postId) {
+    try {
+        const data = await moodleApiCall(session, "mod_forum_delete_post", { postid: postId });
+        return { success: data?.status === true };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Add a new discussion to a forum.
+ */
+export async function addForumDiscussionApi(session, forumId, subject, message) {
+    try {
+        const data = await moodleApiCall(session, "mod_forum_add_discussion", {
+            forumid: forumId,
+            subject,
+            message: message.replace(/\n/g, "<br>"),
+        });
+        if (data?.discussionid) {
+            return { success: true, discussionId: data.discussionid };
+        }
+        return {
+            success: false,
+            error: data?.message ?? data?.error ?? "Failed to add discussion",
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Add a reply post to a discussion.
+ */
+export async function addForumPostApi(session, postId, // Parent post ID to reply to
+subject, message, options) {
+    try {
+        // Build options array for Moodle WS API
+        const apiOptions = [];
+        if (options?.inlineAttachmentId !== undefined) {
+            apiOptions.push({ name: "inlineattachmentsid", value: options.inlineAttachmentId });
+        }
+        if (options?.attachmentId !== undefined) {
+            apiOptions.push({ name: "attachmentsid", value: options.attachmentId });
+        }
+        const params = {
+            postid: postId,
+            subject,
+            message: message.replace(/\n/g, "<br>"),
+            messageformat: 1, // 1 = HTML, 0 = Moodle, 2 = Plain text, 3 = Markdown
+        };
+        // Only add options if not empty
+        if (apiOptions.length > 0) {
+            params.options = apiOptions;
+        }
+        console.debug(`[DEBUG] add_discussion_post params:`, JSON.stringify(params, null, 2));
+        const data = await moodleApiCall(session, "mod_forum_add_discussion_post", params);
+        if (data?.postid) {
+            return { success: true, postId: data.postid };
+        }
+        return {
+            success: false,
+            error: data?.message ?? data?.error ?? "Failed to add post",
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 // ── Resource/Material Operations ──────────────────────────────────────────
 /**
  * Get all resource modules in a course.
@@ -586,13 +691,13 @@ export async function completeVideoApi(session, video) {
             mapa: buildDurationMap(duration),
         });
         // Debug: log the full result
-        console.debug(`completeVideoApi result:`, JSON.stringify(result));
+        // console.debug(`completeVideoApi result:`, JSON.stringify(result));
         const success = result?.[0]?.success === true || result?.success === true;
         return { success, error: success ? undefined : `API returned success=false, result=${JSON.stringify(result)}`, result };
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        console.debug(`completeVideoApi error: ${msg}`);
+        // console.debug(`completeVideoApi error: ${msg}`);
         return { success: false, error: msg };
     }
 }
@@ -774,6 +879,37 @@ export async function getSupervideosInCourseApi(session, courseId) {
     }
     return videos;
 }
+// ── Quizzes via WS API ────────────────────────────────────────────────────────
+/**
+ * Get user attempts for given quiz IDs via WS API.
+ * Returns a map of quiz ID -> { finished: boolean, attemptsUsed: number }.
+ * Note: mod_quiz_get_user_attempts only accepts a single quizid, so we query in parallel.
+ */
+async function getUserQuizAttemptInfo(session, quizIds) {
+    if (quizIds.length === 0)
+        return new Map();
+    const info = new Map();
+    // Query each quiz in parallel (API only accepts single quizid)
+    const results = await Promise.allSettled(quizIds.map(quizId => moodleApiCall(session, "mod_quiz_get_user_attempts", { quizid: quizId })));
+    for (let i = 0; i < quizIds.length; i++) {
+        const quizId = quizIds[i];
+        const result = results[i];
+        if (result.status === "fulfilled" && result.value?.attempts) {
+            let used = 0;
+            let hasFinished = false;
+            for (const a of result.value.attempts) {
+                used++;
+                if (a.state === "finished")
+                    hasFinished = true;
+            }
+            info.set(quizId, { finished: hasFinished, attemptsUsed: used });
+        }
+        else {
+            info.set(quizId, { finished: false, attemptsUsed: 0 });
+        }
+    }
+    return info;
+}
 /**
  * Get quizzes in courses via pure WS API.
  */
@@ -781,15 +917,170 @@ export async function getQuizzesByCoursesApi(session, courseIds) {
     if (courseIds.length === 0)
         return [];
     const data = await moodleApiCall(session, "mod_quiz_get_quizzes_by_courses", { courseids: courseIds });
-    return (data?.quizzes ?? []).map((q) => ({
-        cmid: q.coursemodule.toString(),
-        name: q.name,
-        url: q.viewurl,
-        isComplete: false, // API doesn't provide completion status
-        timeOpen: q.timeopen,
-        timeClose: q.timeclose,
-        courseId: q.course,
-    }));
+    const quizzes = (data?.quizzes ?? []);
+    // Fetch user attempts to determine completion status and left attempts
+    const quizIds = quizzes.map(q => q.id);
+    const attemptInfo = await getUserQuizAttemptInfo(session, quizIds);
+    return quizzes.map(q => {
+        const info = attemptInfo.get(q.id);
+        return {
+            quizid: q.id.toString(),
+            name: q.name,
+            url: q.viewurl,
+            intro: q.intro,
+            isComplete: info?.finished ?? false,
+            attemptsUsed: info?.attemptsUsed ?? 0,
+            timeClose: q.timeclose,
+            maxAttempts: q.attempts,
+            courseId: q.course,
+        };
+    });
+}
+/**
+ * Start a new quiz attempt via pure WS API.
+ */
+export async function startQuizAttemptApi(session, quizId, options = {}) {
+    const params = {
+        quizid: parseInt(quizId, 10),
+        forcenew: options.forcenew ? 1 : 0,
+    };
+    if (options.precheck) {
+        params.precheck = 1;
+    }
+    const data = await moodleApiCall(session, "mod_quiz_start_attempt", params);
+    if (!data?.attempt) {
+        throw new Error("No attempt data returned");
+    }
+    const attempt = data.attempt;
+    const attemptId = attempt.id || attempt.attempt;
+    return {
+        attempt: {
+            attempt: attemptId,
+            attemptid: attemptId,
+            quizid: attempt.quizid,
+            userid: attempt.userid,
+            attemptnumber: attempt.attemptnumber,
+            state: attempt.state,
+            timestart: attempt.timestart,
+            timefinish: attempt.timefinish,
+            preview: attempt.preview === 1,
+        },
+        page: data.page,
+        messages: data.messages,
+    };
+}
+/**
+ * Get quiz attempt data including questions via pure WS API.
+ */
+export async function getAllQuizAttemptDataApi(session, attemptId) {
+    const firstPage = await getQuizAttemptDataApi(session, attemptId, 0);
+    // Moodle re-indexes question keys per page (always starts at 0),
+    // so we must re-key by actual slot number to avoid overwrites.
+    const allQuestions = {};
+    for (const q of Object.values(firstPage.questions)) {
+        allQuestions[q.slot] = q;
+    }
+    let nextPage = firstPage.nextpage;
+    while (nextPage !== undefined && nextPage !== null && nextPage !== -1) {
+        const pageData = await getQuizAttemptDataApi(session, attemptId, nextPage);
+        for (const q of Object.values(pageData.questions)) {
+            allQuestions[q.slot] = q;
+        }
+        nextPage = pageData.nextpage;
+    }
+    return { ...firstPage, questions: allQuestions, nextpage: undefined };
+}
+export async function getQuizAttemptDataApi(session, attemptId, page = 0) {
+    const data = await moodleApiCall(session, "mod_quiz_get_attempt_data", { attemptid: attemptId, page });
+    if (!data?.attempt || !data?.questions) {
+        throw new Error("Invalid attempt data response");
+    }
+    const attempt = data.attempt;
+    const attemptIdValue = attempt.id || attempt.attempt;
+    const questions = {};
+    for (const [slot, question] of Object.entries(data.questions)) {
+        questions[parseInt(slot, 10)] = {
+            slot: question.slot,
+            type: question.type,
+            id: question.id,
+            maxmark: question.maxmark,
+            page: question.page,
+            quizid: question.quizid,
+            html: question.html,
+            status: question.status,
+            stateclass: question.stateclass,
+            sequencecheck: question.sequencecheck,
+            questionnumber: question.questionnumber,
+        };
+    }
+    return {
+        attempt: {
+            attempt: attemptIdValue,
+            attemptid: attemptIdValue,
+            uniqueid: attempt.uniqueid,
+            quizid: attempt.quizid,
+            userid: attempt.userid,
+            attemptnumber: attempt.attemptnumber,
+            state: attempt.state,
+            timestart: attempt.timestart,
+            timefinish: attempt.timefinish,
+        },
+        questions,
+        nextpage: data.nextpage,
+        prevpage: data.prevpage,
+    };
+}
+/**
+ * Process (save answers / finish) a quiz attempt via WS API.
+ *
+ * Answer formats:
+ * - Single choice (multichoice): { slot, answer: "0" }
+ * - Multiple choice (multichoices): { slot, answer: "0,2,3" } (comma-separated choice indices)
+ * - Short answer (shortanswer): { slot, answer: "text answer" }
+ *
+ * @param session - WS session
+ * @param attemptId - The attempt ID
+ * @param uniqueId - The usage attempt uniqueid (from attempt data)
+ * @param answers - Array of { slot, answer } pairs
+ * @param sequenceChecks - Map of slot -> sequencecheck value (required for deferredfeedback)
+ * @param finish - Whether to finish the attempt after saving
+ */
+export async function processQuizAttemptApi(session, attemptId, uniqueId, answers, sequenceChecks, finish = true) {
+    const params = {
+        attemptid: attemptId,
+        finishattempt: finish ? 1 : 0,
+    };
+    let i = 0;
+    for (const a of answers) {
+        // Include sequencecheck first (required for deferredfeedback quizzes)
+        const seq = sequenceChecks.get(a.slot);
+        if (seq !== undefined) {
+            params[`data[${i}][name]`] = `q${uniqueId}:${a.slot}_:sequencecheck`;
+            params[`data[${i}][value]`] = seq.toString();
+            i++;
+        }
+        // Detect answer format:
+        // Comma-separated numeric values = multichoices (checkboxes)
+        // Single numeric value = multichoice (radio)
+        // Non-numeric text = shortanswer
+        if (/^\d+(,\d+)*$/.test(a.answer) && a.answer.includes(",")) {
+            // Multichoices: send each choice as qXXX:Y_choiceN with value 1
+            const choices = a.answer.split(",");
+            for (const choice of choices) {
+                params[`data[${i}][name]`] = `q${uniqueId}:${a.slot}_choice${choice}`;
+                params[`data[${i}][value]`] = "1";
+                i++;
+            }
+        }
+        else {
+            // Single choice or shortanswer: send as qXXX:Y_answer
+            params[`data[${i}][name]`] = `q${uniqueId}:${a.slot}_answer`;
+            params[`data[${i}][value]`] = a.answer;
+            i++;
+        }
+    }
+    const data = await moodleApiCall(session, "mod_quiz_process_attempt", params);
+    return { state: data?.state ?? "unknown", warnings: data?.warnings };
 }
 // ── Materials via WS API ──────────────────────────────────────────────────────
 /**
@@ -814,6 +1105,200 @@ export async function getResourcesByCoursesApi(session, courseIds) {
         };
     });
 }
+/**
+ * Get assignments in courses via pure WS API.
+ */
+export async function getAssignmentsByCoursesApi(session, courseIds) {
+    if (courseIds.length === 0)
+        return [];
+    const data = await moodleApiCall(session, "mod_assign_get_assignments", { courseids: courseIds });
+    const assignments = [];
+    // The API returns an array of courses, each containing assignments
+    for (const course of (data?.courses ?? [])) {
+        if (!course.assignments)
+            continue;
+        for (const a of course.assignments) {
+            assignments.push({
+                id: a.id,
+                cmid: a.cmid?.toString() ?? "",
+                name: a.name,
+                url: a.viewurl ?? "",
+                courseId: course.id,
+                duedate: a.duedate,
+                cutoffdate: a.cutoffdate,
+                allowSubmissionsFromDate: a.allowsubmissionsfromdate,
+                gradingduedate: a.gradingduedate,
+                lateSubmission: a.latesubmissions ? true : false,
+                extensionduedate: a.extensionduedate,
+            });
+        }
+    }
+    return assignments;
+}
+/**
+ * Get assignment submission status via pure WS API.
+ */
+export async function getSubmissionStatusApi(session, assignmentId) {
+    const siteInfo = await getSiteInfoApi(session);
+    const data = await moodleApiCall(session, "mod_assign_get_submission_status", {
+        assignid: assignmentId,
+        userid: siteInfo.userid,
+    });
+    const lastAttempt = data?.lastattempt;
+    // Note: API returns "submission" (singular), not "submissions" (plural)
+    const submission = lastAttempt?.submission;
+    // Find file submissions from submission plugins
+    const plugins = submission?.plugins || [];
+    const filePlugin = plugins.find((p) => p.type === "file");
+    const extensions = (filePlugin?.fileareas || [])
+        .flatMap((fa) => fa?.files || [])
+        .map((f) => ({
+        id: f.id,
+        filename: f.filename,
+        filesize: f.filesize,
+    }));
+    // Get feedback from the separate feedback object
+    const feedback = data?.feedback;
+    const commentsPlugin = feedback?.plugins?.find((p) => p.type === "comments");
+    const commentText = commentsPlugin?.editorfields?.find((e) => e.name === "comments")?.text || null;
+    return {
+        submitted: submission?.status === "submitted",
+        graded: lastAttempt?.gradingstatus === "graded",
+        grader: feedback?.gradername || null,
+        grade: feedback?.gradefordisplay || null,
+        feedback: commentText,
+        lastModified: submission?.timemodified || null,
+        extensions,
+    };
+}
+/**
+ * Save/submit an assignment via pure WS API.
+ * Supports online text submissions and file submissions (by draft ID).
+ */
+export async function saveSubmissionApi(session, assignmentId, options) {
+    try {
+        const siteInfo = await getSiteInfoApi(session);
+        // Build plugins array based on submission type
+        const plugins = [];
+        if (options.onlineText) {
+            plugins.push({
+                type: "onlinetext",
+                online_text: {
+                    text: options.onlineText.text,
+                    format: options.onlineText.format ?? 1,
+                    itemid: 0,
+                },
+            });
+        }
+        if (options.fileId !== undefined) {
+            plugins.push({
+                type: "file",
+                files_filemanager: options.fileId,
+            });
+        }
+        await moodleApiCall(session, "mod_assign_save_submission", {
+            assignmentid: assignmentId,
+            userid: siteInfo.userid,
+            plugins,
+        });
+        return { success: true };
+    }
+    catch (e) {
+        return { success: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+// ── File Upload via WS API ──────────────────────────────────────────────────────
+/**
+ * Generate a unique draft item ID.
+ * Uses timestamp (last 8 digits) to ensure uniqueness.
+ */
+export function generateDraftItemId() {
+    // Use current timestamp in seconds, take last 8 digits
+    return Math.floor(Date.now() / 1000) % 100000000;
+}
+/**
+ * Upload a file to Moodle draft area via pure WS API.
+ * This is the first step before submitting files to assignments, forums, etc.
+ *
+ * Note: We generate our own draft item ID instead of asking Moodle for one.
+ */
+export async function uploadFileApi(session, filePath, options) {
+    try {
+        // Generate or use provided draft ID
+        const draftItemId = options?.draftId ?? generateDraftItemId();
+        // Read file content using fs.promises
+        const fileContent = await fs.promises.readFile(filePath);
+        const fileName = options?.filename || filePath.split(/[/\\]/).pop() || "unknown";
+        // Get site info for user context
+        const siteInfo = await getSiteInfoApi(session);
+        const userContextId = getUserContextId(siteInfo.userid);
+        // Prepare multipart form data
+        const formData = new FormData();
+        formData.append("token", session.wsToken);
+        formData.append("file", new Blob([new Uint8Array(fileContent)]), fileName);
+        formData.append("filepath", options?.filepath || "/");
+        formData.append("itemid", String(draftItemId)); // Use our generated draft ID
+        formData.append("contextid", String(userContextId)); // Use calculated user context
+        formData.append("component", "user");
+        formData.append("filearea", "draft");
+        formData.append("qformat", ""); // Not used
+        // Upload via upload.php (uses multipart/form-data)
+        const url = `${session.moodleBaseUrl}/webservice/upload.php`;
+        const response = await fetch(url, {
+            method: "POST",
+            body: formData,
+        });
+        if (!response.ok) {
+            return { success: false, error: `HTTP ${response.status}` };
+        }
+        const result = await response.json();
+        console.debug(`[DEBUG] upload.php response:`, JSON.stringify(result, null, 2));
+        // Check for errors in response
+        if (result?.error) {
+            return { success: false, error: result.message ?? result.error ?? "Upload failed" };
+        }
+        // Success - return the draft ID we used
+        return { success: true, draftId: draftItemId };
+    }
+    catch (e) {
+        return { success: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+/**
+ * Calculate user context ID in Moodle.
+ * User context ID = (userid * CONTEXT_DEPTH) + CONTEXT_USER
+ * Where CONTEXT_DEPTH = 10 and CONTEXT_USER = 30
+ */
+function getUserContextId(userId) {
+    return userId * 10 + 30;
+}
+/**
+ * Get user's private files (not draft) via pure WS API.
+ * Draft files are temporary and cannot be listed, but private files can.
+ */
+export async function getDraftFilesApi(session) {
+    const siteInfo = await getSiteInfoApi(session);
+    const userContextId = getUserContextId(siteInfo.userid);
+    const data = await moodleApiCall(session, "core_files_get_files", {
+        contextid: userContextId,
+        component: "user",
+        filearea: "private",
+        itemid: 0,
+        filepath: "/",
+        modified: null,
+    });
+    console.debug(`[DEBUG] core_files_get_files response:`, JSON.stringify(data, null, 2));
+    // The API returns a parents array with files inside
+    const files = data?.parents?.[0]?.files || data?.files || [];
+    return files.map((f) => ({
+        itemId: f.itemid || 0,
+        filename: f.filename || "",
+        filesize: f.filesize || 0,
+        filepath: f.filepath || "/",
+        timeModified: f.timemodified || 0,
+        url: f.url || "",
+    }));
+}
 /**
  * Get messages for the current user via pure WS API.
  */