@wilm-ai/wilma-client 1.9.0 → 1.10.0

package/README.md

@@ -50,6 +50,7 @@ Wilma allows one live session per account: a new login ends the previous one, an
 - **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.
+- The password for `resume()` can be a function, e.g. one reading a keychain: `WilmaClient.resume({ baseUrl, username, password: () => readFromKeychain() }, saved)`. It's called only when Wilma has ended the session and a new login is needed, never while the saved one works, and once for many requests. If it fails, the request fails with `CredentialsUnavailableError` (with `reason` and `cause` from your error) and the next request tries again: unlike a password Wilma refuses, it never stops the client for good.
 - `client.logout()` ends the session, as Wilma's own Log out does, so the parent can use Wilma in the browser. It never logs in: a session Wilma has already ended needs nothing, and it returns `false`. Afterwards the client and its `forStudent()` clients don't log in again by themselves. If Wilma can't be reached it throws and keeps the session, so it can be tried again.
 
 ### Any JavaScript runtime

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type SharedSession, type SessionEvent } from "./session.js";
+import { type PasswordSource, type SharedSession, type SessionEvent } from "./session.js";
 import type { Exam, GradebookEntry, Invitation, InvitationListing, MessageRecipient, StudentDetails, LessonNote, LessonNoteSummary, Message, MessageFolder, NewsItem, NewsResource, OverviewData, PastExam, Printout, StudentInfo, UpcomingExam, WilmaProfile } from "./types.js";
 import type { WilmaTransport } from "./transport.js";
 export type MfaCallback = (formkey: string) => Promise<string>;
@@ -19,6 +19,10 @@ export interface ClientOptions {
      */
     sharedSession?: SharedSession;
 }
