@wilm-ai/wilma-client 1.4.1 → 1.5.0

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?: {
@@ -24,6 +36,11 @@ export declare class WilmaClient {
             date?: string;
         }) => Promise<LessonNote[]>;
     };
+    schedule: {
+        list: (opts?: {
+            date?: string;
+        }) => Promise<OverviewData["schedule"]>;
+    };
     overview: {
         get: () => Promise<OverviewData>;
     };

package/dist/client.js

@@ -5,7 +5,12 @@ import { parseNewsDetailHtml, parseNewsDetailJson, parseNewsList, parseNewsListH
 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 { 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) {
@@ -103,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 = {
@@ -138,6 +164,18 @@ export class WilmaClient {
             return parseAttendanceHtml(text, opts?.date ?? "");
         },
     };
+    schedule = {
+        list: async (opts) => {
+            if (!opts?.date) {
+                return (await this.overview.get()).schedule;
+            }
+            const params = new URLSearchParams();
+            params.set("date", isoDateToFinnish(opts.date));
+            const resp = await this.session.get(`/schedule?${params.toString()}`);
+            const text = await resp.text();
+            return parseScheduleHtml(text);
+        },
+    };
     overview = {
         get: async () => {
             const resp = await this.session.get("/overview");
@@ -146,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);
@@ -154,3 +273,10 @@ function safeJson(text) {
         return {};
     }
 }
+function isoDateToFinnish(date) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+    if (!match) {
+        return date;
+    }
+    return `${match[3]}.${match[2]}.${match[1]}`;
+}

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/parsers/schedule.d.ts

@@ -0,0 +1,2 @@
+import type { ScheduleLesson } from "../types.js";
+export declare function parseScheduleHtml(html: string): ScheduleLesson[];

package/dist/parsers/schedule.js

@@ -0,0 +1,83 @@
+import * as cheerio from "cheerio";
+export function parseScheduleHtml(html) {
+    const $ = cheerio.load(html);
+    const scripts = $("script:not([src])")
+        .map((_, el) => $(el).html() ?? "")
+        .get();
+    const script = scripts.find((text) => text.includes("eventsJSON") && text.includes("Events"));
+    if (!script) {
+        return [];
+    }
+    const match = /Events\s*:\s*(\[[\s\S]*?\])\s*,\s*ActiveTyyppi/.exec(script);
+    if (!match) {
+        return [];
+    }
+    let events;
+    try {
+        events = JSON.parse(match[1]);
+    }
+    catch {
+        return [];
+    }
+    return events
+        .map(parseScheduleEvent)
+        .filter((lesson) => lesson !== null)
+        .sort((a, b) => a.date.localeCompare(b.date) || a.start.localeCompare(b.start));
+}
+function parseScheduleEvent(event) {
+    const date = finnishDateToIso(event.Date ?? "");
+    if (!date) {
+        return null;
+    }
+    const subject = firstRecordValue(event.Text) || firstRecordValue(event.LongText);
+    const teacher = firstTeacher(event.OpeInfo);
+    const dateObj = new Date(`${date}T12:00:00`);
+    return {
+        date,
+        dayOfWeek: dateObj.getDay(),
+        start: minutesToTime(event.Start),
+        end: minutesToTime(event.End),
+        subject,
+        subjectCode: firstSubjectToken(subject),
+        teacher: teacher.name,
+        teacherCode: teacher.code,
+        groupId: Number(event.Id) || 0,
+    };
+}
+function finnishDateToIso(value) {
+    const match = /^(\d{1,2})\.(\d{1,2})\.(\d{4})$/.exec(value.trim());
+    if (!match) {
+        return "";
+    }
+    return `${match[3]}-${match[2].padStart(2, "0")}-${match[1].padStart(2, "0")}`;
+}
+function minutesToTime(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return "";
+    }
+    const hours = Math.floor(value / 60);
+    const minutes = value % 60;
+    return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}`;
+}
+function firstRecordValue(record) {
+    if (!record) {
+        return "";
+    }
+    return Object.values(record).find((value) => value.trim()) ?? "";
+}
+function firstTeacher(groups) {
+    if (!groups) {
+        return { name: "", code: "" };
+    }
+    for (const group of Object.values(groups)) {
+        for (const person of Object.values(group)) {
+            if (person?.nimi || person?.lyhenne) {
+                return { name: person.nimi ?? "", code: person.lyhenne ?? "" };
+            }
+        }
+    }
+    return { name: "", code: "" };
+}
+function firstSubjectToken(subject) {
+    return subject.trim().split(/\s+/, 1)[0] ?? "";
+}

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.1",
+  "version": "1.5.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,7 +26,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "lint": "echo 'add lint'",
-    "test": "pnpm run build && node test/parser-messages.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",
     "test:smoke": "tsc -p tsconfig.json && node test/smoke.mjs",
     "test:live": "tsc -p tsconfig.json && node test/live.spec.mjs"
   }