@wilm-ai/wilma-cli 2.3.2 → 2.4.0

package/README.md

@@ -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

package/dist/access.d.ts

@@ -1,4 +1,5 @@
 import { WilmaAccess } from "./agent-data.js";
+import { type StoredProfile } from "./config.js";
 import { type ActiveAccount } from "./credentials.js";
 /**
  * Wilma access for the saved (or environment) logins — the same for CLI
@@ -24,3 +25,20 @@ export declare function logoutAccounts(accounts: ActiveAccount[]): Promise<{
     }[];
     hint: string;
 }>;
+export type RemovedSession = {
+    session: "ended" | "none";
+} | {
+    session: "not_ended";
+    message: 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>;

package/dist/access.js

@@ -1,5 +1,5 @@
-import { WilmaAccess, logoutSession } from "./agent-data.js";
-import { loadConfig, saveConfig } from "./config.js";
+import { WilmaAccess, WilmaAiError, forgetSession, logoutSession } from "./agent-data.js";
+import { loadConfig, revealSecret, saveConfig, savedStudent } from "./config.js";
 import { mfaCallbackFor } from "./credentials.js";
 /**
  * Wilma access for the saved (or environment) logins — the same for CLI
@@ -14,12 +14,13 @@ export function createAccess(accounts, opts = {}) {
         mfa: mfaCallbackFor(index === 0 && opts.totpSecret ? opts.totpSecret : account.totpSecret),
         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();
@@ -54,3 +55,47 @@ 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;
+    await saveConfig(config);
+    return { removed, ...(await endSession(removed)) };
+}
+async function endSession(removed) {
+    const password = revealSecret(removed.passwordObfuscated);
+    if (!password)
+        return { session: "none" };
+    const profile = { baseUrl: removed.tenantUrl, username: removed.username, password };
+    try {
+        return { session: (await logoutSession(profile)) ? "ended" : "none" };
+    }
+    catch (err) {
+        await forgetSession(profile);
+        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);
+}

package/dist/agent-data.d.ts

@@ -1,4 +1,4 @@
-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";
 /**
  * An error with a stable code for agents and scripts (the CLI's JSON errors
@@ -19,11 +19,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[];
@@ -44,7 +55,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;
@@ -106,9 +120,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 +144,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 +193,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 +205,8 @@ export declare class WilmaAccess {
                     pinned: boolean;
                 }[];
                 messages: {
+                    invitationStatus?: string | null | undefined;
+                    invitationInfo?: string | null | undefined;
                     wilmaId: number;
                     subject: string;
                     sentAt: Date;
@@ -179,8 +232,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 +244,8 @@ export declare class WilmaAccess {
                     pinned: boolean;
                 }[];
                 messages: {
+                    invitationStatus?: string | null | undefined;
+                    invitationInfo?: string | null | undefined;
                     wilmaId: number;
                     subject: string;
                     sentAt: Date;
@@ -211,17 +266,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 +317,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 +330,7 @@ export declare class WilmaAccess {
         students: ({
             student: StudentRef;
         } & {
-            lessons: import("@wilm-ai/wilma-client").ScheduleLesson[];
+            lessons: ScheduleLesson[];
         })[];
         problems: {
             wilma: string;
@@ -248,17 +338,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 +398,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 +425,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 +538,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 +620,7 @@ export declare class WilmaAccess {
         students: ({
             student: StudentRef;
         } & {
-            messages: Message[];
+            messages: ListedMessage[];
         })[];
         problems: {
             wilma: string;
@@ -460,7 +630,7 @@ export declare class WilmaAccess {
         students: ({
             student: StudentRef;
         } & {
-            messages: Message[];
+            messages: ListedMessage[];
         })[];
         problems?: undefined;
     }>;