import 'package:networks_sdk/src/domain/entities/socket_connection_state.dart';
import 'package:networks_sdk/src/domain/entities/socket_error.dart';
import 'package:networks_sdk/src/presentation/wiring/networks_sdk_wiring.dart';
import 'package:networks_sdk/src/presentation/wiring/socket_config.dart';

/// Messaging API for real-time communication
///
/// This abstract class provides a technology-agnostic interface for
/// real-time messaging. The actual implementation may use WebSocket
/// or other transport mechanisms.
///
/// ## Usage
///
/// ```dart
/// final messaging = NetworksMessagingApi();
/// await messaging.initialize(SocketConfig(...));
///
/// // Connect to messaging server
/// await messaging.connect('wss://api.example.com/ws', token: 'xxx');
///
/// // Listen for messages
/// messaging.messageStream.listen((msg) => print(msg));
///
/// // Send messages
/// await messaging.send({'type': 'chat', 'data': {...}});
///
/// // Handle connection state
/// messaging.connectionStateStream.listen((state) => ...);
///
/// // Handle errors
/// messaging.errorStream.listen((error) => ...);
///
/// // Lifecycle management
/// messaging.onEnterForeground();
/// messaging.onEnterBackground();
///
/// // Cleanup
/// await messaging.disconnect();
/// await messaging.dispose();
/// ```
abstract class NetworksMessagingApi
{
  factory NetworksMessagingApi() => NetworksSdkWiring.buildMessagingApi();

  /// Initialize the messaging service with configuration
  void initialize(SocketConfig config);

  /// Connect to the messaging server
  ///
  /// [url] - WebSocket URL (e.g., 'wss://api.example.com/ws')
  /// [token] - Optional authentication token
  Future<bool> connect(String url, {String? token});

  /// Disconnect from the messaging server
  ///
  /// Manual disconnect does not trigger auto-reconnect
  Future<void> disconnect();

  /// Check if currently connected
  bool get isConnected;

  /// Current connection state
  SocketConnectionState get connectionState;

  /// Send a JSON message
  Future<bool> send(Map<String, dynamic> message);

  /// Send a raw string message
  Future<bool> sendString(String message);

  /// Stream of incoming parsed JSON messages
  Stream<Map<String, dynamic>> get messageStream;

  /// Stream of raw string messages (including failed JSON parses)
  Stream<String> get rawMessageStream;

  /// Stream of connection state changes
  Stream<SocketConnectionState> get connectionStateStream;

  /// Stream of errors
  Stream<SocketError> get errorStream;

  /// Called when app enters foreground
  void onEnterForeground();

  /// Called when app enters background
  void onEnterBackground();

  /// Dispose all resources
  Future<void> dispose();
}

