@wilm-ai/wilma-cli 2.3.2 → 2.5.0

package/README.md

@@ -14,7 +14,7 @@ pnpm add -g @wilm-ai/wilma-cli
 ```bash
 wilma login
 ```
-Opens a one-time login page in your browser: pick your school's Wilma and log in. The login is saved to `~/.config/wilmai/config.json`.
+Opens a one-time login page in your browser: pick your school's Wilma and log in. The login is saved to `~/.config/wilmai/config.json` (the password can go to the keychain instead: see Config).
 
 Without a browser: `wilma login --tenant <url|city> --username <name>` with the password in `WILMA_PASSWORD` or piped via `--password-stdin`. Or set `WILMA_TENANT`, `WILMA_USERNAME`, `WILMA_PASSWORD` (and `WILMA_TOTP_SECRET`) and skip the saved login.
 
@@ -65,7 +65,7 @@ Starts a stdio MCP server with read-only Wilma tools (`wilma_summary`, `wilma_sc
 `wilma news <id>` lists every link in a bulletin (`resources`). Any resource can be downloaded with `wilma news <id> download <resource> [--output <directory>]` (the resource id also accepts a bare number, e.g. `1` for `resource-1`). Wilma-hosted files download through the session; external links are fetched without your Wilma login, and only from public websites. The result's `status` says what happened: `downloaded` (use the returned `path`) or `not_a_file` when the link answered with a web page (for example a sharing link that needs signing in — open it in a browser instead). `--output` defaults to the current directory; existing files are never overwritten.
 
 ## Several Wilmas
-Children at schools on different Wilmas need one login per Wilma. Run `wilma login` again (or press "Add another Wilma" on the login page); commands then cover every child, and each child carries the `wilma` it belongs to.
+Children at schools on different Wilmas need one login per Wilma. Run `wilma login` again (or press "Add another school's Wilma" on the login page); commands then cover every child, and each child carries the `wilma` it belongs to.
 ```bash
 wilma accounts                     # saved logins, numbered
 wilma accounts remove <number>     # or the Wilma name or username; also ends that login's Wilma session
@@ -79,6 +79,7 @@ wilma find-school <city or school>
 ## Other
 ```bash
 wilma update                       # when a newer version is out, a command says so on stderr, at most once a day (WILMAI_NO_UPDATE_CHECK=1 turns it off)
+wilma config secrets               # where saved passwords are kept; `wilma config secrets auto` moves them to the keychain
 wilma config clear                 # deletes every saved login and session
 wilma home                         # where to download WilmAI Home, the Wilma app for Mac and Windows
 wilma --version
@@ -95,6 +96,22 @@ If your Wilma account has MFA/TOTP enabled:
 ## Config
 Logins are saved in `~/.config/wilmai/config.json` (or `$XDG_CONFIG_HOME/wilmai/config.json`; override with `WILMAI_CONFIG_PATH`) and the current Wilma sessions in `wilmai-sessions.json` next to it, both readable only by you. `wilma logout` ends the sessions and deletes them, keeping the logins; `wilma config clear` deletes both.
 
+### Passwords in the keychain (optional)
+By default the password and authenticator key are in that file too, scrambled (not encrypted), like aws, npm or kubectl keep theirs. To keep them in the operating system's keychain instead:
+
+```bash
+wilma config secrets auto       # the keychain where there is one, the file where there isn't
+wilma config secrets keychain   # the keychain only; saving fails where there is none
+wilma config secrets file       # back to the file
+wilma config secrets            # where each login's password is now
+```
+
+The file stays the default, and stays available: on a server or anything unattended (cron, CI, an agent such as OpenClaw) there's no logged-in user to unlock a keychain, so keep the file there (`auto` does that by itself). Changing the setting moves the saved logins without logging in again. The keychain is the macOS Keychain (through `/usr/bin/security`, so no prompts after a Node.js upgrade), Windows Credential Manager, or a Linux desktop's Secret Service (headless Linux has none: `auto` keeps the file there). `WILMAI_SECRET_STORE=file|auto|keychain` decides where new logins go for one process, for tools that run the CLI; it never moves saved logins.
+
+What stays in files: the rest of the login (Wilma, username, children) and the current Wilma sessions, which give the same access as the password while they last (Wilma ends them after a few hours). The keychain keeps the password out of backups, synced dotfiles and anything that reads files; it doesn't protect against a program running as you, which can ask the keychain too. On Windows, saved credentials roam with a roaming profile. Older copies of the config (backups, synced dotfiles) still hold the password; changing the Wilma password makes them useless. A keychain entry left behind by a config deleted by hand is named `ai.wilm.wilma-cli` in Keychain Access or Credential Manager.
+
+Errors: `secret_missing` (the entry is gone: `wilma login`), `secret_refused` (the keychain is locked or said no), `secret_unavailable` (no keychain this copy can use), all with exit code 4. The Linux binaries of the optional `@napi-rs/keyring` dependency statically link libdbus (`AFL-2.1 OR GPL-2.0-or-later`).
+
 ## Troubleshooting: TLS errors on a managed laptop
 
 A TLS certificate error means the network is intercepting TLS and re-signing with a
@@ -125,6 +142,6 @@ In JSON, transport failures have the code `network`, with the underlying `cause`
 ```
 
 ## Notes
-- Credentials and TOTP secrets are stored with lightweight obfuscation (not encryption) in a file only your user can read.
+- Credentials and TOTP secrets are stored with lightweight obfuscation (not encryption) in a file only your user can read, or in the OS keychain with `wilma config secrets auto` (see Config).
 - Bulletin links are fetched only from public websites (never local or private network addresses), without your Wilma login.
 - Commands cover every child; `--student <number|name>` narrows to one.

package/dist/access.d.ts

@@ -1,5 +1,7 @@
+import type { StudentInfo, WilmaClient } from "@wilm-ai/wilma-client";
 import { WilmaAccess } from "./agent-data.js";
-import { type ActiveAccount } from "./credentials.js";
+import { type StoredProfile } from "./config.js";
+import { type ActiveAccount, type StoreChoice } from "./credentials.js";
 /**
  * Wilma access for the saved (or environment) logins — the same for CLI
  * commands and the local MCP server. Refreshed child lists are written back
@@ -24,3 +26,40 @@ export declare function logoutAccounts(accounts: ActiveAccount[]): Promise<{
     }[];
     hint: string;
 }>;
+export type RemovedSession = ({
+    session: "ended" | "none";
+} | {
+    session: "not_ended";
+    message: string;
+}) & {
+    /** Its keychain entry couldn't be deleted (it stays recorded, so `wilma config clear` can try again). */
+    keychainEntryLeft?: string;
+};
+/**
+ * Remove a saved login (`wilma accounts remove`, the login page's Remove) and
+ * end its Wilma session; the other logins keep theirs. The login is removed
+ * even when Wilma can't be reached: its saved session is forgotten anyway,
+ * and Wilma ends the session when it expires.
+ */
+export declare function removeLogin(id: string): Promise<{
+    removed: StoredProfile;
+} & RemovedSession>;
+/** Which of a login's children aren't read (unticked on the login page); only children the login lists count. */
+export declare function setHiddenChildren(id: string, hidden: string[]): Promise<void>;
+/**
+ * After Wilma accepted a login: save it where `choice` (chooseSecretStore,
+ * decided before contacting Wilma) says, and only then keep the verified
+ * session, under the saved login's keys, so the next command or tool call
+ * needs no second login (or code). A login that couldn't be saved leaves no
+ * session behind.
+ */
+export declare function saveVerifiedLogin(input: {
+    tenantUrl: string;
+    tenantName?: string | null;
+    username: string;
+    password: string;
+    totpSecret?: string | null;
+    students: StudentInfo[];
+}, client: WilmaClient, choice: StoreChoice): Promise<StoredProfile & {
+    note?: string;
+}>;

