@wilm-ai/wilma-cli 1.6.2 → 2.0.0

package/dist/agent-data.d.ts

@@ -0,0 +1,496 @@
+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 type { SessionStore } from "./session-store.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".
+ */
+export declare class WilmaAiError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+/** YYYY-MM-DD, or "today", "yesterday" or "tomorrow" (Finnish time). */
+export declare function parseIsoDate(raw: string): string;
+export type ScheduleDateSelection = {
+    when: string;
+    startDate: string;
+    endDate: string;
+    queryDate?: string;
+    outputWhen: string;
+};
+export declare const SCHEDULE_WHEN: readonly ["today", "tomorrow", "week", "next-week"];
+/** Everything a daily summary is built from (see fetchSummaryInputs). */
+export interface SummaryInputs {
+    overview: OverviewData;
+    news: NewsItem[];
+    messages: Message[];
+    lessonNotes: LessonNote[];
+    /** Parts Wilma couldn't give this time (the rest of the summary is still right). */
+    unavailable: string[];
+}
+export type StudentRef = {
+    studentNumber: string;
+    name: string;
+    wilma?: string;
+};
+/** One Wilma login. A family can have several (children on different Wilmas). */
+export interface AccessAccount {
+    profile: WilmaProfile;
+    mfa?: MfaCallback;
+    /** The Wilma's name, shown to tell children apart when there are several logins. */
+    label?: string | null;
+    onStudents?: (students: StudentInfo[]) => Promise<void>;
+    /** The children saved with the login, used when Wilma's own list comes back empty. */
+    knownStudents?: {
+        studentNumber: string;
+        name: string;
+    }[];
+}
+type AccountStudent = StudentInfo & {
+    account: number;
+};
+export type FetchedAttachment = {
+    status: "fetched";
+    /** Set for a bulletin attachment. */
+    newsId?: number;
+    /** Set for a printout (Tulosteet); `resource` then describes the printout. */
+    printoutId?: string;
+    resource: NewsResource;
+    fileName: string;
+    contentType: string | null;
+    data: Buffer;
+} | {
+    status: "not_a_file";
+    newsId: number;
+    resource: NewsResource;
+    message: string;
+};
+/** Continue saved sessions instead of logging in for each process (CLI and local MCP server). */
+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).
+ */
+export declare function adoptSession(profile: WilmaProfile, client: WilmaClient): void;
+/** Save any sessions still being written (call before a short-lived process exits). */
+export declare function flushSessions(): 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
+ * number or name narrows it. Uses one pooled session per Wilma login for
+ * listing and for every child.
+ */
+/**
+ * The students a name or number refers to. Agents and people pass names from
+ * free text, so match strictly: a student number, the full name, or the start
+ * of a name part ("Kiia" for "Kiia Example"). No fuzzy matching — a child not
+ * on the account must not match a sibling. Throws when nothing or several match.
+ */
+export declare function matchStudents<T extends {
+    studentNumber: string;
+    name: string;
+}>(students: T[], student: string): T[];
+export declare class WilmaAccess {
+    private readonly accounts;
+    private studentsCache;
+    /** One logged-in session per Wilma login, shared by every child on it. */
+    private readonly sessions;
+    /** Logins that failed while other logins worked. */
+    readonly problems: {
+        wilma: string;
+        message: string;
+    }[];
+    constructor(accounts: AccessAccount | AccessAccount[]);
+    private get multi();
+    private session;
+    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[]>;
+    selectStudents(student?: string): Promise<AccountStudent[]>;
+    private client;
+    private perStudent;
+    /** Try each selected student until one can open the item (messages and news are often shared across siblings). */
+    private firstStudentWith;
+    /** The daily briefing per child (see buildSummaryData). `since`: YYYY-MM-DD, "yesterday"… */
+    summary(opts?: {
+        student?: string;
+        days?: number;
+        since?: string;
+    }): Promise<{
+        students: ({
+            student: StudentRef;
+        } & {
+            summary: {
+                unavailable?: string[] | undefined;
+                today: string;
+                tomorrow: string;
+                todaySchedule: import("@wilm-ai/wilma-client").ScheduleLesson[];
+                tomorrowSchedule: import("@wilm-ai/wilma-client").ScheduleLesson[];
+                upcomingExams: import("@wilm-ai/wilma-client").UpcomingExam[];
+                homework: import("@wilm-ai/wilma-client").HomeworkItem[];
+                lessonNotes: LessonNote[];
+                news: {
+                    wilmaId: number;
+                    title: string;
+                    published: Date | null | undefined;
+                    pinned: boolean;
+                }[];
+                messages: {
+                    wilmaId: number;
+                    subject: string;
+                    sentAt: Date;
+                    senderName: string | null;
+                    folder: string;
+                    unread: boolean;
+                    replyCount: number;
+                }[];
+                unreadMessages: number;
+            };
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+        since?: string | undefined;
+        generatedAt: Date;
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            summary: {
+                unavailable?: string[] | undefined;
+                today: string;
+                tomorrow: string;
+                todaySchedule: import("@wilm-ai/wilma-client").ScheduleLesson[];
+                tomorrowSchedule: import("@wilm-ai/wilma-client").ScheduleLesson[];
+                upcomingExams: import("@wilm-ai/wilma-client").UpcomingExam[];
+                homework: import("@wilm-ai/wilma-client").HomeworkItem[];
+                lessonNotes: LessonNote[];
+                news: {
+                    wilmaId: number;
+                    title: string;
+                    published: Date | null | undefined;
+                    pinned: boolean;
+                }[];
+                messages: {
+                    wilmaId: number;
+                    subject: string;
+                    sentAt: Date;
+                    senderName: string | null;
+                    folder: string;
+                    unread: boolean;
+                    replyCount: number;
+                }[];
+                unreadMessages: number;
+            };
+        })[];
+        problems?: undefined;
+        since?: string | undefined;
+        generatedAt: Date;
+    }>;
+    schedule(opts?: {
+        student?: string;
+        when?: (typeof SCHEDULE_WHEN)[number];
+        date?: string;
+        weekday?: string;
+    }): Promise<{
+        students: ({
+            student: StudentRef;
+        } & {
+            lessons: import("@wilm-ai/wilma-client").ScheduleLesson[];
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+        date: string;
+        weekStart?: undefined;
+        weekEnd?: undefined;
+        when: string;
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            lessons: import("@wilm-ai/wilma-client").ScheduleLesson[];
+        })[];
+        problems?: undefined;
+        date: string;
+        weekStart?: undefined;
+        weekEnd?: undefined;
+        when: string;
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            lessons: import("@wilm-ai/wilma-client").ScheduleLesson[];
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+        weekStart: string;
+        weekEnd: string;
+        date?: undefined;
+        when: string;
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            lessons: import("@wilm-ai/wilma-client").ScheduleLesson[];
+        })[];
+        problems?: undefined;
+        weekStart: string;
+        weekEnd: string;
+        date?: undefined;
+        when: string;
+    }>;
+    homework(opts?: {
+        student?: string;
+        limit?: number;
+    }): Promise<{
+        students: ({
+            student: StudentRef;
+        } & {
+            homework: import("@wilm-ai/wilma-client").HomeworkItem[];
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            homework: import("@wilm-ai/wilma-client").HomeworkItem[];
+        })[];
+        problems?: undefined;
+    }>;
+    upcomingExams(opts?: {
+        student?: string;
+        limit?: number;
+    }): Promise<{
+        students: ({
+            student: StudentRef;
+        } & {
+            exams: import("@wilm-ai/wilma-client").UpcomingExam[];
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            exams: import("@wilm-ai/wilma-client").UpcomingExam[];
+        })[];
+        problems?: undefined;
+    }>;
+    grades(opts?: {
+        student?: string;
+        limit?: number;
+    }): Promise<{
+        students: ({
+            student: StudentRef;
+        } & {
+            grades: import("@wilm-ai/wilma-client").ExamGrade[];
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            grades: import("@wilm-ai/wilma-client").ExamGrade[];
+        })[];
+        problems?: undefined;
+    }>;
+    /** Lesson notes for one day (default today), the last `days` days, or `from`–`to` (to defaults to today). */
+    lessonNotes(opts?: {
+        student?: string;
+        date?: string;
+        days?: number;
+        from?: string;
+        to?: string;
+    }): Promise<{
+        students: ({
+            student: StudentRef;
+        } & {
+            notes: LessonNote[];
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+        from: string;
+        to: string;
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            notes: LessonNote[];
+        })[];
+        problems?: undefined;
+        from: string;
+        to: string;
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            notes: LessonNote[];
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+        date: string;
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            notes: LessonNote[];
+        })[];
+        problems?: undefined;
+        date: string;
+    }>;
+    /** Lesson notes counted by kind (absences, lateness, feedback…): this school year, or from a date. */
+    lessonNotesSummary(opts?: {
+        student?: string;
+        from?: string;
+        to?: string;
+    }): Promise<{
+        students: ({
+            student: StudentRef;
+        } & {
+            summary: import("@wilm-ai/wilma-client").LessonNoteSummary;
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            summary: import("@wilm-ai/wilma-client").LessonNoteSummary;
+        })[];
+        problems?: undefined;
+    }>;
+    gradebook(opts?: {
+        student?: string;
+    }): Promise<{
+        students: ({
+            student: StudentRef;
+        } & {
+            gradebook: import("@wilm-ai/wilma-client").GradebookEntry[];
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            gradebook: import("@wilm-ai/wilma-client").GradebookEntry[];
+        })[];
+        problems?: undefined;
+    }>;
+    printouts(opts?: {
+        student?: string;
+    }): Promise<{
+        students: ({
+            student: StudentRef;
+        } & {
+            printouts: import("@wilm-ai/wilma-client").Printout[];
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            printouts: import("@wilm-ai/wilma-client").Printout[];
+        })[];
+        problems?: undefined;
+    }>;
+    printout(opts: {
+        id: string;
+        student?: string;
+    }): Promise<FetchedAttachment & {
+        student: StudentRef;
+    }>;
+    messages(opts?: {
+        student?: string;
+        folder?: MessageFolder;
+        limit?: number;
+    }): Promise<{
+        students: ({
+            student: StudentRef;
+        } & {
+            messages: Message[];
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            messages: Message[];
+        })[];
+        problems?: undefined;
+    }>;
+    message(opts: {
+        id: number;
+        student?: string;
+    }): Promise<{
+        student: StudentRef;
+        message: Message;
+    }>;
+    news(opts?: {
+        student?: string;
+        limit?: number;
+        includeOlder?: boolean;
+    }): Promise<{
+        students: ({
+            student: StudentRef;
+        } & {
+            news: NewsItem[];
+        })[];
+        problems: {
+            wilma: string;
+            message: string;
+        }[];
+    } | {
+        students: ({
+            student: StudentRef;
+        } & {
+            news: NewsItem[];
+        })[];
+        problems?: undefined;
+    }>;
+    newsItem(opts: {
+        id: number;
+        student?: string;
+    }): Promise<{
+        student: StudentRef;
+        news: NewsItem;
+    }>;
+    newsAttachment(opts: {
+        newsId: number;
+        resourceId: string;
+        student?: string;
+    }): Promise<FetchedAttachment & {
+        student: StudentRef;
+    }>;
+}
+export {};