mc5-api-client 1.0.16__py3-none-any.whl → 1.0.18__py3-none-any.whl

mc5_api_client/alerts.py

@@ -0,0 +1,336 @@
+#!/usr/bin/env python3
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : alerts.py
+# | License  | MIT License © 2026 Chizoba
+# | Brief    | Real-time alerts and streaming functionality
+# ────────────────★─────────────────────────────────
+
+import json
+import time
+import threading
+from typing import Optional, Dict, Any, List, Callable
+from .telemetry import report_error, report_usage
+from .debug import debug_function, debug_print
+
+class AlertsMixin:
+    """Mixin class for real-time alerts and streaming functionality."""
+    
+    @debug_function
+    def start_alert_stream(self, 
+                          webhook_url: Optional[str] = None,
+                          alert_types: List[str] = None,
+                          callback: Optional[Callable] = None) -> Dict[str, Any]:
+        """
+        Start real-time alert streaming for live notifications.
+        
+        Args:
+            webhook_url: Optional 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
+        """
+        try:
+            if alert_types is None:
+                alert_types = ["connection", "message", "connection_request", "connection_request_accepted"]
+            
+            # Get a fedex server endpoint (these appear to be load balanced)
+            fedex_servers = [
+                "eur-fedex-fsg006.gameloft.com:45040",
+                "eur-fedex-fsg002.gameloft.com:41245",
+                "eur-fedex-fsg001.gameloft.com:45040"
+            ]
+            
+            # Use first available server
+            server = fedex_servers[0]
+            url = f"https://{server}/alerts/me"
+            
+            params = {
+                "access_token": self._token_data["access_token"],
+                "content_type": "event-stream",
+                "push_method": "streaming",
+                "alert_types": ",".join(alert_types)
+            }
+            
+            debug_print(f"🌊 Starting alert stream from {server}", "info")
+            debug_print(f"📋 Alert types: {', '.join(alert_types)}", "info")
+            
+            # Create stream session info
+            session_info = {
+                "server": server,
+                "url": url,
+                "params": params,
+                "alert_types": alert_types,
+                "webhook_url": webhook_url,
+                "callback": callback,
+                "started_at": time.time(),
+                "status": "starting"
+            }
+            
+            # Start streaming in background thread
+            if callback:
+                stream_thread = threading.Thread(
+                    target=self._stream_alerts,
+                    args=(session_info,),
+                    daemon=True
+                )
+                stream_thread.start()
+                session_info["thread"] = stream_thread
+                session_info["status"] = "streaming"
+            
+            report_usage("start_alert_stream", True, 0, {
+                "server": server,
+                "alert_types_count": len(alert_types),
+                "has_webhook": webhook_url is not None,
+                "has_callback": callback is not None
+            })
+            
+            return session_info
+            
+        except Exception as e:
+            debug_print(f"❌ Failed to start alert stream: {e}", "error")
+            report_error(e, "start_alert_stream", {
+                "alert_types": alert_types,
+                "has_webhook": webhook_url is not None
+            })
+            raise
+    
+    def _stream_alerts(self, session_info: Dict[str, Any]):
+        """
+        Internal method to handle alert streaming.
+        
+        Args:
+            session_info: Stream session information
+        """
+        try:
+            import requests
+            
+            url = session_info["url"]
+            params = session_info["params"]
+            callback = session_info.get("callback")
+            webhook_url = session_info.get("webhook_url")
+            
+            debug_print("🌊 Connecting to alert stream...", "info")
+            
+            # Make streaming request
+            response = requests.get(url, params=params, stream=True, timeout=30)
+            
+            if response.status_code == 200:
+                debug_print("✅ Alert stream connected", "success")
+                
+                # Process stream events
+                for line in response.iter_lines(decode_unicode=True):
+                    if line and line.strip():
+                        try:
+                            # Parse alert data
+                            if line.startswith("data: "):
+                                alert_data = line[6:]  # Remove "data: " prefix
+                                alert_json = json.loads(alert_data)
+                                
+                                # Process alert
+                                self._process_alert(alert_json, callback, webhook_url)
+                                
+                        except json.JSONDecodeError:
+                            debug_print(f"⚠️ Invalid alert data: {line[:50]}...", "warning")
+                        except Exception as e:
+                            debug_print(f"⚠️ Error processing alert: {e}", "warning")
+            else:
+                debug_print(f"❌ Alert stream failed: {response.status_code}", "error")
+                
+        except Exception as e:
+            debug_print(f"❌ Alert stream error: {e}", "error")
+            report_error(e, "_stream_alerts", session_info)
+    
+    def _process_alert(self, 
+                      alert_data: Dict[str, Any], 
+                      callback: Optional[Callable] = None,
+                      webhook_url: Optional[str] = None):
+        """
+        Process incoming alert data.
+        
+        Args:
+            alert_data: Alert data from stream
+            callback: Optional callback function
+            webhook_url: Optional webhook URL for forwarding
+        """
+        try:
+            alert_type = alert_data.get("type", "unknown")
+            timestamp = alert_data.get("timestamp", time.time())
+            
+            debug_print(f"🔔 Received alert: {alert_type}", "info")
+            
+            # Format alert for processing
+            formatted_alert = {
+                "type": alert_type,
+                "timestamp": timestamp,
+                "data": alert_data,
+                "received_at": time.time()
+            }
+            
+            # Call callback if provided
+            if callback:
+                try:
+                    callback(formatted_alert)
+                except Exception as e:
+                    debug_print(f"⚠️ Callback error: {e}", "warning")
+            
+            # Forward to webhook if provided
+            if webhook_url:
+                try:
+                    self._forward_alert_to_webhook(formatted_alert, webhook_url)
+                except Exception as e:
+                    debug_print(f"⚠️ Webhook forwarding error: {e}", "warning")
+            
+        except Exception as e:
+            debug_print(f"❌ Error processing alert: {e}", "error")
+    
+    def _forward_alert_to_webhook(self, alert: Dict[str, Any], webhook_url: str):
+        """
+        Forward alert to Discord webhook.
+        
+        Args:
+            alert: Formatted alert data
+            webhook_url: Discord webhook URL
+        """
+        try:
+            import requests
+            
+            # Create Discord embed
+            alert_type = alert.get("type", "unknown")
+            timestamp = alert.get("timestamp", time.time())
+            
+            embed = {
+                "title": f"🔔 MC5 Alert: {alert_type.upper()}",
+                "description": f"Real-time alert received from MC5 servers",
+                "color": 5814783,  # Blue color
+                "fields": [
+                    {
+                        "name": "Alert Type",
+                        "value": alert_type,
+                        "inline": True
+                    },
+                    {
+                        "name": "Timestamp", 
+                        "value": f"<t:{int(timestamp)}:R>",
+                        "inline": True
+                    },
+                    {
+                        "name": "Server",
+                        "value": "eur-fedex servers",
+                        "inline": True
+                    }
+                ],
+                "footer": {
+                    "text": "MC5 API Client - Real-time Alerts"
+                },
+                "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime())
+            }
+            
+            # Add alert data if available
+            alert_data = alert.get("data", {})
+            if alert_data:
+                # Add relevant data fields
+                for key, value in list(alert_data.items())[:5]:  # Limit to 5 fields
+                    if isinstance(value, (str, int, float, bool)):
+                        embed["fields"].append({
+                            "name": key.replace("_", " ").title(),
+                            "value": str(value),
+                            "inline": True
+                        })
+            
+            payload = {
+                "embeds": [embed],
+                "username": "MC5 Alerts"
+            }
+            
+            # Send to webhook
+            response = requests.post(webhook_url, json=payload, timeout=10)
+            
+            if response.status_code == 204:
+                debug_print(f"✅ Alert forwarded to webhook: {alert_type}", "success")
+            else:
+                debug_print(f"⚠️ Webhook response: {response.status_code}", "warning")
+                
+        except Exception as e:
+            debug_print(f"❌ Webhook forwarding failed: {e}", "error")
+            raise
+    
+    @debug_function
+    def test_alert_connection(self) -> Dict[str, Any]:
+        """
+        Test connection to alert servers.
+        
+        Returns:
+            Connection test results
+        """
+        try:
+            import requests
+            
+            fedex_servers = [
+                "eur-fedex-fsg006.gameloft.com:45040",
+                "eur-fedex-fsg002.gameloft.com:41245",
+                "eur-fedex-fsg001.gameloft.com:45040"
+            ]
+            
+            results = []
+            
+            for server in fedex_servers:
+                try:
+                    url = f"https://{server}/alerts/me"
+                    params = {
+                        "access_token": self._token_data["access_token"],
+                        "content_type": "event-stream",
+                        "push_method": "streaming"
+                    }
+                    
+                    # Test connection (short timeout)
+                    response = requests.get(url, params=params, timeout=5, stream=True)
+                    
+                    server_result = {
+                        "server": server,
+                        "status_code": response.status_code,
+                        "connected": response.status_code == 200,
+                        "response_time": response.elapsed.total_seconds() if hasattr(response, 'elapsed') else 0
+                    }
+                    
+                    if response.status_code == 200:
+                        debug_print(f"✅ {server}: Connected", "success")
+                    else:
+                        debug_print(f"❌ {server}: {response.status_code}", "error")
+                    
+                    results.append(server_result)
+                    
+                    # Close connection
+                    response.close()
+                    
+                except Exception as e:
+                    debug_print(f"❌ {server}: {e}", "error")
+                    results.append({
+                        "server": server,
+                        "status_code": 0,
+                        "connected": False,
+                        "error": str(e)
+                    })
+            
+            # Find best server
+            connected_servers = [r for r in results if r.get("connected")]
+            best_server = None
+            
+            if connected_servers:
+                best_server = min(connected_servers, key=lambda x: x.get("response_time", float('inf')))
+            
+            debug_print(f"🎯 Best server: {best_server.get('server') if best_server else 'None'}", "info")
+            
+            return {
+                "results": results,
+                "connected_count": len(connected_servers),
+                "best_server": best_server,
+                "total_tested": len(results)
+            }
+            
+        except Exception as e:
+            debug_print(f"❌ Alert connection test failed: {e}", "error")
+            report_error(e, "test_alert_connection", {})
+            raise

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