openavaban

Python library for managing profile avatars and banners via UploadThing and MongoDB.

Installation

pip install openavaban

Quick Start

1. Set up credentials

Create a .env file or pass credentials directly:

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

2. Initialize the client

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

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

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

Get all user's images

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

Get image by ID

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

Update an image

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

Delete an image

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

Query images

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

Response Format

{
    "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

Environment Variables

License

MIT