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

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

mc5_api_client/federation_quick.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : federation_quick.py
+# | License  | MIT License © 2026 Chizoba
+# | Brief    | Quick functions for federation and session management
+# ────────────────★─────────────────────────────────
+
+from typing import Optional, Dict, Any, List
+from .simple_client import SimpleMC5Client
+from .telemetry import report_usage
+from .debug import debug_function, debug_print
+
+@debug_function
+def quick_get_active_sessions(username: str, password: str, credentials: Optional[List[str]] = None) -> Optional[Dict[str, Any]]:
+    """
+    Quick function to get active game sessions.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        credentials: Optional list of user credentials to filter by
+        
+    Returns:
+        Session information or None if failed
+    """
+    try:
+        with SimpleMC5Client(username, password) as client:
+            if client.connect():
+                sessions = client.client.get_active_sessions(credentials)
+                debug_print(f"✅ Retrieved {sessions.get('total_count', 0)} active sessions", "success")
+                return sessions
+            return None
+    except Exception as e:
+        debug_print(f"❌ Failed to get active sessions: {e}", "error")
+        return None
+
+@debug_function
+def quick_get_my_sessions(username: str, password: str) -> Optional[Dict[str, Any]]:
+    """
+    Quick function to get current user's sessions.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        
+    Returns:
+        User's sessions or None if failed
+    """
+    try:
+        with SimpleMC5Client(username, password) as client:
+            if client.connect():
+                sessions = client.client.get_my_sessions()
+                debug_print(f"✅ Retrieved {sessions.get('total_count', 0)} user sessions", "success")
+                return sessions
+            return None
+    except Exception as e:
+        debug_print(f"❌ Failed to get user sessions: {e}", "error")
+        return None
+
+@debug_function
+def quick_get_session_statistics(username: str, password: str) -> Optional[Dict[str, Any]]:
+    """
+    Quick function to get session statistics.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        
+    Returns:
+        Session statistics or None if failed
+    """
+    try:
+        with SimpleMC5Client(username, password) as client:
+            if client.connect():
+                stats = client.client.get_session_statistics()
+                debug_print(f"✅ Session statistics analyzed: {stats.get('total_sessions', 0)} sessions", "success")
+                return stats
+            return None
+    except Exception as e:
+        debug_print(f"❌ Failed to get session statistics: {e}", "error")
+        return None
+
+@debug_function
+def quick_check_session_status(username: str, password: str, fed_id: str) -> Optional[Dict[str, Any]]:
+    """
+    Quick function to check status of a specific session.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        fed_id: Federation ID to check
+        
+    Returns:
+        Session status or None if failed
+    """
+    try:
+        with SimpleMC5Client(username, password) as client:
+            if client.connect():
+                status = client.client.check_session_status(fed_id)
+                if status.get("found"):
+                    debug_print(f"✅ Session found: {status.get('status')}", "success")
+                else:
+                    debug_print(f"⚠️ Session not found", "warning")
+                return status
+            return None
+    except Exception as e:
+        debug_print(f"❌ Failed to check session status: {e}", "error")
+        return None
+
+@debug_function
+def quick_get_server_type_sessions(username: str, password: str, server_type: str) -> Optional[Dict[str, Any]]:
+    """
+    Quick function to get sessions by server type.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        server_type: Server type (ts, mp_server, etc.)
+        
+    Returns:
+        Filtered sessions or None if failed
+    """
+    try:
+        with SimpleMC5Client(username, password) as client:
+            if client.connect():
+                sessions = client.client.get_server_type_sessions(server_type)
+                debug_print(f"✅ Found {sessions.get('total_count', 0)} {server_type} sessions", "success")
+                return sessions
+            return None
+    except Exception as e:
+        debug_print(f"❌ Failed to get {server_type} sessions: {e}", "error")
+        return None
+
+@debug_function
+def quick_analyze_session_activity(username: str, password: str) -> Optional[Dict[str, Any]]:
+    """
+    Quick function to analyze overall session activity.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        
+    Returns:
+        Activity analysis or None if failed
+    """
+    try:
+        with SimpleMC5Client(username, password) as client:
+            if client.connect():
+                # Get all sessions
+                all_sessions = client.client.get_active_sessions()
+                sessions = all_sessions.get("sessions", [])
+                
+                if not sessions:
+                    return {"error": "No sessions found"}
+                
+                # Analyze activity patterns
+                total_sessions = len(sessions)
+                
+                # Server type analysis
+                server_analysis = {}
+                country_analysis = {}
+                
+                for session in sessions:
+                    owner_info = session.get("owner_info", {})
+                    
+                    # Server types
+                    server_type = owner_info.get("server_type", "unknown")
+                    server_analysis[server_type] = server_analysis.get(server_type, 0) + 1
+                    
+                    # Countries
+                    country = owner_info.get("country", "unknown")
+                    country_analysis[country] = country_analysis.get(country, 0) + 1
+                
+                # Find most active server type
+                most_active_server = max(server_analysis.items(), key=lambda x: x[1]) if server_analysis else ("unknown", 0)
+                
+                # Find most active country
+                most_active_country = max(country_analysis.items(), key=lambda x: x[1]) if country_analysis else ("unknown", 0)
+                
+                analysis = {
+                    "total_sessions": total_sessions,
+                    "server_type_distribution": server_analysis,
+                    "country_distribution": country_analysis,
+                    "most_active_server_type": most_active_server[0],
+                    "most_active_server_count": most_active_server[1],
+                    "most_active_country": most_active_country[0],
+                    "most_active_country_count": most_active_country[1],
+                    "analysis_timestamp": __import__('datetime').datetime.now().isoformat()
+                }
+                
+                debug_print(f"✅ Activity analysis complete: {total_sessions} sessions", "success")
+                return analysis
+                
+            return None
+    except Exception as e:
+        debug_print(f"❌ Failed to analyze session activity: {e}", "error")
+        return None

