@wilm-ai/wilma-client 1.5.2 → 1.6.0

package/dist/timeouts.js

@@ -0,0 +1,82 @@
+/*
+ * Idle timeouts for requests and downloads. A request fails when the server
+ * stops answering for a while — before the response, or while the body is
+ * read — not after a fixed total, so a large attachment on a slow connection
+ * still finishes while a stalled one doesn't hang forever.
+ */
+import { Response } from "undici";
+import { NetworkError, wrapNetworkError } from "./network-error.js";
+/** An abort signal that fires after `ms` without progress. */
+export class IdleTimer {
+    ms;
+    controller = new AbortController();
+    timer;
+    constructor(ms) {
+        this.ms = ms;
+        this.touch();
+    }
+    get signal() {
+        return this.controller.signal;
+    }
+    /** Progress: start the wait over. */
+    touch() {
+        clearTimeout(this.timer);
+        this.timer = setTimeout(() => this.controller.abort(new DOMException("The server stopped answering", "TimeoutError")), this.ms);
+        // A response nobody reads must not keep the process alive.
+        this.timer.unref?.();
+    }
+    stop() {
+        clearTimeout(this.timer);
+    }
+}
+/** A timeout or broken connection as a NetworkError; anything else unchanged. */
+export function asNetworkError(err, origin) {
+    if (err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError")) {
+        return new NetworkError(`${origin} didn't answer in time`, { code: "TIMEOUT", origin, cause: err });
+    }
+    return wrapNetworkError(err, origin);
+}
+// Statuses whose responses can't carry a body.
+const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
+/**
+ * The same response, with its body read under the idle timer: each chunk
+ * restarts the wait, and a stall or broken connection while reading surfaces
+ * as a NetworkError, like one before the response.
+ */
+export function watchBody(response, idle, origin) {
+    if (!response.body || NULL_BODY_STATUSES.has(response.status)) {
+        idle.stop();
+        return response;
+    }
+    const reader = response.body.getReader();
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                const { done, value } = await reader.read();
+                if (done) {
+                    idle.stop();
+                    controller.close();
+                    return;
+                }
+                idle.touch();
+                controller.enqueue(value);
+            }
+            catch (err) {
+                idle.stop();
+                controller.error(asNetworkError(err, origin));
+            }
+        },
+        cancel(reason) {
+            idle.stop();
+            return reader.cancel(reason);
+        },
+    });
+    const watched = new Response(body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+    // Parsers resolve links against the final address.
+    Object.defineProperty(watched, "url", { value: response.url });
+    return watched;
+}

package/dist/types.d.ts

@@ -9,9 +9,23 @@ export interface Message {
     senderName?: string | null;
     sendersJson?: Record<string, unknown> | null;
     status?: number | null;
+    /** In lists: Wilma hasn't seen it opened yet. */
+    unread?: boolean;
+    /** In lists: how many replies the thread has (read them with the message). */
+    replyCount?: number;
     content?: string | null;
+    /** Message detail: who it went to (Wilma may hide the list). */
+    recipients?: string[] | null;
+    /** Message detail: the thread's replies, oldest first. */
+    replies?: MessageReply[];
     fetchedAt: Date;
 }
