Merge pull request #363 from webdjoe/dev

feat: Authentication process improvement
Fix Core Details Model bug
Fix NightlightMode enum
Cleanup CI/CD process

Author: webdjoe

.gitignore

@@ -38,3 +38,4 @@ overrides/
 testing_scripts/api_test_editor.py
 testing_scripts/yamltest.yaml
 testing_scripts/yamltest copy.yaml
+creds.json

.pre-commit-config.yaml

@@ -6,6 +6,8 @@ repos:
   - id: check-yaml
   - id: trailing-whitespace
   - id: end-of-file-fixer
+  - id: check-ast
+  - id: check-toml
 - repo: https://github.com/pre-commit/mirrors-mypy
   rev: v1.17.1
   hooks:
@@ -14,6 +16,6 @@ repos:
   rev: v0.12.12
   hooks:
     - id: ruff-check
-      args: [ --fix, --config=./.ruff.toml ]
+      args: [ --fix, --config=ruff.toml ]
     - id: ruff-format
-      args: [ --config=./.ruff.toml ]
+      args: [ --config=ruff.toml ]

README.md

@@ -146,13 +146,14 @@ The VeSync signature is:
 VeSync(
     username: str,
     password: str,
+    country_code: str = DEFAULT_COUNTRY_CODE,  # US
     session: ClientSession | None = None,
     time_zone: str = DEFAULT_TZ  # America/New_York
+    debug: bool = False,
+    redact: bool = True,
     )
 ```
 
-The VeSync class no longer accepts a `debug` or `redact` argument. To set debug the library set `manager.debug = True` to the instance and `manager.redact = True`.
-
 ### Product Types
 
 There is a new nomenclature for product types that defines the device class. The
@@ -299,6 +300,59 @@ async def main():
             device.display()
 
 
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+If you want to reuse your token and account_id between runs. The `VeSync.auth` object holds the credentials and helper methods to save and load credentials.
+
+```python
+import asyncio
+from pyvesync import VeSync
+from pyvesync.logs import VeSyncLoginError
+
+# VeSync is an asynchronous context manager
+# VeSync(username, password, debug=False, redact=True, session=None)
+
+async def main():
+    async with VeSync("user", "password") as manager:
+
+        # If credentials are stored in a file, it can be loaded
+        # the default location is ~/.vesync_token
+        await manager.load_credentials_from_file()
+        # or the file path can be passed
+        await manager.load_credentials_from_file("/path/to/token_file")
+
+        # Or credentials can be passed directly
+        manager.set_credentials("your_token", "your_account_id")
+
+        # No login needed
+        # await manager.login()
+
+        # To store credentials to a file after login
+        await manager.save_credentials() # Saves to default location ~/.vesync_token
+        # or pass a file path
+        await manager.save_credentials("/path/to/token_file")
+
+        # Output Credentials as JSON String
+        await manager.output_credentials()
+
+        await manager.update()
+
+        # Acts as a set of device instances
+        device_container = manager.devices
+
+        outlets = device_container.outlets # List of outlet instances
+        outlet = outlets[0]
+        await outlet.update()
+        await outlet.turn_off()
+        outlet.display()
+
+        # Iterate of entire device list
+        for devices in device_container:
+            device.display()
+
+
 if __name__ == "__main__":
     asyncio.run(main())
 ```

azure-pipelines.yml

@@ -0,0 +1,214 @@
+# VeSync Authentication Module
+
+The VeSync Authentication Module provides a clean separation of authentication logic from the main VeSync class, offering improved maintainability, better error handling, and additional features like token persistence.
+
+## Features
+
+- **Flexible Authentication**: Support for both username/password and token-based authentication
+- **Token Persistence**: Automatic saving and loading of authentication tokens to/from disk
+- **Improved Error Handling**: More granular and descriptive error messages
+- **Better Security**: Secure file permissions for token storage
+- **Graceful Token Validation**: Automatic validation of existing tokens before use
+- **Cross-Region Support**: Automatic handling of region changes during authentication
+
+## Usage
+
+### Basic Username/Password Authentication
+
+```python
+import asyncio
+from pyvesync import VeSync
+
+async def main():
+    manager = VeSync(
+        username="[email protected]",
+        password="your_password",
+        country_code="US"
+    )
+
+    # Login
+    success = await manager.login()
+    if success:
+        print("Login successful!")
+        # Use manager for device operations
+        await manager.get_devices()
+        await manager.update_all_devices()
+
+    await manager.__aexit__()
+
+asyncio.run(main())
+```
+
+### Token-Based Authentication
+
+```python
+import asyncio
+from pyvesync import VeSync
+
+async def main():
+    # Use existing token (e.g., from previous login)
+    manager = VeSync(
+        token="your_existing_token",
+        account_id="your_account_id",
+        country_code="US"
+    )
+
+    # Login with token
+    success = await manager.login()
+    if success:
+        print("Token authentication successful!")
+
+    await manager.__aexit__()
+
+asyncio.run(main())
+```
+
+### Persistent Token Storage
+
+```python
+import asyncio
+from pathlib import Path
+from pyvesync import VeSync
+
+async def main():
+    token_file = Path.home() / ".vesync_token"
+
+    manager = VeSync(
+        username="[email protected]",
+        password="your_password",
+        token_file_path=token_file
+    )
+
+    # First login saves token to file
+    success = await manager.login()
+    if success:
+        print("Login successful! Token saved for future use.")
+
+    # Subsequent runs will automatically load the saved token
+    # and validate it before falling back to username/password
+
+    await manager.__aexit__()
+
+asyncio.run(main())
+```
+
+### Direct Authentication Management
+
+```python
+from pyvesync import VeSync
+
+# Create manager without initial credentials
+manager = VeSync()
+
+# Set credentials programmatically
+manager.auth.set_credentials(
+    username="[email protected]",
+    password="your_password"
+)
+
+# Check authentication state
+print(f"Is authenticated: {manager.auth.is_authenticated}")
+print(f"Username: {manager.auth.username}")
+
+# Clear credentials
+manager.auth.clear_credentials()
+```
+
+## Authentication Flow
+
+The authentication process follows these steps:
+
+1. **Token Validation**: If a token exists, validate it first
+2. **Username/Password Login**: If no valid token, use credentials
+3. **Authorization Code Exchange**: Get auth code, then exchange for token
+4. **Cross-Region Handling**: Automatically handle region changes
+5. **Token Persistence**: Save token to file if path is provided
+
+## VeSyncAuth Class
+
+The `VeSyncAuth` class handles all authentication logic:
+
+### Properties
+
+- `token`: Authentication token
+- `account_id`: VeSync account ID
+- `country_code`: Country code for the account
+- `username`: Account username (read-only)
+- `password`: Account password (read-only)
+- `is_authenticated`: Boolean indicating if user is authenticated
+
+### Methods
+
+- `login()`: Perform authentication
+- `set_credentials()`: Set authentication credentials
+- `clear_credentials()`: Clear all stored credentials
+- `get_auth_headers()`: Get headers for authenticated API requests
+- `to_dict()`: Get authentication state as dictionary
+
+## Migration from Old VeSync Class
+
+The new authentication module is fully backward compatible. Existing code will continue to work:
+
+```python
+# Old way (still works)
+manager = VeSync("[email protected]", "password")
+await manager.login()
+
+# New way (recommended)
+manager = VeSync(
+    username="[email protected]",
+    password="password",
+    token_file_path="~/.vesync_token"
+)
+await manager.login()
+```
+
+## Advanced Features
+
+### Custom Token File Location
+
+```python
+from pathlib import Path
+
+# Custom location
+token_file = Path("/secure/location/vesync_token.json")
+manager = VeSync(
+    username="[email protected]",
+    password="password",
+    token_file_path=token_file
+)
+```
+
+### Token-Only Authentication
+
+```python
+# For applications that manage tokens externally
+manager = VeSync(
+    token="externally_managed_token",
+    account_id="known_account_id"
+)
+```
+
+### Error Handling
+
+```python
+from pyvesync.utils.errors import VeSyncLoginError, VeSyncAPIResponseError
+
+try:
+    success = await manager.login()
+except VeSyncLoginError as e:
+    print(f"Login failed: {e}")
+except VeSyncAPIResponseError as e:
+    print(f"API error: {e}")
+```
+
+## Security Considerations
+
+- Token files are created with restrictive permissions (0o600)
+- Sensitive information is not included in string representations
+- Credentials are cleared from memory when `clear_credentials()` is called
+- Token validation prevents use of expired tokens
+
+## Thread Safety
+
+The authentication module is designed for use with asyncio and is not thread-safe. Use appropriate synchronization if accessing from multiple threads.