chuvsu-js 4.2.0 → 5.0.1

package/README.md

@@ -1,14 +1,15 @@
 # chuvsu-js
 
-Node.js библиотека для работы с порталами ЧувГУ:
+Типизированная библиотека для сервисов ЧГУ им. И. Н. Ульянова:
 
-- **tt.chuvsu.ru** — расписание занятий (факультеты, группы, преподаватели)
-- **lk.chuvsu.ru** — личный кабинет студента (персональные данные)
+- `tt.chuvsu.ru` — расписания групп, преподавателей, аудиторий и вебинары;
+- `lk.chuvsu.ru` — личный кабинет студента.
 
-> [!WARNING]
-> Пока не доработана, код и архитектура говно (написано Claude) и надо бы его 10 раз переписать.
-> Не надейтесь на правильный вывод расписания, возможны расхождения но я их фикшу оперативно,
-> как появляется больше информации.
+В версии 5 расписание хранится в едином каноническом репозитории. Если одна
+пара встречается в расписаниях группы, преподавателя и аудитории, она сохраняет
+один ID, а сведения из разных страниц дополняют друг друга.
+
+Переход с версии 4: [`docs/v5-migration.md`](docs/v5-migration.md).
 
 ## Установка
 
@@ -16,286 +17,257 @@ Node.js библиотека для работы с порталами ЧувГ
 npm install chuvsu-js
 ```
 
-## Быстрый старт
+Рекомендуются Node.js 20+ и ESM.
 
-### Расписание (TtClient)
+## Быстрый старт
 
 ```ts
-import { TtClient } from "chuvsu-js";
+import { TimetableClient } from "chuvsu-js";
 
-const tt = new TtClient();
+const client = new TimetableClient({ cache: 15 * 60_000 });
+await client.loginAsGuest();
 
-// Войти гостем (без учётной записи)
-await tt.loginAsGuest();
+const [group] = await client.searchGroups("КТ-41-24");
+const schedule = await client.getGroupSchedule(group.id);
 
