@wilm-ai/wilma-client 1.4.2 → 1.5.1

package/dist/client.d.ts

@@ -1,4 +1,5 @@
-import type { Exam, Message, MessageFolder, NewsItem, OverviewData, WilmaProfile, StudentInfo, LessonNote } from "./types.js";
+import type { Exam, Message, MessageFolder, NewsItem, NewsResource, OverviewData, WilmaProfile, StudentInfo, LessonNote } from "./types.js";
+import { type Response } from "undici";
 export type MfaCallback = (formkey: string) => Promise<string>;
 export declare class WilmaClient {
     private session;
@@ -12,6 +13,17 @@ export declare class WilmaClient {
     news: {
         list: () => Promise<NewsItem[]>;
         get: (newsId: number) => Promise<NewsItem>;
+        fetchResource: (newsId: number, resourceId: string, options?: {
+            item?: NewsItem;
+        }) => Promise<{
+            resource: NewsResource;
+            response: Response;
+            status: "fetched";
+        } | {
+            resource: NewsResource;
+            response: null;
+            status: "not_a_file";
+        }>;
     };
     exams: {
         list: (opts?: {

package/dist/client.js

@@ -7,6 +7,11 @@ 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 { CookieJar } from "tough-cookie";
+import { fetch, Headers } from "undici";
+import { 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 {
     session;
     constructor(session) {
@@ -104,10 +109,31 @@ export class WilmaClient {
             if (!contentType.includes("text/html")) {
                 const data = safeJson(text);
                 if (Object.keys(data).length) {
-                    return parseNewsDetailJson(newsId, data);
+                    return parseNewsDetailJson(newsId, data, resp.url);
                 }
             }
-            return parseNewsDetailHtml(text, newsId);
+            return parseNewsDetailHtml(text, newsId, resp.url);
+        },
+        fetchResource: async (newsId, resourceId, options) => {
+            const item = options?.item ?? (await this.news.get(newsId));
+            const resource = item.resources?.find((candidate) => candidate.id === resourceId);
+            if (!resource) {
+                throw new Error(`News resource "${resourceId}" not found`);
+            }
+            if (resource.authContext === "wilma") {
+                const url = new URL(resource.url);
+                const response = await this.session.get(`${url.pathname}${url.search}`);
+                if (isHtmlResponse(response)) {
+                    await response.body?.cancel();
+                    return { resource, response: null, status: "not_a_file" };
+                }
+                return { resource, response: response, status: "fetched" };
+            }
+            const response = await fetchExternalFile(resource.url);
+            if (!response) {
+                return { resource, response: null, status: "not_a_file" };
+            }
+            return { resource, response, status: "fetched" };
         },
     };
     exams = {
@@ -159,6 +185,93 @@ export class WilmaClient {
         },
     };
 }
+// Some document hosts serve an HTML viewer page for a sharing URL but return
+// the file itself when a conventional download parameter is present. These are
+// generic retry variants, not provider detection: the original URL is always
+// attempted first, and a variant is tried only after an HTML answer.
+const DOWNLOAD_PARAM_VARIANTS = [
+    ["download", "1"],
+    ["dl", "1"],
+];
+function buildDownloadCandidates(rawUrl) {
+    const original = new URL(rawUrl);
+    const candidates = [original];
+    for (const [param, value] of DOWNLOAD_PARAM_VARIANTS) {
+        if (!original.searchParams.has(param)) {
+            const variant = new URL(original.href);
+            variant.searchParams.set(param, value);
+            candidates.push(variant);
+        }
+    }
+    return candidates;
+}
+function isHtmlResponse(response) {
+    const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+    return contentType.startsWith("text/html") || contentType.startsWith("application/xhtml");
+}
+// Fetch an external URL the way a signed-out browser would: an isolated
+// in-memory cookie jar, redirects followed across hosts, and no Wilma
+// credentials anywhere. Returns null when every candidate answered with an
+// HTML page instead of a file.
+async function fetchExternalFile(rawUrl) {
+    for (const candidate of buildDownloadCandidates(rawUrl)) {
+        const response = await fetchFollowingRedirects(candidate);
+        if (!response) {
+            continue;
+        }
+        if (response.ok && isHtmlResponse(response)) {
+            await response.body?.cancel();
+            continue;
+        }
+        return response;
+    }
+    return null;
+}
+async function fetchFollowingRedirects(initialUrl) {
+    const cookieJar = new CookieJar();
+    let currentUrl = initialUrl;
+    for (let redirectCount = 0; redirectCount <= 10; redirectCount += 1) {
+        const headers = new Headers({
+            "User-Agent": EXTERNAL_USER_AGENT,
+            "Accept": "*/*",
+        });
+        const cookieHeader = cookieJar.getCookieStringSync(currentUrl.href);
+        if (cookieHeader) {
+            headers.set("Cookie", cookieHeader);
+        }
+        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) {
+            cookieJar.setCookieSync(cookie, currentUrl.href, { ignoreError: true });
+        }
+        if (!setCookies.length) {
+            const cookie = response.headers.get("set-cookie");
+            if (cookie)
+                cookieJar.setCookieSync(cookie, currentUrl.href, { ignoreError: true });
+        }
+        if (response.status < 300 || response.status >= 400) {
+            return response;
+        }
+        const location = response.headers.get("location");
+        await response.body?.cancel();
+        if (!location) {
+            return null;
+        }
+        const nextUrl = new URL(location, currentUrl);
+        if (nextUrl.protocol !== "https:" && nextUrl.protocol !== "http:") {
+            return null;
+        }
+        currentUrl = nextUrl;
+    }
+    throw new Error("External resource exceeded the redirect limit");
+}
 function safeJson(text) {
     try {
         return JSON.parse(text);

package/dist/index.d.ts

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

@@ -1,5 +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 parseNewsDetailJson(newsId: number, data: Record<string, unknown>, baseUrl?: string): NewsItem;
+export declare function parseNewsDetailHtml(html: string, newsId: number, baseUrl?: string): NewsItem;
 export declare function parseNewsListHtml(html: string): NewsItem[];

package/dist/parsers/news.js

@@ -1,5 +1,6 @@
 import * as cheerio from "cheerio";
 import { parseWilmaTimestamp } from "./dates.js";
+const FILE_EXTENSION_RE = /\.(?:pdf|docx?|xlsx?|pptx?|odt|ods|odp|rtf|txt|csv|zip|7z|png|jpe?g|gif|webp)$/i;
 export function parseNewsList(data) {
     if (Array.isArray(data)) {
         const now = new Date();
@@ -24,18 +25,25 @@ export function parseNewsList(data) {
     }
     return [];
 }
-export function parseNewsDetailJson(newsId, data) {
+export function parseNewsDetailJson(newsId, data, baseUrl) {
+    const content = (data["content"] ?? data["Content"]);
+    let resources = [];
+    if (content && content.includes("<a")) {
+        const $ = cheerio.load(content);
+        resources = extractNewsResources($, $.root(), baseUrl);
+    }
     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"]),
+        content,
+        resources,
         fetchedAt: new Date(),
     };
 }
-export function parseNewsDetailHtml(html, newsId) {
+export function parseNewsDetailHtml(html, newsId, baseUrl) {
     const $ = cheerio.load(html);
     let title = $("title").text().trim();
     if (title.endsWith(" - Wilma")) {
@@ -48,10 +56,23 @@ export function parseNewsDetailHtml(html, newsId) {
     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();
+    let resources = [];
+    // Wilma can hide link-only bulletin content when it renders the target in an
+    // iframe. Prefer the dedicated container even when it carries .hidden.
+    const dedicatedContent = $("#news-content").first();
+    const contentElem = dedicatedContent.length
+        ? dedicatedContent
+        : $(".news-content, .content, .ckeditor, article, .panel-body").first();
     if (contentElem.length) {
-        contentElem.find("script, style").remove();
-        content = contentElem.text().trim();
+        resources = extractNewsResources($, contentElem, baseUrl);
+        const cleanContent = contentElem.clone();
+        cleanContent.find("script, style").remove();
+        const text = cleanContent.text().trim();
+        // A container made entirely from resource anchors has no prose body. Keep
+        // the labels in resources instead of duplicating them in content.
+        const proseOnly = cleanContent.clone();
+        proseOnly.find("a[href]").remove();
+        content = proseOnly.text().trim() ? text : null;
     }
     return {
         wilmaId: newsId,
@@ -60,9 +81,62 @@ export function parseNewsDetailHtml(html, newsId) {
         author: null,
         published: null,
         content,
+        resources,
         fetchedAt: new Date(),
     };
 }
+function extractNewsResources($, contentElem, baseUrl) {
+    const resources = [];
+    const seen = new Set();
+    contentElem.find("a[href]").each((_, element) => {
+        const anchor = $(element);
+        const rawHref = (anchor.attr("href") ?? "").trim();
+        const url = resolveSafeHttpUrl(rawHref, baseUrl);
+        if (!url || seen.has(url.href)) {
+            return;
+        }
+        seen.add(url.href);
+        const authContext = baseUrl && url.origin === new URL(baseUrl).origin ? "wilma" : "external";
+        // Only a naming hint — never used to decide whether a download may be
+        // attempted. The download attempt itself reveals whether a URL is a file.
+        const fileName = FILE_EXTENSION_RE.test(decodeURIComponentSafely(url.pathname))
+            ? fileNameFromUrl(url)
+            : null;
+        const label = anchor.text().trim() || fileName || url.host;
+        resources.push({
+            id: `resource-${resources.length + 1}`,
+            label,
+            url: url.href,
+            authContext,
+            fileName,
+        });
+    });
+    return resources;
+}
+function resolveSafeHttpUrl(rawHref, baseUrl) {
+    if (!rawHref || rawHref.startsWith("#")) {
+        return null;
+    }
+    try {
+        const url = baseUrl ? new URL(rawHref, baseUrl) : new URL(rawHref);
+        return url.protocol === "http:" || url.protocol === "https:" ? url : null;
+    }
+    catch {
+        return null;
+    }
+}
+function fileNameFromUrl(url) {
+    const lastSegment = url.pathname.split("/").filter(Boolean).at(-1);
+    return lastSegment ? decodeURIComponentSafely(lastSegment) : null;
+}
+function decodeURIComponentSafely(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
 export function parseNewsListHtml(html) {
     const $ = cheerio.load(html);
     const now = new Date();

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/dist/types.d.ts

@@ -19,8 +19,17 @@ export interface NewsItem {
     author?: string | null;
     published?: Date | null;
     content?: string | null;
+    resources?: NewsResource[];
     fetchedAt: Date;
 }
+export type NewsResourceAuthContext = "external" | "wilma";
+export interface NewsResource {
+    id: string;
+    label: string;
+    url: string;
+    authContext: NewsResourceAuthContext;
+    fileName?: string | null;
+}
 export interface Exam {
     wilmaId: number;
     examDate: Date;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wilm-ai/wilma-client",
-  "version": "1.4.2",
+  "version": "1.5.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,7 +17,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "lint": "echo 'add lint'",
-    "test": "pnpm run build && node test/parser-messages.mjs && node test/parser-schedule.mjs && node test/client-schedule.mjs",
+    "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 && 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"
   },