voiceroute.py 0.1.0.dev0__py3-none-any.whl

voiceroute/__init__.py

@@ -0,0 +1,149 @@
+"""Async Python SDK and bot framework for VoiceRoute."""
+
+from voiceroute.bot import Bot
+from voiceroute.client import VoiceRouteClient
+from voiceroute.commands import (
+    BucketType,
+    Check,
+    Command,
+    CommandInvocation,
+    CommandParameter,
+    CommandPipeline,
+    CommandRegistry,
+    ConcurrencyLimit,
+    Context,
+    Cooldown,
+    Middleware,
+    NextMiddleware,
+    PrefixCommandAdapter,
+    check,
+    cooldown,
+    max_concurrency,
+)
+from voiceroute.errors import (
+    BadArgument,
+    BadRequest,
+    BotAlreadyRunning,
+    BotClosed,
+    CheckFailure,
+    CommandError,
+    CommandNotFound,
+    CommandOnCooldown,
+    CommandParsingError,
+    Conflict,
+    CursorStoreError,
+    ExtensionAlreadyLoaded,
+    ExtensionError,
+    ExtensionNotLoaded,
+    ExtensionSetupError,
+    Forbidden,
+    HTTPError,
+    MaxConcurrencyReached,
+    MissingRequiredArgument,
+    NoChannelsAvailable,
+    NotFound,
+    RateLimited,
+    ServiceUnavailable,
+    SSEError,
+    TooManyArguments,
+    Unauthorized,
+    UnsupportedCommandParameter,
+    ValidationError,
+    VoiceRouteError,
+)
+from voiceroute.events import (
+    AccessLost,
+    BotEvent,
+    CursorStore,
+    EventDelivery,
+    EventSource,
+    EventTransport,
+    FileCursorStore,
+    LegacySSETransport,
+    MemoryCursorStore,
+    MessageUpserted,
+    RedisCursorStore,
+    SQLiteCursorStore,
+    StreamCheckpoint,
+)
+from voiceroute.extensions import Extension, ExtensionCommand, command, listener
+from voiceroute.models import BotIdentity, Channel, Community, Message, MessagePage, User
+from voiceroute.runtime import RuntimeState
+from voiceroute.transport import RateLimiter
+
+__all__ = [
+    "AccessLost",
+    "BadArgument",
+    "BadRequest",
+    "Bot",
+    "BotAlreadyRunning",
+    "BotClosed",
+    "BotEvent",
+    "BotIdentity",
+    "BucketType",
+    "Channel",
+    "Check",
+    "CheckFailure",
+    "Command",
+    "CommandError",
+    "CommandInvocation",
+    "CommandNotFound",
+    "CommandOnCooldown",
+    "CommandParameter",
+    "CommandParsingError",
+    "CommandPipeline",
+    "CommandRegistry",
+    "Community",
+    "ConcurrencyLimit",
+    "Conflict",
+    "Context",
+    "Cooldown",
+    "CursorStore",
+    "CursorStoreError",
+    "EventDelivery",
+    "EventSource",
+    "EventTransport",
+    "Extension",
+    "ExtensionAlreadyLoaded",
+    "ExtensionCommand",
+    "ExtensionError",
+    "ExtensionNotLoaded",
+    "ExtensionSetupError",
+    "FileCursorStore",
+    "Forbidden",
+    "HTTPError",
+    "LegacySSETransport",
+    "MaxConcurrencyReached",
+    "MemoryCursorStore",
+    "Message",
+    "MessagePage",
+    "MessageUpserted",
+    "Middleware",
+    "MissingRequiredArgument",
+    "NextMiddleware",
+    "NoChannelsAvailable",
+    "NotFound",
+    "PrefixCommandAdapter",
+    "RateLimited",
+    "RateLimiter",
+    "RedisCursorStore",
+    "RuntimeState",
+    "SQLiteCursorStore",
+    "SSEError",
+    "ServiceUnavailable",
+    "StreamCheckpoint",
+    "TooManyArguments",
+    "Unauthorized",
+    "UnsupportedCommandParameter",
+    "User",
+    "ValidationError",
+    "VoiceRouteClient",
+    "VoiceRouteError",
+    "check",
+    "command",
+    "cooldown",
+    "listener",
+    "max_concurrency",
+]
+
+__version__ = "0.1.0.dev0"

