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

mc5_api_client/debug.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : debug.py
+# | License  | MIT License © 2026 Chizoba
+# | Brief    | Enhanced debugging utilities for MC5 API Client
+# ────────────────★─────────────────────────────────
+
+import sys
+import traceback
+import json
+from typing import Optional, Dict, Any, Callable
+from datetime import datetime
+from .telemetry import is_telemetry_enabled, report_error
+
+class DebugContext:
+    """Context manager for debugging function calls."""
+    
+    def __init__(self, function_name: str, **kwargs):
+        self.function_name = function_name
+        self.kwargs = kwargs
+        self.start_time = None
+        
+    def __enter__(self):
+        self.start_time = datetime.now()
+        # if is_telemetry_enabled():
+        #     print(f"🔍 Debug: Starting {self.function_name}")
+        #     if self.kwargs:
+        #         print(f"🔍 Debug: Parameters: {json.dumps(self.kwargs, indent=2)}")
+        return self
+        
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        duration = (datetime.now() - self.start_time).total_seconds()
+        
+        if exc_type is None:
+            # if is_telemetry_enabled():
+            #     print(f"✅ Debug: {self.function_name} completed successfully ({duration:.2f}s)")
+            pass
+        else:
+            # if is_telemetry_enabled():
+            #     print(f"❌ Debug: {self.function_name} failed after {duration:.2f}s")
+            #     print(f"❌ Debug: Error: {exc_type.__name__}: {exc_val}")
+            #     print(f"❌ Debug: Traceback:\n{traceback.format_exc()}")
+            
+            # Report the error
+            report_error(exc_val, self.function_name, {
+                "duration": duration,
+                "parameters": self.kwargs
+            })
+
+def debug_function(func: Callable) -> Callable:
+    """
+    Decorator to add debugging to any function.
+    
+    Args:
+        func: Function to debug
+        
+    Returns:
+        Wrapped function with debugging
+    """
+    def wrapper(*args, **kwargs):
+        function_name = f"{func.__module__}.{func.__name__}"
+        
+        # Sanitize arguments for JSON serialization
+        safe_args = []
+        for arg in args:
+            if hasattr(arg, '__dict__'):
+                safe_args.append(f"<{type(arg).__name__} object>")
+            else:
+                safe_args.append(str(arg))
+        
+        safe_kwargs = {}
+        for key, value in kwargs.items():
+            if hasattr(value, '__dict__'):
+                safe_kwargs[key] = f"<{type(value).__name__} object>"
+            else:
+                safe_kwargs[key] = str(value)
+        
+        with DebugContext(function_name, args=safe_args, kwargs=safe_kwargs):
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except Exception as e:
+                # Re-raise the exception after reporting
+                raise
+    
+    return wrapper
+
+def debug_print(message: str, level: str = "info") -> None:
+    """
+    Print debug message with timestamp and level.
+    
+    Args:
+        message: Message to print
+        level: Debug level (info, warning, error, success)
+    """
+    timestamp = datetime.now().strftime("%H:%M:%S")
+    
+    icons = {
+        "info": "🔍",
+        "warning": "⚠️", 
+        "error": "❌",
+        "success": "✅",
+        "request": "📤",
+        "response": "📥"
+    }
+    
+    icon = icons.get(level, "🔍")
+    print(f"[{timestamp}] {icon} {message}")
+
+def debug_request(method: str, url: str, data: Optional[Dict[str, Any]] = None) -> None:
+    """
+    Debug HTTP request information.
+    
+    Args:
+        method: HTTP method
+        url: Request URL
+        data: Request data
+    """
+    debug_print(f"{method} {url}", "request")
+    if data:
+        debug_print(f"Data: {json.dumps(data, indent=2)}", "info")
+
+def debug_response(status_code: int, data: Optional[Dict[str, Any]] = None) -> None:
+    """
+    Debug HTTP response information.
+    
+    Args:
+        status_code: HTTP status code
+        data: Response data
+    """
+    if 200 <= status_code < 300:
+        debug_print(f"Response {status_code}: Success", "success")
+    else:
+        debug_print(f"Response {status_code}: Error", "error")
+    
+    if data:
+        # Truncate large responses for readability
+        data_str = json.dumps(data, indent=2)
+        if len(data_str) > 500:
+            data_str = data_str[:500] + "...\n[Response truncated]"
+        debug_print(f"Response data: {data_str}", "response")
+
+def analyze_error(error: Exception) -> Dict[str, Any]:
+    """
+    Analyze an error and provide debugging information.
+    
+    Args:
+        error: Exception to analyze
+        
+    Returns:
+        Dictionary with error analysis
+    """
+    error_type = type(error).__name__
+    error_message = str(error)
+    traceback_str = traceback.format_exc()
+    
+    analysis = {
+        "error_type": error_type,
+        "error_message": error_message,
+        "traceback": traceback_str,
+        "suggestions": []
+    }
+    
+    # Provide specific suggestions based on error type
+    if "AuthenticationError" in error_type or "401" in error_message:
+        analysis["suggestions"].extend([
+            "Check your username and password",
+            "Verify your account is not banned",
+            "Try re-authenticating with a fresh token"
+        ])
+    
+    elif "RateLimitError" in error_type or "429" in error_message:
+        analysis["suggestions"].extend([
+            "Wait before making more requests",
+            "Implement exponential backoff",
+            "Check rate limit headers for retry time"
+        ])
+    
+    elif "NetworkError" in error_type or "timeout" in error_message.lower():
+        analysis["suggestions"].extend([
+            "Check your internet connection",
+            "Try increasing timeout value",
+            "Verify MC5 servers are accessible"
+        ])
+    
+    elif "TokenExpiredError" in error_type:
+        analysis["suggestions"].extend([
+            "Enable auto_refresh in client",
+            "Call authenticate() again",
+            "Check token expiration time"
+        ])
+    
+    return analysis
+
+def print_error_analysis(error: Exception) -> None:
+    """
+    Print detailed error analysis with suggestions.
+    
+    Args:
+        error: Exception to analyze
+    """
+    analysis = analyze_error(error)
+    
+    debug_print(f"Error Analysis: {analysis['error_type']}", "error")
+    debug_print(f"Message: {analysis['error_message']}", "error")
+    
+    if analysis["suggestions"]:
+        debug_print("Suggestions:", "warning")
+        for i, suggestion in enumerate(analysis["suggestions"], 1):
+            debug_print(f"  {i}. {suggestion}", "warning")
+
+def create_debug_report() -> Dict[str, Any]:
+    """
+    Create a comprehensive debug report.
+    
+    Returns:
+        Debug report dictionary
+    """
+    import platform
+    import sys
+    
+    report = {
+        "timestamp": datetime.now().isoformat(),
+        "python_version": sys.version,
+        "platform": platform.platform(),
+        "architecture": platform.architecture(),
+        "system": platform.system(),
+        "mc5_client_version": "1.0.16",
+        "telemetry_enabled": is_telemetry_enabled()
+    }
+    
+    return report
+
+def print_debug_report() -> None:
+    """Print a comprehensive debug report."""
+    report = create_debug_report()
+    
+    debug_print("MC5 API Client Debug Report", "info")
+    debug_print("=" * 40, "info")
+    
+    for key, value in report.items():
+        debug_print(f"{key}: {value}", "info")
+
+# Convenience function for quick debugging
+def debug_mode(enable: bool = False) -> None:
+    """
+    Enable or disable debug mode.
+    
+    Args:
+        enable: Whether to enable debug mode (default: False)
+    """
+    if enable:
+        telemetry(True)
+        print_debug_report()
+        print("✅ Debug mode enabled")
+    else:
+        telemetry(False)
+        print("🔇 Debug mode disabled")

