Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
include LICENSE
include README.md
exclude README.vi.md
prune docs
prune tasks
prune tests
global-exclude *.py[cod] __pycache__
231 changes: 125 additions & 106 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,138 +1,157 @@
# MyFAP API CLI

## Giới thiệu
**English** | [Tiếng Việt](./README.vi.md)

Unofficial CLI tương tác với các API internal của ứng dụng myFAP giúp xem lịch học, lịch thi, điểm số (sự thất vọng của gia đình) và thông tin sinh viên
## Introduction

## Tính năng chính
- Hỗ trợ đa nền tảng
- Login thông qua FEID hoặc Google OAuth
- Xem lịch học (từng tuần hoặc cả Kỳ)
- Xem điểm (từng môn hoặc cả Kỳ)
- Check điểm danh (từng môn hoặc cả Kỳ)
- Check tình trạng đơn từ
- Xem thông báo của trường
- Check Info của sinh viên hoặc phòng dvsv
- Convert lịch học Kỳ sang **ICS**, dễ dàng import lịch học vào Google Calendar hoặc các dịch vụ tương tự
- Và nhiều hơn nữa ...
An unofficial CLI that talks to the internal APIs of the myFAP mobile app to check class schedules, exam dates, grades (the family disappointment edition), and student profile info.

## Cách sử dụng
## Disclaimer

- Cài đặt cli
- **Unofficial tool:** This is an independent project built for personal and educational use. It is not affiliated with, authorized, maintained, or endorsed by FPT University (FPTU) or the official myFAP development team.
- **Use at your own risk:** This software is provided "as is", without warranty of any kind. The author is not responsible for any account issues, inaccurate data, service disruptions, or other damages resulting from using this CLI. Always double-check important academic records such as exam schedules, final grades, and tuition fees on the official FAP portal or the official myFAP app.
- **Warnings on internal APIs and session security:**
- **Reverse-engineered internal APIs:** This tool relies on undocumented internal endpoints extracted from the myFAP Android client. Upstream changes can break functionality, alter responses, or block requests at any time without notice.
- **Plaintext local session:** After logging in, your OAuth tokens and `authen_key` are stored in plaintext JSON at `~/.myfap-api-cli/session.json` (or the path passed to `--config`). Never share this file or commit exported `.json`/`.ics` student data to public repositories. Run `myfap logout` when finished on shared machines.
- **Responsible usage:** Avoid automated high-frequency polling or scraping that puts unnecessary load on upstream servers.

```
## Key Features
- Cross-platform support (Windows, macOS, Linux)
- Log in via FEID or Google OAuth
- View class schedules (weekly or full semester)
- View grades (per subject or full semester)
- Check attendance (per subject or full semester)
- Check submitted student applications
- Read campus news and announcements
- View student profile and Student Services (DVSV) info
- Export semester class schedules and exam schedules to **ICS** for Google Calendar or other calendar apps
- And more...

## Usage

- Install the CLI:

```sh
pip install myfap
```

- Lấy danh sách cơ sở
- List available campuses:

```
```sh
myfap campuses
```

- Login vào myFAP api thông qua FEID
```
- Log in to the myFAP API via FEID:

```sh
myfap login --campus HN
```
Sau khi hoàn thành login, phiên đăng nhập sẽ được lưu ở ``~/.myfap-api-cli/session.json``

- Login cho cơ sở Xavalo
```
After logging in, your session is saved at `~/.myfap-api-cli/session.json`.

- Log in for the Xavalo (HCM) campus:

```sh
myfap login -c HCM
```

- Lấy Lịch học *(tự động lấy kỳ mới nhất)*
- Fetch your class schedule *(automatically picks the latest semester)*:

