<!-- status: build -->
<!-- started: 2026-04-26 -->
<!-- component: gateway, frontend-nyla -->

# Infomaniak Connector (kDrive + Mail) + UDB-Integration

## Beschreibung und Kontext

PowerOn besitzt das Provider-Connector-Pattern fuer externe Datenanbindungen
(Microsoft, Google, ClickUp). Infomaniak war bisher nicht angebunden. Ziel: ein
neuer `InfomaniakConnector`, der OAuth gegen `login.infomaniak.com` durchfuehrt
und Daten aus zwei Services bereitstellt:

- **kDrive**  (Pendant zu OneDrive / Google Drive)
- **Mail**    (Pendant zu Outlook / Gmail)

Die Verbindung ist eine reine **Daten-Connection** (`TokenPurpose.DATA_CONNECTION`).
Infomaniak ist explizit **kein** Login-Provider fuer PowerOn -- entsprechend gibt
es nur `_FLOW_CONNECT`, kein `_FLOW_LOGIN`.

Zusatzlich wurden zwei kleine Inkonsistenzen in der ClickUp-UDB-Anzeige
behoben (`_SERVICE_ICONS` + `_SERVICE_TO_SOURCE_TYPE`).

## Fokus und kritische Details

- **Refresh-Token-Persistenz**: Infomaniak rotiert Refresh-Tokens nicht in jedem
  Token-Response; falls `refresh_token` im Callback fehlt, wird aus dem letzten
  gespeicherten Token rekonstruiert (analog Google).
- **API-Pfad-Konvention**: Drei-Ebenen-Hierarchie kDrive (`/{driveId}/{fileId}`)
  und vier-Ebenen Mail (`/{mailboxId}/{folderId}/{uid}`); `ServiceAdapter.browse`
  unterscheidet die Tiefe via Segment-Count.
- **Antwort-Wrapping**: Erfolgreiche Responses sind als
  `{result: 'success', data: ...}` gewrappt -- `_unwrapData()` normalisiert.
- **Authority-Filter** in `tokenRefreshService` muss `INFOMANIAK` enthalten,
  sonst werden Token nie proaktiv refreshed.

## Ziel und Nicht-Ziele

- Ziel: Infomaniak-Daten (kDrive + Mail) wie MSFT/Google im UDB browsbar.
- Ziel: ConnectionsPage hat Button "Infomaniak" (analog ClickUp).
- Ziel: Refresh-Token-Lifecycle vollautomatisch (kein User-Reconnect noetig).
- Ziel: ClickUp-UDB-Inkonsistenz beheben (Service-Icon + Source-Type-Mapping).
- NICHT: Infomaniak als PowerOn-Login (`User`-Erstellung via Infomaniak-OAuth).
- NICHT: Upload-Implementierung in kDrive/Mail (gibt nur Browse + Download).

## Betroffene Module

- Gateway:
  - `modules/datamodels/datamodelUam.py` (Enum)
  - `modules/auth/oauthProviderConfig.py` (Scopes)
  - `modules/auth/tokenManager.py` (Refresh)
  - `modules/auth/tokenRefreshService.py` (Background-Refresh)
  - `modules/connectors/providerInfomaniak/connectorInfomaniak.py` (neu)
  - `modules/connectors/connectorResolver.py` (Registry)
  - `modules/routes/routeSecurityInfomaniak.py` (neu)
  - `modules/routes/routeDataConnections.py` (Dispatch)
  - `app.py` (Router-Mount)
- Frontend:
  - `src/api/connectionApi.ts` (Authority-Typ)
  - `src/hooks/useConnections.ts` (Popup-Handler)
  - `src/pages/basedata/ConnectionsPage.tsx` (Button)
  - `src/components/UnifiedDataBar/SourcesTab.tsx` (Icons + Colors + Mapping, ClickUp-Fix)
- DB-Migration: nein (nur Enum-Wert, alle Tabellen abwaertskompatibel).
- Andere: keine.

## Entscheidungen

| Datum      | Entscheidung | Begruendung |
|------------|--------------|-------------|
| 2026-04-26 | Self-contained Connector (httpx im Modul, kein eigener Service) | Folgt Google/MSFT-Pattern, nicht ClickUp-Pattern (das delegiert an `ClickupService`) |
| 2026-04-26 | Nur DATA_CONNECTION, kein Login | User explicitly: "wir benoetigen nur den userconnection auth" |
| 2026-04-26 | `kdrive` + `mail` als Service-Namen | Kurz, konsistent mit Infomaniak-Branding (kDrive heisst offiziell so) |

## Umsetzungs-Checkliste

- [x] AuthAuthority-Enum erweitert
- [x] Scopes definiert (`user_info kdrive mail`)
- [x] InfomaniakConnector + KdriveAdapter + MailAdapter
- [x] ConnectorResolver-Registry
- [x] OAuth-Route `/api/infomaniak/auth/connect[/callback]`
- [x] Token-Refresh (`refreshInfomaniakToken` + Background-Service)
- [x] DataConnections-Dispatch (`authority_map`, Labels, `connect_service`)
- [x] App-Router-Mount
- [x] Frontend-Typen
- [x] Hook `createInfomaniakConnectionAndAuth` + Event-Listener
- [x] ConnectionsPage-Button
- [x] UDB-Integration (Authority-Icon, Service-Icons, Source-Colors, Mapping)
- [x] ClickUp-UDB-Fix
- [x] Setup-Guide `wiki/d-guides/infomaniak-oauth-setup.md`
- [ ] Manueller End-to-End-Test (ClientID/Secret im Manager registrieren, Verbinden, kDrive browsen, Mail browsen, Datei downloaden)
- [ ] `wiki/b-reference/connectors.md` (falls vorhanden) ergaenzen

## Akzeptanzkriterien

| # | Kriterium (Given-When-Then) | Prio |
|---|-----------------------------|------|
| 1 | Given Infomaniak-Credentials in `APP_CONFIG`, When Nutzer "Infomaniak" auf ConnectionsPage klickt, Then oeffnet sich der OAuth-Popup auf `login.infomaniak.com/authorize` | must |
| 2 | Given erfolgreicher OAuth-Callback, Then ist die UserConnection `ACTIVE`, Token gespeichert (`tokenAccess`+`tokenRefresh`), `externalId/Email` gesetzt | must |
| 3 | Given aktive Connection, When im UDB die Authority expandiert wird, Then werden Services `kdrive` und `mail` mit Icons angezeigt | must |
| 4 | Given Token vor Ablauf < 5 min, When Background-Refresh laeuft, Then wird `_refresh_infomaniak_token` aufgerufen und Token erneuert | must |
| 5 | Given ClickUp-Service-Node im UDB, Then ist das Service-Icon das Klemmbrett (Fix) | should |

## Testplan

| ID | AC | Art | Automatisiert | Repo-Pfad | Status |
|----|----|-----|---------------|-----------|--------|
| T1 | 1-2 | manual | nein | UI: ConnectionsPage | pending |
| T2 | 3   | manual | nein | UI: UDB SourcesTab  | pending |
| T3 | 4   | unit  | spaeter | gateway/tests/auth/test_tokenManager.py | pending |
| T4 | 5   | manual | nein | UI: UDB SourcesTab  | pending |

## Links

- PR: tbd
- Setup-Guide: `wiki/d-guides/infomaniak-oauth-setup.md`

## Abschluss

- [ ] `b-reference/` aktualisiert
- [ ] `TOPICS.md` aktualisiert
- [ ] Dokument nach `z-archive/` verschoben