Schulcloud-MCP/src/core/untis-history.ts

import { addDays, daysBetween } from './dates.ts';
import type { UntisClient, UntisLesson } from './untis.ts';

/**
 * The class register, read backwards: what every past lesson actually covered.
 *
 * `untis_lesson_topics` answers this one series at a time, from a period id the
 * caller already has. That is the wrong shape for two of the questions this
 * exists for — "what have we done in Deutsch this term" and "where does the
 * material about X come from" — because neither starts from a period id, and
 * the second needs the text in the search index rather than in a tool call.
 *
 * So this walks a date range and merges the two halves the API keeps apart:
 *
 * - `getTimetable2017` gives the periods, and with them what a teacher wrote on
 *   one (`text.info` is where this school announces its tests), the homework and
 *   any exam.
 * - `getLessonTopic2017` gives the `Unterrichtsinhalt` — but only per *series*,
 *   as "the previous topics of this lesson". One call per series therefore
 *   covers all of its past lessons at once, which is why this asks per series
 *   and not per period: a term is a few dozen calls, not a few hundred.
 *
 * Requests are sequential on purpose. Every WebUntis call carries its own
 * one-time code, and the index is built by a background crawl that nobody is
 * waiting on, so there is nothing to buy by running them in parallel.
 */

/** The longest range one `getTimetable2017` call is asked for. */
const CHUNK_DAYS = 90;

export interface LessonLogEntry {
	periodId: number;
	/** The series id: every Tuesday-second-period German lesson shares it. */
	lessonId: number;
	date: string;
	start: string;
	end: string;
	subject?: string;
	subjectLong?: string;
	teachers: string[];
	/** The class register's "Unterrichtsinhalt" for this period, when the teacher filled it in. */
	topic?: string;
	/** The free-text fields on the period. `info` is where announced tests live. */
	notes: { lesson?: string; substitution?: string; info?: string };
	homework: { text: string; due: string }[];
	exam?: string;
}

export interface LessonLog {
	from: string;
	to: string;
	entries: LessonLogEntry[];
	/** Series whose topics could not be read, so a gap is visible rather than silent. */
	failures: { lessonId: number; reason: string }[];
	/** Periods seen in the range, including the ones that carried nothing. */
	periodsSeen: number;
}

/**
 * Collects the log for `[from, to]`.
 *
 * Only periods that carry something are returned: a lesson with neither a
 * topic, nor a note, nor homework, nor an exam has nothing to say, and
 * indexing it would bury the ones that do under a term of empty rows.
 */
export async function collectLessonLog(
	untis: UntisClient,
	options: { from: string; to: string; subject?: string },
): Promise<LessonLog> {
	const lessons: UntisLesson[] = [];
	for (const [chunkFrom, chunkTo] of chunkRange(options.from, options.to)) {
		const table = await untis.timetable(chunkFrom, chunkTo);
		for (const day of table.days) lessons.push(...day.lessons);
	}

	// A cancelled period taught nothing, and its replacement beside it carries
	// whatever actually happened.
	const held = lessons.filter((lesson) => !lesson.cancelled).filter((lesson) => matchesSubject(lesson, options.subject));

	const topics = new Map<number, string>();
	const failures: { lessonId: number; reason: string }[] = [];
	for (const [lessonId, periodId] of latestPeriodPerSeries(held)) {
		try {
			for (const topic of await untis.lessonTopics(periodId)) topics.set(topic.periodId, topic.text);
		} catch (error) {
			// One series the register refuses must not cost the rest of the term.
			failures.push({ lessonId, reason: error instanceof Error ? error.message : String(error) });
		}
	}

	const entries = held
		.map((lesson): LessonLogEntry => {
			const subject = lesson.subjects[0];
			return {
				periodId: lesson.periodId,
				lessonId: lesson.lessonId,
				date: lesson.date,
				start: lesson.start,
				end: lesson.end,
				...(subject?.name ? { subject: subject.name } : {}),
				...(subject?.longName ? { subjectLong: subject.longName } : {}),
				teachers: lesson.teachers.map((teacher) => teacher.longName || teacher.name),
				...(topics.get(lesson.periodId) ? { topic: topics.get(lesson.periodId) } : {}),
				notes: lesson.notes,
				homework: lesson.homework.map((item) => ({ text: item.text, due: item.due })),
				...(lesson.exam ? { exam: lesson.exam } : {}),
			};
		})
		.filter(hasContent)
		.sort((a, b) => b.date.localeCompare(a.date) || b.start.localeCompare(a.start));

	return { from: options.from, to: options.to, entries, failures, periodsSeen: held.length };
}

/** True when the entry records anything worth keeping. */
export function hasContent(entry: LessonLogEntry): boolean {
	return Boolean(
		entry.topic ||
			entry.notes.lesson ||
			entry.notes.info ||
			entry.notes.substitution ||
			entry.exam ||
			entry.homework.length > 0,
	);
}

/** Everything the entry says, as one string — the body the index gets. */
export function lessonLogText(entry: LessonLogEntry): string {
	return [
		entry.topic,
		entry.notes.info,
		entry.notes.lesson,
		entry.notes.substitution,
		entry.exam ? `Prüfung: ${entry.exam}` : undefined,
		...entry.homework.map((item) => `Hausaufgabe bis ${item.due}: ${item.text}`),
	]
		.filter(Boolean)
		.join('\n');
}

/** `LF07` matches the subject `LF07` and the long name `Lernfeld 7`. */
function matchesSubject(lesson: UntisLesson, subject: string | undefined): boolean {
	if (!subject) return true;
	const wanted = subject.trim().toLowerCase();
	return lesson.subjects.some(
		(entry) =>
			entry.name.toLowerCase().includes(wanted) || (entry.longName ?? '').toLowerCase().includes(wanted),
	);
}

/**
 * One period id per series — the latest one.
 *
 * `getLessonTopic2017` answers with the topics of the lessons *before* the
 * period it is given, so asking about the last lesson of a series reaches the
 * whole of its history and asking about the first reaches none of it.
 */
function latestPeriodPerSeries(lessons: UntisLesson[]): Map<number, number> {
	const latest = new Map<number, { periodId: number; at: string }>();
	for (const lesson of lessons) {
		const at = `${lesson.date} ${lesson.start}`;
		const current = latest.get(lesson.lessonId);
		if (!current || at > current.at) latest.set(lesson.lessonId, { periodId: lesson.periodId, at });
	}
	return new Map([...latest].map(([lessonId, entry]) => [lessonId, entry.periodId]));
}

/** Splits a range into windows the timetable call will accept. */
export function chunkRange(from: string, to: string): [string, string][] {
	const chunks: [string, string][] = [];
	let start = from;
	while (start <= to) {
		const end = daysBetween(start, to) > CHUNK_DAYS ? addDays(start, CHUNK_DAYS) : to;
		chunks.push([start, end]);
		start = addDays(end, 1);
	}
	return chunks;
}