loading state and error handling refactor

lib/api/errors/app_exception.dart

@@ -0,0 +1,16 @@
+abstract class AppException implements Exception {
+  final String userMessage;
+  final String? technicalDetails;
+  final bool allowRetry;
+
+  const AppException({
+    required this.userMessage,
+    this.technicalDetails,
+    this.allowRetry = true,
+  });
+
+  @override
+  String toString() => technicalDetails == null
+      ? '$runtimeType: $userMessage'
+      : '$runtimeType: $userMessage ($technicalDetails)';
+}

lib/api/errors/auth_exception.dart

@@ -0,0 +1,23 @@
+import 'app_exception.dart';
+
+class AuthException extends AppException {
+  final int statusCode;
+
+  const AuthException({
+    required this.statusCode,
+    required super.userMessage,
+    super.technicalDetails,
+  }) : super(allowRetry: false);
+
+  factory AuthException.unauthorized({String? technicalDetails}) => AuthException(
+        statusCode: 401,
+        userMessage: 'Bitte melde dich erneut an, um fortzufahren.',
+        technicalDetails: technicalDetails,
+      );
+
+  factory AuthException.forbidden({String? technicalDetails}) => AuthException(
+        statusCode: 403,
+        userMessage: 'Du hast keine Berechtigung für diese Aktion.',
+        technicalDetails: technicalDetails,
+      );
+}

lib/api/errors/error_mapper.dart

@@ -0,0 +1,64 @@
+import 'dart:async';
+import 'dart:io';
+
+import 'package:http/http.dart' as http;
+
+import '../apiError.dart';
+import '../marianumcloud/talk/talkError.dart';
+import '../webuntis/webuntisError.dart';
+import 'app_exception.dart';
+import 'network_exception.dart';
+import 'parse_exception.dart';
+import 'talk_exception.dart';
+import 'webuntis_exception.dart';
+
+const String _defaultFallback = 'Etwas ist schiefgelaufen. Bitte versuche es erneut.';
+
+String errorToUserMessage(Object? error, {String fallback = _defaultFallback}) {
+  if (error == null) return fallback;
+  if (error is AppException) return error.userMessage;
+
+  if (error is TalkError) return TalkException(error).userMessage;
+  if (error is WebuntisError) return WebuntisException(error).userMessage;
+
+  if (error is SocketException) {
+    return const NetworkException().userMessage;
+  }
+  if (error is TimeoutException) {
+    return NetworkException.timeout().userMessage;
+  }
+  if (error is http.ClientException) {
+    return const NetworkException().userMessage;
+  }
+  if (error is HandshakeException) {
+    return 'Sichere Verbindung konnte nicht hergestellt werden.';
+  }
+  if (error is FormatException) {
+    return const ParseException().userMessage;
+  }
+  if (error is ApiError) {
+    return _stripDioPrefix(error.message);
+  }
+
+  return fallback;
+}
+
+String? errorToTechnicalDetails(Object? error) {
+  if (error == null) return null;
+  if (error is AppException) return error.technicalDetails ?? error.toString();
+  if (error is TalkError) return TalkException(error).technicalDetails;
+  if (error is WebuntisError) return WebuntisException(error).technicalDetails;
+  return error.toString();
+}
+
+bool errorAllowsRetry(Object? error) {
+  if (error == null) return true;
+  if (error is AppException) return error.allowRetry;
+  return true;
+}
+
+String _stripDioPrefix(String raw) {
+  // ApiError messages embed full request URIs; only surface the first line.
+  final firstLine = raw.split('\n').first.trim();
+  return firstLine.isEmpty ? _defaultFallback : firstLine;
+}

lib/api/errors/network_exception.dart

@@ -0,0 +1,13 @@
+import 'app_exception.dart';
+
+class NetworkException extends AppException {
+  const NetworkException({
+    super.userMessage = 'Keine Internetverbindung. Bitte prüfe dein Netzwerk und versuche es erneut.',
+    super.technicalDetails,
+  }) : super(allowRetry: true);
+
+  factory NetworkException.timeout({String? technicalDetails}) => NetworkException(
+        userMessage: 'Der Server hat zu lange gebraucht. Bitte versuche es erneut.',
+        technicalDetails: technicalDetails,
+      );
+}

