@wilm-ai/wilma-client 1.5.2 → 1.6.0

package/dist/external-fetch.js

@@ -0,0 +1,263 @@
+/*
+ * Fetching files that school bulletins link to on other sites.
+ *
+ * Bulletin links are written by school staff (or by whoever controls a staff
+ * account), and this code may also run on a server. So external fetches:
+ *  - never carry Wilma credentials (an isolated, empty cookie jar per fetch),
+ *  - only go to public internet addresses on ports 80/443: private, loopback,
+ *    link-local and other special ranges are refused at every redirect hop and
+ *    again at connect time, after DNS resolution (which also stops DNS
+ *    rebinding),
+ *  - fail when the site stops sending for a while (an idle timeout, so a big
+ *    file on a slow connection still finishes).
+ */
+import { lookup as dnsLookup } from "node:dns";
+import { BlockList, isIP } from "node:net";
+import { CookieJar } from "tough-cookie";
+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;
+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";
+const blocked = new BlockList();
+for (const [network, prefix] of [
+    ["0.0.0.0", 8], // "this network"
+    ["10.0.0.0", 8], // private
+    ["100.64.0.0", 10], // carrier-grade NAT
+    ["127.0.0.0", 8], // loopback
+    ["169.254.0.0", 16], // link-local, cloud metadata services
+    ["172.16.0.0", 12], // private
+    ["192.0.0.0", 24], // IETF protocol assignments
+    ["192.168.0.0", 16], // private
+    ["198.18.0.0", 15], // benchmarking
+    ["224.0.0.0", 4], // multicast
+    ["240.0.0.0", 4], // reserved, broadcast
+]) {
+    blocked.addSubnet(network, prefix, "ipv4");
+}
+for (const [network, prefix] of [
+    ["::", 128], // unspecified
+    ["::1", 128], // loopback
+    ["fc00::", 7], // unique local
+    ["fe80::", 10], // link-local
+    ["ff00::", 8], // multicast
+]) {
+    blocked.addSubnet(network, prefix, "ipv6");
+}
+/** Tests serve "external" files from 127.0.0.1; nothing else should set this. */
+function privateNetworkAllowed() {
+    return process.env.WILMAI_ALLOW_PRIVATE_NETWORK === "1";
+}
+export function isBlockedAddress(address) {
+    const family = isIP(address);
+    if (family === 4)
+        return blocked.check(address, "ipv4");
+    if (family === 6) {
+        const words = ipv6Words(address);
+        if (!words)
+            return true;
+        const zero = (from, to) => words.slice(from, to).every((w) => w === 0);
+        const v4 = (hi, lo) => `${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`;
+        // IPv6 forms that carry an IPv4 address: judge them by that address.
+        if (zero(0, 5) && words[5] === 0xffff)
+            return blocked.check(v4(words[6], words[7]), "ipv4"); // ::ffff:a.b.c.d
+        if (zero(0, 4) && words[4] === 0xffff && words[5] === 0)
+            return blocked.check(v4(words[6], words[7]), "ipv4"); // ::ffff:0:a.b.c.d
+        if (zero(0, 6))
+            return blocked.check(v4(words[6], words[7]), "ipv4"); // ::a.b.c.d (and :: / ::1)
+        if (words[0] === 0x64 && words[1] === 0xff9b && zero(2, 6))
+            return blocked.check(v4(words[6], words[7]), "ipv4"); // NAT64
+        if (words[0] === 0x2002)
+            return blocked.check(v4(words[1], words[2]), "ipv4"); // 6to4
+        // Local-use NAT64 (64:ff9b:1::/48) and Teredo (2001::/32) map to addresses we can't check.
+        if ((words[0] === 0x64 && words[1] === 0xff9b && words[2] === 1) || (words[0] === 0x2001 && words[1] === 0))
+            return true;
+        return blocked.check(address, "ipv6");
+    }
+    return false;
+}
+/** The eight 16-bit words of an IPv6 address (null if it can't be read). */
+function ipv6Words(address) {
+    let text = address.toLowerCase().split("%")[0];
+    const dotted = /(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(text);
+    if (dotted) {
+        const [a, b, c, d] = dotted.slice(1).map(Number);
+        text = text.slice(0, dotted.index) + `${((a << 8) | b).toString(16)}:${((c << 8) | d).toString(16)}`;
+    }
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const head = halves[0] ? halves[0].split(":") : [];
+    const tail = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+    const missing = 8 - head.length - tail.length;
+    if (halves.length === 2 ? missing < 1 : missing !== 0)
+        return null;
+    const words = [...head, ...Array(halves.length === 2 ? missing : 0).fill("0"), ...tail].map((w) => parseInt(w, 16));
+    return words.every((w) => Number.isInteger(w) && w >= 0 && w <= 0xffff) ? words : null;
+}
+/** Refuse URLs that point at private or special addresses, or at unusual ports. */
+export function assertPublicUrl(url) {
+    if (privateNetworkAllowed())
+        return;
+    const refuse = () => {
+        throw new NetworkError(`WilmAI won't fetch ${url.protocol}//${url.host}: links must point to a public website`, {
+            code: "BLOCKED_ADDRESS",
+            origin: url.origin,
+        });
+    };
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        refuse();
+    if (url.port && url.port !== "80" && url.port !== "443")
+        refuse();
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (host === "localhost" || host.endsWith(".localhost"))
+        refuse();
+    // IP literals skip DNS, so check them here (the URL parser has already turned
+    // forms like "2130706433" into dotted notation).
+    if (isIP(host) && isBlockedAddress(host))
+        refuse();
+}
+// Checks the addresses a host name resolves to, at connect time.
+function guardedLookup(hostname, options, callback) {
+    dnsLookup(hostname, { ...options, all: true }, (err, addresses) => {
+        if (err)
+            return callback(err);
+        const list = addresses;
+        if (!privateNetworkAllowed() && list.some((entry) => isBlockedAddress(entry.address))) {
+            const blockedErr = new Error(`${hostname} resolves to a private address`);
+            blockedErr.code = "BLOCKED_ADDRESS";
+            return callback(blockedErr);
+        }
+        if (options?.all)
+            return callback(null, list);
+        return callback(null, list[0]?.address, list[0]?.family);
+    });
+}
+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
+// attempted first, and a variant is tried only after an HTML answer.
+const DOWNLOAD_PARAM_VARIANTS = [
+    ["download", "1"],
+    ["dl", "1"],
+];
+function buildDownloadCandidates(rawUrl) {
+    const original = new URL(rawUrl);
+    const candidates = [original];
+    for (const [param, value] of DOWNLOAD_PARAM_VARIANTS) {
+        if (!original.searchParams.has(param)) {
+            const variant = new URL(original.href);
+            variant.searchParams.set(param, value);
+            candidates.push(variant);
+        }
+    }
+    return candidates;
+}
+/**
+ * Fetch an external URL the way a signed-out browser would: an isolated
+ * in-memory cookie jar, redirects followed across hosts, and no Wilma
+ * credentials anywhere. Returns null when every candidate answered with an
+ * HTML page instead of a file; throws for HTTP errors and refused addresses.
+ */
+export async function fetchExternalFile(rawUrl) {
+    let failedStatus = null;
+    for (const candidate of buildDownloadCandidates(rawUrl)) {
+        const response = await fetchFollowingRedirects(candidate);
+        if (!response) {
+            continue;
+        }
+        if (!response.ok) {
+            failedStatus ??= response.status;
+            await response.body?.cancel();
+            continue;
+        }
+        if (isHtmlResponse(response)) {
+            await response.body?.cancel();
+            continue;
+        }
+        return response;
+    }
+    if (failedStatus !== null) {
+        throw new APIError(`The linked site answered HTTP ${failedStatus}`, failedStatus);
+    }
+    return null;
+}
+async function fetchFollowingRedirects(initialUrl) {
+    const cookieJar = new CookieJar();
+    const idle = new IdleTimer(DOWNLOAD_TIMEOUT_MS);
+    let currentUrl = initialUrl;
+    for (let redirectCount = 0; redirectCount <= MAX_REDIRECTS; redirectCount += 1) {
+        try {
+            assertPublicUrl(currentUrl);
+        }
+        catch (err) {
+            idle.stop();
+            throw err;
+        }
+        const headers = new Headers({
+            "User-Agent": EXTERNAL_USER_AGENT,
+            "Accept": "*/*",
+        });
+        const cookieHeader = cookieJar.getCookieStringSync(currentUrl.href);
+        if (cookieHeader) {
+            headers.set("Cookie", cookieHeader);
+        }
+        let response;
+        try {
+            idle.touch();
+            response = await fetch(currentUrl, {
+                headers,
+                redirect: "manual",
+                signal: idle.signal,
+                dispatcher: privateNetworkAllowed() ? undefined : guardedAgent,
+            });
+        }
+        catch (err) {
+            idle.stop();
+            const cause = err.cause;
+            if (cause?.code === "BLOCKED_ADDRESS") {
+                throw new NetworkError(`WilmAI won't fetch ${currentUrl.host}: it points to a private address`, {
+                    code: "BLOCKED_ADDRESS",
+                    origin: currentUrl.origin,
+                    cause: err,
+                });
+            }
+            throw asNetworkError(err, currentUrl.origin);
+        }
+        const setCookies = response.headers.getSetCookie?.() ?? [];
+        for (const cookie of setCookies) {
+            cookieJar.setCookieSync(cookie, currentUrl.href, { ignoreError: true });
+        }
+        if (!setCookies.length) {
+            const cookie = response.headers.get("set-cookie");
+            if (cookie)
+                cookieJar.setCookieSync(cookie, currentUrl.href, { ignoreError: true });
+        }
+        if (response.status < 300 || response.status >= 400) {
+            return watchBody(response, idle, currentUrl.origin);
+        }
+        const location = response.headers.get("location");
+        await response.body?.cancel();
+        if (!location) {
+            idle.stop();
+            return null;
+        }
+        const nextUrl = new URL(location, currentUrl);
+        if (nextUrl.protocol !== "https:" && nextUrl.protocol !== "http:") {
+            idle.stop();
+            return null;
+        }
+        currentUrl = nextUrl;
+    }
+    idle.stop();
+    throw new Error("External resource exceeded the redirect limit");
+}

package/dist/finnish-time.d.ts

@@ -0,0 +1,19 @@
+export interface FinnishParts {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+}
+/** The Finnish wall-clock time of an instant. */
+export declare function finnishParts(date: Date): FinnishParts;
+/** YYYY-MM-DD of an instant in Finnish time. */
+export declare function finnishDateString(date?: Date): string;
+/**
+ * "2026-10-02T13:37:00+03:00": an instant as Finnish wall-clock time with its
+ * offset — unambiguous, and readable without converting from UTC.
+ */
+export declare function finnishIsoString(date: Date): string;
+/** The instant of a Finnish wall-clock time (handles summer time). */
+export declare function finnishTime(year: number, month: number, day: number, hour?: number, minute?: number, second?: number): Date;

package/dist/finnish-time.js

@@ -0,0 +1,64 @@
+/*
+ * Wilma shows times in Finnish local time. The code may run anywhere — a
+ * parent's laptop, or a server in UTC — so conversions go through
+ * Europe/Helsinki explicitly instead of the machine's time zone.
+ */
+const TIME_ZONE = "Europe/Helsinki";
+const formatter = new Intl.DateTimeFormat("en-GB", {
+    timeZone: TIME_ZONE,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hourCycle: "h23",
+});
+/** The Finnish wall-clock time of an instant. */
+export function finnishParts(date) {
+    const parts = {};
+    for (const part of formatter.formatToParts(date)) {
+        if (part.type !== "literal")
+            parts[part.type] = Number(part.value);
+    }
+    return {
+        year: parts.year,
+        month: parts.month,
+        day: parts.day,
+        hour: parts.hour,
+        minute: parts.minute,
+        second: parts.second,
+    };
+}
+/** YYYY-MM-DD of an instant in Finnish time. */
+export function finnishDateString(date = new Date()) {
+    const p = finnishParts(date);
+    return `${p.year}-${String(p.month).padStart(2, "0")}-${String(p.day).padStart(2, "0")}`;
+}
+/**
+ * "2026-10-02T13:37:00+03:00": an instant as Finnish wall-clock time with its
+ * offset — unambiguous, and readable without converting from UTC.
+ */
+export function finnishIsoString(date) {
+    const p = finnishParts(date);
+    const pad = (n) => String(n).padStart(2, "0");
+    const offset = Math.round(offsetMs(date.getTime()) / 60000);
+    const sign = offset < 0 ? "-" : "+";
+    const abs = Math.abs(offset);
+    return (`${p.year}-${pad(p.month)}-${pad(p.day)}T${pad(p.hour)}:${pad(p.minute)}:${pad(p.second)}` +
+        `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`);
+}
+function offsetMs(instant) {
+    const p = finnishParts(new Date(instant));
+    return Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second) - Math.floor(instant / 1000) * 1000;
+}
+/** The instant of a Finnish wall-clock time (handles summer time). */
+export function finnishTime(year, month, day, hour = 0, minute = 0, second = 0) {
+    const asUtc = Date.UTC(year, month - 1, day, hour, minute, second);
+    let instant = asUtc - offsetMs(asUtc);
+    // Near a daylight-saving switch the offset at the guess can differ; recheck once.
+    const corrected = asUtc - offsetMs(instant);
+    if (corrected !== instant)
+        instant = corrected;
+    return new Date(instant);
+}

