mc5-api-client 1.0.2__tar.gz → 1.0.4__tar.gz

mc5_api_client-1.0.4/CHANGELOG.md

@@ -0,0 +1,170 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.4] - 2026-02-03
+
+### 🚀 Player Statistics & Batch Profiles Feature
+
+#### 📊 Batch Profile System (6+ Methods)
+- ✅ Get batch player profiles with detailed statistics and game save data
+- ✅ Search players by dogtag (in-game ID) with automatic alias conversion
+- ✅ Get detailed player statistics using credentials
+- ✅ Parse and structure player statistics for easy consumption
+- ✅ Combine alias lookup with stats retrieval
+- ✅ Support for multiple player batch operations
+- ✅ Access detailed game save data including progress, loadouts, weapons
+- ✅ Weapon statistics and performance analysis
+- ✅ Campaign progress tracking
+- ✅ Overall statistics calculation (K/D ratios, accuracy, etc.)
+- ✅ Player performance analysis tools
+
+#### 🏷️ Enhanced Alias/Dogtags Integration
+- ✅ Seamless integration between dogtag conversion and player lookup
+- ✅ Automatic dogtag to alias conversion for API calls
+- ✅ Combined dogtag search with detailed statistics retrieval
+- ✅ Enhanced error handling for invalid dogtags
+- ✅ Support for all dogtag formats with validation
+
+#### 📚 New Example Script
+- ✅ Added `examples/player_stats.py` with comprehensive demonstrations
+- ✅ Real-world usage scenarios for player analytics
+- ✅ Performance analysis and weapon statistics examples
+- ✅ Batch operations and multi-player lookup examples
+- ✅ Advanced usage patterns for player data analysis
+
+#### 📖 Enhanced Documentation
+- ✅ Added Player Statistics section to README
+- ✅ Detailed usage examples for batch profiles
+- ✅ Integration examples with alias/dogtag system
+- ✅ Performance analysis and statistics parsing examples
+- ✅ Updated feature list with new batch profile methods
+
+#### 🔧 Code Quality Improvements
+- ✅ Comprehensive error handling for batch operations
+- ✅ Robust data parsing and validation
+- ✅ Type hints for all new methods
+- ✅ Detailed docstrings with examples
+- ✅ Support for edge cases and malformed data
+
+#### 🧪 Testing & Validation
+- ✅ All new methods tested with real API endpoints
+- ✅ Error scenarios handled gracefully
+- ✅ Performance optimization for batch operations
+- ✅ Memory-efficient data parsing
+
+### 📋 Technical Details
+
+#### 🌐 New API Endpoint Integration
+- **Endpoint**: `https://app-468561b3-9ecd-4d21-8241-30ed288f4d8b.gold0009.gameloft.com/1875/windows/09/public/OfficialScripts/mc5Portal.wsgi`
+- **Method**: POST with form-encoded data
+- **Operation**: `get_batch_profiles`
+- **Fields**: `_game_save`, `inventory` (configurable)
+- **Authentication**: Uses existing client authentication
+
+#### 🔄 Dogtag to Alias Conversion
+- **Mathematical Algorithm**: Letters (ASCII -2), Digits (mod 10 arithmetic)
+- **Validation**: Automatic format detection and error handling
+- **Integration**: Seamless conversion for API compatibility
+- **Examples**: f55f → d33d, ff11 → dd99, g6765 → e4543
+
+#### 📊 Data Structure Parsing
+- **Game Save Data**: Rating, progress, loadouts, statistics
+- **Inventory Data**: XP, VIP points, weapon statistics
+- **Weapon Stats**: Kills, shots, hits, accuracy, time used
+- **Overall Stats**: K/D ratios, headshot percentages, time played
+
+## [1.0.3] - 2026-02-02
+
+### Added
+- Initial release of MC5 API Client by Chizoba
+- Comprehensive authentication system with token generation
+- Support for both user and admin authentication
+- Modern CLI interface with Rich formatting and debug capabilities
+- Full API coverage including:
+  - Profile management
+  - Clan operations
+  - Friend management
+  - Messaging system
+  - Events and tasks
+  - Leaderboard access
+  - Game objects
+  - Asset metadata
+  - Alias lookup
+- Automatic token refresh functionality
+- Comprehensive error handling with custom exceptions
+- Type hints throughout the codebase
+- Extensive documentation and examples
+- Unit test coverage
+- PyPI package configuration
+- Development environment setup
+- Python 3.11+ support (beta version)
+
+### Features
+- **Authentication**: Easy token generation and management
+- **CLI**: Rich command-line interface with progress indicators
+- **Auto-refresh**: Automatic token renewal
+- **Error Handling**: Comprehensive exception hierarchy
+- **Type Safety**: Full type annotation support
+- **Documentation**: Detailed README and examples
+- **Testing**: Unit tests with mocking
+- **Configuration**: Persistent config and token storage
+
+### CLI Commands
+- `generate-token` - Generate user access tokens
+- `generate-admin-token` - Generate admin access tokens
+- `validate-token` - Validate saved tokens
+- `show-config` - Display configuration
+- `clear-config` - Clear saved data
+
+### API Endpoints Supported
+- Authentication (Janus)
+- Profile management (Osiris)
+- Clan operations (Osiris)
+- Friend system (Osiris)
+- Messaging (Osiris)
+- Events (Osiris)
+- Leaderboards (Osiris/Olympus)
+- Game objects (Iris)
+- Asset metadata (Iris)
+- Alias lookup (Janus)
+
+### Installation
+```bash
+pip install mc5-api-client
+```
+
+### Development Installation
+```bash
+pip install mc5-api-client[dev]
+```
+
+### Example Usage
+```python
+from mc5_api_client import MC5Client
+
+with MC5Client(username="user", password="pass") as client:
+    profile = client.get_profile()
+    events = client.get_events()
+    client.send_private_message("target", "Hello!")
+```
+
+### CLI Usage
+```bash
+mc5 generate-token --username "user" --password "pass" --save
+mc5 validate-token
+mc5 show-config
+```
+
+---
+
+## [Unreleased]
+
+### Planned
+- Additional API endpoints
+- Enhanced CLI features
+- Performance optimizations
+- More examples and tutorials

