@wilm-ai/wilma-client 0.0.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

@@ -0,0 +1,21 @@
+import type { Exam, Message, MessageFolder, NewsItem, WilmaProfile, StudentInfo } from "./types.js";
+export declare class WilmaClient {
+    private session;
+    private constructor();
+    static login(profile: WilmaProfile): Promise<WilmaClient>;
+    static listStudents(profile: WilmaProfile): Promise<StudentInfo[]>;
+    messages: {
+        list: (folder?: MessageFolder) => Promise<Message[]>;
+        get: (messageId: number) => Promise<Message>;
+    };
+    news: {
+        list: () => Promise<NewsItem[]>;
+        get: (newsId: number) => Promise<NewsItem>;
+    };
+    exams: {
+        list: (opts?: {
+            start?: string;
+            end?: string;
+        }) => Promise<Exam[]>;
+    };
+}

package/dist/client.js

@@ -0,0 +1,105 @@
+import { WilmaSession } from "./session.js";
+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 { parseStudentsFromHome } from "./parsers/students.js";
+export class WilmaClient {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    static async login(profile) {
+        const session = new WilmaSession(profile.baseUrl, {
+            studentNumber: profile.studentNumber ?? null,
+            debug: profile.debug ?? false,
+        });
+        await session.login(profile.username, profile.password);
+        return new WilmaClient(session);
+    }
+    static async listStudents(profile) {
+        const session = new WilmaSession(profile.baseUrl);
+        await session.login(profile.username, profile.password);
+        const resp = await session.get("/");
+        const html = await resp.text();
+        return parseStudentsFromHome(html);
+    }
+    messages = {
+        list: async (folder = "inbox") => {
+            const folderPaths = {
+                inbox: "/messages/list",
+                archive: "/messages/list/archive",
+                outbox: "/messages/list/outbox",
+                drafts: "/messages/list/drafts",
+                appointments: "/messages/list/appointments",
+            };
+            const path = folderPaths[folder] ?? "/messages/list";
+            const resp = await this.session.get(path);
+            const text = await resp.text();
+            const data = safeJson(text);
+            return parseMessagesList(data, folder);
+        },
+        get: async (messageId) => {
+            const resp = await this.session.get(`/messages/${messageId}`);
+            const contentType = resp.headers.get("content-type")?.toLowerCase() ?? "";
+            const text = await resp.text();
+            if (contentType.includes("application/json")) {
+                const data = safeJson(text);
+                return {
+                    wilmaId: messageId,
+                    subject: String(data["Subject"] ?? data["subject"] ?? ""),
+                    sentAt: parseWilmaTimestamp(data["TimeStamp"] ?? data["timestamp"]),
+                    folder: String(data["Folder"] ?? "unknown"),
+                    senderId: data["SenderId"] ?? null,
+                    senderType: data["SenderType"] ?? null,
+                    senderName: (data["Sender"] ?? data["sender"]),
+                    sendersJson: (data["Senders"] ?? data["senders"]),
+                    status: data["Status"] ?? null,
+                    content: (data["Content"] ?? data["content"]),
+                    fetchedAt: new Date(),
+                };
+            }
+            return parseMessageDetailHtml(text, messageId);
+        },
+    };
+    news = {
+        list: async () => {
+            const resp = await this.session.get("/news");
+            const text = await resp.text();
+            const data = safeJson(text);
+            if (Array.isArray(data)) {
+                return parseNewsList(data);
+            }
+            return parseNewsListHtml(text);
+        },
+        get: async (newsId) => {
+            const resp = await this.session.get(`/news/${newsId}`);
+            const contentType = resp.headers.get("content-type")?.toLowerCase() ?? "";
+            const text = await resp.text();
+            if (!contentType.includes("text/html")) {
+                const data = safeJson(text);
+                if (Object.keys(data).length) {
+                    return parseNewsDetailJson(newsId, data);
+                }
+            }
+            return parseNewsDetailHtml(text, newsId);
+        },
+    };
+    exams = {
+        list: async (opts) => {
+            const startQs = opts?.start ? `?start=${opts.start}` : "";
+            const endQs = opts?.end ? `&end=${opts.end}` : "";
+            const resp = await this.session.get(`/exams/calendar${startQs}${endQs}`);
+            const text = await resp.text();
+            return parseExamsHtml(text);
+        },
+    };
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return {};
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { Exam, Message, MessageFolder, Municipality, NewsItem, TenantDiscoveryResponse, TenantInfo, WilmaProfile, StudentInfo, } from "./types.js";
+export { WilmaClient } from "./client.js";
+export { WilmaSession, AuthenticationError, APIError } from "./session.js";
+export { loadTenantDiscovery, listTenants, searchTenantsByMunicipality, findTenantByUrl, } from "./tenants.js";
+export { parseWilmaTimestamp } from "./parsers/dates.js";
+export { parseStudentsFromHome } from "./parsers/students.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { WilmaClient } from "./client.js";
+export { WilmaSession, AuthenticationError, APIError } from "./session.js";
+export { loadTenantDiscovery, listTenants, searchTenantsByMunicipality, findTenantByUrl, } from "./tenants.js";
+export { parseWilmaTimestamp } from "./parsers/dates.js";
+export { parseStudentsFromHome } from "./parsers/students.js";

package/dist/parsers/dates.d.ts

@@ -0,0 +1 @@
+export declare function parseWilmaTimestamp(value: unknown): Date;

package/dist/parsers/dates.js

@@ -0,0 +1,69 @@
+export function parseWilmaTimestamp(value) {
+    if (value === null || value === undefined) {
+        return new Date();
+    }
+    if (typeof value === "number") {
+        return new Date(value * 1000);
+    }
+    const text = String(value)
+        .trim()
+        .toLowerCase()
+        .replace("klo", "")
+        .replace("julkaistu", "")
+        .trim();
+    const now = new Date();
+    const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const rel = {
+        "tänään": 0,
+        "eilen": 1,
+        today: 0,
+        yesterday: 1,
+        idag: 0,
+        "i dag": 0,
+        "igår": 1,
+        "i går": 1,
+    };
+    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;
+        }
+    }
+    for (const fmt of ["dateTime", "dateOnly"]) {
+        if (fmt === "dateTime") {
+            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);
+            }
+        }
+        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);
+            }
+        }
+    }
+    const shortMatch = /^(\d{1,2})\.(\d{1,2})\.$/.exec(text);
+    if (shortMatch) {
+        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);
+        }
+        return candidate;
+    }
+    return now;
+}

