mc5-api-client 1.0.15__py3-none-any.whl → 1.0.17__py3-none-any.whl

mc5_api_client/alerts_quick.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : alerts_quick.py
+# | License  | MIT License © 2026 Chizoba
+# | Brief    | Quick functions for real-time alerts
+# ────────────────★─────────────────────────────────
+
+from typing import Optional, Dict, Any, List, Callable
+from .simple_client import SimpleMC5Client
+from .telemetry import report_usage
+from .debug import debug_function, debug_print
+
+@debug_function
+def quick_start_alert_stream(username: str, password: str,
+                             webhook_url: Optional[str] = None,
+                             alert_types: Optional[List[str]] = None,
+                             callback: Optional[Callable] = None) -> Optional[Dict[str, Any]]:
+    """
+    Quick function to start real-time alert streaming.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        webhook_url: Optional Discord webhook URL for alert forwarding
+        alert_types: List of alert types to subscribe to
+        callback: Optional callback function for handling alerts
+        
+    Returns:
+        Stream session information or None if failed
+    """
+    try:
+        with SimpleMC5Client(username, password) as client:
+            if client.connect():
+                session = client.client.start_alert_stream(
+                    webhook_url=webhook_url,
+                    alert_types=alert_types,
+                    callback=callback
+                )
+                
+                debug_print(f"✅ Alert stream started on {session.get('server')}", "success")
+                return session
+            return None
+    except Exception as e:
+        debug_print(f"❌ Failed to start alert stream: {e}", "error")
+        return None
+
+@debug_function
+def quick_test_alert_connection(username: str, password: str) -> Optional[Dict[str, Any]]:
+    """
+    Quick function to test alert server connections.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        
+    Returns:
+        Connection test results or None if failed
+    """
+    try:
+        with SimpleMC5Client(username, password) as client:
+            if client.connect():
+                results = client.client.test_alert_connection()
+                
+                connected_count = results.get('connected_count', 0)
+                total_tested = results.get('total_tested', 0)
+                
+                debug_print(f"✅ Alert connection test: {connected_count}/{total_tested} servers connected", "success")
+                
+                best_server = results.get('best_server')
+                if best_server and best_server.get('connected'):
+                    debug_print(f"🎯 Best server: {best_server.get('server')} ({best_server.get('response_time', 0):.2f}s)", "info")
+                
+                return results
+            return None
+    except Exception as e:
+        debug_print(f"❌ Failed to test alert connection: {e}", "error")
+        return None
+
+@debug_function
+def quick_start_alerts_with_discord(username: str, password: str,
+                                    discord_webhook: str,
+                                    alert_types: Optional[List[str]] = None) -> Optional[Dict[str, Any]]:
+    """
+    Quick function to start alerts with Discord webhook forwarding.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        discord_webhook: Discord webhook URL for alert forwarding
+        alert_types: List of alert types to subscribe to
+        
+    Returns:
+        Stream session information or None if failed
+    """
+    try:
+        # Default alert types if not provided
+        if alert_types is None:
+            alert_types = ["connection", "message", "connection_request", "connection_request_accepted"]
+        
+        debug_print(f"🔔 Starting alerts with Discord forwarding", "info")
+        debug_print(f"📋 Alert types: {', '.join(alert_types)}", "info")
+        debug_print(f"🔗 Webhook: {discord_webhook[:50]}...", "info")
+        
+        return quick_start_alert_stream(
+            username=username,
+            password=password,
+            webhook_url=discord_webhook,
+            alert_types=alert_types
+        )
+    except Exception as e:
+        debug_print(f"❌ Failed to start alerts with Discord: {e}", "error")
+        return None
+
+def create_alert_callback(print_alerts: bool = True, save_to_file: Optional[str] = None) -> Callable:
+    """
+    Create a callback function for handling alerts.
+    
+    Args:
+        print_alerts: Whether to print alerts to console
+        save_to_file: Optional file path to save alerts
+        
+    Returns:
+        Callback function
+    """
+    def alert_callback(alert_data: Dict[str, Any]):
+        """Handle incoming alert data."""
+        try:
+            alert_type = alert_data.get('type', 'unknown')
+            timestamp = alert_data.get('timestamp', 0)
+            
+            # Format timestamp
+            import time
+            formatted_time = time.strftime("%H:%M:%S", time.localtime(timestamp))
+            
+            # Print alert if requested
+            if print_alerts:
+                debug_print(f"🔔 [{formatted_time}] {alert_type.upper()}", "info")
+                
+                # Print additional data if available
+                alert_info = alert_data.get('data', {})
+                if alert_info:
+                    for key, value in list(alert_info.items())[:3]:  # Show first 3 items
+                        debug_print(f"   {key}: {value}", "info")
+            
+            # Save to file if requested
+            if save_to_file:
+                import json
+                with open(save_to_file, 'a', encoding='utf-8') as f:
+                    f.write(json.dumps({
+                        'timestamp': timestamp,
+                        'type': alert_type,
+                        'data': alert_data
+                    }) + '\n')
+                    
+        except Exception as e:
+            debug_print(f"❌ Error in alert callback: {e}", "error")
+    
+    return alert_callback
+
+@debug_function
+def quick_monitor_alerts(username: str, password: str,
+                        duration: int = 60,
+                        discord_webhook: Optional[str] = None,
+                        save_file: Optional[str] = None) -> int:
+    """
+    Quick function to monitor alerts for a specific duration.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        duration: Duration in seconds to monitor
+        discord_webhook: Optional Discord webhook URL
+        save_file: Optional file to save alerts
+        
+    Returns:
+        Number of alerts received
+    """
+    try:
+        import time
+        
+        # Create callback
+        callback = create_alert_callback(print_alerts=True, save_to_file=save_file)
+        
+        # Start alert stream
+        session = quick_start_alert_stream(
+            username=username,
+            password=password,
+            webhook_url=discord_webhook,
+            alert_types=["connection", "message", "connection_request", "connection_request_accepted"],
+            callback=callback
+        )
+        
+        if not session:
+            return 0
+        
+        debug_print(f"⏰ Monitoring alerts for {duration} seconds...", "info")
+        
+        # Monitor for specified duration
+        time.sleep(duration)
+        
+        debug_print(f"⏹️ Alert monitoring completed", "info")
+        
+        # Note: In a real implementation, you'd want to track alert count
+        # For now, return a placeholder
+        return 0
+        
+    except Exception as e:
+        debug_print(f"❌ Failed to monitor alerts: {e}", "error")
+        return 0

mc5_api_client/cli.py

@@ -447,7 +447,7 @@ class MC5CLI:
     
     def _print_version(self):
         """Print version information."""
-        self._print("MC5 API Client v1.0.15", "cyan")
+        self._print("MC5 API Client v1.0.16", "cyan")
         self._print("The ultimate Modern Combat 5 API library", "green")
         self._print("Author: Chizoba", "blue")
         self._print("Email: chizoba2026@hotmail.com", "blue")