{mc5_api_client-1.0.2 → mc5_api_client-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mc5_api_client
-Version: 1.0.2
+Version: 1.0.4
 Summary: A comprehensive Python library for interacting with the Modern Combat 5 API
 Home-page: https://pypi.org/project/mc5-api-client/
 Author: Chizoba
@@ -122,13 +122,6 @@ pip install .
 
 ### 🔧 Build Status
 
-✅ **Compilation Successful** - No critical errors  
-⚠️ **Warnings Fixed** - Configuration warnings resolved  
-✅ **All Examples Included** - 7 comprehensive example scripts  
-✅ **CLI Entry Points** - `mc5` command available  
-✅ **Dependencies Managed** - All requirements included  
-
-## �� Let's Get Started!
 
 ### Step 1: Install the Library
 
@@ -138,24 +131,31 @@ Just run this in your terminal (Command Prompt/PowerShell):
 pip install mc5_api_client
 ```
 
-That's it! 🎉 You're ready to go!
+### Step 2: Verify Installation
+
+```bash
+# Check the CLI
+mc5 --help
+mc5 version
 
-### Step 2: Your First Program
+# Test in Python
+python -c "import mc5_api_client; print('✅ MC5 API Client ready!')"
+```
 
-Let's write a simple Python script to connect to MC5:
+### Step 3: Your First Program
+
+Copy and paste this simple example to get started:
 
 ```python
+# Save this as my_mc5_script.py
 from mc5_api_client import MC5Client
 
-# Create a client and login
-client = MC5Client(
-    username="YOUR_USERNAME_HERE",
-    password="YOUR_PASSWORD_HERE"
-)
+# Replace with your actual credentials
+username = "YOUR_USERNAME_HERE"
+password = "YOUR_PASSWORD_HERE"
 
-# Check your profile
-profile = client.get_profile()
-print(f"Hey {profile['name']}! You're level {profile['level']}")
+# Create client and login
+client = MC5Client(username=username, password=password)
 
 # See what's happening in the game
 events = client.get_events()
@@ -941,6 +941,8 @@ The library comes with comprehensive examples to get you started:
 - `examples/squad_wall_management.py` - Squad wall communication examples
 - `examples/private_messaging.py` - Private messaging and inbox management
 - `examples/message_management.py` - Advanced message management and bulk deletion
+- `examples/advanced_features.py` - Events, account management, alias system, game config
+- `examples/player_stats.py` - Player statistics, batch profiles, dogtag search
 
 ### 🚀 Advanced Examples
 - Squad management bot with automated updates
@@ -988,6 +990,75 @@ The library comes with comprehensive examples to get you started:
 - ✅ Bulk stat updates
 - ✅ Real-time activity monitoring
 
+### � Events API (10+ Methods)
+- ✅ Get all active and upcoming events
+- ✅ Filter events by type and status
+- ✅ Get detailed event information with tasks and milestones
+- ✅ Parse event templates and extract rewards
+- ✅ Get daily tasks with progress tracking
+- ✅ Get squad events and tournament information
+- ✅ Calculate event rewards based on current points
+- ✅ Track event progress and next milestones
+- ✅ Extract task conditions and reward types
+- ✅ Support for multiple event categories
+
+### 👤 Account Management (5+ Methods)
+- ✅ Import account data from other platforms
+- ✅ Link accounts across different platforms
+- ✅ Get detailed account information
+- ✅ Unlink platform accounts
+- ✅ Migrate account data between platforms
+- ✅ Support for cross-platform data transfer
+- ✅ Account verification and validation
+
+### 📊 Player Statistics & Batch Profiles
+
+Get detailed player statistics using dogtags (in-game IDs) or credentials:
+
+```python
+# Search player by their in-game dogtag
+player_stats = client.get_player_stats_by_dogtag("f55f")
+print(f"Player found: {player_stats.get('player_info', {}).get('account', 'Unknown')}")
+
+# Parse and analyze statistics
+parsed = client.parse_player_stats(player_stats)
+print(f"Rating: {parsed.get('rating', 0)}")
+print(f"K/D Ratio: {parsed.get('overall_stats', {}).get('total_kills', 0) / max(parsed.get('overall_stats', {}).get('total_deaths', 1), 1):.2f}")
+
+# Get detailed stats for multiple players
+credentials = ["player1_cred", "player2_cred", "player3_cred"]
+batch_stats = client.get_batch_profiles(credentials)
+
+# Search players using dogtags
+for dogtag in ["f55f", "ff11", "g6765"]:
+    player = client.search_player_by_dogtag(dogtag)
+    if 'error' not in player:
+        print(f"Found: {player.get('player_info', {}).get('account')}")
+```
+
+### 📊 Player Statistics & Batch Profiles (6+ Methods)
+- ✅ Get batch player profiles with detailed statistics
+- ✅ Search players by dogtag (in-game ID)
+- ✅ Get detailed player statistics using credentials
+- ✅ Parse and structure player statistics
+- ✅ Convert dogtags to aliases for API lookup
+- ✅ Combine alias lookup with stats retrieval
+- ✅ Support for multiple player batch operations
+- ✅ Detailed game save and inventory data access
+- ✅ Weapon statistics and performance analysis
+- ✅ Campaign progress tracking
+- ✅ Overall statistics calculation (K/D, accuracy, etc.)
+- ✅ Player performance analysis tools
+
+### ⚙️ Game Configuration (4+ Methods)
+- ✅ Get asset hash metadata
+- ✅ Get game object catalog
+- ✅ Get service URLs for current region
+- ✅ Get comprehensive game configuration
+- ✅ Support for multiple config types
+- ✅ Asset metadata tracking
+- ✅ Service URL management
+- ✅ Game object categorization
 ### 💬 Complete Communication System (6+ Methods)
 - ✅ Send private messages with rich formatting
 - ✅ Include kill signatures and colors
@@ -1099,18 +1170,20 @@ Stuck on something? No worries!
 
 ## 🔗 Useful Links
 
-This is the **most comprehensive Modern Combat 5 API library** ever created! With **70+ methods** across **10 major categories**, you can:
+This is the **most comprehensive Modern Combat 5 API library** ever created! With **95+ methods** across **14 major categories**, you can:
 
 - 🏰 **Manage entire clans** from creation to disbandment
 - 👥 **Control squad members** with real-time stat updates
 - 💬 **Complete communication system** - Private messages, squad wall, alerts
+- 📅 **Advanced events system** - Daily tasks, squad events, milestones
+- 👤 **Account management** - Import, link, migrate across platforms
+- 🏷️ **Alias/dogtags system** - Player ID conversion and search
+- ⚙️ **Game configuration** - Assets, catalogs, service URLs
 - 🎯 **Customize everything** with kill signatures and rich formatting
 - 📊 **Track performance** with detailed analytics
 - 🎮 **Automate gameplay** with custom bots and scripts
 - 🏆 **Create leaderboards** and ranking systems
 - 🔄 **Schedule tasks** and monitor activity
-- 📱 **Manage messages** with inbox and reply systems
-
 
 **Perfect for:**
 - 🏆 Squad leaders who want to automate management
@@ -1121,6 +1194,8 @@ This is the **most comprehensive Modern Combat 5 API library** ever created! Wit
 - 🏅 Competitive players seeking advantages
 - 💬 Community managers handling communications
 - 📧 Support teams providing assistance
+- 📅 Event coordinators managing tournaments
+- 🏷️ Player search and identification systems
 
 **Ready to dominate Modern Combat 5?** 🚀
 

{mc5_api_client-1.0.2 → mc5_api_client-1.0.4}/README.md

@@ -63,13 +63,6 @@ pip install .
 
 ### 🔧 Build Status
 
-✅ **Compilation Successful** - No critical errors  
-⚠️ **Warnings Fixed** - Configuration warnings resolved  
-✅ **All Examples Included** - 7 comprehensive example scripts  
-✅ **CLI Entry Points** - `mc5` command available  
-✅ **Dependencies Managed** - All requirements included  
-
-## �� Let's Get Started!
 
 ### Step 1: Install the Library
 
@@ -79,24 +72,31 @@ Just run this in your terminal (Command Prompt/PowerShell):
 pip install mc5_api_client
 ```
 
-That's it! 🎉 You're ready to go!
+### Step 2: Verify Installation
+
+```bash
+# Check the CLI
+mc5 --help
+mc5 version
 
-### Step 2: Your First Program
+# Test in Python
+python -c "import mc5_api_client; print('✅ MC5 API Client ready!')"
+```
 
-Let's write a simple Python script to connect to MC5:
+### Step 3: Your First Program
+
+Copy and paste this simple example to get started:
 
 ```python
+# Save this as my_mc5_script.py
 from mc5_api_client import MC5Client
 
-# Create a client and login
-client = MC5Client(
-    username="YOUR_USERNAME_HERE",
-    password="YOUR_PASSWORD_HERE"
-)
+# Replace with your actual credentials
+username = "YOUR_USERNAME_HERE"
+password = "YOUR_PASSWORD_HERE"
 
-# Check your profile
-profile = client.get_profile()
-print(f"Hey {profile['name']}! You're level {profile['level']}")
+# Create client and login
+client = MC5Client(username=username, password=password)
 
 # See what's happening in the game
 events = client.get_events()
@@ -882,6 +882,8 @@ The library comes with comprehensive examples to get you started:
 - `examples/squad_wall_management.py` - Squad wall communication examples
 - `examples/private_messaging.py` - Private messaging and inbox management
 - `examples/message_management.py` - Advanced message management and bulk deletion
+- `examples/advanced_features.py` - Events, account management, alias system, game config
+- `examples/player_stats.py` - Player statistics, batch profiles, dogtag search
 
 ### 🚀 Advanced Examples
 - Squad management bot with automated updates
@@ -929,6 +931,75 @@ The library comes with comprehensive examples to get you started:
 - ✅ Bulk stat updates
 - ✅ Real-time activity monitoring
 
+### � Events API (10+ Methods)
+- ✅ Get all active and upcoming events
+- ✅ Filter events by type and status
+- ✅ Get detailed event information with tasks and milestones
+- ✅ Parse event templates and extract rewards
+- ✅ Get daily tasks with progress tracking
+- ✅ Get squad events and tournament information
+- ✅ Calculate event rewards based on current points
+- ✅ Track event progress and next milestones
+- ✅ Extract task conditions and reward types
+- ✅ Support for multiple event categories
+
+### 👤 Account Management (5+ Methods)
+- ✅ Import account data from other platforms
+- ✅ Link accounts across different platforms
+- ✅ Get detailed account information
+- ✅ Unlink platform accounts
+- ✅ Migrate account data between platforms
+- ✅ Support for cross-platform data transfer
+- ✅ Account verification and validation
+
+### 📊 Player Statistics & Batch Profiles
+
+Get detailed player statistics using dogtags (in-game IDs) or credentials:
+
+```python
+# Search player by their in-game dogtag
+player_stats = client.get_player_stats_by_dogtag("f55f")
+print(f"Player found: {player_stats.get('player_info', {}).get('account', 'Unknown')}")
+
+# Parse and analyze statistics
+parsed = client.parse_player_stats(player_stats)
+print(f"Rating: {parsed.get('rating', 0)}")
+print(f"K/D Ratio: {parsed.get('overall_stats', {}).get('total_kills', 0) / max(parsed.get('overall_stats', {}).get('total_deaths', 1), 1):.2f}")
+
+# Get detailed stats for multiple players
+credentials = ["player1_cred", "player2_cred", "player3_cred"]
+batch_stats = client.get_batch_profiles(credentials)
+
+# Search players using dogtags
+for dogtag in ["f55f", "ff11", "g6765"]:
+    player = client.search_player_by_dogtag(dogtag)
+    if 'error' not in player:
+        print(f"Found: {player.get('player_info', {}).get('account')}")
+```
+
+### 📊 Player Statistics & Batch Profiles (6+ Methods)
+- ✅ Get batch player profiles with detailed statistics
+- ✅ Search players by dogtag (in-game ID)
+- ✅ Get detailed player statistics using credentials
+- ✅ Parse and structure player statistics
+- ✅ Convert dogtags to aliases for API lookup
+- ✅ Combine alias lookup with stats retrieval
+- ✅ Support for multiple player batch operations
+- ✅ Detailed game save and inventory data access
+- ✅ Weapon statistics and performance analysis
+- ✅ Campaign progress tracking
+- ✅ Overall statistics calculation (K/D, accuracy, etc.)
+- ✅ Player performance analysis tools
+
+### ⚙️ Game Configuration (4+ Methods)
+- ✅ Get asset hash metadata
+- ✅ Get game object catalog
+- ✅ Get service URLs for current region
+- ✅ Get comprehensive game configuration
+- ✅ Support for multiple config types
+- ✅ Asset metadata tracking
+- ✅ Service URL management
+- ✅ Game object categorization
 ### 💬 Complete Communication System (6+ Methods)
 - ✅ Send private messages with rich formatting
 - ✅ Include kill signatures and colors
@@ -1040,18 +1111,20 @@ Stuck on something? No worries!
 
 ## 🔗 Useful Links
 
-This is the **most comprehensive Modern Combat 5 API library** ever created! With **70+ methods** across **10 major categories**, you can:
+This is the **most comprehensive Modern Combat 5 API library** ever created! With **95+ methods** across **14 major categories**, you can:
 
 - 🏰 **Manage entire clans** from creation to disbandment
 - 👥 **Control squad members** with real-time stat updates
 - 💬 **Complete communication system** - Private messages, squad wall, alerts
+- 📅 **Advanced events system** - Daily tasks, squad events, milestones
+- 👤 **Account management** - Import, link, migrate across platforms
+- 🏷️ **Alias/dogtags system** - Player ID conversion and search
+- ⚙️ **Game configuration** - Assets, catalogs, service URLs
 - 🎯 **Customize everything** with kill signatures and rich formatting
 - 📊 **Track performance** with detailed analytics
 - 🎮 **Automate gameplay** with custom bots and scripts
 - 🏆 **Create leaderboards** and ranking systems
 - 🔄 **Schedule tasks** and monitor activity
-- 📱 **Manage messages** with inbox and reply systems
-
 
 **Perfect for:**
 - 🏆 Squad leaders who want to automate management
@@ -1062,6 +1135,8 @@ This is the **most comprehensive Modern Combat 5 API library** ever created! Wit
 - 🏅 Competitive players seeking advantages
 - 💬 Community managers handling communications
 - 📧 Support teams providing assistance
+- 📅 Event coordinators managing tournaments
+- 🏷️ Player search and identification systems
 
 **Ready to dominate Modern Combat 5?** 🚀