@wilm-ai/wilma-client 1.4.2 → 1.5.0

package/LICENSE

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

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,10 @@ 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";
+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 +108,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 +184,87 @@ 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);
+        }
+        const response = await fetch(currentUrl, { headers, redirect: "manual" });
+        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,4 +1,4 @@
-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";

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/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.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,13 +14,6 @@
     "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-schedule.mjs && node test/client-schedule.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",
@@ -29,5 +22,12 @@
   "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"
   }
-}
+}