```
```sh
myfap schedule
```

## Danh sách các Command
## Command Reference

| Command | Tác dụng |
| Command | Description |
|:--|:--|
| `version` | Hiển thị phiên bản CLI |
| `doctor` | Kiểm tra cấu hình; thêm `--online` để kiểm tra kết nối bootstrap v2. |
| `login` | Đăng nhập hoặc dùng session hiện có; thêm `--force` để đăng nhập lại |
| `logout` | Xóa session trên máy |
| `refresh` | Làm mới token và session |
| `campuses` | Liệt kê các cơ sở của API đang chọn |
| `semesters` | Liệt kê các kỳ học |
| `schedule` | Xem lịch học theo kỳ; dùng `--ics` để xuất lịch **ICS** |
| `week-timetable` | Xem lịch học theo tuần hoặc ngày |
| `exams` | Xem lịch thi; dùng `--ics` để xuất lịch, thêm `--full` để kèm thông tin phụ |
| `courses` | Xem danh sách khóa học theo kỳ |
| `marks` | Xem điểm theo kỳ, chi tiết theo môn hoặc tổng kết với `--summary` |
| `transcript` | Xem bảng điểm toàn khóa; `--pretty` phân tích dữ liệu bảng HTML sang JSON |
| `attendance` | Xem điểm danh theo kỳ hoặc theo môn và lớp |
| `applications` | Xem danh sách đơn đã gửi |
| `news` | Xem hoặc tìm kiếm tin tức |
| `info student` | Xem thông tin sinh viên |
| `info photo` | Lấy dữ liệu ảnh sinh viên ở dạng JSON |
| `info campus` | Xem thông tin phòng dịch vụ sinh viên |
| `other training` | Xem điểm phong trào theo kỳ |
| `other survey` | Kiểm tra khảo sát cần làm |
| `other feedback` | Kiểm tra feedback đang mở |
| `other feedbacks` | Xem danh sách feedback của sinh viên; chỉ hỗ trợ v2 |
| `other profile` | Kiểm tra yêu cầu cập nhật hồ sơ |
| `other notification` | Xem thông báo của sinh viên |
| `other fee` | Xem các khoản học phí và trạng thái thanh toán |
| `other balance` | Xem số dư tài khoản |
| `other subjects` | Xem danh sách môn; có thể lọc theo kỳ |
| `other rating list` | Xem danh sách đánh giá; chỉ hỗ trợ v1 |

## Biến môi trường
Gồm 2 biến mặc định
- ``MYFAP_TIMEOUT``: thay đổi thời gian timeout mặc định (mặc định: 10s), danh sách môn timeout 30s
- ``MYFAP_API_VER``: overide phiên bản api (mặc định: v2)

## Lưu ý
Khi thiếu `--semester`, cli chọn kỳ theo `startDate` gần đây. Với lịch tuần, `--date` quyết định năm nếu bạn không truyền `--year`

## Các Options
Ví dụ:
| `version` | Show the CLI version |
| `doctor` | Check local configuration; add `--online` to test the v2 bootstrap connection |
| `login` | Log in or reuse an existing session; add `--force` to force re-authentication |
| `logout` | Delete the local session |
| `refresh` | Refresh tokens and session state |
| `campuses` | List campuses for the selected API version |
| `semesters` | List available semesters |
| `schedule` | View semester class schedule; use `--ics` to export an **ICS** calendar |
| `week-timetable` | View weekly or daily class timetable |
| `exams` | View exam schedule; use `--ics` to export an **ICS** file, add `--full` for extra fields |
| `courses` | List courses for a semester |
| `marks` | View semester grades, per-course details, or summary with `--summary` |
| `transcript` | View full academic transcript; `--pretty` parses the HTML table into JSON |
| `attendance` | Check attendance by semester or filter by subject and class |
| `applications` | List submitted student applications |
| `news` | Read or search campus news |
| `info student` | View student profile information |
| `info photo` | Fetch student photo data as JSON |
| `info campus` | View Student Services (DVSV) contact details |
| `other training` | View training points by semester |
| `other survey` | Check pending surveys |
| `other feedback` | Check open feedbacks |
| `other feedbacks` | List student feedbacks; v2 only |
| `other profile` | Check profile update requests |
| `other notification` | View student notifications |
| `other fee` | View tuition fees and payment status |
| `other balance` | View account balance |
| `other subjects` | List subjects; optionally filter by semester |
| `other rating list` | View rating list; v1 only |

## Environment Variables
Two environment variables are supported by default:
- `MYFAP_TIMEOUT`: override the default request timeout in seconds (default: `10`s; subject listing uses `30`s)
- `MYFAP_API_VER`: override the API version (default: `v2`)

## Notes
When `--semester` is omitted, the CLI picks the current semester from recent `startDate` values (at least one past semester needs a valid `startDate` for auto-selection to work, which holds true unless you are a freshman whose first semester has not started yet). For `week-timetable`, `--date` determines the year if `--year` is omitted.

## Options
Examples:
```sh
myfap --api-version v2 --campus HN schedule --ics
myfap schedule --ics --api-version v2 --campus HN
myfap info student --timeout 20 --stdout
```

Nếu khai báo cùng option ở nhiều cấp, giá trị ở lệnh con được ưu tiên; lặp trong cùng cấp thì dùng giá trị cuối

|Option|Chú thích|
|:-|:-|
|--help|Hiển thị bảng Commands và Options|
|--config <đường dẫn>|Đường dẫn tới file cấu hình session tùy chỉnh (mặc định: ~/.myfap-api-cli/session.json)|
|--timeout <giây>|Tăng hoặc giảm thời gian chờ dữ liệu gửi về từ server, có thể dùng biến môi trường ``MYFAP_TIMEOUT``|
|--api-version <v1 hoặc v2>|Chọn API; ưu tiên option, biến môi trường `MYFAP_API_VER`, version trong session, rồi mặc định v2. Session cũ thiếu version vẫn là v1|
|-c, --campus <cơ sở>|Mã cơ sở; ưu tiên option rồi session. APHL chỉ mặc định cho v1; v2 cần chọn campus nếu chưa có mã phù hợp trong session|
|-s, --semester <kỳ học>|Tên kỳ học (VD: ``Fall2026``)|
|-cid, --courseid <mã môn>|Chọn mã môn, chỉ có ở command ``marks``. (VD: 82934, lấy từ bảng điểm của kỳ, ko phải mã môn như PRO192, SWE201c, ...)|
|-w, --week <số tuần>|Chọn tuần, chỉ có ở command ``week-timetable``|
|-y, --year <số năm>|Chọn năm học, chỉ có ở command ``week-timetable``|
|-d, --date \<YYYY-MM-DD\>|Chỉ định ngày chính xác, chỉ có ở command ``week-timetable``|
|-sc, --subjectcode <mã môn>|Chọn môn học, chỉ có ở command ``attendance``|
|-cn, --classname <mã lớp>|Chọn lớp học, chỉ có ở command ``attendance``|
|--ics|Convert Sang **ICS**, dễ dàng import lịch vào Google Calendar hoặc các dịch vụ tương tự, áp dụng cho command ``schedule`` (lịch học) và ``exams`` (lịch thi)|
|--full|Kèm toàn bộ thông tin phụ khi xuất ICS ở command ``exams``, mặc định xuất các thông tin quan trọng (môn, phòng thi, ngày công bố)|
|-p, --pretty|Format lại bảng điểm gốc của trường sang dạng json, chỉ có ở command ``marks`` và ``transcript``|
|--output, -o <thư mục>|Thư mục xuất file thay vì thư mục hiện tại|
|--stdout|In kết quả trực tiếp ra màn hình thay vì lưu file|
|-f, --force|Buộc đăng nhập lại, bỏ qua file ``session.json``, chỉ có ở command ``login``|


## Thông tin thêm
- [Chọn API v1 hoặc v2](./docs/cli/api-versions.md): v2 là mặc định khi chưa có session; xem thứ tự ưu tiên và cách dùng v1
- [Các ví dụ sử dụng](./docs/cli/Example.md)
- [Tạo môi trường dev bằng uv](./docs/cli/development.md)
- [CI và kiểm tra artifact](./docs/cli/development.md#ci-và-kiểm-tra-artifact)

## Ghi công
- Api đã dc reverse engineered từ [myFAP android](https://play.google.com/store/apps/details?id=com.fuct): phiên bản *2.0.6*, versionCode: *31*
- [JADX](https://github.com/skylot/jadx): decompile và unpack apk android
- [Hermes decomp](https://github.com/SymbioticSec/hermes-decomp): decompile index.android.bundle về js có thể đọc dc
- [Burp Suite Community Edition](https://portswigger.net/burp): bắt gói tin và phân tích động ứng dụng myFAP
- [Playwright](https://playwright.dev/): chịu trắch nhiệm chính trong quy trình login
- [Typer](https://typer.tiangolo.com/) & [Rich](https://rich.readthedocs.io/): nền tảng giao diện cli của repo này
- [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/): bóc tách và xử lý dữ liệu html
- [ics.py](https://icspy.readthedocs.io/): tạo và chuẩn hóa định dạng iCalendar giúp dễ dàng import vào các ứng dụng lịch
If the same option is passed at multiple command levels, the subcommand value takes precedence. If repeated at the same level, the last value wins.

| Option | Description |
|:--|:--|
| `--help` | Show commands and options help |
| `--config <path>` | Path to a custom session config file (default: `~/.myfap-api-cli/session.json`) |
| `--timeout <seconds>` | Server request timeout in seconds; can also be set via `MYFAP_TIMEOUT` |
| `--api-version <v1 or v2>` | Select API version. Precedence: CLI option, `MYFAP_API_VER`, session version, then default `v2`. Legacy sessions without a version still default to `v1` |
| `-c, --campus <campus>` | Campus code. Precedence: CLI option then session. `APHL` is the default only for `v1`; `v2` requires choosing a campus if no compatible code is stored in the session |
| `-s, --semester <semester>` | Semester name (e.g., `Fall2026`) |
| `-cid, --courseid <id>` | Internal numeric course ID, only available on `marks` (e.g., `82934` from the semester grade table, not subject codes like `PRO192` or `SWE201c`) |
| `-w, --week <week>` | Week number, only available on `week-timetable` |
| `-y, --year <year>` | Academic year, only available on `week-timetable` |
| `-d, --date <YYYY-MM-DD>` | Specific date, only available on `week-timetable` |
| `-sc, --subjectcode <code>` | Subject code, only available on `attendance` |
| `-cn, --classname <class>` | Class name, only available on `attendance` |
| `--ics` | Export to **ICS** for easy import into Google Calendar or other calendar apps; supported on `schedule` (classes) and `exams` (exam schedule) |
| `--full` | Include all extra fields when exporting ICS on `exams` (default exports key fields: subject, exam room, and result announcement date) |
| `-p, --pretty` | Parse the raw HTML grade tables into JSON; supported on `marks` and `transcript` |
| `--output, -o <dir>` | Output directory instead of the current working directory |
| `--stdout` | Print output to stdout instead of saving a file |
| `-f, --force` | Force re-login and ignore `session.json`; only available on `login` |

## Further Documentation
*(Note: detailed documentation under `docs/` is currently written in Vietnamese.)*

- [Choosing API v1 or v2](./docs/cli/api-versions.md): `v2` is the default when no session exists; precedence rules and using `v1`
- [Usage Examples](./docs/cli/Example.md)
- [Setting up a dev environment with uv](./docs/cli/development.md)
- [CI and Artifact Checks](./docs/cli/development.md#ci-và-kiểm-tra-artifact)

## Credits
- Internal APIs reverse engineered from [myFAP Android](https://play.google.com/store/apps/details?id=com.fuct): version *2.0.6*, versionCode *31*
- [JADX](https://github.com/skylot/jadx): decompiling and unpacking the Android APK
- [Hermes decomp](https://github.com/SymbioticSec/hermes-decomp): decompiling `index.android.bundle` into readable JavaScript
- [Burp Suite Community Edition](https://portswigger.net/burp): intercepting packets and dynamic analysis of myFAP
- [Playwright](https://playwright.dev/): handles the browser OAuth login flow
- [Typer](https://typer.tiangolo.com/) & [Rich](https://rich.readthedocs.io/): CLI framework and terminal UI
- [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/): HTML parsing and extraction
- [ics.py](https://icspy.readthedocs.io/): generating and normalizing iCalendar files for calendar imports

## License

This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
Loading
Loading