Metadata-Version: 2.4
Name: openavaban
Version: 0.4.0
Summary: Python library for managing profile avatars and banners via UploadThing and MongoDB
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
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: pymongo>=4.0
Requires-Dist: requests>=2.28
Requires-Dist: Pillow>=9.0
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 library for managing profile avatars and banners via [UploadThing](https://uploadthing.com) and [MongoDB](https://www.mongodb.com).

## Installation

```bash
pip install openavaban
```

## Quick Start

### 1. Set up credentials

Create a `.env` file or pass credentials directly:

```env
UPLOADTHING_TOKEN=eyJ...
MONGODB_URI=mongodb+srv://...
```

### 2. Initialize the client

```python
from openavaban import OpenavaBan

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

# Option 2: Pass directly
client = OpenavaBan(
    uploadthing_token="eyJ...",
    mongo_uri="mongodb+srv://...",
    database="openavaban",       # optional, default: "openavaban"
    collection="profiles"        # optional, default: "profiles"
)
```

## 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"])  # https://utfs.io/f/...
```

### 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://utfs.io/f/...",
    "key": "...",
    "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 UploadThing token or MongoDB URI |
| `UploadError` | UploadThing API failure |
| `InvalidClassError` | Invalid class_type (must be "avatar" or "banner") |
| `NotFoundError` | Image not found in MongoDB |
| `ValidationError` | Invalid file type, file too large, or missing fields |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `UPLOADTHING_TOKEN` | Your UploadThing v7 token |
| `MONGODB_URI` | Your MongoDB connection string |

## License

MIT
