PowerOn/wiki
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
wiki/c-work/2-build/2026-04-infomaniak-connector.md
ValueOn AG 111faae088 added infomaniak
2026-04-26 23:59:12 +02:00

5.7 KiB
Raw Blame History

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

  • AuthAuthority-Enum erweitert
  • Scopes definiert (user_info kdrive mail)
  • InfomaniakConnector + KdriveAdapter + MailAdapter
  • ConnectorResolver-Registry
  • OAuth-Route /api/infomaniak/auth/connect[/callback]
  • Token-Refresh (refreshInfomaniakToken + Background-Service)
  • DataConnections-Dispatch (authority_map, Labels, connect_service)
  • App-Router-Mount
  • Frontend-Typen
  • Hook createInfomaniakConnectionAndAuth + Event-Listener
  • ConnectionsPage-Button
  • UDB-Integration (Authority-Icon, Service-Icons, Source-Colors, Mapping)
  • ClickUp-UDB-Fix
  • 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