@falkenslab/moodle-driver 0.0.0-stage → 0.3.1

package/dist/moodle/content.d.ts

@@ -0,0 +1,43 @@
+import type { BrowserContext } from "playwright-core";
+import type { Trail } from "../options.js";
+import { type MediaItem } from "./text.js";
+export declare const CONTENT_TYPES: readonly ["page", "book", "label", "url", "resource", "folder"];
+export type ContentType = (typeof CONTENT_TYPES)[number];
+/** The activity isn't of the given type, or the person can't view it. */
+export declare class NotViewableError extends Error {
+    name: string;
+}
+export interface ActivityContent {
+    activity: {
+        id: number;
+        type: ContentType;
+    };
+    /** Page and label content, as plain text with paragraphs and lists kept. */
+    text?: string;
+    /** A book's chapters, in order. */
+    chapters?: {
+        title: string;
+        text: string;
+    }[];
+    /** Videos, audio and players in a page's, label's or book's content. */
+    media?: MediaItem[];
+    /** A URL resource's target. */
+    url?: string;
+    /** A file resource's or a folder's files. */
+    files?: {
+        name: string;
+        url: string;
+    }[];
+    trail: Trail;
+    /** With the realistic trail, the time spent reading. */
+    readingSeconds?: number;
+}
+/**
+ * Reads a page's or label's text, a book's chapters, a URL resource's target, or a file resource's
+ * or folder's files. With the realistic trail, page by page at a reader's pace, calling `onProgress`
+ * with the seconds read so far while it pauses.
+ */
+export declare function activityContent(context: BrowserContext, siteUrl: string, cmid: number, type: ContentType, { trail, onProgress }?: {
+    trail?: Trail;
+    onProgress?: (secondsRead: number) => void;
+}): Promise<ActivityContent>;

package/dist/moodle/content.js