voiceroute/api/__init__.py

@@ -0,0 +1,8 @@
+"""Domain-specific VoiceRoute API clients."""
+
+from voiceroute.api.bots import BotsAPI
+from voiceroute.api.communities import CommunitiesAPI
+from voiceroute.api.events import EventsAPI
+from voiceroute.api.messages import MessagesAPI
+
+__all__ = ["BotsAPI", "CommunitiesAPI", "EventsAPI", "MessagesAPI"]

voiceroute/api/bots.py

@@ -0,0 +1,40 @@
+"""Bot profile endpoints."""
+
+from voiceroute.models import BotIdentity, User
+from voiceroute.transport import HTTPTransport
+
+
+class BotsAPI:
+    """Operations for the currently authenticated bot."""
+
+    def __init__(self, transport: HTTPTransport) -> None:
+        self._transport = transport
+
+    async def get_current(self) -> BotIdentity:
+        payload = await self._transport.request("GET", "/api/bots/@me")
+        if payload is None:
+            raise RuntimeError("VoiceRoute returned no bot identity")
+        return BotIdentity.from_dict(payload)
+
+    async def update_current(
+        self,
+        *,
+        display_name: str | None = None,
+        bio: str | None = None,
+        custom_status: str | None = None,
+        accent_color: str | None = None,
+    ) -> User:
+        data = {
+            key: value
+            for key, value in {
+                "displayName": display_name,
+                "bio": bio,
+                "customStatus": custom_status,
+                "accentColor": accent_color,
+            }.items()
+            if value is not None
+        }
+        payload = await self._transport.request("PATCH", "/api/bots/@me", json=data)
+        if payload is None:
+            raise RuntimeError("VoiceRoute returned no updated bot profile")
+        return User.from_dict(payload["user"])

voiceroute/api/communities.py

@@ -0,0 +1,36 @@
+"""Community and channel endpoints available to bots."""
+
+from __future__ import annotations
+
+import builtins
+
+from voiceroute.models import Channel, Community
+from voiceroute.transport import HTTPTransport
+
+
+class CommunitiesAPI:
+    """Read communities and their bot-visible channels."""
+
+    def __init__(self, transport: HTTPTransport) -> None:
+        self._transport = transport
+
+    async def list(self) -> list[Community]:
+        payload = await self._transport.request("GET", "/api/communities")
+        if payload is None:
+            return []
+        return [Community.from_dict(item) for item in payload.get("items", [])]
+
+    async def get(self, community_id: str) -> Community:
+        payload = await self._transport.request("GET", f"/api/communities/{community_id}")
+        if payload is None:
+            raise RuntimeError("VoiceRoute returned no community")
+        data = payload.get("community", payload)
+        return Community.from_dict(data)
+
+    async def list_channels(self, community_id: str) -> builtins.list[Channel]:
+        payload = await self._transport.request("GET", f"/api/communities/{community_id}/channels")
+        if payload is None:
+            return []
+        return [
+            Channel.from_dict(item, community_id=community_id) for item in payload.get("items", [])
+        ]

voiceroute/api/events.py