mc5_api_client/pc_storage_client.py

@@ -0,0 +1,229 @@
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : pc_storage_client.py
+# | License  : MIT License © 2026 Chizoba
+# | Brief    | PC storage admin client for MC5 API
+# ────────────────★─────────────────────────────────
+
+"""
+PC Storage Admin Client for MC5 API with storage, storage_restricted, and storage_admin scopes.
+Provides advanced squad management capabilities for PC platform.
+"""
+
+from typing import Optional, Dict, Any, List
+from .client import MC5Client
+from .platform import Platform
+from .storage_admin import StorageAdminMixin
+from .auth import TokenGenerator
+from .exceptions import MC5APIError
+
+
+class PCStorageClient(MC5Client, StorageAdminMixin):
+    """
+    PC Storage Admin Client with advanced squad management capabilities.
+    
+    This client uses storage scopes to provide admin-level squad management
+    including deletion, comprehensive updates, and audit capabilities.
+    """
+    
+    def __init__(
+        self,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        device_id: Optional[str] = None,
+        scope: str = "alert auth chat leaderboard_ro lobby message session social config storage storage_restricted storage_admin tracking_bi feed storage leaderboard_admin social_eve social soc transaction schedule lottery voice matchmaker",
+        auto_refresh: bool = True,
+        timeout: int = 30
+    ):
+        """
+        Initialize PC Storage Admin Client.
+        
+        Args:
+            username: MC5 username (default: game:mc5_system)
+            password: Account password (default: admin)
+            device_id: Device ID (generated if not provided)
+            scope: Permission scopes with storage capabilities
+            auto_refresh: Whether to auto-refresh tokens
+            timeout: Request timeout in seconds
+            debug_mode: Enable debug mode
+        """
+        # Default to game:mc5_system for storage admin
+        if username is None:
+            username = "game:mc5_system"
+        if password is None:
+            password = "admin"
+        
+        # Set storage-specific attributes before calling parent constructor
+        self._storage_scope = scope
+        self._device_id = device_id or ""
+        self._username = username
+        self._password = password
+        
+        # Initialize with PC platform
+        super().__init__(
+            username=username,
+            password=password,
+            platform=Platform.PC,
+            client_id="1875:55979:6.0.0a:windows:windows",
+            auto_refresh=auto_refresh,
+            timeout=timeout
+        )
+        
+        # Override token generation for storage admin
+        self.token_generator = TokenGenerator()
+        
+        # Set storage base URL
+        self._storage_base_url = "https://eur-seshat.gameloft.com"
+    
+    def authenticate(
+        self, 
+        username: Optional[str] = None, 
+        password: Optional[str] = None, 
+        device_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Authenticate with storage admin scopes.
+        
+        Args:
+            username: Username (uses instance default if None)
+            password: Password (uses instance default if None)
+            device_id: Device ID (uses instance default if None)
+            
+        Returns:
+            Authentication response with storage scopes
+        """
+        username = username or self._username
+        password = password or self._password
+        device_id = device_id or self._device_id
+        
+        try:
+            token_data = self.token_generator.generate_token(
+                username=username,
+                password=password,
+                device_id=device_id,
+                scope=self._storage_scope
+            )
+            
+            self._token_data = token_data
+            self._username = username
+            
+            # Update session headers
+            self.session.headers.update({
+                "User-Agent": f"MC5-PC-Storage-Admin/1.0.17",
+                "Accept": "application/json",
+                "Content-Type": "application/json"
+            })
+            
+            return token_data
+            
+        except Exception as e:
+            raise MC5APIError(f"Storage admin authentication failed: {e}")
+    
+    def get_storage_info(self) -> Dict[str, Any]:
+        """
+        Get current storage admin information.
+        
+        Returns:
+            Storage admin information including scopes and capabilities
+        """
+        if not self._token_data:
+            return {"error": "Not authenticated"}
+        
+        return {
+            "username": self._username,
+            "platform": self.get_platform_info()["platform"],
+            "scopes": self._token_data.get("scopes", []),
+            "client_id": self.client_id,
+            "has_storage": "storage" in self._token_data.get("scopes", []),
+            "has_storage_restricted": "storage_restricted" in self._token_data.get("scopes", []),
+            "has_storage_admin": "storage_admin" in self._token_data.get("scopes", []),
+            "capabilities": self._get_storage_capabilities()
+        }
+    
+    def _get_storage_capabilities(self) -> List[str]:
+        """Get available storage capabilities based on scopes."""
+        scopes = self._token_data.get("scopes", [])
+        capabilities = []
+        
+        if "storage" in scopes:
+            capabilities.extend([
+                "read_squad_info",
+                "update_squad_info",
+                "get_all_squads",
+                "get_squad_audit_log"
+            ])
+        
+        if "storage_restricted" in scopes:
+            capabilities.extend([
+                "limited_squad_updates",
+                "read_squad_audit_log"
+            ])
+        
+        if "storage_admin" in scopes:
+            capabilities.extend([
+                "delete_squad",
+                "batch_delete_squads",
+                "transfer_squad_ownership",
+                "full_squad_management",
+                "admin_audit_access"
+            ])
+        
+        return capabilities
+    
+    def quick_squad_management_report(self, squad_id: str) -> Dict[str, Any]:
+        """
+        Generate a comprehensive squad management report.
+        
+        Args:
+            squad_id: Squad ID to analyze
+            
+        Returns:
+            Comprehensive squad report
+        """
+        try:
+            # Get squad info
+            squad_info = self.get_squad_storage_info(squad_id)
+            
+            # Get audit log if available
+            audit_log = None
+            if self._has_storage_capability("get_squad_audit_log"):
+                try:
+                    audit_log = self.get_squad_audit_log(squad_id, limit=10)
+                except:
+                    audit_log = {"error": "Audit log not available"}
+            
+            return {
+                "squad_id": squad_id,
+                "squad_info": squad_info,
+                "audit_log": audit_log,
+                "storage_capabilities": self._get_storage_capabilities(),
+                "available_actions": self._get_available_actions(squad_id)
+            }
+            
+        except Exception as e:
+            return {"error": f"Failed to generate report: {e}"}
+    
+    def _has_storage_capability(self, capability: str) -> bool:
+        """Check if a specific storage capability is available."""
+        return capability in self._get_storage_capabilities()
+    
+    def _get_available_actions(self, squad_id: str) -> List[str]:
+        """Get available actions for a squad based on storage capabilities."""
+        actions = []
+        
+        if self._has_storage_capability("read_squad_info"):
+            actions.append("read_info")
+        
+        if self._has_storage_capability("update_squad_info"):
+            actions.append("update_info")
+        
+        if self._has_storage_capability("delete_squad"):
+            actions.append("delete")
+        
+        if self._has_storage_capability("transfer_squad_ownership"):
+            actions.append("transfer_ownership")
+        
+        if self._has_storage_capability("get_squad_audit_log"):
+            actions.append("view_audit_log")
+        
+        return actions