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/providers/agent_provider.dart

@@ -0,0 +1,88 @@
+import 'dart:async';
+import 'package:flutter/foundation.dart';
+import '../models/agent_status.dart';
+import '../models/queue_state.dart';
+import '../services/api_client.dart';
+import '../services/sse_service.dart';
+
+class AgentProvider extends ChangeNotifier {
+  final ApiClient _api;
+  final SseService _sse;
+
+  AgentStatus? _status;
+  List<QueueInfo> _queues = [];
+  bool _sseConnected = false;
+  StreamSubscription? _sseSub;
+  StreamSubscription? _connSub;
+
+  AgentStatus? get status => _status;
+  List<QueueInfo> get queues => _queues;
+  bool get sseConnected => _sseConnected;
+
+  AgentProvider(this._api, this._sse) {
+    _connSub = _sse.connectionState.listen((connected) {
+      _sseConnected = connected;
+      notifyListeners();
+    });
+
+    _sseSub = _sse.events.listen(_handleSseEvent);
+  }
+
+  Future<void> fetchStatus() async {
+    try {
+      final response = await _api.dio.get('/agent/status');
+      _status = AgentStatus.fromJson(response.data);
+      notifyListeners();
+    } catch (_) {}
+  }
+
+  Future<void> updateStatus(AgentStatusValue newStatus) async {
+    final statusStr = newStatus.name;
+    try {
+      await _api.dio.post('/agent/status', data: {
+        'status': statusStr,
+        'is_logged_in': true,
+      });
+      _status = AgentStatus(
+        status: newStatus,
+        isLoggedIn: true,
+        currentCallSid: _status?.currentCallSid,
+      );
+      notifyListeners();
+    } catch (_) {}
+  }
+
+  Future<void> fetchQueues() async {
+    try {
+      final response = await _api.dio.get('/queues/state');
+      final data = response.data;
+      _queues = (data['queues'] as List)
+          .map((q) => QueueInfo.fromJson(q as Map<String, dynamic>))
+          .toList();
+      notifyListeners();
+    } catch (_) {}
+  }
+
+  Future<void> refresh() async {
+    await Future.wait([fetchStatus(), fetchQueues()]);
+  }
+
+  void _handleSseEvent(SseEvent event) {
+    switch (event.event) {
+      case 'call_enqueued':
+      case 'call_dequeued':
+        fetchQueues();
+        break;
+      case 'agent_status_changed':
+        fetchStatus();
+        break;
+    }
+  }
+
+  @override
+  void dispose() {
+    _sseSub?.cancel();
+    _connSub?.cancel();
+    super.dispose();
+  }
+}

mobile/lib/providers/auth_provider.dart

@@ -0,0 +1,107 @@
+import 'package:flutter/foundation.dart';
+import '../models/user.dart';
+import '../services/api_client.dart';
+import '../services/auth_service.dart';
+import '../services/voice_service.dart';
+import '../services/push_notification_service.dart';
+import '../services/sse_service.dart';
+
+enum AuthState { unauthenticated, authenticating, authenticated }
+
+class AuthProvider extends ChangeNotifier {
+  final ApiClient _apiClient;
+  late final AuthService _authService;
+  late final VoiceService _voiceService;
+  late final PushNotificationService _pushService;
+  late final SseService _sseService;
+
+  AuthState _state = AuthState.unauthenticated;
+  User? _user;
+  String? _error;
+
+  AuthState get state => _state;
+  User? get user => _user;
+  String? get error => _error;
+  VoiceService get voiceService => _voiceService;
+  SseService get sseService => _sseService;
+  ApiClient get apiClient => _apiClient;
+
+  AuthProvider(this._apiClient) {
+    _authService = AuthService(_apiClient);
+    _voiceService = VoiceService(_apiClient);
+    _pushService = PushNotificationService(_apiClient);
+    _sseService = SseService(_apiClient);
+
+    _apiClient.onForceLogout = _handleForceLogout;
+  }
+
+  Future<void> tryRestoreSession() async {
+    final restored = await _authService.tryRestoreSession();
+    if (restored) {
+      _state = AuthState.authenticated;
+      await _initializeServices();
+      notifyListeners();
+    }
+  }
+
+  Future<void> login(String serverUrl, String username, String password) async {
+    _state = AuthState.authenticating;
+    _error = null;
+    notifyListeners();
+
+    try {
+      _user = await _authService.login(serverUrl, username, password);
+      _state = AuthState.authenticated;
+      await _initializeServices();
+    } catch (e) {
+      _state = AuthState.unauthenticated;
+      _error = e.toString().replaceFirst('Exception: ', '');
+    }
+    notifyListeners();
+  }
+
+  Future<void> _initializeServices() async {
+    try {
+      await _pushService.initialize();
+    } catch (_) {}
+    try {
+      await _voiceService.initialize();
+    } catch (_) {}
+    try {
+      await _sseService.connect();
+    } catch (_) {}
+  }
+
+  Future<void> logout() async {
+    _voiceService.dispose();
+    _sseService.disconnect();
+    await _authService.logout();
+
+    _state = AuthState.unauthenticated;
+    _user = null;
+    _error = null;
+
+    // Re-create services for potential re-login
+    _voiceService = VoiceService(_apiClient);
+    _pushService = PushNotificationService(_apiClient);
+    _sseService = SseService(_apiClient);
+
+    notifyListeners();
+  }
+
+  void _handleForceLogout() {
+    _state = AuthState.unauthenticated;
+    _user = null;
+    _error = 'Session expired. Please log in again.';
+    _sseService.disconnect();
+    notifyListeners();
+  }
+
+  @override
+  void dispose() {
+    _authService.dispose();
+    _voiceService.dispose();
+    _sseService.dispose();
+    super.dispose();
+  }
+}

