@falkenslab/moodle-driver 0.0.0-stage → 0.4.0

package/dist/core/session.d.ts

@@ -0,0 +1,55 @@
+import type { BrowserContext, Page } from "playwright-core";
+import { MoodleError } from "./errors.js";
+/** No live Moodle session: the person has to log in again (ADR-002). */
+export declare class NotLoggedInError extends MoodleError {
+    name: string;
+    constructor();
+}
+/** What a Moodle page says about its session, read without depending on the interface's language. */
+export interface SessionFacts {
+    /** Moodle adds the `notloggedin` body class when nobody is logged in. */
+    notLoggedIn: boolean;
+    /** `M.cfg.userId`: 0 when logged out; `null` on a page that isn't Moodle's (an SSO provider's). */
+    userId: number | null;
+    /** A logout link, in the user menu of a real user's pages. */
+    hasLogoutLink: boolean;
+    /** A login link: a guest (who also has a user id) gets one and no logout link. */
+    hasLoginLink: boolean;
+}
+export declare function readSessionFacts(page: Page): Promise<SessionFacts>;
+/** Whether a page at `url`, with these facts, belongs to the site and has a real user logged in. */
+export declare function isLoggedIn(url: string, siteUrl: string, facts: SessionFacts): boolean;
+/** Whether `page`, as it is now, shows the site with a real user logged in. */
+export declare function pageIsLoggedIn(page: Page, siteUrl: string): Promise<boolean>;
+/** Has `show` called with the page each function opened, once it's done with it. */
+export declare function followPages(context: BrowserContext, show: (url: string) => Promise<void>): void;
+/**
+ * Opens a page of the site (`path` relative to it) in a new tab and checks the session; throws
+ * `NotLoggedInError`, closing the tab, when Moodle answers with its login page.
+ */
+export declare function openSitePage(context: BrowserContext, siteUrl: string, path: string, { follow }?: {
+    follow?: boolean | undefined;
+}): Promise<Page>;
+/** `M.cfg` as a Moodle page's HTML sets it (`M.cfg = {…};`), parsed; `undefined` when it has none. */
+export declare function readMoodleConfig(html: string): Record<string, unknown> | undefined;
+/** What a page's HTML says about its session, read as `readSessionFacts` reads a page. */
+export declare function htmlSessionFacts(html: string): SessionFacts;
+/**
+ * A page of the site over HTTP with the profile's session, without a tab (ADR-011): its final URL and
+ * HTML. Throws `NotLoggedInError` when Moodle answers with its login page. While the browser is shown,
+ * the working tab shows the page afterwards (ADR-007), unless `follow` is false.
+ */
+export declare function fetchSitePage(context: BrowserContext, siteUrl: string, path: string, { follow }?: {
+    follow?: boolean | undefined;
+}): Promise<{
+    url: string;
+    html: string;
+}>;
+/**
+ * Logs the person out of Moodle through the user menu's logout link (it carries the sesskey; without
+ * one Moodle asks to confirm, and the confirmation is accepted). Returns false when nobody was logged
+ * in. Only Moodle's session ends: a single sign-on provider may keep its own.
+ */
+export declare function logOut(context: BrowserContext, siteUrl: string): Promise<boolean>;
+/** Moodle's message on an error page (its fatal error box: no permission, no such record), which keeps the page's body id. */
+export declare function moodleErrorMessage(page: Page): Promise<string | undefined>;

package/dist/core/session.js

