@falkenslab/moodle-driver 0.0.0-stage → 0.3.1

package/dist/areas/lessons/lessons.js

@@ -0,0 +1,145 @@
+import { setFields } from "../../core/forms.js";
+import { inPage } from "../../core/inPage.js";
+import { pause, readingSeconds } from "../../core/pace.js";
+import { openSitePage } from "../../core/session.js";
+import { MoodleError } from "../../core/errors.js";
+/** The lesson isn't there, or the page can't take that answer. */
+export class LessonError extends MoodleError {
+    name = "LessonError";
+    constructor(message) {
+        super(message, "lesson");
+    }
+}
+/** The lesson page on screen, read by its forms and blocks. */
+export function readLessonPage(page) {
+    return inPage(page, () => {
+        const doc = globalThis.document;
+        const main = doc.querySelector('#region-main [role="main"]') ?? doc.querySelector("#region-main");
+        const text = (el) => (el?.innerText ?? "").replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim();
+        const title = text(main?.querySelector("h2")) || undefined;
+        const question = main?.querySelector('form.mform[action*="/mod/lesson/continue.php"]');
+        const pageIdOf = (form) => Number(form?.querySelector('input[name="pageid"]')?.getAttribute("value")) || undefined;
+        if (question) {
+            const fields = [];
+            for (const input of Array.from(question.querySelectorAll("input:not([type=hidden]), select, textarea"))) {
+                if (!input.name || input.type === "submit")
+                    continue;
+                const label = text(input.closest("label")) || undefined;
+                if (input.type === "radio") {
+                    let field = fields.find((f) => f.name === input.name);
+                    if (!field) {
+                        field = { name: input.name, kind: "choice", options: [] };
+                        fields.push(field);
+                    }
+                    field.options.push({ value: input.value, label: label ?? input.value });
+                }
+                else if (input.type === "checkbox")
+                    fields.push({ name: input.name, kind: "checkbox", ...(label ? { label } : {}) });
+                else if (input.tagName === "SELECT") {
+                    fields.push({ name: input.name, kind: "select", ...(label ? { label } : {}), options: Array.from(input.options).map((o) => ({ value: o.value, label: o.text.trim() })) });
+                }
+                else
+                    fields.push({ name: input.name, kind: "text", ...(label ? { label } : {}) });
+            }
+            return { kind: "question", pageId: pageIdOf(question), ...(title ? { title } : {}), text: text(question.querySelector(".contents")), fields };
+        }
+        const buttons = Array.from(main?.querySelectorAll('.branchbuttoncontainer form[action*="/mod/lesson/continue.php"]') ?? []);
+        if (buttons.length > 0) {
+            return {
+                kind: "content",
+                pageId: pageIdOf(buttons[0]),
+                ...(title ? { title } : {}),
+                text: text(main?.querySelector(".contents")),
+                buttons: buttons.map((form) => ({ label: text(form.querySelector("button, [type=submit]")), jumpTo: Number(form.querySelector('input[name="jumpto"]')?.getAttribute("value")) })),
+            };
+        }
+        const next = main?.querySelector('form[action*="/mod/lesson/view.php"]');
+        if (next) {
+            const response = main?.querySelector(".response");
+            const correct = response ? (/\bcorrect\b/.test(response.className) ? true : /\bincorrect\b/.test(response.className) ? false : undefined) : undefined;
+            return {
+                kind: "feedback",
+                pageId: pageIdOf(next),
+                text: text(main).replace(text(next), "").trim(),
+                feedback: { ...(correct !== undefined ? { correct } : {}), ...(response ? { response: text(response).replace(/^[^:\n]*:\s*/, "") } : {}) },
+            };
+        }
+        return { kind: "end", ...(title ? { title } : {}), text: text(main) };
+    }, null);
+}
+/** Opens the lesson where the person is: Moodle asks whether to go on from the last page seen, and they do. */
+async function openLesson(context, siteUrl, activityId) {
+    const page = await openSitePage(context, siteUrl, `mod/lesson/view.php?id=${activityId}`);
+    try {
+        if ((await page.locator("body#page-mod-lesson-view").count()) === 0) {
+            throw new LessonError(`Activity ${activityId} isn't a lesson you can open. Take the id of a lesson (module "lesson") from the course structure.`);
+        }
+        const resume = page.locator('#region-main a[href*="startlastseen=yes"]');
+        if ((await resume.count()) > 0)
+            await page.goto((await resume.first().getAttribute("href")), { waitUntil: "domcontentloaded" });
+        return page;
+    }
+    catch (error) {
+        await page.close().catch(() => undefined);
+        throw error;
+    }
+}
+/** The lesson page the person is on (starting the lesson the first time). */
+export async function lessonPage(context, siteUrl, activityId) {
+    const page = await openLesson(context, siteUrl, activityId);
+    try {
+        return await readLessonPage(page);
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+/**
+ * Answers the page the person is on: a content page's button (its label or position), or a
+ * question's fields by name. Returns Moodle's feedback when it gives one, and the page that follows,
+ * going on past the feedback as its "Continue" does; reaching the end ends the attempt. With the
+ * realistic trail it first takes the time a reader needs for the page (ADR-005).
+ */
+export async function answerLessonPage(context, siteUrl, activityId, answer, { trail = "realistic", onProgress } = {}) {
+    const page = await openLesson(context, siteUrl, activityId);
+    try {
+        const current = await readLessonPage(page);
+        // What the answer can't be is told before the reading pause, not after it.
+        const buttons = current.buttons ?? [];
+        const index = typeof answer.button === "number" ? answer.button : buttons.findIndex((b) => b.label === answer.button);
+        if (current.kind === "content" && (answer.button === undefined || index < 0 || index >= buttons.length)) {
+            throw new LessonError(`This content page's buttons are: ${buttons.map((b, i) => `${i}: "${b.label}"`).join(", ")}. Give one by label or position.`);
+        }
+        if (current.kind === "question" && (!answer.responses || Object.keys(answer.responses).length === 0)) {
+            throw new LessonError("This page is a question: answer it with its fields' values (responses).");
+        }
+        if (current.kind === "end" || current.kind === "feedback") {
+            throw new LessonError(current.kind === "end" ? "The lesson has ended: there's nothing more to answer." : "This page only goes on: answer the page it leads to.");
+        }
+        if (trail === "realistic") {
+            const seconds = readingSeconds([current.text, ...(current.fields ?? []).flatMap((f) => [f.label ?? "", ...(f.options ?? []).map((o) => o.label)])].join(" "));
+            await pause(seconds, (elapsed) => onProgress?.(elapsed, seconds));
+        }
+        if (current.kind === "content") {
+            await Promise.all([page.waitForNavigation({ waitUntil: "domcontentloaded" }), page.locator('.branchbuttoncontainer form[action*="/mod/lesson/continue.php"] [type=submit], .branchbuttoncontainer form button').nth(index).click()]);
+        }
+        else {
+            const form = 'form.mform[action*="/mod/lesson/continue.php"]';
+            await setFields(page, answer.responses, form);
+            await Promise.all([page.waitForNavigation({ waitUntil: "domcontentloaded" }), page.click(`${form} [name="submitbutton"]`)]);
+        }
+        let next = await readLessonPage(page);
+        let feedback;
+        if (next.kind === "feedback") {
+            feedback = next;
+            await Promise.all([page.waitForNavigation({ waitUntil: "domcontentloaded" }), page.click('#region-main form[action*="/mod/lesson/view.php"] [type=submit], #region-main form[action*="/mod/lesson/view.php"] button')]);
+            next = await readLessonPage(page);
+        }
+        const changed = current.kind === "content" ? `Went on from lesson ${activityId}'s page with "${buttons[index].label}".` : `Answered lesson ${activityId}'s question.`;
+        return { changed, ...(feedback ? { feedback } : {}), page: next };
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=lessons.js.map

package/dist/areas/lessons/lessons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lessons.js","sourceRoot":"","sources":["../../../src/areas/lessons/lessons.ts"],"names":[],"mappings":"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"}

package/dist/areas/messages/messages.d.ts

@@ -0,0 +1,68 @@
+import type { BrowserContext } from "playwright-core";
+import { MoodleError } from "../../core/errors.js";
+/** Moodle didn't deliver a message. */
+export declare class MessageError extends MoodleError {
+    name: string;
+    constructor(message: string);
+}
+export interface Notification {
+    id: number;
+    subject: string;
+    /** The notification's text, plain. */
+    text: string;
+    /** Who it's from: a user id, or a negative one for the site itself (noreply, support). */
+    fromUserId: number;
+    time?: string;
+    read: boolean;
+    /** Where it leads (the post, the assignment…). */
+    url?: string;
+    /** What sent it: "mod_forum", "mod_assign"… and its kind. */
+    component?: string;
+    eventType?: string;
+}
+/** The person's notifications, newest first, only the unread ones when asked. */
+export declare function notifications(context: BrowserContext, siteUrl: string, { unreadOnly }?: {
+    unreadOnly?: boolean;
+}): Promise<Notification[]>;
+/** Marks all the person's notifications read, as the popover's "Mark all as read" does; doing it twice changes nothing. */
+export declare function markNotificationsRead(context: BrowserContext, siteUrl: string): Promise<{
+    changed: string;
+}>;
+export interface ConversationSummary {
+    id: number;
+    type: "private" | "group" | "self";
+    /** A group conversation's name (its course group). */
+    name?: string;
+    members: {
+        userId: number;
+        fullName: string;
+    }[];
+    unread: number;
+    lastMessage?: {
+        fromUserId: number;
+        text: string;
+        time?: string;
+    };
+}
+/** The person's conversations, latest first, with their last message as text. */
+export declare function conversations(context: BrowserContext, siteUrl: string): Promise<ConversationSummary[]>;
+/** A conversation's members and messages, oldest first, as text. */
+export declare function conversation(context: BrowserContext, siteUrl: string, conversationId: number): Promise<{
+    id: number;
+    members: {
+        userId: number;
+        fullName: string;
+    }[];
+    messages: {
+        id: number;
+        fromUserId: number;
+        text: string;
+        time: string | undefined;
+    }[];
+}>;
+/** Sends a private message to a user, as the messaging drawer does; returns the message and its conversation. */
+export declare function sendMessage(context: BrowserContext, siteUrl: string, userId: number, text: string): Promise<{
+    changed: string;
+    messageId: number;
+    conversationId?: number;
+}>;

package/dist/areas/messages/messages.js

@@ -0,0 +1,84 @@
+import { callService, readPageConfig } from "../../core/ajax.js";
+import { isoDate } from "../courses/list.js";
+import { htmlToTexts } from "../forums/discussions.js";
+import { decodeEntities } from "../../core/text.js";
+import { MoodleError } from "../../core/errors.js";
+/** Moodle didn't deliver a message. */
+export class MessageError extends MoodleError {
+    name = "MessageError";
+    constructor(message) {
+        super(message, "message");
+    }
+}
+/** The person's notifications, newest first, only the unread ones when asked. */
+export async function notifications(context, siteUrl, { unreadOnly = false } = {}) {
+    const { notifications: found } = await callService(context, siteUrl, "message_popup_get_popup_notifications", { useridto: 0, limit: 0, offset: 0 });
+    return found
+        .filter((n) => !unreadOnly || !n.read)
+        .map((n) => ({
+        id: n.id,
+        subject: decodeEntities(n.subject),
+        text: decodeEntities(n.fullmessage || n.smallmessage).trim(),
+        fromUserId: n.useridfrom,
+        time: isoDate(n.timecreated),
+        read: n.read,
+        ...(n.contexturl ? { url: n.contexturl } : {}),
+        ...(n.component ? { component: n.component } : {}),
+        ...(n.eventtype ? { eventType: n.eventtype } : {}),
+    }));
+}
+/** Marks all the person's notifications read, as the popover's "Mark all as read" does; doing it twice changes nothing. */
+export async function markNotificationsRead(context, siteUrl) {
+    const { userId } = await readPageConfig(context, siteUrl);
+    await callService(context, siteUrl, "core_message_mark_all_notifications_as_read", { useridto: userId });
+    return { changed: "All notifications marked read." };
+}
+/** A conversation's types, by Moodle's MESSAGE_CONVERSATION_TYPE_* values. */
+const CONVERSATION_TYPES = { 1: "private", 2: "group", 3: "self" };
+/** The person's conversations, latest first, with their last message as text. */
+export async function conversations(context, siteUrl) {
+    const { userId } = await readPageConfig(context, siteUrl);
+    const { conversations: found } = await callService(context, siteUrl, "core_message_get_conversations", { userid: userId, limitfrom: 0, limitnum: 0 });
+    const texts = await htmlToTexts(context, found.map((c) => c.messages[0]?.text ?? ""));
+    return found.map((c, i) => {
+        const last = c.messages[0];
+        return {
+            id: c.id,
+            type: CONVERSATION_TYPES[c.type] ?? "private",
+            ...(c.name ? { name: decodeEntities(c.name) } : {}),
+            members: c.members.map((m) => ({ userId: m.id, fullName: m.fullname })),
+            unread: c.unreadcount ?? 0,
+            ...(last ? { lastMessage: { fromUserId: last.useridfrom, text: texts[i] ?? "", time: isoDate(last.timecreated) } } : {}),
+        };
+    });
+}
+/** A conversation's members and messages, oldest first, as text. */
+export async function conversation(context, siteUrl, conversationId) {
+    const { userId } = await readPageConfig(context, siteUrl);
+    const found = await callService(context, siteUrl, "core_message_get_conversation_messages", {
+        currentuserid: userId,
+        convid: conversationId,
+        limitfrom: 0,
+        limitnum: 0,
+        newest: false,
+    });
+    const texts = await htmlToTexts(context, found.messages.map((m) => m.text));
+    return {
+        id: found.id,
+        members: found.members.map((m) => ({ userId: m.id, fullName: m.fullname })),
+        messages: found.messages.map((m, i) => ({ id: m.id, fromUserId: m.useridfrom, text: texts[i] ?? "", time: isoDate(m.timecreated) })),
+    };
+}
+/** Sends a private message to a user, as the messaging drawer does; returns the message and its conversation. */
+export async function sendMessage(context, siteUrl, userId, text) {
+    if (text.replace(/<[^>]*>/g, "").replace(/&nbsp;/g, " ").trim() === "")
+        throw new MessageError("The message is empty: write something before sending it.");
+    const [sent] = await callService(context, siteUrl, "core_message_send_instant_messages", {
+        messages: [{ touserid: userId, text, textformat: 1 }],
+    });
+    // A refused message comes back with id -1 and Moodle's reason (blocked, not a contact…).
+    if (!sent || sent.msgid < 0)
+        throw new MessageError(`Moodle didn't send the message to user ${userId}: ${sent?.errormessage ?? "no reason given"}`);
+    return { changed: `Message ${sent.msgid} sent to user ${userId}.`, messageId: sent.msgid, ...(sent.conversationid ? { conversationId: sent.conversationid } : {}) };
+}
+//# sourceMappingURL=messages.js.map

package/dist/areas/messages/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../src/areas/messages/messages.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,uCAAuC;AACvC,MAAM,OAAO,YAAa,SAAQ,WAAW;IAClC,IAAI,GAAG,cAAc,CAAC;IAC/B,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC5B,CAAC;CACF;AAgCD,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAuB,EAAE,OAAe,EAAE,EAAE,UAAU,GAAG,KAAK,KAA+B,EAAE;IACjI,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,MAAM,WAAW,CAA0C,OAAO,EAAE,OAAO,EAAE,uCAAuC,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IAC7L,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;SACrC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC;QAClC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC,IAAI,EAAE;QAC5D,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;QAC5B,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnD,CAAC,CAAC,CAAC;AACR,CAAC;AAED,2HAA2H;AAC3H,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,OAAuB,EAAE,OAAe;IAClF,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1D,MAAM,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,6CAA6C,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACzG,OAAO,EAAE,OAAO,EAAE,gCAAgC,EAAE,CAAC;AACvD,CAAC;AAED,8EAA8E;AAC9E,MAAM,kBAAkB,GAAiD,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;AAwBjH,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAuB,EAAE,OAAe;IAC1E,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1D,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,MAAM,WAAW,CAE/C,OAAO,EAAE,OAAO,EAAE,gCAAgC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;IACtG,MAAM,KAAK,GAAG,MAAM,WAAW,CAC7B,OAAO,EACP,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAC5C,CAAC;IACF,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACxB,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC3B,OAAO;YACL,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,SAAS;YAC7C,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnD,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;YACvE,MAAM,EAAE,CAAC,CAAC,WAAW,IAAI,CAAC;YAC1B,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzH,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,oEAAoE;AACpE,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAuB,EAAE,OAAe,EAAE,cAAsB;IACjG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1D,MAAM,KAAK,GAAG,MAAM,WAAW,CAAiF,OAAO,EAAE,OAAO,EAAE,wCAAwC,EAAE;QAC1K,aAAa,EAAE,MAAM;QACrB,MAAM,EAAE,cAAc;QACtB,SAAS,EAAE,CAAC;QACZ,QAAQ,EAAE,CAAC;QACX,MAAM,EAAE,KAAK;KACd,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,MAAM,WAAW,CAC7B,OAAO,EACP,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAClC,CAAC;IACF,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC3E,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;KACrI,CAAC;AACJ,CAAC;AAED,iHAAiH;AACjH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAuB,EAAE,OAAe,EAAE,MAAc,EAAE,IAAY;IACtG,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,MAAM,IAAI,YAAY,CAAC,0DAA0D,CAAC,CAAC;IAC3J,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,WAAW,CAAsE,OAAO,EAAE,OAAO,EAAE,oCAAoC,EAAE;QAC5J,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;KACtD,CAAC,CAAC;IACH,yFAAyF;IACzF,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,0CAA0C,MAAM,KAAK,IAAI,EAAE,YAAY,IAAI,iBAAiB,EAAE,CAAC,CAAC;IACpJ,OAAO,EAAE,OAAO,EAAE,WAAW,IAAI,CAAC,KAAK,iBAAiB,MAAM,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACtK,CAAC"}

package/dist/areas/participants/participants.d.ts

@@ -0,0 +1,57 @@
+import type { BrowserContext, Page } from "playwright-core";
+import { MoodleError } from "../../core/errors.js";
+export interface Participant {
+    userId: number;
+    fullName: string;
+    roles: {
+        id: number;
+        name: string;
+    }[];
+    groups: {
+        id: number;
+        name: string;
+    }[];
+}
+export interface CourseGroup {
+    id: number;
+    name: string;
+    /** The members' user ids. */
+    members: number[];
+}
+/** The person can't see the course's participants. */
+export declare class NoParticipantsError extends MoodleError {
+    name: string;
+    constructor(message: string);
+}
+/** The rows of a participants table fragment: user id and name, read by link and markup, in any language. */
+export declare function readParticipantRows(page: Page): Promise<{
+    userId: number;
+    fullName: string;
+}[]>;
+/**
+ * The roles and groups the participants page filters by in a course (its filters' options), as the
+ * person may use them: every group, or only their own in a course with separate groups. "No roles"
+ * and "no group" left out.
+ */
+export declare function participantFilters(context: BrowserContext, siteUrl: string, courseId: number): Promise<{
+    roles: {
+        id: number;
+        name: string;
+    }[];
+    groups: {
+        id: number;
+        name: string;
+    }[];
+}>;
+/** A course's groups the person can see, with their members' user ids. */
+export declare function groups(context: BrowserContext, siteUrl: string, courseId: number): Promise<CourseGroup[]>;
+/**
+ * A course's participants with their roles and groups, as the participants page lists them: only
+ * those with a role (its id), in a group, or (`inactiveSince`) who haven't accessed the course since
+ * that date, when asked. Each role and group is a filter of its own, so ids come in any language.
+ */
+export declare function participants(context: BrowserContext, siteUrl: string, courseId: number, { role, group, inactiveSince }?: {
+    role?: number;
+    group?: number;
+    inactiveSince?: Date;
+}): Promise<Participant[]>;

package/dist/areas/participants/participants.js

@@ -0,0 +1,135 @@
+import { callService } from "../../core/ajax.js";
+import { openSitePage } from "../../core/session.js";
+import { MoodleError } from "../../core/errors.js";
+/** The person can't see the course's participants. */
+export class NoParticipantsError extends MoodleError {
+    name = "NoParticipantsError";
+    constructor(message) {
+        super(message, "no-participants");
+    }
+}
+// The table's join types (core\output\datafilter): a filter's values match any; filters all apply.
+const JOIN_ANY = 1;
+const JOIN_ALL = 2;
+const PAGE_SIZE = 100;
+const MAX_PAGES = 100;
+/** The rows of a participants table fragment: user id and name, read by link and markup, in any language. */
+export function readParticipantRows(page) {
+    return page.evaluate(() => {
+        const doc = globalThis.document;
+        // Moodle pads a page with empty rows up to its size.
+        return Array.from(doc.querySelectorAll("tbody tr:not(.emptyrow)")).flatMap((row) => {
+            const link = row.querySelector('a[href*="/user/view.php?id="]');
+            const userId = Number(new URL(link?.getAttribute("href") ?? "", "http://x/").searchParams.get("id"));
+            if (!link || !userId)
+                return [];
+            // The link holds the picture or initials before the name.
+            const copy = link.cloneNode(true);
+            for (const extra of Array.from(copy.querySelectorAll(".userinitials, img, .visually-hidden")))
+                extra.remove();
+            return [{ userId, fullName: (copy.textContent ?? "").replace(/\s+/g, " ").trim() }];
+        });
+    });
+}
+/** Every participant matching `filters`, page by page, parsed in `parser` (a blank tab). */
+async function fetchAll(context, siteUrl, parser, courseId, filters) {
+    const all = new Map();
+    for (let pagenumber = 1; pagenumber <= MAX_PAGES; pagenumber++) {
+        const { html } = await callService(context, siteUrl, "core_table_get_dynamic_table_content", {
+            component: "core_user",
+            handler: "participants",
+            uniqueid: `user-index-participants-${courseId}`,
+            sortdata: [{ sortby: "lastname", sortorder: 4 }],
+            // Integer filters take numbers: a string id fails (confirmed empirically, Moodle 5.2).
+            filters: [{ name: "courseid", jointype: JOIN_ANY, values: [courseId] }, ...filters],
+            jointype: JOIN_ALL,
+            firstinitial: "",
+            lastinitial: "",
+            pagenumber,
+            pagesize: PAGE_SIZE,
+            hiddencolumns: [],
+            resetpreferences: false,
+        });
+        await parser.setContent(html);
+        const rows = await readParticipantRows(parser);
+        for (const row of rows)
+            all.set(row.userId, row);
+        if (rows.length < PAGE_SIZE)
+            break;
+    }
+    return Array.from(all.values());
+}
+/**
+ * The roles and groups the participants page filters by in a course (its filters' options), as the
+ * person may use them: every group, or only their own in a course with separate groups. "No roles"
+ * and "no group" left out.
+ */
+export async function participantFilters(context, siteUrl, courseId) {
+    const page = await openSitePage(context, siteUrl, `user/index.php?id=${courseId}`);
+    try {
+        if ((await page.locator("body#page-course-view-participants").count()) === 0) {
+            throw new NoParticipantsError(`You can't see the participants of course ${courseId}: it doesn't exist, or you aren't allowed.`);
+        }
+        return await page.evaluate(() => {
+            const doc = globalThis.document;
+            // Anonymous callbacks only: see the conventions on page.evaluate.
+            const [roles, groups] = ["roles", "groups"].map((field) => Array.from(doc.querySelectorAll(`select[data-field-name="${field}"] option`))
+                .map((option) => ({ id: Number(option.value), name: (option.textContent ?? "").trim() }))
+                .filter((option) => option.id > 0));
+            return { roles: roles ?? [], groups: groups ?? [] };
+        });
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+/** A course's groups the person can see, with their members' user ids. */
+export async function groups(context, siteUrl, courseId) {
+    const { groups: found } = await participantFilters(context, siteUrl, courseId);
+    const parser = await context.newPage();
+    try {
+        const result = [];
+        for (const group of found) {
+            const members = await fetchAll(context, siteUrl, parser, courseId, [{ name: "groups", jointype: JOIN_ANY, values: [group.id] }]);
+            result.push({ ...group, members: members.map((m) => m.userId) });
+        }
+        return result;
+    }
+    finally {
+        await parser.close().catch(() => undefined);
+    }
+}
+/**
+ * A course's participants with their roles and groups, as the participants page lists them: only
+ * those with a role (its id), in a group, or (`inactiveSince`) who haven't accessed the course since
+ * that date, when asked. Each role and group is a filter of its own, so ids come in any language.
+ */
+export async function participants(context, siteUrl, courseId, { role, group, inactiveSince } = {}) {
+    const { roles, groups: courseGroupList } = await participantFilters(context, siteUrl, courseId);
+    const filters = [];
+    if (role !== undefined)
+        filters.push({ name: "roles", jointype: JOIN_ANY, values: [role] });
+    if (group !== undefined)
+        filters.push({ name: "groups", jointype: JOIN_ANY, values: [group] });
+    // "Inactive for more than": no access to the course since this time (the filter's "any" join).
+    if (inactiveSince !== undefined)
+        filters.push({ name: "accesssince", jointype: JOIN_ANY, values: [Math.floor(inactiveSince.getTime() / 1000)] });
+    const parser = await context.newPage();
+    try {
+        const people = await fetchAll(context, siteUrl, parser, courseId, filters);
+        const byUser = new Map(people.map((p) => [p.userId, { ...p, roles: [], groups: [] }]));
+        for (const r of roles) {
+            for (const member of await fetchAll(context, siteUrl, parser, courseId, [{ name: "roles", jointype: JOIN_ANY, values: [r.id] }]))
+                byUser.get(member.userId)?.roles.push(r);
+        }
+        for (const g of courseGroupList) {
+            for (const member of await fetchAll(context, siteUrl, parser, courseId, [{ name: "groups", jointype: JOIN_ANY, values: [g.id] }]))
+                byUser.get(member.userId)?.groups.push(g);
+        }
+        return Array.from(byUser.values());
+    }
+    finally {
+        await parser.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=participants.js.map

package/dist/areas/participants/participants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"participants.js","sourceRoot":"","sources":["../../../src/areas/participants/participants.ts"],"names":[],"mappings":"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"}

package/dist/areas/questions/banks.d.ts

@@ -0,0 +1,83 @@
+import type { BrowserContext, Page } from "playwright-core";
+import { type FieldValue } from "../../core/forms.js";
+import { MoodleError } from "../../core/errors.js";
+/** The bank isn't there, or Moodle refused the questions. */
+export declare class QuestionBankError extends MoodleError {
+    name: string;
+    constructor(message: string);
+}
+export interface QuestionBank {
+    /** The bank's course module id: a qbank activity's, or the quiz's whose private bank it is. */
+    id: number;
+    name: string;
+    /** The module: "qbank" for a shared bank, "quiz"… for an activity's own. */
+    type: string;
+    /** Shared banks' questions can be used anywhere in the course; activities' only there. */
+    shared: boolean;
+}
+/** A course's question banks: its shared ones and the activities' own, as the banks page lists them. */
+export declare function questionBanks(context: BrowserContext, siteUrl: string, courseId: number): Promise<QuestionBank[]>;
+export interface BankQuestion {
+    id: number;
+    name: string;
+    /** The question type: "multichoice", "truefalse", "shortanswer", "essay"… */
+    type: string;
+    /** "ready" or "draft". */
+    status?: string;
+    version?: string;
+    categoryId: number;
+}
+export interface BankCategory {
+    id: number;
+    name: string;
+}
+/** The questions on a bank page: id from their checkbox, type from their icon, name from the in-place editor. */
+export declare function readBankQuestions(page: Page, categoryId: number): Promise<BankQuestion[]>;
+/** A bank's categories and every question in them, category by category. */
+export declare function questions(context: BrowserContext, siteUrl: string, activityId: number): Promise<{
+    categories: BankCategory[];
+    questions: BankQuestion[];
+}>;
+/**
+ * Imports questions into a bank from a GIFT or Moodle XML file (a local path) or text, through the
+ * bank's import form; returns the questions created. A file Moodle can't parse comes back as a
+ * `QuestionBankError` with its messages, and nothing is imported.
+ */
+export declare function importQuestions(context: BrowserContext, siteUrl: string, activityId: number, { format, file, text, categoryId }: {
+    format: "gift" | "xml";
+    file?: string;
+    text?: string;
+    categoryId?: number;
+}): Promise<{
+    changed: string;
+    questions: BankQuestion[];
+}>;
+export declare const QUESTION_TYPES: readonly ["multichoice", "truefalse", "shortanswer", "numerical", "essay"];
+export type QuestionType = (typeof QUESTION_TYPES)[number];
+export interface QuestionInput {
+    type: QuestionType;
+    name: string;
+    /** The question's text (HTML). */
+    text: string;
+    /** Multichoice, short answer and numerical answers: a fraction of the mark (1 right, 0 wrong, negatives for penalties), the nearest one Moodle offers. */
+    answers?: {
+        text: string;
+        fraction: number;
+        feedback?: string;
+        tolerance?: number;
+    }[];
+    /** True/false: the right answer. */
+    correct?: boolean;
+    categoryId?: number;
+    defaultMark?: number;
+    /** Any other field of the type's form, by name. */
+    fields?: Record<string, FieldValue>;
+}
+/**
+ * Creates one question in a bank through its type's edit form; returns its id. Imports are the way
+ * for several; this is for one-offs.
+ */
+export declare function createQuestion(context: BrowserContext, siteUrl: string, activityId: number, input: QuestionInput): Promise<{
+    changed: string;
+    questionId?: number;
+}>;