@wilm-ai/wilma-client 1.6.1 → 1.7.1

package/dist/write.js

@@ -0,0 +1,427 @@
+/*
+ * @wilm-ai/wilma-client/write: changing things in Wilma (answering messages,
+ * writing to teachers, signing up for event invitations, reporting an
+ * absence). Experimental. A separate entry point, so read-only tools such as
+ * the wilma CLI and its MCP server don't carry it.
+ *
+ * Every write takes two steps, like Wilma's own pages. Prepare reads Wilma's
+ * form and changes nothing. Send posts that form once, as Wilma's page would:
+ * the fields Wilma filled in, plus what the parent wrote (as HTML where the
+ * page has an editor, as Wilma's message forms do). A send is never repeated, and never retried after a login: when
+ * Wilma has ended the session it fails with SessionEndedError and nothing was
+ * sent. A form prepared under one session is never posted under another
+ * (another program's session continued, or a new login): that also fails
+ * with SessionEndedError, and preparing again gives a form for the session
+ * now in use. Afterwards Wilma's answer is checked and, where Wilma shows it,
+ * the result is read back:
+ *  - WriteRefusedError: Wilma said no; nothing changed.
+ *  - WriteUnconfirmedError: the form reached Wilma but the result didn't
+ *    show; it may have gone through, so check Wilma before sending again.
+ *
+ * Writes are per child: pass client.forStudent(studentNumber).
+ */
+import * as cheerio from "cheerio";
+import { SessionEndedError } from "./session.js";
+import { sessionOf } from "./internal.js";
+import { pageErrors, pageFormkey, pageNotices, readForm, setField, wilmaPath } from "./parsers/forms.js";
+import { slotState } from "./parsers/invitations.js";
+import { composePath } from "./parsers/recipients.js";
+export { FormOutsideWilmaError } from "./parsers/forms.js";
+/** Wilma doesn't offer this here right now (no answer form, absence reports closed…). Nothing was sent. */
+export class NotOfferedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NotOfferedError";
+    }
+}
+/** Wilma turned the form down and said so. Nothing changed. */
+export class WriteRefusedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WriteRefusedError";
+    }
+}
+/** The form reached Wilma, but the result didn't show. It may have gone through: check Wilma before sending again. */
+export class WriteUnconfirmedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WriteUnconfirmedError";
+    }
+}
+/** Wilma's day numbers count days from 30 December 1899 (46302 = 7 October 2026). */
+export function wilmaDayToIso(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 30000 || n > 80000)
+        return null;
+    return new Date(Date.UTC(1899, 11, 30) + n * 86_400_000).toISOString().slice(0, 10);
+}
+export async function prepareAbsenceReport(client) {
+    const session = sessionFor(client);
+    const { $, url } = await page(session, "/attendance/report");
+    const el = $("form")
+        .filter((_, f) => /savereport/i.test($(f).attr("action") ?? ""))
+        .first();
+    if (!el.length)
+        throw new NotOfferedError("Wilma doesn't offer an absence report for this child right now.");
+    const form = readForm($, el, url);
+    const select = form.selects[0];
+    const reasons = (select?.options ?? [])
+        .filter((o) => o.value && o.value !== "0" && !/^-*$/.test(o.label))
+        .map(({ value, label }) => ({ value, label }));
+    if (!select || !reasons.length)
+        throw new NotOfferedError("Wilma's absence form has no reasons to choose from.");
+    const reportDate = form.fields.find(([name]) => /^reportdate$/i.test(name))?.[1];
+    const heading = $("h1, h2, h3, h4")
+        .map((_, h) => clean($(h).text()))
+        .get()
+        .find((t) => /poissaolon ajankohta|frånvarons tidpunkt|time of absence/i.test(t));
+    const guidance = $(".panel-body p, .alert, .info, .notification")
+        .map((_, p) => clean($(p).text()))
+        .get()
+        .find((t) => /ilmoit|anmäl|report/i.test(t)) ?? "";
+    const textField = el.find("input[type=text][name], textarea[name]").first().attr("name") ?? null;
+    return {
+        kind: "absence-report",
+        sessionMark: session.sessionMark,
+        date: reportDate ? wilmaDayToIso(reportDate) : null,
+        dateLabel: heading ? heading.replace(/^[^:]*:\s*/, "") : "",
+        reasons,
+        acceptsText: textField !== null,
+        guidance,
+        form,
+        reasonField: select.name,
+        textField,
+        noticesBefore: pageNotices($),
+    };
+}
+/** Report the absence (once). Returns Wilma's confirmation. */
+export async function sendAbsenceReport(client, prepared, input) {
+    const session = sessionFor(client);
+    if (prepared.kind !== "absence-report")
+        throw new TypeError("Expected a form from prepareAbsenceReport()");
+    if (!prepared.reasons.some((r) => r.value === input.reason))
+        throw new TypeError("Pick one of the form's reasons");
+    let fields = setField(prepared.form.fields, prepared.reasonField, input.reason);
+    if (prepared.textField)
+        fields = setField(fields, prepared.textField, input.text ?? "");
+    fields = withButton(fields, prepared.form, "savebtn");
+    sameSession(session, prepared);
+    const answer = await read(await session.submit(prepared.form.action, fields), "The report");
+    const refused = pageErrors(answer.$);
+    if (refused)
+        throw new WriteRefusedError(`Wilma didn't take the report: ${refused}`);
+    const notice = pageNotices(answer.$).find((n) => !prepared.noticesBefore.includes(n));
+    if (notice)
+        return { notice };
+    throw new WriteUnconfirmedError("Wilma didn't confirm the report. Check the child's lesson notes in Wilma before reporting again.");
+}
+export async function prepareReply(client, messageId) {
+    const session = sessionFor(client);
+    const { $, url } = await page(session, `/messages/${messageId}`);
+    const quick = $("form#quickreply-form").first();
+    if (quick.length && quick.attr("action")) {
+        const form = readForm($, quick, url);
+        sendButton(form, "quickbtn");
+        return { kind: "reply", sessionMark: session.sessionMark, messageId, mode: "discussion", subject: null, recipients: [], form, bodyField: form.textareas[0] ?? "bodytext" };
+    }
+    let href;
+    $("a[href]").each((_, a) => {
+        const candidate = $(a).attr("href") ?? "";
+        // "Vastaa viestin lähettäjälle" links to compose?replyid=<id>; its neighbour "Välitä" adds &forward.
+        if (href || candidate.startsWith("#") || /forward/i.test(candidate))
+            return;
+        if (/^\s*(vastaa|svara|reply)\b/i.test($(a).text()) || /compose.*(answer|reply|replyid)/i.test(candidate))
+            href = candidate;
+    });
+    if (!href)
+        throw new NotOfferedError("Wilma doesn't offer an answer to this message.");
+    const compose = await composeForm(session, wilmaPath(href, url));
+    return {
+        kind: "reply",
+        sessionMark: session.sessionMark,
+        messageId,
+        mode: "private",
+        subject: compose.subject,
+        recipients: compose.recipients,
+        form: compose.form,
+        bodyField: compose.bodyField,
+    };
+}
+/** Send the answer (once). */
+export async function sendReply(client, prepared, text) {
+    const session = sessionFor(client);
+    if (prepared.kind !== "reply")
+        throw new TypeError("Expected a form from prepareReply()");
+    if (!text.trim())
+        throw new TypeError("The answer is empty");
+    const before = await sentState(client, prepared.messageId);
+    const body = editorBody(prepared.form, text);
+    const fields = withButton(setField(prepared.form.fields, prepared.bodyField, body), prepared.form, prepared.mode === "discussion" ? "quickbtn" : "addsavebtn");
+    sameSession(session, prepared);
+    const answer = await read(await session.submit(prepared.form.action, fields), "The answer");
+    const refused = pageErrors(answer.$);
+    if (refused)
+        throw new WriteRefusedError(`Wilma didn't send the answer: ${refused}`);
+    if (await wasSent(client, before, { messageId: prepared.messageId, subject: prepared.subject, text }))
+        return;
+    throw new WriteUnconfirmedError("Wilma didn't show the answer as sent. Check the thread in Wilma before answering again.");
+}
+export async function prepareMessage(client, to) {
+    const session = sessionFor(client);
+    let path;
+    if ("composePath" in to) {
+        // A link Wilma gave, kept to its own compose page and this child.
+        const own = composePath(to.composePath, `${client.origin}/`);
+        if (!own || (own.startsWith("/!") && !own.startsWith(session.getPrefixedPath("/"))))
+            throw new TypeError("Not a compose link for this child");
+        path = own;
+    }
+    else {
+        const id = String(to.teacherId);
+        if (!/^\d+$/.test(id))
+            throw new TypeError("A teacher id is a number");
+        path = `/messages/compose?r_teacher=${id}`;
+    }
+    const compose = await composeForm(session, path);
+    if (!compose.subjectField)
+        throw new NotOfferedError("Wilma's message form has no subject field.");
+    return { kind: "message", sessionMark: session.sessionMark, recipients: compose.recipients, form: compose.form, subjectField: compose.subjectField, bodyField: compose.bodyField };
+}
+/** Send the message (once). */
+export async function sendMessage(client, prepared, input) {
+    const session = sessionFor(client);
+    if (prepared.kind !== "message")
+        throw new TypeError("Expected a form from prepareMessage()");
+    if (!input.subject.trim())
+        throw new TypeError("The subject is empty");
+    if (!input.text.trim())
+        throw new TypeError("The message is empty");
+    const before = await sentState(client, null);
+    let fields = setField(prepared.form.fields, prepared.subjectField, input.subject);
+    fields = withButton(setField(fields, prepared.bodyField, editorBody(prepared.form, input.text)), prepared.form, "addsavebtn");
+    sameSession(session, prepared);
+    const answer = await read(await session.submit(prepared.form.action, fields), "The message");
+    const refused = pageErrors(answer.$);
+    if (refused)
+        throw new WriteRefusedError(`Wilma didn't send the message: ${refused}`);
+    if (await wasSent(client, before, { messageId: null, subject: input.subject, text: input.text }))
+        return;
+    throw new WriteUnconfirmedError("Wilma didn't show the message as sent. Check sent messages in Wilma before sending again.");
+}
+// ---------------------------------------------------------------------------
+// Event invitations
+/**
+ * Sign up for an invitation's time slot, or cancel the sign-up. This is what
+ * Wilma's own page sends (appointments.js): POST `/messages/apply/` with the
+ * page's formkey, apptId (the slot), action, appliedpersons and kortti (the
+ * message), answered with JSON {resultmessage: {message, problem}}. Checks
+ * the slot's state first, like Wilma's page, and reads the invitation back
+ * afterwards. Opening the invitation marks it read, as in Wilma.
+ */
+export async function answerInvitation(client, messageId, slotId, action, opts = {}) {
+    const session = sessionFor(client);
+    const invitation = (await client.messages.get(messageId)).invitation;
+    if (!invitation)
+        throw new NotOfferedError("This message isn't an event invitation.");
+    const slot = invitation.slots.find((s) => s.id === slotId);
+    if (!slot)
+        throw new NotOfferedError("The invitation has no such time slot.");
+    const state = slotState(slot, new Date(), invitation);
+    if (action === "apply" && state !== "open")
+        throw new NotOfferedError(`Signing up isn't open for this time (${state}).`);
+    if (action === "cancel" && state !== "chosen")
+        throw new NotOfferedError(`This sign-up can't be cancelled (${state}).`);
+    const { $ } = await page(session, `/messages/${messageId}`);
+    const mark = session.sessionMark;
+    const formkey = pageFormkey($);
+    if (!formkey)
+        throw new NotOfferedError("Wilma's invitation page has no form key.");
+    const fields = [
+        ["formkey", formkey],
+        ["apptId", slotId],
+        ["action", action],
+        ["appliedpersons", String(opts.persons ?? 1)],
+        ["kortti", String(messageId)],
+    ];
+    sameSession(session, { sessionMark: mark });
+    const resp = await session.submit("/messages/apply/", fields, {
+        headers: { "X-Requested-With": "XMLHttpRequest", Accept: "application/json, text/javascript, */*; q=0.01" },
+    });
+    const answer = await read(resp, "The sign-up");
+    let result;
+    try {
+        result = JSON.parse(answer.html);
+    }
+    catch {
+        throw new WriteUnconfirmedError("Wilma's answer wasn't what its own page expects. Check the invitation in Wilma.");
+    }
+    const notice = typeof result.resultmessage?.message === "string" ? clean(result.resultmessage.message) : "";
+    if (result.resultmessage?.problem === "problem")
+        throw new WriteRefusedError(notice || "Wilma refused the change.");
+    const after = (await client.messages.get(messageId)).invitation;
+    const chosen = after?.slots.find((s) => s.id === slotId)?.selected;
+    if (!after || chosen !== (action === "apply")) {
+        throw new WriteUnconfirmedError("The invitation doesn't show the change yet. Check it in Wilma before trying again.");
+    }
+    return { notice, invitation: after };
+}
+/**
+ * Say the family won't attend ("En osallistu"), or take that back (`undo`).
+ * This is what Wilma's own page sends (appointments.js, dismissAppt): POST
+ * `/messages/apply` with the page's formkey, action "dismiss" (or
+ * "canceldismiss") and kortti (the message), no slot. Declining also cancels
+ * a sign-up that can still be cancelled, as Wilma's page warns. Reads the
+ * invitation back afterwards.
+ */
+export async function declineInvitation(client, messageId, opts = {}) {
+    const session = sessionFor(client);
+    const invitation = (await client.messages.get(messageId)).invitation;
+    if (!invitation)
+        throw new NotOfferedError("This message isn't an event invitation.");
+    if (!invitation.canDecline)
+        throw new NotOfferedError("Wilma doesn't offer \"won't attend\" for this invitation.");
+    if (opts.undo ? !invitation.declined : invitation.declined) {
+        throw new NotOfferedError(opts.undo ? "The family hasn't said it won't attend." : "The family has already said it won't attend.");
+    }
+    const { $ } = await page(session, `/messages/${messageId}`);
+    const mark = session.sessionMark;
+    const formkey = pageFormkey($);
+    if (!formkey)
+        throw new NotOfferedError("Wilma's invitation page has no form key.");
+    const fields = [
+        ["formkey", formkey],
+        ["action", opts.undo ? "canceldismiss" : "dismiss"],
+        ["kortti", String(messageId)],
+    ];
+    sameSession(session, { sessionMark: mark });
+    const resp = await session.submit("/messages/apply", fields, {
+        headers: { "X-Requested-With": "XMLHttpRequest", Accept: "application/json, text/javascript, */*; q=0.01" },
+    });
+    const answer = await read(resp, "The answer");
+    let result;
+    try {
+        result = JSON.parse(answer.html);
+    }
+    catch {
+        throw new WriteUnconfirmedError("Wilma's answer wasn't what its own page expects. Check the invitation in Wilma.");
+    }
+    const notice = typeof result.resultmessage?.message === "string" ? clean(result.resultmessage.message) : "";
+    if (result.resultmessage?.problem === "problem")
+        throw new WriteRefusedError(notice || "Wilma refused the change.");
+    const after = (await client.messages.get(messageId)).invitation;
+    if (!after || after.declined !== !opts.undo) {
+        throw new WriteUnconfirmedError("The invitation doesn't show the change yet. Check it in Wilma before trying again.");
+    }
+    return { notice, invitation: after };
+}
+// ---------------------------------------------------------------------------
+/** A form's key belongs to the session it was read in: refuse to post it under another one. */
+function sameSession(session, prepared) {
+    if (prepared.sessionMark !== undefined && prepared.sessionMark !== session.sessionMark) {
+        throw new SessionEndedError("The Wilma session changed after the form was prepared; nothing was sent. Prepare it again.");
+    }
+}
+function sessionFor(client) {
+    const session = sessionOf.get(client);
+    if (!session)
+        throw new TypeError("Expected a WilmaClient");
+    if (session.getPrefixedPath("/") === "/")
+        throw new TypeError("Writes are per child: pass client.forStudent(studentNumber)");
+    return session;
+}
+const clean = (text) => text.replace(/\s+/g, " ").trim();
+async function page(session, path) {
+    const resp = await session.get(path);
+    const html = await resp.text();
+    return { $: cheerio.load(html), url: resp.url };
+}
+/** Wilma's answer to a sent form. 5xx: it may have been saved before failing. */
+async function read(resp, what) {
+    const html = await resp.text();
+    if (resp.status >= 500) {
+        throw new WriteUnconfirmedError(`Wilma answered HTTP ${resp.status}. ${what} may or may not have gone through: check Wilma before trying again.`);
+    }
+    if (resp.status >= 400)
+        throw new WriteRefusedError(`Wilma answered HTTP ${resp.status}; nothing was changed.`);
+    return { $: cheerio.load(html), html, url: resp.url };
+}
+/** Wilma's compose form (new message or private answer): the form with a text area, never logout. */
+async function composeForm(session, path) {
+    const { $, url } = await page(session, path);
+    const el = $("form")
+        .filter((_, f) => !/logout/i.test($(f).attr("action") ?? "") && $(f).find("textarea[name]").length > 0)
+        .first();
+    if (!el.length)
+        throw new NotOfferedError("Wilma's message form wasn't where it usually is.");
+    const form = readForm($, el, url);
+    // A recipient Wilma filled in (r_teacher, r_groupteachers…): without one nothing would be delivered.
+    if (!form.fields.some(([name]) => /^[rs]_/.test(name))) {
+        throw new NotOfferedError("Wilma's message form has no recipient, so nothing would be delivered.");
+    }
+    sendButton(form, "addsavebtn");
+    const subjectField = form.fields.find(([name]) => /^subject$/i.test(name))?.[0] ?? null;
+    return {
+        form,
+        recipients: el
+            .find(".recipient-item")
+            .map((_, item) => clean($(item).children("span").first().text() || $(item).text()))
+            .get()
+            .filter(Boolean),
+        bodyField: form.textareas.find((name) => /body/i.test(name)) ?? form.textareas[0],
+        subjectField,
+        subject: subjectField ? (form.fields.find(([name]) => name === subjectField)?.[1] ?? null) : null,
+    };
+}
+/**
+ * The form's send button, by Wilma's name for it. Never another one: a form
+ * also has buttons that save a draft, cancel, or open the recipient picker.
+ */
+function sendButton(form, name) {
+    const button = form.buttons.find((b) => b.name === name);
+    if (!button)
+        throw new NotOfferedError("Wilma's form has no send button where it usually is; nothing was sent.");
+    return button;
+}
+function withButton(fields, form, name) {
+    const button = sendButton(form, name);
+    return [...fields, [button.name, button.value]];
+}
+/**
+ * What goes in the body field. Wilma's message forms say `wysiwyg=ckeditor`:
+ * its editor sends HTML, so plain text becomes paragraphs (blank lines) and
+ * line breaks, with <, > and & escaped. Other forms get the text as is.
+ */
+export function editorBody(form, text) {
+    const mode = form.fields.find(([name]) => name.toLowerCase() === "wysiwyg")?.[1] ?? "";
+    if (!mode || /^(0|false|no|plain|text)$/i.test(mode))
+        return text;
+    const escape = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+    return text
+        .replace(/\r\n?/g, "\n")
+        .trim()
+        .split(/\n\s*\n/)
+        .map((paragraph) => `<p>${escape(paragraph.trim()).replace(/\n/g, "<br />\n")}</p>`)
+        .join("\n");
+}
+/** What's sent so far: outbox ids, and the thread's answers when there is a thread. */
+async function sentState(client, messageId) {
+    const [outbox, thread] = await Promise.all([
+        outboxIds(client),
+        messageId === null ? null : client.messages.get(messageId),
+    ]);
+    return { outbox, replies: thread?.replies?.length ?? 0 };
+}
+async function outboxIds(client) {
+    return new Set((await client.messages.list("outbox")).map((m) => m.wilmaId));
+}
+/** Did it arrive: a new answer with this text in the thread, or a new message with this subject in sent messages? */
+async function wasSent(client, before, sent) {
+    const opening = clean(sent.text).slice(0, 40);
+    if (sent.messageId !== null) {
+        const replies = (await client.messages.get(sent.messageId)).replies ?? [];
+        if (replies.slice(before.replies).some((r) => clean(r.content).includes(opening)))
+            return true;
+    }
+    const outbox = await client.messages.list("outbox");
+    return outbox.some((m) => !before.outbox.has(m.wilmaId) && (!sent.subject || clean(m.subject) === clean(sent.subject)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wilm-ai/wilma-client",
-  "version": "1.6.1",
+  "version": "1.7.1",
   "description": "Unofficial client for Wilma, the Finnish school information system: login (with two-step verification), schedule, homework, exams, messages and news.",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "default": "./dist/core.js"
+    },
+    "./write": {
+      "types": "./dist/write.d.ts",
+      "default": "./dist/write.js"
     }
   },
   "files": [
@@ -31,14 +39,14 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "lint": "tsc -p tsconfig.json --noEmit",
-    "test": "pnpm run build && node test/login.mjs && node test/parser-attendance.mjs && node test/parser-messages.mjs && node test/parser-news.mjs && node test/parser-schedule.mjs && node test/parser-students.mjs && node test/client-students.mjs && node test/client-schedule.mjs && node test/client-attendance.mjs && node test/client-news-resources.mjs && node test/network-error.mjs && node test/audit.mjs && node test/real-pages.mjs && node test/client-features.mjs",
+    "test": "pnpm run build && node test/login.mjs && node test/logout.mjs && node test/core.mjs && node test/write.mjs && node test/parser-attendance.mjs && node test/parser-messages.mjs && node test/parser-news.mjs && node test/parser-schedule.mjs && node test/parser-students.mjs && node test/client-students.mjs && node test/client-schedule.mjs && node test/client-attendance.mjs && node test/client-news-resources.mjs && node test/network-error.mjs && node test/audit.mjs && node test/real-pages.mjs && node test/client-features.mjs",
     "test:live": "tsc -p tsconfig.json && node test/live.spec.mjs",
     "fixtures:anonymize": "node scripts/anonymize-fixture.mjs"
   },
   "dependencies": {
     "cheerio": "^1.0.0-rc.12",
     "tough-cookie": "^4.1.4",
-    "undici": "^6.27.0"
+    "undici": "^6.29.1"
   },
   "devDependencies": {
     "typescript": "^5.6.3",