@wilm-ai/wilma-client 1.3.0 → 1.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wilm.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { Exam, Message, MessageFolder, NewsItem, OverviewData, WilmaProfile, StudentInfo } from "./types.js";
+import type { Exam, Message, MessageFolder, NewsItem, OverviewData, WilmaProfile, StudentInfo, LessonNote } from "./types.js";
 export type MfaCallback = (formkey: string) => Promise<string>;
 export declare class WilmaClient {
     private session;
@@ -19,6 +19,11 @@ export declare class WilmaClient {
             end?: string;
         }) => Promise<Exam[]>;
     };
+    attendance: {
+        list: (opts?: {
+            date?: string;
+        }) => Promise<LessonNote[]>;
+    };
     overview: {
         get: () => Promise<OverviewData>;
     };

package/dist/client.js

@@ -3,6 +3,7 @@ import { parseWilmaTimestamp } from "./parsers/dates.js";
 import { parseMessagesList, parseMessageDetailHtml } from "./parsers/messages.js";
 import { parseNewsDetailHtml, parseNewsDetailJson, parseNewsList, parseNewsListHtml, } from "./parsers/news.js";
 import { parseExamsHtml } from "./parsers/exams.js";
+import { parseAttendanceHtml } from "./parsers/attendance.js";
 import { parseOverview } from "./parsers/overview.js";
 import { parseStudentsFromHome } from "./parsers/students.js";
 export class WilmaClient {
@@ -124,6 +125,19 @@ export class WilmaClient {
             return parseExamsHtml(text);
         },
     };
