@falkenslab/moodle-driver 0.0.0-stage → 0.3.1

package/dist/moodle/participants.js

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

package/dist/moodle/participants.js.map

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

package/dist/moodle/questionBank.d.ts

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

package/dist/moodle/questionBank.js

@@ -0,0 +1,235 @@
+// Question banks (Moodle 5: shared banks are qbank activities; quizzes keep private ones), their
+// questions read from the bank page by field names and icons, questions imported from a GIFT or
+// Moodle XML file through the import form, and single questions made through their edit form.
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { checkLocalFiles } from "./files.js";
+import { formValue, openForm, setFields, submitForm, uploadToDraft } from "./forms.js";
+import { NotLoggedInError, openSitePage } from "./session.js";
+/** The bank isn't there, or Moodle refused the questions. */
+export class QuestionBankError extends Error {
+    name = "QuestionBankError";
+}
+/** A course's question banks: its shared ones and the activities' own, as the banks page lists them. */
+export async function questionBanks(context, siteUrl, courseId) {
+    const page = await openSitePage(context, siteUrl, `question/banks.php?courseid=${courseId}`);
+    try {
+        if ((await page.locator("body#page-question-banks").count()) === 0) {
+            throw new QuestionBankError(`You can't see course ${courseId}'s question banks: the course doesn't exist, or you aren't allowed.`);
+        }
+        return await page.evaluate(() => {
+            const doc = globalThis.document;
+            return Array.from(doc.querySelectorAll(".question-banks-list li")).flatMap((item) => {
+                const link = item.querySelector('a[href*="/mod/"][href*="view.php"]');
+                const match = /\/mod\/([a-z0-9_]+)\/view\.php\?(?:.*&)?id=(\d+)/.exec(link?.getAttribute("href") ?? "");
+                if (!match)
+                    return [];
+                return [{ cmid: Number(match[2]), name: (link?.textContent ?? "").replace(/\s+/g, " ").trim(), type: match[1], shared: item.closest(".shared-banks") !== null }];
+            });
+        });
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+/** The bank page's categories (its category filter's options) and its context id. */
+async function bankCategories(page) {
+    return page.evaluate(() => {
+        const doc = globalThis.document;
+        const categories = Array.from(doc.querySelectorAll('[data-filterregion="filtertypedata"] select[data-field-name="category"] option'))
+            .filter((option) => option.value !== "")
+            // Names come indented, with their question count: "   Default for X (6)".
+            .map((option) => ({ id: Number(option.value), name: (option.textContent ?? "").replace(/\s+/g, " ").replace(/\s*\(\d+\)$/, "").trim() }));
+        return { contextId: Number(doc.querySelector(".questionbankwindow[data-contextid]")?.getAttribute("data-contextid")), categories };
+    });
+}
+/** The questions on a bank page: id from their checkbox, type from their icon, name from the in-place editor. */
+export function readBankQuestions(page, categoryId) {
+    return page.evaluate((categoryId) => {
+        const doc = globalThis.document;
+        return Array.from(doc.querySelectorAll("#categoryquestions tbody tr")).flatMap((row) => {
+            const id = Number(/^q(\d+)$/.exec(row.querySelector('input[type="checkbox"][name^="q"]')?.getAttribute("name") ?? "")?.[1]);
+            if (!id)
+                return [];
+            const type = /\/qtype_([a-z0-9_]+)\//.exec(row.querySelector('[data-columnid*="question_type_column"] img')?.getAttribute("src") ?? "")?.[1] ?? "";
+            const name = row.querySelector('[data-itemtype="questionname"]')?.getAttribute("data-value") ?? "";
+            const status = row.querySelector('select[name="question_status_dropdown"]')?.value;
+            const version = (row.querySelector('[data-columnid*="version_number_column"]')?.textContent ?? "").trim();
+            return [{ id, name, type, ...(status ? { status } : {}), ...(version ? { version } : {}), categoryId }];
+        });
+    }, categoryId);
+}
+// Modules that keep questions (FEATURE_USES_QUESTIONS in Moodle 5): a shared bank, a quiz's own.
+const BANK_MODULES = new Set(["qbank", "quiz"]);
+const bankModules = new Map();
+/**
+ * Checks that a course module keeps questions before opening its bank: Moodle creates a bank's
+ * categories for any activity whose bank page is opened (confirmed empirically, 5.2). The module
+ * comes from its settings form, which changes nothing.
+ */
+async function checkBank(context, siteUrl, bankCmid) {
+    const key = `${siteUrl}|${bankCmid}`;
+    let module = bankModules.get(key);
+    if (!module) {
+        const page = await openSitePage(context, siteUrl, `course/modedit.php?update=${bankCmid}`);
+        try {
+            module = (await formValue(page, "modulename")) ?? "";
+        }
+        finally {
+            await page.close().catch(() => undefined);
+        }
+        if (module)
+            bankModules.set(key, module);
+    }
+    if (!BANK_MODULES.has(module)) {
+        throw new QuestionBankError(`Activity ${bankCmid} ${module ? `is a ${module}, which` : "doesn't exist, or you can't edit it, so it"} has no question bank. Take a bank's id from the course's question banks.`);
+    }
+}
+// A bank page shows this many questions at most; more than that in one category isn't read.
+const PER_PAGE = 1000;
+/** A bank's categories and every question in them, category by category. */
+export async function questions(context, siteUrl, bankCmid) {
+    await checkBank(context, siteUrl, bankCmid);
+    const page = await openSitePage(context, siteUrl, `question/edit.php?cmid=${bankCmid}`);
+    try {
+        if ((await page.locator("body#page-question-edit .questionbankwindow").count()) === 0) {
+            throw new QuestionBankError(`Activity ${bankCmid} has no question bank you can see. Take a bank's id from the course's question banks.`);
+        }
+        const { contextId, categories } = await bankCategories(page);
+        const found = [];
+        for (const category of categories) {
+            await page.goto(new URL(`question/edit.php?cmid=${bankCmid}&cat=${category.id},${contextId}&qperpage=${PER_PAGE}`, siteUrl).href, { waitUntil: "domcontentloaded" });
+            found.push(...(await readBankQuestions(page, category.id)));
+        }
+        return { categories, questions: found };
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+/** The form's category option ("<id>,<context>") for a category id; the form's default without one. */
+async function categoryOption(page, categoryId) {
+    if (categoryId === undefined)
+        return undefined;
+    const values = await page.evaluate(() => Array.from(globalThis.document.querySelectorAll('form.mform select[name="category"] option')).map((o) => o.value));
+    const value = values.find((v) => v.split(",")[0] === String(categoryId));
+    if (!value)
+        throw new QuestionBankError(`The bank has no category ${categoryId}: take one from the bank's categories.`);
+    return value;
+}
+/** Moodle's messages on the page after a form or an import (problems first). */
+async function pageProblems(page) {
+    return page.evaluate(() => {
+        const doc = globalThis.document;
+        return Array.from(doc.querySelectorAll("#region-main .alert-danger, #region-main .notifyproblem, #region-main .errorbox, #region-main .alert-warning"))
+            .map((element) => {
+            // Without the close button, the error box's heading and its "more information" link.
+            const copy = element.cloneNode(true);
+            for (const extra of Array.from(copy.querySelectorAll("button, .visually-hidden, .errorcode, h2, h3, h4")))
+                extra.remove();
+            return (copy.textContent ?? "").replace(/\s+/g, " ").trim();
+        })
+            .filter(Boolean);
+    });
+}
+/**
+ * Imports questions into a bank from a GIFT or Moodle XML file (a local path) or text, through the
+ * bank's import form; returns the questions created. A file Moodle can't parse comes back as a
+ * `QuestionBankError` with its messages, and nothing is imported.
+ */
+export async function importQuestions(context, siteUrl, bankCmid, { format, file, text, categoryId }) {
+    if ((file === undefined) === (text === undefined))
+        throw new QuestionBankError("Give the questions as a file or as text, one of the two.");
+    if (file)
+        await checkLocalFiles([file]);
+    const before = new Set((await questions(context, siteUrl, bankCmid)).questions.map((q) => q.id));
+    // Text goes up as a file, as a person would upload one.
+    const dir = text !== undefined ? await mkdtemp(path.join(tmpdir(), "moodle-import-")) : undefined;
+    const upload = dir ? path.join(dir, format === "gift" ? "questions.txt" : "questions.xml") : file;
+    if (dir)
+        await writeFile(upload, text, "utf8");
+    const page = await openForm(context, siteUrl, `question/bank/importquestions/import.php?cmid=${bankCmid}`).catch((error) => {
+        if (error instanceof NotLoggedInError)
+            throw error;
+        throw new QuestionBankError(`Activity ${bankCmid} has no question bank you can import into.`);
+    });
+    try {
+        await uploadToDraft(page, (await formValue(page, "newfile")), [upload]);
+        const values = { format };
+        const category = await categoryOption(page, categoryId);
+        // The file's own categories would override the one chosen.
+        if (category)
+            Object.assign(values, { category, catfromfile: false, contextfromfile: false });
+        await setFields(page, values);
+        await submitForm(page, "submitbutton");
+        const problems = await pageProblems(page);
+        if (problems.length > 0)
+            throw new QuestionBankError(`Moodle didn't import the questions: ${problems.join(" ")}`);
+    }
+    finally {
+        await page.close().catch(() => undefined);
+        if (dir)
+            await rm(dir, { recursive: true, force: true });
+    }
+    const created = (await questions(context, siteUrl, bankCmid)).questions.filter((q) => !before.has(q.id));
+    return { changed: `Imported ${created.length} question${created.length === 1 ? "" : "s"} into bank ${bankCmid}.`, questions: created };
+}
+export const QUESTION_TYPES = ["multichoice", "truefalse", "shortanswer", "numerical", "essay"];
+/** The option of a fraction select nearest to `fraction` (Moodle offers 100%, 90%, 83.33%…). */
+async function nearestFraction(page, field, fraction) {
+    const options = await page.evaluate((field) => Array.from(globalThis.document.querySelectorAll(`select[name="${field}"] option`)).map((o) => o.value), field);
+    return options.reduce((best, value) => (Math.abs(Number(value) - fraction) < Math.abs(Number(best) - fraction) ? value : best), options[0] ?? "0.0");
+}
+/**
+ * Creates one question in a bank through its type's edit form; returns its id. Imports are the way
+ * for several; this is for one-offs.
+ */
+export async function createQuestion(context, siteUrl, bankCmid, input) {
+    if (!QUESTION_TYPES.includes(input.type))
+        throw new QuestionBankError(`Question type ${input.type} isn't one this creates (${QUESTION_TYPES.join(", ")}); import it as GIFT or Moodle XML instead.`);
+    const answers = input.answers ?? [];
+    if (["multichoice", "shortanswer", "numerical"].includes(input.type) && answers.length === 0)
+        throw new QuestionBankError(`A ${input.type} question needs answers.`);
+    if (input.type === "truefalse" && input.correct === undefined)
+        throw new QuestionBankError("A true/false question needs its right answer (correct).");
+    const { categories } = await questions(context, siteUrl, bankCmid);
+    // The bank lists its "Top" category first, which holds no questions: its default one comes next.
+    const category = input.categoryId ?? (categories[1] ?? categories[0])?.id;
+    const page = await openForm(context, siteUrl, `question/bank/editquestion/question.php?cmid=${bankCmid}&category=${category}&qtype=${input.type}`).catch((error) => {
+        if (error instanceof NotLoggedInError)
+            throw error;
+        throw new QuestionBankError(`Activity ${bankCmid} has no question bank you can add to, or category ${category} isn't in it.`);
+    });
+    try {
+        // The form comes with a few blank answers; "Blanks for more" adds three at a time.
+        for (let i = 0; i < 10 && answers.length > Number((await formValue(page, "noanswers")) ?? answers.length); i++) {
+            await Promise.all([page.waitForNavigation({ waitUntil: "domcontentloaded" }), page.click('form.mform [name="addanswers"]')]);
+        }
+        const values = { name: input.name, "questiontext[text]": input.text, ...(input.defaultMark !== undefined ? { defaultmark: input.defaultMark } : {}) };
+        const choice = await categoryOption(page, input.categoryId);
+        if (choice)
+            values.category = choice;
+        if (input.type === "truefalse")
+            values.correctanswer = input.correct ? 1 : 0;
+        if (input.type === "multichoice")
+            values.single = answers.filter((a) => a.fraction > 0).length > 1 ? 0 : 1;
+        for (const [i, answer] of answers.entries()) {
+            values[input.type === "multichoice" ? `answer[${i}][text]` : `answer[${i}]`] = answer.text;
+            values[`fraction[${i}]`] = await nearestFraction(page, `fraction[${i}]`, answer.fraction);
+            if (answer.feedback !== undefined)
+                values[`feedback[${i}][text]`] = answer.feedback;
+            if (answer.tolerance !== undefined)
+                values[`tolerance[${i}]`] = answer.tolerance;
+        }
+        await setFields(page, { ...values, ...input.fields });
+        await submitForm(page, "submitbutton");
+        // Moodle lands on the bank, naming the question it changed last.
+        const id = Number(new URL(page.url()).searchParams.get("lastchanged")) || undefined;
+        return { changed: `Created ${input.type} question${id ? ` ${id}` : ""} "${input.name}" in bank ${bankCmid}.`, questionId: id };
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=questionBank.js.map

package/dist/moodle/questionBank.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"questionBank.js","sourceRoot":"","sources":["../../src/moodle/questionBank.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,gGAAgG;AAChG,8FAA8F;AAC9F,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAmB,MAAM,YAAY,CAAC;AACxG,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE9D,6DAA6D;AAC7D,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,IAAI,GAAG,mBAAmB,CAAC;CACrC;AAYD,wGAAwG;AACxG,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAuB,EAAE,OAAe,EAAE,QAAgB;IAC5F,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,+BAA+B,QAAQ,EAAE,CAAC,CAAC;IAC7F,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;YACnE,MAAM,IAAI,iBAAiB,CAAC,wBAAwB,QAAQ,qEAAqE,CAAC,CAAC;QACrI,CAAC;QACD,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;YAQ9B,MAAM,GAAG,GAAI,UAA0C,CAAC,QAAQ,CAAC;YACjE,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,yBAAyB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;gBAClF,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,oCAAoC,CAAC,CAAC;gBACtE,MAAM,KAAK,GAAG,kDAAkD,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;gBACxG,IAAI,CAAC,KAAK;oBAAE,OAAO,EAAE,CAAC;gBACtB,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,WAAW,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YACpK,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;AACH,CAAC;AAkBD,qFAAqF;AACrF,KAAK,UAAU,cAAc,CAAC,IAAU;IACtC,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;QACxB,MAAM,GAAG,GAAI,UAEX,CAAC,QAAQ,CAAC;QACZ,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,gFAAgF,CAAC,CAAC;aAClI,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,KAAK,EAAE,CAAC;YACxC,0EAA0E;aACzE,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;QAC5I,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,qCAAqC,CAAC,EAAE,YAAY,CAAC,gBAAgB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC;IACrI,CAAC,CAAC,CAAC;AACL,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,iBAAiB,CAAC,IAAU,EAAE,UAAkB;IAC9D,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,UAAU,EAAE,EAAE;QAQlC,MAAM,GAAG,GAAI,UAA0C,CAAC,QAAQ,CAAC;QACjE,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,6BAA6B,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;YACrF,MAAM,EAAE,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,mCAAmC,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5H,IAAI,CAAC,EAAE;gBAAE,OAAO,EAAE,CAAC;YACnB,MAAM,IAAI,GAAG,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,6CAA6C,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACnJ,MAAM,IAAI,GAAG,GAAG,CAAC,aAAa,CAAC,gCAAgC,CAAC,EAAE,YAAY,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;YACnG,MAAM,MAAM,GAAG,GAAG,CAAC,aAAa,CAAC,yCAAyC,CAAC,EAAE,KAAK,CAAC;YACnF,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,0CAA0C,CAAC,EAAE,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAC1G,OAAO,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;QAC1G,CAAC,CAAC,CAAC;IACL,CAAC,EAAE,UAAU,CAAC,CAAC;AACjB,CAAC;AAED,iGAAiG;AACjG,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AAChD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE9C;;;;GAIG;AACH,KAAK,UAAU,SAAS,CAAC,OAAuB,EAAE,OAAe,EAAE,QAAgB;IACjF,MAAM,GAAG,GAAG,GAAG,OAAO,IAAI,QAAQ,EAAE,CAAC;IACrC,IAAI,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,6BAA6B,QAAQ,EAAE,CAAC,CAAC;QAC3F,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,MAAM,SAAS,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC;QACvD,CAAC;gBAAS,CAAC;YACT,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,MAAM;YAAE,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,iBAAiB,CAAC,YAAY,QAAQ,IAAI,MAAM,CAAC,CAAC,CAAC,QAAQ,MAAM,SAAS,CAAC,CAAC,CAAC,4CAA4C,2EAA2E,CAAC,CAAC;IAClN,CAAC;AACH,CAAC;AAED,4FAA4F;AAC5F,MAAM,QAAQ,GAAG,IAAI,CAAC;AAEtB,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAuB,EAAE,OAAe,EAAE,QAAgB;IACxF,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,0BAA0B,QAAQ,EAAE,CAAC,CAAC;IACxF,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,6CAA6C,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;YACtF,MAAM,IAAI,iBAAiB,CAAC,YAAY,QAAQ,uFAAuF,CAAC,CAAC;QAC3I,CAAC;QACD,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;QAC7D,MAAM,KAAK,GAAmB,EAAE,CAAC;QACjC,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;YAClC,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,0BAA0B,QAAQ,QAAQ,QAAQ,CAAC,EAAE,IAAI,SAAS,aAAa,QAAQ,EAAE,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC,CAAC;YACrK,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC9D,CAAC;QACD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC1C,CAAC;YAAS,CAAC;QACT,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;AACH,CAAC;AAED,uGAAuG;AACvG,KAAK,UAAU,cAAc,CAAC,IAAU,EAAE,UAA8B;IACtE,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC/C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CACtC,KAAK,CAAC,IAAI,CAAE,UAAqG,CAAC,QAAQ,CAAC,gBAAgB,CAAC,2CAA2C,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAC9M,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IACzE,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,iBAAiB,CAAC,4BAA4B,UAAU,wCAAwC,CAAC,CAAC;IACxH,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gFAAgF;AAChF,KAAK,UAAU,YAAY,CAAC,IAAU;IACpC,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;QAMxB,MAAM,GAAG,GAAI,UAA0C,CAAC,QAAQ,CAAC;QACjE,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,8GAA8G,CAAC,CAAC;aACpJ,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;YACf,qFAAqF;YACrF,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACrC,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,kDAAkD,CAAC,CAAC;gBAAE,KAAK,CAAC,MAAM,EAAE,CAAC;YAC1H,OAAO,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9D,CAAC,CAAC;aACD,MAAM,CAAC,OAAO,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAuB,EACvB,OAAe,EACf,QAAgB,EAChB,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAiF;IAEjH,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;QAAE,MAAM,IAAI,iBAAiB,CAAC,0DAA0D,CAAC,CAAC;IAC3I,IAAI,IAAI;QAAE,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACjG,wDAAwD;IACxD,MAAM,GAAG,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAClG,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,IAAK,CAAC;IACnG,IAAI,GAAG;QAAE,MAAM,SAAS,CAAC,MAAM,EAAE,IAAK,EAAE,MAAM,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,iDAAiD,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAClI,IAAI,KAAK,YAAY,gBAAgB;YAAE,MAAM,KAAK,CAAC;QACnD,MAAM,IAAI,iBAAiB,CAAC,YAAY,QAAQ,4CAA4C,CAAC,CAAC;IAChG,CAAC,CAAC,CAAC;IACH,IAAI,CAAC;QACH,MAAM,aAAa,CAAC,IAAI,EAAE,CAAC,MAAM,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;QACzE,MAAM,MAAM,GAA+B,EAAE,MAAM,EAAE,CAAC;QACtD,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACxD,2DAA2D;QAC3D,IAAI,QAAQ;YAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9F,MAAM,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC9B,MAAM,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QACvC,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,iBAAiB,CAAC,uCAAuC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACpH,CAAC;YAAS,CAAC;QACT,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC1C,IAAI,GAAG;YAAE,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACzG,OAAO,EAAE,OAAO,EAAE,YAAY,OAAO,CAAC,MAAM,YAAY,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,cAAc,QAAQ,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AACzI,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,OAAO,CAAU,CAAC;AAkBzG,gGAAgG;AAChG,KAAK,UAAU,eAAe,CAAC,IAAU,EAAE,KAAa,EAAE,QAAgB;IACxE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CACjC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAE,UAAqG,CAAC,QAAQ,CAAC,gBAAgB,CAAC,gBAAgB,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAC7M,KAAK,CACN,CAAC;IACF,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC;AACvJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAuB,EAAE,OAAe,EAAE,QAAgB,EAAE,KAAoB;IACnH,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,iBAAiB,CAAC,iBAAiB,KAAK,CAAC,IAAI,4BAA4B,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAC;IACrM,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;IACpC,IAAI,CAAC,aAAa,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,iBAAiB,CAAC,KAAK,KAAK,CAAC,IAAI,0BAA0B,CAAC,CAAC;IACrK,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,MAAM,IAAI,iBAAiB,CAAC,yDAAyD,CAAC,CAAC;IACtJ,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IACnE,iGAAiG;IACjG,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAC1E,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,gDAAgD,QAAQ,aAAa,QAAQ,UAAU,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC1K,IAAI,KAAK,YAAY,gBAAgB;YAAE,MAAM,KAAK,CAAC;QACnD,MAAM,IAAI,iBAAiB,CAAC,YAAY,QAAQ,qDAAqD,QAAQ,eAAe,CAAC,CAAC;IAChI,CAAC,CAAC,CAAC;IACH,IAAI,CAAC;QACH,mFAAmF;QACnF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,MAAM,SAAS,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/G,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC,CAAC,CAAC;QAC/H,CAAC;QACD,MAAM,MAAM,GAA+B,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,oBAAoB,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QAClL,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAC5D,IAAI,MAAM;YAAE,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC;QACrC,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW;YAAE,MAAM,CAAC,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7E,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa;YAAE,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3G,KAAK,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;YAC5C,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;YAC3F,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,MAAM,eAAe,CAAC,IAAI,EAAE,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC1F,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS;gBAAE,MAAM,CAAC,YAAY,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC;YACpF,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;gBAAE,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC;QACnF,CAAC;QACD,MAAM,SAAS,CAAC,IAAI,EAAE,EAAE,GAAG,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QACtD,MAAM,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QACvC,iEAAiE;QACjE,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,SAAS,CAAC;QACpF,OAAO,EAAE,OAAO,EAAE,WAAW,KAAK,CAAC,IAAI,YAAY,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,CAAC,IAAI,aAAa,QAAQ,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IACjI,CAAC;YAAS,CAAC;QACT,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;AACH,CAAC"}

package/dist/moodle/quiz.d.ts

@@ -0,0 +1,117 @@
+import type { BrowserContext, Page } from "playwright-core";
+import type { Trail } from "../options.js";
+/** The quiz or attempt isn't there, or the person can't do what was asked. */
+export declare class QuizError extends Error {
+    name: string;
+}
+/** A label and value as Moodle shows them (site language). */
+export interface Detail {
+    label: string;
+    value: string;
+}
+/** What the quiz's page says: its info lines, dates, the person's attempts, whether they can start one. */
+export interface QuizInfo {
+    intro: string;
+    info: string[];
+    dates: Detail[];
+    feedback?: string;
+    attempts: {
+        attemptId: number;
+        inProgress: boolean;
+        details: Detail[];
+    }[];
+    canStart: boolean;
+    messages: string[];
+}
+/** One input of a question, by its form name, with its options and current value. */
+export interface QuestionField {
+    name: string;
+    kind: "choice" | "checkbox" | "text" | "select";
+    label?: string;
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    value?: string;
+}
+/** A question as the attempt or review page shows it. */
+export interface Question {
+    slot: number;
+    page?: number;
+    number?: string;
+    type: string;
+    state: string;
+    mark?: string;
+    text: string;
+    images: string[];
+    fields: QuestionField[];
+    feedback?: string;
+    rightAnswer?: string;
+}
+export declare function readQuizView(page: Page): Promise<QuizInfo>;
+/** The questions on an attempt or review page, with their fields read from the form. */
+export declare function readQuestions(page: Page): Promise<Question[]>;
+/** The pages of an attempt, from its navigation: slot → page. */
+export declare function readNavigation(page: Page): Promise<Record<number, number>>;
+export declare function quizInfo(context: BrowserContext, siteUrl: string, quizId: number): Promise<QuizInfo>;
+/** Starts an attempt, or continues the one in progress, as the quiz page's button does; returns its id. */
+export declare function startAttempt(context: BrowserContext, siteUrl: string, quizId: number): Promise<number>;
+/** Every question of an attempt, page by page, with the page each is on. */
+export declare function readAttempt(context: BrowserContext, siteUrl: string, attemptId: number): Promise<Question[]>;
+/**
+ * Saves answers page by page, as the attempt's "next" button does; `beforeSave` runs with each
+ * page's questions (the realistic trail's reading pause). Throws, saving nothing more, on a field
+ * a page doesn't have.
+ */
+export declare function saveAnswers(context: BrowserContext, siteUrl: string, attemptId: number, answers: {
+    slot: number;
+    responses: Record<string, string>;
+}[], beforeSave?: (questions: Question[]) => Promise<void>): Promise<void>;
+/** Submits the attempt for grading, as "Submit all and finish" does, without its confirm dialog. */
+export declare function finishAttempt(context: BrowserContext, siteUrl: string, attemptId: number): Promise<void>;
+/** A finished attempt's review, as far as the quiz's review options let the person see it. */
+export declare function readReview(context: BrowserContext, siteUrl: string, attemptId: number): Promise<{
+    summary: Detail[];
+    questions: Question[];
+}>;
+/** Starts an attempt, or continues the one in progress, and gives its questions. */
+export declare function startQuizAttempt(context: BrowserContext, siteUrl: string, quizId: number): Promise<{
+    attemptId: number;
+    questions: Question[];
+}>;
+/**
+ * Saves answers in an attempt in progress without finishing it, and gives its questions afterwards.
+ * With the realistic trail, it first takes the time a reader needs for the questions and their
+ * options (ADR-005), calling `onProgress` with the seconds elapsed and the total.
+ */
+export declare function answerQuizQuestions(context: BrowserContext, siteUrl: string, attemptId: number, answers: {
+    slot: number;
+    responses: Record<string, string>;
+}[], { trail, onProgress }?: {
+    trail?: Trail;
+    onProgress?: (elapsed: number, total: number) => void;
+}): Promise<{
+    attemptId: number;
+    questions: Question[];
+}>;
+/** Submits an attempt for grading, and gives its review when the quiz shows it. */
+export declare function finishQuizAttempt(context: BrowserContext, siteUrl: string, attemptId: number): Promise<{
+    attemptId: number;
+    finished: true;
+    review: {
+        summary: Detail[];
+        questions: Question[];
+    } | undefined;
+}>;
+/**
+ * Sets a user override on a quiz, through its override form: other opening and closing dates, a time
+ * limit in minutes, or a number of attempts (0 unlimited); what isn't given stays the quiz's.
+ */
+export declare function setQuizOverride(context: BrowserContext, siteUrl: string, quizId: number, userId: number, { open, close, timeLimitMinutes, attempts }: {
+    open?: Date;
+    close?: Date;
+    timeLimitMinutes?: number;
+    attempts?: number;
+}): Promise<{
+    changed: string;
+}>;