Add TWP Softphone Flutter app and complete mobile backend API

Backend: Add /voice/token endpoint with AccessToken + VoiceGrant for
mobile VoIP, implement unhold_call() with call leg detection, wire FCM
push notifications into call queue and webhook missed call handlers,
add data-only FCM message support for Android background wake, and add
Twilio API Key / Push Credential settings fields.

Flutter app: Full softphone with Twilio Voice SDK integration, JWT auth
with auto-refresh, SSE real-time queue updates, FCM push notifications,
Material 3 UI with dashboard, active call screen, dialpad, and call
controls (mute/speaker/hold/transfer).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

mobile/lib/services/api_client.dart

@@ -0,0 +1,85 @@
+import 'package:dio/dio.dart';
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+
+class ApiClient {
+  late final Dio dio;
+  final FlutterSecureStorage _storage = const FlutterSecureStorage();
+  VoidCallback? onForceLogout;
+
+  ApiClient() {
+    dio = Dio(BaseOptions(
+      connectTimeout: const Duration(seconds: 15),
+      receiveTimeout: const Duration(seconds: 30),
+    ));
+
+    dio.interceptors.add(InterceptorsWrapper(
+      onRequest: (options, handler) async {
+        final token = await _storage.read(key: 'access_token');
+        if (token != null) {
+          options.headers['Authorization'] = 'Bearer $token';
+        }
+        handler.next(options);
+      },
+      onError: (error, handler) async {
+        if (error.response?.statusCode == 401) {
+          final refreshed = await _tryRefreshToken();
+          if (refreshed) {
+            final opts = error.requestOptions;
+            final token = await _storage.read(key: 'access_token');
+            opts.headers['Authorization'] = 'Bearer $token';
+            try {
+              final response = await dio.fetch(opts);
+              return handler.resolve(response);
+            } catch (e) {
+              return handler.next(error);
+            }
+          } else {
+            onForceLogout?.call();
+          }
+        }
+        handler.next(error);
+      },
+    ));
+  }
+
+  Future<void> setBaseUrl(String serverUrl) async {
+    final url = serverUrl.endsWith('/')
+        ? serverUrl.substring(0, serverUrl.length - 1)
+        : serverUrl;
+    dio.options.baseUrl = '$url/wp-json/twilio-mobile/v1';
+    await _storage.write(key: 'server_url', value: url);
+  }
+
+  Future<void> restoreBaseUrl() async {
+    final url = await _storage.read(key: 'server_url');
+    if (url != null) {
+      dio.options.baseUrl = '$url/wp-json/twilio-mobile/v1';
+    }
+  }
+
+  Future<bool> _tryRefreshToken() async {
+    try {
+      final refreshToken = await _storage.read(key: 'refresh_token');
+      if (refreshToken == null) return false;
+
+      final response = await dio.post(
+        '/auth/refresh',
+        data: {'refresh_token': refreshToken},
+        options: Options(headers: {'Authorization': ''}),
+      );
+
+      if (response.statusCode == 200 && response.data['success'] == true) {
+        await _storage.write(
+            key: 'access_token', value: response.data['access_token']);
+        if (response.data['refresh_token'] != null) {
+          await _storage.write(
+              key: 'refresh_token', value: response.data['refresh_token']);
+        }
+        return true;
+      }
+    } catch (_) {}
+    return false;
+  }
+}
+
+typedef VoidCallback = void Function();

mobile/lib/services/auth_service.dart

@@ -0,0 +1,95 @@
+import 'dart:async';
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+import '../models/user.dart';
+import 'api_client.dart';
+
+class AuthService {
+  final ApiClient _api;
+  final FlutterSecureStorage _storage = const FlutterSecureStorage();
+  Timer? _refreshTimer;
+
+  AuthService(this._api);
+
+  Future<User> login(String serverUrl, String username, String password,
+      {String? fcmToken}) async {
+    await _api.setBaseUrl(serverUrl);
+
+    final response = await _api.dio.post('/auth/login', data: {
+      'username': username,
+      'password': password,
+      if (fcmToken != null) 'fcm_token': fcmToken,
+    });
+
+    final data = response.data;
+    if (data['success'] != true) {
+      throw Exception(data['message'] ?? 'Login failed');
+    }
+
+    await _storage.write(key: 'access_token', value: data['access_token']);
+    await _storage.write(key: 'refresh_token', value: data['refresh_token']);
+
+    _scheduleRefresh(data['expires_in'] as int? ?? 3600);
+
+    return User.fromJson(data['user']);
+  }
+
+  Future<bool> tryRestoreSession() async {
+    final token = await _storage.read(key: 'access_token');
+    if (token == null) return false;
+
+    await _api.restoreBaseUrl();
+    if (_api.dio.options.baseUrl.isEmpty) return false;
+
+    try {
+      final response = await _api.dio.get('/agent/status');
+      return response.statusCode == 200;
+    } catch (_) {
+      return false;
+    }
+  }
+
+  Future<void> refreshToken() async {
+    final refreshToken = await _storage.read(key: 'refresh_token');
+    if (refreshToken == null) throw Exception('No refresh token');
+
+    final response = await _api.dio.post('/auth/refresh', data: {
+      'refresh_token': refreshToken,
+    });
+
+    final data = response.data;
+    if (data['success'] != true) {
+      throw Exception('Token refresh failed');
+    }
+
+    await _storage.write(key: 'access_token', value: data['access_token']);
+    if (data['refresh_token'] != null) {
+      await _storage.write(key: 'refresh_token', value: data['refresh_token']);
+    }
+
+    _scheduleRefresh(data['expires_in'] as int? ?? 3600);
+  }
+
+  void _scheduleRefresh(int expiresInSeconds) {
+    _refreshTimer?.cancel();
+    // Refresh 2 minutes before expiry
+    final refreshIn = Duration(seconds: expiresInSeconds - 120);
+    if (refreshIn.isNegative) return;
+    _refreshTimer = Timer(refreshIn, () async {
+      try {
+        await refreshToken();
+      } catch (_) {}
+    });
+  }
+
+  Future<void> logout() async {
+    _refreshTimer?.cancel();
+    try {
+      await _api.dio.post('/auth/logout');
+    } catch (_) {}
+    await _storage.deleteAll();
+  }
+
+  void dispose() {
+    _refreshTimer?.cancel();
+  }
+}

