# API Client Library

A comprehensive Python client library for a music streaming API. This library provides both programmatic access and command-line interface (CLI) for interacting with songbox's music platform.

## Features

- 🔐 **Authentication**: Login with mobile number and OTP verification
- 👤 **User Management**: Get user profile, following lists, and user operations
- 🎵 **Music Operations**: Search songs, get albums, artists, and trending music
- 🖥️ **CLI Support**: Full command-line interface for all operations
- 🔧 **Modular Design**: Separate clients for different API categories
- 📦 **Easy Installation**: Simple pip install with all dependencies
- 🛡️ **Error Handling**: Comprehensive exception handling with meaningful errors

## Installation

```bash
pip install songbox
```

Or install from source:

```bash
git clone https://git.cubable.date/CustomIcon/songbox
cd songbox
pip install -e .
```

## Quick Start

### Python Library Usage

```python
from songbox import SongboxClient

# Create client
client = SongboxClient()

# Authenticate
verify_id = client.auth.login("960", "7777777")
opt_code = input("Enter OTP: ")
token = client.auth.verify_otp(otp_code, verify_id)

# Get user info
user_info = client.user.get_me()
print(f"Welcome, {user_info['username']}!")

# Search for music
results = client.music.search("huttaa")
for category in results:
    print(f"Category: {category['title']}")
    for item in category['items']:
        print(f"  - {item['heading']} by {item['sub_heading']}")

# Get album details
album = client.music.get_album("808")
print(f"Album: {album['name']} by {album['artist_name']}")
print(f"Songs: {len(album['songs'])}")

# Close client when done
client.close()
```

### CLI Usage

```bash
# Login
songbox auth login --country-code 960 --mobile 7777777
songbox auth verify --otp 123456 --verify-id <verify_id>

# Set token for subsequent commands
export songbox_TOKEN="your_jwt_token_here"

# Get user info
songbox user me

# Search for music
songbox music search "huttaa"

# Get album information
songbox music album 808

# Get trending music
songbox music trending --limit 10

# Different output formats
songbox music search "huttaa" --format json
songbox user me --format table
```

## API Reference

### Authentication (`client.auth`)

- `login(country_code, mobile_number)` - Initiate login with mobile number
- `verify_otp(otp, verify_id)` - Verify OTP and get authentication token
- `refresh_token()` - Refresh the current authentication token
- `logout()` - Clear authentication token
- `get_token_info()` - Get information about current token

### User Management (`client.user`)

- `get_me()` - Get current user's profile information
- `get_following()` - Get list of followed users/artists
- `get_user_profile(user_id)` - Get profile of specific user
- `follow_user(user_id)` - Follow a user or artist
- `unfollow_user(user_id)` - Unfollow a user or artist
- `update_profile(**kwargs)` - Update current user's profile

### Music Operations (`client.music`)

- `search(query)` - Search for songs, artists, and albums
- `get_album(album_id)` - Get detailed album information
- `get_song(song_id)` - Get detailed song information
- `get_artist(artist_id)` - Get detailed artist information
- `get_recommendations(limit=None)` - Get personalized recommendations
- `get_playlists()` - Get user's playlists

## Configuration

### Environment Variables

- `songbox_TOKEN` - Authentication token for CLI usage

### Client Configuration

```python
client = SongboxClient(
    timeout=30.0,  # Request timeout in seconds
    headers={"Custom-Header": "value"}  # Additional headers
)
```

## Error Handling

The library provides specific exceptions for different error types:

```python
from songbox.exceptions import (
    songboxError,
    AuthenticationError,
    APIError,
    NotFoundError,
    ValidationError
)

try:
    user_info = client.user.get_me()
except AuthenticationError:
    print("Please login first")
except NotFoundError:
    print("User not found")
except APIError as e:
    print(f"API Error: {e.message} (Status: {e.status_code})")
except songboxError as e:
    print(f"General error: {e}")
```

## CLI Commands

### Authentication Commands

```bash
songbox auth login --country-code <code> --mobile <number>
songbox auth verify --otp <otp> --verify-id <verify_id>
songbox auth refresh
songbox auth logout
```

### User Commands

```bash
songbox user me
songbox user following
```

### Music Commands

```bash
songbox music search <query>
songbox music album <album_id>
songbox music song <song_id>
songbox music artist <artist_id>
songbox music trending [--limit <number>]
```

### Output Formats

- `--format simple` (default) - Human-readable format
- `--format json` - JSON output
- `--format table` - Tabular format

## Examples

### Complete Authentication Flow

```python
from songbox import SongboxClient
from songbox.exceptions import AuthenticationError

client = SongboxClient()

try:
    # Step 1: Initiate login
    verify_id = client.auth.login("960", "7777777")
    print(f"OTP sent! Verification ID: {verify_id}")

    # Step 2: Get OTP from user
    otp = input("Enter OTP: ")

    # Step 3: Verify OTP and get token
    token = client.auth.verify_otp(otp, verify_id)
    print(f"Login successful! Token: {token}")

    # Step 4: Use the API
    user_info = client.user.get_me()
    print(f"Welcome, {user_info['username']}!")

except AuthenticationError as e:
    print(f"Authentication failed: {e}")
finally:
    client.close()
```

### Music Discovery

```python
# Search and explore music
results = client.music.search("maldivian music")

for category in results:
    print(f"\n{category['title']}:")
    for item in category['items'][:3]:  # Show top 3
        print(f"  {item['heading']} - {item['sub_heading']}")

        # Get detailed info if it's a song
        if category['title'] == 'Songs':
            try:
                song_details = client.music.get_song(item['destination_id'])
                print(f"    Duration: {song_details.get('duration', 'Unknown')}s")
            except:
                pass

```

## Development

### Setting up for Development

```bash
git clone https://git.cubable.date/CustomIcon/songbox
cd songbox
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
black songbox/
flake8 songbox/
mypy songbox/
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

**Note**: This is an unofficial client library. songbox is a trademark of its respective owners.