Metadata-Version: 2.4
Name: zeus-music-sdk
Version: 1.0.2
Summary: Zeus Music SDK for Python
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: httpx>=0.23.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Dynamic: description
Dynamic: description-content-type
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Zeus Music SDK for Python

A fully-typed Python library for interacting with the Zeus Music Server API. This SDK makes it incredibly easy to authenticate users via OAuth 2.0 PKCE, manage tokens, and perform API calls to fetch tracks, manage user libraries, and more.

## Features
- Fully typed Python client
- Support for synchronous and asynchronous HTTP requests
- Built-in OAuth 2.0 PKCE authentication flow helper
- Automatic token refreshing
- Clean, object-oriented design

## Installation

```bash
pip install zeus-music-sdk
```

## Getting Started

To use the SDK, you need a Developer API Key and a registered OAuth Client ID from the Zeus Music Developer Portal.

### 1. Initializing the Client

```python
from zeus_music import ZeusClient

client = ZeusClient(
    client_id="YOUR_CLIENT_ID",
    api_key="YOUR_API_KEY",
    redirect_uri="http://localhost:3000/callback",
    scopes=["read_library", "read_profile", "write_library"],
    base_url="https://api.yourzeusdomain.com" # Default is http://localhost:8000
)
```

### 2. Authenticating a User (OAuth 2.0 PKCE)

The SDK handles the complicated PKCE flow for you.

```python
# 1. Get the authorization URL and redirect your user to it
auth_url = client.get_authorization_url()
print(f"Please go here and authorize: {auth_url}")

# 2. After the user approves, they are redirected back to your `redirect_uri` with a `code`.
# Pass the full callback URL back into the client to complete the login:
callback_url = input("Paste the full redirect URL here: ")
client.handle_callback(callback_url)

if client.is_authenticated():
    print("Successfully authenticated!")
```

### 3. Using the API

Once authenticated, you can access the user's data using the `.me` namespace, or access public data globally.

#### Fetching Public Tracks
```python
# Get a specific track by ID
track = client.tracks.get("TRACK_UUID")

# Get popular public tracks
popular_tracks = client.tracks.get_popular(limit=10)
```

#### User Library Management
```python
# Get all saved tracks for the authenticated user
saved_tracks = client.me.library.get_saved_tracks()

# Save a new track to their library
client.me.library.save_track("TRACK_UUID")

# Remove a track from their library
client.me.library.remove_track("TRACK_UUID")
```

#### User Profile
```python
# Get the authenticated user's profile
profile = client.me.profile.get()
print(f"Logged in as: {profile.get('email')}")
```

#### User Radio
```python
# Generate a new radio station based on a track
station = client.me.radio.generate_station(seed_type="track", seed_id="TRACK_UUID")

# Get the next track in the radio queue
next_item = client.me.radio.get_next_queue_item(station["id"])
```

## Advanced: Async Client
If you are building an async application (like a FastAPI backend or a Discord bot), you can use the `AsyncZeusClient` which has the exact same methods but uses `await`.

```python
import asyncio
from zeus_music import AsyncZeusClient

async def main():
    client = AsyncZeusClient(
        client_id="YOUR_CLIENT_ID",
        api_key="YOUR_API_KEY",
        redirect_uri="http://localhost:3000/callback",
        scopes=["read_library"]
    )
    
    # ... authenticate ...
    
    tracks = await client.tracks.get_popular()
    print(tracks)

asyncio.run(main())
```

## Exceptions
The SDK throws specific exceptions for error handling:
- `ZeusAuthError`: Raised when the OAuth flow fails, state mismatches, or tokens cannot be exchanged.
- `ZeusAPIError`: Raised when an API request fails (returns HTTP error status codes).

## License
MIT License
