v0.2.0

A release that settles the shape of the API before more programs depend on it. Most of it is breaking: read Breaking changes before upgrading.

New

• The Moodle object's defaults. createMoodle() takes trail, onProgress, loginTimeoutMs and downloadDir, so they aren't repeated on every call; any call can still give its own. logIn() needs no arguments (5 minutes by default).
• Surveys find their module. getSurvey(activityId) and submitSurvey(activityId, responses) work out whether it's a feedback or a questionnaire when not told ({ type } still accepted).
• submitForGrading(activityId, { acceptStatement }), an options object instead of a bare boolean (still accepted).
• MoodleDriverError. Every error the driver throws extends it and carries a stable code (not-logged-in, survey, form…, and generic ones: invalid-input, not-found, not-available, outside-site, unexpected-page, logout-failed, chromium-install-failed). Match errors by class, name or code, never by message.
• @falkenslab/moodle-driver/internals, a second entry point with the primitives the operations are built from: callService, readPageConfig, openSitePage, readSessionFacts, pageIsLoggedIn, moodleErrorMessage, openForm, formValue, setFields, submitForm, uploadToDraft, dateSelectorValues, dateSelectorDate, inPage, readTexts, readMedia, decodeEntities, readingSeconds, pause, editCourse, renameActivity, renameSection, courseState, activityDetails, readOwnProfile, readWwwroot, fileNameFor.
• moodle.readAttempt(attemptId), now a method too.

Breaking changes

The main entry is curated. It exports the Moodle object, the operations, their types and errors. The primitives moved to @falkenslab/moodle-driver/internals (list above): change the import. The areas' parsers and single steps are no longer exported at all: readQuizView, readQuestions, readNavigation, startAttempt, saveAnswers, finishAttempt, readQuizReport, readQuizSlots, assignmentIds, readAssignmentIds, listParticipants, participantDates, gradingPanelHtml, fillGradingForm, panelGrade, submitGradingForm, readSubmissionContent, readGradingDefinition, readStudentAssignment, listDiscussions, discussionPosts, forumInstanceId, readDiscussionRows, structureOf, assignmentsOf, toCourse, isoDate, overviewField, readFormFields, surveyType, readSurveyPage, readChoice, readLessonPage, readH5PAttempts, readGradeRows, readGraderReport, readGradebookSetup, readBankQuestions, readParticipantRows, readCompletionReport, waitForLogin, followPages, parseServiceResponse, courseFormat, and the raw types MoodleCourse, MoodleParticipant, MoodleParticipantDates, AssignmentIds, DiscussionRow, MoodlePost, MoodleUser. Use the operations (startQuizAttempt, assignmentSubmissions, forumDiscussions, courseStructure…) or the primitives instead.

Activity ids are activityId. Every parameter taking an activity's course module id is named activityId, whatever the module (it was cmid, forumCmid, bankCmid or quizId). Positional calls don't change; code reading the names (wrappers, docs) does.

Results name ids one way: a thing's own id is id, the ids it refers to are <thing>Id.

Was	Now
QuizSlot.slotId	id
quizInfo().attempts[].attemptId	id
QuizAttemptResult.attemptId	id
H5PAttempt.attemptId	id
GradeColumn.itemId	id (grades still refer to it as itemId)
QuestionBank.cmid	id
CourseChange.newId	activityId (duplicateActivity) or sectionId (addSection)
discussion().discussion.forumId (the instance id)	forumInstanceId

userById returns a User in the driver's terms (fullName, firstAccess and lastAccess as ISO 8601 dates, left out for never), no longer Moodle's raw record (fullname, Unix seconds).

Every write returns { changed, …state }:

Function	Was	Now
saveSubmission, submitForGrading	StudentAssignment	{ changed, assignment }
answerChoice	Choice	{ changed, choice }
submitSurvey	{ messages }	{ changed, messages }
startQuizAttempt, answerQuizQuestions, finishQuizAttempt, answerLessonPage	their objects	the same, with changed

Plain Errors are now MoodleDriverErrors with a code (relative paths, missing files, a forum without attachments, content for a module without it, a failed logout, a file outside the site…). instanceof Error still holds.

The session cookies file is moodle-driver-session.json (SESSION_COOKIES_FILE), no longer moodle-mcp-session-cookies.json. Profiles from before keep their persistent cookies but lose Moodle's session cookie: the person logs in once more.

The object is leaner: it no longer has the pieces the operations are built from (assignmentIds, gradingPanelHtml, startAttempt, courseState, editCourse and the like). It keeps callService, openSitePage and openForm.

Internal

• The source is one folder per Moodle area (src/areas/<area>/), with src/core/ for what they're built on and src/browser/ for the browser; the tests mirror it.
• ADR-010 records the curated entry and /internals; the conventions record the naming and result rules.

Documentation: https://falkenslab.github.io/moodle-driver/