Update README.md to improve clarity and structure, translating sections to German and refining installation and usage instructions for the Brunata API client.

Author: fjfricke

README.md

@@ -1,191 +1,91 @@
 # brunata-api
 
-Async Python client for the Brunata Munich user portal (`nutzerportal.brunata-muenchen.de`),
-intended for Home Assistant integrations.
+Python-Client zum Abrufen von Verbrauchsdaten aus dem Brunata München Nutzerportal
+(`nutzerportal.brunata-muenchen.de`). Gedacht als Basis für eine Home-Assistant-Integration.
 
 ## Status
 
-This is an **early / experimental** project. The Munich portal uses **SAP OData** behind a UI5
-frontend. Login is performed via `NP_REG_LOGON_SRV_01` and subsequent data calls use SAP OData
-services like `NP_DASHBOARD_SRV`.
+Frühes/experimentelles Projekt. Die Münchner Instanz nutzt **SAP OData** (UI5 Frontend).
 
-## Setup
+- **Login**: `NP_REG_LOGON_SRV_01` (`CredentialSet` via `$batch`)
+- **Daten**: `NP_APPLAUNCHER_SRV`, `NP_DASHBOARD_SRV` (z.B. monatliche Werte)
 
-1) Install dependencies:
+## Installation (Poetry)
 
 ```bash
 poetry install
 ```
 
-2) Create `.env` in the project root (this file is ignored by git):
+## Konfiguration
+
+Lege eine `.env` im Projekt-Root an (wird durch `.gitignore` nicht committet):
 
 ```env
 BRUNATA_USERNAME=you@example.com
 BRUNATA_PASSWORD=your-password
-```
-
-Optional:
-
-```env
 BRUNATA_BASE_URL=https://nutzerportal.brunata-muenchen.de
-```
-
-Optional (usually `201` for Munich):
-
-```env
 BRUNATA_SAP_CLIENT=201
 ```
 
 ## CLI
 
-Try a login:
+Login testen:
 
 ```bash
 poetry run brunata login
 ```
 
-Dump key OData responses (account + available periods/cost types):
+Account + verfügbare Perioden/CostTypes dumpen (Achtung: kann persönliche Daten enthalten):
 
 ```bash
 poetry run brunata dump-pages --output-dir .brunata-dump
 ```
 
-Fetch readings:
+Verbrauchsdaten abrufen:
 
 ```bash
 poetry run brunata readings --kind heating
 poetry run brunata readings --kind hot_water
 ```
 
-## Home Assistant usage
+## Nutzung als Library (Home Assistant)
+
+Der Client ist async und für HA-Coordinator-Patterns geeignet:
 
-Home Assistant integrations typically need an async client that provides a stable interface.
-This package exposes:
+```python
+from brunata_api import BrunataClient, ReadingKind
+
+async def fetch():
+    async with BrunataClient(
+        base_url="https://nutzerportal.brunata-muenchen.de",
+        username="...",
+        password="...",
+        sap_client="201",
+    ) as client:
+        await client.login()
+        heating = await client.get_readings(ReadingKind.heating)
+        hot_water = await client.get_readings(ReadingKind.hot_water)
+        return heating, hot_water
+```
 
+Wichtige Methoden:
 - `BrunataClient.login()`
 - `BrunataClient.get_account()`
 - `BrunataClient.get_supported_cost_types()`
-- `BrunataClient.get_readings(ReadingKind.heating|ReadingKind.hot_water)`
+- `BrunataClient.get_readings(...)`
 - `BrunataClient.get_monthly_consumption(cost_type=..., in_kwh=...)`
 