@@ -0,0 +1,86 @@
+"""Resumable bot event streams."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator
+
+from voiceroute.errors import RateLimited, ServiceUnavailable, SSEError, TransportError
+from voiceroute.events.models import AccessLost, BotEvent, MessageUpserted
+from voiceroute.events.sse import SSEDecoder
+from voiceroute.models import Message
+from voiceroute.transport import HTTPTransport
+
+
+class EventsAPI:
+    """Consume authenticated channel message events with cursor recovery."""
+
+    def __init__(self, transport: HTTPTransport) -> None:
+        self._transport = transport
+
+    async def listen_messages(
+        self,
+        community_id: str,
+        channel_id: str,
+        *,
+        after_seq: str | None = None,
+        cursor: str | None = None,
+        reconnect: bool = True,
+        max_backoff: float = 30.0,
+    ) -> AsyncIterator[BotEvent]:
+        if max_backoff <= 0:
+            raise ValueError("max_backoff must be positive")
+
+        last_cursor = cursor
+        backoff = 1.0
+        path = f"/api/communities/{community_id}/channels/{channel_id}/events"
+
+        while True:
+            params = {
+                "after": after_seq if last_cursor is None else None,
+                "changeCursor": last_cursor,
+            }
+            headers = {"Last-Event-ID": last_cursor} if last_cursor is not None else None
+            decoder = SSEDecoder()
+
+            retry_delay: float | None = None
+            try:
+                async with self._transport.stream(path, params=params, headers=headers) as response:
+                    async for line in response.aiter_lines():
+                        frame = decoder.feed_line(line)
+                        if frame is None:
+                            continue
+                        if frame.id is not None:
+                            last_cursor = frame.id
+                        backoff = 1.0
+
+                        event = self._decode(frame.event, frame.data, last_cursor)
+                        yield event
+                        if isinstance(event, AccessLost):
+                            return
+            except RateLimited as exc:
+                retry_delay = exc.retry_after
+            except (ServiceUnavailable, TransportError):
+                pass
+
+            if not reconnect:
+                return
+            await asyncio.sleep(retry_delay if retry_delay is not None else backoff)
+            backoff = min(backoff * 2, max_backoff)
+
+    @staticmethod
+    def _decode(event_name: str, data: str, cursor: str | None) -> BotEvent:
+        try:
+            payload = json.loads(data)
+        except json.JSONDecodeError as exc:
+            raise SSEError("VoiceRoute SSE event contains invalid JSON") from exc
+
+        if event_name == "message":
+            if not isinstance(payload, dict):
+                raise SSEError("VoiceRoute message event must contain a JSON object")
+            return MessageUpserted(Message.from_dict(payload), cursor)
+        if event_name == "access-lost":
+            reason = payload.get("reason") if isinstance(payload, dict) else None
+            return AccessLost(cursor=cursor, reason=str(reason) if reason is not None else None)
+        raise SSEError(f"unsupported VoiceRoute SSE event: {event_name}")

voiceroute/api/messages.py

@@ -0,0 +1,215 @@
+"""Community text message endpoints."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Sequence
+
+from voiceroute.models import Message, MessagePage
+from voiceroute.transport import HTTPTransport
+
+
+class MessagesAPI:
+    """Read and send messages in bot-visible text channels."""
+
+    def __init__(self, transport: HTTPTransport) -> None:
+        self._transport = transport
+
+    async def history(
+        self,
+        community_id: str,
+        channel_id: str,
+        *,
+        limit: int = 50,
+        before_seq: str | None = None,
+        after_seq: str | None = None,
+    ) -> MessagePage:
+        _validate_limit(limit)
+        if before_seq is not None and after_seq is not None:
+            raise ValueError("before_seq and after_seq cannot be used together")
+
+        params: dict[str, str | int | None] = {
+            "limit": limit,
+            "beforeSeq": before_seq,
+            "afterSeq": after_seq,
+        }
+        payload = await self._transport.request(
+            "GET",
+            self._messages_path(community_id, channel_id),
+            params=params,
+        )
+        if payload is None:
+            return MessagePage(())
+        return _message_page(payload)
+
+    async def send(
+        self,
+        community_id: str,
+        channel_id: str,
+        body: str = "",
+        *,
+        reply_to_seq: str | None = None,
+        attachment_ids: Sequence[str] = (),
+        sticker_ids: Sequence[str] = (),
+        client_message_id: str | uuid.UUID | None = None,
+    ) -> Message:
+        if len(body) > 4000:
+            raise ValueError("message body cannot exceed 4000 characters")
+        if len(attachment_ids) > 4:
+            raise ValueError("a message cannot contain more than four attachments")
+        if not body and not attachment_ids and not sticker_ids:
+            raise ValueError("a message must contain text, an attachment, or a sticker")
+
+        operation_id = str(client_message_id or uuid.uuid4())
+        payload = await self._transport.request(
+            "POST",
+            self._messages_path(community_id, channel_id),
+            json={
+                "clientMessageId": operation_id,
+                "body": body,
+                "replyToSeq": reply_to_seq,
+                "attachmentIds": list(attachment_ids),
+                "stickerIds": list(sticker_ids),
+            },
+            retryable=True,
+        )
+        if payload is None:
+            raise RuntimeError("VoiceRoute returned no sent message")
+        return Message.from_dict(payload["message"])
+
+    async def edit(
+        self,
+        community_id: str,
+        channel_id: str,
+        message_seq: str,
+        body: str,
+        *,
+        version: int,
+    ) -> Message:
+        """Replace the text of an existing message."""
+        if not body:
+            raise ValueError("edited message body cannot be empty")
+        if len(body) > 4000:
+            raise ValueError("message body cannot exceed 4000 characters")
+        payload = await self._transport.request(
+            "PATCH",
+            self._message_path(community_id, channel_id, message_seq),
+            json={"body": body, "version": version},
+        )
+        return _required_message(payload, "edited")
+
+    async def delete(self, community_id: str, channel_id: str, message_seq: str) -> None:
+        """Delete a message. Repeating the same request is safe at transport level."""
+        await self._transport.request(
+            "DELETE",
+            self._message_path(community_id, channel_id, message_seq),
+            retryable=True,
+        )
+
+    async def set_pin(
+        self,
+        community_id: str,
+        channel_id: str,
+        message_seq: str,
+        *,
+        pinned: bool = True,
+    ) -> Message:
+        """Set the desired pin state for a message."""
+        payload = await self._transport.request(
+            "PUT",
+            f"{self._message_path(community_id, channel_id, message_seq)}/pin",
+            json={"pinned": pinned},
+            retryable=True,
+        )
+        return _required_message(payload, "pin update")
+
+    async def set_reaction(
+        self,
+        community_id: str,
+        channel_id: str,
+        message_seq: str,
+        emoji: str,
+        *,
+        active: bool = True,
+    ) -> Message:
+        """Set the current bot's desired reaction state."""
+        if not emoji or len(emoji) > 64:
+            raise ValueError("emoji must contain between 1 and 64 characters")
+        payload = await self._transport.request(
+            "PUT",
+            f"{self._message_path(community_id, channel_id, message_seq)}/reactions",
+            json={"emoji": emoji, "active": active},
+            retryable=True,
+        )
+        return _required_message(payload, "reaction update")
+
+    async def pins(
+        self,
+        community_id: str,
+        channel_id: str,
+    ) -> MessagePage:
+        """Read pinned messages in a channel."""
+        payload = await self._transport.request(
+            "GET",
+            f"{self._channel_path(community_id, channel_id)}/pins",
+        )
+        return _message_page(payload)
+
+    async def search(
+        self,
+        community_id: str,
+        channel_id: str,
+        query: str,
+        *,
+        before_seq: str | None = None,
+    ) -> MessagePage:
+        """Search visible messages in a channel."""
+        if not query.strip():
+            raise ValueError("search query cannot be empty")
+        payload = await self._transport.request(
+            "GET",
+            f"{self._channel_path(community_id, channel_id)}/search",
+            params={"q": query, "beforeSeq": before_seq},
+        )
+        return _message_page(payload)
+
+    @staticmethod
+    def _messages_path(community_id: str, channel_id: str) -> str:
+        return f"/api/communities/{community_id}/channels/{channel_id}/messages"
+
+    @staticmethod
+    def _channel_path(community_id: str, channel_id: str) -> str:
+        return f"/api/communities/{community_id}/channels/{channel_id}"
+
+    @classmethod
+    def _message_path(cls, community_id: str, channel_id: str, message_seq: str) -> str:
+        return f"{cls._messages_path(community_id, channel_id)}/{message_seq}"
+
+
+def _optional_cursor(value: object) -> str | None:
+    return None if value is None else str(value)
+
+
+def _validate_limit(limit: int) -> None:
+    if not 1 <= limit <= 100:
+        raise ValueError("limit must be between 1 and 100")
+
+
+def _message_page(payload: dict[str, object] | None) -> MessagePage:
+    if payload is None:
+        return MessagePage(())
+    raw_items = payload.get("items", payload.get("messages", []))
+    items = raw_items if isinstance(raw_items, list) else []
+    return MessagePage(
+        items=tuple(Message.from_dict(item) for item in items if isinstance(item, dict)),
+        next_before_seq=_optional_cursor(payload.get("nextBeforeSeq")),
+    )
+
+
+def _required_message(payload: dict[str, object] | None, operation: str) -> Message:
+    if payload is None:
+        raise RuntimeError(f"VoiceRoute returned no message after {operation}")
+    raw_message = payload.get("message", payload)
+    if not isinstance(raw_message, dict):
+        raise RuntimeError(f"VoiceRoute returned an invalid message after {operation}")
+    return Message.from_dict(raw_message)