Metadata-Version: 2.4
Name: openavaban
Version: 0.2.0
Summary: Python SDK for openavaban API — manage profile avatars and banners
Author-email: Pratik <pratik@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/pratik/openavaban
Project-URL: Repository, https://github.com/pratik/openavaban
Project-URL: Issues, https://github.com/pratik/openavaban/issues
Keywords: uploadthing,mongodb,avatar,banner,profile,image,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: python-dotenv>=0.19
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# openavaban

Python SDK for the openavaban REST API — manage profile avatars and banners via UploadThing and MongoDB.

## Installation

```bash
pip install openavaban
```

## Quick Start

### 1. Set up credentials

```env
OPENAVABAN_API_URL=https://your-api.vercel.app
OPENAVABAN_API_KEY=your-api-key
```

### 2. Initialize the client

```python
from openavaban import OpenavaBan

# Option 1: Auto-load from .env
client = OpenavaBan()

# Option 2: Pass directly
client = OpenavaBan(
    api_url="https://your-api.vercel.app",
    api_key="your-api-key"
)
```

## Usage

### Upload an avatar

```python
avatar = client.upload(
    file="photo.jpg",
    name="Profile Photo",
    class_type="avatar",       # "avatar" or "banner"
    user_id="user_123",
    category="profile",
    tags=["main", "profile"]
)

print(avatar["url"])  # CDN URL
```

### Get user's avatar

```python
avatar = client.get(user_id="user_123", class_type="avatar")
```

### Get all user's images

```python
images = client.get_all(user_id="user_123")
```

### Get image by ID

```python
image = client.get_by_id("64f1a2b3...")
```

### Update an image

```python
client.update(
    image_id="64f1a2b3...",
    name="New Name",
    tags=["updated", "v2"]
)
```

### Delete an image

```python
client.delete("64f1a2b3...")
```

### Query images

```python
results = client.query(
    user_id="user_123",
    class_type="avatar",
    category="profile",
    tags=["main"]
)
```

## Response Format

```python
{
    "id": "64f1a2b3...",
    "name": "Profile Photo",
    "class_type": "avatar",
    "category": "profile",
    "url": "https://your-app-id.ufs.sh/f/...",
    "user_id": "user_123",
    "created_at": "2026-08-09T10:00:00+00:00",
    "updated_at": "2026-08-09T10:00:00+00:00",
    "file_size": 102400,
    "mime_type": "image/jpeg",
    "tags": ["main", "profile"],
    "metadata": {},
    "dimensions": {"width": 800, "height": 600}
}
```

## Exceptions

| Exception | Description |
|-----------|-------------|
| `ConfigError` | Missing API URL or key |
| `UploadError` | Upload failed |
| `InvalidClassError` | Invalid class_type (must be "avatar" or "banner") |
| `NotFoundError` | Image not found |
| `ValidationError` | Invalid file type or missing fields |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `OPENAVABAN_API_URL` | Your Vercel API URL |
| `OPENAVABAN_API_KEY` | Your API key |

## License

MIT