package/dist/access.js

@@ -1,6 +1,32 @@
-import { WilmaAccess, logoutSession } from "./agent-data.js";
-import { loadConfig, saveConfig } from "./config.js";
-import { mfaCallbackFor } from "./credentials.js";
+import { WilmaAccess, WilmaAiError, adoptSession, forgetSession, logoutSession } from "./agent-data.js";
+import { editConfig, loadConfig, saveConfig, savedStudent } from "./config.js";
+import { accountFor, mfaCallbackFor, saveLogin } from "./credentials.js";
+import { deleteLoginSecrets } from "./secret-store.js";
+/**
+ * Codes from the saved authenticator key. A keychain login's key comes from
+ * the same single read as its password (no second keychain access), and one
+ * code generator serves the whole process, so a rejected code waits for the
+ * next one instead of repeating it.
+ */
+function mfaFor(account) {
+    if (!account.secrets)
+        return mfaCallbackFor(account.totpSecret);
+    if (!account.hasTotp)
+        return undefined;
+    const read = account.secrets;
+    let generator = null;
+    return async (formkey) => {
+        const pending = (generator ??= read().then((secrets) => mfaCallbackFor(secrets.totpSecret)));
+        pending.catch(() => {
+            if (generator === pending)
+                generator = null;
+        });
+        const callback = await pending;
+        if (!callback)
+            throw new WilmaAiError("mfa_required", "Wilma asks for a two-step verification code, and no authenticator key is saved for this login. Run `wilma login`.");
+        return callback(formkey);
+    };
+}
 /**
  * Wilma access for the saved (or environment) logins — the same for CLI
  * commands and the local MCP server. Refreshed child lists are written back
@@ -10,16 +36,19 @@ import { mfaCallbackFor } from "./credentials.js";
 export function createAccess(accounts, opts = {}) {
     return new WilmaAccess(accounts.map((account, index) => ({
         profile: { ...account.profile, debug: opts.debug ?? account.profile.debug },
+        password: account.secrets ? async () => (await account.secrets()).password : undefined,
+        keys: account.keys,
         // A --totp-secret given on the command line belongs to the first (active) login.
-        mfa: mfaCallbackFor(index === 0 && opts.totpSecret ? opts.totpSecret : account.totpSecret),
+        mfa: index === 0 && opts.totpSecret ? mfaCallbackFor(opts.totpSecret) : mfaFor(account),
         label: account.stored?.tenantName ?? account.profile.baseUrl,
         knownStudents: account.stored?.students,
+        hidden: account.stored?.hidden,
         onStudents: async (students) => {
             const stored = account.stored;
             // An empty answer from Wilma keeps the saved list (see knownStudents).
             if (!stored || !students.length)
                 return;
-            const fresh = students.map((s) => ({ studentNumber: s.studentNumber, name: s.name }));
+            const fresh = students.map(savedStudent);
             if (JSON.stringify(fresh) === JSON.stringify(stored.students ?? []))
                 return;
             const latest = await loadConfig();
@@ -37,7 +66,7 @@ export function createAccess(accounts, opts = {}) {
  * (different Wilmas don't affect each other), then throws the first failure.
  */
 export async function logoutAccounts(accounts) {
-    const results = await Promise.allSettled(accounts.map((account) => logoutSession(account.profile)));
+    const results = await Promise.allSettled(accounts.map((account) => logoutSession(account.profile, account.keys)));
     const failed = results.find((result) => result.status === "rejected");
     if (failed)
         throw failed.reason;
@@ -54,3 +83,73 @@ export async function logoutAccounts(accounts) {
             : "No saved Wilma login, so there was nothing to log out.",
     };
 }
