zdu-student-api 1.1.5 → 1.1.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NIKITA KHORECHKO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,19 +2,55 @@
 
 API для **Житомирського державного університету імені Івана Франка**.
 
+### СТАБІЛЬНЕ API:
+
 Бібліотека надає програмний доступ до відкритих сервісів університету, зокрема:
 
-* 📅 розклад занять студентів / викладачів / аудиторій
-* 🚪 зайняті / вільні аудиторії
-* 🏫 списки аудиторій
-* 👥 списки груп
-* 👨‍🏫 списки викладачів
+- 📅 розклад занять студентів / викладачів / аудиторій
+- 🚪 зайняті / вільні аудиторії
+- 🏫 списки аудиторій
+- 👥 списки груп
+- 👨‍🏫 списки викладачів
+- 🎯 TypeScript підтримка з повною типізацією
+- 📱 Сумісність з Node.js та браузерними середовищами
+
+### BETA API:
+
+#### 📚 Кабінет студента (CabinetStudent)
+
+- 🔐 Авторизація в кабінеті студента
+- 📝 Отримання анкетних даних студента (ПІБ, дата народження, стать, контакти, факультет, спеціальність, група, форма навчання)
+- 📖 Отримання дисциплін поточного семестру
+- 📊 Отримання оцінок з окремого предмета (з деталізацією по заняттях, пропускам та фінальною оцінкою)
+- 📈 Отримання оцінок з усіх дисциплін одночасно
+- 🎓 Отримання оцінок за конкретний семестр (1 або 2)
+- 🆔 Отримання ID студента в системі оцінювання
+- 💾 Відновлення попередньої сесії без повторної авторизації
+- ✅ Перевірка валідності поточної сесії
+- 🔄 Автоматичне визначення поточного семестру
+- 📦 Масове завантаження всіх даних (анкетні дані + дисципліни + оцінки)
+- 📅 Інформація про розклад занять для кожної дисципліни (викладач, дата, час, тип заняття)
+
+#### 👨‍🏫 Кабінет викладача (CabinetTeacher)
+
+- 🔐 Авторизація в кабінеті викладача
+- 📝 Отримання анкетних даних викладача (ПІБ, кафедра, години роботи, навантаження)
+- 👥 Отримання списку всіх академічних груп викладача
+- 📊 Деталізована інформація про кожну групу (назва, курс, семестр, спеціальність, факультет)
+- 🔗 URL-посилання на журнали академічних груп
+- 💼 Інформація про навчальне навантаження (години за штатом, за сумісництвом, загальне)
+- 📆 Тривалість роботи в навчальному році
+- 💾 Відновлення попередньої сесії без повторної авторизації
+- ✅ Перевірка валідності поточної сесії
+- 📦 Масове завантаження всіх даних (анкетні дані + академічні групи)
 
 ### 🔮 У планах
 
-* API кабінету студента
-* оцінки
-* рейтинги
+- стабільне API кабінету студента
+- стабільне API кабінету викладача
+- Отримання історії оцінок з усіх предметів
+- Отримання айді всіх доступних студентів для окремого викладача
+- Отримання всіх оцінок через кабінет викладача
 
 > ⚠️ Проєкт **не є офіційним** API університету.
 
@@ -26,6 +62,12 @@ API для **Житомирського державного університ
 npm install zdu-student-api
 ```
 
+або
+
+```bash
+pnpm install zdu-student-api
+```
+
 ---
 
 ## Базове використання
@@ -42,11 +84,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]);
 }
 ```
 
@@ -137,16 +179,198 @@ console.log(dops);
 
 ---
 
