chuvsu-js 4.1.2 → 4.1.5

package/README.md

@@ -18,6 +18,18 @@ npm install chuvsu-js
 
 ## Быстрый старт
 
+### Проверка расписаний на живых данных
+
+Укажите `TT_EMAIL` и `TT_PASSWORD` в `.env`, затем запустите:
+
+```bash
+pnpm test:live:schedules
+```
+
+По умолчанию проверяются 50 групп. Доступны `--limit=100`, `--all` и
+`--group=КТ-41-24` (аргументы передаются после `--`). Значения авторизации
+скрипт не выводит.
+
 ### Расписание (TtClient)
 
 ```ts

package/dist/tt/client.d.ts

@@ -8,6 +8,7 @@ export declare class TtClient {
     private cache;
     private blobAdapter;
     private loginMode;
+    private timetableContext;
     constructor(opts?: TtClientOptions);
     private get pertt();
     clearCache(category?: keyof CacheConfig): Promise<void>;
@@ -23,6 +24,8 @@ export declare class TtClient {
     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

package/dist/tt/client.js

@@ -1,10 +1,11 @@
 import { HttpClient } from "../common/http.js";
 import { HybridCache } from "../common/cache.js";
-import { AuthError } from "../common/types.js";
-import { parseAudienceButtons, parseAudienceFullSchedule, parseAudienceInfo, parseAudienceName, parseGroupButtons, parseFacultyButtons, parseTeacherButtons, parseFullSchedule, parseTeacherFullSchedule, parseTeacherInfo, parseWebinars, } from "./parse/index.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";
 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 */,
@@ -32,17 +33,13 @@ function formatDate(date) {
     const day = String(date.getDate()).padStart(2, "0");
     return `${year}-${month}-${day}`;
 }
-function getAcademicYearKey(date = new Date()) {
-    const year = date.getFullYear();
-    const start = date.getMonth() >= 8 ? year : year - 1;
-    return `${start}-${start + 1}`;
-}
 export class TtClient {
     http = new HttpClient();
     educationType;
     cache;
     blobAdapter = undefined;
     loginMode = null;
+    timetableContext = null;
     constructor(opts) {
         this.educationType = opts?.educationType ?? 1 /* EducationType.HigherEducation */;
         this.blobAdapter = opts?.blobAdapter;
@@ -83,6 +80,7 @@ export class TtClient {
             throw new AuthError("TT login failed");
         }
         this.loginMode = { type: "credentials", ...opts };
+        this.timetableContext = null;
     }
     async loginAsGuest() {
         const res = await this.http.post(AUTH_URL, { guest: "Войти гостем", hfac: "0", pertt: this.pertt }, false);
@@ -90,6 +88,7 @@ export class TtClient {
             throw new AuthError("TT guest login failed");
         }
         this.loginMode = { type: "guest" };
+        this.timetableContext = null;
     }
     isSessionExpired(body) {
         return body.includes('name="wname"');
@@ -123,9 +122,32 @@ export class TtClient {
         }
         return res;
     }
+    /** Resolve the academic year and active period from tt.chuvsu.ru itself. */
+    async getTimetableContext(pageUrl) {
+        if (this.timetableContext &&
+            Date.now() - this.timetableContext.resolvedAt < TIMETABLE_CONTEXT_TTL_MS) {
+            return this.timetableContext;
+        }
+        const { body } = await this.authGet(pageUrl);
+        const academicYearStartYear = parseAcademicYearFromPage(body);
+        if (academicYearStartYear == null) {
+            throw new ParseError("TT page does not expose the current academic year");
+        }
+        const period = parsePeriodFromPage(body);
+        if (period == null) {
+            throw new ParseError("TT page does not expose the active timetable period");
+        }
+        const context = {
+            academicYearStartYear,
+            period,
+            resolvedAt: Date.now(),
+        };
+        this.timetableContext = context;
+        return context;
+    }
     // --- Schedule ---
-    async fetchSchedule(groupId, period) {
-        const cacheKey = `${groupId}:${period}:${getAcademicYearKey()}`;
+    async fetchSchedule(groupId, period, academicYearStartYear) {
+        const cacheKey = `${groupId}:${period}:${academicYearStartYear}-${academicYearStartYear + 1}`;
         const cached = await this.cache?.get("schedule", cacheKey);
         if (cached)
             return cached;
@@ -141,23 +163,25 @@ export class TtClient {
      */
     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);
+            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, undefined, this.educationType);
+        return new Schedule(groupId, schedules, context.period, this.educationType, undefined, undefined, undefined, context.academicYearStartYear);
     }
     /**
      * Get schedule for a specific period only.
      */
     async getScheduleForPeriod(opts) {
-        const days = await this.fetchSchedule(opts.groupId, opts.period);
+        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);
+        return new Schedule(opts.groupId, schedules, opts.period, this.educationType, undefined, undefined, undefined, context.academicYearStartYear);
     }
     async getWebinars(opts) {
         const date = opts?.date ?? new Date();
@@ -317,8 +341,8 @@ export class TtClient {
             await this.cache?.set("audienceInfo", String(audienceId), info);
         return info;
     }
-    async fetchAudienceSchedule(audienceId, period) {
-        const cacheKey = `audience:${audienceId}:${period}`;
+    async fetchAudienceSchedule(audienceId, period, academicYearStartYear) {
+        const cacheKey = `audience:${audienceId}:${period}:${academicYearStartYear}-${academicYearStartYear + 1}`;
         const cached = await this.cache?.get("schedule", cacheKey);
         if (cached)
             return cached;
@@ -336,20 +360,22 @@ export class TtClient {
     }
     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);
+            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, undefined, this.educationType);
+        return new Schedule(audienceId, schedules, context.period, this.educationType, undefined, undefined, undefined, context.academicYearStartYear);
     }
     async getAudienceScheduleForPeriod(opts) {
-        const days = await this.fetchAudienceSchedule(opts.audienceId, opts.period);
+        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);
+        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) ??
@@ -433,8 +459,8 @@ export class TtClient {
         await this.cache?.set("teachers", "all", data);
         return data;
     }
-    async fetchTeacherSchedule(teacherId, period) {
-        const cacheKey = `teacher:${teacherId}:${period}`;
+    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;
@@ -452,20 +478,22 @@ export class TtClient {
     }
     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);
+            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, undefined, this.educationType, undefined, undefined, true);
+        return new Schedule(teacherId, schedules, context.period, this.educationType, undefined, undefined, true, context.academicYearStartYear);
     }
     async getTeacherScheduleForPeriod(opts) {
-        const days = await this.fetchTeacherSchedule(opts.teacherId, opts.period);
+        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);
+        return new Schedule(opts.teacherId, schedules, opts.period, this.educationType, undefined, undefined, true, context.academicYearStartYear);
     }
     async getTeacherInfo(teacherId) {
         const cached = await this.cache?.get("teacherInfo", String(teacherId));

package/dist/tt/parse/index.d.ts

@@ -1,5 +1,5 @@
 export { parseGroupsString } from "./groups.js";
-export { parseAudienceButtons, parseAudienceName, parseFacultyButtons, parseGroupButtons, parsePeriodFromPage, parseTeacherButtons, } from "./lists.js";
+export { parseAcademicYearFromPage, parseAudienceButtons, parseAudienceName, parseFacultyButtons, parseGroupButtons, parsePeriodFromPage, parseTeacherButtons, } from "./lists.js";
 export { parseFullSchedule } from "./full-schedule.js";
 export { parseAudienceFullSchedule, parseAudienceInfo, } from "./audience.js";
 export { parseTeacherFullSchedule, parseTeacherInfo, } from "./teacher.js";

package/dist/tt/parse/index.js

@@ -1,5 +1,5 @@
 export { parseGroupsString } from "./groups.js";
-export { parseAudienceButtons, parseAudienceName, parseFacultyButtons, parseGroupButtons, parsePeriodFromPage, parseTeacherButtons, } from "./lists.js";
+export { parseAcademicYearFromPage, parseAudienceButtons, parseAudienceName, parseFacultyButtons, parseGroupButtons, parsePeriodFromPage, parseTeacherButtons, } from "./lists.js";
 export { parseFullSchedule } from "./full-schedule.js";
 export { parseAudienceFullSchedule, parseAudienceInfo, } from "./audience.js";
 export { parseTeacherFullSchedule, parseTeacherInfo, } from "./teacher.js";

package/dist/tt/parse/lists.d.ts

@@ -1,6 +1,8 @@
 import { Period } from "../../common/types.js";
 import type { Audience, Faculty, Group } from "../types.js";
 export declare function parsePeriodFromPage(html: string): Period | null;
+/** Parse the start year from labels like "2026/2027 учебный год". */
+export declare function parseAcademicYearFromPage(html: string): number | null;
 export declare function parseGroupButtons(html: string): Group[];
 export declare function parseFacultyButtons(html: string): Faculty[];
 export declare function parseAudienceButtons(html: string): Audience[];

package/dist/tt/parse/lists.js

@@ -6,12 +6,34 @@ const PERIOD_LABELS = {
     "летняя сессия": 4,
 };
 export function parsePeriodFromPage(html) {
+    const doc = parseHtml(html);
+    // Schedule pages expose the active period as the checked radio button.
+    const checked = doc.querySelector('input[name="pertype"][checked]');
+    const checkedValue = Number(checked?.getAttribute("value"));
+    if (checkedValue >= 1 && checkedValue <= 4) {
+        return checkedValue;
+    }
+    // Some pages keep the selected period only in the hidden form field.
+    const hiddenValue = Number(doc.querySelector('#htype')?.getAttribute("value"));
+    if (hiddenValue >= 1 && hiddenValue <= 4) {
+        return hiddenValue;
+    }
+    // Legacy markup used an italic textual marker.
     const match = html.match(/идет\s+(.+?)\s*</i);
     if (!match)
         return null;
     const label = match[1].toLowerCase().trim();
     return PERIOD_LABELS[label] ?? null;
 }
+/** Parse the start year from labels like "2026/2027 учебный год". */
+export function parseAcademicYearFromPage(html) {
+    const match = html.match(/(\d{4})\s*[\/-]\s*(\d{4})\s*учебный\s+год/i);
+    if (!match)
+        return null;
+    const start = Number(match[1]);
+    const end = Number(match[2]);
+    return end === start + 1 ? start : null;
+}
 export function parseGroupButtons(html) {
     const doc = parseHtml(html);
     const groups = [];

package/dist/tt/schedule.d.ts

@@ -11,8 +11,10 @@ export declare class Schedule {
     readonly holidays: Holiday[];
     /** Government decree day-off transfers (Постановление Правительства). */
     readonly holidayTransfers: HolidayTransfer[];
+    /** Academic year represented by this schedule (e.g. 2026 for 2026/2027). */
+    readonly academicYearStartYear: number;
     private _period?;
-    constructor(groupId: number, scheduleMap: Map<number, FullScheduleDay[]>, period?: Period, educationType?: EducationType, holidays?: Holiday[] | null, holidayTransfers?: HolidayTransfer[], isTeacherSchedule?: boolean);
+    constructor(groupId: number, scheduleMap: Map<number, FullScheduleDay[]>, period?: Period, educationType?: EducationType, holidays?: Holiday[] | null, holidayTransfers?: HolidayTransfer[], isTeacherSchedule?: boolean, academicYearStartYear?: number);
     /** Current (or fixed) period for this schedule. */
     get period(): Period;
     /** Days for the current period. */
@@ -21,6 +23,7 @@ export declare class Schedule {
     get periods(): Period[];
     /** Get days for a specific period. */
     getDays(period: Period): FullScheduleDay[];
+    private getSemesterYear;
     private getSlotsForWeekday;
     private getDateForWeekday;
     private isInCurrentAcademicYear;

package/dist/tt/schedule.js

@@ -9,8 +9,10 @@ export class Schedule {
     holidays;
     /** Government decree day-off transfers (Постановление Правительства). */
     holidayTransfers;
+    /** Academic year represented by this schedule (e.g. 2026 for 2026/2027). */
+    academicYearStartYear;
     _period;
-    constructor(groupId, scheduleMap, period, educationType, holidays, holidayTransfers, isTeacherSchedule) {
+    constructor(groupId, scheduleMap, period, educationType, holidays, holidayTransfers, isTeacherSchedule, academicYearStartYear) {
         this.groupId = groupId;
         this.scheduleMap = scheduleMap;
         this.educationType = educationType ?? 1 /* EducationType.HigherEducation */;
@@ -18,6 +20,14 @@ export class Schedule {
         this._period = period;
         this.holidays = holidays ?? RUSSIAN_HOLIDAYS;
         this.holidayTransfers = holidayTransfers ?? [];
+        if (academicYearStartYear != null) {
+            this.academicYearStartYear = academicYearStartYear;
+        }
+        else {
+            const now = new Date();
+            this.academicYearStartYear =
+                now.getMonth() >= 8 ? now.getFullYear() : now.getFullYear() - 1;
+        }
     }
     /** Current (or fixed) period for this schedule. */
     get period() {
@@ -35,6 +45,14 @@ export class Schedule {
     getDays(period) {
         return this.scheduleMap.get(period) ?? [];
     }
+    getSemesterYear(period) {
+        const semester = isSessionPeriod(period)
+            ? getAdjacentSemester(period)
+            : period;
+        return semester === 1 /* Period.FallSemester */
+            ? this.academicYearStartYear
+            : this.academicYearStartYear + 1;
+    }
     // --- Semester helpers (weekday-based) ---
     getSlotsForWeekday(weekday, days, opts) {
         const dayName = getWeekdayName(weekday);
@@ -45,7 +63,7 @@ export class Schedule {
     }
     getDateForWeekday(weekday, period, week) {
         if (week != null) {
-            const startMonday = getMonday(getSemesterStart({ period }));
+            const startMonday = getMonday(getSemesterStart({ period, year: this.getSemesterYear(period) }));
             const date = new Date(startMonday);
             date.setDate(startMonday.getDate() +
                 (week - 1) * 7 +
@@ -61,10 +79,7 @@ export class Schedule {
         return date;
     }
     isInCurrentAcademicYear(date) {
-        const now = new Date();
-        const startYear = now.getMonth() >= 8
-            ? now.getFullYear()
-            : now.getFullYear() - 1;
+        const startYear = this.academicYearStartYear;
         const start = new Date(startYear, 8, 1);
         const end = new Date(startYear + 1, 7, 31, 23, 59, 59, 999);
         return date >= start && date <= end;
@@ -115,8 +130,12 @@ export class Schedule {
             : period;
         const semesterDays = this.getDays(semesterPeriod);
         if (semesterDays.length > 0) {
-            const week = getWeekNumber({ period: semesterPeriod, date });
-            if (week >= 0 && week <= 17) {
+            const week = getWeekNumber({
+                period: semesterPeriod,
+                year: this.getSemesterYear(semesterPeriod),
+                date,
+            });
+            if (week >= 1 && week <= 17) {
                 const weekday = date.getDay();
                 const slots = this.getSlotsForWeekday(weekday, semesterDays, {
                     subgroup: opts?.subgroup,
@@ -140,6 +159,7 @@ export class Schedule {
         if (week != null && !isSessionPeriod(period)) {
             const semesterWeeks = getSemesterWeeks({
                 period,
+                year: this.getSemesterYear(period),
                 weekCount: week,
             });
             const weekData = semesterWeeks.find((w) => w.week === week);
@@ -182,12 +202,32 @@ export class Schedule {
         return null;
     }
     getWeekNumber(date) {
-        return getWeekNumber({ period: this.period, date });
+        const period = isSessionPeriod(this.period)
+            ? getAdjacentSemester(this.period)
+            : this.period;
+        return getWeekNumber({
+            period,
+            year: this.getSemesterYear(period),
+            date,
+        });
     }
     getSemesterWeeks(weekCount) {
-        return getSemesterWeeks({ period: this.period, weekCount });
+        const period = isSessionPeriod(this.period)
+            ? getAdjacentSemester(this.period)
+            : this.period;
+        return getSemesterWeeks({
+            period,
+            year: this.getSemesterYear(period),
+            weekCount,
+        });
     }
     getSemesterStart() {
-        return getSemesterStart({ period: this.period });
+        const period = isSessionPeriod(this.period)
+            ? getAdjacentSemester(this.period)
+            : this.period;
+        return getSemesterStart({
+            period,
+            year: this.getSemesterYear(period),
+        });
     }
 }

package/dist/tt/utils/semester.d.ts

@@ -14,7 +14,7 @@ export declare function getSemesterStart(opts: {
 }): Date;
 /**
  * All weeks in a semester with their start/end dates.
- * Week 0 starts from the semester start date.
+ * Week 1 is the calendar week containing the semester start date.
  */
 export declare function getSemesterWeeks(opts: {
     period: Period;

package/dist/tt/utils/semester.js

@@ -36,16 +36,16 @@ export function getSemesterStart(opts) {
 }
 /**
  * All weeks in a semester with their start/end dates.
- * Week 0 starts from the semester start date.
+ * Week 1 is the calendar week containing the semester start date.
  */
 export function getSemesterWeeks(opts) {
     const weekCount = opts.weekCount ?? 17;
     const semesterStart = getSemesterStart(opts);
     const startMonday = getMonday(semesterStart);
     const weeks = [];
-    for (let i = 0; i <= weekCount; i++) {
+    for (let i = 1; i <= weekCount; i++) {
         const start = new Date(startMonday);
-        start.setDate(startMonday.getDate() + i * 7);
+        start.setDate(startMonday.getDate() + (i - 1) * 7);
         const end = new Date(start);
         end.setDate(start.getDate() + 6);
         end.setHours(23, 59, 59, 999);
@@ -60,5 +60,5 @@ export function getWeekNumber(opts) {
     const startMonday = getMonday(semesterStart);
     const targetMonday = getMonday(date);
     const diff = targetMonday.getTime() - startMonday.getTime();
-    return Math.floor(diff / (7 * 24 * 60 * 60 * 1000));
+    return Math.floor(diff / (7 * 24 * 60 * 60 * 1000)) + 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chuvsu-js",
-  "version": "4.1.2",
+  "version": "4.1.5",
   "description": "Node.js library for ChuvSU student portal (lk.chuvsu.ru) and schedule (tt.chuvsu.ru)",
   "type": "module",
   "main": "dist/index.js",
@@ -43,6 +43,7 @@
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "pnpm clean && tsc",
-    "test": "pnpm build && node --test"
+    "test": "pnpm build && node --test",
+    "test:live:schedules": "pnpm build && node --env-file=.env examples/testSchedules.mjs"
   }
 }