@wilm-ai/wilma-client 1.8.0 → 1.10.0

package/README.md

@@ -50,6 +50,7 @@ Wilma allows one live session per account: a new login ends the previous one, an
 - **Log in once** and use `client.forStudent(number)` for each child; they share the login.
 - A session that Wilma ends (another login, or expiry) **logs in again by itself** on the next request — once, even when many requests notice at the same time, including the two-step verification step. A refused password stops further attempts, so a changed password can't lock the account.
 - To continue a session in another process, save `client.exportSession()` (treat it like the password) and later call `WilmaClient.resume(profile, saved, onMfa)`. `client.onLogin(callback)` tells you when a new session should be saved.
+- The password for `resume()` can be a function, e.g. one reading a keychain: `WilmaClient.resume({ baseUrl, username, password: () => readFromKeychain() }, saved)`. It's called only when Wilma has ended the session and a new login is needed, never while the saved one works, and once for many requests. If it fails, the request fails with `CredentialsUnavailableError` (with `reason` and `cause` from your error) and the next request tries again: unlike a password Wilma refuses, it never stops the client for good.
 - `client.logout()` ends the session, as Wilma's own Log out does, so the parent can use Wilma in the browser. It never logs in: a session Wilma has already ended needs nothing, and it returns `false`. Afterwards the client and its `forStudent()` clients don't log in again by themselves. If Wilma can't be reached it throws and keeps the session, so it can be tried again.
 
 ### Any JavaScript runtime

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type SharedSession, type SessionEvent } from "./session.js";
+import { type PasswordSource, type SharedSession, type SessionEvent } from "./session.js";
 import type { Exam, GradebookEntry, Invitation, InvitationListing, MessageRecipient, StudentDetails, LessonNote, LessonNoteSummary, Message, MessageFolder, NewsItem, NewsResource, OverviewData, PastExam, Printout, StudentInfo, UpcomingExam, WilmaProfile } from "./types.js";
 import type { WilmaTransport } from "./transport.js";
 export type MfaCallback = (formkey: string) => Promise<string>;
@@ -19,6 +19,10 @@ export interface ClientOptions {
      */
     sharedSession?: SharedSession;
 }