package/dist/parsers/exams.d.ts

@@ -0,0 +1,2 @@
+import type { Exam } from "../types.js";
+export declare function parseExamsHtml(html: string): Exam[];

package/dist/parsers/exams.js

@@ -0,0 +1,69 @@
+import * as cheerio from "cheerio";
+export function parseExamsHtml(html) {
+    const $ = cheerio.load(html);
+    const exams = [];
+    let autoId = 1;
+    const now = new Date();
+    $("div.table-responsive.margin-bottom").each((_, block) => {
+        const table = $(block).find("table.table-grey").first();
+        if (!table.length) {
+            return;
+        }
+        const rows = table.find("tr");
+        if (!rows.length) {
+            return;
+        }
+        const firstCells = $(rows.get(0)).find("td");
+        if (firstCells.length < 2) {
+            return;
+        }
+        const dateText = $(firstCells.get(0)).text().trim();
+        const match = /(\d{1,2}\.\d{1,2}\.\d{4})/.exec(dateText);
+        if (!match) {
+            return;
+        }
+        const [d, m, y] = match[1].split(".").map(Number);
+        const examDate = new Date(y, m - 1, d);
+        const subjDesc = $(firstCells.get(1)).text().trim();
+        let subject = subjDesc;
+        let description = null;
+        if (subjDesc.includes(":")) {
+            const parts = subjDesc.split(":");
+            description = parts[0].trim();
+            subject = parts.slice(1).join(":").trim();
+        }
+        let teacher = null;
+        let notes = null;
+        rows.slice(1).each((_, row) => {
+            const th = $(row).find("th").first();
+            const td = $(row).find("td").first();
+            if (!th.length || !td.length) {
+                return;
+            }
+            const header = th.text().trim().toLowerCase();
+            const value = td.text().trim();
+            if (header.includes("opettaja")) {
+                const names = td
+                    .find("a.profile-link")
+                    .toArray()
+                    .map((a) => $(a).text().trim())
+                    .filter(Boolean);
+                teacher = names.length ? names.join(", ") : value;
+            }
+            else if (header.includes("lisätiedot") || header.includes("notes")) {
+                notes = value;
+            }
+        });
+        exams.push({
+            wilmaId: autoId,
+            examDate,
+            subject: subject || "(N/A)",
+            description,
+            teacher,
+            notes,
+            fetchedAt: now,
+        });
+        autoId += 1;
+    });
+    return exams;
+}