@@ -0,0 +1,105 @@
+import { pause, readingSeconds } from "./pace.js";
+import { openSitePage } from "./session.js";
+import { readMedia, readTexts } from "./text.js";
+export const CONTENT_TYPES = ["page", "book", "label", "url", "resource", "folder"];
+// A book has a reasonable number of chapters; the bound stops a loop on a broken "next" link.
+const MAX_CHAPTERS = 200;
+/** The activity isn't of the given type, or the person can't view it. */
+export class NotViewableError extends Error {
+    name = "NotViewableError";
+}
+async function links(page, selector) {
+    return page.evaluate((selector) => {
+        const anchors = globalThis.document.querySelectorAll(selector);
+        return Array.from(anchors).map((a) => ({ name: (a.textContent ?? "").replace(/\s+/g, " ").trim(), url: a.href }));
+    }, selector);
+}
+/** A book chapter's title and text, the title taken off the text's start. */
+function chapter(title, body) {
+    return { title, text: body.startsWith(title) ? body.slice(title.length).trim() : body };
+}
+/**
+ * Reads a page's or label's text, a book's chapters, a URL resource's target, or a file resource's
+ * or folder's files. With the realistic trail, page by page at a reader's pace, calling `onProgress`
+ * with the seconds read so far while it pauses.
+ */
+export async function activityContent(context, siteUrl, cmid, type, { trail = "realistic", onProgress } = {}) {
+    const realistic = trail === "realistic";
+    const output = { activity: { id: cmid, type }, trail };
+    let secondsRead = 0;
+    const readAsAPerson = async (text) => {
+        if (!realistic)
+            return;
+        const seconds = readingSeconds(text);
+        await pause(seconds, (elapsed) => onProgress?.(secondsRead + elapsed));
+        secondsRead += seconds;
+    };
+    // Opens the activity's page and checks it shows what this type should.
+    const view = async (path, ready) => {
+        const page = await openSitePage(context, siteUrl, path);
+        if ((await page.locator(ready).count()) === 0) {
+            await page.close().catch(() => undefined);
+            throw new NotViewableError(`Activity ${cmid} isn't a ${type} you can view. Take its id and module from the course structure.`);
+        }
+        return page;
+    };
+    if (type === "page" || type === "label") {
+        const path = type === "page" ? `mod/page/view.php?id=${cmid}` : `mod/label/view.php?id=${cmid}`;
+        const selector = type === "page" ? "#region-main .generalbox" : `[data-for="cmitem"][data-id="${cmid}"] .activity-altcontent`;
+        const page = await view(path, selector);
+        output.text = (await readTexts(page, selector))[0] ?? "";
+        output.media = await readMedia(page, selector);
+        await page.close();
+        await readAsAPerson(output.text);
+    }
+    else if (type === "book") {
+        output.chapters = [];
+        const media = [];
+        if (realistic) {
+            // Chapter by chapter, following "next", as a reader does.
+            const page = await view(`mod/book/view.php?id=${cmid}`, "#region-main .book_content");
+            try {
+                for (let i = 0; i < MAX_CHAPTERS; i++) {
+                    const title = (await readTexts(page, "#region-main .book_content h3, #region-main .book_content h2"))[0] ?? "";
+                    const read = chapter(title, (await readTexts(page, "#region-main .book_content"))[0] ?? "");
+                    output.chapters.push(read);
+                    media.push(...(await readMedia(page, "#region-main .book_content")));
+                    await readAsAPerson(read.text);
+                    const next = page.locator("#region-main a.btn-next").first();
+                    if ((await next.count()) === 0)
+                        break;
+                    await page.goto((await next.getAttribute("href")), { waitUntil: "domcontentloaded" });
+                }
+            }
+            finally {
+                await page.close().catch(() => undefined);
+            }
+        }
+        else {
+            const page = await view(`mod/book/tool/print/index.php?id=${cmid}`, ".book_chapter");
+            const titles = await readTexts(page, ".book_chapter h2, .book_chapter h3");
+            const bodies = await readTexts(page, ".book_chapter");
+            output.chapters = bodies.map((body, i) => chapter(titles[i] ?? "", body));
+            media.push(...(await readMedia(page, ".book_chapter")));
+            await page.close();
+        }
+        // The same video can appear in several chapters: once each.
+        output.media = [...new Map(media.map((item) => [item.url, item])).values()];
+    }
+    else if (type === "url") {
+        // forceview logs the view and shows the link instead of leaving the site.
+        const page = await view(`mod/url/view.php?id=${cmid}&forceview=1`, ".urlworkaround a");
+        output.url = (await links(page, ".urlworkaround a"))[0]?.url;
+        await page.close();
+    }
+    else {
+        const [path, selector] = type === "resource" ? [`mod/resource/view.php?id=${cmid}&forceview=1`, ".resourceworkaround a"] : [`mod/folder/view.php?id=${cmid}`, '.foldertree a[href*="pluginfile.php"]'];
+        const page = await view(path, selector);
+        output.files = await links(page, selector);
+        await page.close();
+    }
+    if (secondsRead > 0)
+        output.readingSeconds = secondsRead;
+    return output;
+}
+//# sourceMappingURL=content.js.map

package/dist/moodle/content.js.map

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

package/dist/moodle/course.d.ts