+/** A profile for WilmaClient.resume(): the password may be a function called only for a new login. */
+export type ResumeProfile = Omit<WilmaProfile, "password"> & {
+    password: PasswordSource;
+};
 export declare class WilmaClient {
     private session;
     private constructor();
@@ -27,8 +31,13 @@ export declare class WilmaClient {
      * A client on a session saved earlier with exportSession(), without logging
      * in. If Wilma has ended that session, the first request logs in again by
      * itself. Returns null when the saved state has no session.
+     *
+     * The password may be a function (e.g. reading a keychain): it is called
+     * only when Wilma needs a new login, never while the saved session works.
+     * If it fails, the request fails with CredentialsUnavailableError and the
+     * next request tries again.
      */
-    static resume(profile: WilmaProfile, state: string, onMfaRequired?: MfaCallback, options?: ClientOptions): WilmaClient | null;
+    static resume(profile: ResumeProfile, state: string, onMfaRequired?: MfaCallback, options?: ClientOptions): WilmaClient | null;
     /**
      * A client on a saved session without any credentials: it never logs in.
      * When Wilma ends the session, requests fail with SessionEndedError. For

package/dist/client.js

@@ -47,6 +47,11 @@ export class WilmaClient {
      * A client on a session saved earlier with exportSession(), without logging
      * in. If Wilma has ended that session, the first request logs in again by
      * itself. Returns null when the saved state has no session.
+     *
+     * The password may be a function (e.g. reading a keychain): it is called
+     * only when Wilma needs a new login, never while the saved session works.
+     * If it fails, the request fails with CredentialsUnavailableError and the
+     * next request tries again.
      */
     static resume(profile, state, onMfaRequired, options = {}) {
         const session = new WilmaSession(profile.baseUrl, {

package/dist/core.d.ts

@@ -1,8 +1,8 @@
 export type { Exam, ExamGrade, GradebookEntry, HomeworkItem, Invitation, InvitationListing, InvitationSlot, InvitationSlotState, MessageRecipient, StudentDetails, LessonNote, LessonNoteSummary, Message, MessageReply, MessageFolder, Municipality, NewsItem, NewsResource, NewsResourceAuthContext, OverviewData, PastExam, Printout, ScheduleLesson, TenantDiscoveryResponse, TenantInfo, UpcomingExam, WilmaProfile, StudentInfo, } from "./types.js";
 export { WilmaClient } from "./client.js";
-export type { MfaCallback, ClientOptions } from "./client.js";
-export { WilmaSession, AuthenticationError, MfaRequiredError, APIError, SessionEndedError } from "./session.js";
-export type { SessionOptions, RequestInit, SharedSession, SessionEvent } from "./session.js";
+export type { MfaCallback, ClientOptions, ResumeProfile } from "./client.js";
+export { WilmaSession, AuthenticationError, MfaRequiredError, APIError, SessionEndedError, CredentialsUnavailableError } from "./session.js";
+export type { SessionOptions, RequestInit, SharedSession, SessionEvent, PasswordSource } from "./session.js";
 export { setDefaultTransport } from "./transport.js";
 export type { WilmaTransport, WilmaRequest, WilmaReply } from "./transport.js";
 export { DOWNLOAD_TIMEOUT_MS, isHtmlResponse, setExternalFetcher } from "./downloads.js";

package/dist/core.js

@@ -1,5 +1,5 @@
 export { WilmaClient } from "./client.js";
-export { WilmaSession, AuthenticationError, MfaRequiredError, APIError, SessionEndedError } from "./session.js";
+export { WilmaSession, AuthenticationError, MfaRequiredError, APIError, SessionEndedError, CredentialsUnavailableError } from "./session.js";
 export { setDefaultTransport } from "./transport.js";
 export { DOWNLOAD_TIMEOUT_MS, isHtmlResponse, setExternalFetcher } from "./downloads.js";
 export { NetworkError, describeNetworkCode, extractCauseCode, wrapNetworkError } from "./network-error.js";

package/dist/parsers/forms.d.ts

@@ -23,6 +23,12 @@ export interface WilmaForm {
         }[];
     }[];
     textareas: string[];
+    /** The form's checkboxes, ticked or not (`fields` has only the ticked ones, as a browser sends them). */
+    checkboxes?: {
+        name: string;
+        value: string;
+        checked: boolean;
+    }[];
 }
 export declare class FormOutsideWilmaError extends Error {
     constructor();

package/dist/parsers/forms.js

@@ -18,6 +18,7 @@ export function readForm($, form, pageUrl) {
     const buttons = [];
     const selects = [];
     const textareas = [];
+    const checkboxes = [];
     form.find("input, select, textarea, button").each((_, el) => {
         const control = $(el);
         const name = control.attr("name");
@@ -50,14 +51,17 @@ export function readForm($, form, pageUrl) {
             buttons.push({ name, value, label: clean(control.text()) || value });
         }
         else if (type === "checkbox" || type === "radio") {
-            if (control.attr("checked") !== undefined)
+            const checked = control.attr("checked") !== undefined;
+            if (type === "checkbox")
+                checkboxes.push({ name, value: control.attr("value") ?? "on", checked });
+            if (checked)
                 fields.push([name, control.attr("value") ?? "on"]);
         }
         else if (type !== "file" && type !== "reset" && type !== "button") {
             fields.push([name, value]);
         }
     });
-    return { action: wilmaPath(form.attr("action") ?? "", pageUrl), fields, buttons, selects, textareas };
+    return { action: wilmaPath(form.attr("action") ?? "", pageUrl), fields, buttons, selects, textareas, checkboxes };
 }
 /** The form key on a page (Wilma's anti-forgery token), preferring one outside the logout form. */
 export function pageFormkey($) {

package/dist/parsers/recipients.d.ts

@@ -3,6 +3,12 @@ import type { MessageRecipient, StudentDetails } from "../types.js";
 export declare function composePath(href: string | undefined, pageUrl: string): string | null;
 /** What a compose link writes to, from its r_ parameters (a repeated or mixed one: several people). */
 export declare function recipientKind(path: string): MessageRecipient["kind"];
+/**
+ * One compose link to several recipients, made as Wilma's own "to all teachers" links are: every r_… parameter of
+ * theirs, each once, and for more than one person showrecipients=1&collatedreplies=1 (the recipients see who else
+ * got it and each other's replies, which the message form can still untick). The links must be one child's.
+ */
+export declare function composeToAll(paths: string[]): string;
 /** The child's class and supervisors from their front page (`/!<n>/`); empty fields when the panel isn't there. */
 export declare function parseStudentDetailsHtml(html: string, pageUrl: string): StudentDetails;
 /**

package/dist/parsers/recipients.js

@@ -51,6 +51,32 @@ export function recipientKind(path) {
             return "other";
     }
 }
+/**
+ * One compose link to several recipients, made as Wilma's own "to all teachers" links are: every r_… parameter of
+ * theirs, each once, and for more than one person showrecipients=1&collatedreplies=1 (the recipients see who else
+ * got it and each other's replies, which the message form can still untick). The links must be one child's.
+ */
+export function composeToAll(paths) {
+    if (!paths.length)
+        throw new TypeError("No recipients");
+    if (paths.length === 1)
+        return paths[0];
+    const urls = paths.map((p) => new URL(p, "https://wilma.invalid"));
+    if (urls.some((u) => u.pathname !== urls[0].pathname))
+        throw new TypeError("The recipients are another child's");
+    const params = [];
+    for (const u of urls) {
+        for (const [k, v] of u.searchParams)
+            if (k.startsWith("r_") && !params.some(([a, b]) => a === k && b === v))
+                params.push([k, v]);
+    }
+    const out = new URLSearchParams(params);
+    if (params.length > 1 || recipientKind(`?${out}`) === "group") {
+        out.set("showrecipients", "1");
+        out.set("collatedreplies", "1");
+    }
+    return `${urls[0].pathname}?${out}`;
+}
 /** 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);

package/dist/session.d.ts

@@ -56,6 +56,24 @@ export declare class APIError extends Error {
 export declare class SessionEndedError extends APIError {
     constructor(message?: string);
 }
+/**
+ * The password, or where to get it: a function called only when Wilma needs a
+ * new login (e.g. reading a keychain), not while a saved session works.
+ */
+export type PasswordSource = string | (() => Promise<string>);
+/**
+ * Wilma needed a new login and the password couldn't be had (the function
+ * given as the password failed: a keychain locked, declined or missing the
+ * entry). Not a refusal by Wilma, so it never stops the client for good;
+ * the next request tries again. `reason` and `cause` come from the failure.
+ */
+export declare class CredentialsUnavailableError extends Error {
+    reason: string;
+    constructor(message: string, options?: {
+        reason?: string;
+        cause?: unknown;
+    });
+}
 /**
  * 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
@@ -81,7 +99,7 @@ export declare class WilmaSession {
      * 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?: PasswordSource): 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;
@@ -138,6 +156,13 @@ export declare class WilmaSession {
      * waits for a fresh code.
      */
     answerMfa(formkey: string, onMfa: (formkey: string) => Promise<string>): Promise<void>;
+    /**
+     * The password for a new login. A function given as the password is called
+     * here, only now; its answer replaces it (as a login does). If it fails, the
+     * session is "ended by Wilma" (never "logged out", never failed for good)
+     * and the error is a CredentialsUnavailableError.
+     */
+    private resolvePassword;
     /**
      * 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

package/dist/session.js

@@ -35,6 +35,20 @@ export class SessionEndedError extends APIError {
         this.name = "SessionEndedError";
     }
 }
+/**
+ * Wilma needed a new login and the password couldn't be had (the function
+ * given as the password failed: a keychain locked, declined or missing the
+ * entry). Not a refusal by Wilma, so it never stops the client for good;
+ * the next request tries again. `reason` and `cause` come from the failure.
+ */
+export class CredentialsUnavailableError extends Error {
+    reason;
+    constructor(message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "CredentialsUnavailableError";
+        this.reason = options.reason ?? "unavailable";
+    }
+}
 /** How long Wilma may go silent (before answering, or mid-body) before a request fails. */
 const REQUEST_TIMEOUT_MS = 30_000;
 const MAX_REDIRECTS = 10;
@@ -268,6 +282,9 @@ export class WilmaSession {
         const ended = holdsSession(auth.cookieJar, this.baseUrl) ? await this.endSession() : false;
         auth.cookieJar.removeAllCookiesSync();
         auth.loggedIn = false;
+        // Logged out on purpose: not "ended by Wilma", so the next request neither
+        // logs in again nor continues a session another program saved.
+        auth.endedByWilma = false;
         auth.username = undefined;
         auth.password = undefined;
         return ended;
@@ -444,6 +461,36 @@ export class WilmaSession {
             }
         }
     }
+    /**
+     * The password for a new login. A function given as the password is called
+     * here, only now; its answer replaces it (as a login does). If it fails, the
+     * session is "ended by Wilma" (never "logged out", never failed for good)
+     * and the error is a CredentialsUnavailableError.
+     */
+    async resolvePassword() {
+        const auth = this.auth;
+        const source = auth.password;
+        if (typeof source !== "function")
+            return source ?? "";
+        try {
+            const password = await source();
+            if (typeof password !== "string" || !password)
+                throw new Error("No password was returned");
+            // logout() may have cleared it meanwhile: then it stays cleared.
+            if (auth.password === source)
+                auth.password = password;
+            return password;
+        }
+        catch (err) {
+            auth.loggedIn = false;
+            auth.endedByWilma = true;
+            auth.onEvent?.("ended");
+            if (err instanceof CredentialsUnavailableError)
+                throw err;
+            const reason = typeof err?.reason === "string" ? err.reason : undefined;
+            throw new CredentialsUnavailableError(err instanceof Error ? err.message : String(err), { reason, cause: err });
+        }
+    }
     /**
      * 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
@@ -462,6 +509,9 @@ export class WilmaSession {
                     auth.onEvent?.("ended");
                     throw new SessionEndedError();
                 }
+                // Get the password before changing anything: if it can't be had, the
+                // session stays "ended by Wilma" and the next request tries again.
+                const password = await this.resolvePassword();
                 auth.loggedIn = false;
                 // Start from a clean jar: a leftover session cookie must not make a
                 // failed login look successful.
@@ -469,7 +519,7 @@ export class WilmaSession {
                 if (this.debug)
                     console.error("[wilmai] session cancelled or expired; logging in again");
                 try {
-                    await this.login(auth.username, auth.password);
+                    await this.login(auth.username, password);
                 }
                 catch (err) {
                     if (err instanceof MfaRequiredError && auth.onMfa) {

package/dist/write.d.ts

@@ -1,5 +1,6 @@
 import type { WilmaClient } from "./client.js";
 import { type WilmaForm } from "./parsers/forms.js";
+export { composeToAll } from "./parsers/recipients.js";
 import type { Invitation, MessageRecipient } from "./types.js";
 export type { WilmaForm } from "./parsers/forms.js";
 export { FormOutsideWilmaError } from "./parsers/forms.js";
@@ -98,14 +99,23 @@ export interface MessageForm {
     readonly form: WilmaForm;
     readonly subjectField: string;
     readonly bodyField: string;
+    /**
+     * Whether the recipients see each other's replies (Wilma's CollatedReplies box, which makes the thread an open
+     * discussion), as Wilma's form has it; null when the form has no such box.
+     */
+    readonly collatedReplies?: boolean | null;
 }
 export declare function prepareMessage(client: WilmaClient, to: {
     teacherId: string | number;
 } | Pick<MessageRecipient, "composePath">): Promise<MessageForm>;
-/** Send the message (once). */
+/**
+ * Send the message (once). `collatedReplies` ticks or clears Wilma's "recipients see each other's replies" box
+ * when the form has one; left out, the box stays as Wilma's form has it.
+ */
 export declare function sendMessage(client: WilmaClient, prepared: MessageForm, input: {
     subject: string;
     text: string;
+    collatedReplies?: boolean;
 }): Promise<void>;
 /**
  * Sign up for an invitation's time slot, or cancel the sign-up. This is what

package/dist/write.js

@@ -26,6 +26,7 @@ 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 { composeToAll } 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 {
@@ -166,6 +167,7 @@ export async function sendReply(client, prepared, text) {
         return;
     throw new WriteUnconfirmedError("Wilma didn't show the answer as sent. Check the thread in Wilma before answering again.");
 }
+const COLLATED = "CollatedReplies";
 export async function prepareMessage(client, to) {
     const session = sessionFor(client);
     let path;
@@ -185,9 +187,21 @@ export async function prepareMessage(client, to) {
     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 };
+    const collated = compose.form.checkboxes?.find((c) => c.name === COLLATED);
+    return {
+        kind: "message",
+        sessionMark: session.sessionMark,
+        recipients: compose.recipients,
+        form: compose.form,
+        subjectField: compose.subjectField,
+        bodyField: compose.bodyField,
+        collatedReplies: collated ? collated.checked : null,
+    };
 }
-/** Send the message (once). */
+/**
+ * Send the message (once). `collatedReplies` ticks or clears Wilma's "recipients see each other's replies" box
+ * when the form has one; left out, the box stays as Wilma's form has it.
+ */
 export async function sendMessage(client, prepared, input) {
     const session = sessionFor(client);
     if (prepared.kind !== "message")
@@ -197,7 +211,12 @@ export async function sendMessage(client, prepared, input) {
     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);
+    let fields = prepared.form.fields;
+    const box = prepared.form.checkboxes?.find((c) => c.name === COLLATED);
+    if (box && input.collatedReplies !== undefined) {
+        fields = input.collatedReplies ? setField(fields, box.name, box.value) : fields.filter(([name]) => name !== box.name);
+    }
+    fields = setField(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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wilm-ai/wilma-client",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Unofficial client for Wilma, the Finnish school information system: login (with two-step verification), schedule, homework, exams, messages and news.",
   "license": "MIT",
   "repository": {
@@ -39,7 +39,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "lint": "tsc -p tsconfig.json --noEmit",
-    "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": "pnpm run build && node test/login.mjs && node test/logout.mjs && node test/password-source.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"
   },