+/**
+ * Remove a saved login (`wilma accounts remove`, the login page's Remove) and
+ * end its Wilma session; the other logins keep theirs. The login is removed
+ * even when Wilma can't be reached: its saved session is forgotten anyway,
+ * and Wilma ends the session when it expires.
+ */
+export async function removeLogin(id) {
+    const config = await loadConfig();
+    const removed = config.profiles.find((p) => p.id === id);
+    if (!removed)
+        throw new WilmaAiError("unknown_account", "That login isn't saved any more.");
+    config.profiles = config.profiles.filter((p) => p.id !== id);
+    if (config.lastProfileId === id)
+        config.lastProfileId = config.profiles[0]?.id ?? null;
+    const entry = removed.secretId ?? config.keychainLogins?.[id];
+    await saveConfig(config);
+    // The session first (it needs no password), then the keychain entry; its record goes only once it's deleted.
+    const session = await endSession(removed);
+    if (!entry)
+        return { removed, ...session };
+    try {
+        await deleteLoginSecrets(entry);
+    }
+    catch (err) {
+        return { removed, ...session, keychainEntryLeft: err instanceof Error ? err.message : String(err) };
+    }
+    await editConfig((fresh) => {
+        if (fresh.keychainLogins?.[id] !== entry)
+            return false;
+        const { [id]: _gone, ...rest } = fresh.keychainLogins;
+        fresh.keychainLogins = rest;
+    });
+    return { removed, ...session };
+}
+async function endSession(removed) {
+    const { profile, keys } = accountFor(removed);
+    try {
+        return { session: (await logoutSession(profile, keys)) ? "ended" : "none" };
+    }
+    catch (err) {
+        await forgetSession(profile, keys);
+        return { session: "not_ended", message: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Which of a login's children aren't read (unticked on the login page); only children the login lists count. */
+export async function setHiddenChildren(id, hidden) {
+    const config = await loadConfig();
+    const target = config.profiles.find((p) => p.id === id);
+    if (!target)
+        throw new WilmaAiError("unknown_account", "That login isn't saved any more.");
+    const known = new Set((target.students ?? []).map((s) => s.studentNumber));
+    const kept = [...new Set(hidden)].filter((number) => known.has(number));
+    if (kept.length)
+        target.hidden = kept;
+    else
+        delete target.hidden;
+    await saveConfig(config);
+}
+/**
+ * After Wilma accepted a login: save it where `choice` (chooseSecretStore,
+ * decided before contacting Wilma) says, and only then keep the verified
+ * session, under the saved login's keys, so the next command or tool call
+ * needs no second login (or code). A login that couldn't be saved leaves no
+ * session behind.
+ */
+export async function saveVerifiedLogin(input, client, choice) {
+    const stored = await saveLogin(await loadConfig(), input, choice);
+    adoptSession(accountFor(stored).keys, client);
+    return stored;
+}

package/dist/agent-data.d.ts

@@ -1,5 +1,6 @@
-import { WilmaClient, type LessonNote, type Message, type MessageFolder, type MfaCallback, type NewsItem, type NewsResource, type OverviewData, type StudentInfo, type WilmaProfile } from "@wilm-ai/wilma-client";
+import { WilmaClient, type LessonNote, type Message, type MessageFolder, type MfaCallback, type NewsItem, type NewsResource, type OverviewData, type ScheduleLesson, type StudentInfo, type WilmaProfile } from "@wilm-ai/wilma-client";
 import type { SessionStore } from "./session-store.js";
+import { type SessionKeys } from "./session-keys.js";
 /**
  * An error with a stable code for agents and scripts (the CLI's JSON errors
  * and exit codes use it): e.g. "unknown_student", "invalid_argument".
@@ -19,11 +20,22 @@ export type ScheduleDateSelection = {
     outputWhen: string;
 };
 export declare const SCHEDULE_WHEN: readonly ["today", "tomorrow", "week", "next-week"];
+/** The longest period one schedule request covers. */
+export declare const SCHEDULE_MAX_DAYS = 31;
+/**
+ * An event invitation as listed: the message, plus the family's answer as
+ * Wilma's list shows it ("Applied" with the chosen time, "ExpiredReg"…;
+ * null when it shows none).
+ */
+export type ListedMessage = Message & {
+    invitationStatus?: string | null;
+    invitationInfo?: string | null;
+};
 /** Everything a daily summary is built from (see fetchSummaryInputs). */
 export interface SummaryInputs {
     overview: OverviewData;
     news: NewsItem[];
-    messages: Message[];
+    messages: ListedMessage[];
     lessonNotes: LessonNote[];
     /** Parts Wilma couldn't give this time (the rest of the summary is still right). */
     unavailable: string[];
@@ -35,7 +47,12 @@ export type StudentRef = {
 };
 /** One Wilma login. A family can have several (children on different Wilmas). */
 export interface AccessAccount {
+    /** For a keychain login the password is empty here and `password` gives it. */
     profile: WilmaProfile;
+    /** The password when Wilma needs a new login (a keychain read), never while a saved session works. */
+    password?: () => Promise<string>;
+    /** Where its session is saved and pooled; by default today's key (address, username and password). */
+    keys?: SessionKeys;
     mfa?: MfaCallback;
     /** The Wilma's name, shown to tell children apart when there are several logins. */
     label?: string | null;
@@ -44,7 +61,10 @@ export interface AccessAccount {
     knownStudents?: {
         studentNumber: string;
         name: string;
+        role?: StudentInfo["role"];
     }[];
+    /** Student numbers unticked on the login page (a profile Wilma lists twice): not read. */
+    hidden?: string[];
 }
 type AccountStudent = StudentInfo & {
     account: number;
@@ -70,26 +90,29 @@ export declare function useSessionStore(store: SessionStore | undefined): void;
 /**
  * Keep a session that is already logged in — e.g. the one the login page just
  * verified — so the first tool call needs no second login (and, with two-step
- * verification, no second code).
+ * verification, no second code). `keys` are the saved login's (v2 for a
+ * keychain login); without them, today's keys from the profile.
  */
-export declare function adoptSession(profile: WilmaProfile, client: WilmaClient): void;
+export declare function adoptSession(profileOrKeys: WilmaProfile | SessionKeys, client: WilmaClient): void;
 /**
  * Finish saving sessions (call before a short-lived process exits). Only
  * logins made here are saved, never an older session over a newer one
  * another process saved meanwhile.
  */
 export declare function flushSessions(): Promise<void>;
+/** Drop this process's client for a login (after its secrets moved, so the next use starts from its new keys). */
+export declare function dropPooledSession(keys: SessionKeys): void;
 /**
  * End WilmAI's Wilma session for one login (Wilma's own "Log out") and forget
  * it, in this process and in the session store, so nothing continues it. The
  * login itself stays saved; the next command or tool call logs in again.
- * Never logs in. Returns true when a live session was ended, false when there
- * was none. If Wilma can't be reached, throws and keeps the saved session, so
- * logging out can be tried again.
+ * Never logs in (so it needs no password). Returns true when a live session
+ * was ended, false when there was none. If Wilma can't be reached, throws and
+ * keeps the saved session, so logging out can be tried again.
  */
-export declare function logoutSession(profile: WilmaProfile): Promise<boolean>;
+export declare function logoutSession(profile: WilmaProfile, keys?: SessionKeys): Promise<boolean>;
 /** Forget one login's session without ending it in Wilma (when the login itself is removed). */
-export declare function forgetSession(profile: WilmaProfile): Promise<void>;
+export declare function forgetSession(profile: WilmaProfile, keys?: SessionKeys): Promise<void>;
 /**
  * Read-only Wilma access for agent tools (MCP). Covers every Wilma login the
  * family has saved; every method defaults to all children, and a student
@@ -106,9 +129,17 @@ export declare function matchStudents<T extends {
     studentNumber: string;
     name: string;
 }>(students: T[], student: string): T[];
+/** Whose login it is: a student's own when Wilma lists only the student themself, a guardian's when it says so. */
+export declare function roleOf(students: {
+    role?: StudentInfo["role"];
+}[]): StudentInfo["role"];
 export declare class WilmaAccess {
     private readonly accounts;
     private studentsCache;
+    /** The children each login lists (by login index), including those read through another login. */
+    private readonly listed;
+    /** Why a login failed (by login index), while others worked. */
+    private readonly failures;
     /** One logged-in session per Wilma login, shared by every child on it. */
     private readonly sessions;
     /** Logins that failed while other logins worked. */
@@ -122,8 +153,37 @@ export declare class WilmaAccess {
     private labelOf;
     private ref;
     students(): Promise<AccountStudent[]>;
-    /** The children as tools and commands show them (with their Wilma when there are several). */
-    studentList(): Promise<StudentRef[]>;
+    /**
+     * The children as tools and commands show them (with their Wilma when there
+     * are several), and whose login reads each: a guardian's, or the student's own.
+     */
+    studentList(): Promise<(StudentRef & {
+        role?: StudentInfo["role"];
+    })[]>;
+    /**
+     * Each login: its Wilma, username, whose it is (a guardian's, or a
+     * student's own; missing when Wilma doesn't say) and the children it lists.
+     * A child another login on the same Wilma also lists is read through one of
+     * them only; `readVia` names the other login's username. A child unticked
+     * on the login page has `hidden: true` and isn't read.
+     */
+    logins(): Promise<{
+        problem?: string | undefined;
+        children: ({
+            name: string;
+            studentNumber: string;
+            hidden: boolean;
+        } | {
+            readVia?: string | undefined;
+            name: string;
+            studentNumber: string;
+            hidden?: undefined;
+        })[];
+        role?: "guardian" | "student" | undefined;
+        wilma: string;
+        username: string;
+    }[]>;
+    private sameWilma;
     selectStudents(student?: string): Promise<AccountStudent[]>;
     private client;
     private perStudent;
@@ -142,8 +202,8 @@ export declare class WilmaAccess {
                 unavailable?: string[] | undefined;
                 today: string;
                 tomorrow: string;
-                todaySchedule: import("@wilm-ai/wilma-client").ScheduleLesson[];
-                tomorrowSchedule: import("@wilm-ai/wilma-client").ScheduleLesson[];
+                todaySchedule: ScheduleLesson[];
+                tomorrowSchedule: ScheduleLesson[];
                 upcomingExams: import("@wilm-ai/wilma-client").UpcomingExam[];
                 homework: import("@wilm-ai/wilma-client").HomeworkItem[];
                 lessonNotes: LessonNote[];
@@ -154,6 +214,8 @@ export declare class WilmaAccess {
                     pinned: boolean;
                 }[];
                 messages: {
+                    invitationStatus?: string | null | undefined;
+                    invitationInfo?: string | null | undefined;
                     wilmaId: number;
                     subject: string;
                     sentAt: Date;
@@ -179,8 +241,8 @@ export declare class WilmaAccess {
                 unavailable?: string[] | undefined;
                 today: string;
                 tomorrow: string;
-                todaySchedule: import("@wilm-ai/wilma-client").ScheduleLesson[];
-                tomorrowSchedule: import("@wilm-ai/wilma-client").ScheduleLesson[];
+                todaySchedule: ScheduleLesson[];
+                tomorrowSchedule: ScheduleLesson[];
                 upcomingExams: import("@wilm-ai/wilma-client").UpcomingExam[];
                 homework: import("@wilm-ai/wilma-client").HomeworkItem[];
                 lessonNotes: LessonNote[];
@@ -191,6 +253,8 @@ export declare class WilmaAccess {
                     pinned: boolean;
                 }[];
                 messages: {
+                    invitationStatus?: string | null | undefined;
+                    invitationInfo?: string | null | undefined;
                     wilmaId: number;
                     subject: string;
                     sentAt: Date;
@@ -211,17 +275,50 @@ export declare class WilmaAccess {
         when?: (typeof SCHEDULE_WHEN)[number];
         date?: string;
         weekday?: string;
+        from?: string;
+        to?: string;
     }): Promise<{
         students: ({
             student: StudentRef;
         } & {
-            lessons: import("@wilm-ai/wilma-client").ScheduleLesson[];
+            lessons: ScheduleLesson[];
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+        from: string;
+        to: string;
+        date?: undefined;
+        weekStart?: undefined;
+        weekEnd?: undefined;
+        when: string;
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            lessons: ScheduleLesson[];
+        })[];
+        problems?: undefined;
+        from: string;
+        to: string;
+        date?: undefined;
+        weekStart?: undefined;
+        weekEnd?: undefined;
+        when: string;
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            lessons: ScheduleLesson[];
         })[];
         problems: {
             wilma: string;
             message: string;
         }[];
         date: string;
+        from?: undefined;
+        to?: undefined;
         weekStart?: undefined;
         weekEnd?: undefined;
         when: string;
@@ -229,10 +326,12 @@ export declare class WilmaAccess {
         students: ({
             student: StudentRef;
         } & {
-            lessons: import("@wilm-ai/wilma-client").ScheduleLesson[];
+            lessons: ScheduleLesson[];
         })[];
         problems?: undefined;
         date: string;
+        from?: undefined;
+        to?: undefined;
         weekStart?: undefined;
         weekEnd?: undefined;
         when: string;
@@ -240,7 +339,7 @@ export declare class WilmaAccess {
         students: ({
             student: StudentRef;
         } & {
-            lessons: import("@wilm-ai/wilma-client").ScheduleLesson[];
+            lessons: ScheduleLesson[];
         })[];
         problems: {
             wilma: string;
@@ -248,17 +347,21 @@ export declare class WilmaAccess {
         }[];
         weekStart: string;
         weekEnd: string;
+        from?: undefined;
+        to?: undefined;
         date?: undefined;
         when: string;
     } | {
         students: ({
             student: StudentRef;
         } & {
-            lessons: import("@wilm-ai/wilma-client").ScheduleLesson[];
+            lessons: ScheduleLesson[];
         })[];
         problems?: undefined;
         weekStart: string;
         weekEnd: string;
+        from?: undefined;
+        to?: undefined;
         date?: undefined;
         when: string;
     }>;
@@ -304,9 +407,16 @@ export declare class WilmaAccess {
         })[];
         problems?: undefined;
     }>;
+    /**
+     * Exam grades: the newest the front page lists, or with `from` (to `to`,
+     * default today) Wilma's list of past exams for that period (Kokeet >
+     * Menneet), including exams still waiting for a grade (grade: null).
+     */
     grades(opts?: {
         student?: string;
         limit?: number;
+        from?: string;
+        to?: string;
     }): Promise<{
         students: ({
             student: StudentRef;
@@ -324,6 +434,27 @@ export declare class WilmaAccess {
             grades: import("@wilm-ai/wilma-client").ExamGrade[];
         })[];
         problems?: undefined;
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            grades: import("@wilm-ai/wilma-client").PastExam[];
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+        from: string;
+        to: string;
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            grades: import("@wilm-ai/wilma-client").PastExam[];
+        })[];
+        problems?: undefined;
+        from: string;
+        to: string;
     }>;
     /** Lesson notes for one day (default today), the last `days` days, or `from`–`to` (to defaults to today). */
     lessonNotes(opts?: {
@@ -416,6 +547,54 @@ export declare class WilmaAccess {
         })[];
         problems?: undefined;
     }>;
+    /**
+     * The child's class, class teacher and other supervisors (front page), and
+     * their own teachers (Wilma's recipient list) with what each teaches them,
+     * from this and next week's timetable. Parts Wilma can't give are listed in
+     * `unavailable`.
+     */
+    contacts(opts?: {
+        student?: string;
+    }): Promise<{
+        students: ({
+            student: StudentRef;
+        } & {
+            contacts: {
+                unavailable?: string[] | undefined;
+                className: string | null;
+                supervisors: {
+                    name: string;
+                    role: string;
+                }[];
+                teachers: {
+                    name: string;
+                    subjects: string[];
+                }[];
+            };
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            contacts: {
+                unavailable?: string[] | undefined;
+                className: string | null;
+                supervisors: {
+                    name: string;
+                    role: string;
+                }[];
+                teachers: {
+                    name: string;
+                    subjects: string[];
+                }[];
+            };
+        })[];
+        problems?: undefined;
+    }>;
     printouts(opts?: {
         student?: string;
     }): Promise<{
@@ -450,7 +629,7 @@ export declare class WilmaAccess {
         students: ({
             student: StudentRef;
         } & {
-            messages: Message[];
+            messages: ListedMessage[];
         })[];
         problems: {
             wilma: string;
@@ -460,7 +639,7 @@ export declare class WilmaAccess {
         students: ({
             student: StudentRef;
         } & {
-            messages: Message[];
+            messages: ListedMessage[];
         })[];
         problems?: undefined;
     }>;