@@ -0,0 +1,51 @@
+import type { BrowserContext, Page } from "playwright-core";
+/** `core_courseformat_get_state` as Moodle 4.0–5.2 returns it, the fields read. */
+export interface CourseState {
+    course?: {
+        id: string;
+        baseurl?: string;
+    };
+    section: {
+        id: string;
+        number: number;
+        title: string;
+        visible?: boolean;
+        hasrestrictions?: boolean;
+        sectionurl?: string;
+        component?: string | null;
+        parentsectionid?: string | null;
+        cmlist?: string[];
+    }[];
+    cm: {
+        id: string;
+        name: string;
+        module: string;
+        url?: string;
+        visible: boolean;
+        uservisible?: boolean;
+        accessvisible?: boolean;
+        hascmrestrictions?: boolean;
+        sectionid: string;
+        istrackeduser?: boolean;
+        completionstate?: number;
+        isoverallcomplete?: boolean;
+    }[];
+}
+/** The course page's own state: sections and activities, as a JSON string (ADR-004). */
+export declare function courseState(context: BrowserContext, siteUrl: string, courseId: number): Promise<CourseState>;
+/** What the course page shows of an activity, in the site's language. */
+export interface ActivityDetails {
+    id: number;
+    dates: {
+        label: string;
+        value: string;
+    }[];
+    restriction?: string;
+}
+/** The activities on a course or section page: their dates and restriction texts. */
+export declare function readActivityDetails(page: Page): Promise<ActivityDetails[]>;
+/**
+ * Details for the given activities: from the course page, then from the section pages of those it
+ * doesn't show (courses with one section per page).
+ */
+export declare function activityDetails(context: BrowserContext, siteUrl: string, courseId: number, state: CourseState): Promise<Map<number, ActivityDetails>>;

package/dist/moodle/course.js

@@ -0,0 +1,45 @@
+import { callService } from "./ajax.js";
+import { openSitePage } from "./session.js";
+/** The course page's own state: sections and activities, as a JSON string (ADR-004). */
+export async function courseState(context, siteUrl, courseId) {
+    return JSON.parse(await callService(context, siteUrl, "core_courseformat_get_state", { courseid: courseId }));
+}
+/** The activities on a course or section page: their dates and restriction texts. */
+export function readActivityDetails(page) {
+    return page.evaluate(() => {
+        const doc = globalThis.document;
+        // No helper functions in here: see the conventions on page.evaluate.
+        return Array.from(doc.querySelectorAll('[data-for="cmitem"][data-id], li.activity[data-id]')).map((item) => {
+            const dates = Array.from(item.querySelectorAll('[data-region="activity-dates"] .date-item')).map((date) => {
+                const label = (date.querySelector(".date-item-label")?.textContent ?? "").replace(/\s+/g, " ").trim();
+                const all = (date.textContent ?? "").replace(/\s+/g, " ").trim();
+                return { label: label.replace(/:$/, ""), value: all.slice(label.length).trim() };
+            });
+            const restriction = (item.querySelector(".availabilityinfo")?.textContent ?? "").replace(/\s+/g, " ").trim() || undefined;
+            return { id: Number(item.getAttribute("data-id")), dates, restriction };
+        });
+    });
+}
+/**
+ * Details for the given activities: from the course page, then from the section pages of those it
+ * doesn't show (courses with one section per page).
+ */
+export async function activityDetails(context, siteUrl, courseId, state) {
+    const details = new Map();
+    const read = async (path) => {
+        const page = await openSitePage(context, siteUrl, path);
+        try {
+            for (const item of await readActivityDetails(page))
+                details.set(item.id, item);
+        }
+        finally {
+            await page.close().catch(() => undefined);
+        }
+    };
+    await read(`course/view.php?id=${courseId}`);
+    const missingSections = new Set(state.cm.filter((cm) => !details.has(Number(cm.id))).map((cm) => cm.sectionid));
+    for (const sectionId of missingSections)
+        await read(`course/section.php?id=${sectionId}`);
+    return details;
+}
+//# sourceMappingURL=course.js.map