@@ -0,0 +1,157 @@
+import { MoodleError } from "./errors.js";
+import { siteFetch } from "./http.js";
+/** No live Moodle session: the person has to log in again (ADR-002). */
+export class NotLoggedInError extends MoodleError {
+    name = "NotLoggedInError";
+    constructor() {
+        super("There is no Moodle session, or it expired: the person has to log in again.", "not-logged-in");
+    }
+}
+export function readSessionFacts(page) {
+    return page.evaluate(() => {
+        // Runs in the page: Moodle's globals and the DOM, typed loosely on purpose (no DOM lib in Node).
+        const g = globalThis;
+        const userId = g.M?.cfg?.userId;
+        return {
+            notLoggedIn: g.document.body?.classList.contains("notloggedin") ?? true,
+            userId: typeof userId === "number" ? userId : null,
+            hasLogoutLink: g.document.querySelector('a[href*="/login/logout.php"]') !== null,
+            hasLoginLink: g.document.querySelector('a[href*="/login/index.php"]') !== null,
+        };
+    });
+}
+/** Whether a page at `url`, with these facts, belongs to the site and has a real user logged in. */
+export function isLoggedIn(url, siteUrl, facts) {
+    if (!url.startsWith(siteUrl))
+        return false;
+    if (url.startsWith(new URL("login/", siteUrl).href))
+        return false;
+    // Pages without the navigation bar (the assignment grader) have neither link (confirmed empirically,
+    // Moodle 5.2): only a login link without a logout one means a guest.
+    const guest = facts.hasLoginLink && !facts.hasLogoutLink;
+    return !facts.notLoggedIn && (facts.userId ?? 0) > 0 && !guest;
+}
+/** Whether `page`, as it is now, shows the site with a real user logged in. */
+export async function pageIsLoggedIn(page, siteUrl) {
+    return isLoggedIn(page.url(), siteUrl, await readSessionFacts(page));
+}
+// While the person watches (ADR-007), a context's browser manager shows the pages functions worked on.
+const followers = new WeakMap();
+/** Has `show` called with the page each function opened, once it's done with it. */
+export function followPages(context, show) {
+    followers.set(context, show);
+}
+/**
+ * Opens a page of the site (`path` relative to it) in a new tab and checks the session; throws
+ * `NotLoggedInError`, closing the tab, when Moodle answers with its login page.
+ */
+export async function openSitePage(context, siteUrl, path, { follow = true } = {}) {
+    const page = await context.newPage();
+    try {
+        await page.goto(new URL(path, siteUrl).href, { waitUntil: "domcontentloaded" });
+        if (!(await pageIsLoggedIn(page, siteUrl)))
+            throw new NotLoggedInError();
+        // The page as it was opened (a form's URL, not where posting it led), once it's closed.
+        const opened = page.url();
+        if (follow)
+            page.once("close", () => void followers.get(context)?.(opened));
+        return page;
+    }
+    catch (error) {
+        await page.close().catch(() => undefined);
+        throw error;
+    }
+}
+/** `M.cfg` as a Moodle page's HTML sets it (`M.cfg = {…};`), parsed; `undefined` when it has none. */
+export function readMoodleConfig(html) {
+    const start = html.indexOf("M.cfg = {");
+    if (start < 0)
+        return undefined;
+    // The object literal is JSON (Moodle writes it with json_encode): its end is where the braces balance.
+    let depth = 0;
+    let inString = false;
+    const from = html.indexOf("{", start);
+    for (let i = from; i < html.length; i++) {
+        const c = html[i];
+        if (inString) {
+            if (c === "\\")
+                i++;
+            else if (c === '"')
+                inString = false;
+        }
+        else if (c === '"')
+            inString = true;
+        else if (c === "{")
+            depth++;
+        else if (c === "}" && --depth === 0) {
+            try {
+                return JSON.parse(html.slice(from, i + 1));
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    return undefined;
+}
+/** What a page's HTML says about its session, read as `readSessionFacts` reads a page. */
+export function htmlSessionFacts(html) {
+    const userId = readMoodleConfig(html)?.userId;
+    const bodyClass = /<body\b[^>]*\bclass="([^"]*)"/i.exec(html)?.[1] ?? "notloggedin";
+    return {
+        notLoggedIn: /(^|\s)notloggedin(\s|$)/.test(bodyClass),
+        userId: typeof userId === "number" ? userId : null,
+        hasLogoutLink: /href="[^"]*\/login\/logout\.php/.test(html),
+        hasLoginLink: /href="[^"]*\/login\/index\.php/.test(html),
+    };
+}
+/**
+ * A page of the site over HTTP with the profile's session, without a tab (ADR-011): its final URL and
+ * HTML. Throws `NotLoggedInError` when Moodle answers with its login page. While the browser is shown,
+ * the working tab shows the page afterwards (ADR-007), unless `follow` is false.
+ */
+export async function fetchSitePage(context, siteUrl, path, { follow = true } = {}) {
+    const response = await siteFetch(context, new URL(path, siteUrl).href);
+    if (!isLoggedIn(response.url, siteUrl, htmlSessionFacts(response.body)))
+        throw new NotLoggedInError();
+    if (follow)
+        void followers.get(context)?.(response.url);
+    return { url: response.url, html: response.body };
+}
+/**
+ * Logs the person out of Moodle through the user menu's logout link (it carries the sesskey; without
+ * one Moodle asks to confirm, and the confirmation is accepted). Returns false when nobody was logged
+ * in. Only Moodle's session ends: a single sign-on provider may keep its own.
+ */
+export async function logOut(context, siteUrl) {
+    const page = await context.newPage();
+    const home = new URL("my/", siteUrl).href;
+    try {
+        await page.goto(home, { waitUntil: "domcontentloaded" });
+        if (!(await pageIsLoggedIn(page, siteUrl)))
+            return false;
+        const link = await page.locator('a[href*="/login/logout.php"]').first().getAttribute("href").catch(() => null);
+        // Moodle's redirect after logging out can abort this navigation (ERR_ABORTED, confirmed empirically,
+        // Moodle 5.2); whether the session ended is checked below either way.
+        await page.goto(new URL(link ?? "login/logout.php", siteUrl).href, { waitUntil: "domcontentloaded" }).catch((error) => {
+            if (!/ERR_ABORTED/.test(error.message))
+                throw error;
+        });
+        const confirm = page.locator('form[action*="/login/logout.php"] [type="submit"]');
+        if ((await confirm.count()) > 0)
+            await Promise.all([page.waitForNavigation({ waitUntil: "domcontentloaded" }), confirm.first().click()]);
+        await page.goto(home, { waitUntil: "domcontentloaded" });
+        if (await pageIsLoggedIn(page, siteUrl))
+            throw new MoodleError("Moodle didn't end the session: the person is still logged in. Try again, or log out in the browser.", "logout-failed");
+        return true;
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+/** Moodle's message on an error page (its fatal error box: no permission, no such record), which keeps the page's body id. */
+export async function moodleErrorMessage(page) {
+    const box = page.locator('[data-rel="fatalerror"] .errormessage');
+    return (await box.count()) > 0 ? ((await box.first().textContent()) ?? "").replace(/\s+/g, " ").trim() : undefined;
+}
+//# sourceMappingURL=session.js.map

package/dist/core/session.js.map

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

package/dist/core/site.d.ts

@@ -0,0 +1,8 @@
+/** `M.cfg.wwwroot` in a Moodle page, JSON-escaped as Moodle writes it (`"http:\/\/host"`). */
+export declare function readWwwroot(html: string): string | undefined;
+/**
+ * The site's base URL for any URL of it (the site, a course, the login page), read from the
+ * `M.cfg.wwwroot` Moodle puts in every page; fetched without the browser or any session. Throws
+ * `MoodleUrlError` when it can't be reached or isn't a Moodle.
+ */
+export declare function findMoodleSite(url: string, fetchImpl?: typeof fetch): Promise<string>;

package/dist/core/site.js

@@ -0,0 +1,36 @@
+import { MoodleUrlError, parseSiteUrl } from "../options.js";
+// The first answer of a site that just started can take long (confirmed empirically, the sandbox).
+const TIMEOUT_MS = 60_000;
+/** `M.cfg.wwwroot` in a Moodle page, JSON-escaped as Moodle writes it (`"http:\/\/host"`). */
+export function readWwwroot(html) {
+    const match = /"wwwroot":"((?:[^"\\]|\\.)*)"/.exec(html);
+    if (!match)
+        return undefined;
+    try {
+        return JSON.parse(`"${match[1]}"`);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The site's base URL for any URL of it (the site, a course, the login page), read from the
+ * `M.cfg.wwwroot` Moodle puts in every page; fetched without the browser or any session. Throws
+ * `MoodleUrlError` when it can't be reached or isn't a Moodle.
+ */
+export async function findMoodleSite(url, fetchImpl = fetch) {
+    parseSiteUrl(url); // http(s) and well formed, or MoodleUrlError.
+    let html;
+    try {
+        const response = await fetchImpl(url.trim(), { redirect: "follow", signal: AbortSignal.timeout(TIMEOUT_MS) });
+        html = await response.text();
+    }
+    catch (error) {
+        throw new MoodleUrlError(`Couldn't reach ${url}: ${error.message}. Check the URL and that the site is up.`);
+    }
+    const wwwroot = readWwwroot(html);
+    if (!wwwroot)
+        throw new MoodleUrlError(`${url} doesn't look like a Moodle site (its page has no M.cfg.wwwroot). Check the URL.`);
+    return parseSiteUrl(wwwroot);
+}
+//# sourceMappingURL=site.js.map

package/dist/core/site.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"site.js","sourceRoot":"","sources":["../../src/core/site.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7D,mGAAmG;AACnG,MAAM,UAAU,GAAG,MAAM,CAAC;AAE1B,8FAA8F;AAC9F,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,KAAK,GAAG,+BAA+B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzD,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,CAAW,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW,EAAE,YAA0B,KAAK;IAC/E,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,8CAA8C;IACjE,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC9G,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,cAAc,CAAC,kBAAkB,GAAG,KAAM,KAAe,CAAC,OAAO,0CAA0C,CAAC,CAAC;IACzH,CAAC;IACD,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,cAAc,CAAC,GAAG,GAAG,kFAAkF,CAAC,CAAC;IACjI,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC;AAC/B,CAAC"}

package/dist/core/text.d.ts

@@ -0,0 +1,21 @@
+import type { Page } from "playwright-core";
+/** Moodle formats names for HTML (`format_string`): plain text for the client. */
+export declare function decodeEntities(text: string): string;
+/**
+ * The text of the elements matching `selector` in `page`, one string each: paragraphs, line breaks
+ * and list items kept, scripts and styles left out. Runs in the page with no named functions inside
+ * (see the conventions on page.evaluate).
+ */
+export declare function readTexts(page: Page, selector: string): Promise<string[]>;
+/** A video, audio or player found in a page's content. */
+export interface MediaItem {
+    kind: "video" | "audio" | "youtube" | "vimeo" | "embed";
+    url: string;
+    title?: string;
+}
+/**
+ * The media in the elements matching `selector`: `<video>`/`<audio>` and their sources, players in
+ * iframes, video.js's `data-setup` sources (Moodle's media filter turns a YouTube link into one), and
+ * plain links to media. YouTube URLs come back as `watch?v=` links. Read in the page.
+ */
+export declare function readMedia(page: Page, selector: string): Promise<MediaItem[]>;

package/dist/core/text.js

@@ -0,0 +1,113 @@
+import { inPage } from "./inPage.js";
+/** Moodle formats names for HTML (`format_string`): plain text for the client. */
+export function decodeEntities(text) {
+    return text.replace(/&(#x[0-9a-f]+|#\d+|amp|lt|gt|quot|apos|nbsp);/gi, (entity, code) => {
+        const lower = code.toLowerCase();
+        if (lower.startsWith("#x"))
+            return String.fromCodePoint(parseInt(lower.slice(2), 16));
+        if (lower.startsWith("#"))
+            return String.fromCodePoint(parseInt(lower.slice(1), 10));
+        return { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " }[lower] ?? entity;
+    });
+}
+/**
+ * The text of the elements matching `selector` in `page`, one string each: paragraphs, line breaks
+ * and list items kept, scripts and styles left out. Runs in the page with no named functions inside
+ * (see the conventions on page.evaluate).
+ */
+export function readTexts(page, selector) {
+    return page.evaluate((selector) => {
+        const doc = globalThis;
+        const BLOCKS = new Set(["P", "DIV", "LI", "UL", "OL", "TR", "TABLE", "PRE", "BLOCKQUOTE", "SECTION", "ARTICLE", "H1", "H2", "H3", "H4", "H5", "H6"]);
+        return Array.from(doc.document.querySelectorAll(selector)).map((root) => {
+            let raw = "";
+            const stack = [root];
+            while (stack.length > 0) {
+                const item = stack.pop();
+                if (typeof item === "string")
+                    raw += item;
+                else if (item.nodeType === 3)
+                    raw += (item.textContent ?? "").replace(/\s+/g, " ");
+                else if (item.nodeType !== 1 || item.nodeName === "SCRIPT" || item.nodeName === "STYLE")
+                    continue;
+                else if (item.nodeName === "BR")
+                    raw += "\n";
+                else if (item.nodeName === "PRE")
+                    raw += `\n${item.textContent ?? ""}\n`;
+                else {
+                    const isBlock = BLOCKS.has(item.nodeName);
+                    raw += item.nodeName === "LI" ? "\n- " : isBlock ? "\n" : "";
+                    // A list item ends where the next one starts: no blank line between items.
+                    stack.push(isBlock && item.nodeName !== "LI" ? "\n" : "", ...Array.from(item.childNodes).reverse());
+                }
+            }
+            return raw
+                .replace(/[ \t]+\n/g, "\n")
+                .replace(/\n[ \t]+/g, "\n")
+                .replace(/\n- +/g, "\n- ")
+                .replace(/\n{3,}/g, "\n\n")
+                .trim();
+        });
+    }, selector);
+}
+/**
+ * The media in the elements matching `selector`: `<video>`/`<audio>` and their sources, players in
+ * iframes, video.js's `data-setup` sources (Moodle's media filter turns a YouTube link into one), and
+ * plain links to media. YouTube URLs come back as `watch?v=` links. Read in the page.
+ */
+export function readMedia(page, selector) {
+    return inPage(page, (selector) => {
+        const roots = Array.from(globalThis.document.querySelectorAll(selector));
+        const found = new Map();
+        const add = (raw, tag, title) => {
+            if (!raw || raw.startsWith("blob:") || raw.startsWith("data:"))
+                return;
+            let url;
+            try {
+                url = new URL(raw, globalThis.location.href);
+            }
+            catch {
+                return;
+            }
+            const youtube = /(?:youtube(?:-nocookie)?\.com\/(?:embed\/|watch\?v=|shorts\/)|youtu\.be\/)([\w-]{6,})/.exec(url.href)?.[1];
+            let kind;
+            let href = url.href;
+            if (youtube) {
+                kind = "youtube";
+                href = `https://www.youtube.com/watch?v=${youtube}`;
+            }
+            else if (/vimeo\.com\//.test(url.href))
+                kind = "vimeo";
+            else if (tag === "AUDIO" || /\.(mp3|ogg|oga|wav|m4a|aac)(\?|$)/i.test(url.pathname))
+                kind = "audio";
+            else if (tag === "VIDEO" || /\.(mp4|webm|m4v|mov|ogv|m3u8)(\?|$)/i.test(url.pathname))
+                kind = "video";
+            else if (tag === "IFRAME")
+                kind = "embed";
+            else
+                return;
+            if (!found.has(href))
+                found.set(href, { kind, url: href, ...(title ? { title } : {}) });
+        };
+        for (const root of roots) {
+            for (const el of Array.from(root.querySelectorAll("video, audio, source, iframe, a[href]"))) {
+                const media = el.tagName === "SOURCE" ? "VIDEO" : el.tagName;
+                add(el.getAttribute("src") ?? el.getAttribute("href"), media, el.getAttribute("title"));
+                for (const attribute of ["data-setup-lazy", "data-setup"]) {
+                    const setup = el.getAttribute(attribute);
+                    if (!setup)
+                        continue;
+                    try {
+                        for (const source of JSON.parse(setup).sources ?? [])
+                            add(source.src, "VIDEO", el.getAttribute("title"));
+                    }
+                    catch {
+                        // Not JSON: nothing to read.
+                    }
+                }
+            }
+        }
+        return Array.from(found.values());
+    }, selector);
+}
+//# sourceMappingURL=text.js.map

package/dist/core/text.js.map

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

package/dist/home.d.ts

@@ -0,0 +1,19 @@
+/** The command's home when nothing else is given: `~/.moodle-driver`, the same on every system. */
+export declare function defaultHome(home?: string): string;
+/** A site's folder name: its host and port, with anything but letters, digits, dots and hyphens as `_` (`localhost:8080` is `localhost_8080`). */
+export declare function siteFolderName(site: string): string;
+/** A site's folder in the command's home: its `site.json` and its profiles. */
+export declare function siteDir(site: string, home?: string): string;
+/** A profile's name from a Moodle username: anything but letters, digits, dots, hyphens and underscores as `_`. */
+export declare function profileName(username: string): string;
+/**
+ * The browser profile folder the `moodle` command uses for an account on a site:
+ * `sites/<host>/profiles/<as>`. Without `as`, the site's default (the account last logged in with,
+ * named in its `site.json`); `MoodleError` with code `not-found` when the command hasn't logged in to
+ * the site. Pass it as `profileDir` to share the command's session; `home` is `~/.moodle-driver`
+ * unless given.
+ */
+export declare function siteProfileDir(site: string, { as, home }?: {
+    as?: string;
+    home?: string;
+}): string;

package/dist/home.js

@@ -0,0 +1,54 @@
+// Where the `moodle` command keeps each site's browser profiles (ADR-013): `~/.moodle-driver` on every
+// system, a folder per site, a named profile per account. The library still chooses no folder by
+// itself; a program that wants to share the command's sessions asks for one here.
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { MoodleError } from "./core/errors.js";
+import { parseSiteUrl } from "./options.js";
+/** The command's home when nothing else is given: `~/.moodle-driver`, the same on every system. */
+export function defaultHome(home = os.homedir()) {
+    return path.join(home, ".moodle-driver");
+}
+/** A site's folder name: its host and port, with anything but letters, digits, dots and hyphens as `_` (`localhost:8080` is `localhost_8080`). */
+export function siteFolderName(site) {
+    return new URL(parseSiteUrl(site)).host.replace(/[^a-z0-9.-]/gi, "_");
+}
+/** A site's folder in the command's home: its `site.json` and its profiles. */
+export function siteDir(site, home = defaultHome()) {
+    return path.join(home, "sites", siteFolderName(site));
+}
+/** A profile's name from a Moodle username: anything but letters, digits, dots, hyphens and underscores as `_`. */
+export function profileName(username) {
+    const name = username.trim().replace(/[^\w.-]/g, "_").replace(/^\.+/, "");
+    return name === "" ? "user" : name;
+}
+/**
+ * The browser profile folder the `moodle` command uses for an account on a site:
+ * `sites/<host>/profiles/<as>`. Without `as`, the site's default (the account last logged in with,
+ * named in its `site.json`); `MoodleError` with code `not-found` when the command hasn't logged in to
+ * the site. Pass it as `profileDir` to share the command's session; `home` is `~/.moodle-driver`
+ * unless given.
+ */
+export function siteProfileDir(site, { as, home = defaultHome() } = {}) {
+    if (as === undefined) {
+        let record;
+        try {
+            record = JSON.parse(readFileSync(path.join(siteDir(site, home), "site.json"), "utf8"));
+        }
+        catch {
+            // No site.json: the command hasn't logged in to this site.
+        }
+        if (record?.default)
+            return siteProfileDir(site, { as: record.default, home });
+        if (record?.profileDir)
+            return record.profileDir;
+        const url = parseSiteUrl(site);
+        throw new MoodleError(`There's no profile for ${url} yet: log in with \`moodle login --site ${url}\`, or name one with \`as\`.`, "not-found");
+    }
+    if (!/^[\w.-]+$/.test(as) || as.startsWith(".")) {
+        throw new MoodleError(`A profile's name is letters, digits, dots, hyphens and underscores, not starting with a dot: "${as}".`, "invalid-input");
+    }
+    return path.join(siteDir(site, home), "profiles", as);
+}
+//# sourceMappingURL=home.js.map

package/dist/home.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"home.js","sourceRoot":"","sources":["../src/home.ts"],"names":[],"mappings":"AAAA,uGAAuG;AACvG,iGAAiG;AACjG,kFAAkF;AAClF,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,mGAAmG;AACnG,MAAM,UAAU,WAAW,CAAC,IAAI,GAAG,EAAE,CAAC,OAAO,EAAE;IAC7C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;AAC3C,CAAC;AAED,kJAAkJ;AAClJ,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;AACxE,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,IAAI,GAAG,WAAW,EAAE;IACxD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,mHAAmH;AACnH,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC1E,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,EAAE,EAAE,EAAE,IAAI,GAAG,WAAW,EAAE,KAAqC,EAAE;IAC5G,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,IAAI,MAA6D,CAAC;QAClE,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAkB,CAAC;QAC1G,CAAC;QAAC,MAAM,CAAC;YACP,2DAA2D;QAC7D,CAAC;QACD,IAAI,MAAM,EAAE,OAAO;YAAE,OAAO,cAAc,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/E,IAAI,MAAM,EAAE,UAAU;YAAE,OAAO,MAAM,CAAC,UAAU,CAAC;QACjD,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,IAAI,WAAW,CAAC,0BAA0B,GAAG,2CAA2C,GAAG,8BAA8B,EAAE,WAAW,CAAC,CAAC;IAChJ,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,WAAW,CAAC,iGAAiG,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC;IAClJ,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC;AACxD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+export * from "./client.js";
+export * from "./options.js";
+export { createBrowserManager, canShowWindow, BrowserNotFoundError, BrowserDownloadingError, NoDisplayError, type BrowserManager, type ContextOptions } from "./browser/manager.js";
+export { SESSION_COOKIES_FILE } from "./browser/cookies.js";
+export { siteProfileDir } from "./home.js";
+export * from "./categories.js";
+export * from "./core/errors.js";
+export { logIn, LoginTimeoutError, LoginWindowClosedError, type LoginResult } from "./core/login.js";
+export { logOut, NotLoggedInError } from "./core/session.js";
+export { MoodleServiceError } from "./core/ajax.js";
+export { FormError, type FieldValue } from "./core/forms.js";
+export { findMoodleSite } from "./core/site.js";
+export { checkLocalFiles, downloadFile, type DownloadedFile } from "./core/files.js";
+export type { MediaItem } from "./core/text.js";
+export { publicSiteInfo, courseActivityTypes } from "./areas/site/info.js";
+export { userById, siteName, courseRoles, courseAbilities, whoAmI, type User, type Me } from "./areas/site/users.js";
+export { listCourses, updateCourse, COURSE_CLASSIFICATIONS, CourseError, type CourseClassification, type Course } from "./areas/courses/list.js";
+export { courseStructure, listAssignments, pendingActivities, COMPLETION_STATES, type CompletionState, type CourseActivity, type CourseSection, type CourseAssignment, type PendingActivity, } from "./areas/courses/structure.js";
+export { activitiesOverview, deadlines, courseUpdates, type OverviewField } from "./areas/courses/overview.js";
+export { createActivity, updateActivity, editActivity, duplicateActivity, deleteActivity, addSection, editSection, deleteSection, activitySettings, ACTIVITY_VISIBILITIES, ActivitySettingsError, type ActivityVisibility, type ActivityFields, type CourseChange, type FormField, } from "./areas/activities/build.js";
+export { activityContent, CONTENT_TYPES, NotViewableError, type ContentType, type ContentOptions, type ActivityContent } from "./areas/activities/content.js";
+export { NotAnAssignmentError, GradingError, type PluginContent } from "./areas/assignments/grader.js";
+export { assignmentSubmissions, gradeSubmission, rubric, grantExtension, type Submission, type GradingCriterion, type GradingDefinition } from "./areas/assignments/grading.js";
+export { studentAssignment, saveSubmission, submitForGrading, SubmissionError, type StudentAssignment } from "./areas/assignments/student.js";
+export { quizInfo, startQuizAttempt, readAttempt, answerQuizQuestions, finishQuizAttempt, readReview, setQuizOverride, QuizError, type Detail, type QuizInfo, type QuestionField, type Question, } from "./areas/quizzes/attempts.js";
+export { quizResults, type QuizAttemptResult } from "./areas/quizzes/results.js";
+export { quizStructure, addQuestionsToQuiz, type QuizSlot } from "./areas/quizzes/structure.js";
+export { questionBanks, questions, importQuestions, createQuestion, QUESTION_TYPES, QuestionBankError, type QuestionBank, type BankQuestion, type BankCategory, type QuestionType, type QuestionInput, } from "./areas/questions/banks.js";
+export { NotAForumError } from "./areas/forums/discussions.js";
+export { forumDiscussions, discussion, replyToPost, startDiscussion, setDiscussionState, type ForumDiscussion, type ForumPost, type PostInput } from "./areas/forums/posts.js";
+export { getSurvey, submitSurvey, SurveyError, type SurveyType, type SurveyField, type SurveyQuestion } from "./areas/surveys/surveys.js";
+export { getChoice, answerChoice, ChoiceError, type Choice } from "./areas/surveys/choice.js";
+export { lessonPage, answerLessonPage, LessonError, type LessonField, type LessonPage } from "./areas/lessons/lessons.js";
+export { h5pActivity, NotAnH5PActivityError, type H5PAttempt, type H5PActivity } from "./areas/h5p/h5p.js";
+export { scorm, openScorm, ScormError, type ScoStatus, type ScormSco, type ScormActivity, type OpenedScorm } from "./areas/scorm/scorm.js";
+export { myGrades, NoGradeReportError, type GradeRow } from "./areas/grades/user-report.js";
+export { graderReport, gradebookSetup, updateGradeItem, addGradeCategory, GRADE_AGGREGATIONS, GradebookError, type GradeAggregation, type GradeColumn, type GraderReport, type GradebookCategory, type GradebookItem, } from "./areas/grades/gradebook.js";
+export { setCompletion, overrideCompletion, completionReport, CompletionError, type CompletionCell, type CompletionReport } from "./areas/completion/completion.js";
+export { participants, participantFilters, groups, NoParticipantsError, type Participant, type CourseGroup } from "./areas/participants/participants.js";
+export { upcomingEvents, createEvent, deleteEvent, CalendarError, type CalendarEvent } from "./areas/calendar/calendar.js";
+export { notifications, markNotificationsRead, conversations, conversation, sendMessage, MessageError, type Notification, type ConversationSummary } from "./areas/messages/messages.js";

package/dist/index.js

@@ -0,0 +1,52 @@
+// The public API of @falkenslab/moodle-driver: everything a program needs to work a Moodle site with
+// the person's own session. The primitives the operations are built from are in ./internals.ts
+// (`@falkenslab/moodle-driver/internals`); what neither exports is internal.
+// The Moodle object, the browser and what a program chooses.
+export * from "./client.js";
+export * from "./options.js";
+export { createBrowserManager, canShowWindow, BrowserNotFoundError, BrowserDownloadingError, NoDisplayError } from "./browser/manager.js";
+export { SESSION_COOKIES_FILE } from "./browser/cookies.js";
+export { siteProfileDir } from "./home.js";
+export * from "./categories.js";
+export * from "./core/errors.js";
+// The session and the site.
+export { logIn, LoginTimeoutError, LoginWindowClosedError } from "./core/login.js";
+export { logOut, NotLoggedInError } from "./core/session.js";
+export { MoodleServiceError } from "./core/ajax.js";
+export { FormError } from "./core/forms.js";
+export { findMoodleSite } from "./core/site.js";
+export { checkLocalFiles, downloadFile } from "./core/files.js";
+export { publicSiteInfo, courseActivityTypes } from "./areas/site/info.js";
+export { userById, siteName, courseRoles, courseAbilities, whoAmI } from "./areas/site/users.js";
+// Courses.
+export { listCourses, updateCourse, COURSE_CLASSIFICATIONS, CourseError } from "./areas/courses/list.js";
+export { courseStructure, listAssignments, pendingActivities, COMPLETION_STATES, } from "./areas/courses/structure.js";
+export { activitiesOverview, deadlines, courseUpdates } from "./areas/courses/overview.js";
+// Activities: building them and viewing their content.
+export { createActivity, updateActivity, editActivity, duplicateActivity, deleteActivity, addSection, editSection, deleteSection, activitySettings, ACTIVITY_VISIBILITIES, ActivitySettingsError, } from "./areas/activities/build.js";
+export { activityContent, CONTENT_TYPES, NotViewableError } from "./areas/activities/content.js";
+// Assignments.
+export { NotAnAssignmentError, GradingError } from "./areas/assignments/grader.js";
+export { assignmentSubmissions, gradeSubmission, rubric, grantExtension } from "./areas/assignments/grading.js";
+export { studentAssignment, saveSubmission, submitForGrading, SubmissionError } from "./areas/assignments/student.js";
+// Quizzes and question banks.
+export { quizInfo, startQuizAttempt, readAttempt, answerQuizQuestions, finishQuizAttempt, readReview, setQuizOverride, QuizError, } from "./areas/quizzes/attempts.js";
+export { quizResults } from "./areas/quizzes/results.js";
+export { quizStructure, addQuestionsToQuiz } from "./areas/quizzes/structure.js";
+export { questionBanks, questions, importQuestions, createQuestion, QUESTION_TYPES, QuestionBankError, } from "./areas/questions/banks.js";
+// Forums, surveys, choices, lessons, H5P.
+export { NotAForumError } from "./areas/forums/discussions.js";
+export { forumDiscussions, discussion, replyToPost, startDiscussion, setDiscussionState } from "./areas/forums/posts.js";
+export { getSurvey, submitSurvey, SurveyError } from "./areas/surveys/surveys.js";
+export { getChoice, answerChoice, ChoiceError } from "./areas/surveys/choice.js";
+export { lessonPage, answerLessonPage, LessonError } from "./areas/lessons/lessons.js";
+export { h5pActivity, NotAnH5PActivityError } from "./areas/h5p/h5p.js";
+export { scorm, openScorm, ScormError } from "./areas/scorm/scorm.js";
+// Grades, completion, participants, calendar, messages.
+export { myGrades, NoGradeReportError } from "./areas/grades/user-report.js";
+export { graderReport, gradebookSetup, updateGradeItem, addGradeCategory, GRADE_AGGREGATIONS, GradebookError, } from "./areas/grades/gradebook.js";
+export { setCompletion, overrideCompletion, completionReport, CompletionError } from "./areas/completion/completion.js";
+export { participants, participantFilters, groups, NoParticipantsError } from "./areas/participants/participants.js";
+export { upcomingEvents, createEvent, deleteEvent, CalendarError } from "./areas/calendar/calendar.js";
+export { notifications, markNotificationsRead, conversations, conversation, sendMessage, MessageError } from "./areas/messages/messages.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/internals.d.ts

@@ -0,0 +1,11 @@
+export { callService, readPageConfig, type PageConfig } from "./core/ajax.js";
+export { openSitePage, fetchSitePage, readSessionFacts, htmlSessionFacts, readMoodleConfig, isLoggedIn, pageIsLoggedIn, moodleErrorMessage, type SessionFacts } from "./core/session.js";
+export { readOwnProfile } from "./core/login.js";
+export { openForm, formValue, setFields, submitForm, uploadToDraft, dateSelectorValues, dateSelectorDate } from "./core/forms.js";
+export { inPage } from "./core/inPage.js";
+export { decodeEntities, readTexts, readMedia } from "./core/text.js";
+export { readingSeconds, pause } from "./core/pace.js";
+export { editCourse, renameActivity, renameSection, type EditorAction } from "./core/editor.js";
+export { readWwwroot } from "./core/site.js";
+export { fileNameFor } from "./core/files.js";
+export { courseState, activityDetails, type CourseState, type ActivityDetails } from "./areas/courses/state.js";