# ViewIT – Entwicklerdoku Plugins (`addon/plugins/*_plugin.py`)

Diese Doku beschreibt, wie Plugins im ViewIT‑Addon aufgebaut sind und wie neue Provider‑Integrationen entwickelt werden.

## Grundlagen
- Jedes Plugin ist eine einzelne Datei unter `addon/plugins/`.
- Dateinamen **ohne** `_`‑Prefix werden automatisch geladen.
- Jede Datei enthält eine Klasse, die von `BasisPlugin` erbt.

## Pflicht‑Methoden (BasisPlugin)
Jedes Plugin muss diese Methoden implementieren:
- `async search_titles(query: str) -> list[str]`
- `seasons_for(title: str) -> list[str]`
- `episodes_for(title: str, season: str) -> list[str]`

## Vertrag Plugin ↔ Hauptlogik (`default.py`)
Die Hauptlogik ruft Plugin-Methoden auf und verarbeitet ausschließlich deren Rückgaben.

Wesentliche Rückgaben an die Hauptlogik:
- `search_titles(...)` → Liste von Titel-Strings für die Trefferliste
- `seasons_for(...)` → Liste von Staffel-Labels
- `episodes_for(...)` → Liste von Episoden-Labels
- `stream_link_for(...)` → Hoster-/Player-Link (nicht zwingend finale Media-URL)
- `resolve_stream_link(...)` → finale/spielbare URL nach Redirect/Resolver
- Optional `available_hosters_for(...)` → auswählbare Hoster-Namen im Dialog
- Optional `series_url_for_title(...)` → stabile Detail-URL pro Titel für Folgeaufrufe
- Optional `remember_series_url(...)` → Übernahme einer bereits bekannten Detail-URL

Standard für Film-Provider (ohne echte Staffeln):
- `seasons_for(title)` gibt `["Film"]` zurück
- `episodes_for(title, "Film")` gibt `["Stream"]` zurück

## Optionale Features (Capabilities)
Über `capabilities()` kann das Plugin zusätzliche Funktionen anbieten:
- `popular_series` → `popular_series()`
- `genres` → `genres()` + `titles_for_genre(genre)`
- `latest_episodes` → `latest_episodes(page=1)`

## Empfohlene Struktur
- Konstanten für URLs/Endpoints (BASE_URL, Pfade, Templates)
- `requests` + `bs4` optional (fehlt beides, Plugin sollte sauber deaktivieren)
- Helper‑Funktionen für Parsing und Normalisierung
- Caches für Such‑, Staffel‑ und Episoden‑Daten

## Suche (aktuelle Policy)
- **Nur Titel‑Matches**
- **Wortbasierter Match** nach Normalisierung (Lowercase + Nicht‑Alnum → Leerzeichen)
- Keine Teilwort-Treffer innerhalb eines Wortes (Beispiel: `hund` matcht nicht `thunder`)
- Keine Beschreibung/Plot/Meta für Matches

## Namensgebung
- Plugin‑Klassenname: `XxxPlugin`
- Anzeigename (Property `name`): **mit Großbuchstaben beginnen** (z. B. `Serienstream`, `Einschalten`)

## Settings pro Plugin
Standard: `*_base_url` (Domain / BASE_URL)
- Beispiele:
  - `serienstream_base_url`
  - `aniworld_base_url`
  - `einschalten_base_url`
  - `topstream_base_url`
  - `filmpalast_base_url`

## Playback
- `stream_link_for(...)` implementieren (liefert bevorzugten Hoster-Link).
- `available_hosters_for(...)` bereitstellen, wenn die Seite mehrere Hoster anbietet.
- `resolve_stream_link(...)` nach einheitlichem Flow umsetzen:
  1. Redirects auflösen (falls vorhanden)
  2. ResolveURL (`resolveurl_backend.resolve`) versuchen
  3. Bei Fehlschlag auf den besten verfügbaren Link zurückfallen
- Optional `set_preferred_hosters(...)` unterstützen, damit die Hoster-Auswahl aus der Hauptlogik direkt greift.

## Standard‑Flow (empfohlen)
1. **Suche**: nur Titel liefern und Titel→Detail-URL mappen.
2. **Navigation**: `series_url_for_title`/`remember_series_url` unterstützen, damit URLs zwischen Aufrufen stabil bleiben.
3. **Auswahl Hoster**: Hoster-Namen aus der Detailseite extrahieren und anbieten.
4. **Playback**: Hoster-Link liefern, danach konsistent über `resolve_stream_link` finalisieren.
5. **Fallbacks**: bei Layout-Unterschieden defensiv parsen und Logging aktivierbar halten.

## Debugging
Global gesteuert über Settings:
- `debug_log_urls`
- `debug_dump_html`
- `debug_show_url_info`

Plugins sollten die Helper aus `addon/plugin_helpers.py` nutzen:
- `log_url(...)`
- `dump_response_html(...)`
- `notify_url(...)`

## Template
`addon/plugins/_template_plugin.py` dient als Startpunkt für neue Provider.

## Build & Test
- ZIP bauen: `./scripts/build_kodi_zip.sh`
- Addon‑Ordner: `./scripts/build_install_addon.sh`

## Beispiel‑Checkliste
- [ ] `name` korrekt gesetzt
- [ ] `*_base_url` in Settings vorhanden
- [ ] Suche matcht nur Titel und wortbasiert
- [ ] `stream_link_for` + `resolve_stream_link` folgen dem Standard-Flow
- [ ] Optional: `available_hosters_for` + `set_preferred_hosters` vorhanden
- [ ] Optional: `series_url_for_title` + `remember_series_url` vorhanden
- [ ] Fehlerbehandlung und Timeouts vorhanden
- [ ] Optional: Caches für Performance

## Hinweis zur Erstellung
Teile dieser Dokumentation wurden KI‑gestützt erstellt und bei Bedarf manuell angepasst.