package/dist/index.d.ts

@@ -1,8 +1,11 @@
-export type { Exam, ExamGrade, HomeworkItem, LessonNote, Message, MessageFolder, Municipality, NewsItem, NewsResource, NewsResourceAuthContext, OverviewData, ScheduleLesson, TenantDiscoveryResponse, TenantInfo, UpcomingExam, WilmaProfile, StudentInfo, } from "./types.js";
+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";

package/dist/index.js

@@ -3,4 +3,7 @@ export { WilmaSession, AuthenticationError, MfaRequiredError, APIError } from ".
 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";

package/dist/parsers/attendance.d.ts

@@ -1,4 +1,4 @@
-import type { LessonNote } from "../types.js";
+import type { LessonNote, LessonNoteSummary } from "../types.js";
 /**
  * Parse Wilma's /attendance/view HTML page into structured LessonNote objects.
  *
@@ -15,4 +15,6 @@ import type { LessonNote } from "../types.js";
  * Title attribute on event cells: "TypeLabel /TeacherName" or
  * "SubjectCode; TypeLabel /TeacherName".
  */
-export declare function parseAttendanceHtml(html: string, date: string): LessonNote[];
+export declare function parseAttendanceHtml(html: string, date?: string): LessonNote[];
+/** Count lesson notes by kind (absences, lateness, feedback…), most common first. */
+export declare function summarizeLessonNotes(notes: LessonNote[], from: string | null, to: string | null): LessonNoteSummary;

