chuvsu-js 4.2.0 → 5.0.0

package/dist/tt/client.js

@@ -1,29 +1,60 @@
-import { HttpClient } from "../common/http.js";
+import { HttpClient, } from "../common/http.js";
 import { HybridCache } from "../common/cache.js";
-import { AuthError, ParseError } from "../common/types.js";
-import { parseAcademicYearFromPage, parseAudienceButtons, parseAudienceFullSchedule, parseAudienceInfo, parseAudienceName, parseGroupButtons, parseFacultyButtons, parseTeacherButtons, parseFullSchedule, parseTeacherFullSchedule, parseTeacherInfo, parsePeriodFromPage, parseWebinars, } from "./parse/index.js";
-import { Schedule } from "./schedule.js";
+import { AcademicPeriod, AuthError, EducationLevel, ParseError, } from "../common/types.js";
+import { parseAcademicYearFromPage, parseRoomButtons, parseRoomSchedule, parseRoomInfo, parseRoomName, parseGroupButtons, parseGroupName, parseFacultyButtons, parseTeacherButtons, parseGroupSchedule, parseTeacherSchedule, parseTeacherInfo, parsePeriodFromPage, parseWebinars, } from "./parse/index.js";
+import { Schedule } from "./domain/schedule.js";
+import { TimetableRepository } from "./domain/repository.js";
+import { createScheduleSourceSnapshot } from "./observations.js";
 const BASE = "https://tt.chuvsu.ru";
 const AUTH_URL = `${BASE}/auth`;
 const TIMETABLE_CONTEXT_TTL_MS = 15 * 60 * 1000;
 const ALL_PERIODS = [
-    1 /* Period.FallSemester */,
-    2 /* Period.WinterSession */,
-    3 /* Period.SpringSemester */,
-    4 /* Period.SummerSession */,
+    AcademicPeriod.FallSemester,
+    AcademicPeriod.WinterSession,
+    AcademicPeriod.SpringSemester,
+    AcademicPeriod.SummerSession,
 ];
+function requirePositiveId(value, label) {
+    if (!Number.isInteger(value) || value == null || value < 1) {
+        throw new RangeError(`${label} must be a positive integer`);
+    }
+    return value;
+}
+function normalizeSearchQuery(value, label, minimumLength = 1) {
+    const normalized = value.trim();
+    if (normalized.length < minimumLength) {
+        throw new RangeError(`${label} must contain at least ${minimumLength} characters`);
+    }
+    return normalized;
+}
+function normalizePeriods(periods) {
+    const values = [...(periods ?? ALL_PERIODS)];
+    if (values.length === 0)
+        throw new RangeError("At least one period is required");
+    const unique = new Set();
+    for (const period of values) {
+        if (!ALL_PERIODS.includes(period)) {
+            throw new RangeError(`Invalid academic period: ${period}`);
+        }
+        if (unique.has(period)) {
+            throw new RangeError(`Duplicate academic period: ${period}`);
+        }
+        unique.add(period);
+    }
+    return values;
+}
 function makeUniformCacheConfig(ttl) {
     return {
         schedule: ttl,
         faculties: ttl,
         groups: ttl,
-        audiences: ttl,
-        audienceNames: ttl,
+        rooms: ttl,
+        roomNames: ttl,
         teachers: ttl,
         teacherInfo: ttl,
         teacherPhotos: ttl,
-        audienceInfo: ttl,
-        audienceImages: ttl,
+        roomInfo: ttl,
+        roomImages: ttl,
         webinars: ttl,
     };
 }
@@ -33,16 +64,26 @@ function formatDate(date) {
     const day = String(date.getDate()).padStart(2, "0");
     return `${year}-${month}-${day}`;
 }
