# Il Post Podcasts — plasmoide KDE Plasma 6

![Avatar del progetto](assets/repository-avatar.png)

Plasmoide standalone per KDE Plasma 6 che visualizza gli episodi più recenti dei podcast de Il Post, mette i programmi preferiti in cima e permette di riprodurre gli episodi con un player KDE compatibile con MPRIS.

> **Progetto derivato, non libreria upstream.** Questo repository **non è** il repository upstream originale clonato e non pretende di essere una nuova versione della libreria `thekoma/ilpostapi`. È un progetto separato, con scopo, struttura, UI e ciclo di rilascio propri, che integra e utilizza gli endpoint/API individuati nel progetto upstream.

## Relazione con upstream

- **Upstream di riferimento:** [`thekoma/ilpostapi`](https://github.com/thekoma/ilpostapi)
- **Questo progetto:** [`enne2/ilpost-podcasts-plasmoid`](https://git.enne2.net/enne2/ilpost-podcasts-plasmoid)
- Il repository upstream resta la sorgente di riferimento per gli endpoint non ufficiali de Il Post; questo plasmoide ne riusa il modello API senza incorporare il backend web upstream.
- Gli aggiornamenti upstream non vengono importati automaticamente: vanno valutati e integrati manualmente quando cambiano endpoint o formato delle risposte.
- Il client usa gli endpoint non ufficiali autenticati de Il Post (`/user/v1/auth/login` e `/podcast/v1/podcast`). Usarlo solo con un account autorizzato e nel rispetto dei Termini di servizio.

## Funzionalità

- Elenco degli episodi più recenti dei programmi disponibili.
- Programmi preferiti selezionabili dalle impostazioni Plasma e mostrati con priorità.
- Copertine asincrone con cache e icona di fallback se l'artwork non è disponibile.
- Login dal widget; username, password e token vengono conservati in KWallet tramite `kwallet-query`, non in KConfig o nei file del progetto.
- Riproduzione con Dragon Player, player KDE che espone MPRIS (`org.mpris.MediaPlayer2.dragonplayer`), con fallback al player predefinito tramite `xdg-open`.
- Aggiornamento periodico configurabile e filtro “solo preferiti”.

## Struttura

```text
package/
  metadata.json
  contents/config/       # impostazioni Plasma 6
  contents/ui/            # interfaccia QML e catalogo programmi
  contents/lib/           # plugin QML compilato durante la build
src/                     # client API/KWallet e plugin QML C++
CMakeLists.txt
```

Il codice è volutamente standalone: `package/` è il pacchetto Plasma, mentre `src/` contiene il bridge C++ per rete, autenticazione, KWallet e avvio del player.

## Compilazione e installazione locale

Dipendenze: Qt 6 Core/Network/Qml, `kwallet-query`, `kpackagetool6` e Dragon Player (oppure un handler audio compatibile).

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --build build --target install-plasmoid
```

Per una prima installazione:

```bash
kpackagetool6 -t Plasma/Applet -i package
```

Test rapido:

```bash
plasmawindowed org.enne2.ilpost.podcasts
```

Dopo l'installazione, aggiungere **Podcast de Il Post** al desktop e aprire **Configura** per scegliere preferiti, quantità e intervallo di aggiornamento. Le credenziali vanno inserite nei campi del widget, non nella shell o nei file Git.

## Sviluppo upstream

Il repository upstream può essere registrato come remoto di sola lettura:

```bash
git remote add upstream https://github.com/thekoma/ilpostapi.git
git fetch upstream --prune
```

`origin` deve rimanere il repository Gitea del plasmoide. Prima di integrare modifiche upstream, verificare manualmente endpoint, autenticazione, campi JSON e Termini di servizio.

## Sicurezza e limiti

- Non committare credenziali, token, file `.env` o dump delle risposte API.
- KWallet deve essere disponibile nella sessione KDE; se non lo è, il login non può salvare i segreti.
- Le API usate non sono un contratto pubblico stabile e possono cambiare senza preavviso.
- L'audio e le copertine possono mancare per alcuni episodi o dipendere dai permessi dell'account.

## Licenza

Il codice del plasmoide è distribuito con licenza GPL-3.0-or-later, come indicato nei metadati del pacchetto. L'attribuzione all'upstream resta esplicita sopra; verificare sempre gli obblighi applicabili prima di redistribuire o modificare il progetto.