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

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

mc5_api_client/transfer_quick.py

@@ -0,0 +1,280 @@
+#!/usr/bin/env python3
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : transfer_quick.py
+# | License  | MIT License © 2026 Chizoba
+# | Brief    : Quick functions for account transfer and device linking
+# ────────────────★─────────────────────────────────
+
+from typing import Optional, Dict, Any
+from .simple_client import SimpleMC5Client
+from .telemetry import report_usage
+from .debug import debug_function, debug_print
+
+@debug_function
+def quick_generate_transfer_code(username: str, password: str) -> Optional[Dict[str, Any]]:
+    """
+    Quick function to generate a transfer code for account linking.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        
+    Returns:
+        Transfer code information or None if failed
+    """
+    try:
+        with SimpleMC5Client(username, password) as client:
+            if client.connect():
+                transfer_info = client.client.generate_transfer_code()
+                
+                if transfer_info.get("transfer_code"):
+                    code = transfer_info["transfer_code"]
+                    expiration = transfer_info["expiration"]
+                    
+                    debug_print(f"✅ Transfer code generated: {code}", "success")
+                    debug_print(f"⏰ Expires: {expiration}", "info")
+                    debug_print("📱 Use this code on your new device to link your account", "info")
+                    
+                    return transfer_info
+                else:
+                    debug_print("❌ Failed to generate transfer code", "error")
+                    return None
+            return None
+    except Exception as e:
+        debug_print(f"❌ Failed to generate transfer code: {e}", "error")
+        return None
+
+@debug_function
+def quick_check_transfer_status(username: str, password: str) -> Optional[Dict[str, Any]]:
+    """
+    Quick function to check transfer code status.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        
+    Returns:
+        Transfer code status or None if failed
+    """
+    try:
+        with SimpleMC5Client(username, password) as client:
+            if client.connect():
+                status = client.client.get_transfer_code_info()
+                
+                if status.get("has_active_code"):
+                    code = status["transfer_code"]
+                    time_remaining = status.get("time_remaining", {})
+                    
+                    debug_print(f"✅ Active transfer code found: {code}", "success")
+                    
+                    if time_remaining and not status.get("is_expired"):
+                        debug_print(f"⏰ Time remaining: {time_remaining.get('formatted', 'Unknown')}", "info")
+                    else:
+                        debug_print("⚠️ Code has expired", "warning")
+                    
+                    return status
+                else:
+                    debug_print("ℹ️ No active transfer code found", "info")
+                    return status
+            return None
+    except Exception as e:
+        debug_print(f"❌ Failed to check transfer status: {e}", "error")
+        return None
+
+@debug_function
+def quick_get_device_linking_guide(username: str, password: str) -> Optional[Dict[str, Any]]:
+    """
+    Quick function to get complete device linking guide.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        
+    Returns:
+        Device linking guide or None if failed
+    """
+    try:
+        with SimpleMC5Client(username, password) as client:
+            if client.connect():
+                guide = client.client.get_device_linking_guide()
+                
+                debug_print("📖 Device linking guide generated", "success")
+                
+                # Show current code status
+                code_info = guide.get("current_code_info", {})
+                if code_info.get("has_active_code"):
+                    debug_print(f"🔑 Current code: {code_info.get('transfer_code')}", "info")
+                    debug_print(f"⏰ Expires: {code_info.get('expiration')}", "info")
+                else:
+                    debug_print("ℹ️ No active code - generate one first", "info")
+                
+                return guide
+            return None
+    except Exception as e:
+        debug_print(f"❌ Failed to get linking guide: {e}", "error")
+        return None
+
+@debug_function
+def quick_link_device_workflow(username: str, password: str) -> Optional[Dict[str, Any]]:
+    """
+    Quick function for complete device linking workflow.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        
+    Returns:
+        Complete workflow results or None if failed
+    """
+    try:
+        with SimpleMC5Client(username, password) as client:
+            if client.connect():
+                debug_print("🔄 Starting device linking workflow", "info")
+                
+                # Step 1: Check existing code
+                debug_print("📋 Step 1: Checking existing transfer code...")
+                status = client.client.get_transfer_code_info()
+                
+                if status.get("has_active_code") and not status.get("is_expired"):
+                    debug_print(f"✅ Found active code: {status['transfer_code']}", "success")
+                    time_remaining = status.get("time_remaining", {})
+                    if time_remaining:
+                        debug_print(f"⏰ Time remaining: {time_remaining.get('formatted')}", "info")
+                    
+                    workflow_result = {
+                        "status": "existing_code",
+                        "transfer_code": status["transfer_code"],
+                        "expiration": status["expiration"],
+                        "time_remaining": time_remaining,
+                        "instructions": status["instructions"]
+                    }
+                else:
+                    # Step 2: Generate new code
+                    debug_print("📋 Step 2: Generating new transfer code...")
+                    transfer_info = client.client.generate_transfer_code()
+                    
+                    if transfer_info.get("transfer_code"):
+                        debug_print(f"✅ New code generated: {transfer_info['transfer_code']}", "success")
+                        
+                        workflow_result = {
+                            "status": "new_code",
+                            "transfer_code": transfer_info["transfer_code"],
+                            "expiration": transfer_info["expiration"],
+                            "instructions": transfer_info["instructions"]
+                        }
+                    else:
+                        debug_print("❌ Failed to generate new code", "error")
+                        return None
+                
+                # Step 3: Get linking guide
+                debug_print("📋 Step 3: Getting linking instructions...")
+                guide = client.client.get_device_linking_guide()
+                
+                workflow_result.update({
+                    "linking_guide": guide,
+                    "steps": guide.get("steps", []),
+                    "important_notes": guide.get("important_notes", [])
+                })
+                
+                debug_print("✅ Device linking workflow completed", "success")
+                return workflow_result
+            return None
+    except Exception as e:
+        debug_print(f"❌ Failed to complete linking workflow: {e}", "error")
+        return None
+
+@debug_function
+def quick_validate_transfer_code(transfer_code: str) -> Optional[Dict[str, Any]]:
+    """
+    Quick function to validate transfer code format.
+    
+    Args:
+        transfer_code: Transfer code to validate
+        
+    Returns:
+        Validation result or None if failed
+    """
+    try:
+        from .transfer import TransferMixin
+        
+        # Create a temporary client instance for validation
+        client = TransferMixin()
+        client._token_data = {"access_token": "dummy"}  # Set minimal token data
+        
+        validation = client.validate_transfer_code_format(transfer_code)
+        
+        if validation.get("valid"):
+            debug_print(f"✅ Transfer code format is valid", "success")
+        else:
+            debug_print(f"❌ Invalid transfer code: {validation.get('error')}", "error")
+        
+        return validation
+    except Exception as e:
+        debug_print(f"❌ Failed to validate transfer code: {e}", "error")
+        return None
+
+@debug_function
+def quick_force_new_code(username: str, password: str) -> Optional[Dict[str, Any]]:
+    """
+    Quick function to force generate a new transfer code.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        
+    Returns:
+        New transfer code information or None if failed
+    """
+    try:
+        with SimpleMC5Client(username, password) as client:
+            if client.connect():
+                debug_print("🔄 Forcing new transfer code generation...", "info")
+                
+                result = client.client.generate_new_transfer_code()
+                
+                if result.get("transfer_code"):
+                    debug_print(f"✅ New transfer code: {result['transfer_code']}", "success")
+                    debug_print(f"⏰ Expires: {result['expiration']}", "info")
+                    debug_print("⚠️ This may have overridden any existing code", "warning")
+                    
+                    return result
+                else:
+                    debug_print("❌ Failed to force generate new code", "error")
+                    return None
+            return None
+    except Exception as e:
+        debug_print(f"❌ Failed to force new code generation: {e}", "error")
+        return None
+
+@debug_function
+def quick_transfer_status_summary(username: str, password: str) -> Optional[str]:
+    """
+    Quick function to get a human-readable transfer status summary.
+    
+    Args:
+        username: MC5 username
+        password: MC5 password
+        
+    Returns:
+        Human-readable status summary or None if failed
+    """
+    try:
+        status = quick_check_transfer_status(username, password)
+        
+        if status:
+            if status.get("has_active_code"):
+                if status.get("is_expired"):
+                    return f"⚠️ Transfer code expired: {status.get('transfer_code')}"
+                else:
+                    code = status.get("transfer_code")
+                    time_remaining = status.get("time_remaining", {})
+                    time_str = time_remaining.get('formatted', 'Unknown time')
+                    return f"✅ Active code: {code} (expires in {time_str})"
+            else:
+                return "ℹ️ No active transfer code - generate one to link a device"
+        else:
+            return "❌ Failed to check transfer status"
+    except Exception as e:
+        debug_print(f"❌ Failed to get status summary: {e}", "error")
+        return None