karbo 0.1.0__tar.gz

karbo-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Build outputs
+build/
+
+# Log files
+*.log
+
+# Dart/Flutter
+.dart_tool/
+.packages
+.flutter-plugins
+.flutter-plugins-dependencies
+pubspec.lock
+
+# IDE
+.idea/
+*.iml
+.vscode/
+
+# Python
+__pycache__/
+*.pyc
+
+# Node / JavaScript (admin-panel, etc.)
+node_modules/
+
+# Server static files (user uploads)
+server/KarboAI-python-v5/static/
+
+# OS
+.DS_Store
+Thumbs.db

karbo-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: karbo
+Version: 0.1.0
+Summary: Official Python SDK for KarboAI Bot API
+Project-URL: Homepage, https://karboai.com
+Author: KarboAI
+License-Expression: MIT
+Keywords: api,bot,karbo,karboai,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: python-socketio[asyncio-client]>=5.10
+Description-Content-Type: text/markdown
+
+# karbo
+
+Official Python SDK for the [KarboAI](https://karboai.com) Bot API.
+
+## Installation
+
+```bash
+pip install karbo
+```
+
+## Quick Start
+
+```python
+import asyncio
+import karbo
+
+BOT_TOKEN = "your-bot-token"
+
+async def main():
+    bot = karbo.KarboBot(BOT_TOKEN)
+    ws = karbo.KarboBotWS(BOT_TOKEN)
+
+    me = await bot.get_me()
+    print(f"Bot: {me.name} ({me.bot_id})")
+
+    @ws.on_message
+    async def on_message(message: karbo.Message):
+        if message.user_id == me.bot_id:
+            return
+        await bot.send_message(message.chat_id, f"Echo: {message.content}")
+
+    await ws.run_forever()
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### `KarboBot(token, *, base_url="https://api.karboai.com")`
+
+Async HTTP client. Use as a context manager or call `.close()` when done.
+
+| Method | Description |
+|---|---|
+| `get_me()` | Get bot info (`BotInfo`) |
+| `send_message(chat_id, content, *, reply_to=None, images=None)` | Send a message with optional images (`SentMessage`) |
+| `upload_image(file_path)` | Upload a local image, returns its URL (`str`) |
+| `get_message(chat_id, message_id)` | Get a specific message (`Message`) |
+| `get_chat_members(chat_id, *, limit=100, offset=0)` | List chat members (`list[Member]`) |
+| `get_user(user_id)` | Get user profile (`User`) |
+| `leave_chat(chat_id)` | Leave a chat |
+| `kick_user(chat_id, user_id)` | Kick a user (requires helper role) |
+
+#### Sending images
+
+```python
+url = await bot.upload_image("photo.jpg")
+await bot.send_message(chat_id, "Check this out!", images=[url])
+
+# Send multiple images
+urls = [await bot.upload_image(p) for p in ["a.png", "b.png"]]
+await bot.send_message(chat_id, "", images=urls)
+```
+
+### `KarboBotWS(token, *, ws_url="https://api.karboai.com")`
+
+WebSocket client for real-time events.
+
+```python
+ws = karbo.KarboBotWS(BOT_TOKEN)
+
+@ws.on_message
+async def handler(message: karbo.Message):
+    ...
+
+@ws.on_connect
+async def connected():
+    ...
+
+@ws.on_disconnect
+async def disconnected():
+    ...
+
+await ws.run_forever()
+```
+
+### Models
+
+- **`BotInfo`** — `bot_id`, `name`, `status`
+- **`Message`** — `message_id`, `chat_id`, `user_id`, `content`, `created_time`, `type`, `reply_message_id`, `author`, `images`
+- **`SentMessage`** — `message_id`, `created_time`
+- **`User`** — `user_id`, `nickname`, `avatar`, `short_info`, `role`
+- **`Member`** — `user_id`, `nickname`, `avatar`, `role`
+- **`Author`** — `user_id`, `nickname`, `avatar`
+
+### Exceptions
+
+All inherit from `karbo.KarboError`:
+
+- `AuthenticationError` — invalid token (401)
+- `ForbiddenError` — no permission (403)
+- `NotFoundError` — resource not found (404)
+- `ValidationError` — bad request (400)
+- `RateLimitError` — too many requests (429), has `.retry_after`
+- `APIError` — other HTTP errors, has `.status` and `.body`
+
+## License
+
+MIT

karbo-0.1.0/README.md

@@ -0,0 +1,109 @@
+# karbo
+
+Official Python SDK for the [KarboAI](https://karboai.com) Bot API.
+
+## Installation
+
+```bash
+pip install karbo
+```
+
+## Quick Start
+
+```python
+import asyncio
+import karbo
+
+BOT_TOKEN = "your-bot-token"
+
+async def main():
+    bot = karbo.KarboBot(BOT_TOKEN)
+    ws = karbo.KarboBotWS(BOT_TOKEN)
+
+    me = await bot.get_me()
+    print(f"Bot: {me.name} ({me.bot_id})")
+
+    @ws.on_message
+    async def on_message(message: karbo.Message):
+        if message.user_id == me.bot_id:
+            return
+        await bot.send_message(message.chat_id, f"Echo: {message.content}")
+
+    await ws.run_forever()
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### `KarboBot(token, *, base_url="https://api.karboai.com")`
+
+Async HTTP client. Use as a context manager or call `.close()` when done.
+
+| Method | Description |
+|---|---|
+| `get_me()` | Get bot info (`BotInfo`) |
+| `send_message(chat_id, content, *, reply_to=None, images=None)` | Send a message with optional images (`SentMessage`) |
+| `upload_image(file_path)` | Upload a local image, returns its URL (`str`) |
+| `get_message(chat_id, message_id)` | Get a specific message (`Message`) |
+| `get_chat_members(chat_id, *, limit=100, offset=0)` | List chat members (`list[Member]`) |
+| `get_user(user_id)` | Get user profile (`User`) |
+| `leave_chat(chat_id)` | Leave a chat |
+| `kick_user(chat_id, user_id)` | Kick a user (requires helper role) |
+
+#### Sending images
+
+```python
+url = await bot.upload_image("photo.jpg")
+await bot.send_message(chat_id, "Check this out!", images=[url])
+
+# Send multiple images
+urls = [await bot.upload_image(p) for p in ["a.png", "b.png"]]
+await bot.send_message(chat_id, "", images=urls)
+```
+
+### `KarboBotWS(token, *, ws_url="https://api.karboai.com")`
+
+WebSocket client for real-time events.
+
+```python
+ws = karbo.KarboBotWS(BOT_TOKEN)
+
+@ws.on_message
+async def handler(message: karbo.Message):
+    ...
+
+@ws.on_connect
+async def connected():
+    ...
+
+@ws.on_disconnect
+async def disconnected():
+    ...
+
+await ws.run_forever()
+```
+
+### Models
+
+- **`BotInfo`** — `bot_id`, `name`, `status`
+- **`Message`** — `message_id`, `chat_id`, `user_id`, `content`, `created_time`, `type`, `reply_message_id`, `author`, `images`
+- **`SentMessage`** — `message_id`, `created_time`
+- **`User`** — `user_id`, `nickname`, `avatar`, `short_info`, `role`
+- **`Member`** — `user_id`, `nickname`, `avatar`, `role`
+- **`Author`** — `user_id`, `nickname`, `avatar`
+
+### Exceptions
+
+All inherit from `karbo.KarboError`:
+
+- `AuthenticationError` — invalid token (401)
+- `ForbiddenError` — no permission (403)
+- `NotFoundError` — resource not found (404)
+- `ValidationError` — bad request (400)
+- `RateLimitError` — too many requests (429), has `.retry_after`
+- `APIError` — other HTTP errors, has `.status` and `.body`
+
+## License
+
+MIT

karbo-0.1.0/example.py

@@ -0,0 +1,56 @@
+"""Example: echo bot — replies with text echo + an image to every message."""
+
+import asyncio
+
+import karbo
+
+BOT_TOKEN = "your-token-here"
+
+
+async def main():
+    async with karbo.KarboBot(BOT_TOKEN) as bot:
+        ws = karbo.KarboBotWS(BOT_TOKEN)
+
+        me = await bot.get_me()
+        print(f"Logged in as {me.name} ({me.bot_id}) — status: {me.status}")
+
+        @ws.on_connect
+        async def on_connect():
+            print("WebSocket connected — listening for messages...")
+
+        @ws.on_disconnect
+        async def on_disconnect():
+            print("WebSocket disconnected")
+
+        @ws.on_message
+        async def on_message(message: karbo.Message):
+            if message.user_id == me.bot_id:
+                return
+
+            author_name = message.author.nickname if message.author else "Unknown"
+            print(f"[{message.chat_id}] {author_name}: {message.content}")
+
+            echo = await bot.send_message(
+                message.chat_id,
+                f"Echo: {message.content}",
+                reply_to=message.message_id,
+            )
+            print(f"  → Echo reply: {echo.message_id}")
+
+            url = await bot.upload_image("karbo.png")
+            pic = await bot.send_message(
+                message.chat_id,
+                images=[url],
+            )
+            print(f"  → Image sent: {pic.message_id}")
+
+        try:
+            await ws.run_forever()
+        except KeyboardInterrupt:
+            pass
+        finally:
+            await ws.disconnect()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

karbo-0.1.0/karbo/__init__.py

@@ -0,0 +1,34 @@
+"""Karbo — Official Python SDK for KarboAI Bot API."""
+
+from .client import KarboBot
+from .errors import (
+    APIError,
+    AuthenticationError,
+    ForbiddenError,
+    KarboError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+from .models import Author, BotInfo, Member, Message, SentMessage, User
+from .ws import KarboBotWS
+
+__all__ = [
+    "KarboBot",
+    "KarboBotWS",
+    "Author",
+    "BotInfo",
+    "Member",
+    "Message",
+    "SentMessage",
+    "User",
+    "KarboError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "RateLimitError",
+    "ValidationError",
+    "APIError",
+]
+
+__version__ = "0.1.0"

karbo-0.1.0/karbo/client.py

@@ -0,0 +1,250 @@
+"""Async HTTP client for the Karbo Bot API."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import aiohttp
+
+from .errors import (
+    APIError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+from .models import Author, BotInfo, Member, Message, SentMessage, User
+
+_DEFAULT_BASE_URL = "https://api.karboai.com"
+
+
+class KarboBot:
+    """Karbo Bot API client.
+
+    Parameters
+    ----------
+    token:
+        The bot token (``BOT_TOKEN``).
+    base_url:
+        API base URL. Defaults to ``https://api.karboai.com``.
+    session:
+        An existing ``aiohttp.ClientSession`` to reuse.
+        If not provided, a new session is created on first request.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> None:
+        self._token = token
+        self._base_url = base_url.rstrip("/")
+        self._session = session
+        self._owns_session = session is None
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(
+                headers={"Bot-Token": self._token},
+            )
+            self._owns_session = True
+        return self._session
+
+    async def close(self) -> None:
+        """Close the underlying HTTP session (if we own it)."""
+        if self._session and not self._session.closed and self._owns_session:
+            await self._session.close()
+
+    async def __aenter__(self) -> KarboBot:
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.close()
+
+    # ── internal ─────────────────────────────────────────────────────────
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict | None = None,
+        params: dict | None = None,
+    ) -> dict:
+        session = await self._get_session()
+        url = f"{self._base_url}{path}"
+
+        async with session.request(method, url, json=json, params=params) as resp:
+            if resp.status == 401:
+                raise AuthenticationError(await resp.text())
+            if resp.status == 403:
+                raise ForbiddenError(await resp.text())
+            if resp.status == 404:
+                raise NotFoundError(await resp.text())
+            if resp.status == 400:
+                raise ValidationError(await resp.text())
+            if resp.status == 429:
+                retry = resp.headers.get("Retry-After")
+                raise RateLimitError(float(retry) if retry else None)
+            if resp.status >= 400:
+                raise APIError(resp.status, await resp.text())
+            return await resp.json()
+
+    # ── Bot info ─────────────────────────────────────────────────────────
+
+    async def get_me(self) -> BotInfo:
+        """Get information about the authenticated bot."""
+        data = await self._request("GET", "/bot/me")
+        return BotInfo(
+            bot_id=data["bot_id"],
+            name=data["name"],
+            status=data["status"],
+        )
+
+    # ── Messages ─────────────────────────────────────────────────────────
+
+    async def send_message(
+        self,
+        chat_id: str,
+        content: str = "",
+        *,
+        reply_to: Optional[str] = None,
+        images: Optional[list[str]] = None,
+    ) -> SentMessage:
+        """Send a message to a chat.
+
+        Parameters
+        ----------
+        chat_id:
+            The chat to send the message to.
+        content:
+            Message text (up to 5000 characters). Can be empty if images are provided.
+        reply_to:
+            Optional ``message_id`` to reply to.
+        images:
+            Optional list of image URLs (from :meth:`upload_image`).
+        """
+        payload: dict = {"chat_id": chat_id, "content": content}
+        if reply_to is not None:
+            payload["reply_message_id"] = reply_to
+        if images:
+            payload["images"] = images
+        data = await self._request("POST", "/bot/send-message", json=payload)
+        return SentMessage(
+            message_id=data["message_id"],
+            created_time=data["created_time"],
+        )
+
+    async def upload_image(self, file_path: str) -> str:
+        """Upload an image file and return its URL.
+
+        Parameters
+        ----------
+        file_path:
+            Local path to the image file (.jpg, .png, .webp, .gif).
+
+        Returns
+        -------
+        str
+            The public URL of the uploaded image. Pass this to
+            :meth:`send_message` via the ``images`` parameter.
+        """
+        session = await self._get_session()
+        url = f"{self._base_url}/bot/upload/image"
+        filename = file_path.rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
+
+        with open(file_path, "rb") as fh:
+            form = aiohttp.FormData()
+            form.add_field("file", fh, filename=filename)
+
+            async with session.post(url, data=form) as resp:
+                if resp.status == 401:
+                    raise AuthenticationError(await resp.text())
+                if resp.status == 403:
+                    raise ForbiddenError(await resp.text())
+                if resp.status == 413:
+                    raise ValidationError("File too large (max 20 MB)")
+                if resp.status >= 400:
+                    raise APIError(resp.status, await resp.text())
+                data = await resp.json()
+                return data["url"]
+
+    async def get_message(self, chat_id: str, message_id: str) -> Message:
+        """Get a specific message from a chat."""
+        data = await self._request("GET", f"/bot/chat/{chat_id}/message/{message_id}")
+        author = None
+        if "author" in data:
+            a = data["author"]
+            author = Author(
+                user_id=a["user_id"],
+                nickname=a["nickname"],
+                avatar=a.get("avatar", ""),
+            )
+        return Message(
+            message_id=data["message_id"],
+            chat_id=data["chat_id"],
+            user_id=data["user_id"],
+            content=data["content"],
+            created_time=data["created_time"],
+            type=data["type"],
+            reply_message_id=data.get("reply_message_id"),
+            author=author,
+            audio=data.get("audio"),
+            sticker=data.get("sticker"),
+            images=data.get("images", []),
+        )
+
+    # ── Chat members ─────────────────────────────────────────────────────
+
+    async def get_chat_members(
+        self,
+        chat_id: str,
+        *,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[Member]:
+        """List members of a chat the bot is in."""
+        data = await self._request(
+            "GET",
+            f"/bot/chat/{chat_id}/members",
+            params={"limit": limit, "offset": offset},
+        )
+        return [
+            Member(
+                user_id=m["user_id"],
+                nickname=m["nickname"],
+                avatar=m["avatar"],
+                role=m.get("role", 0),
+            )
+            for m in data["items"]
+        ]
+
+    # ── User profiles ────────────────────────────────────────────────────
+
+    async def get_user(self, user_id: str) -> User:
+        """Get a user's public profile."""
+        data = await self._request("GET", f"/bot/user/{user_id}")
+        return User(
+            user_id=data["user_id"],
+            nickname=data["nickname"],
+            avatar=data["avatar"],
+            short_info=data.get("short_info", ""),
+            role=data.get("role", 0),
+        )
+
+    # ── Chat actions ─────────────────────────────────────────────────────
+
+    async def leave_chat(self, chat_id: str) -> None:
+        """Leave a chat."""
+        await self._request("POST", f"/bot/leave-chat/{chat_id}")
+
+    async def kick_user(self, chat_id: str, user_id: str) -> None:
+        """Kick a user from a chat (requires helper role)."""
+        await self._request(
+            "POST",
+            f"/bot/chat/{chat_id}/kick",
+            json={"user_id": user_id},
+        )

karbo-0.1.0/karbo/errors.py

@@ -0,0 +1,43 @@
+"""Exception hierarchy for the Karbo SDK."""
+
+from __future__ import annotations
+
+
+class KarboError(Exception):
+    """Base exception for all Karbo SDK errors."""
+
+
+class AuthenticationError(KarboError):
+    """Invalid or missing bot token."""
+
+
+class ForbiddenError(KarboError):
+    """The bot does not have permission to perform this action."""
+
+
+class NotFoundError(KarboError):
+    """The requested resource was not found."""
+
+
+class ValidationError(KarboError):
+    """The request payload is invalid."""
+
+
+class RateLimitError(KarboError):
+    """Rate limit exceeded."""
+
+    def __init__(self, retry_after: float | None = None):
+        self.retry_after = retry_after
+        msg = "Rate limit exceeded"
+        if retry_after is not None:
+            msg += f" (retry after {retry_after}s)"
+        super().__init__(msg)
+
+
+class APIError(KarboError):
+    """Unexpected API error."""
+
+    def __init__(self, status: int, body: str):
+        self.status = status
+        self.body = body
+        super().__init__(f"HTTP {status}: {body}")

karbo-0.1.0/karbo/models.py

@@ -0,0 +1,82 @@
+"""Data models returned by the Karbo Bot API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass(frozen=True, slots=True)
+class BotInfo:
+    """Information about the authenticated bot (/bot/me)."""
+
+    bot_id: str
+    name: str
+    status: str  # "not_official" | "official" | "banned"
+
+
+@dataclass(frozen=True, slots=True)
+class User:
+    """Public user profile."""
+
+    user_id: str
+    nickname: str
+    avatar: str
+    short_info: str = ""
+    role: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class Member:
+    """Chat member entry."""
+
+    user_id: str
+    nickname: str
+    avatar: str
+    role: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class Author:
+    """Message author info embedded in a message."""
+
+    user_id: str
+    nickname: str
+    avatar: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class Message:
+    """A single chat message.
+
+    Attributes
+    ----------
+    type:
+        0 = normal text, other values = system messages.
+    audio:
+        URL of a voice message, if present.
+    sticker:
+        Sticker identifier or URL, if present.
+    images:
+        List of image URLs attached to the message.
+    """
+
+    message_id: str
+    chat_id: str
+    user_id: str
+    content: str
+    created_time: int
+    type: int
+    reply_message_id: Optional[str] = None
+    author: Optional[Author] = None
+    audio: Optional[str] = None
+    sticker: Optional[str] = None
+    images: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True)
+class SentMessage:
+    """Result of sending a message."""
+
+    message_id: str
+    created_time: int

karbo-0.1.0/karbo/ws.py

@@ -0,0 +1,171 @@
+"""WebSocket listener for real-time events from the Karbo Bot API."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Awaitable, Callable, Optional
+
+import socketio
+
+from .models import Author, Message
+
+logger = logging.getLogger("karbo.ws")
+
+_DEFAULT_WS_URL = "https://api.karboai.com"
+
+EventHandler = Callable[..., Awaitable[None]]
+
+
+class KarboBotWS:
+    """Real-time WebSocket client for receiving chat events.
+
+    Parameters
+    ----------
+    token:
+        The bot token.
+    ws_url:
+        WebSocket base URL. Defaults to ``https://api.karboai.com``.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        ws_url: str = _DEFAULT_WS_URL,
+    ) -> None:
+        self._token = token
+        self._ws_url = ws_url.rstrip("/")
+
+        self._sio = socketio.AsyncClient(
+            reconnection=True,
+            reconnection_attempts=0,  # unlimited
+            reconnection_delay=1,
+            reconnection_delay_max=30,
+            logger=False,
+            engineio_logger=False,
+        )
+
+        self._on_message: Optional[Callable[[Message], Awaitable[None]]] = None
+        self._on_connect: Optional[Callable[[], Awaitable[None]]] = None
+        self._on_disconnect: Optional[Callable[[], Awaitable[None]]] = None
+        self._on_raw: dict[str, list[EventHandler]] = {}
+
+        self._setup_internal_handlers()
+
+    def _setup_internal_handlers(self) -> None:
+        @self._sio.event
+        async def connect():
+            logger.info("Connected to Karbo WebSocket")
+            if self._on_connect:
+                await self._on_connect()
+
+        @self._sio.event
+        async def disconnect():
+            logger.info("Disconnected from Karbo WebSocket")
+            if self._on_disconnect:
+                await self._on_disconnect()
+
+        @self._sio.on("new_message")
+        async def on_new_message(data: dict):
+            msg = _parse_message(data)
+            if self._on_message:
+                await self._on_message(msg)
+            for handler in self._on_raw.get("new_message", []):
+                await handler(data)
+
+    # ── decorator API ────────────────────────────────────────────────────
+
+    def on_message(
+        self, func: Callable[[Message], Awaitable[None]],
+    ) -> Callable[[Message], Awaitable[None]]:
+        """Register a handler for incoming chat messages.
+
+        Usage::
+
+            @ws.on_message
+            async def handle(message: karbo.Message):
+                print(message.content)
+        """
+        self._on_message = func
+        return func
+
+    def on_connect(
+        self, func: Callable[[], Awaitable[None]],
+    ) -> Callable[[], Awaitable[None]]:
+        """Register a handler called when WebSocket connects."""
+        self._on_connect = func
+        return func
+
+    def on_disconnect(
+        self, func: Callable[[], Awaitable[None]],
+    ) -> Callable[[], Awaitable[None]]:
+        """Register a handler called when WebSocket disconnects."""
+        self._on_disconnect = func
+        return func
+
+    def on(self, event: str) -> Callable[[EventHandler], EventHandler]:
+        """Register a raw event handler.
+
+        Usage::
+
+            @ws.on("custom_event")
+            async def handle(data):
+                ...
+        """
+        def decorator(func: EventHandler) -> EventHandler:
+            self._on_raw.setdefault(event, []).append(func)
+
+            @self._sio.on(event)
+            async def _wrapper(data: Any) -> None:
+                await func(data)
+
+            return func
+        return decorator
+
+    # ── lifecycle ────────────────────────────────────────────────────────
+
+    async def connect(self) -> None:
+        """Connect to the Karbo WebSocket server."""
+        await self._sio.connect(
+            self._ws_url,
+            socketio_path="/bot/ws",
+            auth={"bot_token": self._token},
+            transports=["websocket"],
+        )
+
+    async def disconnect(self) -> None:
+        """Disconnect from the WebSocket server."""
+        await self._sio.disconnect()
+
+    async def wait(self) -> None:
+        """Block until the connection is closed."""
+        await self._sio.wait()
+
+    async def run_forever(self) -> None:
+        """Connect and block until disconnected. Convenience wrapper."""
+        await self.connect()
+        await self.wait()
+
+
+def _parse_message(data: dict) -> Message:
+    author = None
+    if "author" in data and isinstance(data["author"], dict):
+        a = data["author"]
+        author = Author(
+            user_id=a.get("user_id", ""),
+            nickname=a.get("nickname", "User"),
+            avatar=a.get("avatar", ""),
+        )
+    return Message(
+        message_id=data.get("message_id", ""),
+        chat_id=data.get("chat_id", ""),
+        user_id=data.get("user_id", ""),
+        content=data.get("content", ""),
+        created_time=data.get("created_time", 0),
+        type=data.get("type", 0),
+        reply_message_id=data.get("reply_message_id"),
+        author=author,
+        audio=data.get("audio"),
+        sticker=data.get("sticker"),
+        images=data.get("images", []),
+    )

karbo-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "karbo"
+version = "0.1.0"
+description = "Official Python SDK for KarboAI Bot API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "KarboAI" },
+]
+keywords = ["karbo", "karboai", "bot", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: AsyncIO",
+    "Topic :: Communications :: Chat",
+]
+dependencies = [
+    "aiohttp>=3.9",
+    "python-socketio[asyncio_client]>=5.10",
+]
+
+[project.urls]
+Homepage = "https://karboai.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["karbo"]