package/dist/moodle/course.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"course.js","sourceRoot":"","sources":["../../src/moodle/course.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAgC5C,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAuB,EAAE,OAAe,EAAE,QAAgB;IAC1F,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,WAAW,CAAS,OAAO,EAAE,OAAO,EAAE,6BAA6B,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAgB,CAAC;AACvI,CAAC;AASD,qFAAqF;AACrF,MAAM,UAAU,mBAAmB,CAAC,IAAU;IAC5C,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;QAOxB,MAAM,GAAG,GAAI,UAA+C,CAAC,QAAQ,CAAC;QACtE,qEAAqE;QACrE,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,oDAAoD,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YACzG,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,2CAA2C,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;gBACxG,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,kBAAkB,CAAC,EAAE,WAAW,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;gBACtG,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;gBACjE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACnF,CAAC,CAAC,CAAC;YACH,MAAM,WAAW,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,mBAAmB,CAAC,EAAE,WAAW,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;YAC1H,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QAC1E,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAAuB,EAAE,OAAe,EAAE,QAAgB,EAAE,KAAkB;IAClH,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IACnD,MAAM,IAAI,GAAG,KAAK,EAAE,IAAY,EAAE,EAAE;QAClC,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QACxD,IAAI,CAAC;YACH,KAAK,MAAM,IAAI,IAAI,MAAM,mBAAmB,CAAC,IAAI,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACjF,CAAC;gBAAS,CAAC;YACT,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC,CAAC;IACF,MAAM,IAAI,CAAC,sBAAsB,QAAQ,EAAE,CAAC,CAAC;IAC7C,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAChH,KAAK,MAAM,SAAS,IAAI,eAAe;QAAE,MAAM,IAAI,CAAC,yBAAyB,SAAS,EAAE,CAAC,CAAC;IAC1F,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/moodle/courses.d.ts

@@ -0,0 +1,57 @@
+import type { BrowserContext } from "playwright-core";
+import { type FieldValue } from "./forms.js";
+/** Which courses by their dates; "all" includes those the person hid from their dashboard. */
+export declare const COURSE_CLASSIFICATIONS: readonly ["all", "inprogress", "future", "past"];
+export type CourseClassification = (typeof COURSE_CLASSIFICATIONS)[number];
+export interface Course {
+    id: number;
+    shortname: string;
+    fullname: string;
+    category?: string;
+    url: string;
+    /** Whether students can see the course. */
+    visible: boolean;
+    startDate?: string;
+    endDate?: string;
+    /** The person's completion percentage, when the course tracks it. */
+    progress?: number;
+    /** When the person last opened the course. */
+    lastAccess?: string;
+}
+/** A course as `core_course_get_enrolled_courses_by_timeline_classification` returns it (Moodle 5.2). */
+export interface MoodleCourse {
+    id: number;
+    shortname: string;
+    fullname: string;
+    coursecategory?: string;
+    viewurl: string;
+    visible: boolean;
+    startdate?: number;
+    enddate?: number;
+    progress?: number | null;
+    hasprogress?: boolean;
+    timeaccess?: number | null;
+}
+/** Unix seconds as ISO 8601; Moodle uses 0 for "none". */
+export declare function isoDate(seconds: number | null | undefined): string | undefined;
+export declare function toCourse(raw: MoodleCourse): Course;
+/** The courses the person is enrolled in, as teacher or student. */
+export declare function listCourses(context: BrowserContext, siteUrl: string, classification?: CourseClassification): Promise<Course[]>;
+/** A course that isn't there, or the person can't change. */
+export declare class CourseError extends Error {
+    name: string;
+}
+/**
+ * Changes a course's full name, short name, summary (HTML) or any other setting by its form field
+ * name, through the course's settings form; returns the course as `listCourses` gives it. Moodle's
+ * refusals (a short name already taken) come back as `FormError` by field.
+ */
+export declare function updateCourse(context: BrowserContext, siteUrl: string, courseId: number, { fullName, shortName, summary, settings }: {
+    fullName?: string;
+    shortName?: string;
+    summary?: string;
+    settings?: Record<string, FieldValue>;
+}): Promise<{
+    changed: string;
+    course?: Course;
+}>;

package/dist/moodle/courses.js

@@ -0,0 +1,70 @@
+import { callService } from "./ajax.js";
+import { openForm, setFields, submitForm } from "./forms.js";
+import { NotLoggedInError } from "./session.js";
+import { decodeEntities } from "./text.js";
+/** Which courses by their dates; "all" includes those the person hid from their dashboard. */
+export const COURSE_CLASSIFICATIONS = ["all", "inprogress", "future", "past"];
+const MOODLE_CLASSIFICATIONS = { all: "allincludinghidden", inprogress: "inprogress", future: "future", past: "past" };
+/** Unix seconds as ISO 8601; Moodle uses 0 for "none". */
+export function isoDate(seconds) {
+    return seconds ? new Date(seconds * 1000).toISOString() : undefined;
+}
+export function toCourse(raw) {
+    return {
+        id: raw.id,
+        shortname: decodeEntities(raw.shortname),
+        fullname: decodeEntities(raw.fullname),
+        category: raw.coursecategory ? decodeEntities(raw.coursecategory) : undefined,
+        url: raw.viewurl,
+        visible: raw.visible,
+        startDate: isoDate(raw.startdate),
+        endDate: isoDate(raw.enddate),
+        progress: raw.hasprogress && typeof raw.progress === "number" ? raw.progress : undefined,
+        lastAccess: isoDate(raw.timeaccess),
+    };
+}
+/** The courses the person is enrolled in, as teacher or student. */
+export async function listCourses(context, siteUrl, classification = "all") {
+    const { courses } = await callService(context, siteUrl, "core_course_get_enrolled_courses_by_timeline_classification", {
+        classification: MOODLE_CLASSIFICATIONS[classification],
+        limit: 0,
+        offset: 0,
+        sort: "fullname",
+    });
+    return courses.map(toCourse);
+}
+/** A course that isn't there, or the person can't change. */
+export class CourseError extends Error {
+    name = "CourseError";
+}
+/**
+ * Changes a course's full name, short name, summary (HTML) or any other setting by its form field
+ * name, through the course's settings form; returns the course as `listCourses` gives it. Moodle's
+ * refusals (a short name already taken) come back as `FormError` by field.
+ */
+export async function updateCourse(context, siteUrl, courseId, { fullName, shortName, summary, settings }) {
+    const values = { ...settings };
+    if (fullName !== undefined)
+        values.fullname = fullName;
+    if (shortName !== undefined)
+        values.shortname = shortName;
+    if (summary !== undefined)
+        values["summary_editor[text]"] = summary;
+    if (Object.keys(values).length === 0)
+        return { changed: "Nothing to change.", course: (await listCourses(context, siteUrl)).find((c) => c.id === courseId) };
+    const page = await openForm(context, siteUrl, `course/edit.php?id=${courseId}`).catch((error) => {
+        if (error instanceof NotLoggedInError)
+            throw error;
+        throw new CourseError(`You can't change course ${courseId}'s settings: it doesn't exist, or you aren't allowed.`);
+    });
+    try {
+        await setFields(page, values);
+        await submitForm(page, "saveanddisplay");
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+    const course = (await listCourses(context, siteUrl)).find((c) => c.id === courseId);
+    return { changed: `Course ${courseId} updated (${Object.keys(values).join(", ")}).`, course };
+}
+//# sourceMappingURL=courses.js.map

package/dist/moodle/courses.js.map

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

package/dist/moodle/editor.d.ts

@@ -0,0 +1,18 @@
+import type { BrowserContext } from "playwright-core";
+/** The course editor's actions this server uses (`core_courseformat\stateactions`, Moodle 4.0–5.2). */
+export type EditorAction = "cm_show" | "cm_hide" | "cm_stealth" | "cm_move" | "cm_duplicate" | "cm_delete" | "section_add" | "section_show" | "section_hide" | "section_move_after" | "section_delete";
+/**
+ * Runs one of the course editor's actions through its own service (ADR-004), as the editor does:
+ * ids of activities or sections, and a target section (`cm_move`: at its end; `section_add`,
+ * `section_move_after`: after it) or a target activity (`cm_move`: before it).
+ */
+export declare function editCourse(context: BrowserContext, siteUrl: string, courseId: number, action: EditorAction, ids: number[], target?: {
+    sectionId?: number;
+    activityId?: number;
+}): Promise<void>;
+/** The course format (topics, weeks…), a class of the course page's body: no service tells teachers. */
+export declare function courseFormat(context: BrowserContext, siteUrl: string, courseId: number): Promise<string>;
+/** Renames an activity, as the course page's in-place editor does. */
+export declare function renameActivity(context: BrowserContext, siteUrl: string, activityId: number, name: string): Promise<void>;
+/** Renames a section through its course format's in-place editor. */
+export declare function renameSection(context: BrowserContext, siteUrl: string, courseId: number, sectionId: number, name: string): Promise<void>;

package/dist/moodle/editor.js

@@ -0,0 +1,50 @@
+import { callService } from "./ajax.js";
+import { openSitePage } from "./session.js";
+/**
+ * Runs one of the course editor's actions through its own service (ADR-004), as the editor does:
+ * ids of activities or sections, and a target section (`cm_move`: at its end; `section_add`,
+ * `section_move_after`: after it) or a target activity (`cm_move`: before it).
+ */
+export async function editCourse(context, siteUrl, courseId, action, ids, target = {}) {
+    await callService(context, siteUrl, "core_courseformat_update_course", {
+        action,
+        courseid: courseId,
+        ids,
+        ...(target.sectionId ? { targetsectionid: target.sectionId } : {}),
+        ...(target.activityId ? { targetcmid: target.activityId } : {}),
+    });
+}
+// A course's format doesn't change while a program runs.
+const formats = new Map();
+/** The course format (topics, weeks…), a class of the course page's body: no service tells teachers. */
+export async function courseFormat(context, siteUrl, courseId) {
+    const key = `${siteUrl}|${courseId}`;
+    const cached = formats.get(key);
+    if (cached)
+        return cached;
+    const page = await openSitePage(context, siteUrl, `course/view.php?id=${courseId}`);
+    try {
+        const classes = await page.evaluate(() => globalThis.document.body.className);
+        const format = classes
+            .split(" ")
+            .find((name) => name.startsWith("format-"))
+            ?.slice("format-".length);
+        if (!format)
+            throw new Error(`Course ${courseId}'s format isn't on its page.`);
+        formats.set(key, format);
+        return format;
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+/** Renames an activity, as the course page's in-place editor does. */
+export async function renameActivity(context, siteUrl, activityId, name) {
+    await callService(context, siteUrl, "core_update_inplace_editable", { component: "core_course", itemtype: "activityname", itemid: activityId, value: name });
+}
+/** Renames a section through its course format's in-place editor. */
+export async function renameSection(context, siteUrl, courseId, sectionId, name) {
+    const format = await courseFormat(context, siteUrl, courseId);
+    await callService(context, siteUrl, "core_update_inplace_editable", { component: `format_${format}`, itemtype: "sectionname", itemid: sectionId, value: name });
+}
+//# sourceMappingURL=editor.js.map

package/dist/moodle/editor.js.map

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

package/dist/moodle/files.d.ts

@@ -0,0 +1,16 @@
+import type { BrowserContext } from "playwright-core";
+/** Local files given to upload (a submission, an attachment, a resource): absolute, and there. */
+export declare function checkLocalFiles(files: string[]): Promise<void>;
+/** A file name from Content-Disposition, else the URL's last segment; never a path. */
+export declare function fileNameFor(url: URL, disposition: string | undefined): string;
+export interface DownloadedFile {
+    path: string;
+    name: string;
+    size: number;
+    contentType?: string;
+}
+/**
+ * Saves a file of the site into `destDir` with the person's session, never overwriting. Only URLs of
+ * the site's origin: the session's cookies go nowhere else (its media outside Moodle's path included).
+ */
+export declare function downloadFile(context: BrowserContext, siteUrl: string, url: string, destDir: string): Promise<DownloadedFile>;

package/dist/moodle/files.js

@@ -0,0 +1,57 @@
+import { access, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { NotLoggedInError } from "./session.js";
+/** Local files given to upload (a submission, an attachment, a resource): absolute, and there. */
+export async function checkLocalFiles(files) {
+    for (const file of files) {
+        if (!path.isAbsolute(file))
+            throw new Error(`Give files as absolute paths: "${file}".`);
+        await access(file).catch(() => {
+            throw new Error(`There's no file at ${file}.`);
+        });
+    }
+}
+/** A file name from Content-Disposition, else the URL's last segment; never a path. */
+export function fileNameFor(url, disposition) {
+    const encoded = disposition && /filename\*=UTF-8''([^;]+)/i.exec(disposition)?.[1];
+    const plain = disposition && /filename="?([^";]+)"?/i.exec(disposition)?.[1];
+    const raw = encoded ? decodeURIComponent(encoded) : (plain ?? decodeURIComponent(url.pathname.split("/").pop() || "download"));
+    // The last segment of whatever path it names, then without characters a file name can't have.
+    const name = (raw.split(/[\\/]/).pop() ?? "").replace(/[:*?"<>|]+/g, "_").trim();
+    return name === "" || name === "." || name === ".." ? "download" : name;
+}
+/** `dir/name`, or `dir/name (2).ext`… when it exists: a download never overwrites. */
+async function freePath(dir, name) {
+    const { name: stem, ext } = path.parse(name);
+    for (let n = 1;; n++) {
+        const candidate = path.join(dir, n === 1 ? name : `${stem} (${n})${ext}`);
+        if (!(await access(candidate).then(() => true, () => false)))
+            return candidate;
+    }
+}
+/**
+ * Saves a file of the site into `destDir` with the person's session, never overwriting. Only URLs of
+ * the site's origin: the session's cookies go nowhere else (its media outside Moodle's path included).
+ */
+export async function downloadFile(context, siteUrl, url, destDir) {
+    const target = new URL(url);
+    const origin = new URL(siteUrl).origin;
+    if (target.origin !== origin)
+        throw new Error(`Only files of ${origin} can be downloaded with the session; ${target.origin} isn't the site.`);
+    if (!path.isAbsolute(destDir))
+        throw new Error(`Give the destination folder as an absolute path: "${destDir}".`);
+    // The context's request API carries its cookies without opening a tab.
+    const response = await context.request.get(target.href, { maxRedirects: 5 });
+    const contentType = response.headers()["content-type"]?.split(";")[0]?.trim();
+    // A file the session can't reach comes back as the login page.
+    if (contentType === "text/html" && new URL(response.url()).pathname.includes("/login/"))
+        throw new NotLoggedInError();
+    if (!response.ok())
+        throw new Error(`Moodle answered ${response.status()} for ${target.pathname}: the file doesn't exist or you can't see it.`);
+    await mkdir(destDir, { recursive: true });
+    const body = await response.body();
+    const saved = await freePath(destDir, fileNameFor(target, response.headers()["content-disposition"]));
+    await writeFile(saved, body);
+    return { path: saved, name: path.basename(saved), size: body.length, contentType };
+}
+//# sourceMappingURL=files.js.map

package/dist/moodle/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/moodle/files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,kGAAkG;AAClG,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAAe;IACnD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,IAAI,CAAC,CAAC;QACxF,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YAC5B,MAAM,IAAI,KAAK,CAAC,sBAAsB,IAAI,GAAG,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAAC,GAAQ,EAAE,WAA+B;IACnE,MAAM,OAAO,GAAG,WAAW,IAAI,4BAA4B,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACnF,MAAM,KAAK,GAAG,WAAW,IAAI,wBAAwB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7E,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,UAAU,CAAC,CAAC,CAAC;IAC/H,8FAA8F;IAC9F,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACjF,OAAO,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1E,CAAC;AAED,sFAAsF;AACtF,KAAK,UAAU,QAAQ,CAAC,GAAW,EAAE,IAAY;IAC/C,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7C,KAAK,IAAI,CAAC,GAAG,CAAC,GAAI,CAAC,EAAE,EAAE,CAAC;QACtB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC;QAC1E,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;YAAE,OAAO,SAAS,CAAC;IACjF,CAAC;AACH,CAAC;AASD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAuB,EAAE,OAAe,EAAE,GAAW,EAAE,OAAe;IACvG,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IACvC,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,iBAAiB,MAAM,wCAAwC,MAAM,CAAC,MAAM,kBAAkB,CAAC,CAAC;IAC9I,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,OAAO,IAAI,CAAC,CAAC;IACjH,uEAAuE;IACvE,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC,CAAC;IAC7E,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC,cAAc,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IAC9E,+DAA+D;IAC/D,IAAI,WAAW,KAAK,WAAW,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,MAAM,IAAI,gBAAgB,EAAE,CAAC;IACtH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,QAAQ,CAAC,MAAM,EAAE,QAAQ,MAAM,CAAC,QAAQ,+CAA+C,CAAC,CAAC;IAChJ,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACtG,MAAM,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC7B,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC;AACrF,CAAC"}

package/dist/moodle/forms.d.ts

@@ -0,0 +1,44 @@
+import type { BrowserContext, Page } from "playwright-core";
+/** A form field's value: text, a number, a checkbox, or a multiple select's values. */
+export type FieldValue = string | number | boolean | string[];
+/** Moodle refused the form, or a field to set isn't in it. */
+export declare class FormError extends Error {
+    readonly fields: {
+        field: string;
+        message: string;
+    }[];
+    name: string;
+    constructor(message: string, fields: {
+        field: string;
+        message: string;
+    }[]);
+}
+/** Opens a Moodle form page and waits for its editors to be ready. */
+export declare function openForm(context: BrowserContext, siteUrl: string, pathAndQuery: string): Promise<Page>;
+/** A hidden field's value in the form (a draft area id, the course id…). */
+export declare function formValue(page: Page, name: string): Promise<string | undefined>;
+/**
+ * Sets fields by their form name: text inputs and textareas (through TinyMCE when it edits them),
+ * selects (several values for a multiple one), checkboxes and radios, in the order given (a field can
+ * enable the next one). Throws `FormError` naming the fields the form doesn't have, and those it has
+ * disabled: Moodle wouldn't send them, and the change would be lost unnoticed.
+ */
+export declare function setFields(page: Page, values: Record<string, FieldValue>, formSelector?: string): Promise<void>;
+/**
+ * Uploads local files to a form's draft area, as the file picker's "Upload a file" does: the
+ * upload repository's id comes from the page's file picker settings, the context from `M.cfg`.
+ */
+export declare function uploadToDraft(page: Page, draftItemId: string, filePaths: string[]): Promise<void>;
+/**
+ * Submits the form with one of its buttons and waits for the next page. Throws `FormError` with
+ * Moodle's messages by field (`#id_error_<field>`) when the form comes back with errors.
+ */
+export declare function submitForm(page: Page, button: string): Promise<void>;
+/**
+ * The values of a Moodle date selector's parts (`name[day]`, `[month]`, `[year]`, `[hour]`,
+ * `[minute]`) for `date`, in the person's time zone (`M.cfg.usertimezone`), which is how Moodle
+ * reads them. Its "enable" checkbox, when it has one, is the caller's to set first.
+ */
+export declare function dateSelectorValues(page: Page, name: string, date: Date): Promise<Record<string, FieldValue>>;
+/** The date a Moodle date selector holds (`name[day]`… in the person's time zone), or undefined when it's off. */
+export declare function dateSelectorDate(page: Page, name: string): Promise<Date | undefined>;