zdu-student-api 1.1.4 → 1.1.6

package/README.md

@@ -4,17 +4,28 @@ API для **Житомирського державного університ
 
 Бібліотека надає програмний доступ до відкритих сервісів університету, зокрема:
 
-* 📅 розклад занять студентів / викладачів / аудиторій
-* 🚪 зайняті / вільні аудиторії
-* 🏫 списки аудиторій
-* 👥 списки груп
-* 👨‍🏫 списки викладачів
+- 📅 розклад занять студентів / викладачів / аудиторій
+- 🚪 зайняті / вільні аудиторії
+- 🏫 списки аудиторій
+- 👥 списки груп
+- 👨‍🏫 списки викладачів
+
+#### BETA API:
+
+- 🔑 Авторизація в кабінеті студента
+- 📝 Отримання анкетних данних студента
+- 📚 Отримання дисциплін студента
+- 📊 Отримання оцінок з окремого предмета
+- 👨‍💻 Клас кабінету для спрощеного керування функціями, який включає:
+-   - 🔐 Авторизація
+-   - 📂 Отримання всіх данних
+-   - ✅ Перевірка сесії
+-   - 📈 Отримання всіх оцінок з усіх дисциплін
 
 ### 🔮 У планах
 
-* API кабінету студента
-* оцінки
-* рейтинги
+- стабільне API кабінету студента
+- Отримання історії оцінок з усіх предметів
 
 > ⚠️ Проєкт **не є офіційним** API університету.
 
