2026-02-06 18:45:56 +01:00

4.3 KiB

Raw Blame History

Anny Booking Automation

Automate study space reservations on anny.eu platforms used by university libraries. Logs in via SAML SSO, finds available slots, and books them automatically.

Features

Pluggable SSO - TUM, KIT provider included, easily extendable for other universities
Smart scheduling - Waits until midnight when slots open, or runs immediately for testing
Configurable time slots - Set your preferred booking times in order of priority
Automated execution - Runs via GitHub Actions + cron-job.org for precise timing

Quick Start

1. Clone and install

git clone https://github.com/wiestju/anny-booking-automation.git
cd anny-booking-automation
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Configure credentials

Create a .env file:

USERNAME=your_university_username
PASSWORD=your_university_password

3. Configure booking settings

Edit config/constants.py:

SSO_PROVIDER = "kit"  # Your university's SSO provider
RESOURCE_ID = None    # Auto-detect, or set a specific resource ID

BOOKING_TIMES = [
    {'start': '14:00:00', 'end': '19:00:00'},  # First priority
    {'start': '09:00:00', 'end': '13:00:00'},  # Second priority
    {'start': '20:00:00', 'end': '23:45:00'},  # Third priority
]

4. Run locally

python main.py

Automated Scheduling

For daily automated bookings, use GitHub Actions triggered by cron-job.org.

Why cron-job.org instead of GitHub's schedule?

GitHub Actions on: schedule has two issues:

Queue delays - Workflows can be delayed by minutes, missing the booking window
UTC only - No timezone support, requiring manual DST adjustments

cron-job.org provides precise, timezone-aware scheduling with no delays.

Setup

1. Add GitHub Secrets

In your repository: Settings > Secrets and variables > Actions

Secret	Value
`USERNAME`	Your university username
`PASSWORD`	Your university password

2. Create a GitHub Personal Access Token

Go to GitHub Settings > Developer settings > Personal access tokens
Generate a token with repo scope (or fine-grained with Actions read/write)
Copy the token

3. Configure cron-job.org

Create a new cron job with these settings:

Setting	Value
URL	`https://api.github.com/repos/YOUR_USERNAME/anny-booking-automation/actions/workflows/schedule.yml/dispatches`
Schedule	`58 23 * * *` (23:58 daily)
Timezone	`Europe/Berlin` (or your timezone)
Request method	`POST`

Headers:

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

Request body:

{"ref": "main"}

How it works

cron-job.org triggers the workflow at 23:58
The script logs in and establishes a session
It waits until 00:00 when new slots become available
Instantly books the first available slot from your priority list

Project Structure

anny-booking-automation/
├── main.py                 # Entry point
├── config/
│   └── constants.py        # URLs, timezone, booking times
├── auth/
│   ├── session.py          # Login session handling
│   └── providers/          # SSO provider implementations
│       ├── base.py         # Abstract base class
│       └── kit.py          # KIT provider
├── booking/
│   └── client.py           # Booking API client
└── utils/
    └── helpers.py          # Utility functions

Adding a New SSO Provider

Create auth/providers/youruni.py:

from auth.providers.base import SSOProvider

class YourUniProvider(SSOProvider):
    name = "youruni"
    domain = "youruni.edu"

    def authenticate(self) -> str:
        # Implement SAML authentication flow
        # Use self.session, self.redirect_response, self.username, self.password
        # Return HTML containing SAMLResponse
        pass

from auth.providers.youruni import YourUniProvider

PROVIDERS = {
    "kit": KITProvider,
    "youruni": YourUniProvider,
}

License

MIT

4.3 KiB Raw Blame History