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

mc5_api_client/easy_mc5.py

@@ -0,0 +1,682 @@
+#!/usr/bin/env python3
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : easy_mc5.py
+# | License  : MIT License © 2026 Chizoba
+# | Brief    | Easy-to-use MC5 functions for everyday tasks
+# ────────────────★─────────────────────────────────
+
+"""
+Easy MC5 - Simplified Interface for Everyday Tasks
+==================================================
+
+This module provides simple, one-line functions for the most common MC5 tasks.
+No complex setup, no confusing API calls - just simple functions that work.
+
+Quick Start:
+    from mc5_api_client.easy_mc5 import MC5Easy
+    
+    # Initialize with your credentials
+    mc5 = MC5Easy("your_credential", "your_password")
+    
+    # Check your daily tasks
+    tasks = mc5.check_daily_tasks()
+    
+    # Get your profile
+    profile = mc5.get_my_profile()
+    
+    # Search for a player
+    player = mc5.find_player("f55f")
+    
+    # Send a message
+    mc5.send_message_to_friend("f55f", "Hello!")
+"""
+
+import os
+from typing import Optional, Dict, Any, List
+from .client import MC5Client, Platform
+from .exceptions import MC5APIError
+
+
+class MC5Easy:
+    """
+    Easy-to-use MC5 client for everyday tasks.
+    
+    Simplifies common MC5 operations into simple, one-line functions.
+    """
+    
+    def __init__(self, username: str = None, password: str = None, platform: Platform = Platform.PC):
+        """
+        Initialize MC5Easy client.
+        
+        Args:
+            username: MC5 credential (can be set via environment variable MC5_USERNAME)
+            password: MC5 password (can be set via environment variable MC5_PASSWORD)
+            platform: Platform to use (PC or Android)
+        """
+        self.username = username or os.getenv('MC5_USERNAME')
+        self.password = password or os.getenv('MC5_PASSWORD')
+        self.platform = platform
+        self.client = None
+        self._connected = False
+        
+        if not self.username or not self.password:
+            raise ValueError("Username and password are required. Set them directly or use MC5_USERNAME and MC5_PASSWORD environment variables.")
+    
+    def connect(self) -> bool:
+        """Connect to MC5 servers."""
+        try:
+            self.client = MC5Client(
+                username=self.username,
+                password=self.password,
+                platform=self.platform
+            )
+            self.client.authenticate()
+            self._connected = True
+            return True
+        except Exception as e:
+            print(f"❌ Connection failed: {e}")
+            self._connected = False
+            return False
+    
+    def is_connected(self) -> bool:
+        """Check if connected to MC5."""
+        return self._connected and self.client is not None
+    
+    def _ensure_connected(self):
+        """Ensure we're connected to MC5."""
+        if not self.is_connected():
+            if not self.connect():
+                raise ConnectionError("Not connected to MC5. Call connect() first.")
+    
+    # === PROFILE FUNCTIONS ===
+    
+    def get_my_profile(self) -> Dict[str, Any]:
+        """Get your profile information."""
+        self._ensure_connected()
+        try:
+            profile = self.client.get_profile()
+            return profile
+        except Exception as e:
+            print(f"❌ Error getting profile: {e}")
+            return {}
+    
+    def get_my_stats(self) -> Dict[str, Any]:
+        """Get your stats in a simple format."""
+        profile = self.get_my_profile()
+        if not profile:
+            return {}
+        
+        return {
+            'name': profile.get('name', 'Unknown'),
+            'level': profile.get('level') or profile.get('_level') or profile.get('player_level') or 'Unknown',
+            'xp': profile.get('xp') or profile.get('_xp') or profile.get('experience') or 0,
+            'score': profile.get('score') or profile.get('_score') or profile.get('player_score') or 0,
+            'clan_id': profile.get('groups', [None])[0]
+        }
+    
+    # === PLAYER SEARCH FUNCTIONS ===
+    
+    def find_player(self, dogtag: str) -> Dict[str, Any]:
+        """Find a player by dogtag."""
+        self._ensure_connected()
+        try:
+            player = self.client.search_player(dogtag)
+            if player and 'kills' in player:
+                return {
+                    'dogtag': dogtag,
+                    'found': True,
+                    'kills': player.get('kills', 0),
+                    'level': player.get('level') or player.get('_level') or player.get('player_level') or 'Unknown',
+                    'score': player.get('score') or player.get('_score') or player.get('player_score') or 0,
+                    'wins': player.get('wins', 0),
+                    'losses': player.get('losses', 0),
+                    'draws': player.get('draws', 0)
+                }
+            else:
+                return {'dogtag': dogtag, 'found': False}
+        except Exception as e:
+            print(f"❌ Error finding player {dogtag}: {e}")
+            return {'dogtag': dogtag, 'found': False, 'error': str(e)}
+    
+    def compare_players(self, dogtag1: str, dogtag2: str) -> Dict[str, Any]:
+        """Compare two players."""
+        player1 = self.find_player(dogtag1)
+        player2 = self.find_player(dogtag2)
+        
+        return {
+            'player1': player1,
+            'player2': player2,
+            'comparison': {
+                'player1_wins_kills': player1.get('kills', 0) > player2.get('kills', 0),
+                'player1_wins_score': player1.get('score', 0) > player2.get('score', 0),
+                'player1_wins_level': player1.get('level', 0) > player2.get('level', 0)
+            }
+        }
+    
+    # === CLAN/SQUAD FUNCTIONS ===
+    
+    def get_my_clan_members(self) -> List[Dict[str, Any]]:
+        """Get your clan members."""
+        self._ensure_connected()
+        try:
+            # First get profile to find clan ID
+            profile = self.get_my_profile()
+            clan_id = profile.get('groups', [None])[0]
+            
+            if not clan_id:
+                return []
+            
+            members = self.client.get_group_members(clan_id)
+            return members
+        except Exception as e:
+            print(f"❌ Error getting clan members: {e}")
+            return []
+    
+    def get_clan_stats(self) -> Dict[str, Any]:
+        """Get clan statistics."""
+        members = self.get_my_clan_members()
+        if not members:
+            return {}
+        
+        online_count = len([m for m in members if m.get('online', False)])
+        total_score = sum(int(m.get('_score') or m.get('score') or 0) for m in members)
+        avg_score = total_score // len(members) if members else 0
+        
+        # Sort by score
+        sorted_members = sorted(members, key=lambda x: int(x.get('_score') or x.get('score') or 0), reverse=True)
+        
+        return {
+            'total_members': len(members),
+            'online_members': online_count,
+            'total_score': total_score,
+            'average_score': avg_score,
+            'top_member': sorted_members[0] if sorted_members else None,
+            'top_5_members': sorted_members[:5]
+        }
+    
+    # === DAILY TASKS FUNCTIONS ===
+    
+    def check_daily_tasks(self) -> List[Dict[str, Any]]:
+        """Check your daily tasks."""
+        self._ensure_connected()
+        try:
+            events = self.client.get_events()
+            daily_tasks = [e for e in events if 'daily' in e.get('name', '').lower() or 'activities' in e.get('name', '').lower()]
+            return daily_tasks
+        except Exception as e:
+            print(f"❌ Error checking daily tasks: {e}")
+            return []
+    
+    def get_daily_summary(self) -> Dict[str, Any]:
+        """Get a summary of your daily status."""
+        tasks = self.check_daily_tasks()
+        profile = self.get_my_stats()
+        clan_stats = self.get_clan_stats()
+        
+        return {
+            'daily_tasks': {
+                'count': len(tasks),
+                'tasks': tasks
+            },
+            'profile': profile,
+            'clan': clan_stats
+        }
+    
+    # === MESSAGING FUNCTIONS ===
+    
+    def send_message_to_friend(self, dogtag: str, message: str) -> bool:
+        """Send a message to a friend."""
+        self._ensure_connected()
+        try:
+            result = self.client.send_private_message(dogtag, message)
+            return result is not None
+        except Exception as e:
+            print(f"❌ Error sending message to {dogtag}: {e}")
+            return False
+    
+    def broadcast_to_clan(self, message: str) -> bool:
+        """Broadcast a message to your clan wall."""
+        self._ensure_connected()
+        try:
+            profile = self.get_my_profile()
+            clan_id = profile.get('groups', [None])[0]
+            
+            if not clan_id:
+                print("❌ Not in a clan")
+                return False
+            
+            result = self.client.post_group_wall(clan_id, message)
+            return result is not None
+        except Exception as e:
+            print(f"❌ Error broadcasting to clan: {e}")
+            return False
+    
+    # === UTILITY FUNCTIONS ===
+    
+    def quick_status(self) -> str:
+        """Get a quick status overview."""
+        try:
+            profile = self.get_my_stats()
+            tasks = self.check_daily_tasks()
+            clan_stats = self.get_clan_stats()
+            
+            status = f"🎮 MC5 Status:\n"
+            status += f"👤 Player: {profile.get('name', 'Unknown')} (Level {profile.get('level', 'Unknown')})\n"
+            status += f"⭐ XP: {profile.get('xp', 0):,}\n"
+            status += f"💰 Score: {profile.get('score', 0):,}\n"
+            status += f"📅 Daily Tasks: {len(tasks)} pending\n"
+            
+            if clan_stats.get('total_members', 0) > 0:
+                status += f"🏰 Clan: {clan_stats['total_members']} members ({clan_stats['online_members']} online)\n"
+            
+            return status
+        except Exception as e:
+            return f"❌ Error getting status: {e}"
+    
+    def run_daily_routine(self) -> Dict[str, Any]:
+        """Run a complete daily routine."""
+        print("🚀 Running daily MC5 routine...")
+        
+        results = {
+            'profile': self.get_my_stats(),
+            'daily_tasks': self.check_daily_tasks(),
+            'clan_stats': self.get_clan_stats(),
+            'status': self.quick_status()
+        }
+        
+        print("✅ Daily routine completed!")
+        return results
+    
+    def close(self):
+        """Close the connection."""
+        if self.client:
+            self.client.close()
+            self._connected = False
+    
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()
+    
+    # === DEVICE ID FUNCTIONS ===
+    
+    def get_global_id(self, device_id: str = None, device_type: str = "w10", hdidfv: str = None) -> str:
+        """
+        Get a global device ID from Gameloft's global ID service.
+        
+        Args:
+            device_id: Your device ID (optional, will generate one if not provided)
+            device_type: Device type (w10, android, ios, etc.)
+            hdidfv: Hardware ID fingerprint (optional)
+            
+        Returns:
+            Global device ID string
+        """
+        self._ensure_connected()
+        
+        try:
+            # Build request parameters
+            params = {
+                "source": "Identifiers_6.0.0",
+                "client_id": "1875:55979:6.0.0a:windows:windows",
+                "device_type": device_type,
+                "global_device_id": device_id or "1364509832654538259",
+                "hdidfv": hdidfv or "76dfc72e-7850-4d9e-b79c-9861c7e3ea20"
+            }
+            
+            headers = {
+                "Accept": "*/*",
+                "Accept-Encoding": "gzip;q=1.0, deflate;q=1.0, identity;q=0.5, *;q=0"
+            }
+            
+            # Make request
+            response = self.client.session.get(
+                "https://gdid.datalake.gameloft.com/assign_global_id/",
+                params=params,
+                headers=headers,
+                timeout=30
+            )
+            
+            if response.status_code == 200:
+                return response.text.strip()
+            else:
+                print(f"❌ Global ID request failed: {response.status_code}")
+                return ""
+        
+        except Exception as e:
+            print(f"❌ Error getting global ID: {e}")
+            return ""
+    
+    def get_device_info(self) -> Dict[str, Any]:
+        """
+        Get comprehensive device information including global ID.
+        
+        Returns:
+            Dictionary with device information
+        """
+        self._ensure_connected()
+        
+        try:
+            # Get global ID
+            global_id = self.get_global_id()
+            
+            # Get device info from profile
+            profile = self.get_my_stats()
+            
+            return {
+                "global_id": global_id,
+                "device_type": "w10",  # Default for PC
+                "client_id": "1875:55979:6.0.0a:windows:windows",
+                "profile_name": profile.get('name', 'Unknown'),
+                "profile_level": profile.get('level', 'Unknown'),
+                "profile_score": profile.get('score', 0),
+                "has_clan": bool(profile.get('clan_id')),
+                "timestamp": "Unknown"
+            }
+            
+        except Exception as e:
+            print(f"❌ Error getting device info: {e}")
+            return {"error": str(e)}
+    
+    def generate_device_id(self) -> str:
+        """
+        Generate a unique device ID for the current device.
+        
+        Returns:
+            Generated device ID string
+        """
+        import uuid
+        import random
+        import string
+        
+        # Generate a unique device ID
+        device_id = f"mc5_{uuid.uuid4().hex[:16]}"
+        return device_id
+    
+    # === FEDERATION SESSION FUNCTIONS ===
+    
+    def create_federation_session(self, device_id: str = None) -> Dict[str, Any]:
+        """
+        Create a federation session for MC5 game launch.
+        
+        Args:
+            device_id: Device ID for the session (optional)
+            
+        Returns:
+            Dictionary with session information
+        """
+        self._ensure_connected()
+        
+        try:
+            # Build request parameters
+            params = {
+                "password": self.password,
+                "device_id": device_id or "1364509832654538259"
+            }
+            
+            headers = {
+                "Accept": "*/*",
+                "Content-Type": "application/x-www-form-urlencoded"
+            }
+            
+            # Build URL with encoded credential
+            encoded_credential = self.username.replace(":", "%3A")
+            url = f"https://federation-eur.gameloft.com/sessions/1875%3A55979%3A6.0.0a%3Awindows%3Awindows/{encoded_credential}"
+            
+            # Make request
+            response = self.client.session.post(
+                url,
+                data=params,
+                headers=headers,
+                timeout=30
+            )
+            
+            if response.status_code == 200:
+                return {
+                    "status": "OK",
+                    "response": response.text.strip(),
+                    "service_type": service_type,
+                    "timestamp": params["timestamp"],
+                    "domain": params["domain"]
+                }
+            else:
+                return {
+                    "status": "Failed",
+                    "error": f"HTTP {response.status_code}",
+                    "response": response.text,
+                    "service_type": service_type
+                }
+        
+        except Exception as e:
+            print(f"❌ Error checking connection status: {e}")
+            return {"error": str(e), "service_type": service_type}
+    
+    def get_connection_status_all(self) -> Dict[str, Any]:
+        """
+        Check connection status for all services.
+        
+        Returns:
+            Dictionary with all service connection statuses
+        """
+        services = ["auth", "matchmaking", "lobby", "gs", "sp"]
+        
+        connection_statuses = {}
+        
+        for service in services:
+            status = self.check_connection_status(service)
+            connection_statuses[service] = status
+        
+        return connection_statuses
+    
+    # === ROOM FINDER FUNCTIONS ===
+    
+    def find_rooms(self, clan_id: str = None, clan_battle_room: bool = False, server_type: str = "mp_server") -> List[Dict[str, Any]]:
+        """
+        Find available rooms using AnubisFinder.
+        
+        Args:
+            clan_id: Clan ID to filter rooms (optional)
+            clan_battle_room: Filter for clan battle rooms (optional)
+            server_type: Server type (mp_server)
+            
+        Returns:
+            List of room dictionaries
+        """
+        self._ensure_connected()
+        
+        try:
+            # Build request parameters
+            params = {
+                "_can_spectate": "false",
+                "_customs_room": "true",
+                "_event_id": "x",
+                "_joinable": "true",
+                "_public": "true",
+                "full": "false",
+                "game_started": "true",
+                "server_type": server_type
+            }
+            
+            # Add clan filters if provided
+            if clan_id:
+                params["_clan_" + clan_id] = "true"
+            
+            if clan_battle_room:
+                params["_clan_battle_room"] = "true"
+            
+            headers = {
+                "Accept": "*/*"
+            }
+            
+            # Make request
+            response = self.client.session.get(
+                "https://eur-anubisfinder.gameloft.com/rooms/1875:55979:6.0.0a:windows:windows",
+                params=params,
+                headers=headers,
+                timeout=30
+            )
+            
+            if response.status_code == 200:
+                try:
+                    rooms = response.json()
+                    return rooms if isinstance(rooms, list) else []
+                except:
+                    return []
+            else:
+                print(f"❌ Room finder failed: {response.status_code}")
+                return []
+        
+        except Exception as e:
+            print(f"❌ Error finding rooms: {e}")
+            return []
+    
+    def get_available_rooms(self, clan_id: str = None) -> Dict[str, Any]:
+        """
+        Get comprehensive room information.
+        
+        Args:
+            clan_id: Clan ID to filter rooms (optional)
+            
+        Returns:
+            Dictionary with room information
+        """
+        rooms = self.find_rooms(clan_id=clan_id)
+        
+        return {
+            "total_rooms": len(rooms),
+            "rooms": rooms,
+            "clan_id": clan_id,
+            "timestamp": "2026-02-03 22:10:19"
+        }
+    
+    def _parse_access_token(self, access_token: str) -> Dict[str, Any]:
+        """
+        Parse the access token into its components.
+        
+        Args:
+            access_token: The access token string
+            
+        Returns:
+            Dictionary with parsed token components
+        """
+        try:
+            # Split the token by commas
+            parts = access_token.split(',')
+            
+            if len(parts) >= 6:
+                return {
+                    "token_id": parts[0],
+                    "scopes": parts[1],
+                    "client_id": parts[2],
+                    "timestamp": parts[3],
+                    "credential": parts[4],
+                    "device_id": parts[5],
+                    "signature": parts[6] if len(parts) > 6 else ""
+                }
+            else:
+                return {"raw_token": access_token, "parts": parts}
+        except Exception as e:
+            return {"error": str(e), "raw_token": access_token}
+    
+    def launch_game_session(self, device_id: str = None) -> Dict[str, Any]:
+        """
+        Create a federation session and prepare for game launch.
+        
+        Args:
+            device_id: Device ID for the session (optional)
+            
+        Returns:
+            Dictionary with launch information
+        """
+        session_data = self.create_federation_session(device_id)
+        
+        if session_data.get("success"):
+            return {
+                "success": True,
+                "message": "Game session ready for launch",
+                "room_id": session_data.get("room_id"),
+                "controller": {
+                    "host": session_data.get("controller_host"),
+                    "tcp_port": session_data.get("controller_tcp_port"),
+                    "http_port": session_data.get("controller_http_port"),
+                    "https_port": session_data.get("controller_https_port")
+                },
+                "access_token": session_data.get("access_token"),
+                "encrypted_access_token": session_data.get("encrypted_access_token"),
+                "parsed_token": session_data.get("parsed_access_token"),
+                "launch_command": self._build_launch_command(session_data)
+            }
+        else:
+            return session_data
+    
+    def _build_launch_command(self, session_data: Dict[str, Any]) -> str:
+        """
+        Build a launch command for the MC5 game.
+        
+        Args:
+            session_data: Session data from federation
+            
+        Returns:
+            Launch command string
+        """
+        host = session_data.get("controller_host", "localhost")
+        room_id = session_data.get("room_id", "")
+        access_token = session_data.get("access_token", "")
+        
+        # This is a simplified launch command
+        return f"mc5://launch?host={host}&room={room_id}&token={access_token}"
+    
+    def get_session_info(self, device_id: str = None) -> Dict[str, Any]:
+        """
+        Get comprehensive session information.
+        
+        Args:
+            device_id: Device ID for the session (optional)
+            
+        Returns:
+            Dictionary with session information
+        """
+        session_data = self.create_federation_session(device_id)
+        
+        if session_data.get("success"):
+            return {
+                "session": session_data,
+                "device_info": self.get_device_info(),
+                "global_id": self.get_global_id(device_id),
+                "timestamp": session_data.get("parsed_access_token", {}).get("timestamp", "Unknown")
+            }
+        else:
+            return session_data
+
+
+# === CONVENIENCE FUNCTIONS ===
+
+def quick_connect(username: str = None, password: str = None) -> MC5Easy:
+    """Quick connect to MC5 with credentials."""
+    mc5 = MC5Easy(username, password)
+    mc5.connect()
+    return mc5
+
+def check_my_daily_tasks(username: str = None, password: str = None) -> List[Dict[str, Any]]:
+    """Quick check of daily tasks."""
+    with quick_connect(username, password) as mc5:
+        return mc5.check_daily_tasks()
+
+def get_my_mc5_profile(username: str = None, password: str = None) -> Dict[str, Any]:
+    """Quick get of profile."""
+    with quick_connect(username, password) as mc5:
+        return mc5.get_my_stats()
+
+def find_mc5_player(dogtag: str, username: str = None, password: str = None) -> Dict[str, Any]:
+    """Quick find player."""
+    with quick_connect(username, password) as mc5:
+        return mc5.find_player(dogtag)
+
+def send_mc5_message(dogtag: str, message: str, username: str = None, password: str = None) -> bool:
+    """Quick send message."""
+    with quick_connect(username, password) as mc5:
+        return mc5.send_message_to_friend(dogtag, message)