lib/api/errors/not_found_exception.dart

@@ -0,0 +1,8 @@
+import 'app_exception.dart';
+
+class NotFoundException extends AppException {
+  const NotFoundException({
+    super.userMessage = 'Der angeforderte Eintrag wurde nicht gefunden.',
+    super.technicalDetails,
+  }) : super(allowRetry: false);
+}

lib/api/errors/parse_exception.dart

@@ -0,0 +1,8 @@
+import 'app_exception.dart';
+
+class ParseException extends AppException {
+  const ParseException({
+    super.userMessage = 'Die Antwort des Servers konnte nicht gelesen werden.',
+    super.technicalDetails,
+  }) : super(allowRetry: true);
+}

lib/api/errors/server_exception.dart

@@ -0,0 +1,14 @@
+import 'app_exception.dart';
+
+class ServerException extends AppException {
+  final int statusCode;
+
+  ServerException({
+    required this.statusCode,
+    String? userMessage,
+    super.technicalDetails,
+  }) : super(
+          userMessage: userMessage ?? 'Der Server hat gerade Probleme (Status $statusCode). Bitte später erneut versuchen.',
+          allowRetry: true,
+        );
+}

lib/api/errors/talk_exception.dart

@@ -0,0 +1,33 @@
+import '../marianumcloud/talk/talkError.dart';
+import 'app_exception.dart';
+
+class TalkException extends AppException {
+  final TalkError source;
+
+  TalkException(this.source)
+      : super(
+          userMessage: _mapMessage(source),
+          technicalDetails: 'Talk ${source.status} (${source.code}): ${source.message}',
+          allowRetry: source.code >= 500,
+        );
+
+  static String _mapMessage(TalkError e) {
+    switch (e.code) {
+      case 401:
+        return 'Bitte melde dich erneut an, um auf Talk zuzugreifen.';
+      case 403:
+        return 'Du hast keine Berechtigung für diese Talk-Aktion.';
+      case 404:
+        return 'Dieser Chat existiert nicht oder wurde entfernt.';
+      case 412:
+        return 'Diese Aktion ist im aktuellen Chat-Zustand nicht erlaubt.';
+      case 429:
+        return 'Zu viele Anfragen. Bitte kurz warten und erneut versuchen.';
+      default:
+        if (e.code >= 500) {
+          return 'Talk-Server hat gerade Probleme (${e.code}).';
+        }
+        return e.message.isNotEmpty ? e.message : 'Talk meldet einen Fehler (${e.code}).';
+    }
+  }
+}

lib/api/errors/webuntis_exception.dart

@@ -0,0 +1,31 @@
+import '../webuntis/webuntisError.dart';
+import 'app_exception.dart';
+
+class WebuntisException extends AppException {
+  final WebuntisError source;
+
+  WebuntisException(this.source)
+      : super(
+          userMessage: _mapMessage(source),
+          technicalDetails: 'WebUntis (${source.code}): ${source.message}',
+          allowRetry: true,
+        );
+
+  static String _mapMessage(WebuntisError e) {
+    switch (e.code) {
+      case -8504:
+      case -8502:
+        return 'WebUntis-Anmeldung abgelaufen. Bitte erneut anmelden.';
+      case -8520:
+        return 'Bitte melde dich erneut an.';
+      case -7004:
+        return 'Für diesen Zeitraum sind keine Stundenplandaten verfügbar.';
+      case -32601:
+        return 'WebUntis kennt diese Anfrage nicht. Bitte App aktualisieren.';
+      default:
+        return e.message.isNotEmpty
+            ? 'WebUntis: ${e.message}'
+            : 'WebUntis konnte die Anfrage nicht bearbeiten (Code ${e.code}).';
+    }
+  }
+}