@wilm-ai/wilma-client 1.5.2 → 1.6.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/README.md

@@ -0,0 +1,66 @@
+# @wilm-ai/wilma-client
+
+A TypeScript client for **Wilma**, the Finnish school information system, as a parent (guardian) sees it: schedule, homework, exams and grades, the gradebook, lesson notes and absences, messages with their replies, bulletins and their attachments, and printouts. Read-only.
+
+It powers the [`wilma` CLI and MCP server](https://www.npmjs.com/package/@wilm-ai/wilma-cli) ([wilm.ai](https://wilm.ai)).
+
+> Independent open-source project, not affiliated with, endorsed by, or connected to Visma or the official Wilma service.
+
+Needs Node.js 20.18.1 or newer.
+
+```bash
+npm i @wilm-ai/wilma-client
+```
+
+## Use
+
+```ts
+import { WilmaClient, listTenants } from "@wilm-ai/wilma-client";
+
+// Find the Wilma address (most city schools share their city's Wilma).
+const wilmas = await listTenants();
+
+// Log in once; every child shares the login.
+const client = await WilmaClient.login({ baseUrl: "https://<school>.inschool.fi", username, password }, onMfa);
+for (const student of await client.students()) {
+  const kid = client.forStudent(student.studentNumber);
+  const overview = await kid.overview.get();          // this week's lessons, homework, exams, exam grades
+  const exams = await kid.exams.upcoming();           // with start times when the school gives one
+  const lessons = await kid.schedule.list({ from: "2026-10-05", to: "2026-10-09" }); // teachers and rooms
+  const notes = await kid.attendance.list({ from: "2026-09-01", to: "2026-09-30" });  // lesson notes, with the teacher's words
+  const summary = await kid.attendance.summary();    // counts by kind for the school year
+  const gradebook = await kid.gradebook.get();       // subject > syllabus > course, with grades and dates
+  const messages = await kid.messages.list("inbox"); // unread and replyCount included
+  const thread = await kid.messages.get(messages[0].wilmaId); // the message and its replies
+  const news = await kid.news.list();                 // dated, pinned and older bulletins
+  const printouts = await kid.printouts.list();       // PDFs such as report cards
+}
+```
+
+`onMfa(formkey)` returns a one-time code for accounts with two-step verification (e.g. generated from the authenticator setup key).
+
+### One session per account
+
+Wilma allows one live session per account: a new login ends the previous one, and also logs the parent out of Wilma in their own browser. So:
+
+- **Log in once** and use `client.forStudent(number)` for each child; they share the login.
+- A session that Wilma ends (another login, or expiry) **logs in again by itself** on the next request — once, even when many requests notice at the same time, including the two-step verification step. A refused password stops further attempts, so a changed password can't lock the account.
+- To continue a session in another process, save `client.exportSession()` (treat it like the password) and later call `WilmaClient.resume(profile, saved, onMfa)`. `client.onLogin(callback)` tells you when a new session should be saved.
+
+### Times
+
+Wilma's times are Finnish wall-clock times. The client reads them as such wherever it runs (dates are correct on a UTC server too), and exports helpers: `finnishDateString()`, `finnishTime()`, and `finnishIsoString(date)` for output like `2026-10-02T13:37:00+03:00`.
+
+### Where the data comes from
+
+JSON wherever Wilma has it: the account's roles, the front page (overview), message lists and threads, and the timetable API. Bulletins, lesson notes, the gradebook, printouts and the exam calendar exist only as pages and are parsed; the parsers are tested against anonymised copies of real pages. Older Wilma versions without the JSON endpoints fall back to the pages.
+
+### Safety
+
+- Requests stay on the Wilma address; redirects to other sites never carry Wilma's cookies.
+- Files linked from bulletins are fetched without the Wilma login and only from public internet addresses (private, loopback and cloud-metadata addresses are refused, also after DNS resolution).
+- Requests and downloads fail after a while without progress instead of hanging.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -1,13 +1,34 @@
-import type { Exam, Message, MessageFolder, NewsItem, NewsResource, OverviewData, WilmaProfile, StudentInfo, LessonNote } from "./types.js";
-import { type Response } from "undici";
+import type { Exam, GradebookEntry, LessonNote, LessonNoteSummary, Message, MessageFolder, NewsItem, NewsResource, OverviewData, Printout, StudentInfo, UpcomingExam, WilmaProfile } from "./types.js";
+import type { Response } from "undici";
 export type MfaCallback = (formkey: string) => Promise<string>;
 export declare class WilmaClient {
     private session;
     private constructor();
     static login(profile: WilmaProfile, onMfaRequired?: MfaCallback): Promise<WilmaClient>;
+    /**
+     * A client on a session saved earlier with exportSession(), without logging
+     * in. If Wilma has ended that session, the first request logs in again by
+     * itself. Returns null when the saved state has no session.
+     */
+    static resume(profile: WilmaProfile, state: string, onMfaRequired?: MfaCallback): WilmaClient | null;
+    /** This login's session (cookies) as a string, for WilmaClient.resume() in a later process. Treat it like a password. */
+    exportSession(): string;
+    /** Run a callback after every successful login, e.g. to save the new session. */
+    onLogin(callback: (() => void) | undefined): void;
     static listStudents(profile: WilmaProfile, onMfaRequired?: MfaCallback): Promise<StudentInfo[]>;
+    /**
+     * A client for one of the account's students that reuses this client's
+     * login. Log in once, then call this per child instead of logging in again.
+     */
+    forStudent(studentNumber: string | null | undefined): WilmaClient;
+    /** The guardian's students, discovered with this client's login. */
+    students(): Promise<StudentInfo[]>;
     messages: {
         list: (folder?: MessageFolder) => Promise<Message[]>;
+        /**
+         * One message with its replies. Wilma answers `?format=json` with the whole
+         * thread; older versions only have the HTML page, which is parsed instead.
+         */
         get: (messageId: number) => Promise<Message>;
     };
     news: {
@@ -26,21 +47,65 @@ export declare class WilmaClient {
         }>;
     };
     exams: {
+        /**
+         * Upcoming exams with topics and teachers (front page), plus the start
+         * time when the school gives one (exam calendar). Without the calendar,
+         * exams come back without times.
+         */
+        upcoming: () => Promise<UpcomingExam[]>;
+        /** The exam calendar, or [] if it can't be read (start times are a bonus). */
+        calendarOrEmpty: () => Promise<Exam[]>;
+        /** The exam calendar page: upcoming exams with dates, start times, teachers and notes. */
         list: (opts?: {
             start?: string;
             end?: string;
         }) => Promise<Exam[]>;
     };
     attendance: {
+        /**
+         * Lesson notes (merkinnät): absences, lateness and teachers' feedback, with
+         * any words the teacher wrote. One day (default today), or a period with
+         * `from`/`to` (YYYY-MM-DD).
+         */
         list: (opts?: {
             date?: string;
+            from?: string;
+            to?: string;
         }) => Promise<LessonNote[]>;
+        /** How many lesson notes of each kind from `from` to `to` (default today); without `from`, this school year. */
+        summary: (opts?: {
+            from?: string;
+            to?: string;
+        }) => Promise<LessonNoteSummary>;
     };
+    /** The lesson notes page for a period ("range" as Wilma's own period links use it). */
+    private attendancePage;
     schedule: {
+        /**
+         * Lessons on a date or in a period (YYYY-MM-DD), from Wilma's timetable
+         * API, with teachers and rooms. Without dates: this week, from the front
+         * page. Older Wilma versions without the API fall back to the schedule
+         * page (one date) or the front page (this week).
+         */
         list: (opts?: {
             date?: string;
+            from?: string;
+            to?: string;
         }) => Promise<OverviewData["schedule"]>;
     };
+    gradebook: {
+        /** Completed courses and grades (Suoritukset), as a tree: subject > syllabus > course. */
+        get: () => Promise<GradebookEntry[]>;
+    };
+    printouts: {
+        /** PDF documents the school offers (Tulosteet): report cards, absence reports… */
+        list: () => Promise<Printout[]>;
+        /** Download one printout; the response body is the PDF. */
+        fetch: (id: string) => Promise<{
+            printout: Printout;
+            response: Response;
+        }>;
+    };
     overview: {
         get: () => Promise<OverviewData>;
     };

package/dist/client.js

@@ -1,17 +1,17 @@
-import { WilmaSession, MfaRequiredError } from "./session.js";
+import { WilmaSession, MfaRequiredError, APIError } from "./session.js";
 import { parseWilmaTimestamp } from "./parsers/dates.js";
-import { parseMessagesList, parseMessageDetailHtml } from "./parsers/messages.js";
+import { finnishDateString } from "./finnish-time.js";
+import { parseMessagesList, parseMessageDetailHtml, parseMessageDetailJson } from "./parsers/messages.js";
 import { parseNewsDetailHtml, parseNewsDetailJson, parseNewsList, parseNewsListHtml, } from "./parsers/news.js";
-import { parseExamsHtml } from "./parsers/exams.js";
-import { parseAttendanceHtml } from "./parsers/attendance.js";
+import { addExamTimes, parseExamsHtml } from "./parsers/exams.js";
+import { parseAttendanceHtml, summarizeLessonNotes } from "./parsers/attendance.js";
+import { parseGradebookHtml } from "./parsers/gradebook.js";
+import { parsePrintoutsHtml } from "./parsers/printouts.js";
 import { parseOverview } from "./parsers/overview.js";
-import { parseScheduleHtml } from "./parsers/schedule.js";
+import { parseScheduleHtml, parseTimetableJson } from "./parsers/schedule.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";
+import { NetworkError } from "./network-error.js";
+import { DOWNLOAD_TIMEOUT_MS, fetchExternalFile, isHtmlResponse } from "./external-fetch.js";
 export class WilmaClient {
     session;
     constructor(session) {
@@ -22,13 +22,13 @@ export class WilmaClient {
             studentNumber: profile.studentNumber ?? null,
             debug: profile.debug ?? false,
         });
+        session.setMfaCallback(onMfaRequired);
         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);
+                await session.answerMfa(err.formkey, onMfaRequired);
             }
             else {
                 throw err;
@@ -36,22 +36,42 @@ export class WilmaClient {
         }
         return new WilmaClient(session);
     }
-    static async listStudents(profile, onMfaRequired) {
+    /**
+     * A client on a session saved earlier with exportSession(), without logging
+     * in. If Wilma has ended that session, the first request logs in again by
+     * itself. Returns null when the saved state has no session.
+     */
+    static resume(profile, state, onMfaRequired) {
         const session = new WilmaSession(profile.baseUrl, {
+            studentNumber: profile.studentNumber ?? null,
             debug: profile.debug ?? false,
         });
-        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;
-            }
-        }
+        session.setMfaCallback(onMfaRequired);
+        return session.resumeState(state, profile.username, profile.password) ? new WilmaClient(session) : null;
+    }
+    /** This login's session (cookies) as a string, for WilmaClient.resume() in a later process. Treat it like a password. */
+    exportSession() {
+        return this.session.exportState();
+    }
+    /** Run a callback after every successful login, e.g. to save the new session. */
+    onLogin(callback) {
+        this.session.onLogin(callback);
+    }
+    static async listStudents(profile, onMfaRequired) {
+        const client = await WilmaClient.login({ ...profile, studentNumber: null }, onMfaRequired);
+        return client.students();
+    }
+    /**
+     * A client for one of the account's students that reuses this client's
+     * login. Log in once, then call this per child instead of logging in again.
+     */
+    forStudent(studentNumber) {
+        return new WilmaClient(this.session.forStudent(studentNumber || null));
+    }
+    /** The guardian's students, discovered with this client's login. */
+    async students() {
+        // Discovery pages live outside any student's "/!<number>/" prefix.
+        const session = this.session.forStudent(null);
         try {
             const accountsResp = await session.get("/api/v1/accounts/me/roles");
             const accountsText = await accountsResp.text();
@@ -89,7 +109,22 @@ export class WilmaClient {
             const data = safeJson(text);
             return parseMessagesList(data, folder);
         },
+        /**
+         * One message with its replies. Wilma answers `?format=json` with the whole
+         * thread; older versions only have the HTML page, which is parsed instead.
+         */
         get: async (messageId) => {
+            try {
+                const resp = await this.session.get(`/messages/${messageId}?format=json`);
+                const thread = parseMessageDetailJson(safeJson(await resp.text()), messageId);
+                if (thread)
+                    return thread;
+            }
+            catch (err) {
+                if (err instanceof NetworkError || !(err instanceof APIError) || err.status !== 404)
+                    throw err;
+            }
+            // Older versions: the message page (flat JSON on some, HTML on most).
             const resp = await this.session.get(`/messages/${messageId}`);
             const contentType = resp.headers.get("content-type")?.toLowerCase() ?? "";
             const text = await resp.text();
@@ -142,7 +177,21 @@ export class WilmaClient {
             }
             if (resource.authContext === "wilma") {
                 const url = new URL(resource.url);
-                const response = await this.session.get(`${url.pathname}${url.search}`);
+                // Collapse leading slashes so the path can't turn into "//other-host/...".
+                const path = `/${url.pathname.replace(/^\/+/, "")}${url.search}`;
+                const response = await this.session.get(path, undefined, {
+                    externalRedirect: "return",
+                    timeoutMs: DOWNLOAD_TIMEOUT_MS,
+                });
+                if (response.status >= 300 && response.status < 400) {
+                    // Wilma handed the file off to another site: fetch it there, without Wilma credentials.
+                    const location = response.headers.get("location");
+                    await response.body?.cancel();
+                    const external = location ? await fetchExternalFile(new URL(location, url).href) : null;
+                    return external
+                        ? { resource, response: external, status: "fetched" }
+                        : { resource, response: null, status: "not_a_file" };
+                }
                 if (isHtmlResponse(response)) {
                     await response.body?.cancel();
                     return { resource, response: null, status: "not_a_file" };
@@ -157,6 +206,27 @@ export class WilmaClient {
         },
     };
     exams = {
+        /**
+         * Upcoming exams with topics and teachers (front page), plus the start
+         * time when the school gives one (exam calendar). Without the calendar,
+         * exams come back without times.
+         */
+        upcoming: async () => {
+            const [overview, calendar] = await Promise.all([this.overview.get(), this.exams.calendarOrEmpty()]);
+            return addExamTimes(overview.upcomingExams, calendar);
+        },
+        /** The exam calendar, or [] if it can't be read (start times are a bonus). */
+        calendarOrEmpty: async () => {
+            try {
+                return await this.exams.list();
+            }
+            catch (err) {
+                if (err instanceof NetworkError)
+                    throw err;
+                return [];
+            }
+        },
+        /** The exam calendar page: upcoming exams with dates, start times, teachers and notes. */
         list: async (opts) => {
             const params = new URLSearchParams();
             if (opts?.start) {
@@ -173,28 +243,84 @@ export class WilmaClient {
         },
     };
     attendance = {
+        /**
+         * Lesson notes (merkinnät): absences, lateness and teachers' feedback, with
+         * any words the teacher wrote. One day (default today), or a period with
+         * `from`/`to` (YYYY-MM-DD).
+         */
         list: async (opts) => {
-            const params = new URLSearchParams();
-            if (opts?.date) {
-                params.set("date", opts.date);
+            const from = opts?.from ?? opts?.date ?? finnishDateString();
+            const to = opts?.to ?? opts?.date ?? from;
+            const notes = parseAttendanceHtml(await this.attendancePage(`range=-3&first=${isoDateToFinnish(from)}&last=${isoDateToFinnish(to)}`));
+            return notes.filter((note) => note.date >= from && note.date <= to);
+        },
+        /** How many lesson notes of each kind from `from` to `to` (default today); without `from`, this school year. */
+        summary: async (opts) => {
+            if (!opts?.from) {
+                const notes = parseAttendanceHtml(await this.attendancePage("range=-4"));
+                return summarizeLessonNotes(opts?.to ? notes.filter((note) => note.date <= opts.to) : notes, null, opts?.to ?? null);
             }
-            const query = params.toString();
-            const path = query ? `/attendance/view?${query}` : "/attendance/view";
-            const resp = await this.session.get(path);
-            const text = await resp.text();
-            return parseAttendanceHtml(text, opts?.date ?? "");
+            const to = opts.to ?? finnishDateString();
+            return summarizeLessonNotes(await this.attendance.list({ from: opts.from, to }), opts.from, to);
         },
     };
+    /** The lesson notes page for a period ("range" as Wilma's own period links use it). */
+    async attendancePage(range) {
+        const resp = await this.session.get(`/attendance/view?${range}`);
+        return resp.text();
+    }
     schedule = {
+        /**
+         * Lessons on a date or in a period (YYYY-MM-DD), from Wilma's timetable
+         * API, with teachers and rooms. Without dates: this week, from the front
+         * page. Older Wilma versions without the API fall back to the schedule
+         * page (one date) or the front page (this week).
+         */
         list: async (opts) => {
-            if (!opts?.date) {
-                return (await this.overview.get()).schedule;
+            const from = opts?.from ?? opts?.date;
+            const to = opts?.to ?? opts?.date ?? from;
+            if (from && to) {
+                try {
+                    const resp = await this.session.get(`/api/v1/schedules/timetable?startdate=${from}&enddate=${to}`);
+                    const data = safeJson(await resp.text());
+                    if (Array.isArray(data.payload)) {
+                        return parseTimetableJson(data.payload).filter((lesson) => lesson.date >= from && lesson.date <= to);
+                    }
+                }
+                catch (err) {
+                    if (!(err instanceof APIError) || (err.status !== 403 && err.status !== 404))
+                        throw err;
+                }
+                if (from === to) {
+                    const params = new URLSearchParams({ date: isoDateToFinnish(from) });
+                    const resp = await this.session.get(`/schedule?${params.toString()}`);
+                    return parseScheduleHtml(await resp.text()).filter((lesson) => lesson.date === from);
+                }
+                return (await this.overview.get()).schedule.filter((lesson) => lesson.date >= from && lesson.date <= to);
             }
-            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);
+            return (await this.overview.get()).schedule;
+        },
+    };
+    gradebook = {
+        /** Completed courses and grades (Suoritukset), as a tree: subject > syllabus > course. */
+        get: async () => {
+            const resp = await this.session.get("/gradebook");
+            return parseGradebookHtml(await resp.text());
+        },
+    };
+    printouts = {
+        /** PDF documents the school offers (Tulosteet): report cards, absence reports… */
+        list: async () => {
+            const resp = await this.session.get("/printouts");
+            return parsePrintoutsHtml(await resp.text());
+        },
+        /** Download one printout; the response body is the PDF. */
+        fetch: async (id) => {
+            const printout = (await this.printouts.list()).find((candidate) => candidate.id === id);
+            if (!printout)
+                throw new Error(`Printout "${id}" not found`);
+            const response = await this.session.get(printout.path, undefined, { timeoutMs: DOWNLOAD_TIMEOUT_MS });
+            return { printout, response: response };
         },
     };
     overview = {
@@ -205,93 +331,6 @@ 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/external-fetch.d.ts

@@ -0,0 +1,18 @@
+import { type Response } from "undici";
+/** How long a download may stall (before answering, or mid-file) before it fails. */
+export declare const DOWNLOAD_TIMEOUT_MS = 60000;
+export declare function isBlockedAddress(address: string): boolean;
+/** Refuse URLs that point at private or special addresses, or at unusual ports. */
+export declare function assertPublicUrl(url: URL): void;
+export declare function isHtmlResponse(response: {
+    headers: {
+        get(name: string): string | null;
+    };
+}): boolean;
+/**
+ * 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; throws for HTTP errors and refused addresses.
+ */
+export declare function fetchExternalFile(rawUrl: string): Promise<Response | null>;