chuvsu-js 4.2.0 → 5.0.0

package/dist/common/types.d.ts

@@ -1,10 +1,10 @@
-export declare const enum Period {
+export declare enum AcademicPeriod {
     FallSemester = 1,
     WinterSession = 2,
     SpringSemester = 3,
     SummerSession = 4
 }
-export declare const enum EducationType {
+export declare enum EducationLevel {
     HigherEducation = 1,
     VocationalEducation = 2
 }
@@ -12,6 +12,12 @@ export interface Time {
     hours: number;
     minutes: number;
 }
+export interface TimeRange {
+    start: Time;
+    end: Time;
+}
+/** Calendar date without a timezone or time component. */
+export type LocalDate = `${number}-${number}-${number}`;
 export interface WeekRange {
     from: number;
     to: number;

package/dist/common/types.js

@@ -1,3 +1,15 @@
+export var AcademicPeriod;
+(function (AcademicPeriod) {
+    AcademicPeriod[AcademicPeriod["FallSemester"] = 1] = "FallSemester";
+    AcademicPeriod[AcademicPeriod["WinterSession"] = 2] = "WinterSession";
+    AcademicPeriod[AcademicPeriod["SpringSemester"] = 3] = "SpringSemester";
+    AcademicPeriod[AcademicPeriod["SummerSession"] = 4] = "SummerSession";
+})(AcademicPeriod || (AcademicPeriod = {}));
+export var EducationLevel;
+(function (EducationLevel) {
+    EducationLevel[EducationLevel["HigherEducation"] = 1] = "HigherEducation";
+    EducationLevel[EducationLevel["VocationalEducation"] = 2] = "VocationalEducation";
+})(EducationLevel || (EducationLevel = {}));
 export class AuthError extends Error {
     constructor(message) {
         super(message);

package/dist/core.d.ts

@@ -0,0 +1,10 @@
+export * from "./tt/domain/index.js";
+export { attachWebinars, findWebinar } from "./tt/webinars.js";
+export type { LessonWithWebinar } from "./tt/webinars.js";
+export { getAdjacentSemester, getCompensatingWorkDays, getCurrentPeriod, getEffectiveHolidays, formatLocalDate, getHolidayTransfers, getSemesterStart, getSemesterWeeks, getStandardScheduleBlocks, getWeekNumber, getWeekdayName, isHoliday, isLocalDate, isSessionPeriod, parseLocalDate, RUSSIAN_HOLIDAYS, } from "./tt/utils/index.js";
+export type { Holiday, HolidayTransfer } from "./tt/utils/index.js";
+export { AuthError, EducationLevel, ParseError, AcademicPeriod, } from "./common/types.js";
+export type { LocalDate, Teacher, Time, TimeRange, WeekRange, } from "./common/types.js";
+export type { CacheAdapter, CacheEntry } from "./common/cache.js";
+export type { CacheConfig, DirectoryPreloadOptions, EntityResolutionStrategy, Faculty, GetScheduleOptions, Group, StandardScheduleBlock, Room, RoomInfo, SemesterWeek, TeacherInfo, TimetableClientOptions, Webinar, } from "./tt/types.js";
+export type { StudentPortalCacheConfig, StudentPortalClientOptions, StudentProfile, } from "./lk/types.js";

package/dist/core.js

@@ -0,0 +1,5 @@
+// Runtime-safe core for Node.js, browsers, Deno, and workers.
+export * from "./tt/domain/index.js";
+export { attachWebinars, findWebinar } from "./tt/webinars.js";
+export { getAdjacentSemester, getCompensatingWorkDays, getCurrentPeriod, getEffectiveHolidays, formatLocalDate, getHolidayTransfers, getSemesterStart, getSemesterWeeks, getStandardScheduleBlocks, getWeekNumber, getWeekdayName, isHoliday, isLocalDate, isSessionPeriod, parseLocalDate, RUSSIAN_HOLIDAYS, } from "./tt/utils/index.js";
+export { AuthError, EducationLevel, ParseError, AcademicPeriod, } from "./common/types.js";

package/dist/index.d.ts

@@ -1,3 +1,5 @@
-export * from "./shared.js";
-export { LkClient } from "./lk/client.js";
-export { TtClient } from "./tt/client.js";
+export * from "./core.js";
+export { StudentPortalClient } from "./lk/client.js";
+export { TimetableClient } from "./tt/client.js";
+export * from "./parsers.js";
+export type { BlobAdapter, BlobPutOptions, } from "./common/cache.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export * from "./shared.js";
-// Node-only clients (depend on `undici`).
-export { LkClient } from "./lk/client.js";
-export { TtClient } from "./tt/client.js";
+export * from "./core.js";
+export { StudentPortalClient } from "./lk/client.js";
+export { TimetableClient } from "./tt/client.js";
+export * from "./parsers.js";

package/dist/lk/client.d.ts

@@ -1,17 +1,19 @@
-import type { LkClientOptions, PersonalData } from "./types.js";
-export declare class LkClient {
+import type { StudentPortalClientOptions, StudentProfile } from "./types.js";
+export declare class StudentPortalClient {
     private http;
     private credentials;
     private cache;
     private blobAdapter;
-    constructor(opts?: LkClientOptions);
+    constructor(opts?: StudentPortalClientOptions);
     login(opts: {
         email: string;
         password: string;
     }): Promise<void>;
     private isSessionExpired;
     private authGet;
-    getPersonalData(): Promise<PersonalData>;
-    getPhoto(): Promise<Buffer>;
-    getGroupId(): Promise<number | null>;
+    private isBinarySessionExpired;
+    private authGetBuffer;
+    getProfile(): Promise<StudentProfile>;
+    getProfilePhoto(): Promise<Buffer>;
+    getTimetableGroupId(): Promise<number | null>;
 }

package/dist/lk/client.js

@@ -1,18 +1,18 @@
-import { HttpClient } from "../common/http.js";
+import { HttpClient, } from "../common/http.js";
 import { HybridCache } from "../common/cache.js";
-import { AuthError } from "../common/types.js";
+import { AuthError, ParseError } from "../common/types.js";
 import { extractScriptValues } from "./parse.js";
 const BASE = "https://lk.chuvsu.ru";
 const LOGIN_URL = `${BASE}/info/login.php`;
 const STUDENT_BASE = `${BASE}/student`;
 function makeUniformCacheConfig(ttl) {
     return {
-        personalData: ttl,
-        photo: ttl,
-        groupId: ttl,
+        profile: ttl,
+        profilePhoto: ttl,
+        timetableGroupId: ttl,
     };
 }
-export class LkClient {
+export class StudentPortalClient {
     http = new HttpClient();
     credentials = null;
     cache;
@@ -40,19 +40,47 @@ export class LkClient {
         return body.includes("login.php");
     }
     async authGet(url) {
-        const res = await this.http.get(url);
+        let res = await this.http.get(url);
         if (this.credentials && this.isSessionExpired(res.body)) {
             await this.login(this.credentials);
-            return this.http.get(url);
+            res = await this.http.get(url);
+        }
+        if (this.isSessionExpired(res.body)) {
+            throw new AuthError("LK request returned an authentication page");
+        }
+        if (res.status < 200 || res.status >= 300) {
+            throw new Error(`LK request failed with HTTP ${res.status}: ${url}`);
         }
         return res;
     }
-    async getPersonalData() {
-        const cached = await this.cache?.get("personalData", "self");
+    isBinarySessionExpired(response) {
+        const prefix = response.body.subarray(0, 8_192).toString("utf8");
+        return this.isSessionExpired(prefix) ||
+            response.contentType?.toLowerCase().includes("text/html") === true;
+    }
+    async authGetBuffer(url) {
+        let res = await this.http.getBufferResponse(url);
+        if (this.credentials && this.isBinarySessionExpired(res)) {
+            await this.login(this.credentials);
+            res = await this.http.getBufferResponse(url);
+        }
+        if (res.status < 200 || res.status >= 300) {
+            throw new Error(`LK request failed with HTTP ${res.status}: ${url}`);
+        }
+        if (this.isBinarySessionExpired(res)) {
+            throw new AuthError("LK binary request returned an authentication page");
+        }
+        return res.body;
+    }
+    async getProfile() {
+        const cached = await this.cache?.get("profile", "self");
         if (cached)
             return cached;
         const { body } = await this.authGet(`${STUDENT_BASE}/personal_data.php`);
         const vals = extractScriptValues(body, "form_personal_data");
+        if (!vals.fam?.trim() || !vals.nam?.trim()) {
+            throw new ParseError("LK profile response has no student identity");
+        }
         const data = {
             lastName: vals.fam ?? "",
             firstName: vals.nam ?? "",
@@ -68,12 +96,12 @@ export class LkClient {
             email: vals.email ?? "",
             phone: vals.phone ?? "",
         };
-        await this.cache?.set("personalData", "self", data);
+        await this.cache?.set("profile", "self", data);
         return data;
     }
-    async getPhoto() {
-        const cached = this.cache?.getLocal("photo", "self") ??
-            await this.cache?.get("photo", "self");
+    async getProfilePhoto() {
+        const cached = this.cache?.getLocal("profilePhoto", "self") ??
+            await this.cache?.get("profilePhoto", "self");
         if (cached !== null && cached !== undefined) {
             const entry = cached;
             if (typeof entry === "string")
@@ -84,33 +112,33 @@ export class LkClient {
             if (entry.blobKey && this.blobAdapter) {
                 const photo = await this.blobAdapter.get(entry.blobKey);
                 if (photo) {
-                    this.cache?.setLocal("photo", "self", { data: photo.toString("base64") });
+                    this.cache?.setLocal("profilePhoto", "self", { data: photo.toString("base64") });
                     return photo;
                 }
             }
         }
-        const photo = await this.http.getBuffer(`${STUDENT_BASE}/face.php`);
+        const photo = await this.authGetBuffer(`${STUDENT_BASE}/face.php`);
         if (this.blobAdapter) {
             const blobKey = "lk/photo/self";
-            this.cache?.setLocal("photo", "self", { data: photo.toString("base64") });
+            this.cache?.setLocal("profilePhoto", "self", { data: photo.toString("base64") });
             await this.blobAdapter.put(blobKey, photo, {
-                ttl: this.cache?.ttl("photo"),
+                ttl: this.cache?.ttl("profilePhoto"),
             });
-            await this.cache?.setExternal("photo", "self", { blobKey });
+            await this.cache?.setExternal("profilePhoto", "self", { blobKey });
         }
         else {
-            await this.cache?.set("photo", "self", photo.toString("base64"));
+            await this.cache?.set("profilePhoto", "self", photo.toString("base64"));
         }
         return photo;
     }
-    async getGroupId() {
-        const cached = await this.cache?.get("groupId", "self");
+    async getTimetableGroupId() {
+        const cached = await this.cache?.get("timetableGroupId", "self");
         if (cached !== null && cached !== undefined)
             return cached;
         const { body } = await this.authGet(`${STUDENT_BASE}/tt.php`);
         const match = body.match(/tt\.chuvsu\.ru\/index\/grouptt\/gr\/(\d+)/);
         const groupId = match ? parseInt(match[1]) : null;
-        await this.cache?.set("groupId", "self", groupId);
+        await this.cache?.set("timetableGroupId", "self", groupId);
         return groupId;
     }
 }

package/dist/lk/types.d.ts

@@ -1,5 +1,5 @@
 import type { BlobAdapter, CacheAdapter } from "../common/cache.js";
-export interface PersonalData {
+export interface StudentProfile {
     lastName: string;
     firstName: string;
     patronymic: string;
@@ -14,13 +14,13 @@ export interface PersonalData {
     email: string;
     phone: string;
 }
-export interface LkCacheConfig {
-    personalData?: number;
-    photo?: number;
-    groupId?: number;
+export interface StudentPortalCacheConfig {
+    profile?: number;
+    profilePhoto?: number;
+    timetableGroupId?: number;
 }
-export interface LkClientOptions {
-    cache?: number | LkCacheConfig;
+export interface StudentPortalClientOptions {
+    cache?: number | StudentPortalCacheConfig;
     cacheAdapter?: CacheAdapter;
     blobAdapter?: BlobAdapter;
 }

package/dist/node.d.ts

@@ -0,0 +1 @@
+export * from "./index.js";

package/dist/node.js

@@ -0,0 +1 @@
+export * from "./index.js";

package/dist/parsers.d.ts

@@ -0,0 +1,3 @@
+export { parseAcademicYearFromPage, parseRoomButtons, parseRoomSchedule, parseRoomInfo, parseRoomName, parseFacultyButtons, parseGroupSchedule, parseGroupName, parseGroupButtons, parseGroupsString, parsePeriodFromPage, parseTeacherButtons, parseTeacherSchedule, parseTeacherInfo, parseWebinars, } from "./tt/parse/index.js";
+export { createScheduleSourceSnapshot } from "./tt/observations.js";
+export type { ParsedScheduleDay, ParsedLesson, ParsedScheduleBlock, } from "./tt/types.js";

package/dist/parsers.js

@@ -0,0 +1,2 @@
+export { parseAcademicYearFromPage, parseRoomButtons, parseRoomSchedule, parseRoomInfo, parseRoomName, parseFacultyButtons, parseGroupSchedule, parseGroupName, parseGroupButtons, parseGroupsString, parsePeriodFromPage, parseTeacherButtons, parseTeacherSchedule, parseTeacherInfo, parseWebinars, } from "./tt/parse/index.js";
+export { createScheduleSourceSnapshot } from "./tt/observations.js";

package/dist/tt/client.d.ts

@@ -1,16 +1,29 @@
 import type { CacheEntry } from "../common/cache.js";
-import { Period } from "../common/types.js";
-import { Schedule } from "./schedule.js";
-import type { Audience, AudienceInfo, Faculty, Group, TeacherInfo, TtClientOptions, CacheConfig, Webinar } from "./types.js";
-export declare class TtClient {
+import { Schedule } from "./domain/schedule.js";
+import { TimetableRepository } from "./domain/repository.js";
+import type { GroupRef, RoomRef, ScheduleOwner, TeacherRef, TimetableRepositorySnapshot } from "./domain/types.js";
+import type { Room, RoomInfo, Faculty, Group, TeacherInfo, TimetableClientOptions, CacheConfig, DirectoryPreloadOptions, EntityResolutionStrategy, GetScheduleOptions, Webinar } from "./types.js";
+export declare class TimetableClient {
     private http;
-    private educationType;
+    private educationLevel;
     private cache;
     private blobAdapter;
+    private _repository;
+    private repositoryAdapter;
+    private repositoryReady;
+    private repositoryMutation;
     private loginMode;
     private timetableContext;
-    constructor(opts?: TtClientOptions);
+    constructor(opts?: TimetableClientOptions);
     private get pertt();
+    get repository(): TimetableRepository;
+    private ensureRepository;
+    private mutateRepository;
+    private performRepositoryMutation;
+    exportRepository(): Promise<TimetableRepositorySnapshot>;
+    private rememberGroups;
+    private rememberTeachers;
+    private rememberRooms;
     clearCache(category?: keyof CacheConfig): Promise<void>;
     exportCache(): Record<string, CacheEntry>;
     importCache(data: Record<string, CacheEntry>): void;
@@ -20,25 +33,21 @@ export declare class TtClient {
     }): Promise<void>;
     loginAsGuest(): Promise<void>;
     private isSessionExpired;
+    private isBinarySessionExpired;
     private relogin;
     private authGet;
     private authGetBuffer;
     private authPost;
     /** Resolve the academic year and active period from tt.chuvsu.ru itself. */
     private getTimetableContext;
-    private fetchSchedule;
-    /**
-     * Get schedule for all periods. The returned Schedule automatically
-     * routes queries to the correct period based on the date.
-     */
-    getSchedule(groupId: number): Promise<Schedule>;
-    /**
-     * Get schedule for a specific period only.
-     */
-    getScheduleForPeriod(opts: {
-        groupId: number;
-        period: Period;
-    }): Promise<Schedule>;
+    private fetchGroupSchedule;
+    private validateSchedulePage;
+    private ownerUrl;
+    private sourceKey;
+    private resolveOwner;
+    private fetchOwnerSchedule;
+    getSchedule(owner: ScheduleOwner, options?: GetScheduleOptions): Promise<Schedule>;
+    getGroupSchedule(groupId: number, options?: GetScheduleOptions): Promise<Schedule>;
     getWebinars(opts?: {
         date?: Date;
         facultyId?: number;
@@ -50,19 +59,13 @@ export declare class TtClient {
         password: string;
     }): Promise<string>;
     getFaculties(): Promise<Faculty[]>;
-    getGroupsForFaculty(opts: {
-        facultyId: number;
-    }): Promise<Group[]>;
-    searchGroup(opts: {
-        name: string;
-    }): Promise<Group[]>;
+    getFacultyGroups(facultyId: number): Promise<Group[]>;
+    searchGroups(name: string): Promise<GroupRef[]>;
     /**
      * Search audiences by name (substring match). The server requires at
      * least 3 characters in the query.
      */
-    searchAudience(opts: {
-        name: string;
-    }): Promise<Audience[]>;
+    searchRooms(name: string): Promise<Room[]>;
     /**
      * Get every audience known to the system in a single request.
      *
@@ -71,61 +74,50 @@ export declare class TtClient {
      * 3-character wildcard `%%%` matches every audience at once and returns
      * the full list of (id, name) pairs.
      */
-    getAudiences(): Promise<Audience[]>;
+    getRooms(): Promise<Room[]>;
+    resolveGroup(value: string | GroupRef, options?: {
+        strategy?: EntityResolutionStrategy;
+    }): Promise<GroupRef>;
+    resolveTeacher(value: string | TeacherRef, options?: {
+        strategy?: EntityResolutionStrategy;
+    }): Promise<TeacherRef>;
+    resolveRoom(value: string | RoomRef, options?: {
+        strategy?: EntityResolutionStrategy;
+    }): Promise<RoomRef>;
+    preloadDirectory(options: DirectoryPreloadOptions): Promise<void>;
     /**
      * Resolve an audience id from its exact name by searching and
      * selecting the button whose `value` equals the given name.
      */
-    findAudienceByName(opts: {
-        name: string;
-    }): Promise<Audience | null>;
+    findRoomByName(name: string): Promise<Room | null>;
     /** Fetch the audience's display name from its schedule page. */
-    getAudienceName(audienceId: number): Promise<string | null>;
+    getRoomName(roomId: number): Promise<string | null>;
     /**
      * Fetch detailed info about an audience (building, floor, usage,
      * image URLs for the audience photo, building photo and floor plan).
      */
-    getAudienceInfo(audienceId: number): Promise<AudienceInfo | null>;
-    private fetchAudienceSchedule;
-    getAudienceSchedule(audienceId: number): Promise<Schedule>;
-    getAudienceScheduleForPeriod(opts: {
-        audienceId: number;
-        period: Period;
-    }): Promise<Schedule>;
-    private getCachedAudienceImage;
+    getRoomInfo(roomId: number): Promise<RoomInfo | null>;
+    private fetchRoomSchedule;
+    getRoomSchedule(roomId: number, options?: GetScheduleOptions): Promise<Schedule>;
+    private getCachedRoomImage;
     /** Get the audience photo (audimage). Returns null if missing. */
-    getAudienceImage(audienceId: number): Promise<Buffer | null>;
+    getRoomImage(roomId: number): Promise<Buffer | null>;
     /** Get the building exterior image (blockimage). Returns null if missing. */
-    getAudienceBlockImage(audienceId: number): Promise<Buffer | null>;
+    getRoomBuildingImage(roomId: number): Promise<Buffer | null>;
     /** Get the floor plan image for the audience. Returns null if missing. */
-    getAudienceFloorplan(audienceId: number): Promise<Buffer | null>;
-    searchTeacher(opts: {
-        name: string;
-    }): Promise<{
-        id: number;
-        name: string;
-    }[]>;
+    getRoomFloorPlan(roomId: number): Promise<Buffer | null>;
+    searchTeachers(name: string): Promise<TeacherRef[]>;
     getTeachers(): Promise<{
         id: number;
         name: string;
     }[]>;
     private fetchTeacherSchedule;
-    getTeacherSchedule(teacherId: number): Promise<Schedule>;
-    getTeacherScheduleForPeriod(opts: {
-        teacherId: number;
-        period: Period;
-    }): Promise<Schedule>;
+    getTeacherSchedule(teacherId: number, options?: GetScheduleOptions): Promise<Schedule>;
     getTeacherInfo(teacherId: number): Promise<TeacherInfo | null>;
     /**
-     * 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.
      */
     getTeacherPhoto(teacherId: number): Promise<Buffer | null>;
-    /**
-     * 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.
-     */
-    getTeacherPhotoLazy(teacherId: number): Promise<Buffer | null>;
 }