+    attendance = {
+        list: async (opts) => {
+            const params = new URLSearchParams();
+            if (opts?.date) {
+                params.set("date", opts.date);
+            }
+            const query = params.toString();
+            const path = query ? `/attendance/view?${query}` : "/attendance/view";
+            const resp = await this.session.get(path);
+            const text = await resp.text();
+            return parseAttendanceHtml(text, opts?.date ?? "");
+        },
+    };
     overview = {
         get: async () => {
             const resp = await this.session.get("/overview");

package/dist/index.d.ts

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

package/dist/parsers/attendance.d.ts

@@ -0,0 +1,18 @@
+import type { LessonNote } from "../types.js";
+/**
+ * Parse Wilma's /attendance/view HTML page into structured LessonNote objects.
+ *
+ * The attendance table is a fine-grained grid: <thead> declares hour-group
+ * headers like `<th colspan="3">9</th>`, and tbody rows mix `<td>` cells with
+ * varying colspans (filler `<td colspan="2">`, event `<td colspan="3">`, etc).
+ * To map an event `<td>` to its hour, we walk cumulative grid columns (sum of
+ * colspans) within the row and look up the column's hour group from the thead.
+ *
+ * Counting `<td>` indices alone is wrong: a `<td colspan="3">` filler skips
+ * three grid columns but consumes one index, so by the third or fourth cell
+ * the index has drifted from the true grid column.
+ *
+ * Title attribute on event cells: "TypeLabel /TeacherName" or
+ * "SubjectCode; TypeLabel /TeacherName".
+ */
+export declare function parseAttendanceHtml(html: string, date: string): LessonNote[];

package/dist/parsers/attendance.js

@@ -0,0 +1,121 @@
+import * as cheerio from "cheerio";
+/**
+ * Parse Wilma's /attendance/view HTML page into structured LessonNote objects.
+ *
+ * The attendance table is a fine-grained grid: <thead> declares hour-group
+ * headers like `<th colspan="3">9</th>`, and tbody rows mix `<td>` cells with
+ * varying colspans (filler `<td colspan="2">`, event `<td colspan="3">`, etc).
+ * To map an event `<td>` to its hour, we walk cumulative grid columns (sum of
+ * colspans) within the row and look up the column's hour group from the thead.
+ *
+ * Counting `<td>` indices alone is wrong: a `<td colspan="3">` filler skips
+ * three grid columns but consumes one index, so by the third or fourth cell
+ * the index has drifted from the true grid column.
+ *
+ * Title attribute on event cells: "TypeLabel /TeacherName" or
+ * "SubjectCode; TypeLabel /TeacherName".
+ */
+export function parseAttendanceHtml(html, date) {
+    const $ = cheerio.load(html);
+    const notes = [];
+    const targetFinnish = dateToFinnish(date);
+    $("table").each((_, table) => {
+        const $table = $(table);
+        // Build a flat array indexed by grid-column whose value is the hour.
+        // thead has hour-labeled <th>s with colspans (e.g. <th colspan="3">9</th>);
+        // replicate each hour by its colspan to get a column->hour lookup.
+        // Non-numeric headers (Päivämäärä, Yhteensä, Huomioita) are skipped.
+        const hourMap = [];
+        $table.find("thead th").each((_, th) => {
+            const text = $(th).text().trim();
+            const hour = parseInt(text, 10);
+            if (!Number.isNaN(hour) && hour >= 0 && hour <= 23) {
+                const colspan = parseInt($(th).attr("colspan") ?? "1", 10) || 1;
+                for (let i = 0; i < colspan; i++)
+                    hourMap.push(hour);
+            }
+        });
+        if (hourMap.length === 0)
+            return; // not the attendance table (e.g. legend)
+        $table.find("tbody tr").each((_, row) => {
+            const cells = $(row).find("td").toArray();
+            if (cells.length < 3)
+                return; // need at least weekday, date, and one slot
+            const rowDate = $(cells[1]).text().trim();
+            if (!rowDate || rowDate !== targetFinnish)
+                return;
+            // Walk event-grid cells. Indices 0..1 are weekday + date (outside grid).
+            let gridCol = 0;
+            for (let i = 2; i < cells.length; i++) {
+                const $cell = $(cells[i]);
+                const colspan = parseInt($cell.attr("colspan") ?? "1", 10) || 1;
+                const tpClass = (($cell.attr("class") ?? "").match(/\bat-tp\d+\b/) ?? [])[0];
+                if (tpClass) {
+                    const title = ($cell.attr("title") ?? "").trim();
+                    const cellText = $cell.text().trim();
+                    // Title formats observed:
+                    //   "TypeLabel /TeacherFullName"
+                    //   "SubjectCode; TypeLabel /TeacherFullName"
+                    //   "SubjectCode; TypeLabel; ExtraNote /TeacherFullName"
+                    let subject = "";
+                    let typeLabel = "";
+                    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();
+                        }
+                    }
+                    // Map cell's grid range to start/end via the thead-derived map.
+                    // start = hour at the cell's first grid column.
+                    // end   = hour at the cell's last grid column + 45 min.
+                    // If the cell extends past the mapped grid (shouldn't happen with
+                    // well-formed tables), report null so consumers don't see a wrong time.
+                    const startHour = hourMap[gridCol];
+                    const endHour = hourMap[gridCol + colspan - 1];
+                    let start = null;
+                    let end = null;
+                    if (startHour !== undefined && endHour !== undefined) {
+                        start = `${pad(startHour)}:00`;
+                        end = `${pad(endHour)}:45`;
+                    }
+                    notes.push({
+                        date,
+                        start,
+                        end,
+                        subject,
+                        typeLabel: typeLabel || tpClass.replace("at-tp", "Type "),
+                        typeClass: tpClass,
+                        teacher,
+                    });
+                }
+                gridCol += colspan;
+            }
+        });
+    });
+    return notes;
+}
+function pad(n) {
+    return String(n).padStart(2, "0");
+}
+function dateToFinnish(date) {
+    // Convert YYYY-MM-DD to D.M.YYYY (Finnish format, no leading zeros).
+    if (!date)
+        return "";
+    const parts = date.split("-");
+    if (parts.length !== 3)
+        return date;
+    const day = parseInt(parts[2], 10);
+    const month = parseInt(parts[1], 10);
+    const year = parts[0];
+    return `${day}.${month}.${year}`;
+}

package/dist/parsers/messages.js