@@ -42,11 +53,11 @@ schedule.rosText = true;
 schedule.allStreamComponents = true;
 
 try {
-  const sc = await schedule.getSchedule();
-  console.log('Розклад:', sc);
+    const sc = await schedule.getSchedule();
+    console.log('Розклад:', sc);
 } catch (err: any) {
-  console.error(err.message);
-  console.error(scheduleErrors[JSON.parse(err.message).errorcode]);
+    console.error(err.message);
+    console.error(scheduleErrors[JSON.parse(err.message).errorcode]);
 }
 ```
 

package/dist/audience.d.ts

@@ -1,68 +1,68 @@
-import { AudienceRoom, Blocks } from './types';
+import { AudienceRoom, Blocks } from './types.js';
 /**
  * Клас розкладу
  * @category Audience
  */
 export declare class Audience {
     /**
-    * Назва корпусу
-    */
+     * Назва корпусу
+     */
     blockName?: Blocks;
     /**
-    * Номер пари
-    */
+     * Номер пари
+     */
     lesson: number;
     /**
-    * Тип аудиторій який є в даному корпусі
-    */
+     * Тип аудиторій який є в даному корпусі
+     */
     roomType?: string;
     /**
-    * Кількість місць не менше ніж
-    */
+     * Кількість місць не менше ніж
+     */
     size_min?: number;
     /**
-    * Кількість місць не більше ніж
-    */
+     * Кількість місць не більше ніж
+     */
     size_max?: number;
     /**
-    * Дата аудиторії
-    */
+     * Дата аудиторії
+     */
     roomsDate: Date;
     /**
-    * Наявніть доп. обладнання типу 1, 2, 3, 4, 5, 6, 7, 8
-    */
+     * Наявніть доп. обладнання типу 1, 2, 3, 4, 5, 6, 7, 8
+     */
     dops: number[];
     /**
-    * Повертає список аудиторій
-    *
-    * @throws {Error} Якщо виникають проблеми з запитом або дані некоректні.
-    *
-    * @example
-    * ```ts
-    * import { Audience } from "./audience.ts";
-    * const audience = new Audience();
-    * try {
-    *   const audiences = await audience.getAudience();
-    *   console.log("Аудиторії:", audiences); // Поверне список аудиторій
-    * } catch (err: any) {
-    *   console.error(err.message);
-    * }
-    * ```
-    *
-    * @remarks
-    * У `err.message` може повертатися простий текст помилки,
-    * або об’єкт у форматі:
-    * ```JSON
-    * {
-    *   "error_message": "Текст помилки",
-    *   "errorcode": "Код помилки"
-    * }
-    * ```
-    *
-    * Де:
-    * - `error_message` - текст помилки відповідно до {@link scheduleErrors}
-    * - `errorcode` - код помилки відповідно до {@link scheduleErrors}
-    */
+     * Повертає список аудиторій
+     *
+     * @throws {Error} Якщо виникають проблеми з запитом або дані некоректні.
+     *
+     * @example
+     * ```ts
+     * import { Audience } from "./audience.ts";
+     * const audience = new Audience();
+     * try {
+     *   const audiences = await audience.getAudience();
+     *   console.log("Аудиторії:", audiences); // Поверне список аудиторій
+     * } catch (err: any) {
+     *   console.error(err.message);
+     * }
+     * ```
+     *
+     * @remarks
+     * У `err.message` може повертатися простий текст помилки,
+     * або об’єкт у форматі:
+     * ```JSON
+     * {
+     *   "error_message": "Текст помилки",
+     *   "errorcode": "Код помилки"
+     * }
+     * ```
+     *
+     * Де:
+     * - `error_message` - текст помилки відповідно до {@link scheduleErrors}
+     * - `errorcode` - код помилки відповідно до {@link scheduleErrors}
+     */
     getAudience(): Promise<AudienceRoom[]>;
     private encodeCP1251;
 }

package/dist/audience.js

@@ -6,72 +6,72 @@ import fetch from 'cross-fetch';
  */
 export class Audience {
     /**
-    * Назва корпусу
-    */
+     * Назва корпусу
+     */
     blockName;
     /**
-    * Номер пари
-    */
+     * Номер пари
+     */
     lesson = 1;
     /**
-    * Тип аудиторій який є в даному корпусі
-    */
+     * Тип аудиторій який є в даному корпусі
+     */
     roomType;
     /**
-    * Кількість місць не менше ніж
-    */
+     * Кількість місць не менше ніж
+     */
     size_min;
     /**
-    * Кількість місць не більше ніж
-    */
+     * Кількість місць не більше ніж
+     */
     size_max;
     /**
-    * Дата аудиторії
-    */
+     * Дата аудиторії
+     */
     roomsDate = new Date();
     /**
-    * Наявніть доп. обладнання типу 1, 2, 3, 4, 5, 6, 7, 8
-    */
+     * Наявніть доп. обладнання типу 1, 2, 3, 4, 5, 6, 7, 8
+     */
     dops = [];
     /**
-    * Повертає список аудиторій
-    *
-    * @throws {Error} Якщо виникають проблеми з запитом або дані некоректні.
-    *
-    * @example
-    * ```ts
-    * import { Audience } from "./audience.ts";
-    * const audience = new Audience();
-    * try {
-    *   const audiences = await audience.getAudience();
-    *   console.log("Аудиторії:", audiences); // Поверне список аудиторій
-    * } catch (err: any) {
-    *   console.error(err.message);
-    * }
-    * ```
-    *
-    * @remarks
-    * У `err.message` може повертатися простий текст помилки,
-    * або об’єкт у форматі:
-    * ```JSON
-    * {
-    *   "error_message": "Текст помилки",
-    *   "errorcode": "Код помилки"
-    * }
-    * ```
-    *
-    * Де:
-    * - `error_message` - текст помилки відповідно до {@link scheduleErrors}
-    * - `errorcode` - код помилки відповідно до {@link scheduleErrors}
-    */
+     * Повертає список аудиторій
+     *
+     * @throws {Error} Якщо виникають проблеми з запитом або дані некоректні.
+     *
+     * @example
+     * ```ts
+     * import { Audience } from "./audience.ts";
+     * const audience = new Audience();
+     * try {
+     *   const audiences = await audience.getAudience();
+     *   console.log("Аудиторії:", audiences); // Поверне список аудиторій
+     * } catch (err: any) {
+     *   console.error(err.message);
+     * }
+     * ```
+     *
+     * @remarks
+     * У `err.message` може повертатися простий текст помилки,
+     * або об’єкт у форматі:
+     * ```JSON
+     * {
+     *   "error_message": "Текст помилки",
+     *   "errorcode": "Код помилки"
+     * }
+     * ```
+     *
+     * Де:
+     * - `error_message` - текст помилки відповідно до {@link scheduleErrors}
+     * - `errorcode` - код помилки відповідно до {@link scheduleErrors}
+     */
     async getAudience() {
         const date = this.roomsDate.toLocaleDateString('uk-UA', {
             day: '2-digit',
             month: '2-digit',
-            year: 'numeric'
+            year: 'numeric',
         });
         let dops = '';
-        this.dops.forEach(dop => {
+        this.dops.forEach((dop) => {
             dops += `&dop_${dop}=yes`;
         });
         const response = await fetch(`https://dekanat.zu.edu.ua/cgi-bin/timetable_export.cgi?req_type=free_rooms_list&&block_name=${this.blockName !== undefined ? this.encodeCP1251(this.blockName) : ''}&size_min=${this.size_min !== undefined ? this.size_min : ''}&size_max=${this.size_max !== undefined ? this.size_max : ''}&room_type=${this.roomType !== undefined ? this.encodeCP1251(this.roomType) : ''}&begin_date=${date}&lesson=${this.lesson}${dops}&req_format=json&coding_mode=UTF8&bs=%D1%F4%EE%F0%EC%F3%E2%E0%F2%E8+%E7%E0%EF%E8%F2`);