-export class TtClient {
+export class TimetableClient {
     http = new HttpClient();
-    educationType;
+    educationLevel;
     cache;
     blobAdapter = undefined;
+    _repository;
+    repositoryAdapter;
+    repositoryReady = null;
+    repositoryMutation = Promise.resolve();
     loginMode = null;
     timetableContext = null;
     constructor(opts) {
-        this.educationType = opts?.educationType ?? 1 /* EducationType.HigherEducation */;
+        this.educationLevel = opts?.educationLevel ?? EducationLevel.HigherEducation;
+        if (this.educationLevel !== EducationLevel.HigherEducation &&
+            this.educationLevel !== EducationLevel.VocationalEducation) {
+            throw new RangeError("Invalid education level");
+        }
         this.blobAdapter = opts?.blobAdapter;
+        this._repository = opts?.repository ?? new TimetableRepository();
+        this.repositoryAdapter = opts?.repositoryAdapter;
         if (opts?.cache == null) {
             this.cache = null;
         }
@@ -54,7 +95,62 @@ export class TtClient {
         }
     }
     get pertt() {
-        return String(this.educationType);
+        return String(this.educationLevel);
+    }
+    get repository() {
+        return this._repository;
+    }
+    async ensureRepository() {
+        if (!this.repositoryAdapter)
+            return;
+        if (!this.repositoryReady) {
+            this.repositoryReady = (async () => {
+                const snapshot = await this.repositoryAdapter.load();
+                if (snapshot && this._repository.revision === 0) {
+                    this._repository.replaceSnapshot(snapshot);
+                }
+            })();
+        }
+        await this.repositoryReady;
+    }
+    async mutateRepository(mutate) {
+        const operation = this.repositoryMutation.then(() => this.performRepositoryMutation(mutate));
+        this.repositoryMutation = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+    async performRepositoryMutation(mutate) {
+        await this.ensureRepository();
+        for (let attempt = 0; attempt < 4; attempt++) {
+            const expectedRevision = this._repository.revision;
+            const result = mutate(this._repository);
+            if (!this.repositoryAdapter)
+                return result;
+            if (await this.repositoryAdapter.compareAndSet(expectedRevision, this._repository.export())) {
+                return result;
+            }
+            const latest = await this.repositoryAdapter.load();
+            this._repository.replaceSnapshot(latest ?? {
+                schemaVersion: 5,
+                revision: 0,
+                directory: { groups: [], teachers: [], rooms: [] },
+                sources: [],
+                links: [],
+            });
+        }
+        throw new Error("Timetable repository update conflict");
+    }
+    async exportRepository() {
+        await this.ensureRepository();
+        return this._repository.export();
+    }
+    async rememberGroups(values) {
+        await this.mutateRepository((repository) => repository.rememberGroups(values));
+    }
+    async rememberTeachers(values) {
+        await this.mutateRepository((repository) => repository.rememberTeachers(values));
+    }
+    async rememberRooms(values) {
+        await this.mutateRepository((repository) => repository.rememberRooms(values));
     }
     // --- Cache ---
     async clearCache(category) {
@@ -93,6 +189,11 @@ export class TtClient {
     isSessionExpired(body) {
         return body.includes('name="wname"');
     }
+    isBinarySessionExpired(response) {
+        const prefix = response.body.subarray(0, 8_192).toString("utf8");
+        return this.isSessionExpired(prefix) ||
+            response.contentType?.toLowerCase().includes("text/html") === true;
+    }
     async relogin() {
         if (!this.loginMode)
             return;
@@ -104,21 +205,44 @@ export class TtClient {
         }
     }
     async authGet(url) {
-        const res = await this.http.get(url);
+        let res = await this.http.get(url);
         if (this.loginMode && this.isSessionExpired(res.body)) {
             await this.relogin();
-            return this.http.get(url);
+            res = await this.http.get(url);
+        }
+        if (this.isSessionExpired(res.body)) {
+            throw new AuthError("TT request returned an authentication page");
+        }
+        if (res.status < 200 || res.status >= 300) {
+            throw new Error(`TT request failed with HTTP ${res.status}: ${url}`);
         }
         return res;
     }
     async authGetBuffer(url) {
-        return this.http.getBuffer(url);
+        let res = await this.http.getBufferResponse(url);
+        if (this.loginMode && this.isBinarySessionExpired(res)) {
+            await this.relogin();
+            res = await this.http.getBufferResponse(url);
+        }
+        if (res.status < 200 || res.status >= 300) {
+            throw new Error(`TT request failed with HTTP ${res.status}: ${url}`);
+        }
+        if (this.isBinarySessionExpired(res)) {
+            throw new AuthError("TT binary request returned an authentication page");
+        }
+        return res.body;
     }
     async authPost(url, data) {
-        const res = await this.http.post(url, data);
+        let res = await this.http.post(url, data);
         if (this.loginMode && this.isSessionExpired(res.body)) {
             await this.relogin();
-            return this.http.post(url, data);
+            res = await this.http.post(url, data);
+        }
+        if (this.isSessionExpired(res.body)) {
+            throw new AuthError("TT request returned an authentication page");
+        }
+        if (res.status < 200 || res.status >= 300) {
+            throw new Error(`TT request failed with HTTP ${res.status}: ${url}`);
         }
         return res;
     }
@@ -146,42 +270,118 @@ export class TtClient {
         return context;
     }
     // --- Schedule ---
-    async fetchSchedule(groupId, period, academicYearStartYear) {
-        const cacheKey = `${groupId}:${period}:${academicYearStartYear}-${academicYearStartYear + 1}`;
+    async fetchGroupSchedule(groupId, period, academicYearStartYear) {
+        const cacheKey = `group:${groupId}:${period}:${academicYearStartYear}-${academicYearStartYear + 1}`;
         const cached = await this.cache?.get("schedule", cacheKey);
-        if (cached)
-            return cached;
+        if (cached) {
+            const page = cached;
+            await this.rememberGroups([{ id: groupId, name: page.ownerName }]);
+            return page.days;
+        }
         const url = `${BASE}/index/grouptt/gr/${groupId}`;
         const { body } = await this.authPost(url, { htype: String(period) });
-        const days = parseFullSchedule(body, this.educationType);
-        await this.cache?.set("schedule", cacheKey, days);
+        const ownerName = this.validateSchedulePage({ type: "group", group: { id: groupId, name: "" } }, body, academicYearStartYear);
+        const days = parseGroupSchedule(body);
+        await this.rememberGroups([{ id: groupId, name: ownerName }]);
+        await this.cache?.set("schedule", cacheKey, { days, ownerName });
         return days;
     }
-    /**
-     * Get schedule for all periods. The returned Schedule automatically
-     * routes queries to the correct period based on the date.
-     */
-    async getSchedule(groupId) {
-        const schedules = new Map();
-        const context = await this.getTimetableContext(`${BASE}/index/grouptt/gr/${groupId}`);
-        const results = await Promise.all(ALL_PERIODS.map(async (period) => {
-            const days = await this.fetchSchedule(groupId, period, context.academicYearStartYear);
-            return { period, days };
-        }));
-        for (const { period, days } of results) {
-            schedules.set(period, days);
-        }
-        return new Schedule(groupId, schedules, context.period, this.educationType, undefined, undefined, undefined, context.academicYearStartYear);
+    validateSchedulePage(owner, html, academicYearStartYear) {
+        const pageYear = parseAcademicYearFromPage(html);
+        if (pageYear !== academicYearStartYear) {
+            throw new ParseError("TT schedule response has an unexpected academic year");
+        }
+        const ownerName = owner.type === "group"
+            ? parseGroupName(html)
+            : owner.type === "teacher"
+                ? parseTeacherInfo(html)?.name ?? null
+                : parseRoomName(html);
+        if (!ownerName) {
+            throw new ParseError(`TT ${owner.type} schedule response has no owner name`);
+        }
+        return ownerName;
+    }
+    ownerUrl(owner) {
+        if (owner.type === "group") {
+            return `${BASE}/index/grouptt/gr/${requirePositiveId(owner.group.id, "Group ID")}`;
+        }
+        if (owner.type === "teacher") {
+            return `${BASE}/index/techtt/tech/${requirePositiveId(owner.teacher.id, "Teacher ID")}`;
+        }
+        return `${BASE}/index/audtt/aud/${requirePositiveId(owner.room.id, "Room ID")}`;
+    }
+    sourceKey(owner, period, academicYearStartYear) {
+        const entity = owner.type === "group"
+            ? owner.group
+            : owner.type === "teacher"
+                ? owner.teacher
+                : owner.room;
+        return `${owner.type}:${entity.id}:${period}:${academicYearStartYear}`;
+    }
+    resolveOwner(owner) {
+        if (owner.type === "group") {
+            return {
+                type: "group",
+                group: this._repository.directory.resolveGroup(owner.group),
+            };
+        }
+        if (owner.type === "teacher") {
+            return {
+                type: "teacher",
+                teacher: this._repository.directory.resolveTeacher(owner.teacher),
+            };
+        }
+        return {
+            type: "room",
+            room: this._repository.directory.resolveRoom(owner.room),
+        };
     }
-    /**
-     * Get schedule for a specific period only.
-     */
-    async getScheduleForPeriod(opts) {
-        const context = await this.getTimetableContext(`${BASE}/index/grouptt/gr/${opts.groupId}`);
-        const days = await this.fetchSchedule(opts.groupId, opts.period, context.academicYearStartYear);
-        const schedules = new Map();
-        schedules.set(opts.period, days);
-        return new Schedule(opts.groupId, schedules, opts.period, this.educationType, undefined, undefined, undefined, context.academicYearStartYear);
+    async fetchOwnerSchedule(owner, period, academicYearStartYear) {
+        if (owner.type === "group") {
+            return this.fetchGroupSchedule(owner.group.id, period, academicYearStartYear);
+        }
+        if (owner.type === "teacher") {
+            return this.fetchTeacherSchedule(owner.teacher.id, period, academicYearStartYear);
+        }
+        return this.fetchRoomSchedule(owner.room.id, period, academicYearStartYear);
+    }
+    async getSchedule(owner, options) {
+        const ownerUrl = this.ownerUrl(owner);
+        const periods = normalizePeriods(options?.periods);
+        await this.ensureRepository();
+        if (owner.type === "group" && owner.group.name.trim()) {
+            await this.rememberGroups([owner.group]);
+        }
+        if (owner.type === "teacher" && owner.teacher.name.trim()) {
+            await this.rememberTeachers([owner.teacher]);
+        }
+        if (owner.type === "room" && owner.room.name.trim()) {
+            await this.rememberRooms([owner.room]);
+        }
+        const resolvedOwner = this.resolveOwner(owner);
+        const context = await this.getTimetableContext(ownerUrl);
+        const results = await Promise.all(periods.map(async (period) => ({
+            period,
+            days: await this.fetchOwnerSchedule(resolvedOwner, period, context.academicYearStartYear),
+        })));
+        for (const result of results) {
+            const currentOwner = this.resolveOwner(resolvedOwner);
+            const snapshot = createScheduleSourceSnapshot({
+                sourceKey: this.sourceKey(currentOwner, result.period, context.academicYearStartYear),
+                owner: currentOwner,
+                academicYearStartYear: context.academicYearStartYear,
+                period: result.period,
+                days: result.days,
+            });
+            await this.mutateRepository((repository) => repository.ingest(snapshot));
+        }
+        return new Schedule(this._repository, this.resolveOwner(resolvedOwner), context.academicYearStartYear, { period: periods.length === 1 ? periods[0] : context.period });
+    }
+    async getGroupSchedule(groupId, options) {
+        return this.getSchedule({
+            type: "group",
+            group: this._repository.directory.resolveGroup({ id: groupId, name: "" }),
+        }, options);
     }
     async getWebinars(opts) {
         const date = opts?.date ?? new Date();
@@ -230,51 +430,66 @@ export class TtClient {
         await this.cache?.set("faculties", "all", data);
         return data;
     }
-    async getGroupsForFaculty(opts) {
-        const cacheKey = String(opts.facultyId);
+    async getFacultyGroups(facultyId) {
+        requirePositiveId(facultyId, "Faculty ID");
+        const cacheKey = String(facultyId);
         const cached = await this.cache?.get("groups", cacheKey);
-        if (cached)
-            return cached;
+        if (cached) {
+            const data = cached;
+            await this.rememberGroups(data);
+            return data;
+        }
         const { body } = await this.authPost(`${BASE}/`, {
-            hfac: String(opts.facultyId),
+            hfac: String(facultyId),
             pertt: this.pertt,
         });
         const data = parseGroupButtons(body);
         await this.cache?.set("groups", cacheKey, data);
+        await this.rememberGroups(data);
         return data;
     }
-    async searchGroup(opts) {
-        const cacheKey = `search:${opts.name}:${this.pertt}`;
+    async searchGroups(name) {
+        name = normalizeSearchQuery(name, "Group search query");
+        const cacheKey = `search:${name}:${this.pertt}`;
         const cached = await this.cache?.get("groups", cacheKey);
-        if (cached)
-            return cached;
+        if (cached) {
+            const data = cached;
+            await this.rememberGroups(data);
+            return data;
+        }
         const { body } = await this.authPost(`${BASE}/`, {
-            grname: opts.name,
+            grname: name,
             findgr: "найти",
             hfac: "0",
             pertt: this.pertt,
         });
         const data = parseGroupButtons(body);
         await this.cache?.set("groups", cacheKey, data);
+        await this.rememberGroups(data);
         return data;
     }
     /**
      * Search audiences by name (substring match). The server requires at
      * least 3 characters in the query.
      */
-    async searchAudience(opts) {
-        const cacheKey = `search:${opts.name}:${this.pertt}`;
-        const cached = await this.cache?.get("audiences", cacheKey);
-        if (cached)
-            return cached;
+    async searchRooms(name) {
+        name = normalizeSearchQuery(name, "Room search query", 3);
+        const cacheKey = `search:${name}:${this.pertt}`;
+        const cached = await this.cache?.get("rooms", cacheKey);
+        if (cached) {
+            const data = cached;
+            await this.rememberRooms(data);
+            return data;
+        }
         const { body } = await this.authPost(`${BASE}/`, {
-            audname: opts.name,
+            audname: name,
             findaud: "найти",
             hfac: "0",
             pertt: this.pertt,
         });
-        const data = parseAudienceButtons(body);
-        await this.cache?.set("audiences", cacheKey, data);
+        const data = parseRoomButtons(body);
+        await this.cache?.set("rooms", cacheKey, data);
+        await this.rememberRooms(data);
         return data;
     }
     /**
@@ -285,101 +500,157 @@ export class TtClient {
      * 3-character wildcard `%%%` matches every audience at once and returns
      * the full list of (id, name) pairs.
      */
-    async getAudiences() {
+    async getRooms() {
         const cacheKey = `all:${this.pertt}`;
-        const cached = await this.cache?.get("audiences", cacheKey);
-        if (cached)
-            return cached;
+        const cached = await this.cache?.get("rooms", cacheKey);
+        if (cached) {
+            const data = cached;
+            await this.rememberRooms(data);
+            return data;
+        }
         const { body } = await this.authPost(`${BASE}/`, {
             audname: "%%%",
             findaud: "найти",
             hfac: "0",
             pertt: this.pertt,
         });
-        const data = parseAudienceButtons(body);
-        await this.cache?.set("audiences", cacheKey, data);
+        const data = parseRoomButtons(body);
+        await this.cache?.set("rooms", cacheKey, data);
+        await this.rememberRooms(data);
         return data;
     }
+    async resolveGroup(value, options) {
+        await this.ensureRepository();
+        const ref = typeof value === "string" ? { name: value } : value;
+        let resolved = this._repository.directory.resolveGroup(ref);
+        if (resolved.id == null && options?.strategy === "search") {
+            await this.searchGroups(ref.name);
+            resolved = this._repository.directory.resolveGroup(ref);
+        }
+        return resolved;
+    }
+    async resolveTeacher(value, options) {
+        await this.ensureRepository();
+        const ref = typeof value === "string" ? { name: value } : value;
+        let resolved = this._repository.directory.resolveTeacher(ref);
+        if (resolved.id == null && options?.strategy === "search") {
+            await this.searchTeachers(ref.name);
+            resolved = this._repository.directory.resolveTeacher(ref);
+        }
+        return resolved;
+    }
+    async resolveRoom(value, options) {
+        await this.ensureRepository();
+        const ref = typeof value === "string" ? { name: value } : value;
+        let resolved = this._repository.directory.resolveRoom(ref);
+        if (resolved.id == null && options?.strategy === "search") {
+            await this.searchRooms(ref.name.length >= 3 ? ref.name : "%%%");
+            resolved = this._repository.directory.resolveRoom(ref);
+        }
+        return resolved;
+    }
+    async preloadDirectory(options) {
+        const requests = [];
+        if (options.teachers)
+            requests.push(this.getTeachers());
+        if (options.rooms)
+            requests.push(this.getRooms());
+        for (const facultyId of options.facultyIds ?? []) {
+            requests.push(this.getFacultyGroups(facultyId));
+        }
+        await Promise.all(requests);
+    }
     /**
      * Resolve an audience id from its exact name by searching and
      * selecting the button whose `value` equals the given name.
      */
-    async findAudienceByName(opts) {
-        const q = opts.name.length >= 3 ? opts.name : "%%%";
-        const list = await this.searchAudience({ name: q });
-        return list.find((a) => a.name === opts.name) ?? null;
+    async findRoomByName(name) {
+        name = normalizeSearchQuery(name, "Room name");
+        const query = name.length >= 3 ? name : "%%%";
+        const list = await this.searchRooms(query);
+        return list.find((room) => room.name === name) ?? null;
     }
     /** Fetch the audience's display name from its schedule page. */
-    async getAudienceName(audienceId) {
-        const cacheKey = String(audienceId);
-        const cached = await this.cache?.get("audienceNames", cacheKey);
-        if (cached !== null && cached !== undefined)
-            return cached;
-        const cachedInfo = await this.cache?.get("audienceInfo", cacheKey);
-        if (cachedInfo) {
-            return cachedInfo.name ?? null;
+    async getRoomName(roomId) {
+        requirePositiveId(roomId, "Room ID");
+        const cacheKey = String(roomId);
+        const cached = await this.cache?.get("roomNames", cacheKey);
+        if (cached !== null && cached !== undefined) {
+            const name = cached;
+            if (name)
+                await this.rememberRooms([{ id: roomId, name }]);
+            return name;
         }
-        const { body } = await this.authGet(`${BASE}/index/audtt/aud/${audienceId}`);
-        const name = parseAudienceName(body);
-        const info = parseAudienceInfo(body);
-        await this.cache?.set("audienceNames", cacheKey, name);
+        const cachedInfo = await this.cache?.get("roomInfo", cacheKey);
+        if (cachedInfo) {
+            const name = cachedInfo.name ?? null;
+            if (name)
+                await this.rememberRooms([{ id: roomId, name }]);
+            return name;
+        }
+        const { body } = await this.authGet(`${BASE}/index/audtt/aud/${roomId}`);
+        const name = parseRoomName(body);
+        const info = parseRoomInfo(body);
+        await this.cache?.set("roomNames", cacheKey, name);
         if (info)
-            await this.cache?.set("audienceInfo", cacheKey, info);
+            await this.cache?.set("roomInfo", cacheKey, info);
+        if (name)
+            await this.rememberRooms([{ id: roomId, name }]);
         return name;
     }
     /**
      * Fetch detailed info about an audience (building, floor, usage,
      * image URLs for the audience photo, building photo and floor plan).
      */
-    async getAudienceInfo(audienceId) {
-        const cached = await this.cache?.get("audienceInfo", String(audienceId));
-        if (cached)
-            return cached;
-        const { body } = await this.authGet(`${BASE}/index/audtt/aud/${audienceId}`);
-        const info = parseAudienceInfo(body);
+    async getRoomInfo(roomId) {
+        requirePositiveId(roomId, "Room ID");
+        const cached = await this.cache?.get("roomInfo", String(roomId));
+        if (cached) {
+            const info = cached;
+            await this.rememberRooms([{ id: roomId, name: info.name }]);
+            return info;
+        }
+        const { body } = await this.authGet(`${BASE}/index/audtt/aud/${roomId}`);
+        const info = parseRoomInfo(body);
         if (info)
-            await this.cache?.set("audienceInfo", String(audienceId), info);
+            await this.cache?.set("roomInfo", String(roomId), info);
+        if (info)
+            await this.rememberRooms([{ id: roomId, name: info.name }]);
         return info;
     }
-    async fetchAudienceSchedule(audienceId, period, academicYearStartYear) {
-        const cacheKey = `audience:${audienceId}:${period}:${academicYearStartYear}-${academicYearStartYear + 1}`;
+    async fetchRoomSchedule(roomId, period, academicYearStartYear) {
+        const cacheKey = `room:${roomId}:${period}:${academicYearStartYear}-${academicYearStartYear + 1}`;
         const cached = await this.cache?.get("schedule", cacheKey);
-        if (cached)
-            return cached;
-        const url = `${BASE}/index/audtt/aud/${audienceId}`;
+        if (cached) {
+            const page = cached;
+            await this.rememberRooms([{ id: roomId, name: page.ownerName }]);
+            return page.days;
+        }
+        const url = `${BASE}/index/audtt/aud/${roomId}`;
         const { body } = await this.authPost(url, { htype: String(period) });
-        const days = parseAudienceFullSchedule(body);
-        await this.cache?.set("schedule", cacheKey, days);
+        const ownerName = this.validateSchedulePage({ type: "room", room: { id: roomId, name: "" } }, body, academicYearStartYear);
+        const days = parseRoomSchedule(body);
+        await this.rememberRooms([{ id: roomId, name: ownerName }]);
+        await this.cache?.set("schedule", cacheKey, { days, ownerName });
         // Cache audience info from the same page to avoid an extra request.
-        if (!(await this.cache?.get("audienceInfo", String(audienceId)))) {
-            const info = parseAudienceInfo(body);
+        if (!(await this.cache?.get("roomInfo", String(roomId)))) {
+            const info = parseRoomInfo(body);
             if (info)
-                await this.cache?.set("audienceInfo", String(audienceId), info);
+                await this.cache?.set("roomInfo", String(roomId), info);
+            if (info)
+                await this.rememberRooms([{ id: roomId, name: info.name }]);
         }
         return days;
     }
-    async getAudienceSchedule(audienceId) {
-        const schedules = new Map();
-        const context = await this.getTimetableContext(`${BASE}/index/audtt/aud/${audienceId}`);
-        const results = await Promise.all(ALL_PERIODS.map(async (period) => {
-            const days = await this.fetchAudienceSchedule(audienceId, period, context.academicYearStartYear);
-            return { period, days };
-        }));
-        for (const { period, days } of results) {
-            schedules.set(period, days);
-        }
-        return new Schedule(audienceId, schedules, context.period, this.educationType, undefined, undefined, undefined, context.academicYearStartYear);
-    }
-    async getAudienceScheduleForPeriod(opts) {
-        const context = await this.getTimetableContext(`${BASE}/index/audtt/aud/${opts.audienceId}`);
-        const days = await this.fetchAudienceSchedule(opts.audienceId, opts.period, context.academicYearStartYear);
-        const schedules = new Map();
-        schedules.set(opts.period, days);
-        return new Schedule(opts.audienceId, schedules, opts.period, this.educationType, undefined, undefined, undefined, context.academicYearStartYear);
-    }
-    async getCachedAudienceImage(cacheKey, fetchUrl) {
-        const cached = this.cache?.getLocal("audienceImages", cacheKey) ??
-            await this.cache?.get("audienceImages", cacheKey);
+    async getRoomSchedule(roomId, options) {
+        return this.getSchedule({
+            type: "room",
+            room: this._repository.directory.resolveRoom({ id: roomId, name: "" }),
+        }, options);
+    }
+    async getCachedRoomImage(cacheKey, fetchUrl) {
+        const cached = this.cache?.getLocal("roomImages", cacheKey) ??
+            await this.cache?.get("roomImages", cacheKey);
         if (cached !== null && cached !== undefined) {
             const entry = cached;
             if (entry.data !== undefined) {
@@ -388,7 +659,7 @@ export class TtClient {
             if (entry.blobKey && this.blobAdapter) {
                 const buf = await this.blobAdapter.get(entry.blobKey);
                 if (buf) {
-                    this.cache?.setLocal("audienceImages", cacheKey, {
+                    this.cache?.setLocal("roomImages", cacheKey, {
                         data: buf.toString("base64"),
                     });
                     return buf;
@@ -397,169 +668,149 @@ export class TtClient {
         }
         const url = await fetchUrl();
         if (!url) {
-            await this.cache?.set("audienceImages", cacheKey, { data: null });
+            await this.cache?.set("roomImages", cacheKey, { data: null });
             return null;
         }
         const buf = await this.authGetBuffer(`${BASE}${url}`);
         if (buf.length === 0) {
-            await this.cache?.set("audienceImages", cacheKey, { data: null });
+            await this.cache?.set("roomImages", cacheKey, { data: null });
             return null;
         }
         if (this.blobAdapter) {
-            const blobKey = `tt/audience-images/${cacheKey}`;
-            this.cache?.setLocal("audienceImages", cacheKey, {
+            const blobKey = `tt/room-images/${cacheKey}`;
+            this.cache?.setLocal("roomImages", cacheKey, {
                 data: buf.toString("base64"),
             });
             await this.blobAdapter.put(blobKey, buf, {
-                ttl: this.cache?.ttl("audienceImages"),
+                ttl: this.cache?.ttl("roomImages"),
             });
-            await this.cache?.setExternal("audienceImages", cacheKey, { blobKey });
+            await this.cache?.setExternal("roomImages", cacheKey, { blobKey });
         }
         else {
-            await this.cache?.set("audienceImages", cacheKey, {
+            await this.cache?.set("roomImages", cacheKey, {
                 data: buf.toString("base64"),
             });
         }
         return buf;
     }
     /** Get the audience photo (audimage). Returns null if missing. */
-    async getAudienceImage(audienceId) {
-        return this.getCachedAudienceImage(`aud:${audienceId}`, async () => (await this.getAudienceInfo(audienceId))?.audImageUrl);
+    async getRoomImage(roomId) {
+        requirePositiveId(roomId, "Room ID");
+        return this.getCachedRoomImage(`room:${roomId}`, async () => (await this.getRoomInfo(roomId))?.audImageUrl);
     }
     /** Get the building exterior image (blockimage). Returns null if missing. */
-    async getAudienceBlockImage(audienceId) {
-        return this.getCachedAudienceImage(`block:${audienceId}`, async () => (await this.getAudienceInfo(audienceId))?.blockImageUrl);
+    async getRoomBuildingImage(roomId) {
+        requirePositiveId(roomId, "Room ID");
+        return this.getCachedRoomImage(`block:${roomId}`, async () => (await this.getRoomInfo(roomId))?.blockImageUrl);
     }
     /** Get the floor plan image for the audience. Returns null if missing. */
-    async getAudienceFloorplan(audienceId) {
-        return this.getCachedAudienceImage(`floor:${audienceId}`, async () => (await this.getAudienceInfo(audienceId))?.floorplanUrl);
+    async getRoomFloorPlan(roomId) {
+        requirePositiveId(roomId, "Room ID");
+        return this.getCachedRoomImage(`floor:${roomId}`, async () => (await this.getRoomInfo(roomId))?.floorplanUrl);
     }
-    async searchTeacher(opts) {
-        const cacheKey = `search:${opts.name}:${this.pertt}`;
+    async searchTeachers(name) {
+        name = normalizeSearchQuery(name, "Teacher search query");
+        const cacheKey = `search:${name}:${this.pertt}`;
         const cached = await this.cache?.get("teachers", cacheKey);
-        if (cached)
-            return cached;
+        if (cached) {
+            const data = cached;
+            await this.rememberTeachers(data);
+            return data;
+        }
         const { body } = await this.authPost(`${BASE}/`, {
-            techname: opts.name,
+            techname: name,
             findtech: "найти",
             hfac: "0",
             pertt: this.pertt,
         });
         const data = parseTeacherButtons(body);
         await this.cache?.set("teachers", cacheKey, data);
+        await this.rememberTeachers(data);
         return data;
     }
     // --- Teacher schedule ---
     async getTeachers() {
         const cached = await this.cache?.get("teachers", "all");
-        if (cached)
-            return cached;
+        if (cached) {
+            const data = cached;
+            await this.rememberTeachers(data);
+            return data;
+        }
         const { body } = await this.authGet(`${BASE}/index/tech`);
         const data = parseTeacherButtons(body);
         await this.cache?.set("teachers", "all", data);
+        await this.rememberTeachers(data);
         return data;
     }
     async fetchTeacherSchedule(teacherId, period, academicYearStartYear) {
         const cacheKey = `teacher:${teacherId}:${period}:${academicYearStartYear}-${academicYearStartYear + 1}`;
         const cached = await this.cache?.get("schedule", cacheKey);
-        if (cached)
-            return cached;
+        if (cached) {
+            const page = cached;
+            await this.rememberTeachers([{ id: teacherId, name: page.ownerName }]);
+            return page.days;
+        }
         const url = `${BASE}/index/techtt/tech/${teacherId}`;
         const { body } = await this.authPost(url, { htype: String(period) });
-        const days = parseTeacherFullSchedule(body, this.educationType);
-        await this.cache?.set("schedule", cacheKey, days);
+        const ownerName = this.validateSchedulePage({ type: "teacher", teacher: { id: teacherId, name: "" } }, body, academicYearStartYear);
+        const days = parseTeacherSchedule(body);
+        await this.rememberTeachers([{ id: teacherId, name: ownerName }]);
+        await this.cache?.set("schedule", cacheKey, { days, ownerName });
         // Cache teacher info from the same page to avoid extra requests
         if (!(await this.cache?.get("teacherInfo", String(teacherId)))) {
             const info = parseTeacherInfo(body);
             if (info)
                 await this.cache?.set("teacherInfo", String(teacherId), info);
+            if (info) {
+                await this.rememberTeachers([
+                    {
+                        id: teacherId,
+                        name: info.name,
+                        degree: info.degree,
+                    },
+                ]);
+            }
         }
         return days;
     }
-    async getTeacherSchedule(teacherId) {
-        const schedules = new Map();
-        const context = await this.getTimetableContext(`${BASE}/index/techtt/tech/${teacherId}`);
-        const results = await Promise.all(ALL_PERIODS.map(async (period) => {
-            const days = await this.fetchTeacherSchedule(teacherId, period, context.academicYearStartYear);
-            return { period, days };
-        }));
-        for (const { period, days } of results) {
-            schedules.set(period, days);
-        }
-        return new Schedule(teacherId, schedules, context.period, this.educationType, undefined, undefined, true, context.academicYearStartYear);
-    }
-    async getTeacherScheduleForPeriod(opts) {
-        const context = await this.getTimetableContext(`${BASE}/index/techtt/tech/${opts.teacherId}`);
-        const days = await this.fetchTeacherSchedule(opts.teacherId, opts.period, context.academicYearStartYear);
-        const schedules = new Map();
-        schedules.set(opts.period, days);
-        return new Schedule(opts.teacherId, schedules, opts.period, this.educationType, undefined, undefined, true, context.academicYearStartYear);
+    async getTeacherSchedule(teacherId, options) {
+        return this.getSchedule({
+            type: "teacher",
+            teacher: this._repository.directory.resolveTeacher({
+                id: teacherId,
+                name: "",
+            }),
+        }, options);
     }
     async getTeacherInfo(teacherId) {
+        requirePositiveId(teacherId, "Teacher ID");
         const cached = await this.cache?.get("teacherInfo", String(teacherId));
-        if (cached)
-            return cached;
+        if (cached) {
+            const info = cached;
+            await this.rememberTeachers([
+                { id: teacherId, name: info.name, degree: info.degree },
+            ]);
+            return info;
+        }
         const url = `${BASE}/index/techtt/tech/${teacherId}`;
         const { body } = await this.authGet(url);
         const info = parseTeacherInfo(body);
         if (info)
             await this.cache?.set("teacherInfo", String(teacherId), info);
+        if (info) {
+            await this.rememberTeachers([
+                { id: teacherId, name: info.name, degree: info.degree },
+            ]);
+        }
         return info;
     }
     /**
-     * Get the teacher's photo as a Buffer.
+     * Get teacher photo directly by known URL pattern.
+     * Does not fetch or parse teacher info first.
      * Returns null if the teacher has no photo.
-     * Uses cached teacher info when available to avoid extra requests.
      */
     async getTeacherPhoto(teacherId) {
-        const photoCacheKey = String(teacherId);
-        const cachedPhoto = this.cache?.getLocal("teacherPhotos", photoCacheKey) ??
-            await this.cache?.get("teacherPhotos", photoCacheKey);
-        if (cachedPhoto !== null && cachedPhoto !== undefined) {
-            const entry = cachedPhoto;
-            if (entry.data !== undefined) {
-                return entry.data ? Buffer.from(entry.data, "base64") : null;
-            }
-            if (entry.blobKey && this.blobAdapter) {
-                const buf = await this.blobAdapter.get(entry.blobKey);
-                if (buf) {
-                    this.cache?.setLocal("teacherPhotos", photoCacheKey, {
-                        data: buf.toString("base64"),
-                    });
-                    return buf;
-                }
-            }
-        }
-        // Get teacher info (may already be cached from schedule fetch)
-        const info = await this.getTeacherInfo(teacherId);
-        if (!info?.photoUrl) {
-            await this.cache?.set("teacherPhotos", photoCacheKey, { data: null });
-            return null;
-        }
-        const photoBuffer = await this.authGetBuffer(`${BASE}${info.photoUrl}`);
-        if (this.blobAdapter) {
-            const blobKey = `tt/teacher-photos/${teacherId}`;
-            this.cache?.setLocal("teacherPhotos", photoCacheKey, {
-                data: photoBuffer.toString("base64"),
-            });
-            await this.blobAdapter.put(blobKey, photoBuffer, {
-                ttl: this.cache?.ttl("teacherPhotos"),
-            });
-            await this.cache?.setExternal("teacherPhotos", photoCacheKey, { blobKey });
-        }
-        else {
-            await this.cache?.set("teacherPhotos", photoCacheKey, {
-                data: photoBuffer.toString("base64"),
-            });
-        }
-        return photoBuffer;
-    }
-    /**
-     * Get the teacher's photo without parsing the schedule page.
-     * Uses the known URL pattern directly — no extra page fetch needed.
-     * Returns null if the teacher has no photo.
-     */
-    async getTeacherPhotoLazy(teacherId) {
+        requirePositiveId(teacherId, "Teacher ID");
         const photoCacheKey = String(teacherId);
         const cachedPhoto = this.cache?.getLocal("teacherPhotos", photoCacheKey) ??
             await this.cache?.get("teacherPhotos", photoCacheKey);