@@ -79,9 +79,53 @@ export function parseMessageDetailHtml(html, messageId) {
         });
     }
     let content = null;
-    const hidden = $("div.ckeditor.hidden").first();
-    if (hidden.length) {
-        content = hidden.text().trim();
+    const replyBoxes = $("div.m-replybox.hidden");
+    if (replyBoxes.length > 0) {
+        const otherReplies = replyBoxes.filter(function () {
+            return !$(this).hasClass("m-replybox-me");
+        });
+        if (otherReplies.length > 0) {
+            const latest = otherReplies.last();
+            const inner = latest.find("div.inner.hidden");
+            if (inner.length) {
+                content = inner.text().trim();
+                const replyHeaderText = latest.find("h2").first().text().trim();
+                const replySender = latest.find("a.profile-link").first();
+                if (replySender.length) {
+                    senderName = replySender.text().trim();
+                    sendersJson = {
+                        senders: [
+                            {
+                                Name: senderName,
+                                Href: replySender.attr("href"),
+                            },
+                        ],
+                    };
+                }
+                else {
+                    const replySenderName = extractReplySenderName(replyHeaderText);
+                    if (replySenderName) {
+                        senderName = replySenderName;
+                        sendersJson = {
+                            senders: [
+                                {
+                                    Name: senderName,
+                                },
+                            ],
+                        };
+                    }
+                }
+                if (replyHeaderText) {
+                    sentAt = parseWilmaTimestamp(extractReplyTimestampText(replyHeaderText));
+                }
+            }
+        }
+    }
+    if (!content) {
+        const hidden = $("div.ckeditor.hidden").first();
+        if (hidden.length) {
+            content = hidden.text().trim();
+        }
     }
     if (!content && panelBody.length) {
         const clone = cheerio.load(panelBody.html() ?? "");
@@ -138,3 +182,12 @@ export function debugMessageFields(data) {
 function compactText(value) {
     return value.replace(/\s+/g, " ").trim();
 }
+function extractReplyTimestampText(headerText) {
+    const absoluteDateTime = /(\d{1,2}\.\d{1,2}\.\d{4}\s+\d{1,2}:\d{2})/.exec(headerText);
+    return absoluteDateTime?.[1] ?? headerText;
+}
+function extractReplySenderName(headerText) {
+    const match = /^(.+?)\s+(?:vastasi|svarade|replied)\b/i.exec(compactText(headerText));
+    const sender = match?.[1]?.trim();
+    return sender || null;
+}

package/dist/types.d.ts

@@ -110,3 +110,18 @@ export interface OverviewData {
     homework: HomeworkItem[];
     fetchedAt: Date;
 }
+/**
+ * A lesson note from the attendance/lesson notes page.
+ * start/end are string | null — null when time-slot derivation
+ * falls outside the assumed 08:00–15:00 range (see parseAttendanceHtml).
+ */
+export interface LessonNote {
+    /** YYYY-MM-DD */
+    date: string;
+    start: string | null;
+    end: string | null;
+    subject: string;
+    typeLabel: string;
+    typeClass: string;
+    teacher: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wilm-ai/wilma-client",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,13 +14,6 @@
     "dist",
     "tenant_list.json"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "lint": "echo 'add lint'",
-    "test": "echo 'add tests'",
-    "test:smoke": "tsc -p tsconfig.json && node test/smoke.mjs",
-    "test:live": "tsc -p tsconfig.json && node test/live.spec.mjs"
-  },
   "dependencies": {
     "cheerio": "^1.0.0-rc.12",
     "tough-cookie": "^4.1.4",
@@ -29,5 +22,12 @@
   "devDependencies": {
     "typescript": "^5.6.3",
     "@types/tough-cookie": "^4.0.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "echo 'add lint'",
+    "test": "pnpm run build && node test/parser-messages.mjs",
+    "test:smoke": "tsc -p tsconfig.json && node test/smoke.mjs",
+    "test:live": "tsc -p tsconfig.json && node test/live.spec.mjs"
   }
-}
+}