-// Найти группу по названию
-const groups = await tt.searchGroup({ name: "КТ-41-24" });
-console.log(groups); // [{ id: 8919, name: "КТ-41-24", specialty: "...", profile: "..." }]
-
-// Получить расписание группы
-const schedule = await tt.getSchedule({ groupId: groups[0].id });
-
-// Расписание на сегодня
-const today = schedule.today();
-for (const lesson of today) {
+for (const lesson of schedule.today({ subgroup: 1 })) {
   console.log(
-    `${lesson.start.hours}:${lesson.start.minutes} — ${lesson.subject} (${lesson.type})`,
+    lesson.id,
+    lesson.subject,
+    lesson.teachers.values,
+    lesson.rooms.values,
   );
 }
-
-// С фильтром по подгруппе
-schedule.today({ subgroup: 1 });
-
-// На завтра
-schedule.tomorrow();
-
-// На текущую неделю
-schedule.thisWeek();
-
-// Текущая пара
-schedule.currentLesson();
 ```
 
-### Личный кабинет (LkClient)
+У каждой конкретной пары есть `id`. У повторяющейся пары также есть
+`seriesId`:
 
 ```ts
-import { LkClient } from "chuvsu-js";
-
-const lk = new LkClient({ cache: 60_000 });
-await lk.login({ email: "student@mail.ru", password: "password" });
-
-const data = await lk.getPersonalData();
-console.log(`${data.lastName} ${data.firstName}, группа ${data.group}`);
-
-// Получить ID группы для использования с TtClient
-const groupId = await lk.getGroupId();
+const series = schedule.series();
+const monday = schedule.weekday(1, { week: 4 });
+const day = schedule.on(new Date(2026, 8, 7));
+const week = schedule.week(4);
+const current = schedule.current();
 ```
 
-## API
-
-### TtClient
-
-Клиент для работы с расписанием (`tt.chuvsu.ru`).
+ID не строится из даты, аудитории или времени. Перенос и смена аудитории сами
+по себе не создают новую сущность. Чтобы ID сохранялись между запусками,
+подключите постоянное хранилище репозитория.
 
-#### Конструктор
+## Расписания разных владельцев
 
 ```ts
-new TtClient(options?: TtClientOptions)
+await client.getGroupSchedule(groupId);
+await client.getTeacherSchedule(teacherId);
+await client.getRoomSchedule(roomId);
 ```
 
-| Опция           | Тип                     | По умолчанию      | Описание                                                       |
-| --------------- | ----------------------- | ----------------- | -------------------------------------------------------------- |
-| `educationType` | `EducationType`         | `HigherEducation` | Тип образования: высшее (1) или СПО (2)                        |
-| `cache`         | `number \| CacheConfig` | —                 | TTL кеша в мс. Число задаёт единый TTL, объект — по категориям |
-| `cacheAdapter`  | `CacheAdapter`          | —                 | Внешний L2-кеш для JSON-данных (например Redis/БД)             |
-| `blobAdapter`   | `BlobAdapter`           | —                 | Хранилище бинарных данных, например S3/R2/MinIO                |
-
-#### Авторизация
+Общий метод:
 
 ```ts
-// С учётной записью
-await tt.login({ email: "...", password: "..." });
-
-// Гостевой вход
-await tt.loginAsGuest();
+await client.getSchedule({
+  type: "teacher",
+  teacher: { id: teacherId, name: "Иванов Иван Иванович" },
+});
 ```
 
-#### Получение расписания
+Можно загрузить только нужные периоды:
 
 ```ts
-const schedule = await tt.getSchedule({ groupId, period? });
+import { AcademicPeriod } from "chuvsu-js";
+
+await client.getGroupSchedule(groupId, {
+  periods: [AcademicPeriod.FallSemester],
+});
 ```
 
-Возвращает объект `Schedule`, который позволяет получать расписание локально, без дополнительных запросов к серверу.
+## Дополнение данных из разных страниц
 
-#### Поиск
+Страница группы часто содержит только фамилию и инициалы преподавателя.
+Страница преподавателя сообщает список групп, а страница аудитории — другие
+связи той же пары. Все это считается неполными наблюдениями:
 
 ```ts
-// Список факультетов
-const faculties = await tt.getFaculties();
+const groupSchedule = await client.getGroupSchedule(groupId);
+const before = groupSchedule.on(date);
 
-// Группы факультета
-const groups = await tt.getGroupsForFaculty({ facultyId });
+await client.getTeacherSchedule(teacherId);
+await client.getRoomSchedule(roomId);
 
-// Поиск группы по названию
-const groups = await tt.searchGroup({ name: "ЗИ" });
-
-// Поиск преподавателя
-const teachers = await tt.searchTeacher({ name: "Иванов" });
+const after = groupSchedule.on(date);
+// ID прежний, но в связях могли появиться дополнительные группы и ID сущностей.
 ```
 
-#### Период
+`Schedule` — живое представление репозитория: следующий запрос через уже
+созданный объект видит новые данные.
 
-```ts
-// Текущий учебный период
-const period = tt.getCurrentPeriod();
-```
-
-#### Кеш
+Связи имеют вид `RelationSet<T>`:
 
 ```ts
-// Очистить весь кеш или по категории
-tt.clearCache();
-tt.clearCache("schedule");
-
-// Экспорт/импорт (для сохранения между запусками)
-const data = tt.exportCache();
-tt.importCache(data);
+lesson.rooms // { values: RoomRef[], completeness: "unknown" | "partial" | "complete" }
 ```
 
-Категории кеша: `schedule`, `faculties`, `groups`, `audiences`, `audienceNames`, `teachers`, `teacherInfo`, `teacherPhotos`, `audienceInfo`, `audienceImages`.
+`unknown` означает, что страница ничего не сообщила. `complete` с пустым
+`values` означает, что отсутствие известно явно. Поэтому пустая строка
+аудитории в канонической модели не используется.
 
-Если передать `cacheAdapter`, библиотека использует двухуровневый кеш:
-- L1: in-memory кеш внутри процесса
-- L2: внешний адаптер (`cacheAdapter`)
+## Номер пары и время
 
-Если передать `blobAdapter`, фото преподавателей, аудиторий, корпусов и планов этажей будут храниться во внешнем blob/object storage, а во внешнем JSON-кеше сохранятся только метаданные с ключом blob-объекта.
-
-### Schedule
-
-Объект расписания группы. Все методы синхронные — данные уже загружены.
-
-#### Свойства
+Портал иногда показывает противоречивые номер пары и время. В v5 это независимые
+утверждения:
 
 ```ts
-schedule.groupId; // ID группы
-schedule.period; // Учебный период
-schedule.days; // Сырые данные (FullScheduleDay[])
+lesson.slotNumber // 6
+lesson.time       // { start: { hours: 16, minutes: 40 }, end: ... }
 ```
 
-#### Расписание по дате
+Номер не вычисляется из времени, а время — из номера. При объединении одна
+совпавшая величина может подтвердить пару, если остальные признаки надежны;
+разные дни или несовместимое чередование объединяться не будут.
 
-```ts
-// На сегодня
-schedule.today({ subgroup?: number });
+Даты без времени представлены строкой `LocalDate` формата `YYYY-MM-DD`, например
+`lesson.scheduledDate === "2026-09-03"`. Это исключает сдвиги даты из-за UTC.
 
-// На завтра
-schedule.tomorrow({ subgroup?: number });
+Экзамены, консультации и другие строки сессии являются сразу конкретными
+`LessonOccurrence`: дата берется со страницы, `seriesId` и `recurrence` у них
+нет. Значения-заглушки наподобие `weeks: { from: 0, to: 0 }` не используются.
 
-// На конкретную дату
-schedule.forDate(date: Date, { subgroup?: number });
-```
+## Справочник сущностей без каскадных запросов
 
-#### Расписание по неделе
+Загрузка расписания никогда автоматически не запускает поиск преподавателей,
+групп или аудиторий. Обычные методы поиска наполняют общий справочник:
 
 ```ts
-// На текущую неделю
-schedule.thisWeek({ subgroup?: number });
+await client.getTeachers();
+await client.getRooms();
+await client.getFacultyGroups(facultyId);
 
-// На конкретную неделю
-schedule.forWeek(week?: number, { subgroup?: number });
+const teacher = await client.resolveTeacher("Иванов И. И.");
 ```
 
-#### Расписание по дню недели
+По умолчанию разрешение использует только уже известные данные. Один явный
+поиск можно разрешить отдельно:
 
 ```ts
-// По дню недели (0 = воскресенье, 1 = понедельник, ...)
-schedule.forDay(weekday: number, { subgroup?: number, week?: number });
+const teacher = await client.resolveTeacher("Иванов И. И.", {
+  strategy: "search",
+});
 ```
 
-#### Текущая пара
+Или заранее загрузить нужные справочники:
 
 ```ts
-const lesson = schedule.currentLesson({ subgroup?: number });
+await client.preloadDirectory({
+  teachers: true,
+  rooms: true,
+  facultyIds: [19],
+});
 ```
 
-#### Утилиты семестра
+ID присваивается сокращенному имени только при единственном совпадении.
+
+## Постоянный репозиторий
+
+TTL-кеш ответов и хранилище канонических ID независимы:
 
 ```ts
-// Номер текущей недели
-schedule.getWeekNumber(date?: Date);
+const client = new TimetableClient({
+  cache: 15 * 60_000,
+  cacheAdapter,
+  repositoryAdapter,
+});
+```
 
-// Все недели семестра
-schedule.getSemesterWeeks(weekCount?: number);
+`TimetableRepositoryAdapter` можно реализовать поверх БД, KV-хранилища или
+файлового сервиса. Запись использует ревизии compare-and-set, чтобы параллельные
+процессы не перезаписывали установленные ID.
 
-// Начало семестра
-schedule.getSemesterStart();
+```ts
+const snapshot = await client.exportRepository();
 ```
 
-Утилиты также доступны как standalone функции:
+Для одного процесса есть память:
 
 ```ts
 import {
-  getSemesterStart,
-  getSemesterWeeks,
-  getWeekNumber,
-  Period,
+  MemoryTimetableRepositoryAdapter,
+  TimetableClient,
 } from "chuvsu-js";
 
-getSemesterStart({ period: Period.FallSemester, year: 2025 });
-getSemesterWeeks({ period: Period.SpringSemester });
-getWeekNumber({ period: Period.SpringSemester });
+const repositoryAdapter = new MemoryTimetableRepositoryAdapter();
+const client = new TimetableClient({ repositoryAdapter });
 ```
 
-### LkClient
+## Использование в браузере
 
-Клиент для личного кабинета (`lk.chuvsu.ru`).
+`chuvsu-js/browser` не содержит `undici`, сертификатов ЧГУ, `Buffer` и HTML-
+парсера. Браузер может получить снимок с сервера и выполнять запросы локально:
 
 ```ts
-const lk = new LkClient({ cache?: number | LkCacheConfig });
-await lk.login({ email, password });
-const data = await lk.getPersonalData();
-const groupId = await lk.getGroupId();
-```
-
-`cache` работает так же, как в `TtClient`: число задаёт единый TTL в мс, объект — TTL по категориям (`personalData`, `photo`, `groupId`).
-Также поддерживаются `cacheAdapter` и `blobAdapter`.
+import { Schedule, TimetableRepository } from "chuvsu-js/browser";
 
-**PersonalData** содержит: `lastName`, `firstName`, `patronymic`, `sex`, `birthday`, `recordBookNumber`, `faculty`, `specialty`, `profile`, `group`, `course`, `email`, `phone`.
+const repository = new TimetableRepository({ snapshot });
+const schedule = new Schedule(
+  repository,
+  { type: "group", group: { id: 8919, name: "КТ-41-24" } },
+  2026,
+);
 
-## Типы
+const lessons = schedule.on(new Date(2026, 8, 7));
+```
 
-### Period
+Сетевые клиенты остаются Node-only: авторизация, cookie, сертификаты и CORS
+портала нельзя надежно перенести в чистый браузерный пакет.
 
 ```ts
-enum Period {
-  FallSemester = 1, // Осенний семестр
-  WinterSession = 2, // Зимняя сессия
-  SpringSemester = 3, // Весенний семестр
-  SummerSession = 4, // Летняя сессия
-}
+import { TimetableClient } from "chuvsu-js";          // Node + ядро
+import { TimetableClient } from "chuvsu-js/node";     // явно Node
+import { TimetableRepository } from "chuvsu-js/browser";
+import { parseGroupSchedule } from "chuvsu-js/parsers";
 ```
 
-### EducationType
+## Поиск и метаданные
 
 ```ts
-enum EducationType {
-  HigherEducation = 1, // Высшее образование
-  VocationalEducation = 2, // СПО
-}
+const faculties = await client.getFaculties();
+const groups = await client.getFacultyGroups(facultyId);
+const groupsByName = await client.searchGroups("КТ-41");
+const teachers = await client.searchTeachers("Иванов");
+const rooms = await client.searchRooms("Г-40");
+
+const teacherInfo = await client.getTeacherInfo(teacherId);
+const teacherPhoto = await client.getTeacherPhoto(teacherId);
+const roomInfo = await client.getRoomInfo(roomId);
+const roomPhoto = await client.getRoomImage(roomId);
+const buildingPhoto = await client.getRoomBuildingImage(roomId);
+const floorPlan = await client.getRoomFloorPlan(roomId);
 ```
 
-### Lesson
+Фото преподавателя загружается по уже известному прямому URL без лишнего
+запроса страницы преподавателя.
+
+## Личный кабинет
 
 ```ts
-interface Lesson {
-  number: number; // Номер пары
-  start: LessonTime; // Начало { date, hours, minutes }
-  end: LessonTime; // Конец { date, hours, minutes }
-  subject: string; // Предмет
-  type: string; // Тип (лекция, практика, лаб. работа)
-  room: string; // Аудитория
-  teacher: Teacher; // Преподаватель { name, position?, degree? }
-  weeks: WeekRange; // Диапазон недель { from, to }
-  subgroup?: number; // Подгруппа
-  weekParity?: "even" | "odd"; // Чётность недели
-}
-```
+import { StudentPortalClient } from "chuvsu-js";
 
-## Обработка ошибок
+const portal = new StudentPortalClient({ cache: 60_000 });
+await portal.login({ email: "student@example.com", password: "password" });
 
-```ts
-import { AuthError, ParseError } from "chuvsu-js";
-
-try {
-  await tt.login({ email: "...", password: "wrong" });
-} catch (e) {
-  if (e instanceof AuthError) {
-    console.error("Неверные данные для входа");
-  }
-}
+const profile = await portal.getProfile();
+const photo = await portal.getProfilePhoto();
+const groupId = await portal.getTimetableGroupId();
 ```
 
-## Лицензия
+## Разработка
+
+```bash
+pnpm build
+pnpm test
+pnpm test:coverage
+pnpm fixtures:test
+```
 
-MIT
+Подробности архитектуры: [`docs/v5-architecture.md`](docs/v5-architecture.md).
+Границы и честная интерпретация тестов: [`docs/testing.md`](docs/testing.md).

package/dist/browser.d.ts

@@ -1 +1 @@
-export * from "./shared.js";
+export * from "./core.js";

package/dist/browser.js

@@ -1 +1 @@
-export * from "./shared.js";
+export * from "./core.js";

package/dist/common/cache.js

@@ -2,7 +2,14 @@ export class Cache {
     ttls;
     store = new Map();
     constructor(ttls) {
-        this.ttls = ttls;
+        for (const [category, ttl] of Object.entries(ttls)) {
+            if (ttl != null &&
+                ttl !== Infinity &&
+                (!Number.isFinite(ttl) || ttl < 0)) {
+                throw new RangeError(`Invalid cache TTL for ${category}`);
+            }
+        }
+        this.ttls = { ...ttls };
     }
     get(category, key) {
         const ttl = this.ttls[category];
@@ -15,13 +22,13 @@ export class Cache {
             this.store.delete(`${category}:${key}`);
             return null;
         }
-        return entry.data;
+        return structuredClone(entry.data);
     }
     set(category, key, data) {
         if (this.ttls[category] == null)
             return;
         this.store.set(`${category}:${key}`, {
-            data,
+            data: structuredClone(data),
             timestamp: Date.now(),
         });
     }
@@ -38,11 +45,25 @@ export class Cache {
         }
     }
     export() {
-        return Object.fromEntries(this.store);
+        return structuredClone(Object.fromEntries(this.store));
     }
     import(data) {
         for (const [key, entry] of Object.entries(data)) {
-            this.store.set(key, entry);
+            const separator = key.indexOf(":");
+            const category = separator < 1 || separator === key.length - 1
+                ? ""
+                : key.slice(0, separator);
+            if (this.ttls[category] == null) {
+                throw new TypeError(`Invalid or disabled cache category in ${key}`);
+            }
+            if (entry == null ||
+                typeof entry !== "object" ||
+                !Number.isFinite(entry.timestamp) ||
+                entry.timestamp < 0 ||
+                !("data" in entry)) {
+                throw new TypeError(`Invalid cache entry: ${key}`);
+            }
+            this.store.set(key, structuredClone(entry));
         }
     }
 }