@@ -79,12 +79,14 @@ export class Audience {
             throw new Error(`HTTP error ${response.status}: ${response.statusText}`);
         const data = await response.json();
         if (data.psrozklad_export.code !== '0') {
-            throw new Error(JSON.stringify(data.psrozklad_export.error) || "Unknown error");
+            throw new Error(JSON.stringify(data.psrozklad_export.error) || 'Unknown error');
         }
         return data.psrozklad_export.free_rooms.rooms;
     }
     encodeCP1251(str) {
         const buf = iconv.encode(str, 'win1251');
-        return Array.from(buf).map(b => '%' + b.toString(16).toUpperCase().padStart(2, '0')).join('');
+        return Array.from(buf)
+            .map((b) => '%' + b.toString(16).toUpperCase().padStart(2, '0'))
+            .join('');
     }
 }

package/dist/cabinet/cabinet.d.ts

@@ -0,0 +1,79 @@
+import { Discipline, Disciplines, Data, Scores } from './types.js';
+/**
+ * Клас кабінету студента
+ * @category Cabinet
+ */
+export declare class Cabinet {
+    /**
+     * Прізвище користувача
+     */
+    login: string;
+    /**
+     * Пароль від кабінету студента
+     */
+    password: string;
+    /**
+     * ID сесії користувача
+     */
+    sesID?: string;
+    /**
+     * GUID сесії з cookie
+     */
+    sessGUID?: string;
+    /**
+     * Семестр для пошуку оцінок (0 - перший, 1 - другий)
+     */
+    semester: 0 | 1;
+    /**
+     * Список дисциплін {@link Discipline}
+     */
+    disciplines: Discipline[];
+    /**
+     * Данні студента {@link Data}
+     */
+    data?: Data;
+    /**
+     * Оціки з усіх предметів {@link Scores}
+     */
+    allScores?: Scores[];
+    /**
+     * Конструктор
+     * @param login - Прізвище користувача
+     * @param password - Пароль
+     */
+    constructor(login: string, password: string);
+    /**
+     * Авторизація
+     */
+    auth(login?: string, password?: string): Promise<boolean>;
+    /**
+     * Базове значення семестру
+     */
+    private setSemester;
+    /**
+     * Отримання всіх данних
+     */
+    loadData(): Promise<boolean>;
+    /**
+     * Відновлення сесії
+     */
+    setSession(sesID: string, sessGUID: string): Promise<boolean>;
+    /**
+     * Перевірка валідності сесії
+     */
+    isValidSession(): Promise<boolean>;
+    /**
+     * Отримати дисципліни поточного семестру студента
+     * @returns Масив дисциплін {@link Disciplines}
+     */
+    getDisciplines(): Promise<Disciplines>;
+    /**
+     * Отримати анкетні данні студента
+     * @returns Об'єкт {@link ata}
+     */
+    getData(): Promise<Data>;
+    /**
+     * Отримати оцінки з всіх предметів
+     */
+    getAllScores(semester?: 0 | 1): Promise<Scores[]>;
+}

package/dist/cabinet/cabinet.js

