# eventlens

`eventlens` ist ein selbst gehostetes MVP zum Beobachten von Kuenstlern und Events in Hamburg oder ganz Deutschland.

## Funktionen

- Watchlist fuer Kuenstler oder Events
- Regionen `hamburg` und `germany`
- Geplanter Event-Abgleich ueber mehrere Quellen
- E-Mail-Benachrichtigung bei neu gefundenen Terminen
- Markierung, ob Tickets gekauft wurden
- Erinnerung etwa eine Woche vor dem Termin
- Webfrontend ohne separaten Build-Step
- Docker-Deployment hinter NGINX

## Projektstruktur

- `backend/`: FastAPI-Anwendung
- `deploy/nginx/eventlens.conf`: Beispiel fuer Reverse Proxy
- `docker-compose.yml`: App- und Datenbank-Container

## Start

```bash
cp .env.example .env
docker compose up -d --build
```

Danach ist das Webfrontend lokal unter `http://127.0.0.1:8001` erreichbar.
Die Swagger-Oberflaeche liegt unter `http://127.0.0.1:8001/docs`.
API-Statusinfo findest du unter `http://127.0.0.1:8001/api`.

## Wichtige Umgebungsvariablen

- `TICKETMASTER_API_KEY`: Ticketmaster Discovery API
- `JAMBASE_API_KEY`: JamBase Data API Bearer Token
- `JAMBASE_USER_AGENT`: eigene App-Kennung fuer JamBase-Requests
- `JAMBASE_SYNC_INTERVAL_HOURS`: Mindestabstand fuer JamBase-API-Laeufe, Standard `72`; `0` deaktiviert die Bremse
- `BANDSINTOWN_APP_ID`: echte Bandsintown App-ID fuer Artist-Events
- `EVENTIM_ENABLED`: aktiviert den Eventim-Website-Provider
- `EVENTLENS_AUTH_USERNAME`, `EVENTLENS_AUTH_PASSWORD`: optionaler Passwortschutz fuer Webfrontend und API
- `NOTIFICATION_EMAIL_TO`: Empfaenger fuer Benachrichtigungen
- `SMTP_HOST`, `SMTP_USER`, `SMTP_PASS`: SMTP-Zugang fuer E-Mails

## Beispielablauf

1. Watch Item anlegen:

```bash
curl -X POST http://127.0.0.1:8001/watch-items \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AnnenMayKantereit",
    "watch_type": "artist",
    "region_scope": "hamburg"
  }'
```

2. Sync manuell anstossen:

```bash
curl -X POST http://127.0.0.1:8001/sync
```

JamBase wird dabei nur abgefragt, wenn der letzte erfolgreiche JamBase-Lauf aelter als
`JAMBASE_SYNC_INTERVAL_HOURS` ist. Fuer einen sofortigen Provider-Lauf:

```bash
curl -X POST 'http://127.0.0.1:8001/sync?force_providers=true'
```

3. Events abfragen:

```bash
curl http://127.0.0.1:8001/events
```

4. Ticketkauf markieren:

```bash
curl -X PATCH http://127.0.0.1:8001/events/1/purchase \
  -H "Content-Type: application/json" \
  -d '{"is_ticket_purchased": true}'
```

## Hinweise fuer Debian 13 und NGINX

- NGINX kann nativ auf dem Host laufen und auf `127.0.0.1:8001` proxyen.
- Das Backend lauscht absichtlich nur auf `127.0.0.1`, damit es nicht direkt aus dem Internet erreichbar ist.
- Fuer produktiven Betrieb solltest du TLS im NGINX-Terminator aktivieren.
- Setze `EVENTLENS_AUTH_USERNAME` und `EVENTLENS_AUTH_PASSWORD`, wenn Eventlens ueber NGINX, VPN oder Tunnel erreichbar ist.
- Das Frontend wird direkt vom FastAPI-Container ausgeliefert, es ist kein Node- oder Build-Container noetig.

## Backup und Restore

Ein komprimiertes Datenbank-Backup kannst du so erstellen:

```bash
cd /opt/eventlens
bash scripts/backup-db.sh
```

Die Datei landet standardmaessig unter `backups/`. Einen anderen Zielordner kannst du ueber `BACKUP_DIR` setzen:

```bash
BACKUP_DIR=/srv/backups/eventlens bash scripts/backup-db.sh
```

Restore-Beispiel:

```bash
gunzip -c backups/eventlens-eventlens-YYYYMMDD-HHMMSS.sql.gz | \
  docker compose exec -T db mariadb -u"$DB_USER" -p"$DB_PASSWORD" "$DB_NAME"
```

## Bekannte Betriebsfalle

Wenn MariaDB bereits mit aelteren Zugangsdaten initialisiert wurde, reicht eine Aenderung in `.env` allein nicht aus. In dem Fall bleibt das Docker-Volume bestehen und der App-User in MariaDB hat noch das alte Passwort.

Zum Angleichen auf die aktuellen Werte aus `.env`:

```bash
cd /opt/eventlens
sudo bash scripts/fix-db-user.sh
```

Wenn dir die Datenbank egal ist und du komplett frisch starten willst:

```bash
cd /opt/eventlens
sudo docker compose down -v
sudo docker compose up -d --build
```

## Naechste sinnvolle Ausbaustufen

- Web-Frontend fuer Watchlist und Events
- Weitere Datenquellen neben Ticketmaster
- Telegram oder Push-Benachrichtigungen
- Nutzerverwaltung

## Provider-Hinweise

- Ticketmaster nutzt die offizielle Discovery API.
- JamBase nutzt die JamBase Data API ueber `https://api.data.jambase.com/v3/events` mit Bearer-Token und `User-Agent`.
- Bandsintown nutzt die offizielle Artist-Events-API und arbeitet deshalb vor allem fuer Watchlist-Eintraege vom Typ `artist`.
- Eventim nutzt eine beobachtete oeffentliche JSON-Web-API von eventim.de. Das ist keine offiziell dokumentierte Developer-API, aber stabiler als HTML-Scraping. Aenderungen an diesem Web-Endpoint koennen trotzdem Anpassungen noetig machen.
- Eventim kann serverseitig durch Eventim/Akamai geblockt werden. In dem Fall liefert `eventlens` bewusst keine falschen Treffer, sondern ueberspringt den Provider und schreibt einen Hinweis ins Backend-Log.
- Bandsintown benoetigt eine echte, von Bandsintown freigeschaltete App-ID. Ohne diese wird der Provider deaktiviert oder als `blocked` angezeigt.
- Barclays Arena wird ueber die offizielle Eventseite der Arena abgefragt.
- Fabrik wird ueber die offizielle Veranstaltungsseite der Fabrik Hamburg abgefragt.
- Fuer robuste persoenliche Ueberwachung koennen pro Watchlist-Eintrag direkte Quellen-URLs hinterlegt werden. Diese werden beim Sync gezielt per JSON-LD und HTML-Textscan durchsucht.