@emiran/omu-ubys 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +143 -0
- package/README.tr.md +106 -0
- package/dist/index.cjs +1347 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +264 -0
- package/dist/index.d.ts +264 -0
- package/dist/index.js +1332 -0
- package/dist/index.js.map +1 -0
- package/package.json +64 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Emirhan
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# @emiran/omu-ubys
|
|
4
|
+
|
|
5
|
+
**Unofficial TypeScript client for Ondokuz Mayıs University UBYS**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/@emiran/omu-ubys)
|
|
8
|
+
[](https://nodejs.org)
|
|
9
|
+
[](https://www.typescriptlang.org/)
|
|
10
|
+
[](./LICENSE)
|
|
11
|
+
[](https://github.com/emi-ran/omu-ubys-npm/actions)
|
|
12
|
+
|
|
13
|
+
Stop scraping UBYS manually. Get typed, normalized student data with a single client.
|
|
14
|
+
|
|
15
|
+
[Getting Started](#getting-started) · [API Reference](./DOCS.md) · [Türkçe](./README.tr.md)
|
|
16
|
+
|
|
17
|
+
</div>
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## ✨ Features
|
|
22
|
+
|
|
23
|
+
- 🔐 **Session-based auth** — cookie jar handling, CSRF tokens, login flow managed for you
|
|
24
|
+
- 📊 **Academic data** — grades, transcripts, class details, weekly schedules
|
|
25
|
+
- 💬 **Messaging** — conversation lists, recipients, full message history
|
|
26
|
+
- 🍽️ **Cafeteria menu** — daily menu without needing to log in
|
|
27
|
+
- 🧑🏫 **Advisor info** — name & contact for your academic advisor
|
|
28
|
+
- 🛡️ **Structured errors** — `LoginError`, `SessionExpiredError`, `ParseError`, and more
|
|
29
|
+
- 📦 **ESM + CJS** — works everywhere, with full type exports
|
|
30
|
+
|
|
31
|
+
## Getting Started
|
|
32
|
+
|
|
33
|
+
### Install
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
npm install @emiran/omu-ubys
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### Quick Start
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { UBYSClient } from "@emiran/omu-ubys";
|
|
43
|
+
|
|
44
|
+
const client = new UBYSClient({
|
|
45
|
+
username: process.env.OMU_UBYS_USERNAME,
|
|
46
|
+
password: process.env.OMU_UBYS_PASSWORD,
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
try {
|
|
50
|
+
await client.login();
|
|
51
|
+
|
|
52
|
+
const profile = await client.getProfile();
|
|
53
|
+
const grades = await client.getGrades();
|
|
54
|
+
const schedule = await client.getWeeklySchedule();
|
|
55
|
+
|
|
56
|
+
console.log(profile.name); // "Emirhan Çetinkaya"
|
|
57
|
+
console.log(grades[0]?.courses[0]?.letterGrade); // "AA"
|
|
58
|
+
console.log(schedule[0]?.courseName); // "Veri Yapıları"
|
|
59
|
+
} finally {
|
|
60
|
+
await client.close();
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## 🗂️ Available Methods
|
|
65
|
+
|
|
66
|
+
| Category | Method | Auth Required |
|
|
67
|
+
|----------|--------|:---:|
|
|
68
|
+
| **Auth** | `login()` | — |
|
|
69
|
+
| | `clearSession()` | ✅ |
|
|
70
|
+
| | `close()` | — |
|
|
71
|
+
| **Academic** | `getProfile()` | ✅ |
|
|
72
|
+
| | `getGrades()` | ✅ |
|
|
73
|
+
| | `getClassDetails(classId)` | ✅ |
|
|
74
|
+
| | `getTranscript()` | ✅ |
|
|
75
|
+
| | `getWeeklySchedule()` | ✅ |
|
|
76
|
+
| **Campus** | `getAdvisor()` | ✅ |
|
|
77
|
+
| | `getCafeteriaMenu()` | ❌ |
|
|
78
|
+
| **Messaging** | `getMessages(options?)` | ✅ |
|
|
79
|
+
| | `getChatRecipients(options)` | ✅ |
|
|
80
|
+
| | `getChatMessages(options)` | ✅ |
|
|
81
|
+
|
|
82
|
+
> **State helpers:** `isLoggedIn` · `isClosed`
|
|
83
|
+
|
|
84
|
+
## 🧩 Error Handling
|
|
85
|
+
|
|
86
|
+
Every error extends `UBYSError`, so you can catch granularly or broadly:
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
import { UBYSClient, LoginError, SessionExpiredError } from "@emiran/omu-ubys";
|
|
90
|
+
|
|
91
|
+
try {
|
|
92
|
+
await client.login();
|
|
93
|
+
const grades = await client.getGrades();
|
|
94
|
+
} catch (error) {
|
|
95
|
+
if (error instanceof LoginError) {
|
|
96
|
+
console.error("Invalid credentials.");
|
|
97
|
+
} else if (error instanceof SessionExpiredError) {
|
|
98
|
+
console.error("Session expired — re-login required.");
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
<details>
|
|
104
|
+
<summary>All exported error classes</summary>
|
|
105
|
+
|
|
106
|
+
- `UBYSError` — base class
|
|
107
|
+
- `AuthenticationError`
|
|
108
|
+
- `LoginError`
|
|
109
|
+
- `SessionExpiredError`
|
|
110
|
+
- `NetworkError`
|
|
111
|
+
- `HttpError`
|
|
112
|
+
- `ParseError`
|
|
113
|
+
- `NotImplementedUBYSError`
|
|
114
|
+
- `ClientClosedError`
|
|
115
|
+
|
|
116
|
+
</details>
|
|
117
|
+
|
|
118
|
+
## 🤔 Why This Package?
|
|
119
|
+
|
|
120
|
+
| Without `@emiran/omu-ubys` | With `@emiran/omu-ubys` |
|
|
121
|
+
|---|---|
|
|
122
|
+
| Manual cookie management | Automatic session handling |
|
|
123
|
+
| Parsing raw HTML / Base64 payloads | Clean, typed return values |
|
|
124
|
+
| Guessing at UBYS endpoints | Documented, tested methods |
|
|
125
|
+
| No error context | Structured error hierarchy |
|
|
126
|
+
|
|
127
|
+
## 📚 Documentation
|
|
128
|
+
|
|
129
|
+
| Document | Description |
|
|
130
|
+
|----------|-------------|
|
|
131
|
+
| [**DOCS.md**](./DOCS.md) | Full API reference with types & examples |
|
|
132
|
+
| [**CHANGELOG.md**](./CHANGELOG.md) | Version history & notable changes |
|
|
133
|
+
| [**README.tr.md**](./README.tr.md) | Türkçe genel bakış |
|
|
134
|
+
| [**CONTRIBUTING.md**](./CONTRIBUTING.md) | Contribution guidelines |
|
|
135
|
+
| [**DEVELOPMENT.md**](./DEVELOPMENT.md) | Roadmap & project status |
|
|
136
|
+
|
|
137
|
+
## ⚠️ Legal Notice
|
|
138
|
+
|
|
139
|
+
> This is an **unofficial** third-party project for **educational and research purposes only**.
|
|
140
|
+
>
|
|
141
|
+
> It is not endorsed, approved, or maintained by Ondokuz Mayıs University. Using unofficial APIs or automating access to institutional systems may violate terms of service or applicable law. **You are solely responsible for your usage.**
|
|
142
|
+
>
|
|
143
|
+
> Takedown or review requests: [`ctnky.emiran@gmail.com`](mailto:ctnky.emiran@gmail.com)
|
package/README.tr.md
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# @emiran/omu-ubys
|
|
4
|
+
|
|
5
|
+
**Ondokuz Mayıs Üniversitesi UBYS için gayriresmî TypeScript istemcisi**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/@emiran/omu-ubys)
|
|
8
|
+
[](https://nodejs.org)
|
|
9
|
+
[](https://www.typescriptlang.org/)
|
|
10
|
+
[](./LICENSE)
|
|
11
|
+
|
|
12
|
+
UBYS'yi elle kazımayı bırakın. Tek bir istemciyle tipli, normalize öğrenci verisi alın.
|
|
13
|
+
|
|
14
|
+
[Başlarken](#başlarken) · [API Dokümantasyonu](./DOCS.md) · [English](./README.md)
|
|
15
|
+
|
|
16
|
+
</div>
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## ✨ Özellikler
|
|
21
|
+
|
|
22
|
+
- 🔐 **Oturum tabanlı kimlik doğrulama** — cookie jar, CSRF token ve login akışı sizin için yönetilir
|
|
23
|
+
- 📊 **Akademik veriler** — notlar, transkript, ders detayları, haftalık program
|
|
24
|
+
- 💬 **Mesajlaşma** — konuşma listesi, katılımcılar, tam mesaj geçmişi
|
|
25
|
+
- 🍽️ **Yemekhane menüsü** — giriş yapmadan günlük menü
|
|
26
|
+
- 🧑🏫 **Danışman bilgisi** — akademik danışmanınızın adı ve iletişim bilgisi
|
|
27
|
+
- 🛡️ **Yapılandırılmış hatalar** — `LoginError`, `SessionExpiredError`, `ParseError` ve dahası
|
|
28
|
+
- 📦 **ESM + CJS** — her ortamda çalışır, tam tip dışa aktarımı
|
|
29
|
+
|
|
30
|
+
## Başlarken
|
|
31
|
+
|
|
32
|
+
### Kurulum
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
npm install @emiran/omu-ubys
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Hızlı Başlangıç
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
import { UBYSClient } from "@emiran/omu-ubys";
|
|
42
|
+
|
|
43
|
+
const client = new UBYSClient({
|
|
44
|
+
username: process.env.OMU_UBYS_USERNAME,
|
|
45
|
+
password: process.env.OMU_UBYS_PASSWORD,
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
try {
|
|
49
|
+
await client.login();
|
|
50
|
+
|
|
51
|
+
const profile = await client.getProfile();
|
|
52
|
+
const grades = await client.getGrades();
|
|
53
|
+
|
|
54
|
+
console.log(profile.name); // "Emirhan Çetinkaya"
|
|
55
|
+
console.log(grades[0]?.courses[0]?.letterGrade); // "AA"
|
|
56
|
+
} finally {
|
|
57
|
+
await client.close();
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## 🗂️ Mevcut Metodlar
|
|
62
|
+
|
|
63
|
+
| Kategori | Metod | Giriş Gerekli |
|
|
64
|
+
|----------|-------|:---:|
|
|
65
|
+
| **Kimlik** | `login()` | — |
|
|
66
|
+
| | `clearSession()` | ✅ |
|
|
67
|
+
| | `close()` | — |
|
|
68
|
+
| **Akademik** | `getProfile()` | ✅ |
|
|
69
|
+
| | `getGrades()` | ✅ |
|
|
70
|
+
| | `getClassDetails(classId)` | ✅ |
|
|
71
|
+
| | `getTranscript()` | ✅ |
|
|
72
|
+
| | `getWeeklySchedule()` | ✅ |
|
|
73
|
+
| **Kampüs** | `getAdvisor()` | ✅ |
|
|
74
|
+
| | `getCafeteriaMenu()` | ❌ |
|
|
75
|
+
| **Mesajlaşma** | `getMessages(options?)` | ✅ |
|
|
76
|
+
| | `getChatRecipients(options)` | ✅ |
|
|
77
|
+
| | `getChatMessages(options)` | ✅ |
|
|
78
|
+
|
|
79
|
+
> **Durum yardımcıları:** `isLoggedIn` · `isClosed`
|
|
80
|
+
|
|
81
|
+
## 🤔 Neden Bu Paket?
|
|
82
|
+
|
|
83
|
+
| `@emiran/omu-ubys` olmadan | `@emiran/omu-ubys` ile |
|
|
84
|
+
|---|---|
|
|
85
|
+
| Manuel cookie yönetimi | Otomatik oturum yönetimi |
|
|
86
|
+
| Ham HTML / Base64 payload parse etme | Temiz, tipli dönüş değerleri |
|
|
87
|
+
| UBYS endpoint'lerini tahmin etme | Dökümante edilmiş, test edilmiş metodlar |
|
|
88
|
+
| Hata bağlamı yok | Yapılandırılmış hata hiyerarşisi |
|
|
89
|
+
|
|
90
|
+
## 📚 Dokümantasyon
|
|
91
|
+
|
|
92
|
+
| Döküman | Açıklama |
|
|
93
|
+
|---------|----------|
|
|
94
|
+
| [**DOCS.md**](./DOCS.md) | Tam API referansı, tipler ve örnekler |
|
|
95
|
+
| [**CHANGELOG.md**](./CHANGELOG.md) | Sürüm geçmişi ve önemli değişiklikler |
|
|
96
|
+
| [**README.md**](./README.md) | English overview |
|
|
97
|
+
| [**CONTRIBUTING.md**](./CONTRIBUTING.md) | Katkı rehberi |
|
|
98
|
+
| [**DEVELOPMENT.md**](./DEVELOPMENT.md) | Yol haritası ve proje durumu |
|
|
99
|
+
|
|
100
|
+
## ⚠️ Hukuki Uyarı
|
|
101
|
+
|
|
102
|
+
> Bu proje tamamen **eğitim ve araştırma amacıyla** sunulan **gayriresmî** bir üçüncü taraf çalışmadır.
|
|
103
|
+
>
|
|
104
|
+
> Ondokuz Mayıs Üniversitesi tarafından onaylanmamış, desteklenmemiş veya bakımı yapılmamaktadır. Gayriresmî API kullanımı veya kurumsal sistemlere otomatik erişim, kullanım koşullarını veya ilgili mevzuatı ihlal edebilir. **Kullanım sorumluluğu tamamen size aittir.**
|
|
105
|
+
>
|
|
106
|
+
> Kaldırma veya inceleme talepleri: [`ctnky.emiran@gmail.com`](mailto:ctnky.emiran@gmail.com)
|