package/dist/parsers/messages.d.ts

@@ -0,0 +1,3 @@
+import type { Message, MessageFolder } from "../types.js";
+export declare function parseMessagesList(data: unknown, folder: MessageFolder): Message[];
+export declare function parseMessageDetailHtml(html: string, messageId: number): Message;

package/dist/parsers/messages.js

@@ -0,0 +1,114 @@
+import * as cheerio from "cheerio";
+import { parseWilmaTimestamp } from "./dates.js";
+export function parseMessagesList(data, folder) {
+    const now = new Date();
+    const list = normalizeMessagesList(data);
+    return list.flatMap((item) => {
+        try {
+            const wilmaId = Number(item["id"] ?? item["Id"]);
+            const subject = String(item["Subject"] ?? item["subject"] ?? "");
+            const timeValue = item["Time"] ?? item["time"];
+            return [
+                {
+                    wilmaId,
+                    subject,
+                    sentAt: parseWilmaTimestamp(timeValue),
+                    folder,
+                    fetchedAt: now,
+                },
+            ];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export function parseMessageDetailHtml(html, messageId) {
+    const $ = cheerio.load(html);
+    const panelBody = $("div#page-content-area.panel-body");
+    const subjElem = panelBody.length ? panelBody.children("h1").first() : $("h1, h2, .panel-title, .msg-subject").first();
+    const subject = subjElem.text().trim();
+    let senderName = null;
+    let sentAt = new Date();
+    let sendersJson = null;
+    const propTable = $("table.proptable");
+    if (propTable.length) {
+        propTable.find("tr").each((_, row) => {
+            const th = $(row).find("th").first();
+            const td = $(row).find("td").first();
+            if (!th.length || !td.length) {
+                return;
+            }
+            const header = th.text().trim().toLowerCase();
+            if (header.includes("lähettäjä") || header.includes("sender")) {
+                const senderLink = td.find("a.profile-link").first();
+                if (senderLink.length) {
+                    senderName = senderLink.text().trim();
+                    sendersJson = {
+                        senders: [
+                            {
+                                Name: senderName,
+                                Href: senderLink.attr("href"),
+                            },
+                        ],
+                    };
+                }
+                else {
+                    senderName = td.text().trim();
+                }
+            }
+            else if (header.includes("lähetetty") || header.includes("sent")) {
+                const sentText = td.text().trim();
+                sentAt = parseWilmaTimestamp(sentText);
+            }
+        });
+    }
+    let content = null;
+    const hidden = $("div.ckeditor.hidden").first();
+    if (hidden.length) {
+        content = hidden.text().trim();
+    }
+    if (!content && panelBody.length) {
+        const clone = cheerio.load(panelBody.html() ?? "");
+        ["table.proptable", "h1", "iframe", "script", "style"].forEach((sel) => {
+            clone(sel).remove();
+        });
+        const text = clone.root().text().trim();
+        if (text) {
+            content = text;
+        }
+    }
+    if (!content) {
+        const fallback = $(".message-body, .msg-content").first();
+        if (fallback.length) {
+            fallback.find("script, style").remove();
+            content = fallback.text().trim();
+        }
+    }
+    if (!content || !content.trim()) {
+        content = "(Could not extract content body)";
+    }
+    return {
+        wilmaId: messageId,
+        subject,
+        sentAt,
+        folder: "unknown",
+        senderName,
+        sendersJson,
+        content,
+        fetchedAt: new Date(),
+    };
+}
+function normalizeMessagesList(data) {
+    if (Array.isArray(data)) {
+        return data;
+    }
+    if (data && typeof data === "object") {
+        const obj = data;
+        const list = (obj["messages"] ?? obj["Messages"]);
+        if (Array.isArray(list)) {
+            return list;
+        }
+    }
+    return [];
+}

package/dist/parsers/news.d.ts

@@ -0,0 +1,5 @@
+import type { NewsItem } from "../types.js";
+export declare function parseNewsList(data: unknown): NewsItem[];
+export declare function parseNewsDetailJson(newsId: number, data: Record<string, unknown>): NewsItem;
+export declare function parseNewsDetailHtml(html: string, newsId: number): NewsItem;
+export declare function parseNewsListHtml(html: string): NewsItem[];

package/dist/parsers/news.js

@@ -0,0 +1,138 @@
+import * as cheerio from "cheerio";
+import { parseWilmaTimestamp } from "./dates.js";
+export function parseNewsList(data) {
+    if (Array.isArray(data)) {
+        const now = new Date();
+        return data.flatMap((item) => {
+            try {
+                const wilmaId = Number(item["id"] ?? item["Id"]);
+                const title = String(item["Title"] ?? item["title"] ?? "");
+                const published = parseWilmaTimestamp(item["Published"] ?? item["published"]);
+                return [
+                    {
+                        wilmaId,
+                        title,
+                        published,
+                        fetchedAt: now,
+                    },
+                ];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    return [];
+}
+export function parseNewsDetailJson(newsId, data) {
+    return {
+        wilmaId: newsId,
+        title: String(data["title"] ?? data["Title"] ?? ""),
+        subtitle: (data["subtitle"] ?? data["Subtitle"]),
+        author: (data["author"] ?? data["Author"]),
+        published: parseWilmaTimestamp(data["Published"] ?? data["published"]),
+        content: (data["content"] ?? data["Content"]),
+        fetchedAt: new Date(),
+    };
+}
+export function parseNewsDetailHtml(html, newsId) {
+    const $ = cheerio.load(html);
+    let title = $("title").text().trim();
+    if (title.endsWith(" - Wilma")) {
+        title = title.slice(0, -8).trim();
+    }
+    if (!title) {
+        const titleElem = $("#page-content-area h1, #main-content h1, h1").first();
+        title = titleElem.text().trim();
+    }
+    const subtitleElem = $("p.sub-text, .subtitle").first();
+    const subtitle = subtitleElem.length ? subtitleElem.text().trim() : null;
+    let content = null;
+    const contentElem = $(".panel-body, .news-content, .content, .ckeditor, article").first();
+    if (contentElem.length) {
+        contentElem.find("script, style").remove();
+        content = contentElem.text().trim();
+    }
+    return {
+        wilmaId: newsId,
+        title,
+        subtitle,
+        author: null,
+        published: null,
+        content,
+        fetchedAt: new Date(),
+    };
+}
+export function parseNewsListHtml(html) {
+    const $ = cheerio.load(html);
+    const now = new Date();
+    const newsItems = [];
+    const seenIds = new Set();
+    const headers = $("div.left h2.no-border, h2.no-border");
+    if (!headers.length) {
+        return newsItems;
+    }
+    headers.each((_, header) => {
+        const headerEl = $(header);
+        const timestampRaw = headerEl.text().trim();
+        const published = parseWilmaTimestamp(timestampRaw);
+        let sib = headerEl.next();
+        while (sib.length) {
+            if (sib.is("h2") && sib.hasClass("no-border")) {
+                break;
+            }
+            if (sib.is("div") && (sib.hasClass("well") || sib.hasClass("margin-bottom"))) {
+                const container = sib;
+                const linkTag = container.find("a[href*='/news/']").first();
+                const href = linkTag.attr("href") ?? "";
+                const match = /\/news\/(\d+)/.exec(href);
+                const newsId = match ? Number(match[1]) : null;
+                if (!newsId || seenIds.has(newsId)) {
+                    sib = sib.next();
+                    continue;
+                }
+                seenIds.add(newsId);
+                const titleElem = container.find("h1, h2, h3, h4").first();
+                const title = titleElem.text().trim() || linkTag.text().trim() || "Untitled News";
+                const subtitleElem = container.find("p.sub-text").first();
+                const subtitle = subtitleElem.length ? subtitleElem.text().trim() : null;
+                let author = null;
+                const metaP = container.find("p.small").first();
+                if (metaP.length) {
+                    const authorLink = metaP.find("a.profile-link").first();
+                    if (authorLink.length) {
+                        author = authorLink.attr("title") ?? authorLink.text().trim();
+                    }
+                    else {
+                        const tooltip = metaP.find("span.tooltip").first();
+                        if (tooltip.length) {
+                            author = tooltip.attr("title") ?? tooltip.text().trim();
+                        }
+                        else {
+                            const metaSpan = metaP.find("span.horizontal-link-container.small").first();
+                            if (metaSpan.length) {
+                                const metaText = metaSpan.text().trim();
+                                if (metaText.toLowerCase().includes("ylläpidon tiedote")) {
+                                    author = "Ylläpito";
+                                }
+                                else if (metaText.split(/\s+/).length < 5 && metaText !== linkTag.text().trim()) {
+                                    author = metaText;
+                                }
+                            }
+                        }
+                    }
+                }
+                newsItems.push({
+                    wilmaId: newsId,
+                    title,
+                    subtitle,
+                    author,
+                    published,
+                    fetchedAt: now,
+                });
+            }
+            sib = sib.next();
+        }
+    });
+    return newsItems;
+}

package/dist/parsers/students.d.ts

@@ -0,0 +1,6 @@
+export interface StudentInfo {
+    studentNumber: string;
+    name: string;
+    href: string;
+}
+export declare function parseStudentsFromHome(html: string): StudentInfo[];

package/dist/parsers/students.js

@@ -0,0 +1,44 @@
+import * as cheerio from "cheerio";
+const NAV_KEYWORDS = [
+    "messages",
+    "viestit",
+    "schedule",
+    "lukujärjestys",
+    "gradebook",
+    "assessments",
+    "exams",
+    "attendance",
+    "poissaolot",
+    "printouts",
+    "news",
+];
+export function parseStudentsFromHome(html) {
+    const $ = cheerio.load(html);
+    const students = new Map();
+    $("a[href^='/!']").each((_, anchor) => {
+        const href = $(anchor).attr("href") ?? "";
+        const match = /\/!(\d+)\//.exec(href);
+        if (!match) {
+            return;
+        }
+        const studentNumber = match[1];
+        const cloned = $(anchor).clone();
+        cloned.find("small, span.lem").remove();
+        const text = cloned.text().trim();
+        if (!text) {
+            return;
+        }
+        const lower = text.toLowerCase();
+        if (NAV_KEYWORDS.some((kw) => lower.includes(kw))) {
+            return;
+        }
+        if (!students.has(studentNumber)) {
+            students.set(studentNumber, {
+                studentNumber,
+                name: text,
+                href,
+            });
+        }
+    });
+    return [...students.values()];
+}

package/dist/session.d.ts

@@ -0,0 +1,29 @@
+import { type RequestInit, type Response } from "undici";
+export declare class AuthenticationError extends Error {
+}
+export declare class APIError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+export declare class WilmaSession {
+    private baseUrl;
+    private cookieJar;
+    private loggedIn;
+    private username?;
+    private password?;
+    private studentNumber?;
+    private debug;
+    constructor(baseUrl: string, opts?: {
+        studentNumber?: string | null;
+        debug?: boolean;
+    });
+    get urlPrefix(): string | null;
+    getPrefixedPath(path: string): string;
+    login(username: string, password: string): Promise<void>;
+    private getLoginFormFields;
+    request(path: string, init?: RequestInit): Promise<Response>;
+    get(path: string, init?: RequestInit): Promise<Response>;
+    post(path: string, init?: RequestInit): Promise<Response>;
+    private getLoginToken;
+    private rawRequest;
+}