@@ -51,8 +72,8 @@ export class HybridCache {
     ttls;
     adapter;
     constructor(ttls, adapter) {
-        this.ttls = ttls;
-        this.memory = new Cache(ttls);
+        this.ttls = { ...ttls };
+        this.memory = new Cache(this.ttls);
         this.adapter = adapter;
     }
     ttl(category) {
@@ -75,7 +96,7 @@ export class HybridCache {
         if (external === null || external === undefined)
             return null;
         this.memory.set(category, key, external);
-        return external;
+        return this.memory.get(category, key);
     }
     async set(category, key, data) {
         this.memory.set(category, key, data);
@@ -85,7 +106,7 @@ export class HybridCache {
         const ttl = this.ttls[category];
         if (ttl == null || !this.adapter)
             return;
-        await this.adapter.set(category, key, data, ttl);
+        await this.adapter.set(category, key, structuredClone(data), ttl);
     }
     async clear(category) {
         this.memory.clear(category);

package/dist/common/http.d.ts

@@ -3,11 +3,17 @@ export interface HttpResponse {
     body: string;
     location?: string;
 }
+export interface HttpBufferResponse {
+    status: number;
+    body: Buffer;
+    contentType?: string;
+}
 export declare class HttpClient {
     private cookies;
     private cookieHeader;
     private saveCookies;
     get(url: string, followRedirects?: boolean): Promise<HttpResponse>;
     getBuffer(url: string): Promise<Buffer>;
+    getBufferResponse(url: string): Promise<HttpBufferResponse>;
     post(url: string, data: Record<string, string>, followRedirects?: boolean): Promise<HttpResponse>;
 }

package/dist/common/http.js

@@ -33,13 +33,20 @@ export class HttpClient {
         };
     }
     async getBuffer(url) {
+        return (await this.getBufferResponse(url)).body;
+    }
+    async getBufferResponse(url) {
         const res = await fetch(url, {
             method: "GET",
             headers: { Cookie: this.cookieHeader() },
             dispatcher: agent,
         });
         this.saveCookies(res.headers);
-        return Buffer.from(await res.arrayBuffer());
+        return {
+            status: res.status,
+            body: Buffer.from(await res.arrayBuffer()),
+            contentType: res.headers.get("content-type") ?? undefined,
+        };
     }
     async post(url, data, followRedirects = true) {
         const body = new URLSearchParams(data).toString();

package/dist/common/parse.d.ts

@@ -4,7 +4,7 @@ export declare function text(el: Element | null): string;
 /** Parse "HH:MM" into {hours, minutes} */
 export declare function parseTime(s: string): Time;
 /** Parse "2 нед." -> {from:2,to:2}, "6 - 8 нед." -> {from:6,to:8} */
-export declare function parseWeeks(s: string): WeekRange;
+export declare function parseWeeks(s: string): WeekRange | undefined;
 /** Parse <sup>*</sup> / <sup>**</sup> markers: * = odd week, ** = even week */
 export declare function parseWeekParity(html: string): "even" | "odd" | undefined;
 export declare function parseTeacher(s: string): Teacher;

package/dist/common/parse.js

@@ -18,7 +18,7 @@ export function parseWeeks(s) {
     const single = s.match(/(\d+)/);
     if (single)
         return { from: parseInt(single[1]), to: parseInt(single[1]) };
-    return { from: 0, to: 0 };
+    return undefined;
 }
 /** Parse <sup>*</sup> / <sup>**</sup> markers: * = odd week, ** = even week */
 export function parseWeekParity(html) {
@@ -33,7 +33,7 @@ export function parseTeacher(s) {
         return { name: "" };
     const posMatch = trimmed.match(/^(доц\.|проф\.|ст\.преп\.|ст\. преп\.|преп\.|асс\.|зав\.каф\.)\s*/);
     const afterPos = posMatch ? trimmed.slice(posMatch[0].length) : trimmed;
-    const degMatch = afterPos.match(/^([кд]\.[а-яё.-]+н\.)\s*/);
+    const degMatch = afterPos.match(/^((?:[кд]\.[а-яё.-]+н\.|к\.иск\.))\s*/);
     const name = degMatch ? afterPos.slice(degMatch[0].length).trim() : afterPos.trim();
     const result = { name };
     if (posMatch)