+/** A profile for WilmaClient.resume(): the password may be a function called only for a new login. */
+export type ResumeProfile = Omit<WilmaProfile, "password"> & {
+    password: PasswordSource;
+};
 export declare class WilmaClient {
     private session;
     private constructor();
@@ -27,8 +31,13 @@ export declare class 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.
+     *
+     * The password may be a function (e.g. reading a keychain): it is called
+     * only when Wilma needs a new login, never while the saved session works.
+     * If it fails, the request fails with CredentialsUnavailableError and the
+     * next request tries again.
      */
-    static resume(profile: WilmaProfile, state: string, onMfaRequired?: MfaCallback, options?: ClientOptions): WilmaClient | null;
+    static resume(profile: ResumeProfile, state: string, onMfaRequired?: MfaCallback, options?: ClientOptions): WilmaClient | null;
     /**
      * A client on a saved session without any credentials: it never logs in.
      * When Wilma ends the session, requests fail with SessionEndedError. For

package/dist/client.js

@@ -47,6 +47,11 @@ export class 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.
+     *
+     * The password may be a function (e.g. reading a keychain): it is called
+     * only when Wilma needs a new login, never while the saved session works.
+     * If it fails, the request fails with CredentialsUnavailableError and the
+     * next request tries again.
      */
     static resume(profile, state, onMfaRequired, options = {}) {
         const session = new WilmaSession(profile.baseUrl, {

package/dist/core.d.ts

@@ -1,8 +1,8 @@
 export type { Exam, ExamGrade, GradebookEntry, HomeworkItem, Invitation, InvitationListing, InvitationSlot, InvitationSlotState, MessageRecipient, StudentDetails, LessonNote, LessonNoteSummary, Message, MessageReply, MessageFolder, Municipality, NewsItem, NewsResource, NewsResourceAuthContext, OverviewData, PastExam, Printout, ScheduleLesson, TenantDiscoveryResponse, TenantInfo, UpcomingExam, WilmaProfile, StudentInfo, } from "./types.js";
 export { WilmaClient } from "./client.js";
-export type { MfaCallback, ClientOptions } from "./client.js";
-export { WilmaSession, AuthenticationError, MfaRequiredError, APIError, SessionEndedError } from "./session.js";
-export type { SessionOptions, RequestInit, SharedSession, SessionEvent } from "./session.js";
+export type { MfaCallback, ClientOptions, ResumeProfile } from "./client.js";
+export { WilmaSession, AuthenticationError, MfaRequiredError, APIError, SessionEndedError, CredentialsUnavailableError } from "./session.js";
+export type { SessionOptions, RequestInit, SharedSession, SessionEvent, PasswordSource } from "./session.js";
 export { setDefaultTransport } from "./transport.js";
 export type { WilmaTransport, WilmaRequest, WilmaReply } from "./transport.js";
 export { DOWNLOAD_TIMEOUT_MS, isHtmlResponse, setExternalFetcher } from "./downloads.js";

package/dist/core.js

@@ -1,5 +1,5 @@
 export { WilmaClient } from "./client.js";
-export { WilmaSession, AuthenticationError, MfaRequiredError, APIError, SessionEndedError } from "./session.js";
+export { WilmaSession, AuthenticationError, MfaRequiredError, APIError, SessionEndedError, CredentialsUnavailableError } from "./session.js";
 export { setDefaultTransport } from "./transport.js";
 export { DOWNLOAD_TIMEOUT_MS, isHtmlResponse, setExternalFetcher } from "./downloads.js";
 export { NetworkError, describeNetworkCode, extractCauseCode, wrapNetworkError } from "./network-error.js";

package/dist/session.d.ts

@@ -56,6 +56,24 @@ export declare class APIError extends Error {
 export declare class SessionEndedError extends APIError {
     constructor(message?: string);
 }
+/**
+ * The password, or where to get it: a function called only when Wilma needs a
+ * new login (e.g. reading a keychain), not while a saved session works.
+ */
+export type PasswordSource = string | (() => Promise<string>);
+/**
+ * Wilma needed a new login and the password couldn't be had (the function
+ * given as the password failed: a keychain locked, declined or missing the
+ * entry). Not a refusal by Wilma, so it never stops the client for good;
+ * the next request tries again. `reason` and `cause` come from the failure.
+ */
+export declare class CredentialsUnavailableError extends Error {
+    reason: string;
+    constructor(message: string, options?: {
+        reason?: string;
+        cause?: unknown;
+    });
+}
 /**
  * What happened to a client's session, for a host that shows it (e.g. a
  * sign-in history): "login" (this client logged in), "adopted" (Wilma had
@@ -81,7 +99,7 @@ export declare class WilmaSession {
      * fails with SessionEndedError. Returns false when the state holds no
      * session to resume.
      */
-    resumeState(state: string, username?: string, password?: string): boolean;
+    resumeState(state: string, username?: string, password?: PasswordSource): boolean;
     /** Called after every successful login (first or again). */
     /** Share this login's session with the other WilmAI programs (see SharedSession). */
     setShared(shared: SharedSession | undefined): void;
@@ -138,6 +156,13 @@ export declare class WilmaSession {
      * waits for a fresh code.
      */
     answerMfa(formkey: string, onMfa: (formkey: string) => Promise<string>): Promise<void>;
+    /**
+     * The password for a new login. A function given as the password is called
+     * here, only now; its answer replaces it (as a login does). If it fails, the
+     * session is "ended by Wilma" (never "logged out", never failed for good)
+     * and the error is a CredentialsUnavailableError.
+     */
+    private resolvePassword;
     /**
      * 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

package/dist/session.js

@@ -35,6 +35,20 @@ export class SessionEndedError extends APIError {
         this.name = "SessionEndedError";
     }
 }
+/**
+ * Wilma needed a new login and the password couldn't be had (the function
+ * given as the password failed: a keychain locked, declined or missing the
+ * entry). Not a refusal by Wilma, so it never stops the client for good;
+ * the next request tries again. `reason` and `cause` come from the failure.
+ */
+export class CredentialsUnavailableError extends Error {
+    reason;
+    constructor(message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "CredentialsUnavailableError";
+        this.reason = options.reason ?? "unavailable";
+    }
+}
 /** 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;
@@ -268,6 +282,9 @@ export class WilmaSession {
         const ended = holdsSession(auth.cookieJar, this.baseUrl) ? await this.endSession() : false;
         auth.cookieJar.removeAllCookiesSync();
         auth.loggedIn = false;
+        // Logged out on purpose: not "ended by Wilma", so the next request neither
+        // logs in again nor continues a session another program saved.
+        auth.endedByWilma = false;
         auth.username = undefined;
         auth.password = undefined;
         return ended;
@@ -444,6 +461,36 @@ export class WilmaSession {
             }
         }
     }
+    /**
+     * The password for a new login. A function given as the password is called
+     * here, only now; its answer replaces it (as a login does). If it fails, the
+     * session is "ended by Wilma" (never "logged out", never failed for good)
+     * and the error is a CredentialsUnavailableError.
+     */
+    async resolvePassword() {
+        const auth = this.auth;
+        const source = auth.password;
+        if (typeof source !== "function")
+            return source ?? "";
+        try {
+            const password = await source();
+            if (typeof password !== "string" || !password)
+                throw new Error("No password was returned");
+            // logout() may have cleared it meanwhile: then it stays cleared.
+            if (auth.password === source)
+                auth.password = password;
+            return password;
+        }
+        catch (err) {
+            auth.loggedIn = false;
+            auth.endedByWilma = true;
+            auth.onEvent?.("ended");
+            if (err instanceof CredentialsUnavailableError)
+                throw err;
+            const reason = typeof err?.reason === "string" ? err.reason : undefined;
+            throw new CredentialsUnavailableError(err instanceof Error ? err.message : String(err), { reason, cause: err });
+        }
+    }
     /**
      * 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
@@ -462,6 +509,9 @@ export class WilmaSession {
                     auth.onEvent?.("ended");
                     throw new SessionEndedError();
                 }
+                // Get the password before changing anything: if it can't be had, the
+                // session stays "ended by Wilma" and the next request tries again.
+                const password = await this.resolvePassword();
                 auth.loggedIn = false;
                 // Start from a clean jar: a leftover session cookie must not make a
                 // failed login look successful.
@@ -469,7 +519,7 @@ export class WilmaSession {
                 if (this.debug)
                     console.error("[wilmai] session cancelled or expired; logging in again");
                 try {
-                    await this.login(auth.username, auth.password);
+                    await this.login(auth.username, password);
                 }
                 catch (err) {
                     if (err instanceof MfaRequiredError && auth.onMfa) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wilm-ai/wilma-client",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Unofficial client for Wilma, the Finnish school information system: login (with two-step verification), schedule, homework, exams, messages and news.",
   "license": "MIT",
   "repository": {
@@ -39,7 +39,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "lint": "tsc -p tsconfig.json --noEmit",
-    "test": "pnpm run build && node test/login.mjs && node test/logout.mjs && node test/core.mjs && node test/write.mjs && node test/parser-attendance.mjs && node test/parser-messages.mjs && node test/parser-news.mjs && node test/parser-schedule.mjs && node test/parser-students.mjs && node test/client-students.mjs && node test/client-schedule.mjs && node test/client-attendance.mjs && node test/client-news-resources.mjs && node test/network-error.mjs && node test/audit.mjs && node test/real-pages.mjs && node test/client-features.mjs",
+    "test": "pnpm run build && node test/login.mjs && node test/logout.mjs && node test/password-source.mjs && node test/core.mjs && node test/write.mjs && node test/parser-attendance.mjs && node test/parser-messages.mjs && node test/parser-news.mjs && node test/parser-schedule.mjs && node test/parser-students.mjs && node test/client-students.mjs && node test/client-schedule.mjs && node test/client-attendance.mjs && node test/client-news-resources.mjs && node test/network-error.mjs && node test/audit.mjs && node test/real-pages.mjs && node test/client-features.mjs",
     "test:live": "tsc -p tsconfig.json && node test/live.spec.mjs",
     "fixtures:anonymize": "node scripts/anonymize-fixture.mjs"
   },