mc5-api-client 1.0.6__py3-none-any.whl → 1.0.9__py3-none-any.whl

mc5_api_client/simple_client.py

@@ -0,0 +1,570 @@
+#!/usr/bin/env python3
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : simple_client.py
+# | License  | MIT License © 2026 Chizoba
+# | Brief    : User-friendly MC5 API client for non-developers
+# ────────────────★─────────────────────────────────
+
+"""
+MC5 Simple API Client - User Friendly Interface
+
+A simplified version of the MC5 API Client designed for non-developers.
+Provides easy-to-use methods with automatic clan detection and simplified syntax.
+"""
+
+from typing import Optional, Dict, Any, List
+from .client import MC5Client
+from .exceptions import MC5APIError
+
+class SimpleMC5Client:
+    """
+    User-friendly MC5 API client for non-developers.
+    
+    Automatically handles clan detection and provides simplified methods
+    for common operations.
+    """
+    
+    def __init__(self, username: str, password: str):
+        """
+        Initialize the client with your MC5 credentials.
+        
+        Args:
+            username: Your MC5 username (e.g., "anonymous:your_credential")
+            password: Your MC5 password
+        """
+        self.username = username
+        self.password = password
+        self.client = None
+        self._clan_id = None
+        self._profile = None
+        
+    def connect(self) -> bool:
+        """
+        Connect to MC5 and auto-detect your clan.
+        
+        Returns:
+            True if connection successful, False otherwise
+        """
+        try:
+            # Create the client only when connecting
+            self.client = MC5Client(self.username, self.password)
+            
+            # Get profile info
+            self._profile = self.client.get_profile()
+            
+            # Auto-detect clan ID
+            groups = self._profile.get('groups', [])
+            if groups:
+                self._clan_id = groups[0]
+                print(f"✅ Connected! Auto-detected clan: {self._get_clan_name()}")
+                return True
+            else:
+                print("⚠️ Connected but no clan found")
+                return True
+                
+        except Exception as e:
+            print(f"❌ Connection failed: {e}")
+            return False
+    
+    def _get_clan_name(self) -> str:
+        """Get the clan name if available."""
+        if not self._clan_id:
+            return "No clan"
+        
+        try:
+            clan_info = self.client.get_clan_info(self._clan_id)
+            return clan_info.get('name', 'Unknown clan')
+        except:
+            return "Unknown clan"
+    
+    def search_player(self, dogtag: str) -> Optional[Dict[str, Any]]:
+        """
+        Search for a player by their dogtag.
+        
+        Args:
+            dogtag: Player's dogtag (4-8 characters)
+            
+        Returns:
+            Player information or None if not found
+        """
+        try:
+            stats = self.client.get_player_stats_by_dogtag(dogtag)
+            if 'error' not in stats:
+                # Parse and return simplified info
+                player_credential = list(stats.keys())[0]
+                player_data = stats[player_credential]
+                parsed = self.client.parse_player_stats(stats)
+                
+                return {
+                    'dogtag': dogtag,
+                    'account': player_data.get('player_info', {}).get('account', 'Unknown'),
+                    'rating': parsed.get('rating', 0),
+                    'kills': parsed.get('overall_stats', {}).get('total_kills', 0),
+                    'deaths': parsed.get('overall_stats', {}).get('total_deaths', 0),
+                    'kd_ratio': parsed.get('overall_stats', {}).get('kd_ratio', 0),
+                    'headshot_percent': parsed.get('overall_stats', {}).get('headshot_percentage', 0),
+                    'play_time': parsed.get('overall_stats', {}).get('play_time', 0)
+                }
+            else:
+                print(f"❌ Player not found: {stats['error']}")
+                return None
+                
+        except Exception as e:
+            print(f"❌ Error searching player: {e}")
+            return None
+    
+    def get_my_stats(self) -> Optional[Dict[str, Any]]:
+        """
+        Get your own player statistics.
+        
+        Returns:
+            Your player information or None if error
+        """
+        if not self._profile:
+            print("❌ Not connected. Call connect() first.")
+            return None
+            
+        try:
+            return {
+                'name': self._profile.get('name', 'Unknown'),
+                'level': self._profile.get('level', 0),
+                'xp': self._profile.get('xp', 0),
+                'clan': self._get_clan_name(),
+                'clan_id': self._clan_id
+            }
+        except Exception as e:
+            print(f"❌ Error getting your stats: {e}")
+            return None
+    
+    def get_clan_members(self) -> List[Dict[str, Any]]:
+        """
+        Get all members of your clan.
+        
+        Returns:
+            List of clan members with their stats
+        """
+        if not self._clan_id:
+            print("❌ No clan detected")
+            return []
+            
+        try:
+            members = self.client.get_clan_members(self._clan_id)
+            
+            simplified_members = []
+            for member in members:
+                simplified_members.append({
+                    'name': member.get('name', 'Unknown'),
+                    'level': member.get('level', 0),
+                    'xp': member.get('_xp', 0),
+                    'score': member.get('_score', 0),
+                    'status': member.get('status', 'Unknown'),
+                    'online': member.get('online', False),
+                    'killsig': member.get('_killsig_id', 'default')
+                })
+            
+            return simplified_members
+            
+        except Exception as e:
+            print(f"❌ Error getting clan members: {e}")
+            return []
+    
+    def kick_member(self, dogtag: str, reason: str = "Kicked from clan") -> bool:
+        """
+        Kick a member from your clan by their dogtag.
+        
+        Args:
+            dogtag: Member's dogtag to kick
+            reason: Reason for kicking (optional)
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        if not self._clan_id:
+            print("❌ No clan detected")
+            return False
+            
+        try:
+            result = self.client.kick_clan_member_by_dogtag(
+                dogtag=dogtag,
+                clan_id=self._clan_id,
+                from_name="CLAN_ADMIN"
+            )
+            
+            if 'error' not in result:
+                print(f"✅ Successfully kicked player with dogtag {dogtag}")
+                return True
+            else:
+                print(f"❌ Failed to kick: {result['error']}")
+                return False
+                
+        except Exception as e:
+            print(f"❌ Error kicking member: {e}")
+            return False
+    
+    def update_clan_settings(self, name: Optional[str] = None, 
+                          description: Optional[str] = None,
+                          member_limit: Optional[int] = None) -> bool:
+        """
+        Update your clan settings.
+        
+        Args:
+            name: New clan name (optional)
+            description: New clan description (optional)
+            member_limit: New member limit (optional)
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        if not self._clan_id:
+            print("❌ No clan detected")
+            return False
+            
+        try:
+            # Build settings dict with only provided values
+            settings = {}
+            if name:
+                settings['name'] = name
+            if description:
+                settings['description'] = description
+            if member_limit:
+                settings['member_limit'] = str(member_limit)
+            
+            if not settings:
+                print("⚠️ No settings to update")
+                return False
+            
+            result = self.client.update_clan_settings(self._clan_id, **settings)
+            
+            if 'error' not in result:
+                print(f"✅ Clan settings updated successfully")
+                return True
+            else:
+                print(f"❌ Failed to update settings: {result['error']}")
+                return False
+                
+        except Exception as e:
+            print(f"❌ Error updating clan settings: {e}")
+            return False
+    
+    def send_message(self, dogtag: str, message: str) -> bool:
+        """
+        Send a private message to a player.
+        
+        Args:
+            dogtag: Player's dogtag
+            message: Message to send
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            # First get player info to find their credential
+            player_info = self.client.get_player_stats_by_dogtag(dogtag)
+            if 'error' in player_info:
+                print(f"❌ Player not found: {player_info['error']}")
+                return False
+            
+            # Get credential from player data
+            player_credential = list(player_info.keys())[0]
+            
+            # Send message
+            result = self.client.send_private_message(
+                credential=player_credential,
+                message=message
+            )
+            
+            if 'error' not in result:
+                print(f"✅ Message sent to {dogtag}")
+                return True
+            else:
+                print(f"❌ Failed to send message: {result['error']}")
+                return False
+                
+        except Exception as e:
+            print(f"❌ Error sending message: {e}")
+            return False
+    
+    def get_inactive_members(self, days_inactive: int = 30) -> List[Dict[str, Any]]:
+        """
+        Get members who haven't been active for specified days.
+        
+        Args:
+            days_inactive: Number of days to consider inactive
+            
+        Returns:
+            List of inactive members
+        """
+        if not self._clan_id:
+            print("❌ No clan detected")
+            return []
+            
+        try:
+            members = self.client.get_clan_members(self._clan_id)
+            inactive_members = []
+            
+            for member in members:
+                # Check last online time (simplified - you'd need to parse actual date)
+                if not member.get('online', False):
+                    # In a real implementation, you'd check the last_online timestamp
+                    # For now, we'll consider offline members as potentially inactive
+                    inactive_members.append({
+                        'name': member.get('name', 'Unknown'),
+                        'level': member.get('level', 0),
+                        'xp': member.get('_xp', 0),
+                        'status': member.get('status', 'Unknown'),
+                        'online': False
+                    })
+            
+            return inactive_members
+            
+        except Exception as e:
+            print(f"❌ Error getting inactive members: {e}")
+            return []
+    
+    def auto_kick_inactive_members(self, days_inactive: int = 30, dry_run: bool = True) -> Dict[str, Any]:
+        """
+        Automatically kick inactive members with safety checks.
+        
+        Args:
+            days_inactive: Days of inactivity to trigger kick
+            dry_run: If True, only show who would be kicked without actually kicking
+            
+        Returns:
+            Dictionary with results
+        """
+        inactive_members = self.get_inactive_members(days_inactive)
+        
+        if not inactive_members:
+            return {'kicked': 0, 'skipped': 0, 'members': []}
+        
+        results = {'kicked': 0, 'skipped': 0, 'members': []}
+        
+        for member in inactive_members:
+            # Safety checks
+            if member['level'] > 50:  # Don't kick high-level members
+                print(f"⚠️ Skipping {member['name']} (Level {member['level']} - too high)")
+                results['skipped'] += 1
+                continue
+                
+            if 'leader' in member['status'].lower() or 'admin' in member['status'].lower():
+                print(f"⚠️ Skipping {member['name']} ({member['status']} - protected role)")
+                results['skipped'] += 1
+                continue
+            
+            if dry_run:
+                print(f"🔍 Would kick: {member['name']} (Level {member['level']}) - Inactive for {days_inactive}+ days")
+            else:
+                # Note: This would need the member's dogtag, which we'd need to fetch
+                print(f"🔨 Kicking {member['name']} (Level {member['level']})")
+                # client.kick_member(member['dogtag'], f"Inactive for {days_inactive} days")
+                results['kicked'] += 1
+            
+            results['members'].append(member)
+        
+        return results
+    
+    def close(self):
+        """Close the connection."""
+        try:
+            if self.client:
+                self.client.close()
+                print("✅ Connection closed")
+        except:
+            pass
+    
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()
+
+
+# Even simpler interface for absolute beginners
+def quick_search(dogtag: str, username: str, password: str) -> Optional[Dict[str, Any]]:
+    """
+    Quick search for a player by dogtag.
+    
+    Args:
+        dogtag: Player's dogtag to search
+        username: Your MC5 username
+        password: Your MC5 password
+        
+    Returns:
+        Player information or None if not found
+    """
+    with SimpleMC5Client(username, password) as client:
+        if client.connect():
+            return client.search_player(dogtag)
+    return None
+
+
+def quick_kick(dogtag: str, username: str, password: str, reason: str = "Kicked") -> bool:
+    """
+    Quick kick a member by dogtag.
+    
+    Args:
+        dogtag: Member's dogtag to kick
+        username: Your MC5 username
+        password: Your MC5 password
+        reason: Reason for kicking
+        
+    Returns:
+        True if successful, False otherwise
+    """
+    with SimpleMC5Client(username, password) as client:
+        if client.connect():
+            return client.kick_member(dogtag, reason)
+    return False
+
+
+def batch_search_players(dogtags: List[str], username: str, password: str) -> Dict[str, Any]:
+    """
+    Search for multiple players at once.
+    
+    Args:
+        dogtags: List of dogtags to search
+        username: Your MC5 username
+        password: Your MC5 password
+        
+    Returns:
+        Dictionary with search results
+    """
+    results = {'found': [], 'not_found': [], 'errors': []}
+    
+    with SimpleMC5Client(username, password) as client:
+        if client.connect():
+            for dogtag in dogtags:
+                try:
+                    player = client.search_player(dogtag)
+                    if player:
+                        results['found'].append(player)
+                        print(f"✅ Found {dogtag}: {player['kills']:,} kills")
+                    else:
+                        results['not_found'].append(dogtag)
+                        print(f"❌ Not found: {dogtag}")
+                except Exception as e:
+                    results['errors'].append({'dogtag': dogtag, 'error': str(e)})
+                    print(f"⚠️ Error with {dogtag}: {e}")
+    
+    return results
+
+
+def clan_cleanup(username: str, password: str, 
+                 inactive_days: int = 30,
+                 min_level: int = 10,
+                 dry_run: bool = True) -> Dict[str, Any]:
+    """
+    Comprehensive clan cleanup with conditional logic.
+    
+    Args:
+        username: Your MC5 username
+        password: Your MC5 password
+        inactive_days: Days of inactivity to consider
+        min_level: Minimum level to protect from kicking
+        dry_run: If True, only show what would be done
+        
+    Returns:
+        Dictionary with cleanup results
+    """
+    results = {
+        'total_members': 0,
+        'active_members': 0,
+        'inactive_members': 0,
+        'would_kick': 0,
+        'protected': 0,
+        'actions': []
+    }
+    
+    with SimpleMC5Client(username, password) as client:
+        if not client.connect():
+            return results
+        
+        members = client.get_clan_members()
+        results['total_members'] = len(members)
+        
+        for member in members:
+            # Conditional logic for each member
+            if member.get('online', False):
+                results['active_members'] += 1
+                results['actions'].append(f"✅ {member['name']} - Online (protected)")
+                continue
+            
+            # Check level protection
+            if member.get('level', 0) >= min_level:
+                results['protected'] += 1
+                results['actions'].append(f"🛡️ {member['name']} - Level {member['level']} (protected)")
+                continue
+            
+            # Check role protection
+            status = member.get('status', '').lower()
+            if any(role in status for role in ['leader', 'admin', 'officer']):
+                results['protected'] += 1
+                results['actions'].append(f"👑 {member['name']} - {member['status']} (protected)")
+                continue
+            
+            # Member is inactive and not protected
+            results['inactive_members'] += 1
+            results['would_kick'] += 1
+            
+            if dry_run:
+                results['actions'].append(f"🔍 Would kick: {member['name']} - Level {member['level']}, Inactive")
+            else:
+                # Note: Would need dogtag for actual kicking
+                results['actions'].append(f"🔨 Kicked: {member['name']} - Level {member['level']}")
+    
+    return results
+
+
+def monitor_clan_activity(username: str, password: str, 
+                         check_interval: int = 60,
+                         max_checks: int = 10) -> None:
+    """
+    Monitor clan activity with while loop.
+    
+    Args:
+        username: Your MC5 username
+        password: Your MC5 password
+        check_interval: Seconds between checks
+        max_checks: Maximum number of checks to perform
+    """
+    import time
+    
+    check_count = 0
+    
+    with SimpleMC5Client(username, password) as client:
+        if not client.connect():
+            return
+        
+        print(f"🔍 Starting clan activity monitoring (checking every {check_interval}s)")
+        
+        while check_count < max_checks:
+            check_count += 1
+            
+            try:
+                members = client.get_clan_members()
+                online_count = sum(1 for m in members if m.get('online', False))
+                
+                print(f"Check {check_count}/{max_checks}: {online_count}/{len(members)} members online")
+                
+                # Conditional alerts
+                if online_count == 0:
+                    print("🚨 Alert: No members online!")
+                elif online_count > len(members) * 0.8:
+                    print("🎉 High activity: Most members are online!")
+                
+                # Break if all members are online
+                if online_count == len(members):
+                    print("✅ All members are online! Stopping monitor.")
+                    break
+                    
+            except Exception as e:
+                print(f"⚠️ Error during check {check_count}: {e}")
+            
+            # Wait before next check (except after last check)
+            if check_count < max_checks:
+                time.sleep(check_interval)
+        
+        print(f"🏁 Monitoring completed after {check_count} checks")