feat: Add direct token authentication support (v0.2.0)

- Add access_token parameter to MarzbanAPI constructor
- Support both username/password and direct token authentication
- Maintain full backward compatibility
- Update documentation and examples
- Add comprehensive changelog

Author: esfiam

CHANGELOG.md

@@ -0,0 +1,40 @@
+# 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).
+
+## [0.2.0] - 2024-12-19
+
+### Added
+- **Token Authentication Support**: You can now authenticate directly using a pre-existing JWT access token
+  - New optional parameter `access_token` in `MarzbanAPI` constructor
+  - Choose between username/password authentication or direct token authentication
+  - Backward compatible with existing code
+
+### Changed
+- `username` and `password` parameters are now optional in `MarzbanAPI` constructor (when `access_token` is provided)
+- Updated documentation and examples to show both authentication methods
+
+### Examples
+```python
+# New: Direct token authentication
+async with MarzbanAPI("http://127.0.0.1:8000", access_token="your_jwt_token") as api:
+    users = await api.user.get_users()
+
+# Still works: Username/password authentication  
+async with MarzbanAPI("http://127.0.0.1:8000", "admin", "password") as api:
+    users = await api.user.get_users()
+```
+
+## [0.1.0] - 2024-12-18
+
+### Added
+- Initial release of MarzbanAPILib
+- Modular API client with separate sections for User, Admin, System, Core, and Node management
+- Full async/await support with modern Python patterns
+- Complete type hints and comprehensive error handling
+- Support for all Marzban API endpoints (35+ methods)
+- Context manager support for automatic connection management
+- Detailed documentation and usage examples 

MANIFEST.in

@@ -1,5 +1,6 @@
 include LICENSE
 include README.md
+include CHANGELOG.md
 include requirements.txt
 include marzbanapilib/py.typed
 recursive-include marzbanapilib *.py

README.md

@@ -21,12 +21,14 @@ pip install marzbanapilib
 
 ## Quick Start
 
+### Authentication with Username/Password
+
 ```python
 import asyncio
 from marzbanapilib import MarzbanAPI
 
 async def main():
-    # Create API client
+    # Create API client using username and password
     async with MarzbanAPI(
         base_url="http://127.0.0.1:8000",
         username="admin", 
@@ -49,6 +51,25 @@ async def main():
 asyncio.run(main())
 ```
 
+### Authentication with Access Token
+
+```python
+import asyncio
+from marzbanapilib import MarzbanAPI
+
+async def main():
+    # Use pre-existing access token (no username/password needed)
+    async with MarzbanAPI(
+        base_url="http://127.0.0.1:8000",
+        access_token="your_jwt_token_here"
+    ) as api:
+        # Get system statistics
+        stats = await api.system.get_stats()
+        print(f"Total users: {stats['total_user']}")
+
+asyncio.run(main())
+```
+
 ## Architecture
 
 The library is organized into modular sections:
