@wilm-ai/wilma-client 0.0.4 → 1.1.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { Exam, Message, MessageFolder, NewsItem, WilmaProfile, StudentInfo } from "./types.js";
+import type { Exam, Message, MessageFolder, NewsItem, OverviewData, WilmaProfile, StudentInfo } from "./types.js";
 export declare class WilmaClient {
     private session;
     private constructor();
@@ -18,4 +18,7 @@ export declare class WilmaClient {
             end?: string;
         }) => Promise<Exam[]>;
     };
+    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 { parseOverview } from "./parsers/overview.js";
 import { parseStudentsFromHome } from "./parsers/students.js";
 export class WilmaClient {
     session;
@@ -87,13 +88,27 @@ export class WilmaClient {
     };
     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 params = new URLSearchParams();
+            if (opts?.start) {
+                params.set("start", opts.start);
+            }
+            if (opts?.end) {
+                params.set("end", opts.end);
+            }
+            const query = params.toString();
+            const path = query ? `/exams/calendar?${query}` : "/exams/calendar";
+            const resp = await this.session.get(path);
             const text = await resp.text();
             return parseExamsHtml(text);
         },
     };
+    overview = {
+        get: async () => {
+            const resp = await this.session.get("/overview");
+            const text = await resp.text();
+            return parseOverview(safeJson(text));
+        },
+    };
 }
 function safeJson(text) {
     try {

package/dist/index.d.ts

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

package/dist/parsers/dates.js

@@ -1,9 +1,15 @@
 export function parseWilmaTimestamp(value) {
     if (value === null || value === undefined) {
-        return new Date();
+        return fallbackDate();
     }
     if (typeof value === "number") {
-        return new Date(value * 1000);
+        if (!Number.isFinite(value)) {
+            return fallbackDate();
+        }
+        // Wilma can provide Unix seconds or milliseconds.
+        // Values >= 1e12 are treated as milliseconds.
+        const millis = Math.abs(value) >= 1_000_000_000_000 ? value : value * 1000;
+        return new Date(millis);
     }
     const raw = String(value).trim();
     // Try ISO 8601 format first (e.g., "2026-02-05T13:56:42.737Z")
@@ -84,5 +90,10 @@ export function parseWilmaTimestamp(value) {
         }
         return candidate;
     }
-    return now;
+    return fallbackDate();
+}
+function fallbackDate() {
+    // Keep unknown timestamps deterministic and old so recency filters
+    // do not treat undated items as fresh.
+    return new Date(0);
 }

package/dist/parsers/overview.d.ts

@@ -0,0 +1,2 @@
+import type { OverviewData } from "../types.js";
+export declare function parseOverview(raw: unknown): OverviewData;

package/dist/parsers/overview.js

@@ -0,0 +1,152 @@
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                           */
+/* ------------------------------------------------------------------ */
+/** "4.9.2025" → "2025-09-04", passes through "2025-09-04" unchanged */
+function parseFinnishDate(raw) {
+    const trimmed = raw.trim();
+    if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed))
+        return trimmed;
+    const m = /^(\d{1,2})\.(\d{1,2})\.(\d{4})$/.exec(trimmed);
+    if (m) {
+        return `${m[3]}-${m[2].padStart(2, "0")}-${m[1].padStart(2, "0")}`;
+    }
+    return trimmed;
+}
+function firstTeacher(teachers) {
+    const t = teachers?.[0];
+    return { name: t?.TeacherName ?? "", code: t?.TeacherCode ?? "" };
+}
+function firstScheduleTeacher(teachers) {
+    const t = teachers?.[0];
+    return { name: t?.LongCaption ?? "", code: t?.Caption ?? "" };
+}
+/* ------------------------------------------------------------------ */
+/*  Main parser                                                       */
+/* ------------------------------------------------------------------ */
+export function parseOverview(raw) {
+    const data = (raw ?? {});
+    const now = new Date();
+    const today = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
+    return {
+        schedule: parseSchedule(data.Schedule ?? []),
+        upcomingExams: parseUpcomingExams(data.Groups ?? [], today),
+        grades: parseTopLevelGrades(data.Exams ?? []),
+        homework: parseHomework(data.Groups ?? []),
+        fetchedAt: now,
+    };
+}
+/* ------------------------------------------------------------------ */
+/*  Schedule                                                          */
+/* ------------------------------------------------------------------ */
+function parseSchedule(entries) {
+    const lessons = [];
+    for (const entry of entries) {
+        const dates = entry.DateArray ?? [];
+        const groups = entry.Groups ?? [];
+        const day = entry.Day ?? 0;
+        const start = entry.Start ?? "";
+        const end = entry.End ?? "";
+        for (const date of dates) {
+            for (const group of groups) {
+                const teacher = firstScheduleTeacher(group.Teachers);
+                lessons.push({
+                    date,
+                    dayOfWeek: day,
+                    start,
+                    end,
+                    subject: group.FullCaption ?? group.Caption ?? "",
+                    subjectCode: group.ShortCaption ?? "",
+                    teacher: teacher.name,
+                    teacherCode: teacher.code,
+                    groupId: group.Id ?? 0,
+                });
+            }
+        }
+    }
+    lessons.sort((a, b) => a.date.localeCompare(b.date) || a.start.localeCompare(b.start));
+    return lessons;
+}
+/* ------------------------------------------------------------------ */
+/*  Exams & Grades (from Groups[].Exams[])                            */
+/* ------------------------------------------------------------------ */
+/** Upcoming exams from Groups[].Exams[] — has ungraded exams with Caption/Topic */
+function parseUpcomingExams(groups, today) {
+    const upcoming = [];
+    for (const group of groups) {
+        const teacher = firstTeacher(group.Teachers);
+        const subject = group.CourseName ?? "";
+        const subjectCode = group.CourseCode ?? "";
+        for (const exam of group.Exams ?? []) {
+            // Skip exams that already have a grade
+            if (exam.Grade != null && String(exam.Grade).trim() !== "")
+                continue;
+            const date = parseFinnishDate(exam.Date ?? "");
+            // Only include today or future
+            if (date < today)
+                continue;
+            upcoming.push({
+                examId: exam.Id ?? 0,
+                date,
+                name: exam.Caption ?? exam.Name ?? "",
+                subject,
+                subjectCode,
+                topic: exam.Topic?.trim() || null,
+                teacher: teacher.name,
+                teacherCode: teacher.code,
+            });
+        }
+    }
+    upcoming.sort((a, b) => a.date.localeCompare(b.date));
+    return upcoming;
+}
+/** Grades from top-level Exams[] — authoritative source for all graded exams */
+function parseTopLevelGrades(exams) {
+    const grades = [];
+    for (const exam of exams) {
+        const grade = String(exam.Grade ?? "").trim();
+        if (!grade)
+            continue;
+        const date = parseFinnishDate(exam.Date ?? "");
+        const teacher = exam.Teachers?.[0];
+        grades.push({
+            examId: exam.ExamId ?? exam.Id ?? 0,
+            date,
+            name: exam.Name ?? "",
+            subject: exam.CourseTitle ?? "",
+            subjectCode: (exam.Course ?? "").split(" ")[0],
+            grade,
+            verbalGrade: null,
+            info: exam.Info?.trim() || null,
+            teacher: teacher?.TeacherName ?? "",
+            teacherCode: teacher?.TeacherCode ?? "",
+        });
+    }
+    grades.sort((a, b) => b.date.localeCompare(a.date));
+    return grades;
+}
+/* ------------------------------------------------------------------ */
+/*  Homework (from Groups[].Homework[])                               */
+/* ------------------------------------------------------------------ */
+function parseHomework(groups) {
+    const items = [];
+    for (const group of groups) {
+        const teacher = firstTeacher(group.Teachers);
+        const subject = group.CourseName ?? "";
+        const subjectCode = group.CourseCode ?? "";
+        for (const hw of group.Homework ?? []) {
+            const text = (hw.Homework ?? "").replace(/\r\n/g, "\n").trim();
+            if (!text)
+                continue;
+            items.push({
+                date: hw.Date ?? "",
+                subject,
+                subjectCode,
+                homework: text,
+                teacher: teacher.name,
+                teacherCode: teacher.code,
+            });
+        }
+    }
+    items.sort((a, b) => b.date.localeCompare(a.date));
+    return items;
+}

