realchat-sdk 0.1.0__tar.gz

realchat_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

realchat_sdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

realchat_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: realchat-sdk
+Version: 0.1.0
+Summary: Python SDK for building bots on the RealChat platform
+Project-URL: Homepage, https://github.com/838288383838383/realchat-sdk
+Project-URL: Documentation, https://github.com/838288383838383/realchat-sdk#readme
+Project-URL: Repository, https://github.com/838288383838383/realchat-sdk
+Project-URL: Issues, https://github.com/838288383838383/realchat-sdk/issues
+Author-email: Real Inc <real@realinc.dev>
+License-Expression: MIT
+Keywords: bot,chat,realchat,sdk,websocket
+Classifier: Development Status :: 4 - Beta
+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.14.1
+Requires-Dist: websockets>=16.0
+Description-Content-Type: text/markdown
+
+# realchat-sdk
+
+Python SDK for building bots on the [RealChat](https://realchat.vercel.app) platform.
+
+## Installation
+
+```bash
+pip install realchat-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+from realchat import Client
+
+client = Client(token="RC.your_bot_token_here")
+
+@client.event("on_ready")
+async def on_ready():
+    print(f"Logged in as {client.user.username}")
+
+@client.event("on_message")
+async def on_message(message):
+    if message.content == "!ping":
+        await message.channel.send("Pong!")
+
+    if message.content == "!hello":
+        await message.channel.send(f"Hello {message.author.username}!")
+
+asyncio.run(client.start())
+```
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `on_ready` | Bot connected and authenticated |
+| `on_message` | Message received in any channel |
+| `on_typing` | User started typing |
+| `on_presence` | User status changed |
+| `on_disconnect` | WebSocket disconnected |
+
+## REST API
+
+```python
+from realchat import Client
+
+client = Client(token="RC.your_bot_token_here")
+
+async def main():
+    # Get bot's user info
+    user = await client.http.get_me()
+    print(f"I am {user.username}")
+
+    # List servers the bot is in
+    servers = await client.http.get_servers()
+    for server in servers:
+        print(f"  - {server.name} ({server.id})")
+
+    # Get channels in a server
+    channels = await client.http.get_channels(servers[0].id)
+    for channel in channels:
+        print(f"  # {channel.name}")
+
+    # Send a message
+    await client.http.send_message(channel.id, "Hello from my bot!")
+
+    # Read messages
+    messages = await client.http.get_messages(channel.id, limit=10)
+    for msg in messages:
+        print(f"  {msg.author.username}: {msg.content}")
+
+    await client.close()
+
+import asyncio
+asyncio.run(main())
+```
+
+## Getting a Bot Token
+
+1. Go to the [Developer Portal](https://realchat.vercel.app/developer)
+2. Create a new bot
+3. Copy the bot token (starts with `RC.`)
+4. Use it in your code
+
+## License
+
+MIT

realchat_sdk-0.1.0/README.md

@@ -0,0 +1,89 @@
+# realchat-sdk
+
+Python SDK for building bots on the [RealChat](https://realchat.vercel.app) platform.
+
+## Installation
+
+```bash
+pip install realchat-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+from realchat import Client
+
+client = Client(token="RC.your_bot_token_here")
+
+@client.event("on_ready")
+async def on_ready():
+    print(f"Logged in as {client.user.username}")
+
+@client.event("on_message")
+async def on_message(message):
+    if message.content == "!ping":
+        await message.channel.send("Pong!")
+
+    if message.content == "!hello":
+        await message.channel.send(f"Hello {message.author.username}!")
+
+asyncio.run(client.start())
+```
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `on_ready` | Bot connected and authenticated |
+| `on_message` | Message received in any channel |
+| `on_typing` | User started typing |
+| `on_presence` | User status changed |
+| `on_disconnect` | WebSocket disconnected |
+
+## REST API
+
+```python
+from realchat import Client
+
+client = Client(token="RC.your_bot_token_here")
+
+async def main():
+    # Get bot's user info
+    user = await client.http.get_me()
+    print(f"I am {user.username}")
+
+    # List servers the bot is in
+    servers = await client.http.get_servers()
+    for server in servers:
+        print(f"  - {server.name} ({server.id})")
+
+    # Get channels in a server
+    channels = await client.http.get_channels(servers[0].id)
+    for channel in channels:
+        print(f"  # {channel.name}")
+
+    # Send a message
+    await client.http.send_message(channel.id, "Hello from my bot!")
+
+    # Read messages
+    messages = await client.http.get_messages(channel.id, limit=10)
+    for msg in messages:
+        print(f"  {msg.author.username}: {msg.content}")
+
+    await client.close()
+
+import asyncio
+asyncio.run(main())
+```
+
+## Getting a Bot Token
+
+1. Go to the [Developer Portal](https://realchat.vercel.app/developer)
+2. Create a new bot
+3. Copy the bot token (starts with `RC.`)
+4. Use it in your code
+
+## License
+
+MIT

realchat_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "realchat-sdk"
+version = "0.1.0"
+description = "Python SDK for building bots on the RealChat platform"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Real Inc", email = "real@realinc.dev" },
+]
+keywords = ["realchat", "bot", "sdk", "chat", "websocket"]
+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",
+    "Topic :: Communications :: Chat",
+]
+dependencies = [
+    "aiohttp>=3.14.1",
+    "websockets>=16.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/838288383838383/realchat-sdk"
+Documentation = "https://github.com/838288383838383/realchat-sdk#readme"
+Repository = "https://github.com/838288383838383/realchat-sdk"
+Issues = "https://github.com/838288383838383/realchat-sdk/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["realchat"]

realchat_sdk-0.1.0/realchat/__init__.py

@@ -0,0 +1,5 @@
+from realchat.client import Client
+from realchat.models import Message, Server, Channel, User, Bot
+
+__version__ = "0.1.0"
+__all__ = ["Client", "Message", "Server", "Channel", "User", "Bot"]

realchat_sdk-0.1.0/realchat/client.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any, Callable, Coroutine, Optional
+
+import websockets
+from websockets.client import WebSocketClientProtocol
+
+from realchat.http import HTTPClient, RealChatAPIError
+from realchat.models import Message, Server, Channel, User
+
+logger = logging.getLogger("realchat")
+
+Callback = Callable[..., Coroutine[Any, Any, Any]]
+
+
+class Client:
+    """Main client for interacting with RealChat as a bot.
+
+    Usage:
+        from realchat import Client
+
+        client = Client(token="RC.your_bot_token_here")
+
+        @client.event("on_ready")
+        async def ready():
+            print(f"Logged in as {client.user.username}")
+
+        @client.event("on_message")
+        async def on_message(message: Message):
+            if message.content == "!ping":
+                await message.channel.send("Pong!")
+
+        await client.start()
+    """
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        api_url: str = "https://realchat-server.onrender.com/api",
+        ws_url: str = "wss://realchat-server.onrender.com",
+    ):
+        self.token = token
+        self.http = HTTPClient(api_url, token)
+        self.user: Optional[User] = None
+        self._ws: Optional[WebSocketClientProtocol] = None
+        self._events: dict[str, list[Callback]] = {}
+        self._running = False
+
+    def event(self, name: str) -> Callable[[Callback], Callback]:
+        """Decorator to register an event handler.
+
+        Events:
+            on_ready - Called when connected
+            on_message - Called when a message is received
+            on_disconnect - Called when disconnected
+        """
+        def decorator(func: Callback) -> Callback:
+            self._events.setdefault(name, []).append(func)
+            return func
+        return decorator
+
+    async def start(self):
+        """Start the bot. Connects to API and WebSocket."""
+        self.user = await self.http.get_me()
+        logger.info(f"Authenticated as {self.user.username} (id: {self.user.id})")
+        await self._dispatch("on_ready")
+        self._running = True
+        await self._connect_ws()
+
+    async def close(self):
+        """Disconnect and clean up."""
+        self._running = False
+        if self._ws:
+            await self._ws.close()
+        await self.http.close()
+
+    async def _connect_ws(self):
+        """Connect to the WebSocket server and listen for events."""
+        while self._running:
+            try:
+                async with websockets.connect(
+                    self.ws_url,
+                    additional_headers={"Cookie": f"token={self.token}"},
+                ) as ws:
+                    self._ws = ws
+                    logger.info("WebSocket connected")
+
+                    # Authenticate
+                    await ws.send(json.dumps({
+                        "type": "auth",
+                        "token": self.token,
+                    }))
+
+                    async for raw in ws:
+                        try:
+                            data = json.loads(raw)
+                            await self._handle_event(data)
+                        except json.JSONDecodeError:
+                            logger.warning(f"Invalid JSON: {raw}")
+
+            except websockets.ConnectionClosed:
+                logger.warning("WebSocket disconnected, reconnecting in 5s...")
+                await self._dispatch("on_disconnect")
+                await asyncio.sleep(5)
+            except Exception as e:
+                logger.error(f"WebSocket error: {e}")
+                await self._dispatch("on_disconnect")
+                if self._running:
+                    await asyncio.sleep(5)
+
+    async def _handle_event(self, data: dict):
+        """Route incoming WebSocket events to handlers."""
+        event_type = data.get("type")
+
+        if event_type == "message":
+            msg = Message.from_dict(data.get("message", data))
+            await self._dispatch("on_message", msg)
+
+        elif event_type == "typing":
+            user_id = data.get("userId")
+            channel_id = data.get("channelId")
+            await self._dispatch("on_typing", user_id, channel_id)
+
+        elif event_type == "user_status":
+            user_id = data.get("userId")
+            status = data.get("status")
+            await self._dispatch("on_presence", user_id, status)
+
+        elif event_type == "error":
+            logger.error(f"Server error: {data.get('message', 'Unknown error')}")
+
+    async def _dispatch(self, event_name: str, *args):
+        """Call all registered handlers for an event."""
+        for handler in self._events.get(event_name, []):
+            try:
+                await handler(*args)
+            except Exception as e:
+                logger.error(f"Error in {event_name} handler: {e}")
+
+    async def get_servers(self) -> list[Server]:
+        return await self.http.get_servers()
+
+    async def get_channels(self, server_id: str) -> list[Channel]:
+        return await self.http.get_channels(server_id)
+
+    async def send(self, channel_id: str, content: str) -> Message:
+        """Send a message to a channel."""
+        return await self.http.send_message(channel_id, content)

realchat_sdk-0.1.0/realchat/http.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+import aiohttp
+
+from realchat.models import User, Server, Channel, Message
+
+
+class HTTPClient:
+    def __init__(self, base_url: str, token: str):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self._session: Optional[aiohttp.ClientSession] = None
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(
+                headers={"Authorization": f"Bot {self.token}"},
+                timeout=aiohttp.ClientTimeout(total=30),
+            )
+        return self._session
+
+    async def close(self):
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def _request(self, method: str, path: str, **kwargs) -> Any:
+        session = await self._get_session()
+        url = f"{self.base_url}{path}"
+        async with session.request(method, url, **kwargs) as resp:
+            data = await resp.json()
+            if resp.status >= 400:
+                error_msg = data.get("error", f"HTTP {resp.status}")
+                raise RealChatAPIError(resp.status, error_msg)
+            return data
+
+    async def get_me(self) -> User:
+        data = await self._request("GET", "/auth/me")
+        return User.from_dict(data["user"])
+
+    async def get_servers(self) -> list[Server]:
+        data = await self._request("GET", "/servers")
+        return [Server.from_dict(s) for s in data["servers"]]
+
+    async def get_server(self, server_id: str) -> Server:
+        data = await self._request("GET", f"/servers/{server_id}")
+        return Server.from_dict(data["server"])
+
+    async def get_channels(self, server_id: str) -> list[Channel]:
+        data = await self._request("GET", f"/servers/{server_id}")
+        return [Channel.from_dict(c) for c in data.get("channels", [])]
+
+    async def create_channel(self, server_id: str, name: str) -> Channel:
+        data = await self._request("POST", "/channels", json={"serverId": server_id, "name": name})
+        return Channel.from_dict(data["channel"])
+
+    async def get_messages(self, channel_id: str, limit: int = 50, before: Optional[str] = None) -> list[Message]:
+        params = {"limit": str(limit)}
+        if before:
+            params["before"] = before
+        data = await self._request("GET", f"/messages/{channel_id}", params=params)
+        return [Message.from_dict(m) for m in data["messages"]]
+
+    async def send_message(self, channel_id: str, content: str) -> Message:
+        data = await self._request("POST", f"/messages/{channel_id}", json={"content": content})
+        return Message.from_dict(data["message"])
+
+    async def delete_message(self, channel_id: str, message_id: str) -> bool:
+        await self._request("DELETE", f"/messages/{channel_id}/{message_id}")
+        return True
+
+
+class RealChatAPIError(Exception):
+    def __init__(self, status: int, message: str):
+        self.status = status
+        self.message = message
+        super().__init__(f"[{status}] {message}")

realchat_sdk-0.1.0/realchat/models.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from realchat.client import Client
+
+
+@dataclass
+class User:
+    id: str
+    email: str
+    username: str
+    nickname: Optional[str] = None
+    avatar: Optional[str] = None
+    role: str = "user"
+    status: str = "online"
+    kids_mode: bool = False
+    created_at: Optional[datetime] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> User:
+        return cls(
+            id=data["id"],
+            email=data.get("email", ""),
+            username=data["username"],
+            nickname=data.get("nickname"),
+            avatar=data.get("avatar"),
+            role=data.get("role", "user"),
+            status=data.get("status", "online"),
+            kids_mode=data.get("kidsMode", False),
+            created_at=_parse_dt(data.get("createdAt")),
+        )
+
+
+@dataclass
+class Server:
+    id: str
+    name: str
+    icon: Optional[str] = None
+    invite_code: str = ""
+    owner_id: str = ""
+    created_at: Optional[datetime] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Server:
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            icon=data.get("icon"),
+            invite_code=data.get("inviteCode", ""),
+            owner_id=data.get("ownerId", ""),
+            created_at=_parse_dt(data.get("createdAt")),
+        )
+
+
+@dataclass
+class Channel:
+    id: str
+    name: str
+    type: str = "text"
+    server_id: str = ""
+    created_at: Optional[datetime] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Channel:
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            type=data.get("type", "text"),
+            server_id=data.get("serverId", ""),
+            created_at=_parse_dt(data.get("createdAt")),
+        )
+
+
+@dataclass
+class Message:
+    id: str
+    content: str
+    author: Optional[User] = None
+    channel_id: str = ""
+    edited: bool = False
+    created_at: Optional[datetime] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Message:
+        author = None
+        if "author" in data and data["author"]:
+            author = User.from_dict(data["author"])
+        return cls(
+            id=data["id"],
+            content=data["content"],
+            author=author,
+            channel_id=data.get("channelId", ""),
+            edited=data.get("edited", False),
+            created_at=_parse_dt(data.get("createdAt")),
+        )
+
+
+@dataclass
+class Bot:
+    id: str
+    name: str
+    description: Optional[str] = None
+    token: str = ""
+    secret: str = ""
+    public: bool = False
+    owner_id: str = ""
+    created_at: Optional[datetime] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Bot:
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            description=data.get("description"),
+            token=data.get("token", ""),
+            secret=data.get("secret", ""),
+            public=data.get("public", False),
+            owner_id=data.get("ownerId", ""),
+            created_at=_parse_dt(data.get("createdAt")),
+        )
+
+
+def _parse_dt(value: Optional[str]) -> Optional[datetime]:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except (ValueError, TypeError):
+        return None
+
+
+class ChannelProxy:
+    """Proxy that lets you do message.channel.send("content")."""
+
+    def __init__(self, channel_id: str, client: "Client"):
+        self.id = channel_id
+        self._client = client
+
+    async def send(self, content: str) -> "Message":
+        return await self._client.send(self.id, content)