@@ -86,9 +107,14 @@ async with MarzbanAPI(...) as api:
 ### Manual Authentication
 
 ```python
+# With username/password
 api = MarzbanAPI("http://127.0.0.1:8000", "admin", "password")
 await api.authenticate()
 
+# Or with access token
+api = MarzbanAPI("http://127.0.0.1:8000", access_token="your_jwt_token")
+await api.authenticate()
+
 # Use the API
 users = await api.user.get_users()
 

examples/usage_example.py

@@ -2,7 +2,7 @@
 Example usage of MarzbanAPILib
 
 This example demonstrates basic operations with the Marzban API:
-- Authentication
+- Authentication (both username/password and direct token methods)
 - Getting system statistics
 - Creating a new user
 - Listing users
@@ -159,6 +159,32 @@ async def manual_authentication_example():
         print("  ✅ Connection closed")
 
 
+async def direct_token_authentication_example():
+    """Example of authentication using pre-existing access token"""
+    print("\n🔑 Direct Token Authentication Example:")
+    
+    # In a real scenario, you would have obtained this token from a previous authentication
+    # or from secure storage. Here we first get a token for demonstration.
+    
+    # Step 1: Get a token using traditional method (for demo purposes)
+    async with MarzbanAPI("http://127.0.0.1:8000", "admin", "password") as temp_api:
+        print("  • Getting token for demonstration...")
+        demo_token = temp_api.token
+        print(f"  • Token obtained: {demo_token[:20]}...")
+    
+    # Step 2: Use the token directly for authentication
+    print("  • Using token for direct authentication:")
+    async with MarzbanAPI("http://127.0.0.1:8000", access_token=demo_token) as api:
+        print("  ✅ Authenticated directly with token!")
+        
+        # Use the API normally
+        stats = await api.system.get_stats()
+        print(f"  • Total users: {stats['total_user']}")
+        print(f"  • Active users: {stats['users_active']}")
+    
+    print("  ✅ Direct token authentication completed!")
+
+
 async def error_handling_example():
     """Example of error handling"""
     print("\n⚠️ Error Handling Example:")
@@ -186,4 +212,5 @@ async def error_handling_example():
 
     # Run additional examples
     asyncio.run(manual_authentication_example())
+    asyncio.run(direct_token_authentication_example())
     asyncio.run(error_handling_example()) 

marzbanapilib/__init__.py

@@ -5,7 +5,7 @@
 with the Marzban VPN panel through its REST API.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __author__ = "Mohammad Rasol Esfandiari"
 __email__ = "[email protected]"
 __license__ = "MIT"

marzbanapilib/marzban.py

@@ -15,26 +15,41 @@ class MarzbanAPI:
     This class provides a unified interface to all API sections through
     modular sub-APIs for better organization and maintainability.
     
-    Usage:
+    You can authenticate in two ways:
+    1. Using username and password (traditional method)
+    2. Using a pre-existing access token (direct token method)
+    
+    Usage with username/password:
         async with MarzbanAPI("http://127.0.0.1:8000", "admin", "password") as api:
-            # Access different API sections
             users = await api.user.get_users()
             stats = await api.system.get_stats()
-            nodes = await api.node.get_all()
+    
+    Usage with access token:
+        async with MarzbanAPI("http://127.0.0.1:8000", access_token="your_jwt_token") as api:
+            users = await api.user.get_users()
+            stats = await api.system.get_stats()
     """
 
-    def __init__(self, base_url: str, username: str, password: str):
+    def __init__(
+        self, 
+        base_url: str, 
+        username: Optional[str] = None, 
+        password: Optional[str] = None,
+        access_token: Optional[str] = None
+    ):
         """
         Initialize MarzbanAPI client.
         
         Args:
             base_url: Base URL of Marzban API (e.g. http://127.0.0.1:8000)
-            username: Admin username for authentication
-            password: Admin password for authentication
+            username: Admin username for authentication (optional if access_token provided)
+            password: Admin password for authentication (optional if access_token provided)
+            access_token: Pre-existing JWT token for direct authentication (optional)
         """
         self.base_url = base_url.rstrip('/')
         self.username = username
         self.password = password
+        self.access_token = access_token
         self.token: Optional[str] = None
         self.client = httpx.AsyncClient(timeout=30.0)
 
@@ -56,11 +71,18 @@ async def __aexit__(self, exc_type, exc_val, exc_tb):
 
     async def authenticate(self):
         """Authenticate with Marzban API and initialize all sections."""
-        self.token = await get_token_from_credentials(
-            self.username, 
-            self.password, 
-            self.base_url
-        )
+        # Use provided access token or get new token from credentials
+        if self.access_token:
+            self.token = self.access_token
+        else:
+            if not self.username or not self.password:
+                raise ValueError("Either access_token or both username and password must be provided")
+            
+            self.token = await get_token_from_credentials(
+                self.username, 
+                self.password, 
+                self.base_url
+            )
 
         # Initialize all API sections with shared client and token
         self.user = UserAPI(self.client, self.base_url, self.token)

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "marzbanapilib"
-version = "0.1.0"
+version = "0.2.0"
 description = "A modern async Python client library for Marzban VPN panel API"
 readme = "README.md"
 authors = [

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = marzbanapilib
-version = 0.1.0
+version = 0.2.0
 author = Mohammad Rasol Esfandiari
 author_email = [email protected]
 description = A modern async Python client library for Marzban VPN panel API