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

mc5_api_client/__init__.py

@@ -13,19 +13,49 @@ Provides easy access to authentication, profile management, clan operations,
 messaging, and more.
 """
 
-__version__ = "1.0.6"
+__version__ = "1.0.9"
 __author__ = "Chizoba"
 __email__ = "chizoba2026@hotmail.com"
 __license__ = "MIT"
 
+from .simple_client import (
+    SimpleMC5Client,
+    batch_search_players,
+    clan_cleanup,
+    monitor_clan_activity,
+    quick_search,
+    quick_kick
+)
 from .client import MC5Client
 from .auth import TokenGenerator
 from .exceptions import MC5APIError, AuthenticationError, RateLimitError
+from .help import help, examples, quick_reference
+from .admin_client import (
+    AdminMC5Client,
+    create_admin_client,
+    create_user_client,
+    quick_add_squad_rating,
+    quick_update_player_score
+)
 
 __all__ = [
     "MC5Client",
+    "SimpleMC5Client",
+    "AdminMC5Client",
+    "batch_search_players",
+    "clan_cleanup",
+    "monitor_clan_activity",
+    "quick_search",
+    "quick_kick",
+    "create_admin_client",
+    "create_user_client",
+    "quick_add_squad_rating",
+    "quick_update_player_score",
     "TokenGenerator", 
     "MC5APIError",
     "AuthenticationError",
-    "RateLimitError"
+    "RateLimitError",
+    "help",
+    "examples",
+    "quick_reference"
 ]

mc5_api_client/admin_client.py

@@ -0,0 +1,433 @@
+#!/usr/bin/env python3
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : admin_client.py
+# | License  | MIT License © 2026 Chizoba
+# | Brief    | Admin client with enhanced squad management
+# ────────────────★─────────────────────────────────
+
+"""
+MC5 API Client - Admin Client
+
+Enhanced client with admin capabilities for squad management.
+Supports both regular users and admin users with special privileges.
+"""
+
+import requests
+import json
+from typing import Dict, List, Any, Optional
+from urllib.parse import quote
+
+from .auth import TokenGenerator
+from .exceptions import MC5APIError, AuthenticationError
+
+
+class AdminMC5Client:
+    """Enhanced MC5 client with admin capabilities."""
+    
+    def __init__(self, username: str, password: str, is_admin: bool = False):
+        """
+        Initialize admin client.
+        
+        Args:
+            username: MC5 username or admin username
+            password: MC5 password or admin password
+            is_admin: Whether using admin credentials
+        """
+        self.username = username
+        self.password = password
+        self.is_admin = is_admin
+        self.token = None
+        self.user_id = None
+        self.squad_id = None
+        self.base_url = "https://eur-osiris.gameloft.com"
+        self.auth_url = "https://eur-janus.gameloft.com"
+        
+        # Admin-specific settings
+        if is_admin:
+            self.client_id = "1875:55979:6.0.0a:windows:windows"
+            self.scope = "alert auth chat leaderboard_ro lobby message session social config storage_ro tracking_bi feed storage leaderboard_admin social_eve social soc transaction schedule lottery voice matchmaker profile_inventory admin bypass unrestricted"
+            self.device_id = ""
+        else:
+            self.client_id = "1924:56128:6.0.6a:android:googleplay"
+            self.scope = "alert auth chat leaderboard_ro lobby message session social"
+            self.device_id = "1765668231.356923"
+    
+    def connect(self) -> bool:
+        """Connect to MC5 API."""
+        try:
+            print(f"🔌 Connecting to MC5 ({'Admin' if self.is_admin else 'User'} mode)...")
+            
+            # Generate token
+            token_gen = TokenGenerator()
+            token_data = token_gen.generate_token(
+                self.username,
+                self.password,
+                self.device_id,
+                self.scope
+            )
+            
+            if not token_data or 'access_token' not in token_data:
+                print("❌ Failed to generate token")
+                return False
+            
+            self.token = token_data['access_token']
+            self.user_id = token_data.get('credential', '')
+            print(f"✅ User ID: {self.user_id}")
+            
+            # Get user profile to find squad
+            self._get_user_profile()
+            
+            print("✅ Connected successfully!")
+            return True
+            
+        except Exception as e:
+            print(f"❌ Connection failed: {e}")
+            return False
+    
+    def _get_user_profile(self) -> bool:
+        """Get user profile and extract squad information."""
+        try:
+            url = f"{self.auth_url}/games/mygame/alias/{self.user_id}"
+            params = {
+                'access_token': self.token
+            }
+            
+            response = requests.get(url, params=params)
+            
+            if response.status_code == 200:
+                profile = response.json()
+                
+                # Extract squad ID from groups
+                groups = profile.get('groups', [])
+                if groups:
+                    self.squad_id = groups[0]
+                    print(f"✅ Squad ID detected: {self.squad_id}")
+                    return True
+                else:
+                    print("⚠️ No squad found in profile")
+                    # For admin users, use your squad ID
+                    if self.is_admin:
+                        self.squad_id = "e514e40a-009c-11f1-b16a-b8ca3a7095d0"
+                        print(f"✅ Using default squad ID: {self.squad_id}")
+                        return True
+                    return False
+            else:
+                print(f"❌ Failed to get profile: {response.status_code}")
+                # For admin users, use your squad ID
+                if self.is_admin:
+                    self.squad_id = "e514e40a-009c-11f1-b16a-b8ca3a7095d0"
+                    print(f"✅ Using default squad ID: {self.squad_id}")
+                    return True
+                return False
+                
+        except Exception as e:
+            print(f"❌ Error getting profile: {e}")
+            # For admin users, use your squad ID
+            if self.is_admin:
+                self.squad_id = "e514e40a-009c-11f1-b16a-b8ca3a7095d0"
+                print(f"✅ Using default squad ID: {self.squad_id}")
+                return True
+            return False
+    
+    def add_squad_rating(self, rating: int = 5200) -> Dict[str, Any]:
+        """
+        Add rating to squad.
+        
+        Args:
+            rating: Rating amount to add
+            
+        Returns:
+            Result dictionary
+        """
+        if not self.squad_id:
+            return {'error': 'No squad ID found'}
+        
+        try:
+            print(f"⭐ Adding {rating} rating to squad...")
+            
+            # For admin users, we can update squad score directly
+            if self.is_admin:
+                return self._admin_update_squad_score(rating)
+            else:
+                return self._user_update_squad_score(rating)
+                
+        except Exception as e:
+            return {'error': str(e)}
+    
+    def _admin_update_squad_score(self, rating: int) -> Dict[str, Any]:
+        """Admin method to update squad score."""
+        try:
+            # Admin can update squad settings directly
+            url = f"{self.base_url}/groups/{self.squad_id}"
+            headers = {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            }
+            
+            # Update squad score
+            data = {
+                'access_token': self.token,
+                'operation': 'update',
+                '_score': str(rating)
+            }
+            
+            response = requests.post(url, headers=headers, data=data)
+            
+            print(f"🔍 Admin API Response: {response.status_code}")
+            if response.status_code == 200:
+                return {'success': True, 'rating_added': rating}
+            else:
+                print(f"🔍 Response body: {response.text}")
+                return {'error': f'Failed to update squad score: {response.status_code}'}
+                
+        except Exception as e:
+            return {'error': str(e)}
+    
+    def _user_update_squad_score(self, rating: int) -> Dict[str, Any]:
+        """User method to update squad score."""
+        try:
+            # Regular users update their own score which affects squad
+            url = f"{self.base_url}/groups/{self.squad_id}/members/{quote(self.user_id)}"
+            headers = {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            }
+            
+            # Update user score
+            data = {
+                'access_token': self.token,
+                'operation': 'update',
+                '_score': str(rating)
+            }
+            
+            response = requests.post(url, headers=headers, data=data)
+            
+            if response.status_code == 200:
+                return {'success': True, 'rating_added': rating}
+            else:
+                return {'error': f'Failed to update score: {response.status_code}'}
+                
+        except Exception as e:
+            return {'error': str(e)}
+    
+    def update_player_score(self, target_user_id: str, score: int, xp: int = None, 
+                          killsig_color: str = None, killsig_id: str = None) -> Dict[str, Any]:
+        """
+        Update player score (admin only).
+        
+        Args:
+            target_user_id: Target player's user ID
+            score: New score value
+            xp: New XP value (optional)
+            killsig_color: Kill signature color (optional)
+            killsig_id: Kill signature ID (optional)
+            
+        Returns:
+            Result dictionary
+        """
+        if not self.is_admin:
+            return {'error': 'Admin privileges required'}
+        
+        try:
+            print(f"🎯 Updating player {target_user_id} score to {score}...")
+            
+            url = f"{self.base_url}/groups/{self.squad_id}/members/{quote(target_user_id)}"
+            headers = {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            }
+            
+            data = {
+                'access_token': self.token,
+                'operation': 'update',
+                '_score': str(score),
+                'credential': target_user_id
+            }
+            
+            # Add optional parameters
+            if xp is not None:
+                data['_xp'] = str(xp)
+            if killsig_color is not None:
+                data['_killsig_color'] = killsig_color
+            if killsig_id is not None:
+                data['_killsig_id'] = killsig_id
+            
+            response = requests.post(url, headers=headers, data=data)
+            
+            if response.status_code == 200:
+                result = {'success': True, 'score_updated': score}
+                if xp is not None:
+                    result['xp_updated'] = xp
+                if killsig_color is not None:
+                    result['killsig_color_updated'] = killsig_color
+                if killsig_id is not None:
+                    result['killsig_id_updated'] = killsig_id
+                return result
+            else:
+                return {'error': f'Failed to update player: {response.status_code}'}
+                
+        except Exception as e:
+            return {'error': str(e)}
+    
+    def kick_member(self, target_user_id: str, reason: str = "Kicked by admin") -> Dict[str, Any]:
+        """
+        Kick member from squad (admin only).
+        
+        Args:
+            target_user_id: Target player's user ID
+            reason: Kick reason
+            
+        Returns:
+            Result dictionary
+        """
+        if not self.is_admin:
+            return {'error': 'Admin privileges required'}
+        
+        try:
+            print(f"👢 Kicking member {target_user_id}...")
+            
+            url = f"{self.base_url}/groups/{self.squad_id}/members/{quote(target_user_id)}"
+            headers = {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            }
+            
+            data = {
+                'access_token': self.token,
+                'operation': 'delete',
+                'reason': reason
+            }
+            
+            response = requests.post(url, headers=headers, data=data)
+            
+            if response.status_code == 200:
+                return {'success': True, 'kicked': target_user_id, 'reason': reason}
+            else:
+                return {'error': f'Failed to kick member: {response.status_code}'}
+                
+        except Exception as e:
+            return {'error': str(e)}
+    
+    def get_squad_members(self) -> List[Dict[str, Any]]:
+        """Get squad members."""
+        if not self.squad_id:
+            return []
+        
+        try:
+            url = f"{self.base_url}/groups/{self.squad_id}/members"
+            params = {
+                'access_token': self.token
+            }
+            
+            response = requests.get(url, params=params)
+            
+            if response.status_code == 200:
+                return response.json()
+            else:
+                print(f"❌ Failed to get squad members: {response.status_code}")
+                return []
+                
+        except Exception as e:
+            print(f"❌ Error getting squad members: {e}")
+            return []
+    
+    def get_user_stats(self) -> Dict[str, Any]:
+        """Get current user statistics."""
+        try:
+            url = f"{self.auth_url}/games/mygame/alias/{self.user_id}"
+            params = {
+                'access_token': self.token
+            }
+            
+            response = requests.get(url, params=params)
+            
+            if response.status_code == 200:
+                return response.json()
+            else:
+                return {}
+                
+        except Exception as e:
+            print(f"❌ Error getting user stats: {e}")
+            return {}
+    
+    def close(self):
+        """Close connection."""
+        self.token = None
+        self.user_id = None
+        self.squad_id = None
+
+
+# Convenience functions
+def create_admin_client() -> AdminMC5Client:
+    """Create admin client with default admin credentials."""
+    return AdminMC5Client(
+        username="game:mc5_system",
+        password="admin",
+        is_admin=True
+    )
+
+
+def create_user_client(username: str, password: str) -> AdminMC5Client:
+    """Create user client."""
+    return AdminMC5Client(
+        username=username,
+        password=password,
+        is_admin=False
+    )
+
+
+def quick_add_squad_rating(username: str, password: str, rating: int = 5200, 
+                          use_admin: bool = False) -> Dict[str, Any]:
+    """
+    Quick function to add rating to squad.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        rating: Rating to add
+        use_admin: Whether to use admin credentials
+        
+    Returns:
+        Result dictionary
+    """
+    try:
+        if use_admin:
+            client = create_admin_client()
+        else:
+            client = create_user_client(username, password)
+        
+        if client.connect():
+            result = client.add_squad_rating(rating)
+            client.close()
+            return result
+        else:
+            return {'error': 'Failed to connect'}
+            
+    except Exception as e:
+        return {'error': str(e)}
+
+
+def quick_update_player_score(target_user_id: str, score: int, xp: int = None,
+                             killsig_color: str = None, killsig_id: str = None) -> Dict[str, Any]:
+    """
+    Quick function to update player score (admin only).
+    
+    Args:
+        target_user_id: Target player's user ID
+        score: New score value
+        xp: New XP value (optional)
+        killsig_color: Kill signature color (optional)
+        killsig_id: Kill signature ID (optional)
+        
+    Returns:
+        Result dictionary
+    """
+    try:
+        client = create_admin_client()
+        
+        if client.connect():
+            result = client.update_player_score(target_user_id, score, xp, killsig_color, killsig_id)
+            client.close()
+            return result
+        else:
+            return {'error': 'Failed to connect'}
+            
+    except Exception as e:
+        return {'error': str(e)}

mc5_api_client/help.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : help.py
+# | License  | MIT License © 2026 Chizoba
+# | Brief    : Help system for MC5 API Client
+# ────────────────★─────────────────────────────────
+
+"""
+MC5 API Client - Built-in Help System
+
+Provides comprehensive help for users at all levels.
+"""
+
+def help(topic: str = None) -> None:
+    """
+    Display help information for MC5 API Client.
+    
+    Args:
+        topic: Help topic (basic, clan, advanced, examples, troubleshooting)
+    """
+    if topic is None:
+        _show_overview()
+    elif topic.lower() == 'basic':
+        _show_basic_help()
+    elif topic.lower() == 'clan':
+        _show_clan_help()
+    elif topic.lower() == 'advanced':
+        _show_advanced_help()
+    elif topic.lower() == 'examples':
+        _show_examples_help()
+    elif topic.lower() == 'troubleshooting':
+        _show_troubleshooting_help()
+    else:
+        print(f"❌ Unknown topic: {topic}")
+        print("📋 Available topics: basic, clan, advanced, examples, troubleshooting")
+        _show_overview()
+
+def _show_overview() -> None:
+    """Show help overview."""
+    print("🎮 MC5 API Client - Help System")
+    print("=" * 40)
+    print("📚 Available Help Topics:")
+    print()
+    print("🔸 basic        - Get started with basic usage")
+    print("🔸 clan         - Clan management operations")
+    print("🔸 advanced     - Advanced automation features")
+    print("🔸 examples     - Available example files")
+    print("🔸 troubleshooting - Common issues and solutions")
+    print()
+    print("💡 Usage: help('topic_name')")
+    print("💡 Examples: help('basic'), help('clan')")
+
+def _show_basic_help() -> None:
+    """Show basic usage help."""
+    print("🎮 Basic Usage - Get Started")
+    print("=" * 30)
+    print()
+    print("🚀 QUICK START:")
+    print("   pip install mc5_api_client")
+    print()
+    print("🔹 ONE-LINER COMMANDS:")
+    print("   from mc5_api_client import quick_search")
+    print("   player = quick_search('f55f', 'username', 'password')")
+    print()
+    print("🔹 SIMPLE CLIENT:")
+    print("   from mc5_api_client import SimpleMC5Client")
+    print("   client = SimpleMC5Client('username', 'password')")
+    print("   client.connect()")
+    print("   player = client.search_player('f55f')")
+    print()
+    print("🔹 QUICK KICK:")
+    print("   from mc5_api_client import quick_kick")
+    print("   quick_kick('9gg9', 'username', 'password', 'inactive')")
+
+def _show_clan_help() -> None:
+    """Show clan management help."""
+    print("🏰 Clan Management")
+    print("=" * 20)
+    print()
+    print("🔹 GET CLAN MEMBERS:")
+    print("   client = SimpleMC5Client('user', 'pass')")
+    print("   client.connect()")
+    print("   members = client.get_clan_members()")
+    print()
+    print("🔹 KICK MEMBER:")
+    print("   client.kick_member('9gg9', 'inactive for 30 days')")
+    print()
+    print("🔹 UPDATE CLAN:")
+    print("   client.update_clan_settings(name='New Clan Name')")
+    print()
+    print("🔹 SMART CLEANUP:")
+    print("   from mc5_api_client.simple_client import clan_cleanup")
+    print("   results = clan_cleanup('user', 'pass', dry_run=True)")
+
+def _show_advanced_help() -> None:
+    """Show advanced features help."""
+    print("🤖 Advanced Features")
+    print("=" * 25)
+    print()
+    print("🔹 BATCH SEARCH:")
+    print("   from mc5_api_client.simple_client import batch_search_players")
+    print("   results = batch_search_players(['f55f','9gg9'], 'user', 'pass')")
+    print()
+    print("🔹 REAL-TIME MONITORING:")
+    print("   from mc5_api_client.simple_client import monitor_clan_activity")
+    print("   monitor_clan_activity('user', 'pass', check_interval=60)")
+    print()
+    print("🔹 CONDITIONAL LOGIC:")
+    print("   for player in results['found']:")
+    print("       if player['kills'] > 10000:")
+    print("           print(f'Elite: {player[\"dogtag\"]}')")
+
+def _show_examples_help() -> None:
+    """Show examples help."""
+    print("📚 Example Files")
+    print("=" * 20)
+    print()
+    examples = [
+        ('basic_usage.py', 'Core functionality'),
+        ('simple_usage.py', 'User-friendly interface'),
+        ('advanced_automation.py', 'Loops & automation'),
+        ('clan_management.py', 'Clan operations'),
+        ('player_stats.py', 'Player statistics'),
+        ('quick_help.py', 'Help system')
+    ]
+    
+    for filename, description in examples:
+        print(f"🔸 {filename} - {description}")
+    
+    print()
+    print("💡 Usage: python examples/filename.py")
+
+def _show_troubleshooting_help() -> None:
+    """Show troubleshooting help."""
+    print("🔧 Troubleshooting")
+    print("=" * 20)
+    print()
+    issues = [
+        ('401 Error', 'Check username/password'),
+        ('404 Error', 'Player not found - check dogtag'),
+        ('Connection Failed', 'Check internet connection'),
+        ('Permission Denied', 'Check clan role/permissions')
+    ]
+    
+    for error, solution in issues:
+        print(f"❌ {error}: {solution}")
+    
+    print()
+    print("💡 Always use try/except blocks:")
+    print("   try:")
+    print("       client.connect()")
+    print("   except AuthenticationError:")
+    print("       print('Check credentials')")
+
+
+def quick_reference() -> None:
+    """Show quick reference card."""
+    print("🎯 MC5 API Client - Quick Reference")
+    print("=" * 40)
+    print()
+    print("🚀 INSTALL: pip install mc5_api_client")
+    print()
+    print("🔹 QUICK SEARCH:")
+    print("   quick_search('f55f', 'user', 'pass')")
+    print()
+    print("🔹 SIMPLE CLIENT:")
+    print("   client = SimpleMC5Client('user', 'pass')")
+    print("   client.connect()")
+    print("   player = client.search_player('f55f')")
+    print()
+    print("🔹 CLAN OPS:")
+    print("   members = client.get_clan_members()")
+    print("   client.kick_member('9gg9', 'inactive')")
+    print()
+    print("🔹 ERROR HANDLING:")
+    print("   try: except AuthenticationError:")
+
+
+def examples() -> None:
+    """Show available examples."""
+    print("📚 Available Examples")
+    print("=" * 25)
+    print()
+    print("🔸 basic_usage.py - Core functionality")
+    print("🔸 simple_usage.py - User-friendly interface")
+    print("🔸 advanced_automation.py - Loops & automation")
+    print("🔸 clan_management.py - Clan operations")
+    print("🔸 player_stats.py - Player statistics")
+    print("🔸 private_messaging.py - Direct messaging")
+    print("🔸 squad_management.py - Squad management")
+    print("🔸 message_management.py - Communication")
+    print("🔸 events_and_tasks.py - Daily tasks")
+    print("🔸 squad_wall_management.py - Wall posts")
+    print("🔸 advanced_features.py - Advanced features")
+    print("🔸 clan_management_complete.py - Complete clan ops")
+    print("🔸 quick_help.py - Help system")
+    print()
+    print("💡 Usage: python examples/filename.py")
+
+
+# Export help functions
+__all__ = ['help', 'quick_reference', 'examples']