@wilm-ai/wilma-client 1.5.0 → 1.5.2

package/dist/client.js

@@ -6,9 +6,10 @@ import { parseExamsHtml } from "./parsers/exams.js";
 import { parseAttendanceHtml } from "./parsers/attendance.js";
 import { parseOverview } from "./parsers/overview.js";
 import { parseScheduleHtml } from "./parsers/schedule.js";
-import { parseStudentsFromHome } from "./parsers/students.js";
+import { parseStudentsFromAccountsRoles, parseStudentsFromHome } from "./parsers/students.js";
 import { CookieJar } from "tough-cookie";
 import { fetch, Headers } from "undici";
+import { NetworkError, wrapNetworkError } from "./network-error.js";
 const EXTERNAL_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) " +
     "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0 Safari/537.36";
 export class WilmaClient {
@@ -36,7 +37,9 @@ export class WilmaClient {
         return new WilmaClient(session);
     }
     static async listStudents(profile, onMfaRequired) {
-        const session = new WilmaSession(profile.baseUrl);
+        const session = new WilmaSession(profile.baseUrl, {
+            debug: profile.debug ?? false,
+        });
         try {
             await session.login(profile.username, profile.password);
         }
@@ -49,9 +52,27 @@ export class WilmaClient {
                 throw err;
             }
         }
+        try {
+            const accountsResp = await session.get("/api/v1/accounts/me/roles");
+            const accountsText = await accountsResp.text();
+            const fromAccounts = parseStudentsFromAccountsRoles(safeJson(accountsText));
+            if (fromAccounts.length > 0) {
+                return fromAccounts;
+            }
+        }
+        catch (err) {
+            if (err instanceof NetworkError) {
+                throw err;
+            }
+            // API missing or not JSON (e.g. 404 on older Wilma)
+        }
         const resp = await session.get("/");
         const html = await resp.text();
-        return parseStudentsFromHome(html);
+        const fromHome = parseStudentsFromHome(html, resp.url);
+        if (fromHome.length > 0) {
+            return fromHome;
+        }
+        return [];
     }
     messages = {
         list: async (folder = "inbox") => {
@@ -238,7 +259,13 @@ async function fetchFollowingRedirects(initialUrl) {
         if (cookieHeader) {
             headers.set("Cookie", cookieHeader);
         }
-        const response = await fetch(currentUrl, { headers, redirect: "manual" });
+        let response;
+        try {
+            response = await fetch(currentUrl, { headers, redirect: "manual" });
+        }
+        catch (err) {
+            throw wrapNetworkError(err, currentUrl.href);
+        }
         const setCookies = response.headers
             .getSetCookie?.() ?? [];
         for (const cookie of setCookies) {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export type { Exam, ExamGrade, HomeworkItem, LessonNote, Message, MessageFolder,
 export { WilmaClient } from "./client.js";
 export type { MfaCallback } from "./client.js";
 export { WilmaSession, AuthenticationError, MfaRequiredError, APIError } from "./session.js";
+export { NetworkError, describeNetworkCode, extractCauseCode, wrapNetworkError, } from "./network-error.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,6 @@
 export { WilmaClient } from "./client.js";
 export { WilmaSession, AuthenticationError, MfaRequiredError, APIError } from "./session.js";
+export { NetworkError, describeNetworkCode, extractCauseCode, wrapNetworkError, } from "./network-error.js";
 export { loadTenantDiscovery, listTenants, searchTenantsByMunicipality, findTenantByUrl, } from "./tenants.js";
 export { parseWilmaTimestamp } from "./parsers/dates.js";
 export { parseStudentsFromHome } from "./parsers/students.js";

package/dist/network-error.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Classification of network-level request failures.
+ *
+ * `fetch` rejects with an opaque `TypeError: fetch failed` and puts the real
+ * reason on `error.cause`. Reporting only `error.message` therefore tells the
+ * user nothing at all — the most common real cause, a TLS-intercepting proxy on
+ * the network, is indistinguishable from being offline.
+ *
+ * This module walks the cause chain, extracts the underlying code, and pairs it
+ * with actionable remediation text.
+ */
+/** A request that never produced an HTTP response (DNS, TCP or TLS failure). */
+export declare class NetworkError extends Error {
+    /** Underlying cause code, e.g. `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`. */
+    readonly code?: string;
+    /** Multi-line remediation text, when the cause is recognised. */
+    readonly hint?: string;
+    /** Origin that failed (scheme and host only — never a path). */
+    readonly origin?: string;
+    constructor(message: string, options?: {
+        code?: string;
+        hint?: string;
+        origin?: string;
+        cause?: unknown;
+    });
+}
+/** Human-readable summary plus remediation for a known cause code. */
+export declare function describeNetworkCode(code: string | undefined, origin?: string): {
+    summary: string;
+    hint?: string;
+};
+/** Walk the cause chain for the first string `code` property. */
+export declare function extractCauseCode(error: unknown, maxDepth?: number): string | undefined;
+/**
+ * Convert a thrown `fetch` rejection into a `NetworkError` carrying an
+ * actionable hint. Anything that is not a transport failure is returned
+ * unchanged, so callers can `throw wrapNetworkError(err, url)` safely.
+ */
+export declare function wrapNetworkError(error: unknown, url: string): unknown;

package/dist/network-error.js

@@ -0,0 +1,171 @@
+/**
+ * Classification of network-level request failures.
+ *
+ * `fetch` rejects with an opaque `TypeError: fetch failed` and puts the real
+ * reason on `error.cause`. Reporting only `error.message` therefore tells the
+ * user nothing at all — the most common real cause, a TLS-intercepting proxy on
+ * the network, is indistinguishable from being offline.
+ *
+ * This module walks the cause chain, extracts the underlying code, and pairs it
+ * with actionable remediation text.
+ */
+/** A request that never produced an HTTP response (DNS, TCP or TLS failure). */
+export class NetworkError extends Error {
+    /** Underlying cause code, e.g. `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`. */
+    code;
+    /** Multi-line remediation text, when the cause is recognised. */
+    hint;
+    /** Origin that failed (scheme and host only — never a path). */
+    origin;
+    constructor(message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = "NetworkError";
+        this.code = options.code;
+        this.hint = options.hint;
+        this.origin = options.origin;
+    }
+}
+/**
+ * Certificate-chain failures. Every one of these means "Node could not build a
+ * trust path", which on a managed device almost always means TLS interception.
+ */
+const TLS_TRUST_CODES = new Set([
+    "UNABLE_TO_GET_ISSUER_CERT",
+    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "CERT_UNTRUSTED",
+]);
+const DNS_CODES = new Set(["ENOTFOUND", "EAI_AGAIN"]);
+const TIMEOUT_CODES = new Set([
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "ETIMEDOUT",
+]);
+function tlsTrustHint() {
+    return [
+        "The network appears to intercept TLS traffic (\"break-and-inspect\"), re-signing",
+        "certificates with a private root CA. This is common on managed devices behind a",
+        "corporate secure web gateway. Node ships its own CA bundle and ignores the",
+        "operating system trust store, so a root your browser already trusts is invisible",
+        "to Node.",
+        "",
+        "Fix, in order of preference:",
+        "  1. Node >=22.19 / >=24.6   NODE_USE_SYSTEM_CA=1 wilma <command>",
+        "  2. Node >=22.15            node --use-system-ca \"$(command -v wilma)\" <command>",
+        "  3. Trust the root directly NODE_EXTRA_CA_CERTS=/path/to/root-ca.pem wilma <command>",
+        "",
+        "Do not set NODE_TLS_REJECT_UNAUTHORIZED=0. It disables certificate verification",
+        "entirely, on a network that is already inspecting your traffic.",
+    ].join("\n");
+}
+/** Human-readable summary plus remediation for a known cause code. */
+export function describeNetworkCode(code, origin) {
+    const where = origin ? ` for ${origin}` : "";
+    if (code && TLS_TRUST_CODES.has(code)) {
+        return {
+            summary: `TLS certificate verification failed${where} (${code})`,
+            hint: tlsTrustHint(),
+        };
+    }
+    if (code === "CERT_HAS_EXPIRED") {
+        return {
+            summary: `The certificate presented${where} has expired (${code})`,
+            hint: [
+                "Check the system clock first — a clock that is wrong by days will produce this.",
+                "If the clock is correct, a TLS-intercepting proxy on the network may be",
+                "presenting a stale certificate.",
+            ].join("\n"),
+        };
+    }
+    if (code === "ERR_TLS_CERT_ALTNAME_INVALID") {
+        return {
+            summary: `The certificate presented${where} does not match that hostname (${code})`,
+            hint: [
+                "Check that the tenant URL is correct. A TLS-intercepting proxy can also cause",
+                "this if it re-signs with a certificate issued for a different name.",
+            ].join("\n"),
+        };
+    }
+    if (code && DNS_CODES.has(code)) {
+        return {
+            summary: `Could not resolve the Wilma host${where} (${code})`,
+            hint: [
+                "Check the tenant URL and that you are online. On a VPN or split-tunnel network",
+                "the host may only resolve while connected.",
+            ].join("\n"),
+        };
+    }
+    if (code === "ECONNREFUSED") {
+        return {
+            summary: `Connection refused${where} (${code})`,
+            hint: "The host may be down, or a local firewall or proxy may be blocking the request.",
+        };
+    }
+    if (code && TIMEOUT_CODES.has(code)) {
+        return {
+            summary: `Connection timed out${where} (${code})`,
+            hint: "Check your network. A proxy or firewall may be silently dropping the request.",
+        };
+    }
+    if (code === "ECONNRESET") {
+        return {
+            summary: `Connection reset${where} (${code})`,
+            hint: "This is often a proxy or firewall interrupting the request.",
+        };
+    }
+    // Unrecognised: still surface the code rather than swallowing it.
+    return {
+        summary: code
+            ? `Request failed${where} (${code})`
+            : `Request failed${where}`,
+    };
+}
+/** Walk the cause chain for the first string `code` property. */
+export function extractCauseCode(error, maxDepth = 5) {
+    let current = error;
+    for (let depth = 0; depth < maxDepth && current; depth += 1) {
+        const code = current.code;
+        if (typeof code === "string" && code.length > 0) {
+            return code;
+        }
+        current = current.cause;
+    }
+    return undefined;
+}
+/**
+ * Scheme and host only. Wilma paths embed student numbers, so the full URL must
+ * never reach an error message or a log line.
+ */
+function safeOrigin(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+function looksLikeFetchFailure(error) {
+    if (!(error instanceof Error))
+        return false;
+    return error.message === "fetch failed" || error.name === "TypeError";
+}
+/**
+ * Convert a thrown `fetch` rejection into a `NetworkError` carrying an
+ * actionable hint. Anything that is not a transport failure is returned
+ * unchanged, so callers can `throw wrapNetworkError(err, url)` safely.
+ */
+export function wrapNetworkError(error, url) {
+    if (error instanceof NetworkError) {
+        return error;
+    }
+    const code = extractCauseCode(error);
+    if (!code && !looksLikeFetchFailure(error)) {
+        return error;
+    }
+    const origin = safeOrigin(url);
+    const { summary, hint } = describeNetworkCode(code, origin);
+    return new NetworkError(summary, { code, hint, origin, cause: error });
+}

package/dist/parsers/students.d.ts

@@ -3,4 +3,13 @@ export interface StudentInfo {
     name: string;
     href: string;
 }
-export declare function parseStudentsFromHome(html: string): StudentInfo[];
+export declare function studentNumberFromHref(href: string): string | null;
+export declare function parseStudentFromUrl(url: string): StudentInfo | null;
+/**
+ * Parse GET /api/v1/accounts/me/roles.
+ * Accepts `{ payload: AccountRole[] }` or a raw array.
+ * Skips the account itself (`type === "passwd"` / type 7). Guardian (and other
+ * non-passwd) roles contribute a student from `slug` + `name`.
+ */
+export declare function parseStudentsFromAccountsRoles(data: unknown): StudentInfo[];
+export declare function parseStudentsFromHome(html: string, pageUrl?: string): StudentInfo[];

package/dist/parsers/students.js

@@ -12,16 +12,106 @@ const NAV_KEYWORDS = [
     "printouts",
     "news",
 ];
-export function parseStudentsFromHome(html) {
-    const $ = cheerio.load(html);
+const STUDENT_HREF_RE = /\/!(\d+)(?:\/|$)/;
+export function studentNumberFromHref(href) {
+    const match = STUDENT_HREF_RE.exec(href);
+    return match ? match[1] : null;
+}
+function isPasswdAccountRole(type) {
+    return type === "passwd" || type === 7 || type === "7";
+}
+function studentNumberFromSlug(slug) {
+    const trimmed = slug.trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (/^\d+$/.test(trimmed)) {
+        return trimmed;
+    }
+    const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return studentNumberFromHref(withSlash);
+}
+export function parseStudentFromUrl(url) {
+    const studentNumber = studentNumberFromHref(url);
+    if (!studentNumber) {
+        return null;
+    }
+    return {
+        studentNumber,
+        name: studentNumber,
+        href: `/!${studentNumber}/`,
+    };
+}
+function roleType(rec) {
+    return rec.Type ?? rec.type ?? rec.RoleType ?? rec.roleType;
+}
+function roleName(rec, fallback) {
+    return String(rec.Name ?? rec.name ?? rec.Caption ?? rec.caption ?? fallback);
+}
+function collectStudent(students, studentNumber, name) {
+    if (!students.has(studentNumber)) {
+        students.set(studentNumber, {
+            studentNumber,
+            name,
+            href: `/!${studentNumber}/`,
+        });
+    }
+}
+/**
+ * Parse GET /api/v1/accounts/me/roles.
+ * Accepts `{ payload: AccountRole[] }` or a raw array.
+ * Skips the account itself (`type === "passwd"` / type 7). Guardian (and other
+ * non-passwd) roles contribute a student from `slug` + `name`.
+ */
+export function parseStudentsFromAccountsRoles(data) {
     const students = new Map();
-    $("a[href^='/!']").each((_, anchor) => {
+    let roles = [];
+    if (Array.isArray(data)) {
+        roles = data;
+    }
+    else if (data && typeof data === "object") {
+        const rec = data;
+        const payload = rec.payload ?? rec.Payload;
+        if (Array.isArray(payload)) {
+            roles = payload;
+        }
+    }
+    for (const item of roles) {
+        if (!item || typeof item !== "object") {
+            continue;
+        }
+        const rec = item;
+        if (isPasswdAccountRole(roleType(rec))) {
+            continue;
+        }
+        const slug = String(rec.slug ?? rec.Slug ?? "");
+        const studentNumber = studentNumberFromSlug(slug);
+        if (!studentNumber) {
+            continue;
+        }
+        const name = roleName(rec, studentNumber);
+        if (!name) {
+            continue;
+        }
+        collectStudent(students, studentNumber, name);
+    }
+    return [...students.values()];
+}
+export function parseStudentsFromHome(html, pageUrl) {
+    const $ = cheerio.load(html);
+    const named = new Map();
+    const fromHref = new Map();
+    $("a[href]").each((_, anchor) => {
         const href = $(anchor).attr("href") ?? "";
-        const match = /\/!(\d+)\//.exec(href);
-        if (!match) {
+        const studentNumber = studentNumberFromHref(href);
+        if (!studentNumber) {
             return;
         }
-        const studentNumber = match[1];
+        fromHref.set(studentNumber, {
+            studentNumber,
+            name: studentNumber,
+            href,
+        });
         const cloned = $(anchor).clone();
         cloned.find("small, span.lem").remove();
         const text = cloned.text().trim();
@@ -32,13 +122,25 @@ export function parseStudentsFromHome(html) {
         if (NAV_KEYWORDS.some((kw) => lower.includes(kw))) {
             return;
         }
-        if (!students.has(studentNumber)) {
-            students.set(studentNumber, {
+        if (!named.has(studentNumber)) {
+            named.set(studentNumber, {
                 studentNumber,
                 name: text,
                 href,
             });
         }
     });
-    return [...students.values()];
+    if (named.size > 0) {
+        return [...named.values()];
+    }
+    if (fromHref.size > 0) {
+        return [...fromHref.values()];
+    }
+    if (pageUrl) {
+        const fromUrl = parseStudentFromUrl(pageUrl);
+        if (fromUrl) {
+            return [fromUrl];
+        }
+    }
+    return [];
 }

package/dist/session.js

@@ -1,5 +1,6 @@
 import { CookieJar } from "tough-cookie";
 import { fetch } from "undici";
+import { wrapNetworkError } from "./network-error.js";
 export class AuthenticationError extends Error {
 }
 export class MfaRequiredError extends Error {
@@ -223,10 +224,18 @@ export class WilmaSession {
             // Avoid logging sensitive headers or body
             console.log(`[wilmai] ${method} ${url}`);
         }
-        const resp = await fetch(url, {
-            ...init,
-            headers,
-        });
+        let resp;
+        try {
+            resp = await fetch(url, {
+                ...init,
+                headers,
+            });
+        }
+        catch (err) {
+            // `fetch failed` on its own is undiagnosable; re-throw with the cause code
+            // and remediation attached.
+            throw wrapNetworkError(err, url);
+        }
         const headersAny = resp.headers;
         const setCookies = headersAny.getSetCookie?.() ?? [];
         if (setCookies.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wilm-ai/wilma-client",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "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": "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"
+  },
   "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": "pnpm run build && node test/parser-messages.mjs && node test/parser-news.mjs && node test/parser-schedule.mjs && node test/client-schedule.mjs && node test/client-news-resources.mjs",
-    "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.