@wilm-ai/wilma-client 1.7.1 → 1.9.0

package/dist/client.d.ts

@@ -94,6 +94,11 @@ export declare class WilmaClient {
     };
     news: {
         list: () => Promise<NewsItem[]>;
+        /**
+         * The bulletins, or null when this Wilma doesn't show them to this account: it answers /news with 403 (Helsinki's
+         * does, for a guardian) or 404 while the session is alive. Its other pages read as usual.
+         */
+        listIfShown: () => Promise<NewsItem[] | null>;
         get: (newsId: number) => Promise<NewsItem>;
         fetchResource: (newsId: number, resourceId: string, options?: {
             item?: NewsItem;

package/dist/client.js

@@ -241,6 +241,20 @@ export class WilmaClient {
             }
             return parseNewsListHtml(text);
         },
+        /**
+         * The bulletins, or null when this Wilma doesn't show them to this account: it answers /news with 403 (Helsinki's
+         * does, for a guardian) or 404 while the session is alive. Its other pages read as usual.
+         */
+        listIfShown: async () => {
+            try {
+                return await this.news.list();
+            }
+            catch (err) {
+                if (err instanceof APIError && (err.status === 403 || err.status === 404))
+                    return null;
+                throw err;
+            }
+        },
         get: async (newsId) => {
             const resp = await this.session.get(`/news/${newsId}`);
             const contentType = resp.headers.get("content-type")?.toLowerCase() ?? "";

package/dist/parsers/forms.d.ts

@@ -23,6 +23,12 @@ export interface WilmaForm {
         }[];
     }[];
     textareas: string[];
+    /** The form's checkboxes, ticked or not (`fields` has only the ticked ones, as a browser sends them). */
+    checkboxes?: {
+        name: string;
+        value: string;
+        checked: boolean;
+    }[];
 }
 export declare class FormOutsideWilmaError extends Error {
     constructor();

package/dist/parsers/forms.js

@@ -18,6 +18,7 @@ export function readForm($, form, pageUrl) {
     const buttons = [];
     const selects = [];
     const textareas = [];
+    const checkboxes = [];
     form.find("input, select, textarea, button").each((_, el) => {
         const control = $(el);
         const name = control.attr("name");
@@ -50,14 +51,17 @@ export function readForm($, form, pageUrl) {
             buttons.push({ name, value, label: clean(control.text()) || value });
         }
         else if (type === "checkbox" || type === "radio") {
-            if (control.attr("checked") !== undefined)
+            const checked = control.attr("checked") !== undefined;
+            if (type === "checkbox")
+                checkboxes.push({ name, value: control.attr("value") ?? "on", checked });
+            if (checked)
                 fields.push([name, control.attr("value") ?? "on"]);
         }
         else if (type !== "file" && type !== "reset" && type !== "button") {
             fields.push([name, value]);
         }
     });
-    return { action: wilmaPath(form.attr("action") ?? "", pageUrl), fields, buttons, selects, textareas };
+    return { action: wilmaPath(form.attr("action") ?? "", pageUrl), fields, buttons, selects, textareas, checkboxes };
 }
 /** The form key on a page (Wilma's anti-forgery token), preferring one outside the logout form. */
 export function pageFormkey($) {

package/dist/parsers/recipients.d.ts

@@ -3,6 +3,12 @@ import type { MessageRecipient, StudentDetails } from "../types.js";
 export declare function composePath(href: string | undefined, pageUrl: string): string | null;
 /** What a compose link writes to, from its r_ parameters (a repeated or mixed one: several people). */
 export declare function recipientKind(path: string): MessageRecipient["kind"];
+/**
+ * One compose link to several recipients, made as Wilma's own "to all teachers" links are: every r_… parameter of
+ * theirs, each once, and for more than one person showrecipients=1&collatedreplies=1 (the recipients see who else
+ * got it and each other's replies, which the message form can still untick). The links must be one child's.
+ */
+export declare function composeToAll(paths: string[]): string;
 /** The child's class and supervisors from their front page (`/!<n>/`); empty fields when the panel isn't there. */
 export declare function parseStudentDetailsHtml(html: string, pageUrl: string): StudentDetails;
 /**

package/dist/parsers/recipients.js

@@ -51,6 +51,32 @@ export function recipientKind(path) {
             return "other";
     }
 }
+/**
+ * One compose link to several recipients, made as Wilma's own "to all teachers" links are: every r_… parameter of
+ * theirs, each once, and for more than one person showrecipients=1&collatedreplies=1 (the recipients see who else
+ * got it and each other's replies, which the message form can still untick). The links must be one child's.
+ */
+export function composeToAll(paths) {
+    if (!paths.length)
+        throw new TypeError("No recipients");
+    if (paths.length === 1)
+        return paths[0];
+    const urls = paths.map((p) => new URL(p, "https://wilma.invalid"));
+    if (urls.some((u) => u.pathname !== urls[0].pathname))
+        throw new TypeError("The recipients are another child's");
+    const params = [];
+    for (const u of urls) {
+        for (const [k, v] of u.searchParams)
+            if (k.startsWith("r_") && !params.some(([a, b]) => a === k && b === v))
+                params.push([k, v]);
+    }
+    const out = new URLSearchParams(params);
+    if (params.length > 1 || recipientKind(`?${out}`) === "group") {
+        out.set("showrecipients", "1");
+        out.set("collatedreplies", "1");
+    }
+    return `${urls[0].pathname}?${out}`;
+}
 /** The child's class and supervisors from their front page (`/!<n>/`); empty fields when the panel isn't there. */
 export function parseStudentDetailsHtml(html, pageUrl) {
     const $ = cheerio.load(html);

package/dist/write.d.ts

@@ -1,5 +1,6 @@
 import type { WilmaClient } from "./client.js";
 import { type WilmaForm } from "./parsers/forms.js";
+export { composeToAll } from "./parsers/recipients.js";
 import type { Invitation, MessageRecipient } from "./types.js";
 export type { WilmaForm } from "./parsers/forms.js";
 export { FormOutsideWilmaError } from "./parsers/forms.js";
@@ -98,14 +99,23 @@ export interface MessageForm {
     readonly form: WilmaForm;
     readonly subjectField: string;
     readonly bodyField: string;
+    /**
+     * Whether the recipients see each other's replies (Wilma's CollatedReplies box, which makes the thread an open
+     * discussion), as Wilma's form has it; null when the form has no such box.
+     */
+    readonly collatedReplies?: boolean | null;
 }
 export declare function prepareMessage(client: WilmaClient, to: {
     teacherId: string | number;
 } | Pick<MessageRecipient, "composePath">): Promise<MessageForm>;
-/** Send the message (once). */
+/**
+ * Send the message (once). `collatedReplies` ticks or clears Wilma's "recipients see each other's replies" box
+ * when the form has one; left out, the box stays as Wilma's form has it.
+ */
 export declare function sendMessage(client: WilmaClient, prepared: MessageForm, input: {
     subject: string;
     text: string;
+    collatedReplies?: boolean;
 }): Promise<void>;
 /**
  * Sign up for an invitation's time slot, or cancel the sign-up. This is what

package/dist/write.js

@@ -26,6 +26,7 @@ import { sessionOf } from "./internal.js";
 import { pageErrors, pageFormkey, pageNotices, readForm, setField, wilmaPath } from "./parsers/forms.js";
 import { slotState } from "./parsers/invitations.js";
 import { composePath } from "./parsers/recipients.js";
+export { composeToAll } from "./parsers/recipients.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 class NotOfferedError extends Error {
@@ -166,6 +167,7 @@ export async function sendReply(client, prepared, text) {
         return;
     throw new WriteUnconfirmedError("Wilma didn't show the answer as sent. Check the thread in Wilma before answering again.");
 }
+const COLLATED = "CollatedReplies";
 export async function prepareMessage(client, to) {
     const session = sessionFor(client);
     let path;
@@ -185,9 +187,21 @@ export async function prepareMessage(client, to) {
     const compose = await composeForm(session, path);
     if (!compose.subjectField)
         throw new NotOfferedError("Wilma's message form has no subject field.");
-    return { kind: "message", sessionMark: session.sessionMark, recipients: compose.recipients, form: compose.form, subjectField: compose.subjectField, bodyField: compose.bodyField };
+    const collated = compose.form.checkboxes?.find((c) => c.name === COLLATED);
+    return {
+        kind: "message",
+        sessionMark: session.sessionMark,
+        recipients: compose.recipients,
+        form: compose.form,
+        subjectField: compose.subjectField,
+        bodyField: compose.bodyField,
+        collatedReplies: collated ? collated.checked : null,
+    };
 }
-/** Send the message (once). */
+/**
+ * Send the message (once). `collatedReplies` ticks or clears Wilma's "recipients see each other's replies" box
+ * when the form has one; left out, the box stays as Wilma's form has it.
+ */
 export async function sendMessage(client, prepared, input) {
     const session = sessionFor(client);
     if (prepared.kind !== "message")
@@ -197,7 +211,12 @@ export async function sendMessage(client, prepared, input) {
     if (!input.text.trim())
         throw new TypeError("The message is empty");
     const before = await sentState(client, null);
-    let fields = setField(prepared.form.fields, prepared.subjectField, input.subject);
+    let fields = prepared.form.fields;
+    const box = prepared.form.checkboxes?.find((c) => c.name === COLLATED);
+    if (box && input.collatedReplies !== undefined) {
+        fields = input.collatedReplies ? setField(fields, box.name, box.value) : fields.filter(([name]) => name !== box.name);
+    }
+    fields = setField(fields, prepared.subjectField, input.subject);
     fields = withButton(setField(fields, prepared.bodyField, editorBody(prepared.form, input.text)), prepared.form, "addsavebtn");
     sameSession(session, prepared);
     const answer = await read(await session.submit(prepared.form.action, fields), "The message");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wilm-ai/wilma-client",
-  "version": "1.7.1",
+  "version": "1.9.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": {