@wilm-ai/wilma-client 1.6.1 → 1.7.0

package/README.md

@@ -1,6 +1,6 @@
 # @wilm-ai/wilma-client
 
-A TypeScript client for **Wilma**, the Finnish school information system, as a parent (guardian) sees it: schedule, homework, exams and grades, the gradebook, lesson notes and absences, messages with their replies, bulletins and their attachments, and printouts. Read-only.
+A TypeScript client for **Wilma**, the Finnish school information system, as a parent (guardian) sees it: schedule, homework, exams and grades, the gradebook, lesson notes and absences, messages with their replies, event invitations, bulletins and their attachments, and printouts. The main entry point only reads (and logs out); an experimental, separate entry point writes.
 
 It powers the [`wilma` CLI and MCP server](https://www.npmjs.com/package/@wilm-ai/wilma-cli) ([wilm.ai](https://wilm.ai)).
 
@@ -26,12 +26,16 @@ for (const student of await client.students()) {
   const kid = client.forStudent(student.studentNumber);
   const overview = await kid.overview.get();          // this week's lessons, homework, exams, exam grades
   const exams = await kid.exams.upcoming();           // with start times when the school gives one
+  const results = await kid.exams.past({ from: "2024-08-01" }); // past exams with grades and topics; default: this school year
   const lessons = await kid.schedule.list({ from: "2026-10-05", to: "2026-10-09" }); // teachers and rooms
   const notes = await kid.attendance.list({ from: "2026-09-01", to: "2026-09-30" });  // lesson notes, with the teacher's words
   const summary = await kid.attendance.summary();    // counts by kind for the school year
   const gradebook = await kid.gradebook.get();       // subject > syllabus > course, with grades and dates
   const messages = await kid.messages.list("inbox"); // unread and replyCount included
   const thread = await kid.messages.get(messages[0].wilmaId); // the message and its replies
+  const invitations = await kid.invitations.list();   // event invitations, with whether the family has answered
+  const details = await kid.student.get();            // class, class teacher and supervisors, with message links
+  const recipients = await kid.messages.recipients(); // who the parent can write to: own teachers, staff, the other guardian
   const news = await kid.news.list();                 // dated, pinned and older bulletins
   const printouts = await kid.printouts.list();       // PDFs such as report cards
 }
@@ -46,6 +50,26 @@ 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.
+- `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
+
+`@wilm-ai/wilma-client/core` is the same client without Node-only code, for a browser extension, a desktop app's web view or Node. It sends every request through a transport you give it: one function that makes a single HTTP exchange without following redirects and returns the status, headers, `Set-Cookie` values and body. Cookies, redirects and timeouts stay in the client.
+
+```ts
+import { WilmaClient, SessionEndedError } from "@wilm-ai/wilma-client/core";
+
+const client = await WilmaClient.login(profile, onMfa, { transport, relogin: false });
+const saved = client.exportSession();
+// Later, without keeping the password:
+const again = WilmaClient.resumeSession(profile.baseUrl, saved, { transport });
+```
+
+With `relogin: false` (and always with `resumeSession`), a session Wilma has ended isn't logged in again behind the parent's back: requests fail with `SessionEndedError`, and the app asks.
+
+### One session for every program on the computer
+
+Programs that each log in end each other's sessions (Wilma keeps one per account). Pass `sharedSession: { load, save }` (or call `client.useSharedSession(...)`) with a place they all use, such as the `wilma` CLI's session file: when Wilma ends a client's session, it first continues the newest session another program saved, and logs in only when that one has ended too; after its own login it saves the session for the others. `client.onSessionEvent(event => …)` tells an app what happened: `"login"`, `"adopted"` (another program's session continued) or `"ended"`. A form prepared under one session is never posted under another (see Writing). Downloading files that bulletins link to on other sites needs the main (Node) entry point, which can guard those requests.
 
 ### Times
 
@@ -61,6 +85,29 @@ JSON wherever Wilma has it: the account's roles, the front page (overview), mess
 - Files linked from bulletins are fetched without the Wilma login and only from public internet addresses (private, loopback and cloud-metadata addresses are refused, also after DNS resolution).
 - Requests and downloads fail after a while without progress instead of hanging.
 
+## Writing (experimental)
+
+`@wilm-ai/wilma-client/write` answers messages, writes to teachers, signs up for event invitations and reports absences. It's a separate entry point, so read-only tools such as the `wilma` CLI don't carry it.
+
+```ts
+import { prepareAbsenceReport, sendAbsenceReport } from "@wilm-ai/wilma-client/write";
+
+const kid = client.forStudent(studentNumber);          // writes are per child
+const form = await prepareAbsenceReport(kid);          // reads Wilma's form; changes nothing
+// form.date is the day Wilma will record (today until 12:00, then tomorrow); form.reasons are the school's.
+await sendAbsenceReport(kid, form, { reason: form.reasons[0].value, text: "Fever" });
+```
+
+- **Two steps, like Wilma's own pages.** `prepare…` reads Wilma's form; `send…` posts it once, as Wilma's page would: the fields Wilma filled in plus what the parent wrote (message bodies as HTML, since Wilma's message forms come with an editor). Also `prepareReply`/`sendReply` (an open discussion's quick reply, or a private answer to the sender), `prepareMessage`/`sendMessage` (to anyone from `messages.recipients()` or `student.get()`, or a teacher by id), and `answerInvitation(kid, messageId, slotId, "apply" | "cancel")`. Prepared forms say who a message goes to (`recipients`).
+- **Never sent twice.** A send isn't repeated, and never retried after a login: if Wilma has ended the session it fails with `SessionEndedError`, and nothing was sent.
+- **Checked afterwards.** Wilma's answer is checked, and the result read back where Wilma shows it (the thread, sent messages, the invitation). `WriteRefusedError`: Wilma said no and nothing changed. `WriteUnconfirmedError`: it may have gone through, so check Wilma before sending again. `NotOfferedError`: Wilma doesn't offer this here (no answer form, sign-up closed).
+
+The forms follow Wilma's pages as seen in October 2026, and the tests prepare them from anonymised copies of the real pages. A new message and an answer in an open discussion have been sent on the real Wilma (October 2026). A private answer, signing up for an invitation and an absence report have been tested against a simulated Wilma only, so how they're confirmed may still need adjusting after the first real use. "Won't attend" on invitations isn't supported.
+
+### Not covered
+
+Rarely used parts of Wilma stay there: applications and decisions (`/decisions`, e.g. leave from school), forms such as basic information and consents, surveys, assessment discussions, support plans, notification settings and course selection. Explaining absences ("Selvitä") waits until a real case shows its form. Students' own logins (Wilma for students, EDU) aren't supported; this is a guardian's client.
+
 ## License
 
 MIT

package/dist/client.d.ts

@@ -1,20 +1,61 @@
-import type { Exam, GradebookEntry, LessonNote, LessonNoteSummary, Message, MessageFolder, NewsItem, NewsResource, OverviewData, Printout, StudentInfo, UpcomingExam, WilmaProfile } from "./types.js";
-import type { Response } from "undici";
+import { 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>;
+export interface ClientOptions {
+    /** How requests are sent (default: undici on Node; required with the "core" entry point unless a default is set). */
+    transport?: WilmaTransport;
+    /**
+     * Log in again by itself when Wilma ends the session (default true). Every
+     * login ends the parent's other Wilma sessions (browser, phone), so an app
+     * the parent is looking at may prefer false: requests then fail with
+     * SessionEndedError and the app asks.
+     */
+    relogin?: boolean;
+    /**
+     * Share the session with the other WilmAI programs on this computer (the
+     * CLI, connectors, a desktop app) instead of each logging in and ending the
+     * others' sessions. See SharedSession.
+     */
+    sharedSession?: SharedSession;
+}
 export declare class WilmaClient {
     private session;
     private constructor();
-    static login(profile: WilmaProfile, onMfaRequired?: MfaCallback): Promise<WilmaClient>;
+    static login(profile: WilmaProfile, onMfaRequired?: MfaCallback, options?: ClientOptions): Promise<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.
      */
-    static resume(profile: WilmaProfile, state: string, onMfaRequired?: MfaCallback): WilmaClient | null;
+    static resume(profile: WilmaProfile, 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
+     * apps that don't keep the parent's password. Returns null when the saved
+     * state has no session.
+     */
+    static resumeSession(baseUrl: string, state: string, options?: Omit<ClientOptions, "relogin"> & {
+        debug?: boolean;
+    }): WilmaClient | null;
+    /** The Wilma this client talks to, e.g. "https://example.inschool.fi". */
+    get origin(): string;
     /** This login's session (cookies) as a string, for WilmaClient.resume() in a later process. Treat it like a password. */
     exportSession(): string;
+    /**
+     * End this login's session in Wilma (its "Log out"), e.g. so the parent can
+     * use Wilma in the browser. Never logs in. Afterwards this client and its
+     * forStudent() clients don't log in again by themselves. Returns true when
+     * a live session was ended, false when there was none; throws (keeping the
+     * session) when Wilma can't be reached.
+     */
+    logout(): Promise<boolean>;
+    /** Share the session with the other WilmAI programs on this computer from now on (see ClientOptions.sharedSession). */
+    useSharedSession(shared: SharedSession | undefined): void;
     /** Run a callback after every successful login, e.g. to save the new session. */
     onLogin(callback: (() => void) | undefined): void;
+    /** Be told when this client logs in, continues another program's session, or finds its session ended (see SessionEvent). */
+    onSessionEvent(callback: ((event: SessionEvent) => void) | undefined): void;
     static listStudents(profile: WilmaProfile, onMfaRequired?: MfaCallback): Promise<StudentInfo[]>;
     /**
      * A client for one of the account's students that reuses this client's
@@ -30,6 +71,26 @@ export declare class WilmaClient {
          * thread; older versions only have the HTML page, which is parsed instead.
          */
         get: (messageId: number) => Promise<Message>;
+        /**
+         * Who the parent can write to (Wilma's recipient list): the child, the
+         * other guardians, the child's own teachers, and the school's staff and
+         * teachers. Pass one to prepareMessage() in the write entry point.
+         */
+        recipients: () => Promise<MessageRecipient[]>;
+    };
+    student: {
+        /** The child's class and supervisors (class teacher, other supervisors), with their message links, from the front page. */
+        get: () => Promise<StudentDetails>;
+    };
+    invitations: {
+        /** Event invitations (Tapahtumakutsut), newest first, with whether this family has answered. */
+        list: () => Promise<InvitationListing[]>;
+        /**
+         * One invitation's time slots and this family's choice; null when the
+         * message isn't an invitation. Like opening it in Wilma, this marks the
+         * message read.
+         */
+        get: (messageId: number) => Promise<Invitation | null>;
     };
     news: {
         list: () => Promise<NewsItem[]>;
@@ -60,6 +121,15 @@ export declare class WilmaClient {
             start?: string;
             end?: string;
         }) => Promise<Exam[]>;
+        /**
+         * Past exams with their grades (Kokeet > Menneet), newest first. Wilma
+         * shows this school year by default; `from` (YYYY-MM-DD, to `to` or today)
+         * reaches further back, as far as the school keeps exams.
+         */
+        past: (opts?: {
+            from?: string;
+            to?: string;
+        }) => Promise<PastExam[]>;
     };
     attendance: {
         /**
@@ -72,6 +142,8 @@ export declare class WilmaClient {
             from?: string;
             to?: string;
         }) => Promise<LessonNote[]>;
+        /** Every lesson note of this school year (Wilma's own "whole year" view): one request. */
+        schoolYear: () => Promise<LessonNote[]>;
         /** How many lesson notes of each kind from `from` to `to` (default today); without `from`, this school year. */
         summary: (opts?: {
             from?: string;

package/dist/client.js

@@ -2,8 +2,10 @@ import { WilmaSession, MfaRequiredError, APIError } from "./session.js";
 import { parseWilmaTimestamp } from "./parsers/dates.js";
 import { finnishDateString } from "./finnish-time.js";
 import { parseMessagesList, parseMessageDetailHtml, parseMessageDetailJson } from "./parsers/messages.js";
+import { parseInvitationListings } from "./parsers/invitations.js";
+import { parseRecipientsHtml, parseStudentDetailsHtml, recipientListSources } from "./parsers/recipients.js";
 import { parseNewsDetailHtml, parseNewsDetailJson, parseNewsList, parseNewsListHtml, } from "./parsers/news.js";
-import { addExamTimes, parseExamsHtml } from "./parsers/exams.js";
+import { addExamTimes, parseExamsHtml, parsePastExamsHtml } from "./parsers/exams.js";
 import { parseAttendanceHtml, summarizeLessonNotes } from "./parsers/attendance.js";
 import { parseGradebookHtml } from "./parsers/gradebook.js";
 import { parsePrintoutsHtml } from "./parsers/printouts.js";
@@ -11,16 +13,21 @@ import { parseOverview } from "./parsers/overview.js";
 import { parseScheduleHtml, parseTimetableJson } from "./parsers/schedule.js";
 import { parseStudentsFromAccountsRoles, parseStudentsFromHome } from "./parsers/students.js";
 import { NetworkError } from "./network-error.js";
-import { DOWNLOAD_TIMEOUT_MS, fetchExternalFile, isHtmlResponse } from "./external-fetch.js";
+import { DOWNLOAD_TIMEOUT_MS, getExternalFetcher, isHtmlResponse } from "./downloads.js";
+import { sessionOf } from "./internal.js";
 export class WilmaClient {
     session;
     constructor(session) {
         this.session = session;
+        sessionOf.set(this, session);
     }
-    static async login(profile, onMfaRequired) {
+    static async login(profile, onMfaRequired, options = {}) {
         const session = new WilmaSession(profile.baseUrl, {
             studentNumber: profile.studentNumber ?? null,
             debug: profile.debug ?? false,
+            transport: options.transport,
+            relogin: options.relogin,
+            shared: options.sharedSession,
         });
         session.setMfaCallback(onMfaRequired);
         try {
@@ -41,22 +48,57 @@ export class WilmaClient {
      * in. If Wilma has ended that session, the first request logs in again by
      * itself. Returns null when the saved state has no session.
      */
-    static resume(profile, state, onMfaRequired) {
+    static resume(profile, state, onMfaRequired, options = {}) {
         const session = new WilmaSession(profile.baseUrl, {
             studentNumber: profile.studentNumber ?? null,
             debug: profile.debug ?? false,
+            transport: options.transport,
+            relogin: options.relogin,
+            shared: options.sharedSession,
         });
         session.setMfaCallback(onMfaRequired);
         return session.resumeState(state, profile.username, profile.password) ? new WilmaClient(session) : null;
     }
+    /**
+     * A client on a saved session without any credentials: it never logs in.
+     * When Wilma ends the session, requests fail with SessionEndedError. For
+     * apps that don't keep the parent's password. Returns null when the saved
+     * state has no session.
+     */
+    static resumeSession(baseUrl, state, options = {}) {
+        const session = new WilmaSession(baseUrl, { debug: options.debug, transport: options.transport, relogin: false, shared: options.sharedSession });
+        return session.resumeState(state) ? new WilmaClient(session) : null;
+    }
+    /** The Wilma this client talks to, e.g. "https://example.inschool.fi". */
+    get origin() {
+        return this.session.origin;
+    }
     /** This login's session (cookies) as a string, for WilmaClient.resume() in a later process. Treat it like a password. */
     exportSession() {
         return this.session.exportState();
     }
+    /**
+     * End this login's session in Wilma (its "Log out"), e.g. so the parent can
+     * use Wilma in the browser. Never logs in. Afterwards this client and its
+     * forStudent() clients don't log in again by themselves. Returns true when
+     * a live session was ended, false when there was none; throws (keeping the
+     * session) when Wilma can't be reached.
+     */
+    logout() {
+        return this.session.logout();
+    }
+    /** Share the session with the other WilmAI programs on this computer from now on (see ClientOptions.sharedSession). */
+    useSharedSession(shared) {
+        this.session.setShared(shared);
+    }
     /** Run a callback after every successful login, e.g. to save the new session. */
     onLogin(callback) {
         this.session.onLogin(callback);
     }
+    /** Be told when this client logs in, continues another program's session, or finds its session ended (see SessionEvent). */
+    onSessionEvent(callback) {
+        this.session.onSessionEvent(callback);
+    }
     static async listStudents(profile, onMfaRequired) {
         const client = await WilmaClient.login({ ...profile, studentNumber: null }, onMfaRequired);
         return client.students();
@@ -146,6 +188,48 @@ export class WilmaClient {
             }
             return parseMessageDetailHtml(text, messageId);
         },
+        /**
+         * Who the parent can write to (Wilma's recipient list): the child, the
+         * other guardians, the child's own teachers, and the school's staff and
+         * teachers. Pass one to prepareMessage() in the write entry point.
+         */
+        recipients: async () => {
+            const resp = await this.session.get("/messages/recipients");
+            const html = await resp.text();
+            const recipients = parseRecipientsHtml(html, resp.url);
+            // Lists Wilma loads when opened (the child's own teachers, one by one).
+            for (const [group, path] of recipientListSources(html, resp.url)) {
+                const list = await this.session.get(path);
+                for (const recipient of parseRecipientsHtml(await list.text(), list.url, { group })) {
+                    if (!recipients.some((r) => r.composePath === recipient.composePath && r.group === recipient.group))
+                        recipients.push(recipient);
+                }
+            }
+            return recipients;
+        },
+    };
+    student = {
+        /** The child's class and supervisors (class teacher, other supervisors), with their message links, from the front page. */
+        get: async () => {
+            const resp = await this.session.get("/");
+            return parseStudentDetailsHtml(await resp.text(), resp.url);
+        },
+    };
+    invitations = {
+        /** Event invitations (Tapahtumakutsut), newest first, with whether this family has answered. */
+        list: async () => {
+            const resp = await this.session.get("/messages/list/appointments");
+            const data = safeJson(await resp.text());
+            return parseInvitationListings(data, parseMessagesList(data, "appointments"));
+        },
+        /**
+         * One invitation's time slots and this family's choice; null when the
+         * message isn't an invitation. Like opening it in Wilma, this marks the
+         * message read.
+         */
+        get: async (messageId) => {
+            return (await this.messages.get(messageId)).invitation ?? null;
+        },
     };
     news = {
         list: async () => {
@@ -187,7 +271,7 @@ export class WilmaClient {
                     // Wilma handed the file off to another site: fetch it there, without Wilma credentials.
                     const location = response.headers.get("location");
                     await response.body?.cancel();
-                    const external = location ? await fetchExternalFile(new URL(location, url).href) : null;
+                    const external = location ? await getExternalFetcher()(new URL(location, url).href) : null;
                     return external
                         ? { resource, response: external, status: "fetched" }
                         : { resource, response: null, status: "not_a_file" };
@@ -196,9 +280,9 @@ export class WilmaClient {
                     await response.body?.cancel();
                     return { resource, response: null, status: "not_a_file" };
                 }
-                return { resource, response: response, status: "fetched" };
+                return { resource, response, status: "fetched" };
             }
-            const response = await fetchExternalFile(resource.url);
+            const response = await getExternalFetcher()(resource.url);
             if (!response) {
                 return { resource, response: null, status: "not_a_file" };
             }
@@ -241,6 +325,25 @@ export class WilmaClient {
             const text = await resp.text();
             return parseExamsHtml(text);
         },
+        /**
+         * Past exams with their grades (Kokeet > Menneet), newest first. Wilma
+         * shows this school year by default; `from` (YYYY-MM-DD, to `to` or today)
+         * reaches further back, as far as the school keeps exams.
+         */
+        past: async (opts) => {
+            let path = "/exams/calendar/past";
+            if (opts?.from || opts?.to) {
+                const to = opts.to ?? finnishDateString();
+                const [y, m] = to.split("-").map(Number);
+                // Without a start, the school year `to` falls in (from 1 August).
+                const from = opts.from ?? `${m >= 8 ? y : y - 1}-08-01`;
+                const fi = (iso) => iso.split("-").reverse().map(Number).join(".");
+                // Wilma's own form: range -3 is "between these dates".
+                path += `?${new URLSearchParams({ range: "-3", first: fi(from), last: fi(to) })}`;
+            }
+            const resp = await this.session.get(path);
+            return parsePastExamsHtml(await resp.text());
+        },
     };
     attendance = {
         /**
@@ -254,10 +357,12 @@ export class WilmaClient {
             const notes = parseAttendanceHtml(await this.attendancePage(`range=-3&first=${isoDateToFinnish(from)}&last=${isoDateToFinnish(to)}`));
             return notes.filter((note) => note.date >= from && note.date <= to);
         },
+        /** Every lesson note of this school year (Wilma's own "whole year" view): one request. */
+        schoolYear: async () => parseAttendanceHtml(await this.attendancePage("range=-4")),
         /** How many lesson notes of each kind from `from` to `to` (default today); without `from`, this school year. */
         summary: async (opts) => {
             if (!opts?.from) {
-                const notes = parseAttendanceHtml(await this.attendancePage("range=-4"));
+                const notes = await this.attendance.schoolYear();
                 return summarizeLessonNotes(opts?.to ? notes.filter((note) => note.date <= opts.to) : notes, null, opts?.to ?? null);
             }
             const to = opts.to ?? finnishDateString();
@@ -320,7 +425,7 @@ export class WilmaClient {
             if (!printout)
                 throw new Error(`Printout "${id}" not found`);
             const response = await this.session.get(printout.path, undefined, { timeoutMs: DOWNLOAD_TIMEOUT_MS });
-            return { printout, response: response };
+            return { printout, response };
         },
     };
     overview = {

package/dist/core.d.ts

@@ -0,0 +1,16 @@
+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 { setDefaultTransport } from "./transport.js";
+export type { WilmaTransport, WilmaRequest, WilmaReply } from "./transport.js";
+export { DOWNLOAD_TIMEOUT_MS, isHtmlResponse, setExternalFetcher } from "./downloads.js";
+export type { ExternalFetcher } from "./downloads.js";
+export { NetworkError, describeNetworkCode, extractCauseCode, wrapNetworkError } from "./network-error.js";
+export { parseWilmaTimestamp } from "./parsers/dates.js";
+export { finnishDateString, finnishIsoString, finnishParts, finnishTime } from "./finnish-time.js";
+export { parseStudentsFromHome } from "./parsers/students.js";
+export { htmlToText } from "./parsers/html-text.js";
+export { addExamTimes, parsePastExamsHtml } from "./parsers/exams.js";
+export { awaitingAnswer, slotState } from "./parsers/invitations.js";

package/dist/core.js

@@ -0,0 +1,11 @@
+export { WilmaClient } from "./client.js";
+export { WilmaSession, AuthenticationError, MfaRequiredError, APIError, SessionEndedError } 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";
+export { parseWilmaTimestamp } from "./parsers/dates.js";
+export { finnishDateString, finnishIsoString, finnishParts, finnishTime } from "./finnish-time.js";
+export { parseStudentsFromHome } from "./parsers/students.js";
+export { htmlToText } from "./parsers/html-text.js";
+export { addExamTimes, parsePastExamsHtml } from "./parsers/exams.js";
+export { awaitingAnswer, slotState } from "./parsers/invitations.js";

package/dist/downloads.d.ts

@@ -0,0 +1,11 @@
+/** How long a download may stall (before answering, or mid-file) before it fails. */
+export declare const DOWNLOAD_TIMEOUT_MS = 60000;
+export declare function isHtmlResponse(response: {
+    headers: {
+        get(name: string): string | null;
+    };
+}): boolean;
+/** Fetch a file from another site without Wilma's cookies; null when the address serves no file. */
+export type ExternalFetcher = (url: string) => Promise<Response | null>;
+export declare function setExternalFetcher(fetcher: ExternalFetcher | null): void;
+export declare function getExternalFetcher(): ExternalFetcher;

package/dist/downloads.js

@@ -0,0 +1,21 @@
+/*
+ * Download helpers that work on any runtime. Fetching files from other sites
+ * (bulletin links) needs network guards only Node can give (see
+ * external-fetch.ts), so it's a hook the Node entry point fills in.
+ */
+/** How long a download may stall (before answering, or mid-file) before it fails. */
+export const DOWNLOAD_TIMEOUT_MS = 60_000;
+export function isHtmlResponse(response) {
+    const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+    return contentType.startsWith("text/html") || contentType.startsWith("application/xhtml");
+}
+let externalFetcher = null;
+export function setExternalFetcher(fetcher) {
+    externalFetcher = fetcher;
+}
+export function getExternalFetcher() {
+    if (!externalFetcher) {
+        throw new Error("Downloading files from other sites needs the Node client (@wilm-ai/wilma-client).");
+    }
+    return externalFetcher;
+}

package/dist/external-fetch.d.ts

@@ -1,14 +1,8 @@
-import { type Response } from "undici";
-/** How long a download may stall (before answering, or mid-file) before it fails. */
-export declare const DOWNLOAD_TIMEOUT_MS = 60000;
+import { DOWNLOAD_TIMEOUT_MS, isHtmlResponse } from "./downloads.js";
+export { DOWNLOAD_TIMEOUT_MS, isHtmlResponse };
 export declare function isBlockedAddress(address: string): boolean;
 /** Refuse URLs that point at private or special addresses, or at unusual ports. */
 export declare function assertPublicUrl(url: URL): void;
-export declare function isHtmlResponse(response: {
-    headers: {
-        get(name: string): string | null;
-    };
-}): boolean;
 /**
  * Fetch an external URL the way a signed-out browser would: an isolated
  * in-memory cookie jar, redirects followed across hosts, and no Wilma

package/dist/external-fetch.js

@@ -18,8 +18,8 @@ import { Agent, fetch, Headers } from "undici";
 import { APIError } from "./session.js";
 import { NetworkError } from "./network-error.js";
 import { IdleTimer, asNetworkError, watchBody } from "./timeouts.js";
-/** How long a download may stall (before answering, or mid-file) before it fails. */
-export const DOWNLOAD_TIMEOUT_MS = 60_000;
+import { DOWNLOAD_TIMEOUT_MS, isHtmlResponse } from "./downloads.js";
+export { DOWNLOAD_TIMEOUT_MS, isHtmlResponse };
 const MAX_REDIRECTS = 10;
 const EXTERNAL_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) " +
     "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0 Safari/537.36";
@@ -138,10 +138,6 @@ function guardedLookup(hostname, options, callback) {
     });
 }
 const guardedAgent = new Agent({ connect: { lookup: guardedLookup } });
-export function isHtmlResponse(response) {
-    const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
-    return contentType.startsWith("text/html") || contentType.startsWith("application/xhtml");
-}
 // Some document hosts serve an HTML viewer page for a sharing URL but return
 // the file itself when a conventional download parameter is present. These are
 // generic retry variants, not provider detection: the original URL is always

package/dist/index.d.ts

@@ -1,11 +1,3 @@
-export type { Exam, ExamGrade, GradebookEntry, HomeworkItem, LessonNote, LessonNoteSummary, Message, MessageReply, MessageFolder, Municipality, NewsItem, NewsResource, NewsResourceAuthContext, OverviewData, Printout, ScheduleLesson, TenantDiscoveryResponse, TenantInfo, UpcomingExam, WilmaProfile, StudentInfo, } from "./types.js";
-export { WilmaClient } from "./client.js";
-export type { MfaCallback } from "./client.js";
-export { WilmaSession, AuthenticationError, MfaRequiredError, APIError } from "./session.js";
-export { NetworkError, describeNetworkCode, extractCauseCode, wrapNetworkError, } from "./network-error.js";
-export { loadTenantDiscovery, listTenants, searchTenantsByMunicipality, findTenantByUrl, } from "./tenants.js";
-export { parseWilmaTimestamp } from "./parsers/dates.js";
-export { finnishDateString, finnishIsoString, finnishParts, finnishTime } from "./finnish-time.js";
-export { parseStudentsFromHome } from "./parsers/students.js";
-export { htmlToText } from "./parsers/html-text.js";
-export { addExamTimes } from "./parsers/exams.js";
+export * from "./core.js";
+export { nodeTransport } from "./transport-node.js";
+export { loadTenantDiscovery, listTenants, searchTenantsByMunicipality, findTenantByUrl } from "./tenants.js";

package/dist/index.js

@@ -1,9 +1,14 @@
-export { WilmaClient } from "./client.js";
-export { WilmaSession, AuthenticationError, MfaRequiredError, APIError } from "./session.js";
-export { NetworkError, describeNetworkCode, extractCauseCode, wrapNetworkError, } from "./network-error.js";
-export { loadTenantDiscovery, listTenants, searchTenantsByMunicipality, findTenantByUrl, } from "./tenants.js";
-export { parseWilmaTimestamp } from "./parsers/dates.js";
-export { finnishDateString, finnishIsoString, finnishParts, finnishTime } from "./finnish-time.js";
-export { parseStudentsFromHome } from "./parsers/students.js";
-export { htmlToText } from "./parsers/html-text.js";
-export { addExamTimes } from "./parsers/exams.js";
+/*
+ * @wilm-ai/wilma-client for Node: the core client (./core.js) with Node's
+ * defaults — requests through undici, files from other sites through the
+ * guarded fetcher, and the bundled list of Wilmas read from disk.
+ */
+import { setDefaultTransport } from "./transport.js";
+import { setExternalFetcher } from "./downloads.js";
+import { nodeTransport } from "./transport-node.js";
+import { fetchExternalFile } from "./external-fetch.js";
+setDefaultTransport(nodeTransport);
+setExternalFetcher(fetchExternalFile);
+export * from "./core.js";
+export { nodeTransport } from "./transport-node.js";
+export { loadTenantDiscovery, listTenants, searchTenantsByMunicipality, findTenantByUrl } from "./tenants.js";

package/dist/internal.d.ts

@@ -0,0 +1,3 @@
+import type { WilmaSession } from "./session.js";
+/** Each client's session, so write functions (a separate entry point) can use it. */
+export declare const sessionOf: WeakMap<object, WilmaSession>;

package/dist/internal.js

@@ -0,0 +1,2 @@
+/** Each client's session, so write functions (a separate entry point) can use it. */
+export const sessionOf = new WeakMap();

package/dist/parsers/exams.d.ts

@@ -1,5 +1,14 @@
-import type { Exam, UpcomingExam } from "../types.js";
+import type { Exam, PastExam, UpcomingExam } from "../types.js";
 export declare function parseExamsHtml(html: string): Exam[];
+/**
+ * Wilma's past exams page (Kokeet > Menneet): a table with a row per exam,
+ * columns seen, date, teachers, exam, notes, grade and verbal assessment. The
+ * exam cell reads "name : group course-code : course title", e.g.
+ * "Verbikoe 4 : RUB1_ Ruotsin kieli, B1.t RUB1_91 : Ruotsin kieli, B1".
+ * Columns are found by their headings (Finnish, Swedish or English), or by
+ * Wilma's usual order. Newest first.
+ */
+export declare function parsePastExamsHtml(html: string): PastExam[];
 /**
  * Add start times from the exam calendar to upcoming exams (the front page's
  * exam list has dates only). An exam is matched by date and its course code