anny-booking-automation/README.md

# 📚 KIT Anny Booking Automation

This Python project automates booking of study spaces or resources via the [anny.eu](https://anny.eu) platform used by the KIT (Karlsruhe Institute of Technology) library system. It logs in automatically using KIT SAML SSO, searches for available slots, and makes bookings without user interaction — ideal for recurring reservations.

---

## ⚙️ Features

- 🔐 Automatic KIT login via SAML SSO  
- 📆 Configurable 3-days-ahead reservation window  
- 🔎 Auto-detection of available time slots  
- ⏳ Pre-login shortly before midnight to instantly book a slot at 00:00  
- 🛠️ Clean and modular object-oriented codebase  
- 🔁 Fully automated execution using [cron-job.org](https://cron-job.org) + GitHub API  
- 📦 Easy to extend and maintain  

---

## 🗂️ Project Structure

```
anny_booking/
├── .env                         # Credentials (excluded from version control)
├── main.py                      # Entry point for script execution
├── requirements.txt             # Python dependencies
│
├── auth/
│   └── session.py               # AnnySession class (login logic)
│
├── booking/
│   └── client.py                # BookingClient class (resource booking)
│
├── config/
│   └── constants.py             # API URLs and shared constants
│
├── utils/
│   └── helpers.py               # Utility functions
│
└── .github/
    └── workflows/
        └── schedule.yml         # GitHub Actions workflow (manual trigger)
```

---

## 🚀 Setup & Installation

### 1. Clone the repository

```bash
git clone https://github.com/your-username/anny-booking-automation.git  
cd anny-booking-automation
```

### 2. Set up a Python virtual environment

```bash
python3 -m venv venv  
source venv/bin/activate  
pip install -r requirements.txt
```

### 3. Configure environment variables

Create a `.env` file in the root of the project:

```
USERNAME=your_kit_username  
PASSWORD=your_kit_password
```

> 🔒 Never commit this file to version control!

---

## ⏱️ Automated Execution via cron-job.org + GitHub API

To maximize booking success, the script is triggered **two minutes before midnight** (e.g., 23:58).  
It logs in to the KIT SAML SSO in advance, keeps the session alive, and **waits internally until exactly 00:00** to instantly book the best available slot as soon as new reservations open.

The trigger is handled by:

- `cron-job.org` for precise scheduling (e.g., 23:58 Europe/Berlin)  
- GitHub Actions to run the actual script with credentials passed via GitHub Secrets  

### Why not just use `on: schedule`?

GitHub Actions only supports fixed cron expressions (e.g., once per hour) and does **not** allow more frequent triggers like every 5 or 10 minutes.  
Additionally, it suffers from two major issues:

- ⏳ **Queue delay**: Workflows triggered via GitHub's `schedule` event are sometimes delayed by several minutes due to internal queue congestion. This can cause the booking script to miss the optimal reservation window.  
- 🕒 **Timezone limitations**: GitHub's cron system uses UTC without native timezone support. That means you need to manually convert your desired local time (e.g. Europe/Berlin) and keep adjusting for daylight saving time changes.  

For these reasons, we use [cron-job.org](https://cron-job.org), which offers:

- ✅ Precise minute-level scheduling  
- ✅ Native timezone selection (e.g. Europe/Berlin)  
- ✅ Immediate webhook execution with no delay  

This ensures your booking script runs exactly when needed — already logged in and ready to act at 00:00.

---

### How it works

1. `cron-job.org` triggers the GitHub Actions workflow at **23:58** (Europe/Berlin).  
2. The script logs in via KIT SAML SSO and maintains an active session.  
3. It waits internally until **00:00**.  
4. As soon as new booking slots are released, it instantly reserves the first suitable slot.  

---

### Setup steps

1. Set up a cron job on `cron-job.org` that sends a POST request to:

```
https://api.github.com/repos/your-username/anny-booking-automation/actions/workflows/schedule.yml/dispatches
```

2. Include the following JSON payload:

```json
{"ref": "main"}
```

3. Add this header:

```
Authorization: Bearer YOUR_GITHUB_PERSONAL_ACCESS_TOKEN  
Content-Type: application/json  
Accept: application/vnd.github.v3+json
```

4. Your GitHub workflow (`.github/workflows/schedule.yml`) listens for this event:

```yaml
name: Daily Library Reservation Automation

on:
  workflow_dispatch:

jobs:
  run-script:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.x'
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
      - name: Run script
        env:
          USERNAME: ${{ secrets.USERNAME }}
          PASSWORD: ${{ secrets.PASSWORD }}
        run: |
          python main.py
```

> 💡 Store your KIT credentials securely as [GitHub Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets): `USERNAME` and `PASSWORD`.

---

## 📜 License

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

---

## 👤 Author

Created by @wiestju

---

## 🤝 Contributing

Pull requests are welcome! Feel free to open an issue or suggest features or improvements.

---

## 📎 Related Tools

- [cron-job.org](https://cron-job.org)  
- [GitHub Actions](https://github.com/features/actions)  
- [anny.eu](https://anny.eu)