mobile/lib/services/push_notification_service.dart

@@ -0,0 +1,78 @@
+import 'package:firebase_core/firebase_core.dart';
+import 'package:firebase_messaging/firebase_messaging.dart';
+import 'package:flutter_local_notifications/flutter_local_notifications.dart';
+import 'api_client.dart';
+
+@pragma('vm:entry-point')
+Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
+  await Firebase.initializeApp();
+  // VoIP pushes are handled natively by twilio_voice plugin.
+  // Other data messages can show a local notification if needed.
+}
+
+class PushNotificationService {
+  final ApiClient _api;
+  final FirebaseMessaging _messaging = FirebaseMessaging.instance;
+  final FlutterLocalNotificationsPlugin _localNotifications =
+      FlutterLocalNotificationsPlugin();
+
+  PushNotificationService(this._api);
+
+  Future<void> initialize() async {
+    FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
+
+    await _messaging.requestPermission(
+      alert: true,
+      badge: true,
+      sound: true,
+      criticalAlert: true,
+    );
+
+    // Initialize local notifications
+    const androidSettings =
+        AndroidInitializationSettings('@mipmap/ic_launcher');
+    const initSettings = InitializationSettings(android: androidSettings);
+    await _localNotifications.initialize(initSettings);
+
+    // Get and register FCM token
+    final token = await _messaging.getToken();
+    if (token != null) {
+      await _registerToken(token);
+    }
+
+    // Listen for token refresh
+    _messaging.onTokenRefresh.listen(_registerToken);
+
+    // Handle foreground messages (non-VoIP)
+    FirebaseMessaging.onMessage.listen(_handleForegroundMessage);
+  }
+
+  Future<void> _registerToken(String token) async {
+    try {
+      await _api.dio.post('/fcm/register', data: {'fcm_token': token});
+    } catch (_) {}
+  }
+
+  void _handleForegroundMessage(RemoteMessage message) {
+    final data = message.data;
+    final type = data['type'];
+
+    // VoIP incoming_call is handled by twilio_voice natively
+    if (type == 'incoming_call') return;
+
+    // Show local notification for other types (missed call, queue alert, etc.)
+    _localNotifications.show(
+      message.hashCode,
+      data['title'] ?? 'TWP Softphone',
+      data['body'] ?? '',
+      const NotificationDetails(
+        android: AndroidNotificationDetails(
+          'twp_general',
+          'General Notifications',
+          importance: Importance.high,
+          priority: Priority.high,
+        ),
+      ),
+    );
+  }
+}

mobile/lib/services/sse_service.dart