mobile/lib/providers/call_provider.dart

@@ -0,0 +1,134 @@
+import 'dart:async';
+import 'package:flutter/foundation.dart';
+import 'package:twilio_voice/twilio_voice.dart';
+import '../models/call_info.dart';
+import '../services/voice_service.dart';
+
+class CallProvider extends ChangeNotifier {
+  final VoiceService _voiceService;
+  CallInfo _callInfo = const CallInfo();
+  Timer? _durationTimer;
+  StreamSubscription? _eventSub;
+  DateTime? _connectedAt;
+
+  CallInfo get callInfo => _callInfo;
+
+  CallProvider(this._voiceService) {
+    _eventSub = _voiceService.callEvents.listen(_handleCallEvent);
+  }
+
+  void _handleCallEvent(CallEvent event) {
+    switch (event) {
+      case CallEvent.incoming:
+        _callInfo = _callInfo.copyWith(
+          state: CallState.ringing,
+        );
+        break;
+      case CallEvent.ringing:
+        _callInfo = _callInfo.copyWith(state: CallState.connecting);
+        break;
+      case CallEvent.connected:
+        _connectedAt = DateTime.now();
+        _callInfo = _callInfo.copyWith(state: CallState.connected);
+        _startDurationTimer();
+        break;
+      case CallEvent.callEnded:
+        _stopDurationTimer();
+        _callInfo = const CallInfo(); // reset to idle
+        break;
+      case CallEvent.returningCall:
+        _callInfo = _callInfo.copyWith(state: CallState.connecting);
+        break;
+      case CallEvent.reconnecting:
+        break;
+      case CallEvent.reconnected:
+        break;
+      default:
+        break;
+    }
+
+    // Update caller info from active call
+    final call = TwilioVoice.instance.call;
+    final active = call.activeCall;
+    if (active != null) {
+      _callInfo = _callInfo.copyWith(
+        callerNumber: active.from,
+      );
+      // Fetch SID asynchronously
+      call.getSid().then((sid) {
+        if (sid != null && sid != _callInfo.callSid) {
+          _callInfo = _callInfo.copyWith(callSid: sid);
+          notifyListeners();
+        }
+      });
+    }
+
+    notifyListeners();
+  }
+
+  void _startDurationTimer() {
+    _durationTimer?.cancel();
+    _durationTimer = Timer.periodic(const Duration(seconds: 1), (_) {
+      if (_connectedAt != null) {
+        _callInfo = _callInfo.copyWith(
+          duration: DateTime.now().difference(_connectedAt!),
+        );
+        notifyListeners();
+      }
+    });
+  }
+
+  void _stopDurationTimer() {
+    _durationTimer?.cancel();
+    _connectedAt = null;
+  }
+
+  Future<void> answer() => _voiceService.answer();
+  Future<void> reject() => _voiceService.reject();
+  Future<void> hangUp() => _voiceService.hangUp();
+
+  Future<void> toggleMute() async {
+    final newMuted = !_callInfo.isMuted;
+    await _voiceService.toggleMute(newMuted);
+    _callInfo = _callInfo.copyWith(isMuted: newMuted);
+    notifyListeners();
+  }
+
+  Future<void> toggleSpeaker() async {
+    final newSpeaker = !_callInfo.isSpeakerOn;
+    await _voiceService.toggleSpeaker(newSpeaker);
+    _callInfo = _callInfo.copyWith(isSpeakerOn: newSpeaker);
+    notifyListeners();
+  }
+
+  Future<void> sendDigits(String digits) => _voiceService.sendDigits(digits);
+
+  Future<void> holdCall() async {
+    final sid = _callInfo.callSid;
+    if (sid == null) return;
+    await _voiceService.holdCall(sid);
+    _callInfo = _callInfo.copyWith(isOnHold: true);
+    notifyListeners();
+  }
+
+  Future<void> unholdCall() async {
+    final sid = _callInfo.callSid;
+    if (sid == null) return;
+    await _voiceService.unholdCall(sid);
+    _callInfo = _callInfo.copyWith(isOnHold: false);
+    notifyListeners();
+  }
+
+  Future<void> transferCall(String target) async {
+    final sid = _callInfo.callSid;
+    if (sid == null) return;
+    await _voiceService.transferCall(sid, target);
+  }
+
+  @override
+  void dispose() {
+    _stopDurationTimer();
+    _eventSub?.cancel();
+    super.dispose();
+  }
+}