@wilm-ai/wilma-client 1.1.0 → 1.2.0

package/dist/client.d.ts

@@ -1,9 +1,10 @@
 import type { Exam, Message, MessageFolder, NewsItem, OverviewData, WilmaProfile, StudentInfo } from "./types.js";
+export type MfaCallback = (formkey: string) => Promise<string>;
 export declare class WilmaClient {
     private session;
     private constructor();
-    static login(profile: WilmaProfile): Promise<WilmaClient>;
-    static listStudents(profile: WilmaProfile): Promise<StudentInfo[]>;
+    static login(profile: WilmaProfile, onMfaRequired?: MfaCallback): Promise<WilmaClient>;
+    static listStudents(profile: WilmaProfile, onMfaRequired?: MfaCallback): Promise<StudentInfo[]>;
     messages: {
         list: (folder?: MessageFolder) => Promise<Message[]>;
         get: (messageId: number) => Promise<Message>;

package/dist/client.js

@@ -1,4 +1,4 @@
-import { WilmaSession } from "./session.js";
+import { WilmaSession, MfaRequiredError } 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";
@@ -10,17 +10,39 @@ export class WilmaClient {
     constructor(session) {
         this.session = session;
     }
-    static async login(profile) {
+    static async login(profile, onMfaRequired) {
         const session = new WilmaSession(profile.baseUrl, {
             studentNumber: profile.studentNumber ?? null,
             debug: profile.debug ?? false,
         });
-        await session.login(profile.username, profile.password);
+        try {
+            await session.login(profile.username, profile.password);
+        }
+        catch (err) {
+            if (err instanceof MfaRequiredError && onMfaRequired) {
+                const otpCode = await onMfaRequired(err.formkey);
+                await session.submitMfaCode(err.formkey, otpCode);
+            }
+            else {
+                throw err;
+            }
+        }
         return new WilmaClient(session);
     }
-    static async listStudents(profile) {
+    static async listStudents(profile, onMfaRequired) {
         const session = new WilmaSession(profile.baseUrl);
-        await session.login(profile.username, profile.password);
+        try {
+            await session.login(profile.username, profile.password);
+        }
+        catch (err) {
+            if (err instanceof MfaRequiredError && onMfaRequired) {
+                const otpCode = await onMfaRequired(err.formkey);
+                await session.submitMfaCode(err.formkey, otpCode);
+            }
+            else {
+                throw err;
+            }
+        }
         const resp = await session.get("/");
         const html = await resp.text();
         return parseStudentsFromHome(html);

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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 type { MfaCallback } from "./client.js";
+export { WilmaSession, AuthenticationError, MfaRequiredError, 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

@@ -1,5 +1,5 @@
 export { WilmaClient } from "./client.js";
-export { WilmaSession, AuthenticationError, APIError } from "./session.js";
+export { WilmaSession, AuthenticationError, MfaRequiredError, 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/session.d.ts

@@ -1,6 +1,10 @@
 import { type RequestInit, type Response } from "undici";
 export declare class AuthenticationError extends Error {
 }
+export declare class MfaRequiredError extends Error {
+    formkey: string;
+    constructor(formkey: string);
+}
 export declare class APIError extends Error {
     status: number;
     constructor(message: string, status: number);
@@ -20,6 +24,7 @@ export declare class WilmaSession {
     get urlPrefix(): string | null;
     getPrefixedPath(path: string): string;
     login(username: string, password: string): Promise<void>;
+    submitMfaCode(formkey: string, otpCode: string): Promise<void>;
     private getLoginFormFields;
     request(path: string, init?: RequestInit): Promise<Response>;
     get(path: string, init?: RequestInit): Promise<Response>;

package/dist/session.js

@@ -2,6 +2,13 @@ import { CookieJar } from "tough-cookie";
 import { fetch } from "undici";
 export class AuthenticationError extends Error {
 }
+export class MfaRequiredError extends Error {
+    formkey;
+    constructor(formkey) {
+        super("MFA verification required");
+        this.formkey = formkey;
+    }
+}
 export class APIError extends Error {
     status;
     constructor(message, status) {
@@ -65,6 +72,24 @@ export class WilmaSession {
             .getCookiesSync(this.baseUrl)
             .some((c) => c.key === "Wilma2SID");
         const text = await resp.text();
+        // Check for MFA challenge by following the post-login redirect
+        if (resp.status >= 300 && resp.status < 400 && hasSessionCookie) {
+            const location = resp.headers.get("location");
+            if (location) {
+                const redirectResp = await this.rawRequest(new URL(location).pathname + new URL(location).search, { method: "GET" });
+                const redirectText = await redirectResp.text();
+                const mfaFormkeyMatch = /id="mfa-formkey"\s+value="([^"]+)"/.exec(redirectText);
+                if (mfaFormkeyMatch) {
+                    if (this.debug) {
+                        console.log(`[wilmai] MFA challenge detected`);
+                    }
+                    // Store credentials so we can complete login after MFA
+                    this.username = username;
+                    this.password = password;
+                    throw new MfaRequiredError(mfaFormkeyMatch[1]);
+                }
+            }
+        }
         if (hasSessionCookie || isLoginOk(text)) {
             this.loggedIn = true;
             this.username = username;
@@ -73,6 +98,43 @@ export class WilmaSession {
         }
         throw new AuthenticationError("Wilma login failed");
     }
+    async submitMfaCode(formkey, otpCode) {
+        // Wilma's MFA endpoint: POST /api/v1/accounts/me/mfa/otp/check
+        // Body: formkey=<formkey>&payload={"otp":"<code>","action":"login"}
+        // No student prefix — MFA is account-level, not student-level
+        const path = `/api/v1/accounts/me/mfa/otp/check`;
+        const body = new URLSearchParams({
+            formkey,
+            payload: JSON.stringify({ otp: otpCode, action: "login" }),
+        });
+        if (this.debug) {
+            console.log(`[wilmai] POST ${path} (MFA OTP check)`);
+        }
+        const resp = await this.rawRequest(path, {
+            method: "POST",
+            body: body.toString(),
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
+            },
+        });
+        const text = await resp.text();
+        let success = false;
+        try {
+            const data = JSON.parse(text);
+            // Response format: { statusCode, payload: { success } } or { success }
+            success = data?.payload?.success ?? data?.success ?? false;
+        }
+        catch {
+            throw new AuthenticationError("MFA verification failed: unexpected response");
+        }
+        if (!success) {
+            throw new AuthenticationError("MFA verification failed: invalid OTP code");
+        }
+        this.loggedIn = true;
+        if (this.debug) {
+            console.log(`[wilmai] MFA verification successful`);
+        }
+    }
     async getLoginFormFields() {
         const resp = await this.rawRequest("/login", { method: "GET" });
         if (resp.status >= 400) {
@@ -92,6 +154,9 @@ export class WilmaSession {
             await this.login(this.username, this.password);
             resp = await this.rawRequest(prefixedPath, init);
         }
+        if (this.debug) {
+            console.log(`[wilmai] ${init?.method ?? "GET"} ${prefixedPath} => ${resp.status}`);
+        }
         if (resp.status >= 400) {
             throw new APIError(`Wilma HTTP ${resp.status} at ${prefixedPath}`, resp.status);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wilm-ai/wilma-client",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,6 +14,13 @@
     "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",
@@ -22,12 +29,5 @@
   "devDependencies": {
     "typescript": "^5.6.3",
     "@types/tough-cookie": "^4.0.5"
-  },
-  "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"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-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.