@@ -0,0 +1,119 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:math';
+import 'package:dio/dio.dart';
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+import '../config/app_config.dart';
+import 'api_client.dart';
+
+class SseEvent {
+  final String event;
+  final Map<String, dynamic> data;
+
+  SseEvent({required this.event, required this.data});
+}
+
+class SseService {
+  final ApiClient _api;
+  final FlutterSecureStorage _storage = const FlutterSecureStorage();
+  final StreamController<SseEvent> _eventController =
+      StreamController<SseEvent>.broadcast();
+  final StreamController<bool> _connectionController =
+      StreamController<bool>.broadcast();
+
+  CancelToken? _cancelToken;
+  Timer? _reconnectTimer;
+  int _reconnectAttempt = 0;
+  bool _shouldReconnect = true;
+
+  Stream<SseEvent> get events => _eventController.stream;
+  Stream<bool> get connectionState => _connectionController.stream;
+
+  SseService(this._api);
+
+  Future<void> connect() async {
+    _shouldReconnect = true;
+    _reconnectAttempt = 0;
+    await _doConnect();
+  }
+
+  Future<void> _doConnect() async {
+    _cancelToken?.cancel();
+    _cancelToken = CancelToken();
+
+    try {
+      final token = await _storage.read(key: 'access_token');
+      final response = await _api.dio.get(
+        '/stream/events',
+        options: Options(
+          headers: {'Authorization': 'Bearer $token'},
+          responseType: ResponseType.stream,
+        ),
+        cancelToken: _cancelToken,
+      );
+
+      _connectionController.add(true);
+      _reconnectAttempt = 0;
+
+      final stream = response.data.stream as Stream<List<int>>;
+      String buffer = '';
+
+      await for (final chunk in stream) {
+        buffer += utf8.decode(chunk);
+        final lines = buffer.split('\n');
+        buffer = lines.removeLast(); // keep incomplete line in buffer
+
+        String? eventName;
+        String? dataStr;
+
+        for (final line in lines) {
+          if (line.startsWith('event:')) {
+            eventName = line.substring(6).trim();
+          } else if (line.startsWith('data:')) {
+            dataStr = line.substring(5).trim();
+          } else if (line.isEmpty && eventName != null && dataStr != null) {
+            try {
+              final data = jsonDecode(dataStr) as Map<String, dynamic>;
+              _eventController.add(SseEvent(event: eventName, data: data));
+            } catch (_) {}
+            eventName = null;
+            dataStr = null;
+          }
+        }
+      }
+    } catch (e) {
+      if (e is DioException && e.type == DioExceptionType.cancel) return;
+      _connectionController.add(false);
+    }
+
+    if (_shouldReconnect) {
+      _scheduleReconnect();
+    }
+  }
+
+  void _scheduleReconnect() {
+    _reconnectTimer?.cancel();
+    final delay = Duration(
+      milliseconds: min(
+        AppConfig.sseMaxReconnect.inMilliseconds,
+        AppConfig.sseReconnectBase.inMilliseconds *
+            pow(2, _reconnectAttempt).toInt(),
+      ),
+    );
+    _reconnectAttempt++;
+    _reconnectTimer = Timer(delay, _doConnect);
+  }
+
+  void disconnect() {
+    _shouldReconnect = false;
+    _reconnectTimer?.cancel();
+    _cancelToken?.cancel();
+    _connectionController.add(false);
+  }
+
+  void dispose() {
+    disconnect();
+    _eventController.close();
+    _connectionController.close();
+  }
+}

mobile/lib/services/voice_service.dart

@@ -0,0 +1,85 @@
+import 'dart:async';
+import 'package:twilio_voice/twilio_voice.dart';
+import 'api_client.dart';
+
+class VoiceService {
+  final ApiClient _api;
+  Timer? _tokenRefreshTimer;
+  String? _identity;
+
+  final StreamController<CallEvent> _callEventController =
+      StreamController<CallEvent>.broadcast();
+  Stream<CallEvent> get callEvents => _callEventController.stream;
+
+  VoiceService(this._api);
+
+  Future<void> initialize() async {
+    await _fetchAndRegisterToken();
+
+    TwilioVoice.instance.callEventsListener.listen((event) {
+      _callEventController.add(event);
+    });
+
+    // Refresh token every 50 minutes
+    _tokenRefreshTimer?.cancel();
+    _tokenRefreshTimer = Timer.periodic(
+      const Duration(minutes: 50),
+      (_) => _fetchAndRegisterToken(),
+    );
+  }
+
+  Future<void> _fetchAndRegisterToken() async {
+    try {
+      final response = await _api.dio.get('/voice/token');
+      final data = response.data;
+      final token = data['token'] as String;
+      _identity = data['identity'] as String;
+      await TwilioVoice.instance.setTokens(accessToken: token);
+    } catch (e) {
+      // Token fetch failed - will retry on next interval
+    }
+  }
+
+  String? get identity => _identity;
+
+  Future<void> answer() async {
+    await TwilioVoice.instance.call.answer();
+  }
+
+  Future<void> reject() async {
+    await TwilioVoice.instance.call.hangUp();
+  }
+
+  Future<void> hangUp() async {
+    await TwilioVoice.instance.call.hangUp();
+  }
+
+  Future<void> toggleMute(bool mute) async {
+    await TwilioVoice.instance.call.toggleMute(mute);
+  }
+
+  Future<void> toggleSpeaker(bool speaker) async {
+    await TwilioVoice.instance.call.toggleSpeaker(speaker);
+  }
+
+  Future<void> sendDigits(String digits) async {
+    await TwilioVoice.instance.call.sendDigits(digits);
+  }
+
+  Future<void> holdCall(String callSid) async {
+    await _api.dio.post('/calls/$callSid/hold');
+  }
+
+  Future<void> unholdCall(String callSid) async {
+    await _api.dio.post('/calls/$callSid/unhold');
+  }
+
+  Future<void> transferCall(String callSid, String target) async {
+    await _api.dio.post('/calls/$callSid/transfer', data: {'target': target});
+  }
+
+  void dispose() {
+    _tokenRefreshTimer?.cancel();
+    _callEventController.close();
+  }
+}