@@ -0,0 +1,162 @@
+import { getSesId } from './sesId.js';
+import { isValidSession } from './validSession.js';
+import { getСurrentDisciplines } from './disciplines.js';
+import { getData } from './data.js';
+import { getScores } from './scores.js';
+/**
+ * Клас кабінету студента
+ * @category Cabinet
+ */
+export class Cabinet {
+    /**
+     * Прізвище користувача
+     */
+    login;
+    /**
+     * Пароль від кабінету студента
+     */
+    password;
+    /**
+     * ID сесії користувача
+     */
+    sesID;
+    /**
+     * GUID сесії з cookie
+     */
+    sessGUID;
+    /**
+     * Семестр для пошуку оцінок (0 - перший, 1 - другий)
+     */
+    semester = 0;
+    /**
+     * Список дисциплін {@link Discipline}
+     */
+    disciplines = [];
+    /**
+     * Данні студента {@link Data}
+     */
+    data;
+    /**
+     * Оціки з усіх предметів {@link Scores}
+     */
+    allScores;
+    /**
+     * Конструктор
+     * @param login - Прізвище користувача
+     * @param password - Пароль
+     */
+    constructor(login, password) {
+        this.login = login;
+        this.password = password;
+    }
+    /**
+     * Авторизація
+     */
+    async auth(login, password) {
+        const accountData = await getSesId(login ?? this.login, password ?? this.password);
+        this.setSemester();
+        if (accountData.ok) {
+            this.sesID = accountData.sesID;
+            this.sessGUID = accountData.sessGUID;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Базове значення семестру
+     */
+    setSemester() {
+        const year = new Date().getFullYear();
+        const febStart = new Date(year, 1, 1); // лютий = 1
+        const sepStart = new Date(year, 8, 1); // вересень = 8
+        const date = new Date();
+        if (!(date < febStart || date >= sepStart)) {
+            this.semester = 1;
+        }
+    }
+    /**
+     * Отримання всіх данних
+     */
+    async loadData() {
+        const one = (await this.getDisciplines()).ok;
+        const two = (await this.getData()).ok;
+        const three = (await this.getAllScores()).length > 0;
+        return one && two && three;
+    }
+    /**
+     * Відновлення сесії
+     */
+    async setSession(sesID, sessGUID) {
+        this.setSemester();
+        const ses = await isValidSession(sesID, sessGUID);
+        if (ses) {
+            this.sesID = sesID;
+            this.sessGUID = sessGUID;
+        }
+        return ses;
+    }
+    /**
+     * Перевірка валідності сесії
+     */
+    async isValidSession() {
+        if (!this.sesID || !this.sessGUID)
+            return false;
+        return await isValidSession(this.sesID, this.sessGUID);
+    }
+    /**
+     * Отримати дисципліни поточного семестру студента
+     * @returns Масив дисциплін {@link Disciplines}
+     */
+    async getDisciplines() {
+        if (!this.sesID || !this.sessGUID)
+            return { ok: false, disciplines: [] };
+        try {
+            const disciplinesData = await getСurrentDisciplines(this.sesID, this.sessGUID);
+            if (disciplinesData.ok) {
+                this.disciplines = disciplinesData.disciplines;
+            }
+            return disciplinesData;
+        }
+        catch {
+            return { ok: false, disciplines: [] };
+        }
+    }
+    /**
+     * Отримати анкетні данні студента
+     * @returns Об'єкт {@link ata}
+     */
+    async getData() {
+        if (!this.sesID || !this.sessGUID)
+            return { ok: false };
+        try {
+            const data = await getData(this.sesID, this.sessGUID);
+            if (data.ok) {
+                this.data = data;
+            }
+            return data;
+        }
+        catch {
+            return { ok: false };
+        }
+    }
+    /**
+     * Отримати оцінки з всіх предметів
+     */
+    async getAllScores(semester) {
+        if (!this.sesID || !this.sessGUID)
+            return [];
+        if (!this.disciplines?.length)
+            return [];
+        const targetSemester = semester ?? this.semester;
+        try {
+            const scorePromises = this.disciplines.map((discipline) => getScores(this.sesID, this.sessGUID, discipline.prId, targetSemester));
+            const results = await Promise.all(scorePromises);
+            const allScores = results.filter((scores) => scores.ok);
+            this.allScores = allScores;
+            return allScores;
+        }
+        catch {
+            return [];
+        }
+    }
+}

package/dist/cabinet/data.d.ts

@@ -0,0 +1,37 @@
+import { Data } from './types.js';
+/**
+ * Отримати анкетні дані студента
+ * @category Cabinet
+ * @param sesId - ID сесії користувача
+ * @param sessGUID - GUID сесії з cookie
+ * @throws {Error} Якщо виникають проблеми з запитом або дані некоректні.
+ * @example
+ * ```typescript
+ * const data = await getData(sesId, sessGUID);
+ * // {
+ * //   ok: true,
+ * //   fullName: 'Іванов Іван Іванович',
+ * //   lastName: 'Іванов',
+ * //   firstName: 'Іван',
+ * //   middleName: 'Іванович',
+ * //   birthDate: 'хх.хх.хххх',
+ * //   gender: 'Чол',
+ * //   country: 'УКРАЇНА',
+ * //   email: 'student@example.com',
+ * //   phones: ['+380(99)-123-45-67'],
+ * //   faculty: 'Фізико-математичний факультет',
+ * //   specialty: 'Середня освіта',
+ * //   degree: 'бакалавр',
+ * //   group: '23Бд-СОінф',
+ * //   studyForm: 'Денна',
+ * //   paymentForm: 'Держ.замовлення',
+ * //   enrollmentOrder: 'ххх-К(ОС)',
+ * //   enrollmentDate: 'хх.хх.2024',
+ * //   studyDuration: '4 роки',
+ * //   graduationDate: 'хх.хх.2028'
+ * //   ...інші
+ * // }
+ * ```
+ * @returns Об'єкт з запарсеними даними {@link Data}
+ */
+export declare function getData(sesId: string, sessGUID: string): Promise<Data>;

package/dist/cabinet/data.js

@@ -0,0 +1,69 @@
+import fetch from 'cross-fetch';
+import iconv from 'iconv-lite';
+import { parseDataPageN3, parseDataPageN31 } from './parsers.js';
+import { generateCookieString, isLoginPage } from './utils.js';
+/**
+ * Отримати анкетні дані студента
+ * @category Cabinet
+ * @param sesId - ID сесії користувача
+ * @param sessGUID - GUID сесії з cookie
+ * @throws {Error} Якщо виникають проблеми з запитом або дані некоректні.
+ * @example
+ * ```typescript
+ * const data = await getData(sesId, sessGUID);
+ * // {
+ * //   ok: true,
+ * //   fullName: 'Іванов Іван Іванович',
+ * //   lastName: 'Іванов',
+ * //   firstName: 'Іван',
+ * //   middleName: 'Іванович',
+ * //   birthDate: 'хх.хх.хххх',
+ * //   gender: 'Чол',
+ * //   country: 'УКРАЇНА',
+ * //   email: 'student@example.com',
+ * //   phones: ['+380(99)-123-45-67'],
+ * //   faculty: 'Фізико-математичний факультет',
+ * //   specialty: 'Середня освіта',
+ * //   degree: 'бакалавр',
+ * //   group: '23Бд-СОінф',
+ * //   studyForm: 'Денна',
+ * //   paymentForm: 'Держ.замовлення',
+ * //   enrollmentOrder: 'ххх-К(ОС)',
+ * //   enrollmentDate: 'хх.хх.2024',
+ * //   studyDuration: '4 роки',
+ * //   graduationDate: 'хх.хх.2028'
+ * //   ...інші
+ * // }
+ * ```
+ * @returns Об'єкт з запарсеними даними {@link Data}
+ */
+export async function getData(sesId, sessGUID) {
+    try {
+        const result = { ok: false };
+        const cookieString = generateCookieString(sessGUID);
+        const response1 = await fetch(`https://dekanat.zu.edu.ua/cgi-bin/classman.cgi?n=31&sesID=${sesId}`, { headers: { Cookie: cookieString } });
+        const buffer1 = await response1.arrayBuffer();
+        const html1 = iconv.decode(Buffer.from(buffer1), 'windows-1251');
+        if (isLoginPage(html1))
+            return { ok: false };
+        const data1 = parseDataPageN31(html1);
+        Object.assign(result, data1);
+        const response2 = await fetch(`https://dekanat.zu.edu.ua/cgi-bin/classman.cgi?n=3&sesID=${sesId}`, {
+            headers: {
+                Cookie: cookieString,
+            },
+        });
+        const buffer2 = await response2.arrayBuffer();
+        const html2 = iconv.decode(Buffer.from(buffer2), 'windows-1251');
+        if (!isLoginPage(html2)) {
+            const data2 = parseDataPageN3(html2);
+            Object.assign(result, data2);
+        }
+        result.ok = true;
+        return result;
+    }
+    catch (e) {
+        console.error('Error in getData:', e);
+        throw e;
+    }
+}

package/dist/cabinet/disciplines.d.ts

@@ -0,0 +1,19 @@
+import { Disciplines } from './types.js';
+/**
+ * Отримати всі дисципліни студента
+ * @category Cabinet
+ * @param sesId - ID сесії користувача
+ * @param sessGUID - GUID сесії з cookie
+ * @throws {Error} Якщо виникають проблеми з запитом або дані некоректні.
+ * @returns Масив дисциплін {@link Disciplines}
+ */
+export declare function getDisciplines(sesId: string, sessGUID: string): Promise<Disciplines>;
+/**
+ * Отримати поточні дисципліни студента
+ * @category Cabinet
+ * @param sesId - ID сесії користувача
+ * @param sessGUID - GUID сесії з cookie
+ * @throws {Error} Якщо виникають проблеми з запитом або дані некоректні.
+ * @returns Масив дисциплін {@link Disciplines}
+ */
+export declare function getСurrentDisciplines(sesId: string, sessGUID: string): Promise<Disciplines>;