@falkenslab/moodle-driver 0.0.0-stage → 0.4.0

package/dist/areas/forums/discussions.js

@@ -0,0 +1,119 @@
+import { MoodleServiceError, callService } from "../../core/ajax.js";
+import { openSitePage } from "../../core/session.js";
+import { readTexts } from "../../core/text.js";
+import { MoodleError } from "../../core/errors.js";
+/** The id isn't a forum's course module, or the person can't see it. */
+export class NotAForumError extends MoodleError {
+    name = "NotAForumError";
+    constructor(message) {
+        super(message, "not-a-forum");
+    }
+}
+// The page size asked for; the forum pages until a page brings no new discussions.
+const PAGE_SIZE = 100;
+const MAX_PAGES = 50;
+/** The discussions on a forum page, read by structure: data attributes, links, timestamps. */
+export function readDiscussionRows(page) {
+    return page.evaluate(() => {
+        const doc = globalThis.document;
+        return Array.from(doc.querySelectorAll('tr[data-region="discussion-list-item"][data-discussionid]')).map((row) => {
+            const times = Array.from(row.querySelectorAll("time[data-timestamp]"));
+            // A person's cell is their name followed by the time: the name is the text before it.
+            // (An anonymous callback, not a named helper: see the conventions on page.evaluate.)
+            const [startedBy, lastBy] = [times[0], times[1]].map((time) => {
+                const all = (time?.closest("td")?.textContent ?? "").replace(/\s+/g, " ").trim();
+                const when = (time?.textContent ?? "").replace(/\s+/g, " ").trim();
+                return when && all.endsWith(when) ? all.slice(0, all.length - when.length).trim() : all;
+            });
+            const lastLink = times[1]?.closest("a");
+            const parent = lastLink ? new URL(lastLink.getAttribute("href") ?? "", "http://x/").searchParams.get("parent") : null;
+            const repliesCell = Array.from(row.querySelectorAll("td")).find((cell) => /^\d+$/.test((cell.textContent ?? "").trim()) && !cell.querySelector("a"));
+            const locked = row.querySelector('[data-region="locked-label"]');
+            return {
+                id: Number(row.getAttribute("data-discussionid")),
+                subject: (row.querySelector('a[href*="discuss.php?d="]')?.textContent ?? "").replace(/\s+/g, " ").trim(),
+                author: startedBy ?? "",
+                started: times[0] ? Number(times[0].getAttribute("data-timestamp")) : undefined,
+                lastPost: { author: lastBy ?? "", time: times[1] ? Number(times[1].getAttribute("data-timestamp")) : undefined, postId: parent ? Number(parent) : undefined },
+                replies: Number((repliesCell?.textContent ?? "0").trim()),
+                locked: locked !== null && !locked.hasAttribute("hidden"),
+                pinned: /\bpinned\b/.test(row.className),
+                forumInstanceId: Number(row.getAttribute("data-forumid")) || undefined,
+            };
+        });
+    });
+}
+/** Every discussion of a forum (its course module id), through all its pages. */
+export async function listDiscussions(context, siteUrl, activityId) {
+    const all = new Map();
+    for (let p = 0; p < MAX_PAGES; p++) {
+        const page = await openSitePage(context, siteUrl, `mod/forum/view.php?id=${activityId}&s=${PAGE_SIZE}&p=${p}`);
+        try {
+            // The body id names the page in any language.
+            if ((await page.locator("body#page-mod-forum-view").count()) === 0) {
+                throw new NotAForumError(`Activity ${activityId} isn't a forum you can view. Take the id of a forum (module "forum") from the course structure.`);
+            }
+            const rows = await readDiscussionRows(page);
+            const before = all.size;
+            for (const row of rows)
+                all.set(row.id, row);
+            if (rows.length < PAGE_SIZE || all.size === before)
+                break;
+        }
+        finally {
+            await page.close().catch(() => undefined);
+        }
+    }
+    return Array.from(all.values());
+}
+export async function discussionPosts(context, siteUrl, discussionId) {
+    try {
+        return await callService(context, siteUrl, "mod_forum_get_discussion_posts", { discussionid: discussionId, sortby: "created", sortdirection: "ASC", includeinlineattachments: false });
+    }
+    catch (error) {
+        // A missing discussion fails inside Moodle with a PHP error (confirmed empirically, 5.2).
+        if (error instanceof MoodleServiceError && error.errorcode === "generalexceptionmessage") {
+            throw new NotAForumError(`Discussion ${discussionId} doesn't exist or you can't see it. Take its id from the forum's discussions. (${error.message})`);
+        }
+        throw error;
+    }
+}
+/** Plain text of Moodle-cleaned HTML fragments, parsed in a blank tab. */
+export async function htmlToTexts(context, fragments) {
+    if (fragments.length === 0)
+        return [];
+    const page = await context.newPage();
+    try {
+        await page.setContent(fragments.map((html) => `<div class="driver-fragment">${html}</div>`).join(""));
+        return await readTexts(page, "body > .driver-fragment");
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+/** A forum's instance id (what `post.php?forum=` takes), from its page. */
+export async function forumInstanceId(context, siteUrl, activityId) {
+    const page = await openSitePage(context, siteUrl, `mod/forum/view.php?id=${activityId}`);
+    try {
+        if ((await page.locator("body#page-mod-forum-view").count()) === 0) {
+            throw new NotAForumError(`Activity ${activityId} isn't a forum you can view. Take the id of a forum (module "forum") from the course structure.`);
+        }
+        // The page's quick "new discussion" form carries it (also on an empty forum); discussion rows too.
+        const id = await page.evaluate(() => {
+            const doc = globalThis.document;
+            const fromForm = Number(doc.querySelector('form[action*="post.php"] [name="forum"]')?.value);
+            if (fromForm > 0)
+                return fromForm;
+            return Array.from(doc.querySelectorAll("[data-forumid]"))
+                .map((element) => Number(element.getAttribute("data-forumid")))
+                .find((value) => value > 0);
+        });
+        if (!id)
+            throw new NotAForumError(`Forum ${activityId}'s page doesn't say its id; you may not be allowed to post there.`);
+        return id;
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=discussions.js.map

package/dist/areas/forums/discussions.js.map

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

package/dist/areas/forums/posts.d.ts

@@ -0,0 +1,83 @@
+import type { BrowserContext } from "playwright-core";
+import { type FieldValue } from "../../core/forms.js";
+export interface ForumDiscussion {
+    id: number;
+    subject: string;
+    author: string;
+    started?: string;
+    lastPost: {
+        author: string;
+        time?: string;
+        postId?: number;
+    };
+    replies: number;
+    locked: boolean;
+    pinned: boolean;
+}
+/** A forum's discussions, as its page lists them: who started each, replies, last post. */
+export declare function forumDiscussions(context: BrowserContext, siteUrl: string, activityId: number): Promise<ForumDiscussion[]>;
+export interface ForumPost {
+    id: number;
+    parentId?: number;
+    subject: string;
+    author: {
+        id: number;
+        fullName: string;
+    };
+    created?: string;
+    /** Only when edited more than a minute after posting. */
+    modified?: string;
+    /** The message as plain text, paragraphs and lists kept. */
+    text: string;
+    attachments: {
+        name: string;
+        url: string;
+    }[];
+    privateReply: boolean;
+    unread?: boolean;
+}
+/** A discussion's posts, oldest first, with their messages as text. */
+export declare function discussion(context: BrowserContext, siteUrl: string, discussionId: number): Promise<{
+    discussion: {
+        id: number;
+        forumInstanceId: number;
+        courseId: number;
+    };
+    posts: ForumPost[];
+}>;
+export interface PostInput {
+    /** The message (HTML). */
+    message: string;
+    /** Absolute local paths to attach. */
+    files?: string[];
+    /** Subscribe to the discussion; Moodle's default when missing. */
+    subscribe?: boolean;
+    /** Other post form fields by name ({"pinned": true} for a teacher). */
+    fields?: Record<string, FieldValue>;
+}
+/** Replies to a post; returns the new post's id and its discussion's. */
+export declare function replyToPost(context: BrowserContext, siteUrl: string, postId: number, input: PostInput & {
+    subject?: string;
+}): Promise<{
+    changed: string;
+    postId: number | undefined;
+    discussionId: number | undefined;
+}>;
+/** Starts a discussion in a forum; returns its id. */
+export declare function startDiscussion(context: BrowserContext, siteUrl: string, activityId: number, input: PostInput & {
+    subject: string;
+}): Promise<{
+    changed: string;
+    discussionId: number | undefined;
+}>;
+/**
+ * Pins or unpins, locks or unlocks a discussion, as the discussion list's menu does; what's already
+ * so is left alone. Returns the discussion as the forum lists it afterwards.
+ */
+export declare function setDiscussionState(context: BrowserContext, siteUrl: string, activityId: number, discussionId: number, { pinned, locked }: {
+    pinned?: boolean;
+    locked?: boolean;
+}): Promise<{
+    changed: string;
+    discussion?: ForumDiscussion;
+}>;

package/dist/areas/forums/posts.js

@@ -0,0 +1,114 @@
+import { callService } from "../../core/ajax.js";
+import { isoDate } from "../courses/list.js";
+import { checkLocalFiles } from "../../core/files.js";
+import { formValue, openForm, setFields, submitForm, uploadToDraft } from "../../core/forms.js";
+import { NotAForumError, discussionPosts, forumInstanceId, htmlToTexts, listDiscussions } from "./discussions.js";
+import { decodeEntities } from "../../core/text.js";
+import { MoodleError } from "../../core/errors.js";
+/** A forum's discussions, as its page lists them: who started each, replies, last post. */
+export async function forumDiscussions(context, siteUrl, activityId) {
+    const rows = await listDiscussions(context, siteUrl, activityId);
+    return rows.map((row) => ({
+        id: row.id,
+        subject: row.subject,
+        author: row.author,
+        started: isoDate(row.started),
+        lastPost: { author: row.lastPost.author, time: isoDate(row.lastPost.time), postId: row.lastPost.postId },
+        replies: row.replies,
+        locked: row.locked,
+        pinned: row.pinned,
+    }));
+}
+/** A discussion's posts, oldest first, with their messages as text. */
+export async function discussion(context, siteUrl, discussionId) {
+    const { posts, forumid, courseid } = await discussionPosts(context, siteUrl, discussionId);
+    const texts = await htmlToTexts(context, posts.map((post) => post.message));
+    return {
+        discussion: { id: discussionId, forumInstanceId: forumid, courseId: courseid },
+        posts: posts.map((post, i) => ({
+            id: post.id,
+            parentId: post.parentid ?? undefined,
+            subject: decodeEntities(post.subject),
+            author: { id: post.author.id, fullName: post.author.fullname },
+            created: isoDate(post.timecreated),
+            modified: post.timemodified && post.timemodified - post.timecreated > 60 ? isoDate(post.timemodified) : undefined,
+            text: texts[i] ?? "",
+            attachments: (post.attachments ?? []).map((file) => ({ name: file.filename, url: file.url ?? file.fileurl ?? "" })),
+            privateReply: post.isprivatereply ?? false,
+            unread: post.unread ?? undefined,
+        })),
+    };
+}
+/** Fills and submits the post form at `formPath`; returns the URL Moodle lands on. */
+async function post(context, siteUrl, formPath, input) {
+    // Moodle takes "<p></p>" as a message and posts it blank (confirmed empirically, 5.2).
+    const text = input.message.replace(/<[^>]*>/g, "").replace(/&nbsp;/g, " ").trim();
+    if (text === "" && !/<(img|video|audio|iframe)\b/i.test(input.message))
+        throw new MoodleError("The message is empty: write something before posting.", "invalid-input");
+    if (input.files)
+        await checkLocalFiles(input.files);
+    const page = await openForm(context, siteUrl, formPath);
+    try {
+        if (input.files && input.files.length > 0) {
+            const draft = await formValue(page, "attachments");
+            if (!draft)
+                throw new MoodleError("This forum takes no attachments.", "not-available");
+            await uploadToDraft(page, draft, input.files);
+        }
+        const values = { "message[text]": input.message, ...input.fields };
+        if (input.subject !== undefined)
+            values.subject = input.subject;
+        if (input.subscribe !== undefined)
+            values.discussionsubscribe = input.subscribe;
+        await setFields(page, values);
+        await submitForm(page, "submitbutton");
+        return page.url();
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+/** Replies to a post; returns the new post's id and its discussion's. */
+export async function replyToPost(context, siteUrl, postId, input) {
+    const landed = new URL(await post(context, siteUrl, `mod/forum/post.php?reply=${postId}`, input));
+    // Moodle lands on the discussion, at the new post: discuss.php?d=<discussion>#p<post>.
+    const newPost = /^#p(\d+)$/.exec(landed.hash)?.[1];
+    const discussionId = landed.searchParams.get("d");
+    return {
+        changed: `Replied to post ${postId}${newPost ? ` with post ${newPost}` : ""}.`,
+        postId: newPost ? Number(newPost) : undefined,
+        discussionId: discussionId ? Number(discussionId) : undefined,
+    };
+}
+/** Starts a discussion in a forum; returns its id. */
+export async function startDiscussion(context, siteUrl, activityId, input) {
+    const instance = await forumInstanceId(context, siteUrl, activityId);
+    const before = new Set((await listDiscussions(context, siteUrl, activityId)).map((d) => d.id));
+    await post(context, siteUrl, `mod/forum/post.php?forum=${instance}`, input);
+    const created = (await listDiscussions(context, siteUrl, activityId)).find((d) => !before.has(d.id));
+    return { changed: `Started discussion ${created?.id ?? "?"} "${input.subject}" in forum ${activityId}.`, discussionId: created?.id };
+}
+/**
+ * Pins or unpins, locks or unlocks a discussion, as the discussion list's menu does; what's already
+ * so is left alone. Returns the discussion as the forum lists it afterwards.
+ */
+export async function setDiscussionState(context, siteUrl, activityId, discussionId, { pinned, locked }) {
+    const find = async () => (await forumDiscussions(context, siteUrl, activityId)).find((d) => d.id === discussionId);
+    const row = (await listDiscussions(context, siteUrl, activityId)).find((d) => d.id === discussionId);
+    if (!row)
+        throw new NotAForumError(`Forum ${activityId} has no discussion ${discussionId}. Take its id from the forum's discussions.`);
+    const done = [];
+    if (pinned !== undefined && pinned !== row.pinned) {
+        await callService(context, siteUrl, "mod_forum_set_pin_state", { discussionid: discussionId, targetstate: pinned ? 1 : 0 });
+        done.push(pinned ? "pinned" : "unpinned");
+    }
+    if (locked !== undefined && locked !== row.locked) {
+        // Rows don't always carry the forum's id (confirmed empirically, 5.2): its page does.
+        const instance = row.forumInstanceId ?? (await forumInstanceId(context, siteUrl, activityId));
+        // The service takes the current lock and switches it: 0 locks now, anything else unlocks.
+        await callService(context, siteUrl, "mod_forum_set_lock_state", { forumid: instance, discussionid: discussionId, targetstate: locked ? 0 : 1 });
+        done.push(locked ? "locked" : "unlocked");
+    }
+    return { changed: done.length > 0 ? `Discussion ${discussionId} ${done.join(" and ")}.` : "Nothing to change.", discussion: await find() };
+}
+//# sourceMappingURL=posts.js.map

package/dist/areas/forums/posts.js.map

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

package/dist/areas/grades/gradebook.d.ts

@@ -0,0 +1,104 @@
+import type { BrowserContext, Page } from "playwright-core";
+import { MoodleError } from "../../core/errors.js";
+/** The gradebook can't be read or changed: not allowed, recalculating, or a value Moodle refuses. */
+export declare class GradebookError extends MoodleError {
+    name: string;
+    constructor(message: string);
+}
+/** Moodle's aggregations by their constant (GRADE_AGGREGATE_*). */
+declare const AGGREGATION_CODES: {
+    readonly mean: 0;
+    readonly median: 2;
+    readonly lowest: 4;
+    readonly highest: 6;
+    readonly mode: 8;
+    readonly "weighted-mean": 10;
+    readonly "simple-weighted-mean": 11;
+    readonly "mean-with-extra-credits": 12;
+    readonly natural: 13;
+};
+export type GradeAggregation = keyof typeof AGGREGATION_CODES;
+export declare const GRADE_AGGREGATIONS: GradeAggregation[];
+export interface GradeColumn {
+    id: number;
+    name: string;
+    kind: "item" | "category" | "course";
+    activityId?: number;
+    activityType?: string;
+}
+export interface GraderReport {
+    columns: GradeColumn[];
+    /** Grades as the report shows them ("-" left out). */
+    rows: {
+        userId: number;
+        fullName: string;
+        grades: {
+            itemId: number;
+            grade?: string;
+        }[];
+    }[];
+}
+/** One page of the grader report, by data attributes and links, in any language. */
+export declare function readGraderReport(page: Page): Promise<GraderReport>;
+/**
+ * Everyone's grades in a course as the grader report shows them, page by page, in one group when
+ * given. People come as user id and full name only.
+ */
+export declare function graderReport(context: BrowserContext, siteUrl: string, courseId: number, { group }?: {
+    group?: number;
+}): Promise<GraderReport>;
+export interface GradebookCategory {
+    id: number;
+    /** The category's own grade item (its total). */
+    itemId: number;
+    name: string;
+    parentId?: number;
+    aggregation?: GradeAggregation;
+    maxGrade?: number;
+    /** Its weight in its parent, in percent, where the parent aggregates with weights. */
+    weight?: number;
+}
+export interface GradebookItem {
+    id: number;
+    name: string;
+    categoryId?: number;
+    /** The module ("assign", "quiz"…) for an activity's item, "manual" for one made in the gradebook. */
+    type: string;
+    maxGrade?: number;
+    /** In percent, where the category aggregates with weights. */
+    weight?: number;
+    weightOverridden: boolean;
+}
+/** The gradebook setup page's rows, by data attributes and field names. */
+export declare function readGradebookSetup(page: Page): Promise<{
+    categories: GradebookCategory[];
+    items: GradebookItem[];
+}>;
+/** A course's gradebook setup: its categories (aggregation, weights) and grade items (category, maximum, weight). */
+export declare function gradebookSetup(context: BrowserContext, siteUrl: string, courseId: number): Promise<{
+    categories: GradebookCategory[];
+    items: GradebookItem[];
+}>;
+/**
+ * Changes a grade item: moves it into a category, sets its weight (percent, overriding Natural's
+ * automatic one), or its maximum grade (a manual item's; an activity's is set in the activity).
+ * Returns the item afterwards.
+ */
+export declare function updateGradeItem(context: BrowserContext, siteUrl: string, courseId: number, itemId: number, { category, weight, maxGrade }: {
+    category?: number;
+    weight?: number;
+    maxGrade?: number;
+}): Promise<{
+    changed: string;
+    item?: GradebookItem;
+}>;
+/** Adds a grade category (at the course's top level, or inside `parentId`); returns it as the setup shows it. */
+export declare function addGradeCategory(context: BrowserContext, siteUrl: string, courseId: number, { name, aggregation, parentId }: {
+    name: string;
+    aggregation?: GradeAggregation;
+    parentId?: number;
+}): Promise<{
+    changed: string;
+    category?: GradebookCategory;
+}>;
+export {};