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

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