@wilm-ai/wilma-client 1.6.1 → 1.7.0

package/dist/session.js

@@ -1,6 +1,7 @@
+import * as cheerio from "cheerio";
 import { CookieJar } from "tough-cookie";
-import { fetch } from "undici";
-import { IdleTimer, asNetworkError, watchBody } from "./timeouts.js";
+import { IdleTimer, asNetworkError, watchedResponse } from "./timeouts.js";
+import { getDefaultTransport } from "./transport.js";
 export class AuthenticationError extends Error {
     constructor(message) {
         super(message);
@@ -23,6 +24,17 @@ export class APIError extends Error {
         this.status = status;
     }
 }
+/**
+ * Wilma ended the session (another login on the account, or it expired) and
+ * this client doesn't log in again by itself (no saved credentials, or
+ * `relogin: false`). Nothing was sent; log in again and retry.
+ */
+export class SessionEndedError extends APIError {
+    constructor(message = "Wilma ended the session; log in again") {
+        super(message, 401);
+        this.name = "SessionEndedError";
+    }
+}
 /** How long Wilma may go silent (before answering, or mid-body) before a request fails. */
 const REQUEST_TIMEOUT_MS = 30_000;
 const MAX_REDIRECTS = 10;
@@ -36,10 +48,24 @@ export class WilmaSession {
     debug = false;
     constructor(baseUrl, opts) {
         this.baseUrl = baseUrl.replace(/\/$/, "");
-        this.auth = { cookieJar: new CookieJar(), loggedIn: false, relogin: null, generation: 0, failed: null };
+        this.auth = {
+            cookieJar: new CookieJar(),
+            transport: opts?.transport ?? getDefaultTransport(),
+            reloginAllowed: opts?.relogin ?? true,
+            shared: opts?.shared,
+            loggedIn: false,
+            endedByWilma: false,
+            relogin: null,
+            generation: 0,
+            failed: null,
+        };
         this.studentNumber = opts?.studentNumber ?? null;
         this.debug = Boolean(opts?.debug);
     }
+    /** The address of this Wilma, e.g. "https://example.inschool.fi". */
+    get origin() {
+        return new URL(this.baseUrl).origin;
+    }
     /** The login's cookies, so another process can resume the session (see resumeState). */
     exportState() {
         return JSON.stringify(this.auth.cookieJar.serializeSync());
@@ -47,8 +73,9 @@ export class WilmaSession {
     /**
      * Continue a session saved by exportState() instead of logging in. If Wilma
      * has ended it meanwhile, the first request notices (401/403 or the login
-     * page) and logs in again with these credentials. Returns false when the
-     * state holds no session to resume.
+     * page) and logs in again with these credentials; without credentials it
+     * fails with SessionEndedError. Returns false when the state holds no
+     * session to resume.
      */
     resumeState(state, username, password) {
         let jar;
@@ -58,19 +85,27 @@ export class WilmaSession {
         catch {
             return false;
         }
-        if (!jar.getCookiesSync(this.baseUrl).some((cookie) => cookie.key === "Wilma2SID"))
+        if (!holdsSession(jar, this.baseUrl))
             return false;
         this.auth.cookieJar = jar;
         this.auth.loggedIn = true;
+        this.auth.endedByWilma = false;
         this.auth.generation += 1;
         this.auth.username = username;
         this.auth.password = password;
         return true;
     }
     /** Called after every successful login (first or again). */
+    /** Share this login's session with the other WilmAI programs (see SharedSession). */
+    setShared(shared) {
+        this.auth.shared = shared;
+    }
     onLogin(callback) {
         this.auth.onLogin = callback;
     }
+    onSessionEvent(callback) {
+        this.auth.onEvent = callback;
+    }
     /** Used to answer the two-step verification challenge when the session has to log in again. */
     setMfaCallback(onMfa) {
         this.auth.onMfa = onMfa;
@@ -81,7 +116,7 @@ export class WilmaSession {
      * Wilma picks the student from the "/!<number>/" path prefix.
      */
     forStudent(studentNumber) {
-        const session = new WilmaSession(this.baseUrl, { studentNumber, debug: this.debug });
+        const session = new WilmaSession(this.baseUrl, { studentNumber, debug: this.debug, transport: this.auth.transport });
         session.auth = this.auth;
         return session;
     }
@@ -157,11 +192,12 @@ export class WilmaSession {
         // would otherwise pass the text check, accepting any username and password.
         if (resp.status < 400 && (hasSessionCookie || resp.status < 300)) {
             this.auth.loggedIn = true;
+            this.auth.endedByWilma = false;
             this.auth.generation += 1;
             this.auth.failed = null;
             this.auth.username = username;
             this.auth.password = password;
-            this.auth.onLogin?.();
+            this.loggedInNow();
             return;
         }
         // Not Wilma's "login failed" answer (a rate limit, a firewall, a
@@ -206,13 +242,67 @@ export class WilmaSession {
             throw new AuthenticationError("MFA verification failed: invalid OTP code");
         }
         this.auth.loggedIn = true;
+        this.auth.endedByWilma = false;
         this.auth.generation += 1;
         this.auth.failed = null;
-        this.auth.onLogin?.();
+        this.loggedInNow();
         if (this.debug) {
             console.error(`[wilmai] MFA verification successful`);
         }
     }
+    /**
+     * End this login's session in Wilma, as its "Log out" button does: the
+     * logout form on the front page posts its formkey to /logout. Never logs
+     * in; a session Wilma has already ended needs nothing. The session is
+     * shared with every per-student session made from this one, and afterwards
+     * none of them logs in again by itself (call login() for a new session).
+     * Returns true when a live session was ended, false when there was none.
+     * If Wilma can't be reached, throws and keeps the session, so logging out
+     * can be tried again.
+     */
+    async logout() {
+        const auth = this.auth;
+        // A re-login in progress makes a new session: let it finish, then end that one.
+        if (auth.relogin)
+            await auth.relogin.catch(() => { });
+        const ended = holdsSession(auth.cookieJar, this.baseUrl) ? await this.endSession() : false;
+        auth.cookieJar.removeAllCookiesSync();
+        auth.loggedIn = false;
+        auth.username = undefined;
+        auth.password = undefined;
+        return ended;
+    }
+    async endSession() {
+        // Only raw requests: request() would log in again if the session has ended.
+        const home = await this.rawRequest("/", { method: "GET", stopAtLogin: true });
+        if (home.status >= 500) {
+            await home.body?.cancel();
+            throw new APIError(`Wilma answered HTTP ${home.status} while logging out`, home.status);
+        }
+        let formkey = null;
+        if (home.status === 200)
+            formkey = logoutFormkey(await home.text());
+        else
+            await home.body?.cancel();
+        if (!formkey) {
+            // The login page, or a 401/403: nothing to end. A live session without
+            // the form is kept rather than forgotten while still open.
+            if (await this.sessionAlive())
+                throw new APIError("Wilma's front page had no logout form", home.status);
+            return false;
+        }
+        const resp = await this.rawRequest("/logout", {
+            method: "POST",
+            body: new URLSearchParams({ formkey }).toString(),
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            redirect: "manual",
+        });
+        await resp.body?.cancel();
+        if (resp.status >= 500 || (resp.status >= 400 && (await this.sessionAlive()))) {
+            throw new APIError(`Wilma didn't log out (HTTP ${resp.status})`, resp.status);
+        }
+        return true;
+    }
     async getLoginFormFields() {
         const resp = await this.rawRequest("/login", { method: "GET" });
         if (resp.status >= 500) {
@@ -246,10 +336,11 @@ export class WilmaSession {
         // A re-login in progress: wait for it (and share its outcome).
         if (auth.relogin)
             await auth.relogin;
+        const canRelogin = () => auth.reloginAllowed && Boolean(auth.username && auth.password);
         if (!auth.loggedIn) {
-            // An earlier re-login failed (Wilma down, network blip): try again now.
-            if (auth.username && auth.password)
-                await this.relogin();
+            // Ended earlier (or an earlier re-login failed): another program may have a session now, or try logging in again.
+            if (canRelogin() || auth.endedByWilma)
+                await this.recover();
             else
                 throw new AuthenticationError("WilmaSession not logged in – call login() first");
         }
@@ -264,13 +355,16 @@ export class WilmaSession {
         // another login on the same account cancelled this session, or just this
         // one item is off-limits.
         const loggedOut = (r) => r.status === 401 || this.isLoginRedirect(r);
-        if ((loggedOut(resp) || resp.status === 403) && auth.username && auth.password) {
-            const someoneElseLoggedIn = () => auth.generation !== generation || auth.relogin !== null;
-            let retry = someoneElseLoggedIn();
+        if (loggedOut(resp) || resp.status === 403) {
+            // Another request may have got a session back meanwhile (generation bumped, or recovering now).
+            const recoveredElsewhere = () => auth.generation !== generation || auth.relogin !== null;
+            let retry = recoveredElsewhere();
+            // Tell an ended session apart from one item that's off-limits (403 with the session alive).
             if (!retry && (loggedOut(resp) || !(await this.sessionAlive()))) {
-                // Check again: another request may have logged in while we probed.
-                if (!someoneElseLoggedIn())
-                    await this.relogin();
+                await resp.body?.cancel();
+                // Check again: another request may have recovered while we probed.
+                if (!recoveredElsewhere())
+                    await this.recover();
                 retry = true;
             }
             if (retry) {
@@ -350,11 +444,24 @@ export class WilmaSession {
             }
         }
     }
-    /** Log in again, once for everyone sharing this login even if many requests notice at the same time. */
-    async relogin() {
+    /**
+     * A live session after Wilma ended this one, once for everyone sharing this
+     * login even if many requests notice at the same time: the newest session
+     * another program saved (no login), else a login when this client may log
+     * in again. Without either, SessionEndedError.
+     */
+    async recover() {
         if (!this.auth.relogin) {
             const auth = this.auth;
             const attempt = (async () => {
+                if (await this.adoptShared())
+                    return;
+                if (!(auth.reloginAllowed && auth.username && auth.password)) {
+                    auth.loggedIn = false;
+                    auth.endedByWilma = true;
+                    auth.onEvent?.("ended");
+                    throw new SessionEndedError();
+                }
                 auth.loggedIn = false;
                 // Start from a clean jar: a leftover session cookie must not make a
                 // failed login look successful.
@@ -389,12 +496,99 @@ export class WilmaSession {
         }
         await this.auth.relogin;
     }
+    /** Continue the session another program saved, if it differs from ours and Wilma still accepts it. */
+    async adoptShared() {
+        const auth = this.auth;
+        if (!auth.shared)
+            return false;
+        let jar;
+        try {
+            const state = await auth.shared.load();
+            if (!state)
+                return false;
+            jar = CookieJar.deserializeSync(JSON.parse(state));
+        }
+        catch {
+            return false;
+        }
+        const theirs = sessionCookie(jar, this.baseUrl);
+        if (!theirs || theirs === sessionCookie(auth.cookieJar, this.baseUrl))
+            return false;
+        const ours = auth.cookieJar;
+        auth.cookieJar = jar;
+        if (!(await this.sessionAlive())) {
+            auth.cookieJar = ours;
+            return false;
+        }
+        if (this.debug)
+            console.error("[wilmai] continuing the session another program saved");
+        auth.loggedIn = true;
+        auth.endedByWilma = false;
+        auth.failed = null;
+        auth.generation += 1;
+        auth.onEvent?.("adopted");
+        return true;
+    }
+    /** After a login: tell the host (onLogin) and save the session for the other programs. */
+    loggedInNow() {
+        this.auth.onLogin?.();
+        this.auth.onEvent?.("login");
+        void this.auth.shared?.save(this.exportState()).catch(() => { });
+    }
+    /** Changes whenever the session behind this client changes (a login, or another program's session continued). */
+    get sessionMark() {
+        return this.auth.generation;
+    }
     async get(path, init, opts) {
         return this.request(path, { ...init, method: "GET" }, opts);
     }
     async post(path, init) {
         return this.request(path, { ...init, method: "POST" });
     }
+    /**
+     * Send a form that changes something in Wilma (a reply, a sign-up, an
+     * absence report): one POST, never repeated. Unlike request(), it doesn't
+     * log in again and retry when the session has ended — after a new login
+     * the form's key is stale, and a write must not be sent twice — it fails
+     * with SessionEndedError instead (nothing was sent; prepare the form
+     * again). Redirects within Wilma are followed; the answer is returned for
+     * the caller to check.
+     */
+    async submit(path, form, opts = {}) {
+        const auth = this.auth;
+        if (auth.failed)
+            throw auth.failed;
+        if (auth.relogin)
+            await auth.relogin.catch(() => { });
+        if (!auth.loggedIn)
+            throw new SessionEndedError("Not logged in to Wilma; nothing was sent");
+        const prefixedPath = this.getPrefixedPath(path);
+        const body = (form instanceof URLSearchParams ? form : new URLSearchParams(form)).toString();
+        const generation = auth.generation;
+        const resp = await this.rawRequest(prefixedPath, {
+            method: "POST",
+            body,
+            headers: { ...opts.headers, "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8" },
+            stopAtLogin: true,
+        });
+        // 403 is also how Wilma answers a session another login cancelled.
+        const ended = resp.status === 401 ||
+            this.isLoginRedirect(resp) ||
+            (resp.status === 403 && auth.generation === generation && !(await this.sessionAlive()));
+        if (ended) {
+            await resp.body?.cancel();
+            auth.loggedIn = false;
+            auth.endedByWilma = true;
+            auth.onEvent?.("ended");
+            // The form belonged to the ended session. Preparing again (a read) continues another program's session, or logs in when allowed.
+            throw new SessionEndedError("Wilma ended the session; nothing was sent. Prepare it again.");
+        }
+        if (resp.status >= 300 && resp.status < 400) {
+            await resp.body?.cancel();
+            throw new APIError(`Wilma redirected to another site at ${redactPath(prefixedPath)}`, resp.status);
+        }
+        return resp;
+    }
     async getLoginToken() {
         const resp = await this.rawRequest("/token", { method: "GET" });
         if (resp.status !== 200) {
@@ -456,17 +650,20 @@ export class WilmaSession {
         }
         baseHeaders.set("User-Agent", USER_AGENT);
         baseHeaders.set("Referer", `${this.baseUrl}/`);
-        const { stopAtLogin, ...fetchInit } = init ?? {};
+        const stopAtLogin = init?.stopAtLogin;
         const follow = init?.redirect !== "manual";
         const idle = new IdleTimer(timeoutMs);
         const signal = init?.signal ? AbortSignal.any([init.signal, idle.signal]) : idle.signal;
         let method = (init?.method ?? "GET").toUpperCase();
         let body = init?.body;
         for (let hop = 0;; hop += 1) {
-            const headers = new Headers(baseHeaders);
+            const headers = {};
+            baseHeaders.forEach((value, key) => {
+                headers[key] = value;
+            });
             const cookieHeader = this.auth.cookieJar.getCookieStringSync(url.href);
             if (cookieHeader)
-                headers.set("Cookie", cookieHeader);
+                headers["cookie"] = cookieHeader;
             if (this.debug) {
                 // Method and path only: never headers, bodies or query strings.
                 console.error(`[wilmai] ${method} ${redactPath(url.pathname)}`);
@@ -474,30 +671,28 @@ export class WilmaSession {
             let resp;
             try {
                 idle.touch();
-                resp = await fetch(url, { ...fetchInit, method, body, headers, signal, redirect: "manual" });
+                const reply = await this.auth.transport({ url: url.href, method, headers, body, signal });
+                for (const cookie of reply.setCookies) {
+                    // A cookie Wilma isn't allowed to set (e.g. for another domain) is dropped, not fatal.
+                    this.auth.cookieJar.setCookieSync(cookie, url.href, { ignoreError: true });
+                }
+                resp = watchedResponse({ status: reply.status, headers: reply.headers, body: reply.body, url: url.href }, idle, origin);
             }
             catch (err) {
                 idle.stop();
                 // Timeouts, and `fetch failed` with its cause code and remediation attached.
                 throw asNetworkError(err, origin);
             }
-            const headersAny = resp.headers;
-            const setCookies = headersAny.getSetCookie?.() ?? [];
-            const single = setCookies.length ? [] : [resp.headers.get("set-cookie")].filter((c) => !!c);
-            for (const cookie of [...setCookies, ...single]) {
-                // A cookie Wilma isn't allowed to set (e.g. for another domain) is dropped, not fatal.
-                this.auth.cookieJar.setCookieSync(cookie, url.href, { ignoreError: true });
-            }
             const location = resp.headers.get("location");
             if (!follow || resp.status < 300 || resp.status >= 400 || !location) {
-                return watchBody(resp, idle, origin);
+                return resp;
             }
             const next = new URL(location, url);
             if (next.origin !== origin) {
-                return watchBody(resp, idle, origin); // hand the off-site redirect back to the caller
+                return resp; // hand the off-site redirect back to the caller
             }
             if (stopAtLogin && /^\/login\/?$/i.test(next.pathname)) {
-                return watchBody(resp, idle, origin); // logged out: the caller decides
+                return resp; // logged out: the caller decides
             }
             if (hop >= MAX_REDIRECTS) {
                 idle.stop();
@@ -532,6 +727,18 @@ function isPermanentLoginFailure(err) {
     return (err instanceof MfaRequiredError ||
         (err instanceof AuthenticationError && /^Wilma login failed/.test(err.message)));
 }
+/** Does the jar hold a Wilma session cookie for this Wilma? */
+function holdsSession(jar, baseUrl) {
+    return sessionCookie(jar, baseUrl) !== null;
+}
+/** The Wilma session cookie's value, telling sessions apart. */
+function sessionCookie(jar, baseUrl) {
+    return jar.getCookiesSync(baseUrl).find((cookie) => cookie.key === "Wilma2SID")?.value ?? null;
+}
+/** The formkey of Wilma's logout form (`<form id="logout-form" action="/logout">`, on every page of a live session). */
+function logoutFormkey(html) {
+    return cheerio.load(html)('form#logout-form input[name="formkey"]').attr("value") || null;
+}
 function isLoginOk(text) {
     return !LOGIN_FAIL_RE.test(text);
 }

package/dist/timeouts.d.ts

@@ -1,4 +1,3 @@
-import { Response } from "undici";
 /** An abort signal that fires after `ms` without progress. */
 export declare class IdleTimer {
     private readonly ms;
@@ -17,4 +16,20 @@ export declare function asNetworkError(err: unknown, origin: string): unknown;
  * restarts the wait, and a stall or broken connection while reading surfaces
  * as a NetworkError, like one before the response.
  */
-export declare function watchBody(response: Response, idle: IdleTimer, origin: string): Response;
+export declare function watchBody(response: {
+    status: number;
+    statusText?: string;
+    headers: unknown;
+    body: unknown;
+    url: string;
+}, idle: IdleTimer, origin: string): Response;
+export interface ResponseParts {
+    status: number;
+    statusText?: string;
+    headers: Headers;
+    body: ReadableStream<Uint8Array> | string | null;
+    /** The address that answered: parsers resolve links against it. */
+    url: string;
+}
+/** A standard Response from a transport's reply, its body read under the idle timer. */
+export declare function watchedResponse(parts: ResponseParts, idle: IdleTimer, origin: string): Response;

package/dist/timeouts.js

@@ -4,7 +4,6 @@
  * read — not after a fixed total, so a large attachment on a slow connection
  * still finishes while a stalled one doesn't hang forever.
  */
-import { Response } from "undici";
 import { NetworkError, wrapNetworkError } from "./network-error.js";
 /** An abort signal that fires after `ms` without progress. */
 export class IdleTimer {
@@ -22,8 +21,8 @@ export class IdleTimer {
     touch() {
         clearTimeout(this.timer);
         this.timer = setTimeout(() => this.controller.abort(new DOMException("The server stopped answering", "TimeoutError")), this.ms);
-        // A response nobody reads must not keep the process alive.
-        this.timer.unref?.();
+        // A response nobody reads must not keep the process alive (Node only).
+        this.timer?.unref?.();
     }
     stop() {
         clearTimeout(this.timer);
@@ -44,11 +43,28 @@ const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
  * as a NetworkError, like one before the response.
  */
 export function watchBody(response, idle, origin) {
-    if (!response.body || NULL_BODY_STATUSES.has(response.status)) {
-        idle.stop();
+    return watchedResponse({
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+        body: response.body,
+        url: response.url,
+    }, idle, origin);
+}
+/** A standard Response from a transport's reply, its body read under the idle timer. */
+export function watchedResponse(parts, idle, origin) {
+    const make = (body) => {
+        const response = new Response(body, { status: parts.status, statusText: parts.statusText, headers: parts.headers });
+        Object.defineProperty(response, "url", { value: parts.url });
         return response;
+    };
+    if (parts.body === null || typeof parts.body === "string" || NULL_BODY_STATUSES.has(parts.status)) {
+        idle.stop();
+        if (parts.body && typeof parts.body !== "string")
+            void parts.body.cancel().catch(() => { });
+        return make(NULL_BODY_STATUSES.has(parts.status) ? null : parts.body);
     }
-    const reader = response.body.getReader();
+    const reader = parts.body.getReader();
     const body = new ReadableStream({
         async pull(controller) {
             try {
@@ -71,12 +87,5 @@ export function watchBody(response, idle, origin) {
             return reader.cancel(reason);
         },
     });
-    const watched = new Response(body, {
-        status: response.status,
-        statusText: response.statusText,
-        headers: response.headers,
-    });
-    // Parsers resolve links against the final address.
-    Object.defineProperty(watched, "url", { value: response.url });
-    return watched;
+    return make(body);
 }

package/dist/transport-node.d.ts

@@ -0,0 +1,2 @@
+import type { WilmaTransport } from "./transport.js";
+export declare const nodeTransport: WilmaTransport;

package/dist/transport-node.js

@@ -0,0 +1,19 @@
+/* The Node transport: undici's fetch, redirects not followed. */
+import { fetch } from "undici";
+export const nodeTransport = async (request) => {
+    const resp = await fetch(request.url, {
+        method: request.method,
+        headers: request.headers,
+        body: request.body,
+        signal: request.signal,
+        redirect: "manual",
+    });
+    const headers = resp.headers;
+    const setCookies = headers.getSetCookie?.() ?? [resp.headers.get("set-cookie")].filter((c) => Boolean(c));
+    return {
+        status: resp.status,
+        headers,
+        setCookies,
+        body: resp.body,
+    };
+};

package/dist/transport.d.ts

@@ -0,0 +1,21 @@
+export interface WilmaRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}
+export interface WilmaReply {
+    status: number;
+    /** Response headers; Set-Cookie may be missing here (browsers hide it), see setCookies. */
+    headers: Headers;
+    /** Every Set-Cookie header the response had, as sent. */
+    setCookies: string[];
+    /** The body as a stream, or a string when the transport already has it all; null when there is none. */
+    body: ReadableStream<Uint8Array> | string | null;
+}
+/** Send one request. Must not follow redirects: the session follows them itself, hop by hop. */
+export type WilmaTransport = (request: WilmaRequest) => Promise<WilmaReply>;
+/** Set the transport sessions use when none is given (the Node entry point sets undici). */
+export declare function setDefaultTransport(transport: WilmaTransport | null): void;
+export declare function getDefaultTransport(): WilmaTransport;

package/dist/transport.js

@@ -0,0 +1,19 @@
+/*
+ * How the client talks to a Wilma: one HTTP exchange at a time, redirects not
+ * followed, cookies handled by the session. Node uses undici (the default from
+ * the main entry point); a browser or desktop app passes its own transport to
+ * the "core" entry point, for example a native command that sends the request,
+ * because web pages can't call Wilma directly (no CORS) and can't read
+ * Set-Cookie headers.
+ */
+let defaultTransport = null;
+/** Set the transport sessions use when none is given (the Node entry point sets undici). */
+export function setDefaultTransport(transport) {
+    defaultTransport = transport;
+}
+export function getDefaultTransport() {
+    if (!defaultTransport) {
+        throw new Error("No transport for Wilma: pass `transport` in the client options (or use @wilm-ai/wilma-client, which uses undici on Node).");
+    }
+    return defaultTransport;
+}