package/dist/parsers/attendance.js

@@ -18,7 +18,17 @@ import * as cheerio from "cheerio";
 export function parseAttendanceHtml(html, date) {
     const $ = cheerio.load(html);
     const notes = [];
-    const targetFinnish = dateToFinnish(date);
+    // One day, or every day the page shows (the page covers a chosen period).
+    const targetFinnish = date ? dateToFinnish(date) : null;
+    // The legend table: type class (at-tpN) -> label.
+    const legend = new Map();
+    $("tr").each((_, row) => {
+        const cells = $(row).find("td");
+        const tp = (($(cells[0]).attr("class") ?? "").match(/\bat-tp\d+\b/) ?? [])[0];
+        const label = $(cells[cells.length - 1]).text().trim();
+        if (tp && cells.length === 2 && label && !legend.has(tp))
+            legend.set(tp, label);
+    });
     $("table").each((_, table) => {
         const $table = $(table);
         // Build a flat array indexed by grid-column whose value is the hour.
@@ -42,7 +52,10 @@ export function parseAttendanceHtml(html, date) {
             if (cells.length < 3)
                 return; // need at least weekday, date, and one slot
             const rowDate = $(cells[1]).text().trim();
-            if (!rowDate || rowDate !== targetFinnish)
+            if (!rowDate || (targetFinnish && rowDate !== targetFinnish))
+                return;
+            const rowIso = finnishToIso(rowDate);
+            if (!rowIso)
                 return;
             // Walk event-grid cells. Indices 0..1 are weekday + date (outside grid).
             let gridCol = 0;
@@ -56,24 +69,31 @@ export function parseAttendanceHtml(html, date) {
                     // Title formats observed:
                     //   "TypeLabel /TeacherFullName"
                     //   "SubjectCode; TypeLabel /TeacherFullName"
-                    //   "SubjectCode; TypeLabel; ExtraNote /TeacherFullName"
+                    //   "SubjectCode; TypeLabel; teacher's note /TeacherFullName"
+                    //   "TypeLabel; teacher's note /TeacherFullName" (no lesson)
+                    // The page's legend names each type class, which tells the label
+                    // apart from a subject code or a note.
                     let subject = "";
                     let typeLabel = "";
+                    let note = null;
                     let teacher = cellText;
                     if (title) {
                         let rest = title;
-                        const semiIdx = rest.indexOf(";");
-                        if (semiIdx > 0) {
-                            subject = rest.slice(0, semiIdx).trim();
-                            rest = rest.slice(semiIdx + 1).trim();
-                        }
                         const slashIdx = rest.lastIndexOf(" /");
                         if (slashIdx > 0) {
-                            const afterSlash = rest.slice(slashIdx + 2);
-                            const spaceAfter = afterSlash.startsWith(" ") ? 1 : 0;
-                            typeLabel = rest.slice(0, slashIdx).trim();
-                            teacher = rest.slice(slashIdx + 2 + spaceAfter).trim();
+                            teacher = rest.slice(slashIdx + 2).trim();
+                            rest = rest.slice(0, slashIdx).trim();
                         }
+                        const parts = rest.split(";").map((part) => part.trim());
+                        const known = legend.get(tpClass);
+                        let labelAt = known ? parts.indexOf(known) : -1;
+                        if (labelAt < 0) {
+                            // No legend: a leading course code (no spaces, e.g. "MA_71") is the subject.
+                            labelAt = parts.length > 1 && !/\s/.test(parts[0]) ? 1 : 0;
+                        }
+                        subject = parts.slice(0, labelAt).join("; ");
+                        typeLabel = parts[labelAt] ?? "";
+                        note = parts.slice(labelAt + 1).join("; ") || null;
                     }
                     // Map cell's grid range to start/end via the thead-derived map.
                     // start = hour at the cell's first grid column.
@@ -89,13 +109,14 @@ export function parseAttendanceHtml(html, date) {
                         end = `${pad(endHour)}:45`;
                     }
                     notes.push({
-                        date,
+                        date: rowIso,
                         start,
                         end,
                         subject,
                         typeLabel: typeLabel || tpClass.replace("at-tp", "Type "),
                         typeClass: tpClass,
                         teacher,
+                        note,
                     });
                 }
                 gridCol += colspan;
@@ -104,6 +125,22 @@ export function parseAttendanceHtml(html, date) {
     });
     return notes;
 }
+/** Count lesson notes by kind (absences, lateness, feedback…), most common first. */
+export function summarizeLessonNotes(notes, from, to) {
+    const counts = new Map();
+    for (const note of notes)
+        counts.set(note.typeLabel, (counts.get(note.typeLabel) ?? 0) + 1);
+    return {
+        from,
+        to,
+        total: notes.length,
+        byType: [...counts].map(([type, count]) => ({ type, count })).sort((a, b) => b.count - a.count || a.type.localeCompare(b.type)),
+    };
+}
+function finnishToIso(value) {
+    const match = /^(\d{1,2})\.(\d{1,2})\.(\d{4})$/.exec(value);
+    return match ? `${match[3]}-${match[2].padStart(2, "0")}-${match[1].padStart(2, "0")}` : null;
+}
 function pad(n) {
     return String(n).padStart(2, "0");
 }

package/dist/parsers/dates.js

@@ -1,3 +1,4 @@
+import { finnishParts, finnishTime } from "../finnish-time.js";
 export function parseWilmaTimestamp(value) {
     if (value === null || value === undefined) {
         return fallbackDate();
@@ -23,7 +24,7 @@ export function parseWilmaTimestamp(value) {
     const isoLikeMatch = /^(\d{4})-(\d{2})-(\d{2})\s+(\d{1,2}):(\d{2})$/.exec(raw);
     if (isoLikeMatch) {
         const [, y, m, d, h, mi] = isoLikeMatch.map(Number);
-        return new Date(y, m - 1, d, h, mi, 0, 0);
+        return finnishTime(y, m, d, h, mi);
     }
     // Try Unix timestamp as string
     if (/^\d{10,13}$/.test(raw)) {
@@ -37,7 +38,7 @@ export function parseWilmaTimestamp(value) {
         .replace("julkaistu", "")
         .trim();
     const now = new Date();
-    const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const todayParts = finnishParts(now);
     const rel = {
         "tänään": 0,
         "eilen": 1,
@@ -50,15 +51,12 @@ export function parseWilmaTimestamp(value) {
     };
     for (const [kw, daysAgo] of Object.entries(rel)) {
         if (text.includes(kw)) {
-            const base = new Date(today);
-            base.setDate(base.getDate() - daysAgo);
             const timeMatch = /(\d{1,2})[:.](\d{2})/.exec(text);
-            if (timeMatch) {
-                const h = Number(timeMatch[1]);
-                const m = Number(timeMatch[2]);
-                base.setHours(h, m, 0, 0);
-            }
-            return base;
+            const h = timeMatch ? Number(timeMatch[1]) : 0;
+            const m = timeMatch ? Number(timeMatch[2]) : 0;
+            // Day arithmetic in UTC on the Finnish calendar date, then back to Finnish time.
+            const day = new Date(Date.UTC(todayParts.year, todayParts.month - 1, todayParts.day - daysAgo));
+            return finnishTime(day.getUTCFullYear(), day.getUTCMonth() + 1, day.getUTCDate(), h, m);
         }
     }
     for (const fmt of ["dateTime", "dateOnly"]) {
@@ -66,14 +64,14 @@ export function parseWilmaTimestamp(value) {
             const match = /^(\d{1,2})\.(\d{1,2})\.(\d{4})\s+(\d{1,2}):(\d{2})$/.exec(text);
             if (match) {
                 const [, d, m, y, h, mi] = match.map(Number);
-                return new Date(y, m - 1, d, h, mi, 0, 0);
+                return finnishTime(y, m, d, h, mi);
             }
         }
         else {
             const match = /^(\d{1,2})\.(\d{1,2})\.(\d{4})$/.exec(text);
             if (match) {
                 const [, d, m, y] = match.map(Number);
-                return new Date(y, m - 1, d);
+                return finnishTime(y, m, d);
             }
         }
     }
@@ -82,11 +80,10 @@ export function parseWilmaTimestamp(value) {
         const [, dStr, mStr] = shortMatch;
         const day = Number(dStr);
         const month = Number(mStr);
-        const candidate = new Date(now.getFullYear(), month - 1, day);
-        const sixMonthsAhead = new Date(today);
-        sixMonthsAhead.setDate(sixMonthsAhead.getDate() + 180);
-        if (candidate > sixMonthsAhead) {
-            candidate.setFullYear(candidate.getFullYear() - 1);
+        // A day and month without a year: this year, unless that is over six months ahead.
+        let candidate = finnishTime(todayParts.year, month, day);
+        if (candidate.getTime() > now.getTime() + 180 * 24 * 60 * 60 * 1000) {
+            candidate = finnishTime(todayParts.year - 1, month, day);
         }
         return candidate;
     }

package/dist/parsers/exams.d.ts

@@ -1,2 +1,9 @@
-import type { Exam } from "../types.js";
+import type { Exam, UpcomingExam } from "../types.js";
 export declare function parseExamsHtml(html: string): Exam[];
+/**
+ * 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
+ * (e.g. "MA_91" appears in the calendar entry), or by date alone when it is
+ * the only exam that day in both lists.
+ */
+export declare function addExamTimes(upcoming: UpcomingExam[], calendar: Exam[]): UpcomingExam[];

package/dist/parsers/exams.js

@@ -27,6 +27,9 @@ export function parseExamsHtml(html) {
         const examDate = new Date(Date.UTC(y, m - 1, d, 12, 0, 0));
         // Also store as local date string to avoid any serialization issues
         const dateString = `${y}-${String(m).padStart(2, "0")}-${String(d).padStart(2, "0")}`;
+        // "Pe 30.10.2026 Klo 08:30": some exams have a start time.
+        const timeMatch = /klo\s*(\d{1,2})[:.](\d{2})/i.exec(dateText);
+        const time = timeMatch ? `${timeMatch[1].padStart(2, "0")}:${timeMatch[2]}` : null;
         // Compact whitespace first to normalize the text before parsing
         const subjDesc = compactText($(firstCells.get(1)).text());
         let subject = subjDesc;
@@ -66,12 +69,46 @@ export function parseExamsHtml(html) {
             description: description ? compactText(description) : null,
             teacher: teacher ? compactText(teacher) : null,
             notes: notes ? compactText(notes) : null,
+            time,
             fetchedAt: now,
         });
         autoId += 1;
     });
     return exams;
 }
+/**
+ * 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
+ * (e.g. "MA_91" appears in the calendar entry), or by date alone when it is
+ * the only exam that day in both lists.
+ */
+export function addExamTimes(upcoming, calendar) {
+    return upcoming.map((exam) => {
+        const sameDay = calendar.filter((entry) => entry.dateString === exam.date);
+        const code = exam.subjectCode ? new RegExp(`(^|\\s)${escapeRegExp(exam.subjectCode)}(\\s|$|[.,:])`) : null;
+        const text = (entry) => `${entry.description ?? ""} ${entry.subject}`;
+        let byCode = code ? sameDay.filter((entry) => code.test(text(entry))) : [];
+        if (byCode.length > 1) {
+            // Several exams of one course that day: the exam's name tells them apart.
+            const nameWords = words(exam.name);
+            const scored = byCode.map((entry) => {
+                const entryWords = new Set(words(text(entry)));
+                return { entry, score: nameWords.filter((word) => entryWords.has(word)).length };
+            });
+            const best = Math.max(...scored.map((s) => s.score));
+            byCode = best > 0 ? scored.filter((s) => s.score === best).map((s) => s.entry) : byCode;
+        }
+        const onlyOne = sameDay.length === 1 && upcoming.filter((other) => other.date === exam.date).length === 1;
+        const match = byCode.length === 1 ? byCode[0] : onlyOne ? sameDay[0] : null;
+        return { ...exam, time: match?.time ?? null };
+    });
+}
+function words(value) {
+    return value.toLowerCase().match(/[\p{L}\d]{3,}/gu) ?? [];
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function compactText(value) {
     return value.replace(/\s+/g, " ").trim();
 }

package/dist/parsers/gradebook.d.ts

@@ -0,0 +1,8 @@
+import type { GradebookEntry } from "../types.js";
+/**
+ * The gradebook (Suoritukset): subjects, their syllabi and courses, each with
+ * a grade, scope and completion date. Rows carry their depth as a class
+ * ("level1", "level2", …), which gives the tree. An empty gradebook (nothing
+ * graded yet) has no table and gives [].
+ */
+export declare function parseGradebookHtml(html: string): GradebookEntry[];