@wilm-ai/wilma-client 1.6.1 → 1.7.0

package/dist/types.d.ts

@@ -18,8 +18,91 @@ export interface Message {
     recipients?: string[] | null;
     /** Message detail: the thread's replies, oldest first. */
     replies?: MessageReply[];
+    /** Message detail: the sender opened the thread for everyone ("avoin keskustelu"), so a reply goes to all recipients. */
+    discussion?: boolean;
+    /** Message detail: Wilma allows answering it (null when Wilma doesn't say). */
+    canReply?: boolean | null;
+    /** Message detail: the time slots and this family's choice, when the message is an event invitation. */
+    invitation?: Invitation | null;
     fetchedAt: Date;
 }
+/** An event invitation (Tapahtumakutsu): a parents' evening, a learning discussion with time slots… */
+export interface Invitation {
+    /** Wilma asks for a sign-up, not just attendance. */
+    mustApply: boolean;
+    slots: InvitationSlot[];
+    /** Wilma offers "En osallistu" (won't attend) for this invitation. */
+    canDecline: boolean;
+    /** The family has said it won't attend ("En osallistu"). */
+    declined: boolean;
+}
+export interface InvitationSlot {
+    /** Wilma's event id, for answering. */
+    id: string;
+    start: Date | null;
+    end: Date | null;
+    /** Sign-up opens / closes. */
+    enrollStart: Date | null;
+    enrollEnd: Date | null;
+    /** The last moment a sign-up can be cancelled. */
+    cancelUntil: Date | null;
+    info: string;
+    subject: string;
+    /** 0 when there's no limit. */
+    maxPeople: number;
+    peopleCount: number;
+    /** You signed up for this slot (Wilma: "selected-cancellable" while it can be cancelled, "selected" after). */
+    selected: boolean;
+    /** Another guardian signed up for this slot, as Wilma names them ("Name (child, class)"). */
+    selectedByOther: string | null;
+    /** Wilma's own word for the slot: "available", "selected-cancellable", "selected", "selected-other", "full", "pending", "expired", or "". */
+    wilmaState: string;
+    /** "En osallistu" covers this slot (CanDismissEvent). */
+    canDecline: boolean;
+    /** "En osallistu" was answered for this slot (IsDismissed). */
+    declined: boolean;
+}
+/**
+ * chosen: your slot (chosen-locked: too late to cancel); chosen-by-other:
+ * another guardian's; taken: the family already has another slot; open: can
+ * sign up now.
+ */
+export type InvitationSlotState = "chosen" | "chosen-locked" | "chosen-by-other" | "taken" | "open" | "full" | "not-yet" | "closed";
+/** Someone a message can go to, as Wilma offers them. */
+export interface MessageRecipient {
+    /** As Wilma shows it, e.g. "Virtanen Sari (VIR)", or "Kaikki" for a group. */
+    name: string;
+    /** The list Wilma puts it in: "Omat opettajat", "Opettajat", "Henkilökunta", "Opiskelija"… */
+    group: string;
+    /** The school, for staff and teachers listed per school. */
+    school: string | null;
+    /** teacher, staff (other personnel), student (the child), guardian (the other guardians), group (several at once). */
+    kind: "teacher" | "staff" | "student" | "guardian" | "group" | "other";
+    /** Wilma's compose page with this recipient filled in, for prepareMessage(). */
+    composePath: string;
+}
+/** The child's class and the people responsible for it, from the front page. */
+export interface StudentDetails {
+    name: string | null;
+    /** E.g. "9A". */
+    className: string | null;
+    /** Class teacher and other supervisors, in Wilma's order. */
+    supervisors: {
+        name: string;
+        role: string;
+        recipient: MessageRecipient | null;
+    }[];
+    /** Groups the front page offers to message at once: all supervisors, all the child's teachers. */
+    messageGroups: MessageRecipient[];
+}
+/** An entry in the invitations list (Tapahtumakutsut). */
+export interface InvitationListing {
+    message: Message;
+    /** Wilma's status for this family: "Applied", "ExpiredReg"…; null when it shows none. */
+    status: string | null;
+    /** The chosen time or the sign-up deadline, in Wilma's words. */
+    extra: string | null;
+}
 export interface MessageReply {
     id: number;
     sentAt: Date;
@@ -65,6 +148,11 @@ export interface StudentInfo {
     studentNumber: string;
     name: string;
     href: string;
+    /**
+     * Whose login this is for the student, as Wilma's account roles say: a guardian's, or the student's own.
+     * Missing when Wilma doesn't say (older Wilmas without the roles API).
+     */
+    role?: "guardian" | "student";
 }
 export interface Municipality {
     nameFi: string;
@@ -126,6 +214,29 @@ export interface ExamGrade {
     info: string | null;
     teacher: string;
     teacherCode: string;
+    /** When a guardian saw the grade in Wilma (YYYY-MM-DD), or null. */
+    seen?: string | null;
+}
+/** A past exam from Wilma's exam list (Kokeet > Menneet), graded or not yet. */
+export interface PastExam {
+    /** YYYY-MM-DD */
+    date: string;
+    name: string;
+    /** The course title, e.g. "Fysiikka". */
+    subject: string;
+    /** The course code, e.g. "FY_91" ("" when Wilma doesn't give one). */
+    subjectCode: string;
+    /** The grade as Wilma shows it ("8+", "9½", "S", "21,5/24"), or null before it's given. */
+    grade: string | null;
+    verbalGrade: string | null;
+    /** The exam's notes (topics, pages), lines kept. */
+    info: string | null;
+    /** The teachers' names, comma-separated. */
+    teacher: string;
+    /** The teachers' codes, comma-separated. */
+    teacherCode: string;
+    /** When a guardian marked the grade seen (YYYY-MM-DD), or null. */
+    seen: string | null;
 }
 export interface HomeworkItem {
     /** YYYY-MM-DD */

package/dist/write.d.ts

@@ -0,0 +1,143 @@
+import type { WilmaClient } from "./client.js";
+import { type WilmaForm } from "./parsers/forms.js";
+import type { Invitation, MessageRecipient } from "./types.js";
+export type { WilmaForm } from "./parsers/forms.js";
+export { FormOutsideWilmaError } from "./parsers/forms.js";
+/** Wilma doesn't offer this here right now (no answer form, absence reports closed…). Nothing was sent. */
+export declare class NotOfferedError extends Error {
+    constructor(message: string);
+}
+/** Wilma turned the form down and said so. Nothing changed. */
+export declare class WriteRefusedError extends Error {
+    constructor(message: string);
+}
+/** The form reached Wilma, but the result didn't show. It may have gone through: check Wilma before sending again. */
+export declare class WriteUnconfirmedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Wilma's absence report form for one child. Seen 2026-10-06 (Helsinki):
+ * `/attendance/report` posts to `/attendance/savereport` with formkey,
+ * ReportDate (a day number Wilma fills in), type (the reason), text, savebtn.
+ */
+export interface AbsenceReportForm {
+    readonly kind: "absence-report";
+    /** The session the form belongs to (WilmaSession.sessionMark); not posted under another. */
+    readonly sessionMark?: number;
+    /** The day the report is for (YYYY-MM-DD). Wilma decides: today until 12:00, the next day after that. */
+    readonly date: string | null;
+    /** Wilma's words for that day, e.g. "Huomenna, 7.10.". */
+    readonly dateLabel: string;
+    /** The reasons this school offers (Helsinki offers one: "Terveydellinen syy"). */
+    readonly reasons: {
+        value: string;
+        label: string;
+    }[];
+    /** The form has a field for details. */
+    readonly acceptsText: boolean;
+    /** Wilma's instructions on the form page, if any. */
+    readonly guidance: string;
+    /** What send posts. */
+    readonly form: WilmaForm;
+    readonly reasonField: string;
+    readonly textField: string | null;
+    /** Notices already on the form page, so a new one after sending can be told apart. */
+    readonly noticesBefore: string[];
+}
+/** Wilma's day numbers count days from 30 December 1899 (46302 = 7 October 2026). */
+export declare function wilmaDayToIso(value: string): string | null;
+export declare function prepareAbsenceReport(client: WilmaClient): Promise<AbsenceReportForm>;
+/** Report the absence (once). Returns Wilma's confirmation. */
+export declare function sendAbsenceReport(client: WilmaClient, prepared: AbsenceReportForm, input: {
+    reason: string;
+    text?: string;
+}): Promise<{
+    notice: string;
+}>;
+/**
+ * Wilma has two kinds of answer, and the message page says which applies
+ * (approach from jmccrosky/wilma-mcp, MIT):
+ *  - discussion: an open discussion ("avoin keskustelu") has a quick-reply
+ *    form posting to `/messages/collatedreply/<id>`; everyone on the thread
+ *    sees the answer;
+ *  - private: an ordinary message links to a compose form with the sender
+ *    and "VS:" subject filled in; the answer goes to the sender alone.
+ */
+export interface ReplyForm {
+    readonly kind: "reply";
+    /** The session the form belongs to (WilmaSession.sessionMark); not posted under another. */
+    readonly sessionMark?: number;
+    readonly messageId: number;
+    readonly mode: "discussion" | "private";
+    /** The subject Wilma filled in for a private answer ("VS: …"); null for a discussion. */
+    readonly subject: string | null;
+    /** Who a private answer goes to, as Wilma's form shows them; empty for a discussion. */
+    readonly recipients: string[];
+    /** What send posts. */
+    readonly form: WilmaForm;
+    readonly bodyField: string;
+}
+export declare function prepareReply(client: WilmaClient, messageId: number): Promise<ReplyForm>;
+/** Send the answer (once). */
+export declare function sendReply(client: WilmaClient, prepared: ReplyForm, text: string): Promise<void>;
+/**
+ * A new message. Wilma's compose page with the recipient filled in
+ * (`/messages/compose?r_teacher=<id>`, or a recipient's link from
+ * messages.recipients() or student.get()) has the fields formkey, wysiwyg
+ * ("ckeditor": the body is HTML), the recipients as r_… fields, Subject,
+ * BodyText, ShowRecipients and CollatedReplies; it's sent with addsavebtn,
+ * never draftbtn, cancelbtn or select_recipients.
+ */
+export interface MessageForm {
+    readonly kind: "message";
+    /** The session the form belongs to (WilmaSession.sessionMark); not posted under another. */
+    readonly sessionMark?: number;
+    /** Who it goes to, as Wilma's form shows them. */
+    readonly recipients: string[];
+    /** What send posts. */
+    readonly form: WilmaForm;
+    readonly subjectField: string;
+    readonly bodyField: string;
+}
+export declare function prepareMessage(client: WilmaClient, to: {
+    teacherId: string | number;
+} | Pick<MessageRecipient, "composePath">): Promise<MessageForm>;
+/** Send the message (once). */
+export declare function sendMessage(client: WilmaClient, prepared: MessageForm, input: {
+    subject: string;
+    text: string;
+}): Promise<void>;
+/**
+ * Sign up for an invitation's time slot, or cancel the sign-up. This is what
+ * Wilma's own page sends (appointments.js): POST `/messages/apply/` with the
+ * page's formkey, apptId (the slot), action, appliedpersons and kortti (the
+ * message), answered with JSON {resultmessage: {message, problem}}. Checks
+ * the slot's state first, like Wilma's page, and reads the invitation back
+ * afterwards. Opening the invitation marks it read, as in Wilma.
+ */
+export declare function answerInvitation(client: WilmaClient, messageId: number, slotId: string, action: "apply" | "cancel", opts?: {
+    persons?: number;
+}): Promise<{
+    notice: string;
+    invitation: Invitation;
+}>;
+/**
+ * Say the family won't attend ("En osallistu"), or take that back (`undo`).
+ * This is what Wilma's own page sends (appointments.js, dismissAppt): POST
+ * `/messages/apply` with the page's formkey, action "dismiss" (or
+ * "canceldismiss") and kortti (the message), no slot. Declining also cancels
+ * a sign-up that can still be cancelled, as Wilma's page warns. Reads the
+ * invitation back afterwards.
+ */
+export declare function declineInvitation(client: WilmaClient, messageId: number, opts?: {
+    undo?: boolean;
+}): Promise<{
+    notice: string;
+    invitation: Invitation;
+}>;
+/**
+ * What goes in the body field. Wilma's message forms say `wysiwyg=ckeditor`:
+ * its editor sends HTML, so plain text becomes paragraphs (blank lines) and
+ * line breaks, with <, > and & escaped. Other forms get the text as is.
+ */
+export declare function editorBody(form: WilmaForm, text: string): string;