@wilm-ai/wilma-client 1.6.0 → 1.7.0

package/dist/parsers/recipients.js

@@ -0,0 +1,170 @@
+/*
+ * Who a parent can write to, and the child's class and supervisors.
+ *
+ * Seen 2026-10-07 (Helsinki, Wilma 2.36):
+ * - the child's front page has a "Huollettavasi tiedot" panel of
+ *   `.margin-bottom-inline` blocks, each a `<strong>Label:</strong><br>` and
+ *   its value: the name, the class, the class teacher and other supervisors
+ *   (each followed by a message link `compose?r_teacher=<id>`), and links to
+ *   message all supervisors or all the child's teachers;
+ * - `/messages/recipients` lists recipients as `button.recipient-block` with
+ *   the compose page in `data-source`, grouped in panels (the child, the other
+ *   guardians, all own teachers; staff and teachers per school tab). Disabled
+ *   buttons (no data-source) can't be written to. "Omat opettajat" (own
+ *   teachers) one by one loads from the panel link's data-source.
+ */
+import * as cheerio from "cheerio";
+const clean = (text) => text.replace(/\s+/g, " ").trim();
+/** A compose link as a path on this Wilma, or null for anything else. */
+export function composePath(href, pageUrl) {
+    if (!href)
+        return null;
+    try {
+        const page = new URL(pageUrl);
+        const url = new URL(href, pageUrl);
+        if (url.origin !== page.origin || !/^(\/![^/]+)?\/messages\/compose$/.test(url.pathname))
+            return null;
+        return url.pathname + url.search;
+    }
+    catch {
+        return null;
+    }
+}
+/** What a compose link writes to, from its r_ parameters (a repeated or mixed one: several people). */
+export function recipientKind(path) {
+    const keys = [...new URL(path, "https://wilma.invalid").searchParams.keys()].filter((k) => k.startsWith("r_"));
+    if (keys.length > 1)
+        return "group";
+    switch (keys[0]) {
+        case "r_teacher":
+            return "teacher";
+        case "r_personnel":
+            return "staff";
+        case "r_student":
+            return "student";
+        case "r_guardian":
+            return "guardian";
+        case "r_ownteachers":
+        case "r_groupteachers":
+            return "group";
+        default:
+            return "other";
+    }
+}
+/** The child's class and supervisors from their front page (`/!<n>/`); empty fields when the panel isn't there. */
+export function parseStudentDetailsHtml(html, pageUrl) {
+    const $ = cheerio.load(html);
+    const details = { name: null, className: null, supervisors: [], messageGroups: [] };
+    // The panel whose blocks carry labels in <strong>, with a class or a supervisor's message link.
+    const panel = $(".panel-body")
+        .filter((_, p) => $(p).find(".margin-bottom-inline > strong").length > 0)
+        .filter((_, p) => /luokka|klass|class/i.test($(p).find(".margin-bottom-inline > strong").text()) || $(p).find("a[href*='r_teacher']").length > 0)
+        .first();
+    if (!panel.length)
+        return details;
+    const group = clean(panel.children("h1, h2").first().text());
+    panel.find(".margin-bottom-inline").each((_, block) => {
+        const label = clean($(block).children("strong").first().text()).replace(/:$/, "");
+        if (!label)
+            return;
+        const entries = blockEntries($, block, pageUrl);
+        if (/^(nimi|namn|name)$/i.test(label))
+            details.name = entries[0]?.text ?? null;
+        else if (/^(luokka|klass|class)$/i.test(label))
+            details.className = entries[0]?.text ?? null;
+        else if (entries.some((e) => e.link) || /ohjaaja|valvoja|handledare|föreståndare|supervisor|teacher|tutor/i.test(label)) {
+            for (const entry of entries) {
+                const recipient = entry.link ? { name: entry.text, group, school: null, kind: recipientKind(entry.link), composePath: entry.link } : null;
+                details.supervisors.push({ name: entry.text, role: label, recipient });
+            }
+        }
+    });
+    panel.find("a.show-text[href], .margin-top a[href], .margin-top-inline a[href]").each((_, a) => {
+        const path = composePath($(a).attr("href"), pageUrl);
+        if (!path || details.messageGroups.some((g) => g.composePath === path))
+            return;
+        const name = clean($(a).text()) || clean($(a).attr("title") ?? "");
+        details.messageGroups.push({ name, group, school: null, kind: recipientKind(path), composePath: path });
+    });
+    return details;
+}
+/** A block's values: text up to each <br>, with the message link that follows a name. */
+function blockEntries($, block, pageUrl) {
+    const entries = [];
+    let text = "";
+    let link = null;
+    const flush = () => {
+        const value = clean(text);
+        if (value)
+            entries.push({ text: value, link });
+        text = "";
+        link = null;
+    };
+    $(block)
+        .contents()
+        .each((_, node) => {
+        if (node.type === "text") {
+            text += node.data;
+            return;
+        }
+        const el = $(node);
+        const tag = node.tagName?.toLowerCase();
+        if (tag === "strong")
+            return;
+        if (tag === "br")
+            return flush();
+        const href = el.is("a") ? el.attr("href") : el.find("a[href]").first().attr("href");
+        const path = composePath(href, pageUrl);
+        if (path)
+            link = path;
+        else
+            text += el.text();
+    });
+    flush();
+    return entries;
+}
+/**
+ * The recipients page (`/messages/recipients`), or a list it loads (own
+ * teachers). Only recipients Wilma lets the parent write to are returned.
+ */
+export function parseRecipientsHtml(html, pageUrl, defaults = {}) {
+    const $ = cheerio.load(html);
+    const tabNames = new Map();
+    $("a[href^='#'][data-toggle='tab'], .nav-tabs a[href^='#'], ul.nav a[href^='#']").each((_, a) => {
+        tabNames.set(($(a).attr("href") ?? "").slice(1), clean($(a).text()));
+    });
+    const out = [];
+    $(".recipient-block").each((_, button) => {
+        const el = $(button);
+        if (el.attr("disabled") !== undefined)
+            return;
+        const path = composePath(el.attr("data-source"), pageUrl);
+        if (!path || out.some((r) => r.composePath === path))
+            return;
+        const panel = el.closest(".panel");
+        const group = clean(panel.find(".panel-title").first().text()) || defaults.group || "";
+        const tab = el.closest(".tab-pane").attr("id");
+        const school = tab && tabNames.has(tab) && !/common/i.test(tab) ? tabNames.get(tab) : null;
+        out.push({ name: clean(el.text()), group, school, kind: recipientKind(path), composePath: path });
+    });
+    return out;
+}
+/** Lists the recipients page loads on demand (own teachers one by one): [panel title, path]. */
+export function recipientListSources(html, pageUrl) {
+    const $ = cheerio.load(html);
+    const page = new URL(pageUrl);
+    return $("a.disclosure[data-source]")
+        .map((_, a) => {
+        try {
+            const url = new URL($(a).attr("data-source"), pageUrl);
+            if (url.origin !== page.origin || !/\/messages\/recipients\//.test(url.pathname))
+                return null;
+            return [[clean($(a).text()), url.pathname + url.search]];
+        }
+        catch {
+            return null;
+        }
+    })
+        .get()
+        .filter(Boolean);
+}

package/dist/parsers/schedule.js

@@ -98,7 +98,12 @@ export function parseTimetableJson(payload) {
             if (!/^\d{4}-\d{2}-\d{2}$/.test(date))
                 continue;
             for (const module of lesson.modules ?? []) {
-                const subject = (module.caption ?? "").trim();
+                // The caption is the course code, sometimes followed by the name
+                // ("BI_ Biologia", or just "yRUB1.1" in upper secondary schools); the
+                // name alone is in courseName. Lessons without a course (lunch, a
+                // class teacher's hour) have only a caption.
+                const caption = (module.caption ?? "").trim();
+                const subject = (module.courseName ?? "").trim() || caption;
                 const teachers = module.teachers ?? [];
                 const rooms = (module.rooms ?? []).map((room) => (room.abbreviation ?? room.caption ?? "").trim()).filter(Boolean);
                 lessons.push({
@@ -107,7 +112,7 @@ export function parseTimetableJson(payload) {
                     start,
                     end,
                     subject,
-                    subjectCode: firstSubjectToken(subject),
+                    subjectCode: firstSubjectToken(caption),
                     teacher: teachers.map((t) => [t.lastname, t.firstname].filter(Boolean).join(" ")).join(", "),
                     teacherCode: teachers.map((t) => t.abbreviation ?? "").filter(Boolean).join(", "),
                     groupId: Number(module.id) || 0,

package/dist/parsers/students.js

@@ -53,15 +53,21 @@ function roleName(rec, fallback) {
     }
     return fallback;
 }
-function collectStudent(students, studentNumber, name) {
+function collectStudent(students, studentNumber, name, role) {
     if (!students.has(studentNumber)) {
         students.set(studentNumber, {
             studentNumber,
             name,
             href: `/!${studentNumber}/`,
+            ...(role ? { role } : {}),
         });
     }
 }
+/** A guardian's role for a child, or a student's own login; anything else unknown. */
+function studentRole(type) {
+    const value = typeof type === "string" ? type.toLowerCase() : "";
+    return value === "guardian" ? "guardian" : value === "student" ? "student" : undefined;
+}
 /**
  * Parse GET /api/v1/accounts/me/roles.
  * Accepts `{ payload: AccountRole[] }` or a raw array.
@@ -98,7 +104,7 @@ export function parseStudentsFromAccountsRoles(data) {
         if (!name) {
             continue;
         }
-        collectStudent(students, studentNumber, name);
+        collectStudent(students, studentNumber, name, studentRole(roleType(rec)));
     }
     return [...students.values()];
 }

package/dist/session.d.ts

@@ -1,4 +1,42 @@
-import { type RequestInit, type Response } from "undici";
+import { type WilmaTransport } from "./transport.js";
+/** What a request may carry (a subset of fetch's RequestInit that every transport can send). */
+export interface RequestInit {
+    method?: string;
+    headers?: Record<string, string | undefined> | Headers | [string, string][];
+    body?: string;
+    redirect?: "follow" | "manual";
+    signal?: AbortSignal;
+}
+export interface SessionOptions {
+    studentNumber?: string | null;
+    debug?: boolean;
+    /** How requests are sent (default: the transport set by the entry point; undici on Node). */
+    transport?: WilmaTransport;
+    /**
+     * Log in again by itself when Wilma ends the session (default true, with
+     * the credentials of the last login). Set false where a background login
+     * would be unwelcome — every login ends the parent's other Wilma sessions:
+     * requests then fail with SessionEndedError and the caller decides.
+     */
+    relogin?: boolean;
+    /** Where the WilmAI programs on one computer keep this login's session (see SharedSession). */
+    shared?: SharedSession;
+}
+/**
+ * The session of one Wilma login, kept where every WilmAI program on the
+ * computer finds it (the CLI, assistants' connectors, the desktop app).
+ * Wilma allows one live session per account, so programs that each log in
+ * keep ending each other's sessions. With a shared session, a client whose
+ * session Wilma ended first continues the newest one another program saved,
+ * and logs in only when that one has ended too; after its own login it saves
+ * the session for the others.
+ */
+export interface SharedSession {
+    /** The newest saved session (exportState() format), or null. */
+    load(): Promise<string | null>;
+    /** Save this client's session (after it logged in). */
+    save(state: string): Promise<void>;
+}
 export declare class AuthenticationError extends Error {
     constructor(message: string);
 }
@@ -10,26 +48,45 @@ export declare class APIError extends Error {
     status: number;
     constructor(message: string, status: number);
 }
+/**
+ * Wilma ended the session (another login on the account, or it expired) and
+ * this client doesn't log in again by itself (no saved credentials, or
+ * `relogin: false`). Nothing was sent; log in again and retry.
+ */
+export declare class SessionEndedError extends APIError {
+    constructor(message?: string);
+}
+/**
+ * What happened to a client's session, for a host that shows it (e.g. a
+ * sign-in history): "login" (this client logged in), "adopted" (Wilma had
+ * ended its session and it continued the one another WilmAI program saved),
+ * "ended" (Wilma ended it and the client may not, or could not, get a live
+ * one back by itself).
+ */
+export type SessionEvent = "login" | "adopted" | "ended";
 export declare class WilmaSession {
     private baseUrl;
     private auth;
     private studentNumber?;
     private debug;
-    constructor(baseUrl: string, opts?: {
-        studentNumber?: string | null;
-        debug?: boolean;
-    });
+    constructor(baseUrl: string, opts?: SessionOptions);
+    /** The address of this Wilma, e.g. "https://example.inschool.fi". */
+    get origin(): string;
     /** The login's cookies, so another process can resume the session (see resumeState). */
     exportState(): string;
     /**
      * Continue a session saved by exportState() instead of logging in. If Wilma
      * has ended it meanwhile, the first request notices (401/403 or the login
-     * page) and logs in again with these credentials. Returns false when the
-     * state holds no session to resume.
+     * page) and logs in again with these credentials; without credentials it
+     * fails with SessionEndedError. Returns false when the state holds no
+     * session to resume.
      */
-    resumeState(state: string, username: string, password: string): boolean;
+    resumeState(state: string, username?: string, password?: string): boolean;
     /** Called after every successful login (first or again). */
+    /** Share this login's session with the other WilmAI programs (see SharedSession). */
+    setShared(shared: SharedSession | undefined): void;
     onLogin(callback: (() => void) | undefined): void;
+    onSessionEvent(callback: ((event: SessionEvent) => void) | undefined): void;
     /** Used to answer the two-step verification challenge when the session has to log in again. */
     setMfaCallback(onMfa?: (formkey: string) => Promise<string>): void;
     /**
@@ -42,6 +99,18 @@ export declare class WilmaSession {
     getPrefixedPath(path: string): string;
     login(username: string, password: string): Promise<void>;
     submitMfaCode(formkey: string, otpCode: string): Promise<void>;
+    /**
+     * End this login's session in Wilma, as its "Log out" button does: the
+     * logout form on the front page posts its formkey to /logout. Never logs
+     * in; a session Wilma has already ended needs nothing. The session is
+     * shared with every per-student session made from this one, and afterwards
+     * none of them logs in again by itself (call login() for a new session).
+     * Returns true when a live session was ended, false when there was none.
+     * If Wilma can't be reached, throws and keeps the session, so logging out
+     * can be tried again.
+     */
+    logout(): Promise<boolean>;
+    private endSession;
     private getLoginFormFields;
     /**
      * An authenticated request to this Wilma. Follows redirects within Wilma
@@ -69,13 +138,36 @@ export declare class WilmaSession {
      * waits for a fresh code.
      */
     answerMfa(formkey: string, onMfa: (formkey: string) => Promise<string>): Promise<void>;
-    /** Log in again, once for everyone sharing this login even if many requests notice at the same time. */
-    private relogin;
+    /**
+     * A live session after Wilma ended this one, once for everyone sharing this
+     * login even if many requests notice at the same time: the newest session
+     * another program saved (no login), else a login when this client may log
+     * in again. Without either, SessionEndedError.
+     */
+    private recover;
+    /** Continue the session another program saved, if it differs from ours and Wilma still accepts it. */
+    private adoptShared;
+    /** After a login: tell the host (onLogin) and save the session for the other programs. */
+    private loggedInNow;
+    /** Changes whenever the session behind this client changes (a login, or another program's session continued). */
+    get sessionMark(): number;
     get(path: string, init?: RequestInit, opts?: {
         externalRedirect?: "error" | "return";
         timeoutMs?: number;
     }): Promise<Response>;
     post(path: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Send a form that changes something in Wilma (a reply, a sign-up, an
+     * absence report): one POST, never repeated. Unlike request(), it doesn't
+     * log in again and retry when the session has ended — after a new login
+     * the form's key is stale, and a write must not be sent twice — it fails
+     * with SessionEndedError instead (nothing was sent; prepare the form
+     * again). Redirects within Wilma are followed; the answer is returned for
+     * the caller to check.
+     */
+    submit(path: string, form: URLSearchParams | Record<string, string> | [string, string][], opts?: {
+        headers?: Record<string, string>;
+    }): Promise<Response>;
     private getLoginToken;
     /**
      * One request to this Wilma, following redirects within Wilma hop by hop