riscord-bot 0.2.1__tar.gz

riscord_bot-0.2.1/LICENSE

@@ -0,0 +1,2 @@
+Riscord SDK
+All rights reserved.

riscord_bot-0.2.1/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+recursive-include examples *.py
+include src/riscord/py.typed

riscord_bot-0.2.1/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: riscord-bot
+Version: 0.2.1
+Summary: Official async Riscord bot client
+License: All rights reserved.
+Project-URL: Documentation, https://riscord.ir/developers/docs
+Project-URL: Homepage, https://riscord.ir
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-socketio[asyncio_client]<6,>=5.11
+Requires-Dist: aiohttp<4,>=3.10
+Dynamic: license-file
+
+# Riscord bot SDK — Python
+
+Requires Python 3.11 or newer. Install with `python -m pip install riscord-bot`. Versioned source archives remain available from [Developer Docs](https://riscord.ir/developers/docs); install a downloaded archive with `python -m pip install ./riscord-bot-python-0.2.1.tar.gz`.
+
+Create and install a bot through `https://riscord.ir/developers`, request View Channel and Send Messages, generate its token and set the `RISCORD_BOT_TOKEN` environment variable. Never commit the token.
+
+```python
+import asyncio, os
+from riscord import Client
+
+bot = Client(os.environ['RISCORD_BOT_TOKEN'])
+
+@bot.command('hello')
+async def hello(interaction):
+    await interaction.reply('Hello!', private=True)
+
+async def main():
+    await bot.register_commands([{'name':'hello','description':'Say hello','contexts':['server','dm']}])
+    try:
+        await bot.run()
+    finally:
+        await bot.close()
+
+asyncio.run(main())
+```
+
+Defer slow work with `await interaction.defer(private=True)` before replying; later replies retain that audience. `show_modal({customId,title,fields})` opens a form. Use `@bot.on('interaction')` for buttons, selects and submitted forms and inspect `interaction.kind` and `interaction.data`.
+
+`send(channel_id,content,components=...)`, `open_dm(user_id)`, `send_dm(conversation_id,content)`, `moderate(server_id,user_id,action,...)`, `history`, `edit` and `delete` expose the corresponding API operations. For message options, `client_id` is a Python keyword argument; component/command JSON follows the documented camelCase wire schema. IDs remain strings.
+
+Only registered text commands, mentions and the bot's DMs are delivered without broader Message Content permission. SDKs ignore automated messages, reconnect with bounded replay and honor retry delays. Deduplication is bounded and memory-only; persist operation IDs for external effects that must survive restarts.
+
+For voice playback, request View Channel, Connect and Speak when installing the bot, and allow them in the target server voice channel. Install a separate FFmpeg executable with the `libopus` encoder and SRTP support and add it to `PATH`; the SDK does not download an encoder. Chat and interactions do not need FFmpeg.
+
+```python
+await bot.connect()
+voice = await bot.join_voice('VOICE_CHANNEL_ID')
+try:
+    await voice.play('./music.ogg')
+    await voice.play('https://example.com/direct-audio.ogg')
+finally:
+    await voice.leave()
+```
+
+`join_voice(channel_id)` requires a connected bot gateway and returns a `VoiceConnection`. `play(source, ffmpeg='ffmpeg')` accepts a trusted local audio file or direct HTTP(S) audio URL and waits until playback finishes. A new `play` replaces the previous track; call it in an `asyncio` task if your handler must keep accepting other work. `stop()` ends playback while keeping the bot in the channel; `leave()` releases the connection. Cancelling the playback task also stops its encoder. `playing`, `closed`, `channel_id` and `server_id` expose connection state.
+
+Voice is send-only and self-deafened; the SDK never receives or records channel audio. Each playback gets fresh Opus/SRTP media parameters and stays within the server's audio bitrate limit. The SDK renews the lease every ten seconds and stops playback on a lost lease, gateway disconnect or `bot.close()`. Reconnecting the gateway does not rejoin voice automatically. One client owns one voice channel at a time, and stale playback cleanup cannot stop its replacement.
+
+Use sources you control. FFmpeg fetches URLs from the bot's machine, so do not pass arbitrary member-provided paths or URLs to `play`. Website pages that require a media extractor are not direct audio URLs. Encoder errors omit raw process output because it can contain private source URLs or transport keys. Set `RISCORD_VOICE_CHANNEL_ID` and `RISCORD_AUDIO_SOURCE` alongside the bot token, then run `examples/music.py` to play a configured source and leave when it finishes.
+
+The public [Developer Docs](https://riscord.ir/developers/docs) cover the API contract, limits and migration guidance.

riscord_bot-0.2.1/README.md

@@ -0,0 +1,51 @@
+# Riscord bot SDK — Python
+
+Requires Python 3.11 or newer. Install with `python -m pip install riscord-bot`. Versioned source archives remain available from [Developer Docs](https://riscord.ir/developers/docs); install a downloaded archive with `python -m pip install ./riscord-bot-python-0.2.1.tar.gz`.
+
+Create and install a bot through `https://riscord.ir/developers`, request View Channel and Send Messages, generate its token and set the `RISCORD_BOT_TOKEN` environment variable. Never commit the token.
+
+```python
+import asyncio, os
+from riscord import Client
+
+bot = Client(os.environ['RISCORD_BOT_TOKEN'])
+
+@bot.command('hello')
+async def hello(interaction):
+    await interaction.reply('Hello!', private=True)
+
+async def main():
+    await bot.register_commands([{'name':'hello','description':'Say hello','contexts':['server','dm']}])
+    try:
+        await bot.run()
+    finally:
+        await bot.close()
+
+asyncio.run(main())
+```
+
+Defer slow work with `await interaction.defer(private=True)` before replying; later replies retain that audience. `show_modal({customId,title,fields})` opens a form. Use `@bot.on('interaction')` for buttons, selects and submitted forms and inspect `interaction.kind` and `interaction.data`.
+
+`send(channel_id,content,components=...)`, `open_dm(user_id)`, `send_dm(conversation_id,content)`, `moderate(server_id,user_id,action,...)`, `history`, `edit` and `delete` expose the corresponding API operations. For message options, `client_id` is a Python keyword argument; component/command JSON follows the documented camelCase wire schema. IDs remain strings.
+
+Only registered text commands, mentions and the bot's DMs are delivered without broader Message Content permission. SDKs ignore automated messages, reconnect with bounded replay and honor retry delays. Deduplication is bounded and memory-only; persist operation IDs for external effects that must survive restarts.
+
+For voice playback, request View Channel, Connect and Speak when installing the bot, and allow them in the target server voice channel. Install a separate FFmpeg executable with the `libopus` encoder and SRTP support and add it to `PATH`; the SDK does not download an encoder. Chat and interactions do not need FFmpeg.
+
+```python
+await bot.connect()
+voice = await bot.join_voice('VOICE_CHANNEL_ID')
+try:
+    await voice.play('./music.ogg')
+    await voice.play('https://example.com/direct-audio.ogg')
+finally:
+    await voice.leave()
+```
+
+`join_voice(channel_id)` requires a connected bot gateway and returns a `VoiceConnection`. `play(source, ffmpeg='ffmpeg')` accepts a trusted local audio file or direct HTTP(S) audio URL and waits until playback finishes. A new `play` replaces the previous track; call it in an `asyncio` task if your handler must keep accepting other work. `stop()` ends playback while keeping the bot in the channel; `leave()` releases the connection. Cancelling the playback task also stops its encoder. `playing`, `closed`, `channel_id` and `server_id` expose connection state.
+
+Voice is send-only and self-deafened; the SDK never receives or records channel audio. Each playback gets fresh Opus/SRTP media parameters and stays within the server's audio bitrate limit. The SDK renews the lease every ten seconds and stops playback on a lost lease, gateway disconnect or `bot.close()`. Reconnecting the gateway does not rejoin voice automatically. One client owns one voice channel at a time, and stale playback cleanup cannot stop its replacement.
+
+Use sources you control. FFmpeg fetches URLs from the bot's machine, so do not pass arbitrary member-provided paths or URLs to `play`. Website pages that require a media extractor are not direct audio URLs. Encoder errors omit raw process output because it can contain private source URLs or transport keys. Set `RISCORD_VOICE_CHANNEL_ID` and `RISCORD_AUDIO_SOURCE` alongside the bot token, then run `examples/music.py` to play a configured source and leave when it finishes.
+
+The public [Developer Docs](https://riscord.ir/developers/docs) cover the API contract, limits and migration guidance.

riscord_bot-0.2.1/examples/controls.py

@@ -0,0 +1,25 @@
+import asyncio
+import os
+from riscord import Client
+
+bot = Client(os.environ["RISCORD_BOT_TOKEN"])
+
+@bot.command("feedback")
+async def feedback(i):
+    await i.reply("Got a suggestion?", client_id=f"feedback-{i.id}", components=[[{"type": "button", "label": "Write feedback", "customId": "feedback", "userId": i.user_id}]])
+
+@bot.on("interaction")
+async def controls(i):
+    if i.kind == "component" and i.data.get("customId") == "feedback":
+        await i.show_modal({"customId": "feedback-form", "title": "Your feedback", "fields": [{"name": "message", "label": "What could be better?", "type": "paragraph", "required": True, "maxLength": 1000}]})
+    elif i.kind == "form" and i.data.get("customId") == "feedback-form":
+        await i.reply("Thanks for sharing your feedback.", private=True, client_id=f"thanks-{i.id}")
+
+async def main():
+    await bot.register_commands([{"name": "feedback", "description": "Leave feedback", "contexts": ["server", "dm"]}])
+    try:
+        await bot.run()
+    finally:
+        await bot.close()
+
+asyncio.run(main())

riscord_bot-0.2.1/examples/hello.py

@@ -0,0 +1,18 @@
+import asyncio
+import os
+from riscord import Client
+
+client = Client(os.environ["RISCORD_BOT_TOKEN"])
+
+@client.command("hello")
+async def hello(interaction):
+    await interaction.reply("Hello! This reply is just for you.", private=True)
+
+async def main():
+    await client.register_commands([{"name": "hello", "description": "Say hello", "contexts": ["server", "dm"]}])
+    try:
+        await client.run()
+    finally:
+        await client.close()
+
+asyncio.run(main())

riscord_bot-0.2.1/examples/messages.py

@@ -0,0 +1,30 @@
+import asyncio
+import os
+from riscord import Client
+
+bot = Client(os.environ["RISCORD_BOT_TOKEN"])
+
+@bot.command("hello")
+async def hello(i):
+    await i.reply("Hello!", private=True)
+
+@bot.on("message.create")
+async def message(data):
+    if data.get("channelId") and (data.get("content") or "").strip() == "!hi":
+        await bot.send(data["channelId"], "Hello!", client_id=f"hello-{data['id']}")
+
+@bot.command("sendme")
+async def sendme(i):
+    await i.defer(private=True)
+    conversation = await bot.open_dm(i.user_id)
+    await bot.send_dm(conversation["id"], "You asked me to send this.", client_id=f"requested-{i.id}")
+    await i.reply("Sent. Check your direct messages.", client_id=f"sent-{i.id}")
+
+async def main():
+    await bot.register_commands([{"name": "hello", "description": "Say hello", "aliases": ["hi"]}, {"name": "sendme", "description": "Send me a direct message"}])
+    try:
+        await bot.run()
+    finally:
+        await bot.close()
+
+asyncio.run(main())

riscord_bot-0.2.1/examples/moderation.py

@@ -0,0 +1,20 @@
+import asyncio
+import os
+from riscord import Client
+
+bot = Client(os.environ["RISCORD_BOT_TOKEN"])
+
+@bot.command("quiet")
+async def quiet(i):
+    await i.defer(private=True)
+    await bot.moderate(i.server_id, i.data["values"]["member"], "timeout", durationMinutes=10)
+    await i.reply("The member has been timed out.", client_id=f"quiet-{i.id}")
+
+async def main():
+    await bot.register_commands([{"name": "quiet", "description": "Time out a lower member for ten minutes", "permissions": ["MODERATE_MEMBERS"], "options": [{"name": "member", "description": "Member to time out", "type": "user", "required": True}]}])
+    try:
+        await bot.run()
+    finally:
+        await bot.close()
+
+asyncio.run(main())

riscord_bot-0.2.1/examples/music.py

@@ -0,0 +1,23 @@
+import asyncio
+import os
+from riscord import Client
+
+bot = Client(os.environ["RISCORD_BOT_TOKEN"])
+# Keep the source and voice channel under your control; do not accept arbitrary paths or URLs from chat.
+channel_id = os.environ["RISCORD_VOICE_CHANNEL_ID"]
+source = os.environ["RISCORD_AUDIO_SOURCE"]
+
+
+async def main():
+    try:
+        await bot.connect()
+        voice = await bot.join_voice(channel_id)
+        try:
+            await voice.play(source)
+        finally:
+            await voice.leave()
+    finally:
+        await bot.close()
+
+
+asyncio.run(main())

riscord_bot-0.2.1/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "riscord-bot"
+version = "0.2.1"
+description = "Official async Riscord bot client"
+readme = "README.md"
+license = { text = "All rights reserved." }
+classifiers = ["License :: Other/Proprietary License", "Programming Language :: Python :: 3", "Framework :: AsyncIO"]
+requires-python = ">=3.11"
+dependencies = ["python-socketio[asyncio_client]>=5.11,<6", "aiohttp>=3.10,<4"]
+
+[project.urls]
+Documentation = "https://riscord.ir/developers/docs"
+Homepage = "https://riscord.ir"
+
+[tool.setuptools]
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+riscord = ["py.typed"]

riscord_bot-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

riscord_bot-0.2.1/src/riscord/__init__.py

@@ -0,0 +1,6 @@
+from .client import Client, Interaction, RiscordError
+from .voice import VoiceConnection
+
+from .models import Command, Option, Components, Modal, Message
+
+__all__ = ["Client", "Interaction", "RiscordError", "VoiceConnection", "Command", "Option", "Components", "Modal", "Message"]

riscord_bot-0.2.1/src/riscord/client.py

@@ -0,0 +1,279 @@
+import asyncio
+import inspect
+import random
+import uuid
+from collections import OrderedDict
+from typing import TYPE_CHECKING
+from urllib.parse import urlsplit
+from .models import Command, Modal
+
+if TYPE_CHECKING:
+    from .voice import VoiceConnection
+
+import aiohttp
+import socketio
+
+
+class RiscordError(Exception):
+    def __init__(self, message: str, status: int = 0):
+        super().__init__(message)
+        self.status = status
+
+
+class Interaction:
+    def __init__(self, client: "Client", data: dict):
+        self.client = client
+        self.id: str = data["id"]
+        self.kind: str = data["kind"]
+        self.user_id: str = data["userId"]
+        self.channel_id: str | None = data.get("channelId")
+        self.conversation_id: str | None = data.get("conversationId")
+        self.server_id: str | None = data.get("serverId")
+        self.data: dict = data["data"]
+        self._private = bool(data.get("private", False))
+        self._reply_index = 0
+
+    async def reply(self, content: str, *, private: bool | None = None, client_id: str | None = None, **options) -> dict:
+        audience = self._private if private is None else private
+        key = client_id or f"{self.id}-reply-{self._reply_index}"
+        self._reply_index += 1
+        result = await self.client.request(f"/interactions/{self.id}/respond", "POST", {"type": "message", "content": content, **options, "private": audience, "clientId": key})
+        self._private = audience
+        return result
+
+    async def defer(self, *, private: bool | None = None) -> dict:
+        audience = self._private if private is None else private
+        result = await self.client.request(f"/interactions/{self.id}/respond", "POST", {"type": "defer", "private": audience})
+        self._private = audience
+        return result
+
+    async def show_modal(self, modal: Modal) -> dict:
+        return await self.client.request(f"/interactions/{self.id}/respond", "POST", {"type": "modal", "modal": modal, "private": True})
+
+
+class Client:
+    def __init__(self, token: str, *, base_url: str = "https://riscord.ir", on_error=None):
+        if not token or not token.startswith("rb_"):
+            raise RiscordError("A valid bot token is required")
+        parts = urlsplit(base_url)
+        if parts.scheme not in ("http", "https") or not parts.netloc:
+            raise RiscordError("Invalid Riscord base URL")
+        self.base_url = f"{parts.scheme}://{parts.netloc}"
+        self._token = token
+        self.on_error = on_error or (lambda error: print(str(error)))
+        self.user_id = None
+        self._cursor = "0"
+        self._seen = OrderedDict()
+        self._handlers = {}
+        self._commands = {}
+        self._http = None
+        self._socket = socketio.AsyncClient(reconnection=True, reconnection_delay=1, reconnection_delay_max=30, randomization_factor=0.5)
+        self._lock = asyncio.Lock()
+        self._queued = set()
+        self._epoch = 0
+        self._closed = False
+        self._voice = None
+        self._voice_lock = asyncio.Lock()
+        self._voice_epoch = 0
+        self._socket.on("ready", self._ready, namespace="/bots")
+        self._socket.on("dispatch", self._dispatch, namespace="/bots")
+        self._socket.on("connect_error", self._connect_error, namespace="/bots")
+        self._socket.on("disconnect", self._disconnect, namespace="/bots")
+
+    def on(self, event: str):
+        def register(handler):
+            self._handlers.setdefault(event, []).append(handler)
+            return handler
+        return register
+
+    def command(self, name: str):
+        def register(handler):
+            self._commands[name] = handler
+            return handler
+        return register
+
+    async def _call(self, handler, data):
+        result = handler(data)
+        if inspect.isawaitable(result):
+            await result
+
+    async def _emit(self, event, data):
+        for handler in self._handlers.get(event, []):
+            await self._call(handler, data)
+
+    async def _connect_error(self, _data):
+        await self._call(self.on_error, RiscordError("Could not connect to the bot gateway"))
+
+    async def _disconnect(self, _reason=None):
+        self._voice_epoch += 1
+        voice = self._voice
+        if voice:
+            try:
+                await voice.leave()
+            except Exception:
+                await self._call(self.on_error, RiscordError("Voice connection closed after the gateway disconnected"))
+
+    async def _ready(self, data):
+        self.user_id = data["userId"]
+        if data.get("resyncRequired"):
+            self._cursor = "0"
+        await self._emit("ready", data)
+
+    async def _dispatch(self, envelope):
+        event_id = envelope.get("id")
+        if not isinstance(event_id, str) or event_id in self._queued or len(self._queued) >= 100:
+            return
+        self._queued.add(event_id)
+        epoch = self._epoch
+        try:
+            async with self._lock:
+                if epoch != self._epoch:
+                    return
+                if event_id not in self._seen:
+                    event, data = envelope["event"], envelope["data"]
+                    if event == "interaction.create":
+                        interaction = Interaction(self, data)
+                        handler = self._commands.get(interaction.data.get("name")) if interaction.kind == "command" else None
+                        if handler:
+                            await self._call(handler, interaction)
+                        await self._emit("interaction", interaction)
+                    elif event != "checkpoint":
+                        automated = data.get("senderKind") in ("bot", "webhook") or data.get("authorId") == self.user_id or data.get("senderId") == self.user_id
+                        if event != "message.create" or not automated:
+                            await self._emit(event, data)
+                    self._seen[event_id] = None
+                    if len(self._seen) > 5000:
+                        self._seen.popitem(last=False)
+                self._cursor = event_id
+                await self._socket.emit("ack", {"id": event_id}, namespace="/bots")
+        except Exception as error:
+            if epoch == self._epoch:
+                await self._call(self.on_error, error)
+                self._seen[event_id] = None
+                if len(self._seen) > 5000:
+                    self._seen.popitem(last=False)
+                self._cursor = event_id
+                if self._socket.connected:
+                    await self._socket.emit("ack", {"id": event_id, "failed": True}, namespace="/bots")
+        finally:
+            self._queued.discard(event_id)
+
+    async def request(self, path: str, method: str = "GET", body=None):
+        if not path.startswith("/") or "://" in path:
+            raise RiscordError("Invalid API path")
+        if self._http is None or self._http.closed:
+            self._http = aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=20))
+        retryable = method in ("GET", "PUT") or isinstance(body, dict) and bool(body.get("clientId"))
+        for attempt in range(4):
+            try:
+                async with self._http.request(method, self.base_url + "/api/bot/v1" + path, **({"data": body} if isinstance(body, aiohttp.FormData) else {"json": body}), headers={"Authorization": "Bot " + self._token}, allow_redirects=False) as response:
+                    if response.status in (429, 503) and retryable and attempt < 3:
+                        try:
+                            delay = float(response.headers.get("Retry-After", "1"))
+                        except ValueError:
+                            delay = 1
+                        await asyncio.sleep(min(60, max(1, delay)))
+                        continue
+                    try:
+                        data = await response.json()
+                    except (aiohttp.ContentTypeError, ValueError):
+                        raise RiscordError(f"Riscord returned {response.status}", response.status) from None
+                    if response.status >= 300:
+                        raise RiscordError(data.get("error", f"Riscord returned {response.status}"), response.status)
+                    return data
+            except (aiohttp.ClientError, asyncio.TimeoutError):
+                if retryable and attempt < 3:
+                    await asyncio.sleep(0.5 * 2 ** attempt)
+                    continue
+                raise RiscordError("Could not reach Riscord") from None
+
+    async def me(self):
+        return await self.request("/me")
+
+    async def channels(self, server_id: str):
+        return await self.request(f"/servers/{server_id}/channels")
+
+    async def members(self, server_id: str, cursor: str | None = None):
+        suffix = f"?cursor={cursor}" if cursor else ""
+        return await self.request(f"/servers/{server_id}/members{suffix}")
+
+    async def set_role(self, server_id: str, user_id: str, role_id: str, add: bool = True):
+        return await self.request(f"/servers/{server_id}/members/{user_id}/roles", "POST", {"roleId": role_id, "add": add})
+
+    async def upload(self, data: bytes, filename: str, content_type: str):
+        form = aiohttp.FormData()
+        form.add_field("file", data, filename=filename, content_type=content_type)
+        return await self.request("/upload", "POST", form)
+
+    async def register_commands(self, commands: list[Command]):
+        return await self.request("/commands", "PUT", commands)
+
+    async def send(self, channel_id: str, content: str, *, client_id: str | None = None, **options):
+        return await self.request(f"/channels/{channel_id}/messages", "POST", {"content": content, **options, "clientId": client_id or str(uuid.uuid4())})
+
+    async def edit(self, channel_id: str, message_id: str, content: str, components=None):
+        return await self.request(f"/channels/{channel_id}/messages/{message_id}", "PATCH", {"content": content, "components": components or []})
+
+    async def delete(self, channel_id: str, message_id: str):
+        return await self.request(f"/channels/{channel_id}/messages/{message_id}", "DELETE")
+
+    async def history(self, channel_id: str):
+        return await self.request(f"/channels/{channel_id}/messages")
+
+    async def open_dm(self, user_id: str):
+        return await self.request("/conversations", "POST", {"userId": user_id})
+
+    async def send_dm(self, conversation_id: str, content: str, *, client_id: str | None = None, **options):
+        return await self.request(f"/conversations/{conversation_id}/messages", "POST", {"content": content, **options, "clientId": client_id or str(uuid.uuid4())})
+
+    async def moderate(self, server_id: str, user_id: str, action: str, **options):
+        return await self.request(f"/servers/{server_id}/members/{user_id}/{action}", "POST", options)
+
+    async def join_voice(self, channel_id: str) -> "VoiceConnection":
+        from .voice import VoiceConnection, _identifier
+
+        if not isinstance(channel_id, str) or not channel_id.isascii() or not channel_id.isdecimal():
+            raise RiscordError("Voice channel ID must be a string of digits")
+        async with self._voice_lock:
+            if self._closed or not self._socket.connected:
+                raise RiscordError("Connect to the bot gateway before joining voice")
+            epoch = self._voice_epoch
+            if self._voice:
+                await self._voice.leave()
+            data = await self.request("/voice/join", "POST", {"channelId": channel_id})
+            try:
+                if self._closed or not self._socket.connected or epoch != self._voice_epoch:
+                    raise RiscordError("Bot gateway disconnected while joining voice")
+                voice = VoiceConnection(self, data)
+            except BaseException:
+                if isinstance(data, dict) and _identifier(data.get("connectionId")):
+                    try:
+                        await self.request("/voice/leave", "POST", {"connectionId": data["connectionId"]})
+                    except Exception:
+                        pass
+                raise
+            self._voice = voice
+            return voice
+
+    async def connect(self):
+        self._closed = False
+        if not self._socket.connected:
+            await self._socket.connect(self.base_url, auth=lambda: {"token": self._token, "cursor": self._cursor}, namespaces=["/bots"])
+
+    async def run(self):
+        await self.connect()
+        await self._socket.wait()
+
+    async def close(self):
+        self._closed = True
+        self._epoch += 1
+        self._voice_epoch += 1
+        try:
+            if self._voice:
+                await self._voice.leave()
+        finally:
+            try:
+                await self._socket.disconnect()
+            finally:
+                if self._http:
+                    await self._http.close()

riscord_bot-0.2.1/src/riscord/models.py

@@ -0,0 +1,68 @@
+from typing import Literal, NotRequired, TypedDict
+
+ID = str
+Permission = Literal["VIEW_CHANNEL", "SEND_MESSAGES", "EMBED_LINKS", "ATTACH_FILES", "ADD_REACTIONS", "MANAGE_MESSAGES", "KICK_MEMBERS", "BAN_MEMBERS", "MODERATE_MEMBERS", "MANAGE_ROLES", "MESSAGE_CONTENT", "SEND_DIRECT_MESSAGES", "CONNECT", "SPEAK"]
+
+class Option(TypedDict):
+    name: str
+    description: str
+    type: Literal["string", "integer", "boolean", "user", "channel"]
+    required: NotRequired[bool]
+
+class Command(TypedDict):
+    name: str
+    description: str
+    options: NotRequired[list[Option]]
+    contexts: NotRequired[list[Literal["server", "dm"]]]
+    permissions: NotRequired[list[Permission]]
+    aliases: NotRequired[list[str]]
+    serverId: NotRequired[ID]
+
+class Button(TypedDict):
+    type: Literal["button"]
+    customId: str
+    label: str
+    disabled: NotRequired[bool]
+    userId: NotRequired[ID]
+
+class LinkButton(TypedDict):
+    type: Literal["link"]
+    label: str
+    url: str
+
+class SelectOption(TypedDict):
+    label: str
+    value: str
+
+class Select(TypedDict):
+    type: Literal["select"]
+    customId: str
+    label: str
+    options: list[SelectOption]
+    disabled: NotRequired[bool]
+    userId: NotRequired[ID]
+
+Components = list[list[Button | LinkButton | Select]]
+
+class FormField(TypedDict):
+    name: str
+    label: str
+    type: Literal["text", "paragraph"]
+    required: NotRequired[bool]
+    minLength: NotRequired[int]
+    maxLength: NotRequired[int]
+
+class Modal(TypedDict):
+    customId: str
+    title: str
+    fields: list[FormField]
+
+class Message(TypedDict, total=False):
+    id: ID
+    channelId: ID
+    conversationId: ID
+    senderId: ID
+    authorId: ID
+    content: str | None
+    senderKind: Literal["user", "bot", "webhook"]
+    components: Components

riscord_bot-0.2.1/src/riscord/voice.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import binascii
+import ipaddress
+import os
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+from .client import RiscordError
+
+
+def _identifier(value) -> bool:
+    return isinstance(value, str) and 0 < len(value) <= 128
+
+
+def _source(source: str | os.PathLike) -> str:
+    try:
+        source = os.fspath(source)
+    except TypeError:
+        raise RiscordError("Audio source must be a local file or an HTTP(S) URL") from None
+    if not isinstance(source, str) or not source or len(source) > 8192 or any(ord(c) < 32 for c in source):
+        raise RiscordError("Audio source must be a local file or an HTTP(S) URL")
+    try:
+        parts = urlsplit(source)
+        if parts.scheme in ("http", "https"):
+            if not parts.hostname:
+                raise ValueError
+            return source
+    except ValueError:
+        raise RiscordError("Invalid audio URL") from None
+    if not os.path.isfile(source):
+        raise RiscordError("Audio source must be a local file or an HTTP(S) URL")
+    return os.path.abspath(source)
+
+
+def _ffmpeg_arguments(source: str, media: dict) -> list[str]:
+    try:
+        address = ipaddress.ip_address(media["ip"])
+        port, ssrc, bitrate = media["port"], media["ssrc"], media["audioBitrate"]
+        if type(port) is not int or not 1 <= port <= 65535 or type(ssrc) is not int or not 1 <= ssrc <= 0x7fffffff:
+            raise ValueError
+        if media["payloadType"] != 111 or media["clockRate"] != 48000 or media["channels"] != 2:
+            raise ValueError
+        if type(bitrate) is not int or not 6000 <= bitrate <= 510000:
+            raise ValueError
+        if media["srtpSuite"] != "AES_CM_128_HMAC_SHA1_80" or not isinstance(media["srtpKeyBase64"], str) or len(media["srtpKeyBase64"]) != 40 or len(base64.b64decode(media["srtpKeyBase64"], validate=True)) != 30:
+            raise ValueError
+    except (KeyError, TypeError, ValueError, binascii.Error):
+        raise RiscordError("Riscord returned invalid voice media parameters") from None
+    host = f"[{address}]" if address.version == 6 else str(address)
+    return [
+        "-nostdin", "-hide_banner", "-loglevel", "error", "-re",
+        "-protocol_whitelist", "http,https,tcp,tls,crypto" if urlsplit(source).scheme in ("http", "https") else "file",
+        "-i", source,
+        "-map", "0:a:0", "-vn", "-c:a", "libopus", "-ar", "48000", "-ac", "2",
+        "-b:a", str(min(96000, bitrate)), "-application", "audio", "-frame_duration", "20",
+        "-f", "rtp", "-payload_type", "111", "-ssrc", str(ssrc), "-rtpflags", "skip_rtcp",
+        "-srtp_out_suite", media["srtpSuite"], "-srtp_out_params", media["srtpKeyBase64"],
+        f"srtp://{host}:{port}?rtcpport={port}&pkt_size=1200",
+    ]
+
+
+async def _terminate(process):
+    if process.returncode is not None:
+        return
+    try:
+        process.terminate()
+    except ProcessLookupError:
+        pass
+    try:
+        await asyncio.wait_for(process.wait(), 3)
+    except asyncio.TimeoutError:
+        try:
+            process.kill()
+        except ProcessLookupError:
+            pass
+        try:
+            await asyncio.wait_for(process.wait(), 3)
+        except asyncio.TimeoutError:
+            raise RiscordError("FFmpeg did not exit after being killed") from None
+
+
+@dataclass(repr=False)
+class _Playback:
+    process: asyncio.subprocess.Process
+    media_id: str
+    stopped: bool = False
+
+
+class VoiceConnection:
+    """A send-only, self-deafened server voice connection owned by this gateway."""
+
+    def __init__(self, client, data: dict):
+        if not isinstance(data, dict) or not all(_identifier(data.get(key)) for key in ("connectionId", "channelId", "serverId")):
+            raise RiscordError("Riscord returned an invalid voice connection")
+        interval, timeout = data.get("heartbeatIntervalMs"), data.get("leaseTimeoutMs")
+        if type(interval) is not int or type(timeout) is not int or not 1000 <= interval <= 10000 or timeout < interval * 2:
+            raise RiscordError("Riscord returned an invalid voice lease")
+        self.connection_id: str = data["connectionId"]
+        self.channel_id: str = data["channelId"]
+        self.server_id: str = data["serverId"]
+        self._client = client
+        self._closed = False
+        self._playback = None
+        self._media_lock = asyncio.Lock()
+        self._leave_lock = asyncio.Lock()
+        self._heartbeat_task = asyncio.create_task(self._heartbeat(interval / 1000))
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    @property
+    def playing(self) -> bool:
+        return self._playback is not None and self._playback.process.returncode is None
+
+    async def _heartbeat(self, interval):
+        try:
+            while not self._closed:
+                await asyncio.sleep(interval)
+                await self._client.request("/voice/heartbeat", "POST", {"connectionId": self.connection_id})
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            try:
+                await self.leave()
+            except Exception:
+                pass
+            await self._client._call(self._client.on_error, RiscordError("Voice connection lost; join the channel again"))
+
+    async def _release_media(self, media_id):
+        await self._client.request("/voice/media/stop", "POST", {"connectionId": self.connection_id, "mediaId": media_id})
+
+    async def _stop_locked(self):
+        playback = self._playback
+        if playback is not None:
+            self._playback = None
+            playback.stopped = True
+            try:
+                await _terminate(playback.process)
+            finally:
+                await self._release_media(playback.media_id)
+
+    async def stop(self):
+        """Stop playback and its producer, keeping the channel connection alive."""
+        async with self._media_lock:
+            await self._stop_locked()
+
+    async def play(self, source: str | os.PathLike, *, ffmpeg: str = "ffmpeg"):
+        """Play a local file or HTTP(S) URL until completion, replacement or stop."""
+        source = _source(source)
+        if not isinstance(ffmpeg, str) or not ffmpeg or any(ord(c) < 32 for c in ffmpeg):
+            raise RiscordError("Invalid FFmpeg executable")
+        async with self._media_lock:
+            if self._closed:
+                raise RiscordError("Voice connection is closed; join the channel again")
+            await self._stop_locked()
+            prepare = asyncio.create_task(self._client.request("/voice/media", "POST", {"connectionId": self.connection_id}))
+            try:
+                media = await asyncio.shield(prepare)
+            except asyncio.CancelledError:
+                try:
+                    media = await prepare
+                    if isinstance(media, dict) and _identifier(media.get("mediaId")):
+                        await self._release_media(media["mediaId"])
+                except Exception:
+                    pass
+                raise
+            media_id = media.get("mediaId") if isinstance(media, dict) else None
+            if not _identifier(media_id):
+                raise RiscordError("Riscord returned an invalid voice media ID")
+            try:
+                if self._closed:
+                    raise RiscordError("Voice connection is closed; join the channel again")
+                arguments = _ffmpeg_arguments(source, media)
+                # Keep encoder output private: FFmpeg errors can include source URLs and SRTP keys.
+                environment = {key: value for key, value in os.environ.items() if key.upper() != "FFREPORT"}
+                spawn = asyncio.create_task(asyncio.create_subprocess_exec(ffmpeg, *arguments, env=environment, stdin=asyncio.subprocess.DEVNULL, stdout=asyncio.subprocess.DEVNULL, stderr=asyncio.subprocess.DEVNULL))
+                try:
+                    process = await asyncio.shield(spawn)
+                except asyncio.CancelledError:
+                    process = await spawn
+                    await _terminate(process)
+                    raise
+                if self._closed:
+                    await _terminate(process)
+                    raise RiscordError("Voice connection is closed; join the channel again")
+                self._playback = playback = _Playback(process, media_id)
+            except BaseException as error:
+                try:
+                    await self._release_media(media_id)
+                except Exception:
+                    pass
+                if isinstance(error, FileNotFoundError):
+                    raise RiscordError("FFmpeg was not found. Install FFmpeg with libopus and add it to PATH, or pass ffmpeg= to play()") from None
+                if isinstance(error, OSError):
+                    raise RiscordError("Could not start FFmpeg") from None
+                raise
+        try:
+            result = await process.wait()
+        except asyncio.CancelledError:
+            async with self._media_lock:
+                if self._playback is playback:
+                    await self._stop_locked()
+            raise
+        async with self._media_lock:
+            if self._playback is playback:
+                self._playback = None
+                await self._release_media(media_id)
+        if result and not playback.stopped:
+            raise RiscordError("FFmpeg could not play this audio. Check the source and FFmpeg's libopus/SRTP support")
+
+    async def leave(self):
+        """Release playback, heartbeat and this connection's server voice lease."""
+        async with self._leave_lock:
+            if self._closed:
+                return
+            self._closed = True
+            try:
+                if self._heartbeat_task is not asyncio.current_task():
+                    self._heartbeat_task.cancel()
+                    try:
+                        await self._heartbeat_task
+                    except asyncio.CancelledError:
+                        pass
+                try:
+                    await self.stop()
+                finally:
+                    await self._client.request("/voice/leave", "POST", {"connectionId": self.connection_id})
+            finally:
+                if self._client._voice is self:
+                    self._client._voice = None

riscord_bot-0.2.1/src/riscord_bot.egg-info/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: riscord-bot
+Version: 0.2.1
+Summary: Official async Riscord bot client
+License: All rights reserved.
+Project-URL: Documentation, https://riscord.ir/developers/docs
+Project-URL: Homepage, https://riscord.ir
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-socketio[asyncio_client]<6,>=5.11
+Requires-Dist: aiohttp<4,>=3.10
+Dynamic: license-file
+
+# Riscord bot SDK — Python
+
+Requires Python 3.11 or newer. Install with `python -m pip install riscord-bot`. Versioned source archives remain available from [Developer Docs](https://riscord.ir/developers/docs); install a downloaded archive with `python -m pip install ./riscord-bot-python-0.2.1.tar.gz`.
+
+Create and install a bot through `https://riscord.ir/developers`, request View Channel and Send Messages, generate its token and set the `RISCORD_BOT_TOKEN` environment variable. Never commit the token.
+
+```python
+import asyncio, os
+from riscord import Client
+
+bot = Client(os.environ['RISCORD_BOT_TOKEN'])
+
+@bot.command('hello')
+async def hello(interaction):
+    await interaction.reply('Hello!', private=True)
+
+async def main():
+    await bot.register_commands([{'name':'hello','description':'Say hello','contexts':['server','dm']}])
+    try:
+        await bot.run()
+    finally:
+        await bot.close()
+
+asyncio.run(main())
+```
+
+Defer slow work with `await interaction.defer(private=True)` before replying; later replies retain that audience. `show_modal({customId,title,fields})` opens a form. Use `@bot.on('interaction')` for buttons, selects and submitted forms and inspect `interaction.kind` and `interaction.data`.
+
+`send(channel_id,content,components=...)`, `open_dm(user_id)`, `send_dm(conversation_id,content)`, `moderate(server_id,user_id,action,...)`, `history`, `edit` and `delete` expose the corresponding API operations. For message options, `client_id` is a Python keyword argument; component/command JSON follows the documented camelCase wire schema. IDs remain strings.
+
+Only registered text commands, mentions and the bot's DMs are delivered without broader Message Content permission. SDKs ignore automated messages, reconnect with bounded replay and honor retry delays. Deduplication is bounded and memory-only; persist operation IDs for external effects that must survive restarts.
+
+For voice playback, request View Channel, Connect and Speak when installing the bot, and allow them in the target server voice channel. Install a separate FFmpeg executable with the `libopus` encoder and SRTP support and add it to `PATH`; the SDK does not download an encoder. Chat and interactions do not need FFmpeg.
+
+```python
+await bot.connect()
+voice = await bot.join_voice('VOICE_CHANNEL_ID')
+try:
+    await voice.play('./music.ogg')
+    await voice.play('https://example.com/direct-audio.ogg')
+finally:
+    await voice.leave()
+```
+
+`join_voice(channel_id)` requires a connected bot gateway and returns a `VoiceConnection`. `play(source, ffmpeg='ffmpeg')` accepts a trusted local audio file or direct HTTP(S) audio URL and waits until playback finishes. A new `play` replaces the previous track; call it in an `asyncio` task if your handler must keep accepting other work. `stop()` ends playback while keeping the bot in the channel; `leave()` releases the connection. Cancelling the playback task also stops its encoder. `playing`, `closed`, `channel_id` and `server_id` expose connection state.
+
+Voice is send-only and self-deafened; the SDK never receives or records channel audio. Each playback gets fresh Opus/SRTP media parameters and stays within the server's audio bitrate limit. The SDK renews the lease every ten seconds and stops playback on a lost lease, gateway disconnect or `bot.close()`. Reconnecting the gateway does not rejoin voice automatically. One client owns one voice channel at a time, and stale playback cleanup cannot stop its replacement.
+
+Use sources you control. FFmpeg fetches URLs from the bot's machine, so do not pass arbitrary member-provided paths or URLs to `play`. Website pages that require a media extractor are not direct audio URLs. Encoder errors omit raw process output because it can contain private source URLs or transport keys. Set `RISCORD_VOICE_CHANNEL_ID` and `RISCORD_AUDIO_SOURCE` alongside the bot token, then run `examples/music.py` to play a configured source and leave when it finishes.
+
+The public [Developer Docs](https://riscord.ir/developers/docs) cover the API contract, limits and migration guidance.

riscord_bot-0.2.1/src/riscord_bot.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+examples/controls.py
+examples/hello.py
+examples/messages.py
+examples/moderation.py
+examples/music.py
+src/riscord/__init__.py
+src/riscord/client.py
+src/riscord/models.py
+src/riscord/py.typed
+src/riscord/voice.py
+src/riscord_bot.egg-info/PKG-INFO
+src/riscord_bot.egg-info/SOURCES.txt
+src/riscord_bot.egg-info/dependency_links.txt
+src/riscord_bot.egg-info/requires.txt
+src/riscord_bot.egg-info/top_level.txt

riscord_bot-0.2.1/src/riscord_bot.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

riscord_bot-0.2.1/src/riscord_bot.egg-info/requires.txt

@@ -0,0 +1,2 @@
+python-socketio[asyncio_client]<6,>=5.11
+aiohttp<4,>=3.10

riscord_bot-0.2.1/src/riscord_bot.egg-info/top_level.txt

@@ -0,0 +1 @@
+riscord