package/dist/types.d.ts

@@ -57,3 +57,56 @@ export interface WilmaProfile {
     studentNumber?: string | null;
     debug?: boolean;
 }
+export interface ScheduleLesson {
+    /** YYYY-MM-DD */
+    date: string;
+    /** 1=Monday ... 5=Friday */
+    dayOfWeek: number;
+    start: string;
+    end: string;
+    subject: string;
+    subjectCode: string;
+    teacher: string;
+    teacherCode: string;
+    groupId: number;
+}
+export interface UpcomingExam {
+    examId: number;
+    /** YYYY-MM-DD */
+    date: string;
+    name: string;
+    subject: string;
+    subjectCode: string;
+    topic: string | null;
+    teacher: string;
+    teacherCode: string;
+}
+export interface ExamGrade {
+    examId: number;
+    /** YYYY-MM-DD */
+    date: string;
+    name: string;
+    subject: string;
+    subjectCode: string;
+    grade: string;
+    verbalGrade: string | null;
+    info: string | null;
+    teacher: string;
+    teacherCode: string;
+}
+export interface HomeworkItem {
+    /** YYYY-MM-DD */
+    date: string;
+    subject: string;
+    subjectCode: string;
+    homework: string;
+    teacher: string;
+    teacherCode: string;
+}
+export interface OverviewData {
+    schedule: ScheduleLesson[];
+    upcomingExams: UpcomingExam[];
+    grades: ExamGrade[];
+    homework: HomeworkItem[];
+    fetchedAt: Date;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wilm-ai/wilma-client",
-  "version": "0.0.4",
+  "version": "1.1.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",