-### Кабінет студента (WIP)
+## Кабінет студента
+
+### Базове використання
+
+```ts
+import { CabinetStudent } from 'zdu-student-api';
+
+const cabinet = new CabinetStudent('ПРІЗВИЩЕ', 'ПАРОЛЬ');
+
+// Авторизація
+const authSuccess = await cabinet.auth();
+if (authSuccess) {
+    console.log('Авторизовано успішно!');
+    console.log('Session ID:', cabinet.sesID);
+}
+```
+
+---
+
+### Отримання всіх даних студента
+
+```ts
+const cabinet = new CabinetStudent('ПРІЗВИЩЕ', 'ПАРОЛЬ');
+await cabinet.auth();
+
+// Завантажити всі дані (анкетні дані, дисципліни, оцінки)
+await cabinet.loadData();
+
+console.log('Дані студента:', cabinet.data);
+console.log('Дисципліни:', cabinet.disciplines);
+console.log('Оцінки:', cabinet.allScores);
+```
+
+---
+
+### Робота з дисциплінами та оцінками
+
+```ts
+const cabinet = new CabinetStudent('ПРІЗВИЩЕ', 'ПАРОЛЬ');
+await cabinet.auth();
+
+// Отримати дисципліни поточного семестру
+const disciplines = await cabinet.getDisciplines();
+console.log('Дисципліни:', disciplines);
+
+// Отримати оцінки з усіх дисциплін
+const allScores = await cabinet.getAllScores();
+console.log('Всі оцінки:', allScores);
+
+// Отримати оцінки за конкретний семестр
+const firstSemesterScores = await cabinet.getAllScores(1);
+const secondSemesterScores = await cabinet.getAllScores(2);
+```
+
+---
+
+### Відновлення сесії
+
+```ts
+const cabinet = new CabinetStudent('ПРІЗВИЩЕ', 'ПАРОЛЬ');
+
+// Відновити попередню сесію
+const sesID = 'YOUR_SESSION_ID';
+const sessGUID = 'YOUR_SESSION_GUID';
+
+// Сесія активна тільки 24 години і стає застарілою як тільки відбувається нова авторизація викладача в кабінеті
+const sessionValid = await cabinet.setSession(sesID, sessGUID);
+if (sessionValid) {
+    console.log('Сесію відновлено!');
+    await cabinet.loadData();
+}
+```
+
+---
+
+### Перевірка валідності сесії
+
+```ts
+const cabinet = new CabinetStudent('ПРІЗВИЩЕ', 'ПАРОЛЬ');
+await cabinet.auth();
+
+// Перевірити чи сесія ще дійсна
+const isValid = await cabinet.isValidSession();
+console.log('Сесія дійсна:', isValid);
+```
+
+---
+
+### Отримання ID студента
+
+```ts
+const cabinet = new CabinetStudent('ПРІЗВИЩЕ', 'ПАРОЛЬ');
+await cabinet.auth();
+
+const studentId = await cabinet.getId();
+console.log('ID студента:', studentId);
+```
+
+---
+
+## Кабінет викладача
+
+### Базове використання
 
 ```ts
-import { getSesId } from 'zdu-student-api';
+import { CabinetTeacher } from 'zdu-student-api';
+
+const cabinet = new CabinetTeacher('ЛОГІН', 'ПАРОЛЬ');
 
-const sessionId = await getSesId('LOGIN', 'PASSWORD');
-console.log(sessionId);
+// Авторизація
+const authSuccess = await cabinet.auth();
+if (authSuccess) {
+    console.log('Авторизовано успішно!');
+    console.log('Session ID:', cabinet.sesID);
+}
 ```
 
-> ⚠️ Функціонал у розробці
+---
+
+### Отримання даних викладача
+
+```ts
+const cabinet = new CabinetTeacher('ЛОГІН', 'ПАРОЛЬ');
+await cabinet.auth();
+
+// Отримати анкетні дані викладача
+const data = await cabinet.getData();
+console.log('ПІБ:', data.fullName);
+console.log('Кафедра:', data.department);
+console.log('Навантаження:', data.totalWorkload);
+```
+
+---
+
+### Робота з академічними групами
+
+```ts
+const cabinet = new CabinetTeacher('ЛОГІН', 'ПАРОЛЬ');
+await cabinet.auth();
+
+// Отримати всі академічні групи
+const groups = await cabinet.getAcademicGroups();
+console.log('Академічні групи:', groups);
+
+// Інформація зберігається в об'єкті
+console.log('Групи викладача:', cabinet.academicGroups);
+
+// Приклад даних групи:
+//   {
+//     name: '46Бд-Комп',
+//     semester: 1,
+//     encodedName: '46%C1%E4-%CA%EE%EC%EF',
+//     course: 4,
+//     specialty: '122 Комп`ютерні науки (Д_Б 2022-2023 н.р.)',
+//     faculty: 'Фізико-математичний факультет',
+//     teacherId: '1466',
+//     journalUrl: './teachers.cgi?sesID={sesID}&n=1&grp=46%C1%E4-%CA%EE%EC%EF&teacher=1466'
+//   },
+```
+
+---
+
+### Отримання всіх даних викладача
+
+```ts
+const cabinet = new CabinetTeacher('ЛОГІН', 'ПАРОЛЬ');
+await cabinet.auth();
+
+// Завантажити всі дані (анкетні дані + академічні групи)
+await cabinet.loadData();
+
+console.log('Дані викладача:', cabinet.data);
+console.log('Академічні групи:', cabinet.academicGroups);
+```
+
+---
+
+### Відновлення сесії викладача
+
+```ts
+const cabinet = new CabinetTeacher('ЛОГІН', 'ПАРОЛЬ');
+
+// Відновити попередню сесію
+const sesID = 'YOUR_SESSION_ID';
+const sessGUID = 'YOUR_SESSION_GUID';
+
+const sessionValid = await cabinet.setSession(sesID, sessGUID);
+if (sessionValid) {
+    console.log('Сесію відновлено!');
+    await cabinet.loadData();
+}
+```
 
 ---
 
@@ -159,4 +383,4 @@ console.log(sessionId);
 
 ## Ліцензія
 
-MIT © 2025
+MIT © 2026

package/dist/audience.d.ts

@@ -5,64 +5,64 @@ import { AudienceRoom, Blocks } from './types.js';
  */
 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[]>;
+}