-## Packaging (later)
-
-- Build: `poetry build`
-- Publish: `poetry publish` (or `poetry publish --build`)
-
-# Brunata München API
-
-Python-API zum Abrufen von Verbrauchsdaten vom Brunata München Nutzerportal.
-
-## Installation
-
-1. Repository klonen oder Dateien herunterladen
-2. Dependencies installieren:
-
-```bash
-pip install -r requirements.txt
-```
-
-3. Umgebungsvariablen einrichten:
-
-```bash
-cp .env.example .env
-```
-
-Dann die `.env` Datei bearbeiten und deine Login-Daten eintragen:
-
-```
-BRUNATA_USERNAME=dein_benutzername
-BRUNATA_PASSWORD=dein_passwort
-BRUNATA_CLIENT=201
-```
-
-## Verwendung
-
-### Test-Skript
-
-Schnelltest mit deinen Login-Daten:
+## Entwicklung
 
 ```bash
-python test_client.py <username> <password> [client_id]
+poetry run ruff check src tests
+poetry run pytest
 ```
 
-### Als Python-Modul
-
-```python
-from brunata_client import BrunataClient
-
-# Client erstellen
-client = BrunataClient("username", "password")
-
-# Einloggen
-if client.login():
-    # Verbrauchsdaten abrufen
-    data = client.get_consumption_data(
-        start_date="2024-01-01",
-        end_date="2024-12-31"
-    )
-    print(data)
-    
-    # Verfügbare Entity Sets anzeigen
-    entities = client.get_all_entities()
-    print(entities)
-    
-    client.close()
-```
-
-### Als Flask API Server
+## Packaging (optional)
 
 ```bash
-python api.py
+poetry build
+poetry publish --build
 ```
 
-Die API läuft dann auf `http://localhost:5000`
-
-#### API Endpoints
-
-- `GET /health` - Health Check
-- `POST /login` - Login mit Credentials
-  ```json
-  {
-    "username": "dein_username",
-    "password": "dein_passwort",
-    "client": "201"
-  }
-  ```
-- `GET /consumption?start_date=2024-01-01&end_date=2024-12-31` - Verbrauchsdaten abrufen
-- `GET /entities` - Alle verfügbaren Entity Sets abrufen
-
-## Aktueller Status
-
-✅ **Login funktioniert** - Login via OData `NP_REG_LOGON_SRV_01/CredentialSet`  
-✅ **Datenzugriff funktioniert** - Verbrauchsdaten via `NP_DASHBOARD_SRV` (monatlich)  
-
-### Gefundene Services:
-- `NP_GENERIC_SRV`: PlaceholderSet, InfoTextSet, PageModuleSet, UserContextSet, UserContextRoleSet, FAQSet
-- `NP_REG_LOGON_SRV_01`: PortalUserSet, TitleSet, InfoTextSet, FAQSet, CredentialSet
-- `NP_APPLAUNCHER_SRV`: UserContextSet, ModuleSet, NavigationMenueSet, ...
-- `NP_DASHBOARD_SRV`: DatesSet, ValueHelpUnitOfMeasureSet, CumuConsumptionMonSet, ...
-
-### Nächste Schritte:
-Optional (für eine HA-Integration):
-
-1. Aus `Reading` stabile Sensor-IDs ableiten (z.B. `heating_monthly_kwh`, `hot_water_monthly_kwh`)
-2. Optional weitere Endpoints aus `NP_DASHBOARD_SRV` hinzufügen (z.B. `CumuConsumptionSet` Summen)
-3. Caching/Throttling auf HA-Seite (Coordinator) ergänzen
-
-## Fehlerbehebung
-
-- **Login fehlschlägt**: Überprüfe deine Credentials in der `.env` Datei
-- **Keine Daten gefunden**: Prüfe `BRUNATA_SAP_CLIENT` (Munich meist `201`) und ob in `DatesSet` die CostTypes (`HZ..`, `WW..`) vorhanden sind
-- **401 Fehler**: Login liefert SAP Basic-Auth Credentials, die für nachfolgende OData Requests nötig sind (wird im Client automatisch gemacht)
-
-## Entwicklung
-
-Die Authentifizierung läuft in zwei Phasen:
-
-1. **OData Credential Login**: `NP_REG_LOGON_SRV_01` (`CredentialSet` via `$batch`)
-2. **SAP Basic Auth**: danach werden alle OData Calls (z.B. `NP_DASHBOARD_SRV`) mit Basic Auth durchgeführt
-
-Falls das Portal spezielle Anforderungen hat, müssen diese im `BrunataClient` angepasst werden.
-