mc5_api_client/federation.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : federation.py
+# | License  | MIT License © 2026 Chizoba
+# | Brief    | Federation and session management APIs
+# ────────────────★─────────────────────────────────
+
+import json
+from typing import Optional, Dict, Any, List
+from .telemetry import report_error, report_usage
+from .debug import debug_function, debug_print
+
+class FederationMixin:
+    """Mixin class for federation and session management functionality."""
+    
+    # Federation endpoint
+    FEDERATION_BASE_URL = "https://federation-eur.gameloft.com"
+    
+    @debug_function
+    def get_active_sessions(self, credentials: Optional[List[str]] = None) -> Dict[str, Any]:
+        """
+        Get active game sessions from federation server.
+        
+        Args:
+            credentials: Optional list of user credentials to filter by
+            
+        Returns:
+            Session information with owner details
+        """
+        try:
+            url = f"{self.FEDERATION_BASE_URL}/sessions/{self.client_id}"
+            
+            # Always provide credentials parameter based on API discovery
+            if credentials:
+                credentials_str = ",".join(credentials)
+            else:
+                # Use current user's credential if none provided
+                user_credential = self._token_data.get("user_credential")
+                if not user_credential:
+                    # Extract from access_token if needed
+                    token_parts = self._token_data["access_token"].split(",")
+                    for part in token_parts:
+                        if "anonymous:" in part:
+                            user_credential = part.strip()
+                            break
+                credentials_str = user_credential if user_credential else ""
+            
+            params = {
+                "access_token": self._token_data["access_token"],
+                "credentials": credentials_str
+            }
+            
+            debug_print(f"🔍 Getting active sessions for {self.client_id}", "info")
+            result = self._make_request("GET", url, params=params)
+            
+            if result:
+                sessions = result.get("sessions", [])
+                debug_print(f"✅ Found {len(sessions)} active sessions", "success")
+                
+                # Analyze sessions
+                session_info = []
+                for session in sessions:
+                    owner = session.get("owner", {})
+                    session_data = {
+                        "session_id": session.get("created"),
+                        "client_id": session.get("client_id"),
+                        "created": session.get("created"),
+                        "owner_info": {
+                            "fed_id": owner.get("fed_id"),
+                            "credential": owner.get("credential"),
+                            "name": owner.get("name"),
+                            "server_type": owner.get("server_type"),
+                            "country": owner.get("country")
+                        }
+                    }
+                    session_info.append(session_data)
+                
+                report_usage("get_active_sessions", True, 0, {
+                    "sessions_found": len(sessions),
+                    "client_id": self.client_id
+                })
+                
+                return {
+                    "sessions": session_info,
+                    "total_count": len(sessions),
+                    "client_id": self.client_id
+                }
+            
+            return {"sessions": [], "total_count": 0}
+            
+        except Exception as e:
+            debug_print(f"❌ Failed to get active sessions: {e}", "error")
+            report_error(e, "get_active_sessions", {
+                "client_id": self.client_id,
+                "credentials_count": len(credentials) if credentials else 0
+            })
+            raise
+    
+    @debug_function
+    def get_my_sessions(self) -> Dict[str, Any]:
+        """
+        Get sessions for the current user.
+        
+        Returns:
+            User's active sessions
+        """
+        try:
+            # Use current user's credential
+            user_credential = self._token_data.get("user_credential")
+            if not user_credential:
+                # Extract from access_token if needed
+                token_parts = self._token_data["access_token"].split(",")
+                for part in token_parts:
+                    if "anonymous:" in part:
+                        user_credential = part.strip()
+                        break
+            
+            if user_credential:
+                return self.get_active_sessions([user_credential])
+            else:
+                debug_print("⚠️ Could not determine user credential", "warning")
+                return {"sessions": [], "total_count": 0}
+                
+        except Exception as e:
+            debug_print(f"❌ Failed to get user sessions: {e}", "error")
+            report_error(e, "get_my_sessions", {})
+            raise
+    
+    @debug_function
+    def get_session_statistics(self) -> Dict[str, Any]:
+        """
+        Get statistics about active sessions.
+        
+        Returns:
+            Session statistics and analytics
+        """
+        try:
+            sessions_data = self.get_active_sessions()
+            sessions = sessions_data.get("sessions", [])
+            
+            if not sessions:
+                return {"error": "No sessions found"}
+            
+            # Analyze session data
+            total_sessions = len(sessions)
+            
+            # Server type distribution
+            server_types = {}
+            countries = {}
+            
+            for session in sessions:
+                owner_info = session.get("owner_info", {})
+                
+                # Count server types
+                server_type = owner_info.get("server_type", "unknown")
+                server_types[server_type] = server_types.get(server_type, 0) + 1
+                
+                # Count countries
+                country = owner_info.get("country", "unknown")
+                countries[country] = countries.get(country, 0) + 1
+            
+            # Recent sessions (last 5)
+            recent_sessions = sorted(sessions, key=lambda x: x.get("created", ""), reverse=True)[:5]
+            
+            stats = {
+                "total_sessions": total_sessions,
+                "client_id": self.client_id,
+                "server_type_distribution": server_types,
+                "country_distribution": countries,
+                "recent_sessions": recent_sessions,
+                "analysis_timestamp": __import__('datetime').datetime.now().isoformat()
+            }
+            
+            debug_print(f"✅ Session statistics analyzed: {total_sessions} sessions", "success")
+            return stats
+            
+        except Exception as e:
+            debug_print(f"❌ Failed to analyze session statistics: {e}", "error")
+            report_error(e, "get_session_statistics", {})
+            raise
+    
+    @debug_function
+    def check_session_status(self, fed_id: str) -> Dict[str, Any]:
+        """
+        Check status of a specific session by federation ID.
+        
+        Args:
+            fed_id: Federation ID to check
+            
+        Returns:
+            Session status information
+        """
+        try:
+            sessions_data = self.get_active_sessions()
+            sessions = sessions_data.get("sessions", [])
+            
+            # Find session by fed_id
+            target_session = None
+            for session in sessions:
+                if session.get("owner_info", {}).get("fed_id") == fed_id:
+                    target_session = session
+                    break
+            
+            if target_session:
+                debug_print(f"✅ Found session for fed_id: {fed_id}", "success")
+                return {
+                    "found": True,
+                    "session": target_session,
+                    "status": "active"
+                }
+            else:
+                debug_print(f"⚠️ No session found for fed_id: {fed_id}", "warning")
+                return {
+                    "found": False,
+                    "status": "not_found"
+                }
+                
+        except Exception as e:
+            debug_print(f"❌ Failed to check session status: {e}", "error")
+            report_error(e, "check_session_status", {"fed_id": fed_id})
+            raise
+    
+    @debug_function
+    def get_server_type_sessions(self, server_type: str) -> Dict[str, Any]:
+        """
+        Get sessions filtered by server type.
+        
+        Args:
+            server_type: Server type to filter (ts, mp_server, etc.)
+            
+        Returns:
+            Filtered sessions by server type
+        """
+        try:
+            sessions_data = self.get_active_sessions()
+            sessions = sessions_data.get("sessions", [])
+            
+            # Filter by server type
+            filtered_sessions = []
+            for session in sessions:
+                owner_info = session.get("owner_info", {})
+                if owner_info.get("server_type") == server_type:
+                    filtered_sessions.append(session)
+            
+            debug_print(f"✅ Found {len(filtered_sessions)} {server_type} sessions", "success")
+            
+            return {
+                "server_type": server_type,
+                "sessions": filtered_sessions,
+                "total_count": len(filtered_sessions)
+            }
+            
+        except Exception as e:
+            debug_print(f"❌ Failed to get {server_type} sessions: {e}", "error")
+            report_error(e, "get_server_type_sessions", {"server_type": server_type})
+            raise