mc5-api-client 1.0.0__py3-none-any.whl

mc5_api_client/client.py

@@ -0,0 +1,1220 @@
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : client.py
+# | License  : MIT License © 2026 Chizoba
+# | Brief    : Main MC5 API client with comprehensive functionality
+# ────────────────★─────────────────────────────────
+
+"""
+Main MC5 API client providing comprehensive access to Modern Combat 5 API endpoints.
+"""
+
+import time
+import json
+from typing import Optional, Dict, Any, List
+from datetime import datetime
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from .auth import TokenGenerator
+from .exceptions import (
+    MC5APIError,
+    AuthenticationError,
+    TokenExpiredError,
+    RateLimitError,
+    InsufficientScopeError,
+    NetworkError
+)
+
+
+class MC5Client:
+    """
+    Comprehensive MC5 API client with support for all major endpoints.
+    """
+    
+    # API endpoints
+    BASE_URLS = {
+        "auth": "https://eur-janus.gameloft.com:443",
+        "osiris": "https://eur-osiris.gameloft.com:443",
+        "olympus": "https://eur-olympus.gameloft.com:443",
+        "iris": "https://eur-iris.gameloft.com:443",
+        "hermes": "https://eur-hermes.gameloft.com",
+        "pandora": "https://vgold-eur.gameloft.com",
+        "game_portal": "https://app-468561b3-9ecd-4d21-8241-30ed288f4d8b.gold0009.gameloft.com"
+    }
+    
+    def __init__(
+        self,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        client_id: str = "1875:55979:6.0.0a:windows:windows",
+        auto_refresh: bool = True,
+        timeout: int = 30,
+        max_retries: int = 3
+    ):
+        """
+        Initialize the MC5 API client.
+        
+        Args:
+            username: MC5 username
+            password: MC5 password
+            client_id: Game client identifier
+            auto_refresh: Automatically refresh expired tokens
+            timeout: Request timeout in seconds
+            max_retries: Maximum number of retry attempts
+        """
+        self.client_id = client_id
+        self.auto_refresh = auto_refresh
+        self.timeout = timeout
+        self.max_retries = max_retries
+        
+        # Initialize token generator
+        self.token_generator = TokenGenerator(
+            client_id=client_id,
+            timeout=timeout,
+            max_retries=max_retries
+        )
+        
+        # Setup HTTP session
+        self.session = requests.Session()
+        retry_strategy = Retry(
+            total=max_retries,
+            status_forcelist=[429, 500, 502, 503, 504],
+            allowed_methods=["HEAD", "GET", "POST", "PUT", "DELETE"],
+            backoff_factor=1
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        self.session.mount("http://", adapter)
+        self.session.mount("https://", adapter)
+        
+        # Default headers
+        self.session.headers.update({
+            "User-Agent": "MC5-API-Client/1.0.0",
+            "Accept": "*/*",
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Connection": "close"
+        })
+        
+        # Token storage
+        self._token_data = None
+        self._username = username
+        self._password = password
+        
+        # Auto-authenticate if credentials provided
+        if username and password:
+            self.authenticate(username, password)
+    
+    def authenticate(self, username: str, password: str, device_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Authenticate and obtain access token.
+        
+        Args:
+            username: MC5 username
+            password: MC5 password
+            device_id: Device ID (generated if not provided)
+            
+        Returns:
+            Token data dictionary
+        """
+        self._username = username
+        self._password = password
+        
+        self._token_data = self.token_generator.generate_token(
+            username=username,
+            password=password,
+            device_id=device_id
+        )
+        
+        return self._token_data
+    
+    def authenticate_admin(self, device_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Authenticate as admin.
+        
+        Args:
+            device_id: Device ID (generated if not provided)
+            
+        Returns:
+            Admin token data dictionary
+        """
+        self._token_data = self.token_generator.generate_admin_token(device_id=device_id)
+        self._username = "game:mc5_system"
+        self._password = "admin"
+        
+        return self._token_data
+    
+    def _ensure_valid_token(self):
+        """Ensure we have a valid access token."""
+        if not self._token_data:
+            raise AuthenticationError("No authentication token available. Call authenticate() first.")
+        
+        if not self.token_generator.validate_token(self._token_data):
+            if self.auto_refresh and self._username and self._password:
+                print("🟠 Token expired, refreshing...")
+                self._token_data = self.token_generator.refresh_token_if_needed(
+                    self._token_data,
+                    self._username,
+                    self._password
+                )
+            else:
+                raise TokenExpiredError("Access token has expired")
+    
+    def _make_request(
+        self,
+        method: str,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        require_token: bool = True
+    ) -> Dict[str, Any]:
+        """
+        Make an HTTP request with proper error handling.
+        
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE)
+            url: Request URL
+            params: Query parameters
+            data: Form data
+            json_data: JSON data
+            headers: Additional headers
+            require_token: Whether authentication token is required
+            
+        Returns:
+            Response JSON data
+            
+        Raises:
+            MC5APIError: For API-related errors
+            NetworkError: For network-related errors
+        """
+        if require_token:
+            self._ensure_valid_token()
+            # Add access token to params
+            if params is None:
+                params = {}
+            params["access_token"] = self._token_data["access_token"]
+        
+        # Prepare request
+        request_headers = self.session.headers.copy()
+        if headers:
+            request_headers.update(headers)
+        
+        try:
+            response = self.session.request(
+                method=method,
+                url=url,
+                params=params,
+                data=data,
+                json=json_data,
+                headers=request_headers,
+                timeout=self.timeout
+            )
+            
+            # Handle different response types
+            if response.status_code == 200:
+                try:
+                    return response.json()
+                except json.JSONDecodeError:
+                    return {"response": response.text}
+            
+            elif response.status_code == 401:
+                raise AuthenticationError("Unauthorized - invalid or expired token")
+            
+            elif response.status_code == 403:
+                try:
+                    error_data = response.json()
+                    raise InsufficientScopeError(error_data.get("error", "Insufficient permissions"))
+                except:
+                    raise InsufficientScopeError("Insufficient permissions")
+            
+            elif response.status_code == 429:
+                retry_after = response.headers.get("Retry-After")
+                raise RateLimitError(
+                    "Rate limit exceeded",
+                    retry_after=int(retry_after) if retry_after else None
+                )
+            
+            else:
+                try:
+                    error_data = response.json()
+                    error_msg = error_data.get("error", error_data.get("message", "Unknown error"))
+                except:
+                    error_msg = response.text or "Unknown error"
+                
+                raise MC5APIError(
+                    f"Request failed with status {response.status_code}: {error_msg}",
+                    status_code=response.status_code,
+                    response_data=error_data if 'error_data' in locals() else {}
+                )
+        
+        except requests.exceptions.Timeout:
+            raise NetworkError("Request timed out")
+        except requests.exceptions.ConnectionError:
+            raise NetworkError("Connection failed")
+        except requests.exceptions.RequestException as e:
+            raise NetworkError(f"Network error: {str(e)}")
+    
+    # Profile Management
+    
+    def get_profile(self, credential: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Get player profile information.
+        
+        Args:
+            credential: Player credential (uses current user if not provided)
+            
+        Returns:
+            Profile data
+        """
+        if credential:
+            url = f"{self.BASE_URLS['osiris']}/accounts/me"
+            params = {"credential": credential}
+        else:
+            url = f"{self.BASE_URLS['osiris']}/accounts/me"
+            params = {}
+        
+        return self._make_request("GET", url, params=params)
+    
+    def update_profile(self, profile_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Update player profile.
+        
+        Args:
+            profile_data: Profile data to update
+            
+        Returns:
+            Updated profile data
+        """
+        url = f"{self.BASE_URLS['osiris']}/accounts/me"
+        return self._make_request("PUT", url, data=profile_data)
+    
+    # Clan Management
+    
+    def get_clan_settings(self, clan_id: str) -> Dict[str, Any]:
+        """
+        Get clan settings and information.
+        
+        Args:
+            clan_id: Clan ID
+            
+        Returns:
+            Clan settings data including name, description, members, etc.
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}"
+        return self._make_request("GET", url)
+    
+    def update_clan_settings(self, clan_id: str, settings: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Update clan settings.
+        
+        Args:
+            clan_id: Clan ID
+            settings: Clan settings to update (name, description, membership_type, etc.)
+            
+        Returns:
+            Updated clan settings
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}"
+        return self._make_request("PUT", url, data=settings)
+    
+    def get_clan_members(self, clan_id: str) -> List[Dict[str, Any]]:
+        """
+        Get all members of a clan.
+        
+        Args:
+            clan_id: Clan ID
+            
+        Returns:
+            List of clan members with their roles and stats
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/members"
+        response = self._make_request("GET", url)
+        return response.get("members", [])
+    
+    def invite_clan_member(self, clan_id: str, credential: str, role: str = "member") -> Dict[str, Any]:
+        """
+        Invite a player to join the clan.
+        
+        Args:
+            clan_id: Clan ID
+            credential: Player credential to invite
+            role: Role to assign (member, officer, etc.)
+            
+        Returns:
+            Invitation result
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/invitations"
+        data = {
+            "credential": credential,
+            "role": role
+        }
+        return self._make_request("POST", url, data=data)
+    
+    def accept_clan_invitation(self, clan_id: str) -> Dict[str, Any]:
+        """
+        Accept a clan invitation.
+        
+        Args:
+            clan_id: Clan ID
+            
+        Returns:
+            Acceptance result
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/invitations/me"
+        return self._make_request("POST", url)
+    
+    def decline_clan_invitation(self, clan_id: str) -> Dict[str, Any]:
+        """
+        Decline a clan invitation.
+        
+        Args:
+            clan_id: Clan ID
+            
+        Returns:
+            Decline result
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/invitations/me"
+        return self._make_request("DELETE", url)
+    
+    def kick_clan_member(self, clan_id: str, member_credential: str) -> Dict[str, Any]:
+        """
+        Kick a member from the clan.
+        
+        Args:
+            clan_id: Clan ID
+            member_credential: Credential of member to kick
+            
+        Returns:
+            Operation result
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/members/{member_credential}"
+        return self._make_request("DELETE", url)
+    
+    def promote_clan_member(self, clan_id: str, member_credential: str, new_role: str) -> Dict[str, Any]:
+        """
+        Promote a clan member to a new role.
+        
+        Args:
+            clan_id: Clan ID
+            member_credential: Credential of member to promote
+            new_role: New role (officer, leader, etc.)
+            
+        Returns:
+            Promotion result
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/members/{member_credential}/role"
+        data = {"role": new_role}
+        return self._make_request("PUT", url, data=data)
+    
+    def demote_clan_member(self, clan_id: str, member_credential: str, new_role: str) -> Dict[str, Any]:
+        """
+        Demote a clan member to a new role.
+        
+        Args:
+            clan_id: Clan ID
+            member_credential: Credential of member to demote
+            new_role: New role (member, etc.)
+            
+        Returns:
+            Demotion result
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/members/{member_credential}/role"
+        data = {"role": new_role}
+        return self._make_request("PUT", url, data=data)
+    
+    def leave_clan(self, clan_id: str) -> Dict[str, Any]:
+        """
+        Leave the current clan.
+        
+        Args:
+            clan_id: Clan ID
+            
+        Returns:
+            Leave result
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/members/me"
+        return self._make_request("DELETE", url)
+    
+    def get_clan_applications(self, clan_id: str) -> List[Dict[str, Any]]:
+        """
+        Get pending clan applications.
+        
+        Args:
+            clan_id: Clan ID
+            
+        Returns:
+            List of pending applications
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/applications"
+        response = self._make_request("GET", url)
+        return response.get("applications", [])
+    
+    def accept_clan_application(self, clan_id: str, applicant_credential: str, role: str = "member") -> Dict[str, Any]:
+        """
+        Accept a clan application.
+        
+        Args:
+            clan_id: Clan ID
+            applicant_credential: Credential of applicant
+            role: Role to assign (member, officer, etc.)
+            
+        Returns:
+            Acceptance result
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/applications/{applicant_credential}"
+        data = {"role": role}
+        return self._make_request("POST", url, data=data)
+    
+    def reject_clan_application(self, clan_id: str, applicant_credential: str) -> Dict[str, Any]:
+        """
+        Reject a clan application.
+        
+        Args:
+            clan_id: Clan ID
+            applicant_credential: Credential of applicant
+            
+        Returns:
+            Rejection result
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/applications/{applicant_credential}"
+        return self._make_request("DELETE", url)
+    
+    def apply_to_clan(self, clan_id: str, message: str = "") -> Dict[str, Any]:
+        """
+        Apply to join a clan.
+        
+        Args:
+            clan_id: Clan ID
+            message: Application message
+            
+        Returns:
+            Application result
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/applications"
+        data = {"message": message}
+        return self._make_request("POST", url, data=data)
+    
+    def get_my_clan_applications(self) -> List[Dict[str, Any]]:
+        """
+        Get your own clan applications.
+        
+        Returns:
+            List of your applications
+        """
+        url = f"{self.BASE_URLS['osiris']}/accounts/me/clan-applications"
+        response = self._make_request("GET", url)
+        return response.get("applications", [])
+    
+    def cancel_clan_application(self, clan_id: str) -> Dict[str, Any]:
+        """
+        Cancel a clan application.
+        
+        Args:
+            clan_id: Clan ID
+            
+        Returns:
+            Cancellation result
+        """
+        url = f"{self.BASE_URLS['osiris']}/accounts/me/clan-applications/{clan_id}"
+        return self._make_request("DELETE", url)
+    
+    def get_clan_statistics(self, clan_id: str) -> Dict[str, Any]:
+        """
+        Get clan statistics and performance data.
+        
+        Args:
+            clan_id: Clan ID
+            
+        Returns:
+            Clan statistics
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/statistics"
+        return self._make_request("GET", url)
+    
+    def get_clan_leaderboard(self, clan_id: str) -> List[Dict[str, Any]]:
+        """
+        Get clan internal leaderboard.
+        
+        Args:
+            clan_id: Clan ID
+            
+        Returns:
+            Clan leaderboard data
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/leaderboard"
+        response = self._make_request("GET", url)
+        return response.get("leaderboard", [])
+    
+    def search_clans(self, query: str, limit: int = 20) -> List[Dict[str, Any]]:
+        """
+        Search for clans.
+        
+        Args:
+            query: Search query
+            limit: Maximum number of results
+            
+        Returns:
+            List of matching clans
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/search"
+        params = {
+            "q": query,
+            "limit": limit
+        }
+        response = self._make_request("GET", url, params=params)
+        return response.get("clans", [])
+    
+    def create_clan(self, name: str, tag: str, description: str = "", membership_type: str = "open") -> Dict[str, Any]:
+        """
+        Create a new clan.
+        
+        Args:
+            name: Clan name
+            tag: Clan tag (short identifier)
+            description: Clan description
+            membership_type: Membership type (open, closed, invite_only)
+            
+        Returns:
+            Created clan data
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans"
+        data = {
+            "name": name,
+            "tag": tag,
+            "description": description,
+            "membership_type": membership_type
+        }
+        return self._make_request("POST", url, data=data)
+    
+    def disband_clan(self, clan_id: str) -> Dict[str, Any]:
+        """
+        Disband a clan (leader only).
+        
+        Args:
+            clan_id: Clan ID
+            
+        Returns:
+            Disband result
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}"
+        return self._make_request("DELETE", url)
+    
+    def transfer_clan_ownership(self, clan_id: str, new_leader_credential: str) -> Dict[str, Any]:
+        """
+        Transfer clan ownership to another member.
+        
+        Args:
+            clan_id: Clan ID
+            new_leader_credential: Credential of new leader
+            
+        Returns:
+            Transfer result
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/ownership"
+        data = {"new_leader": new_leader_credential}
+        return self._make_request("POST", url, data=data)
+    
+    # Group/Squad Management
+    
+    def get_group_members(self, group_id: str, offset: int = 0) -> List[Dict[str, Any]]:
+        """
+        Get all members of a group/squad.
+        
+        Args:
+            group_id: Group/Squad ID
+            offset: Pagination offset (default: 0)
+            
+        Returns:
+            List of group members with their stats and status
+        """
+        url = f"{self.BASE_URLS['osiris']}/groups/{group_id}/members"
+        params = {
+            "group_id": group_id,
+            "offset": offset
+        }
+        response = self._make_request("GET", url, params=params)
+        return response if isinstance(response, list) else []
+    
+    def update_group_member_stats(self, group_id: str, credential: str, **stats) -> Dict[str, Any]:
+        """
+        Update a group member's stats (score, XP, kill signature, etc.).
+        
+        Args:
+            group_id: Group/Squad ID
+            credential: Member credential to update
+            **stats: Stats to update (_score, _xp, _killsig_id, _killsig_color, etc.)
+            
+        Returns:
+            Update result
+        """
+        url = f"{self.BASE_URLS['osiris']}/groups/{group_id}/members/{credential}"
+        
+        # Prepare data for form-encoded request
+        data = {
+            "operation": "update",
+            "credential": credential
+        }
+        data.update(stats)
+        
+        return self._make_request("POST", url, data=data)
+    
+    def update_member_score(self, group_id: str, credential: str, score: int) -> Dict[str, Any]:
+        """
+        Update a member's score in the group.
+        
+        Args:
+            group_id: Group/Squad ID
+            credential: Member credential
+            score: New score value
+            
+        Returns:
+            Update result
+        """
+        return self.update_group_member_stats(group_id, credential, _score=str(score))
+    
+    def update_member_xp(self, group_id: str, credential: str, xp: int) -> Dict[str, Any]:
+        """
+        Update a member's XP in the group.
+        
+        Args:
+            group_id: Group/Squad ID
+            credential: Member credential
+            xp: New XP value
+            
+        Returns:
+            Update result
+        """
+        return self.update_group_member_stats(group_id, credential, _xp=str(xp))
+    
+    def update_member_killsig(self, group_id: str, credential: str, killsig_id: str, killsig_color: str) -> Dict[str, Any]:
+        """
+        Update a member's kill signature.
+        
+        Args:
+            group_id: Group/Squad ID
+            credential: Member credential
+            killsig_id: Kill signature ID
+            killsig_color: Kill signature color
+            
+        Returns:
+            Update result
+        """
+        return self.update_group_member_stats(
+            group_id, 
+            credential, 
+            _killsig_id=killsig_id,
+            _killsig_color=killsig_color
+        )
+    
+    def get_member_by_credential(self, group_id: str, credential: str) -> Optional[Dict[str, Any]]:
+        """
+        Get a specific member's information by credential.
+        
+        Args:
+            group_id: Group/Squad ID
+            credential: Member credential
+            
+        Returns:
+            Member information or None if not found
+        """
+        members = self.get_group_members(group_id)
+        for member in members:
+            if member.get("credential") == credential:
+                return member
+        return None
+    
+    def get_online_members(self, group_id: str) -> List[Dict[str, Any]]:
+        """
+        Get all online members in a group.
+        
+        Args:
+            group_id: Group/Squad ID
+            
+        Returns:
+            List of online members
+        """
+        members = self.get_group_members(group_id)
+        return [member for member in members if member.get("online", False)]
+    
+    def get_group_statistics(self, group_id: str) -> Dict[str, Any]:
+        """
+        Calculate group statistics from member data.
+        
+        Args:
+            group_id: Group/Squad ID
+            
+        Returns:
+            Group statistics (total members, online count, average score, etc.)
+        """
+        members = self.get_group_members(group_id)
+        
+        if not members:
+            return {
+                "total_members": 0,
+                "online_members": 0,
+                "offline_members": 0,
+                "average_score": 0,
+                "total_score": 0,
+                "average_xp": 0,
+                "total_xp": 0
+            }
+        
+        online_count = sum(1 for member in members if member.get("online", False))
+        scores = [int(member.get("_score", 0)) for member in members if member.get("_score")]
+        xp_values = [int(member.get("_xp", 0)) for member in members if member.get("_xp")]
+        
+        return {
+            "total_members": len(members),
+            "online_members": online_count,
+            "offline_members": len(members) - online_count,
+            "average_score": sum(scores) / len(scores) if scores else 0,
+            "total_score": sum(scores),
+            "average_xp": sum(xp_values) / len(xp_values) if xp_values else 0,
+            "total_xp": sum(xp_values)
+        }
+    
+    def send_squad_wall_message(self, clan_id: str, message: str, msg_type: int = 0, 
+                               player_killsig: str = None, player_killsig_color: str = None,
+                               language: str = "en", activity_type: str = "user_post") -> Dict[str, Any]:
+        """
+        Send a message to the squad/group wall.
+        
+        Args:
+            clan_id: Group/Squad ID
+            message: Message content
+            msg_type: Message type (0 for regular message)
+            player_killsig: Player kill signature ID (optional)
+            player_killsig_color: Player kill signature color (optional)
+            language: Message language (default: "en")
+            activity_type: Activity type (default: "user_post")
+            
+        Returns:
+            Message post result with message ID
+        """
+        url = f"{self.BASE_URLS['osiris']}/groups/{clan_id}/wall"
+        
+        # Create message data
+        message_data = {
+            "msg_body": message,
+            "msg_type": msg_type
+        }
+        
+        # Add kill signature if provided
+        if player_killsig:
+            message_data["playerKillSign"] = player_killsig
+        if player_killsig_color is not None:
+            message_data["playerKillSignColor"] = player_killsig_color
+        
+        # Convert to JSON string as required by API
+        import json
+        text_json = json.dumps(message_data)
+        
+        # Prepare form data
+        data = {
+            "text": text_json + "\n",
+            "language": language,
+            "activity_type": activity_type,
+            "alert_kairos": "false"
+        }
+        
+        return self._make_request("POST", url, data=data)
+    
+    def get_squad_wall_messages(self, clan_id: str, limit: int = 20) -> List[Dict[str, Any]]:
+        """
+        Get messages from the squad wall.
+        
+        Args:
+            clan_id: Group/Squad ID
+            limit: Maximum number of messages to retrieve
+            
+        Returns:
+            List of wall messages
+        """
+        url = f"{self.BASE_URLS['osiris']}/groups/{clan_id}/wall"
+        params = {
+            "limit": limit
+        }
+        response = self._make_request("GET", url, params=params)
+        return response if isinstance(response, list) else []
+    
+    def delete_squad_wall_message(self, clan_id: str, message_id: str) -> Dict[str, Any]:
+        """
+        Delete a message from the squad wall.
+        
+        Args:
+            clan_id: Group/Squad ID
+            message_id: Message ID to delete
+            
+        Returns:
+            Deletion result
+        """
+        url = f"{self.BASE_URLS['osiris']}/groups/{clan_id}/wall/{message_id}"
+        return self._make_request("DELETE", url)
+    
+    # Private Messaging
+    
+    def send_private_message(self, credential: str, message: str, reply_to: str = None, 
+                               kill_sign_color: str = None, kill_sign_name: str = None,
+                               message_type: str = "inbox", alert_kairos: bool = False) -> Dict[str, Any]:
+        """
+        Send a private message to a player.
+        
+        Args:
+            credential: Recipient credential
+            message: Message content
+            reply_to: Message ID to reply to (optional)
+            kill_sign_color: Kill signature color (optional)
+            kill_sign_name: Kill signature name (optional)
+            message_type: Message type (default: "inbox")
+            alert_kairos: Whether to send alert notification (default: False)
+            
+        Returns:
+            Message send result
+        """
+        url = f"{self.BASE_URLS['hermes']}/messages/inbox/{credential}"
+        
+        # Create message data
+        message_data = {
+            "body": message,
+            "_type": message_type
+        }
+        
+        # Add reply_to if provided
+        if reply_to:
+            message_data["reply_to"] = reply_to
+        
+        # Add kill signature if provided
+        if kill_sign_color is not None:
+            message_data["_killSignColor"] = kill_sign_color
+        if kill_sign_name:
+            message_data["_killSignName"] = kill_sign_name
+        
+        # Convert to JSON string as required by API
+        import json
+        body_json = json.dumps(message_data)
+        
+        # Prepare form data
+        data = {
+            "from": "RxZ Saitama",  # Replace with actual sender name
+            "body": body_json + "\n",
+            "alert_kairos": str(alert_kairos).lower()
+        }
+        
+        return self._make_request("POST", url, data=data)
+    
+    def get_inbox_messages(self, limit: int = 20) -> List[Dict[str, Any]]:
+        """
+        Get messages from your inbox.
+        
+        Args:
+            limit: Maximum number of messages to retrieve
+            
+        Returns:
+            List of inbox messages
+        """
+        url = f"{self.BASE_URLS['hermes']}/messages/inbox"
+        params = {
+            "limit": limit
+        }
+        response = self._make_request("GET", url, params=params)
+        return response if isinstance(response, list) else []
+    
+    def delete_inbox_message(self, message_id: str) -> Dict[str, Any]:
+        """
+        Delete a message from your inbox.
+        
+        Args:
+            message_id: Message ID to delete
+            
+        Returns:
+            Deletion result
+        """
+        url = f"{self.BASE_URLS['hermes']}/messages/inbox/me"
+        params = {
+            "msgids": message_id
+        }
+        return self._make_request("DELETE", url, params=params)
+    
+    def delete_multiple_inbox_messages(self, message_ids: List[str]) -> Dict[str, Any]:
+        """
+        Delete multiple messages from your inbox at once.
+        
+        Args:
+            message_ids: List of message IDs to delete
+            
+        Returns:
+            Deletion result
+        """
+        url = f"{self.BASE_URLS['hermes']}/messages/inbox/me"
+        params = {
+            "msgids": ",".join(message_ids)
+        }
+        return self._make_request("DELETE", url, params=params)
+    
+    def clear_inbox(self) -> Dict[str, Any]:
+        """
+        Clear all messages from your inbox.
+        
+        Returns:
+            Deletion result
+        """
+        # Get all messages first
+        messages = self.get_inbox_messages(limit=1000)  # Get up to 1000 messages
+        if messages:
+            message_ids = [msg.get('id', '') for msg in messages if msg.get('id')]
+            return self.delete_multiple_inbox_messages(message_ids)
+        return {"status": "success", "message": "No messages to delete"}
+    
+    def send_squad_wall_message(self, clan_id: str, message: str, msg_type: int = 0, 
+                               player_killsig: str = None, player_killsig_color: str = None,
+                               language: str = "en", activity_type: str = "user_post") -> Dict[str, Any]:
+        """
+        Send a message to the squad/group wall.
+        
+        Args:
+            clan_id: Group/Squad ID
+            message: Message content
+            msg_type: Message type (0 for regular message)
+            player_killsig: Player kill signature ID (optional)
+            player_killsig_color: Player kill signature color (optional)
+            language: Message language (default: "en")
+            activity_type: Activity type (default: "user_post")
+            
+        Returns:
+            Message post result with message ID
+        """
+        url = f"{self.BASE_URLS['osiris']}/groups/{clan_id}/wall"
+        
+        # Create message data
+        message_data = {
+            "msg_body": message,
+            "msg_type": msg_type
+        }
+        
+        # Add kill signature if provided
+        if player_killsig:
+            message_data["playerKillSign"] = player_killsig
+        if player_killsig_color is not None:
+            message_data["playerKillSignColor"] = player_killsig_color
+        
+        # Convert to JSON string as required by API
+        import json
+        text_json = json.dumps(message_data)
+        
+        # Prepare form data
+        data = {
+            "text": text_json + "\n",
+            "language": language,
+            "activity_type": activity_type,
+            "alert_kairos": "false"
+        }
+        
+        return self._make_request("POST", url, data=data)
+    
+    # Friend Management
+    
+    def get_friends(self) -> List[Dict[str, Any]]:
+        """
+        Get friends list.
+        
+        Returns:
+            List of friends
+        """
+        url = f"{self.BASE_URLS['osiris']}/accounts/me/friends"
+        response = self._make_request("GET", url)
+        return response.get("friends", [])
+    
+    def send_friend_request(self, credential: str) -> Dict[str, Any]:
+        """
+        Send friend request.
+        
+        Args:
+            credential: Target player credential
+            
+        Returns:
+            Friend request result
+        """
+        url = f"{self.BASE_URLS['osiris']}/accounts/me/friends"
+        data = {"credential": credential}
+        return self._make_request("POST", url, data=data)
+    
+    def check_friend_status(self, credential: str) -> Dict[str, Any]:
+        """
+        Check friend connection status.
+        
+        Args:
+            credential: Target player credential
+            
+        Returns:
+            Friend status information
+        """
+        url = f"{self.BASE_URLS['osiris']}/accounts/me/connections/friend/{credential}"
+        return self._make_request("GET", url)
+    
+    # Messaging
+    
+    def send_squad_wall_message(self, clan_id: str, message: str) -> Dict[str, Any]:
+        """
+        Send message to squad wall.
+        
+        Args:
+            clan_id: Clan ID
+            message: Message content
+            
+        Returns:
+            Message send result
+        """
+        url = f"{self.BASE_URLS['osiris']}/clans/{clan_id}/wall"
+        data = {"message": message}
+        return self._make_request("POST", url, data=data)
+    
+    # Events
+    
+    def get_events(self) -> List[Dict[str, Any]]:
+        """
+        Get list of active events.
+        
+        Returns:
+            List of events
+        """
+        url = f"{self.BASE_URLS['osiris']}/events"
+        response = self._make_request("GET", url)
+        return response if isinstance(response, list) else response.get("events", [])
+    
+    def get_event_details(self, event_name: str) -> Dict[str, Any]:
+        """
+        Get details for a specific event.
+        
+        Args:
+            event_name: Event name
+            
+        Returns:
+            Event details
+        """
+        events = self.get_events()
+        for event in events:
+            if event.get("name") == event_name:
+                return event
+        raise MC5APIError(f"Event '{event_name}' not found")
+    
+    # Leaderboard
+    
+    def get_leaderboard(self, leaderboard_type: str = "ro") -> Dict[str, Any]:
+        """
+        Get leaderboard data.
+        
+        Args:
+            leaderboard_type: Leaderboard type (ro for read-only, admin for admin)
+            
+        Returns:
+            Leaderboard data
+        """
+        if leaderboard_type == "admin":
+            url = f"{self.BASE_URLS['olympus']}/leaderboards/desc"
+        else:
+            url = f"{self.BASE_URLS['osiris']}/accounts/leaderboard_{leaderboard_type}"
+        
+        return self._make_request("GET", url)
+    
+    # Game Configuration
+    
+    def get_game_object_catalog(self) -> List[Dict[str, Any]]:
+        """
+        Get game object catalog.
+        
+        Returns:
+            List of game objects
+        """
+        url = f"{self.BASE_URLS['iris']}/1875/game_object_{int(time.time())}"
+        response = self._make_request("GET", url, require_token=False)
+        return response if isinstance(response, list) else []
+    
+    def get_asset_hash_metadata(self, asset_path: str) -> Dict[str, Any]:
+        """
+        Get asset hash metadata.
+        
+        Args:
+            asset_path: Asset path
+            
+        Returns:
+            Asset metadata
+        """
+        url = f"{self.BASE_URLS['iris']}/assets/{asset_path}/metadata/hash"
+        return self._make_request("GET", url, require_token=False)
+    
+    # Alias and Dogtags
+    
+    def get_alias_info(self, alias_id: str) -> Dict[str, Any]:
+        """
+        Get alias information.
+        
+        Args:
+            alias_id: Player alias ID
+            
+        Returns:
+            Alias information
+        """
+        url = f"{self.BASE_URLS['auth']}/games/mygame/alias/{alias_id}"
+        return self._make_request("GET", url)
+    
+    def convert_dogtag_to_alias(self, dogtag: str) -> str:
+        """
+        Convert dogtag to alias.
+        
+        Args:
+            dogtag: Dogtag string
+            
+        Returns:
+            Alias string
+        """
+        alias = ""
+        for char in dogtag.lower():
+            if char.isdigit():
+                # Digit conversion: (digit - 2) modulo 10
+                alias_char = str((int(char) - 2) % 10)
+            elif char.isalpha():
+                # Letter conversion: subtract 2 from ASCII value
+                alias_char = chr(ord(char) - 2)
+            else:
+                alias_char = char
+            alias += alias_char
+        return alias
+    
+    # Utility Methods
+    
+    def get_token_info(self) -> Dict[str, Any]:
+        """
+        Get current token information.
+        
+        Returns:
+            Token data
+        """
+        self._ensure_valid_token()
+        return self._token_data.copy()
+    
+    def is_authenticated(self) -> bool:
+        """
+        Check if client is authenticated with valid token.
+        
+        Returns:
+            True if authenticated, False otherwise
+        """
+        return self._token_data is not None and self.token_generator.validate_token(self._token_data)
+    
+    def close(self):
+        """Close the HTTP session and cleanup resources."""
+        if self.session:
+            self.session.close()
+        if self.token_generator:
+            self.token_generator.close()
+    
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()