+export interface MessageReply {
+    id: number;
+    sentAt: Date;
+    senderName: string | null;
+    content: string;
+}
 export interface NewsItem {
     wilmaId: number;
     title: string;
@@ -20,6 +34,10 @@ export interface NewsItem {
     published?: Date | null;
     content?: string | null;
     resources?: NewsResource[];
+    /** A pinned bulletin (Wilma: "Pysyvät tiedotteet"), kept on the page until removed. */
+    pinned?: boolean;
+    /** Listed among older bulletins (Wilma: "Vanhat tiedotteet"); its date is on the bulletin itself. */
+    archived?: boolean;
     fetchedAt: Date;
 }
 export type NewsResourceAuthContext = "external" | "wilma";
@@ -39,6 +57,8 @@ export interface Exam {
     description?: string | null;
     teacher?: string | null;
     notes?: string | null;
+    /** Start time ("08:30") when the school gives one; only the exam calendar has it. */
+    time?: string | null;
     fetchedAt: Date;
 }
 export interface StudentInfo {
@@ -78,11 +98,15 @@ export interface ScheduleLesson {
     teacher: string;
     teacherCode: string;
     groupId: number;
+    /** Room code(s), e.g. "407"; null when Wilma gives none. */
+    room?: string | null;
 }
 export interface UpcomingExam {
     examId: number;
     /** YYYY-MM-DD */
     date: string;
+    /** Start time ("08:30") when the school gives one (from the exam calendar). */
+    time?: string | null;
     name: string;
     subject: string;
     subjectCode: string;
@@ -133,4 +157,36 @@ export interface LessonNote {
     typeLabel: string;
     typeClass: string;
     teacher: string;
+    /** The teacher's own words, when they wrote any (e.g. what was missing, or praise). */
+    note?: string | null;
+}
+/** How many lesson notes of each kind in a period (absences, lateness, feedback…). */
+export interface LessonNoteSummary {
+    /** YYYY-MM-DD, or null for "the whole school year" as Wilma defines it. */
+    from: string | null;
+    to: string | null;
+    total: number;
+    byType: {
+        type: string;
+        count: number;
+    }[];
+}
+/** One row of the gradebook (Suoritukset): a subject, a syllabus or a course, with its sub-rows. */
+export interface GradebookEntry {
+    name: string;
+    /** Course code such as "MA_81" (null for subject rows). */
+    code: string | null;
+    grade: string | null;
+    /** Scope as Wilma shows it (e.g. "2 vvt"), if any. */
+    credits: string | null;
+    /** YYYY-MM-DD when completed. */
+    date: string | null;
+    children: GradebookEntry[];
+}
+/** A printable document Wilma offers as a PDF (report cards, absence reports…). */
+export interface Printout {
+    id: string;
+    title: string;
+    /** Path on this Wilma, e.g. "/!123/printouts/456.pdf". */
+    path: string;
 }

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "@wilm-ai/wilma-client",
-  "version": "1.5.2",
+  "version": "1.6.0",
+  "description": "Unofficial client for Wilma, the Finnish school information system: login (with two-step verification), schedule, homework, exams, messages and news.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aikarjal/wilmai.git",
+    "directory": "packages/wilma-client"
+  },
+  "homepage": "https://wilm.ai",
+  "bugs": "https://github.com/aikarjal/wilmai/issues",
+  "engines": {
+    "node": ">=20.18.1"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,19 +24,21 @@
   },
   "files": [
     "dist",
-    "tenant_list.json"
+    "tenant_list.json",
+    "LICENSE",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "lint": "echo 'add lint'",
-    "test": "pnpm run build && node test/parser-messages.mjs && node test/parser-news.mjs && node test/parser-schedule.mjs && node test/parser-students.mjs && node test/client-students.mjs && node test/client-schedule.mjs && node test/client-news-resources.mjs && node test/network-error.mjs",
-    "test:smoke": "tsc -p tsconfig.json && node test/smoke.mjs",
-    "test:live": "tsc -p tsconfig.json && node test/live.spec.mjs"
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node test/login.mjs && node test/parser-messages.mjs && node test/parser-news.mjs && node test/parser-schedule.mjs && node test/parser-students.mjs && node test/client-students.mjs && node test/client-schedule.mjs && node test/client-news-resources.mjs && node test/network-error.mjs && node test/audit.mjs && node test/real-pages.mjs && node test/client-features.mjs",
+    "test:live": "tsc -p tsconfig.json && node test/live.spec.mjs",
+    "fixtures:anonymize": "node scripts/anonymize-fixture.mjs"
   },
   "dependencies": {
     "cheerio": "^1.0.0-rc.12",
     "tough-cookie": "^4.1.4",
-    "undici": "^6.19.8"
+    "undici": "^6.27.0"
   },
   "devDependencies": {
     "typescript": "^5.6.3",