osmium-chat 0.1.1__tar.gz

osmium_chat-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ijsbol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

osmium_chat-0.1.1/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: osmium-chat
+Version: 0.1.1
+Summary: A Python API wrapper for Osmium.
+License: MIT
+License-File: LICENSE
+Author: abigail phoebe
+Author-email: abigail@phoebe.sh
+Requires-Python: >=3.13,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: osmium-protos (>=2.0.0)
+Requires-Dist: websockets (>=16.0)
+Project-URL: Bug Tracker, https://github.com/ijsbol/osmium-chat/issues
+Project-URL: Homepage, https://github.com/ijsbol/osmium-chat
+Description-Content-Type: text/markdown
+
+# osmiumchat
+
+
+A Python API wrapper for [Osmium](https://osmium.chat).
+
+
+![enbyware](https://pride-badges.pony.workers.dev/static/v1?label=enbyware&labelColor=%23555&stripeWidth=8&stripeColors=FCF434%2CFFFFFF%2C9C59D1%2C2C2C2C)
+
+
+> [!NOTE]
+> the code was written by humans, the documentation was ai-assisted as i suck at writing documentation lol
+

osmium_chat-0.1.1/README.md

@@ -0,0 +1,11 @@
+# osmiumchat
+
+
+A Python API wrapper for [Osmium](https://osmium.chat).
+
+
+![enbyware](https://pride-badges.pony.workers.dev/static/v1?label=enbyware&labelColor=%23555&stripeWidth=8&stripeColors=FCF434%2CFFFFFF%2C9C59D1%2C2C2C2C)
+
+
+> [!NOTE]
+> the code was written by humans, the documentation was ai-assisted as i suck at writing documentation lol

osmium_chat-0.1.1/osmium_chat/__init__.py

@@ -0,0 +1,39 @@
+import tomllib
+from pathlib import Path
+
+
+def _get_version() -> str:
+    """Read the package version from the project's ``pyproject.toml``.
+
+    Supports both PEP 621 (``[project]``) and Poetry (``[tool.poetry]``) layouts.
+    """
+    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    with pyproject.open("rb") as f:
+        data = tomllib.load(f)
+    project = data.get("project")
+    if project is not None and "version" in project:
+        return project["version"]
+    return data["tool"]["poetry"]["version"]
+
+
+__version__: str = _get_version()
+
+
+# Imported after ``__version__`` is defined, since the submodules read it at
+# import time.
+from osmium_chat.bot import Bot
+from osmium_chat.channel import Channel
+from osmium_chat.commands import Command
+from osmium_chat.context import Context
+from osmium_chat.message import Message
+from osmium_chat.user.user import User
+
+__all__: tuple[str, ...] = (
+    "__version__",
+    "Bot",
+    "Channel",
+    "Command",
+    "Context",
+    "Message",
+    "User",
+)

osmium_chat-0.1.1/osmium_chat/bot.py

@@ -0,0 +1,217 @@
+import asyncio
+from collections.abc import Awaitable, Callable
+from logging import Logger
+from typing import Any, TypeVar
+
+from osmium_protos import PB_UpdateMessageCreated, PB_UseInvite
+
+from osmium_chat.channel import Channel
+from osmium_chat.client import Client
+from osmium_chat.commands import Command, CommandCallback, StringView
+from osmium_chat.context import Context
+from osmium_chat.errors import CommandError, CommandNotFound
+from osmium_chat.message import Message
+from osmium_chat.user.user import User
+
+
+EventHandler = Callable[..., Awaitable[None]]
+EH = TypeVar("EH", bound=EventHandler)
+
+
+class Bot:
+    """The main entry point for an Osmium bot.
+
+    Holds connection state, the registered event listeners, and the
+    authenticated :class:`~osmium_chat.user.user.User` once connected.
+    """
+
+    __slots__: tuple[str, ...] = (
+        "prefix",
+        "_logger",
+        "_client",
+        "_listeners",
+        "_commands",
+        "user",
+    )
+
+    def __init__(
+        self,
+        prefix: str,
+        client_id: int,
+        *,
+        logger: Logger | None = None,
+    ) -> None:
+        """Create a bot.
+
+        :param prefix: The command prefix the bot responds to (e.g. ``"!"``).
+        :param client_id: The Osmium client id this bot authenticates as.
+        :param logger: Optional logger; a default one is created if omitted.
+        """
+        self.prefix = prefix
+        self._logger = logger or Logger(__name__)
+        self._client: Client = Client(
+            client_id=client_id,
+            bot=self,
+            logger=self._logger,
+        )
+        self._listeners: dict[str, list[EventHandler]] = {}
+        self._commands: dict[str, Command] = {}
+        self.user: User | None = None
+
+    def on(self, event: str) -> Callable[[EH], EH]:
+        """Register a coroutine as a listener for the given event.
+
+        This is the generic primitive every ``on_*`` decorator is built on,
+        so new events only need a thin wrapper here plus a ``dispatch`` call
+        from wherever the event originates.
+
+        .. code-block:: python
+
+            @bot.on("connect")
+            async def handler() -> None:
+                ...
+        """
+        def decorator(func: EH) -> EH:
+            self._listeners.setdefault(event, []).append(func)
+            return func
+        return decorator
+
+    async def dispatch(self, event: str, *args: Any, **kwargs: Any) -> None:
+        """Invoke every listener registered for ``event``.
+
+        Handler errors are logged and swallowed so one faulty listener can't
+        take down the connection or block the others.
+        """
+        for handler in self._listeners.get(event, []):
+            try:
+                await handler(*args, **kwargs)
+            except Exception:
+                self._logger.exception("Error in '%s' event handler", event)
+
+    def command(
+        self,
+        name: str | None = None,
+        *,
+        aliases: tuple[str, ...] = (),
+    ) -> Callable[[CommandCallback], Command]:
+        """Register a coroutine as a command.
+
+        The decorated coroutine receives a :class:`~osmium_chat.context.Context`
+        as its first argument; every parameter after that is parsed from the
+        message text and converted to its annotated type. Parameters with a
+        default become optional, a keyword-only parameter (after ``*``) consumes
+        the rest of the message, and ``*args`` collects all remaining tokens.
+
+        .. code-block:: python
+
+            @bot.command("say")
+            async def say(ctx: Context, *, words: str = "...") -> None:
+                await ctx.channel.send(words)
+
+        :param name: The command name; defaults to the function name.
+        :param aliases: Additional names the command also responds to.
+        """
+        def decorator(func: CommandCallback) -> Command:
+            command = Command(func, name=name, aliases=aliases)
+            self.add_command(command)
+            return command
+        return decorator
+
+    def add_command(self, command: Command) -> None:
+        """Register a command under its name and every alias.
+
+        :param command: The command to register.
+        :raises ValueError: If the name or an alias is already registered.
+        """
+        for key in (command.name, *command.aliases):
+            if key in self._commands:
+                raise ValueError(f"Command name {key!r} is already registered")
+            self._commands[key] = command
+
+    def get_command(self, name: str) -> Command | None:
+        """Look up a command by name or alias.
+
+        :param name: The name or alias to resolve.
+        """
+        return self._commands.get(name)
+
+    async def process_commands(self, update: PB_UpdateMessageCreated) -> None:
+        """Turn an inbound message into a command invocation.
+
+        Builds the :class:`~osmium_chat.context.Context`, fires the ``message``
+        event, and — if the message starts with the prefix and names a known
+        command — parses its arguments and invokes it. Command failures are
+        surfaced through the ``command_error`` event.
+
+        :param update: The decoded ``message_created`` payload from the gateway.
+        """
+        if update.message is None or update.message.chat_ref is None:
+            return
+
+        message = Message(update.message)
+        author = User(update.author) if update.author else None
+        channel = Channel(update.message.chat_ref, self._client)
+        ctx = Context(
+            bot=self,
+            message=message,
+            author=author,
+            channel=channel,
+            prefix=self.prefix,
+        )
+
+        await self.dispatch("message", ctx)
+
+        # Never react to our own messages, to avoid command loops.
+        if self.user is not None and message.author_id == self.user.id:
+            return
+
+        content = message.content
+        if not content.startswith(self.prefix):
+            return
+
+        view = StringView(content[len(self.prefix):])
+        name = view.get_word()
+        if not name:
+            return
+
+        ctx.invoked_with = name
+        command = self.get_command(name)
+        if command is None:
+            await self.dispatch("command_error", ctx, CommandNotFound(name))
+            return
+
+        try:
+            await command.invoke(ctx, view)
+        except CommandError as error:
+            await self.dispatch("command_error", ctx, error)
+        except Exception as error:
+            self._logger.exception("Unhandled error in command %r", name)
+            await self.dispatch("command_error", ctx, error)
+
+    async def use_invite(self, invite_code: str) -> None:
+        """Redeem an invite code on behalf of the bot.
+
+        :param invite_code: The invite code to redeem.
+        """
+        self._logger.info(f"Using invite with code: {invite_code}")
+        await self._client.send_pb(PB_UseInvite(code=invite_code))
+
+    async def connect(self, token: str) -> None:
+        """Connect to Osmium and run the bot until the connection closes.
+
+        This authenticates with ``token``, fires the ``connect`` event, then
+        blocks processing incoming messages.
+
+        :param token: The authorization token for this bot.
+        """
+        await self._client.connect(token)
+
+    def run(self, token: str) -> None:
+        """Start the bot's event loop and connect, blocking until it closes.
+
+        A synchronous convenience wrapper around :meth:`connect` for use as a
+        program's entry point.
+
+        :param token: The authorization token for this bot.
+        """
+        asyncio.run(self.connect(token))

osmium_chat-0.1.1/osmium_chat/channel.py

@@ -0,0 +1,46 @@
+from typing import TYPE_CHECKING
+
+from osmium_protos import PB_ChatRef, PB_SendMessage
+
+if TYPE_CHECKING:
+    from osmium_chat.client import Client
+
+
+__all__: tuple[str, ...] = (
+    "Channel",
+)
+
+
+class Channel:
+    """A conversation a message can be sent to.
+
+    Wraps the :class:`~osmium_protos.PB_ChatRef` that identifies a destination
+    (a user DM, community channel, group, or self) together with the client used
+    to deliver outbound messages, so callers can simply ``await channel.send(...)``.
+    """
+
+    __slots__: tuple[str, ...] = (
+        "_chat_ref",
+        "_client",
+    )
+
+    def __init__(self, chat_ref: PB_ChatRef, client: "Client") -> None:
+        """Bind a channel to a destination ref and the transport client.
+
+        :param chat_ref: The ref identifying where messages should be delivered.
+        :param client: The client used to send messages.
+        """
+        self._chat_ref = chat_ref
+        self._client = client
+
+    async def send(self, content: str, *, reply_to: int | None = None) -> None:
+        """Send a text message to this channel.
+
+        :param content: The message text to send.
+        :param reply_to: Optional id of a message this should reply to.
+        """
+        await self._client.send_pb(PB_SendMessage(
+            chat_ref=self._chat_ref,
+            message=content,
+            reply_to=reply_to,
+        ))

osmium_chat-0.1.1/osmium_chat/client.py

@@ -0,0 +1,152 @@
+from logging import Logger
+import platform
+from typing import TYPE_CHECKING, Any, cast
+
+from osmium_chat import __version__
+
+from websockets.asyncio.client import ClientConnection, connect
+from websockets.exceptions import ConnectionClosed
+from osmium_protos import unwrap, wrap, PB_Initialize, PB_Authorization, PB_Authorize, PB_UpdateMessageCreated
+from osmium_protos.osmium.client.auth import Authorization
+from osmium_chat.user.user import User
+
+if TYPE_CHECKING:
+    from osmium_chat.bot import Bot
+
+
+class Client:
+    """Low-level WebSocket transport between a :class:`~osmium_chat.bot.Bot`
+    and the Osmium gateway.
+
+    Handles connecting, the initialize/authorize handshake, sending protobuf
+    messages, and reading the inbound message stream.
+    """
+
+    __slots__: tuple[str, ...] = (
+        "bot",
+        "id",
+        "_connection",
+        "__session_id",
+        "__token",
+        "_logger",
+    )
+
+    WS_URL: str = "wss://ws-0.osmium.chat"
+
+    def __init__(
+        self,
+        client_id: int,
+        bot: "Bot",
+        *,
+        logger: Logger | None = None,
+    ) -> None:
+        """Create a client bound to ``bot``.
+
+        :param client_id: The Osmium client id to identify as.
+        :param bot: The owning bot, used to dispatch events and store the user.
+        :param logger: Optional logger; a default one is created if omitted.
+        """
+        self.bot: "Bot" = bot
+        self.id: int = client_id
+        self._connection: ClientConnection | None = None
+        self.__session_id: int | None = None
+        self.__token: str | None = None
+        self._logger = logger or Logger(__name__)
+
+    async def _handle_msg(self, message: Any) -> None:
+        """Process a single decoded inbound message.
+
+        Routes ``message_created`` updates into the bot's command pipeline; all
+        other messages are logged for now.
+
+        :param message: The unwrapped protobuf message.
+        """
+        self._logger.debug(f"Received message: {message}")
+        if isinstance(message, PB_UpdateMessageCreated):
+            await self.bot.process_commands(message)
+
+    async def _handle_ws(self, **kwargs: Any) -> None:
+        """Read and dispatch inbound messages until the connection closes."""
+        assert self._connection is not None
+
+        async for data in self._connection:
+            try:
+                _, message = unwrap(cast(bytes, data))
+                await self._handle_msg(message)
+            except ConnectionClosed as e:
+                self._logger.error("WebSocket connection closed: %s", e)
+                raise ConnectionError("Connection closed while waiting for authorization") from e
+
+    async def send_pb(self, message: Any) -> None:
+        """Wrap, serialize, and send a protobuf message over the connection.
+
+        :param message: The protobuf message to send.
+        """
+        assert self._connection is not None
+        await self._connection.send(wrap(message).SerializeToString())
+
+    def _handle_authorization(self, message: Authorization) -> None:
+        """Store the session id/token and the authenticated user from an
+        authorization response.
+
+        :param message: The authorization payload from the gateway.
+        """
+        self.__session_id = message.session_id
+        self.__token = message.token
+        if message.user:
+            self.bot.user = User(message.user)
+
+    async def connect(self, token: str) -> None:
+        """Open the connection, run the handshake, and process messages.
+
+        Performs the initialize/authorize exchange, dispatches the bot's
+        ``connect`` event once authorized, then blocks reading messages until
+        the connection closes.
+
+        :param token: The authorization token for the bot.
+        :raises ConnectionError: If the connection closes before authorization.
+        """
+        self._logger.info("Connecting to WebSocket server...")
+        self._connection = await connect(
+            uri=self.WS_URL,
+        )
+
+        self._logger.info("Connected to WebSocket server, initializing...")
+        await self.send_pb(PB_Initialize(
+            client_id=self.id,
+            device_type="Library[Python/OsmiumChat]",
+            device_version=__version__,
+            app_version=f"OsmiumChat Python API Wrapper (Python {platform.python_version()}) (OsmiumChat {__version__})",
+            no_subscribe=False,
+        ))
+
+        self._logger.info("Received initialization response, getting entry points...")
+
+        # this will return entry points and vapidPublicKey, but we don't need them for now
+        await self._connection.recv()
+
+        self._logger.info("Received initialization response, sending authorization...")
+        await self.send_pb(PB_Authorize(
+            token=token,
+        ))
+
+        # wait for authorization
+        # most of the time it is the first or second message, but to be safe we will loop until we get it
+        self._logger.info("Waiting for authorization...")
+        async for data in self._connection:
+            try:
+                _, message = unwrap(cast(bytes, data))
+                if isinstance(message, PB_Authorization):
+                    self._handle_authorization(message)
+                    break
+                else:
+                    await self._handle_msg(message)
+            except ConnectionClosed:
+                self._logger.error("Connection closed while waiting for authorization")
+                raise ConnectionError("Connection closed while waiting for authorization")
+
+        self._logger.info("Authorized successfully, dispatching connect event...")
+        await self.bot.dispatch("connect")
+
+        self._logger.info("Starting message handler...")
+        await self._handle_ws()

osmium_chat-0.1.1/osmium_chat/commands.py

@@ -0,0 +1,366 @@
+import inspect
+from collections.abc import Awaitable, Callable
+from types import UnionType
+from typing import TYPE_CHECKING, Any, Union, get_args, get_origin, get_type_hints
+
+from osmium_chat.errors import BadArgument, MissingRequiredArgument, TooManyArguments
+
+if TYPE_CHECKING:
+    from osmium_chat.context import Context
+
+
+__all__: tuple[str, ...] = (
+    "Command",
+    "Parameter",
+    "StringView",
+    "CommandCallback",
+)
+
+
+CommandCallback = Callable[..., Awaitable[None]]
+
+_TRUE = frozenset({"true", "t", "yes", "y", "1", "on", "enable", "enabled"})
+_FALSE = frozenset({"false", "f", "no", "n", "0", "off", "disable", "disabled"})
+
+
+def _convert_bool(value: str) -> bool:
+    """Convert a token to a bool, accepting common truthy/falsey spellings."""
+    lowered = value.lower()
+    if lowered in _TRUE:
+        return True
+    if lowered in _FALSE:
+        return False
+    raise ValueError(value)
+
+
+# Maps an annotated argument type to the callable that parses a raw token into it.
+# Extend this to teach the command parser about new argument types.
+CONVERTERS: dict[type, Callable[[str], Any]] = {
+    str: str,
+    int: int,
+    float: float,
+    bool: _convert_bool,
+}
+
+
+class StringView:
+    """A cursor over a command's argument string.
+
+    Hands out whitespace-delimited words one at a time (respecting single and
+    double quotes so multi-word arguments can be passed), or the entire
+    remaining string for "consume rest" parameters.
+    """
+
+    __slots__: tuple[str, ...] = (
+        "text",
+        "index",
+    )
+
+    _QUOTES: frozenset[str] = frozenset({'"', "'"})
+
+    def __init__(self, text: str) -> None:
+        """:param text: The raw argument string to read from."""
+        self.text = text
+        self.index = 0
+
+    @property
+    def eof(self) -> bool:
+        """Whether the cursor has reached the end of the string."""
+        return self.index >= len(self.text)
+
+    def skip_whitespace(self) -> None:
+        """Advance the cursor past any run of whitespace."""
+        while not self.eof and self.text[self.index].isspace():
+            self.index += 1
+
+    def rest(self) -> str:
+        """Consume and return the remaining string, stripped of surrounding space."""
+        self.skip_whitespace()
+        remaining = self.text[self.index:]
+        self.index = len(self.text)
+        return remaining.strip()
+
+    def get_word(self) -> str | None:
+        """Consume and return the next word, or ``None`` if none remain.
+
+        A word is a run of non-whitespace characters, unless it is wrapped in
+        matching quotes, in which case everything up to the closing quote is
+        returned as a single word (with backslash escaping inside the quotes).
+        """
+        self.skip_whitespace()
+        if self.eof:
+            return None
+
+        char = self.text[self.index]
+        if char in self._QUOTES:
+            return self._read_quoted(char)
+
+        start = self.index
+        while not self.eof and not self.text[self.index].isspace():
+            self.index += 1
+        return self.text[start:self.index]
+
+    def _read_quoted(self, quote: str) -> str:
+        """Read a quoted word starting at the opening ``quote`` character."""
+        self.index += 1  # skip opening quote
+        chars: list[str] = []
+        while not self.eof:
+            char = self.text[self.index]
+            if char == "\\" and self.index + 1 < len(self.text):
+                self.index += 1
+                chars.append(self.text[self.index])
+            elif char == quote:
+                self.index += 1  # skip closing quote
+                return "".join(chars)
+            else:
+                chars.append(char)
+            self.index += 1
+        # Unterminated quote: treat the rest as literal content.
+        return "".join(chars)
+
+
+class Parameter:
+    """A single command argument, resolved from the callback's signature."""
+
+    __slots__: tuple[str, ...] = (
+        "name",
+        "annotation",
+        "kind",
+        "default",
+        "optional",
+    )
+
+    def __init__(
+        self,
+        name: str,
+        annotation: Any,
+        kind: inspect._ParameterKind,
+        default: Any,
+    ) -> None:
+        """:param name: The parameter name.
+        :param annotation: The resolved leaf type to convert tokens to.
+        :param kind: The parameter kind (positional, keyword-only, var-positional).
+        :param default: The default value, or :data:`inspect.Parameter.empty`.
+        """
+        self.name = name
+        self.annotation = annotation
+        self.kind = kind
+        self.default = default
+        # A parameter is optional if it has a default or accepts ``None``.
+        self.optional = default is not inspect.Parameter.empty
+
+    @property
+    def required(self) -> bool:
+        """Whether a value must be supplied for this parameter."""
+        return not self.optional
+
+    def convert(self, value: str) -> Any:
+        """Convert a raw token to this parameter's annotated type.
+
+        :param value: The raw token from the message.
+        :raises BadArgument: If the token cannot be converted.
+        """
+        annotation = self.annotation
+        if annotation is inspect.Parameter.empty or annotation is str:
+            return value
+        converter = CONVERTERS.get(annotation)
+        try:
+            if converter is not None:
+                return converter(value)
+            return annotation(value)
+        except (ValueError, TypeError) as exc:
+            raise BadArgument(self.name, value, annotation) from exc
+
+
+def _resolve_annotation(annotation: Any) -> tuple[Any, bool]:
+    """Reduce an annotation to a concrete leaf type and an optional flag.
+
+    Unwraps ``Optional[T]`` / ``T | None`` to ``(T, True)``; for a plain ``T``
+    returns ``(T, False)``. For unions of several non-``None`` types the first
+    member is used.
+    """
+    origin = get_origin(annotation)
+    if origin is Union or origin is UnionType:
+        args = [arg for arg in get_args(annotation) if arg is not type(None)]
+        accepts_none = len(args) != len(get_args(annotation))
+        leaf = args[0] if args else str
+        return leaf, accepts_none
+    return annotation, False
+
+
+class Command:
+    """A registered command: a name, optional aliases, and a parsed callback.
+
+    The callback's signature drives argument parsing. The first parameter always
+    receives the :class:`~osmium_chat.context.Context`; each parameter after it
+    becomes a command argument, read from the message text following the command
+    name and converted according to the rules below.
+
+    **Automatic type conversion**
+
+    Each argument is converted to its annotated type before the callback runs.
+    The built-in converters are:
+
+    - ``str`` (or an un-annotated parameter) — the raw token, unchanged.
+    - ``int`` — parsed with :class:`int`.
+    - ``float`` — parsed with :class:`float`.
+    - ``bool`` — accepts ``true``/``false``, ``yes``/``no``, ``y``/``n``,
+      ``on``/``off``, ``1``/``0``, ``enable``/``disable`` (case-insensitive).
+
+    Any other annotation is called with the raw token (``annotation(token)``),
+    so a type whose constructor takes a single string just works. Conversion
+    failures raise :class:`~osmium_chat.errors.BadArgument`. New types can be
+    registered by adding to :data:`CONVERTERS`.
+
+    **Optional arguments**
+
+    A parameter with a default value is optional; if the invoker omits it, the
+    default is used. Otherwise a missing argument raises
+    :class:`~osmium_chat.errors.MissingRequiredArgument`. An annotation of
+    ``T | None`` (i.e. ``Optional[T]``) is converted as ``T``.
+
+    **Quoting** (``"..."``)
+
+    Arguments are split on whitespace, so each parameter normally receives a
+    single word. To pass a value that contains spaces as one argument, wrap it
+    in single or double quotes; the surrounding quotes are stripped and a
+    backslash escapes the next character inside them::
+
+        @bot.command("echo")
+        async def echo(ctx: Context, word: str) -> None:
+            await ctx.channel.send(word)
+
+        # !echo "hello world"   ->   word == "hello world"
+
+    **Consume-rest** (``*``) **and variadic** (``*args``)
+
+    A keyword-only parameter — one declared after a bare ``*`` — consumes the
+    entire remaining message as a single, unsplit string (quotes are kept
+    verbatim here). This is the idiomatic way to accept free-form text::
+
+        @bot.command("say")
+        async def say(ctx: Context, *, words: str) -> None:
+            await ctx.channel.send(words)
+
+        # !say hello there world   ->   words == "hello there world"
+
+    A variadic ``*args`` parameter instead collects every remaining token,
+    converting each one to the annotated element type::
+
+        @bot.command("sum")
+        async def sum_(ctx: Context, *numbers: int) -> None:
+            await ctx.channel.send(str(sum(numbers)))
+
+        # !sum 1 2 3   ->   numbers == (1, 2, 3)
+
+    Any leftover text after all parameters are filled raises
+    :class:`~osmium_chat.errors.TooManyArguments`.
+    """
+
+    __slots__: tuple[str, ...] = (
+        "name",
+        "callback",
+        "aliases",
+        "params",
+    )
+
+    def __init__(
+        self,
+        callback: CommandCallback,
+        *,
+        name: str | None = None,
+        aliases: tuple[str, ...] = (),
+    ) -> None:
+        """:param callback: The coroutine invoked when the command runs.
+        :param name: The command name; defaults to the callback's name.
+        :param aliases: Additional names the command also responds to.
+        """
+        if not inspect.iscoroutinefunction(callback):
+            raise TypeError("Command callback must be a coroutine function")
+        self.callback = callback
+        self.name = name or callback.__name__
+        self.aliases = aliases
+        self.params = self._build_params(callback)
+
+    @staticmethod
+    def _build_params(callback: CommandCallback) -> list[Parameter]:
+        """Parse the callback signature into argument parameters (skipping ctx)."""
+        signature = inspect.signature(callback)
+        try:
+            hints = get_type_hints(callback)
+        except Exception:
+            # If annotations can't be resolved (e.g. a missing import) fall back
+            # to whatever raw annotations the signature carries.
+            hints = {}
+
+        params: list[Parameter] = []
+        for index, param in enumerate(signature.parameters.values()):
+            if index == 0:
+                continue  # the context parameter
+            if param.kind in (
+                inspect.Parameter.VAR_KEYWORD,
+            ):
+                continue  # **kwargs is not fed from the message
+            raw = hints.get(param.name, param.annotation)
+            annotation, _ = _resolve_annotation(raw)
+            params.append(Parameter(param.name, annotation, param.kind, param.default))
+        return params
+
+    def parse_arguments(self, view: StringView) -> tuple[list[Any], dict[str, Any]]:
+        """Convert the argument string into call arguments for the callback.
+
+        Returns the positional ``args`` and keyword-only ``kwargs`` to pass to
+        the callback alongside the context.
+
+        :param view: A view over the message text following the command name.
+        :raises MissingRequiredArgument: If a required argument is absent.
+        :raises BadArgument: If an argument fails type conversion.
+        :raises TooManyArguments: If unconsumed tokens remain at the end.
+        """
+        args: list[Any] = []
+        kwargs: dict[str, Any] = {}
+        for param in self.params:
+            if param.kind is inspect.Parameter.VAR_POSITIONAL:
+                # ``*args``: greedily convert every remaining token.
+                while True:
+                    word = view.get_word()
+                    if word is None:
+                        break
+                    args.append(param.convert(word))
+                return args, kwargs
+
+            if param.kind is inspect.Parameter.KEYWORD_ONLY:
+                # Keyword-only parameter: consume the rest of the message. It is
+                # passed by name since the callback won't accept it positionally.
+                remaining = view.rest()
+                if not remaining:
+                    if param.required:
+                        raise MissingRequiredArgument(param.name)
+                    kwargs[param.name] = param.default
+                else:
+                    kwargs[param.name] = param.convert(remaining)
+                return args, kwargs
+
+            word = view.get_word()
+            if word is None:
+                if param.required:
+                    raise MissingRequiredArgument(param.name)
+                args.append(param.default)
+            else:
+                args.append(param.convert(word))
+
+        leftover = view.rest()
+        if leftover:
+            raise TooManyArguments(leftover)
+        return args, kwargs
+
+    async def invoke(self, ctx: "Context", view: StringView) -> None:
+        """Parse arguments from ``view`` and run the command callback.
+
+        :param ctx: The invocation context, passed as the first argument.
+        :param view: A view over the message text following the command name.
+        """
+        args, kwargs = self.parse_arguments(view)
+        ctx.command = self
+        ctx.args = args
+        await self.callback(ctx, *args, **kwargs)

osmium_chat-0.1.1/osmium_chat/context.py

@@ -0,0 +1,84 @@
+from typing import TYPE_CHECKING, Any
+
+from osmium_chat.channel import Channel
+from osmium_chat.message import Message
+from osmium_chat.user.user import User
+
+if TYPE_CHECKING:
+    from osmium_chat.bot import Bot
+    from osmium_chat.commands import Command
+
+
+__all__: tuple[str, ...] = (
+    "Context",
+)
+
+
+class Context:
+    """The invocation context handed to a command callback.
+
+    Bundles everything a command needs: who sent the message
+    (:attr:`author`), where it came from (:attr:`channel`), the underlying
+    :attr:`message`, and the resolved command metadata. Reply with
+    ``await ctx.channel.send(...)`` or the :meth:`send` shortcut.
+    """
+
+    __slots__: tuple[str, ...] = (
+        "bot",
+        "message",
+        "author",
+        "channel",
+        "prefix",
+        "command",
+        "invoked_with",
+        "args",
+    )
+
+    def __init__(
+        self,
+        *,
+        bot: "Bot",
+        message: Message,
+        author: User | None,
+        channel: Channel,
+        prefix: str,
+        command: "Command | None" = None,
+        invoked_with: str | None = None,
+        args: list[Any] | None = None,
+    ) -> None:
+        """Create a context.
+
+        :param bot: The bot handling the message.
+        :param message: The message that triggered the command.
+        :param author: The user who sent the message, if known.
+        :param channel: The channel the message was sent in.
+        :param prefix: The prefix the message was invoked with.
+        :param command: The resolved command, if one matched.
+        :param invoked_with: The name or alias actually used to invoke it.
+        :param args: The converted positional arguments passed to the callback.
+        """
+        self.bot = bot
+        self.message = message
+        self.author = author
+        self.channel = channel
+        self.prefix = prefix
+        self.command = command
+        self.invoked_with = invoked_with
+        self.args: list[Any] = args if args is not None else []
+
+    async def send(self, content: str, *, reply_to: int | None = None) -> None:
+        """Send a message to the channel this command was invoked in.
+
+        A shortcut for ``ctx.channel.send(...)``.
+
+        :param content: The message text to send.
+        :param reply_to: Optional id of a message this should reply to.
+        """
+        await self.channel.send(content, reply_to=reply_to)
+
+    async def reply(self, content: str) -> None:
+        """Reply to the invoking message, threading it as a reply.
+
+        :param content: The message text to send.
+        """
+        await self.channel.send(content, reply_to=self.message.id)

osmium_chat-0.1.1/osmium_chat/errors.py

@@ -0,0 +1,67 @@
+"""Exceptions raised while parsing and invoking commands."""
+
+
+__all__: tuple[str, ...] = (
+    "OsmiumChatError",
+    "CommandError",
+    "CommandNotFound",
+    "ArgumentError",
+    "MissingRequiredArgument",
+    "BadArgument",
+    "TooManyArguments",
+)
+
+
+class OsmiumChatError(Exception):
+    """Base class for every exception raised by ``osmium_chat``."""
+
+
+class CommandError(OsmiumChatError):
+    """Base class for errors that occur while handling a command."""
+
+
+class CommandNotFound(CommandError):
+    """No command was registered under the invoked name or alias."""
+
+    def __init__(self, name: str) -> None:
+        """:param name: The name the user tried to invoke."""
+        self.name = name
+        super().__init__(f"Command {name!r} is not registered")
+
+
+class ArgumentError(CommandError):
+    """Base class for problems converting or supplying command arguments."""
+
+
+class MissingRequiredArgument(ArgumentError):
+    """A required argument was not supplied by the invoker."""
+
+    def __init__(self, name: str) -> None:
+        """:param name: The name of the parameter that was missing."""
+        self.name = name
+        super().__init__(f"Missing required argument: {name!r}")
+
+
+class BadArgument(ArgumentError):
+    """An argument could not be converted to the parameter's annotated type."""
+
+    def __init__(self, name: str, value: str, expected: type) -> None:
+        """:param name: The parameter the value was being converted for.
+        :param value: The raw token that failed to convert.
+        :param expected: The type conversion was attempted against.
+        """
+        self.name = name
+        self.value = value
+        self.expected = expected
+        super().__init__(
+            f"Could not convert {value!r} to {expected.__name__} for argument {name!r}",
+        )
+
+
+class TooManyArguments(ArgumentError):
+    """The invoker supplied more arguments than the command accepts."""
+
+    def __init__(self, extra: str) -> None:
+        """:param extra: The leftover, unconsumed portion of the message."""
+        self.extra = extra
+        super().__init__(f"Too many arguments supplied: {extra!r}")

osmium_chat-0.1.1/osmium_chat/message.py

@@ -0,0 +1,33 @@
+from osmium_protos import PB_ChatRef, PB_Message
+
+
+__all__: tuple[str, ...] = (
+    "Message",
+)
+
+
+class Message:
+    """A chat message, parsed from its protobuf representation.
+
+    Holds where the message came from (``chat_ref``) so replies can be routed
+    back to the same conversation, alongside its text content and metadata.
+    """
+
+    __slots__: tuple[str, ...] = (
+        "id",
+        "content",
+        "author_id",
+        "chat_ref",
+        "reply_to",
+    )
+
+    def __init__(self, message: PB_Message) -> None:
+        """Build a message from a protobuf payload.
+
+        :param message: The raw ``PB_Message`` to read fields from.
+        """
+        self.id: int = message.message_id
+        self.content: str = message.message
+        self.author_id: int = message.author_id
+        self.chat_ref: PB_ChatRef | None = message.chat_ref
+        self.reply_to: int | None = message.reply_to

osmium_chat-0.1.1/osmium_chat/photo.py

@@ -0,0 +1,23 @@
+from osmium_protos import PB_ChatPhoto
+
+
+__all__: tuple[str, ...] = (
+    "Photo",
+)
+
+
+class Photo:
+    """A chat photo: its file id and an inline preview blob."""
+
+    __slots__: tuple[str, ...] = (
+        "file_id",
+        "preview",
+    )
+
+    def __init__(self, photo: PB_ChatPhoto) -> None:
+        """Build a photo from a protobuf payload.
+
+        :param photo: The raw ``PB_ChatPhoto`` to read fields from.
+        """
+        self.file_id: int = photo.file_id
+        self.preview: bytes = photo.preview

osmium_chat-0.1.1/osmium_chat/user/__init__.py

@@ -0,0 +1,12 @@
+from osmium_chat.user.activity import UserActivityType, UserStatusActivity
+from osmium_chat.user.status import UserStatus, UserStatusStatus
+from osmium_chat.user.user import User
+
+
+__all__: tuple[str, ...] = (
+    "User",
+    "UserActivityType",
+    "UserStatus",
+    "UserStatusActivity",
+    "UserStatusStatus",
+)

osmium_chat-0.1.1/osmium_chat/user/activity.py

@@ -0,0 +1,41 @@
+from enum import IntEnum
+
+from osmium_protos import PB_UserStatusActivity
+
+
+__all__: tuple[str, ...] = (
+    "UserActivityType",
+    "UserStatusActivity",
+)
+
+
+class UserActivityType(IntEnum):
+    """The kind of activity a user is engaged in."""
+
+    GAME = 0
+    STREAMING = 1
+    LISTENING = 2
+    WATCHING = 3
+
+
+class UserStatusActivity:
+    """A single activity shown in a user's status (e.g. a game being played)."""
+
+    __slots__: tuple[str, ...] = (
+        "title",
+        "type",
+        "start_time",
+        "end_time",
+        "state",
+    )
+
+    def __init__(self, activity: PB_UserStatusActivity) -> None:
+        """Build an activity from a protobuf payload.
+
+        :param activity: The raw ``PB_UserStatusActivity`` to read fields from.
+        """
+        self.title: str = activity.title
+        self.type: UserActivityType = UserActivityType(activity.type)
+        self.start_time: int = activity.start_time
+        self.end_time: int | None = activity.end_time
+        self.state: str | None = activity.state

osmium_chat-0.1.1/osmium_chat/user/status.py

@@ -0,0 +1,37 @@
+from enum import IntEnum
+
+from osmium_protos import PB_UserStatus
+
+from osmium_chat.user.activity import UserStatusActivity
+
+
+__all__: tuple[str, ...] = (
+    "UserStatusStatus",
+    "UserStatus",
+)
+
+
+class UserStatusStatus(IntEnum):
+    """A user's availability state."""
+
+    ONLINE = 0
+    IDLE = 1
+
+
+class UserStatus:
+    """A user's presence: online flag, status state, and activities."""
+
+    __slots__: tuple[str, ...] = (
+        "online",
+        "status",
+        "activities",
+    )
+
+    def __init__(self, status: PB_UserStatus) -> None:
+        """Build a status from a protobuf payload.
+
+        :param status: The raw ``PB_UserStatus`` to read fields from.
+        """
+        self.online: bool = status.online
+        self.status: UserStatusStatus | None = UserStatusStatus(status.status) if status.status else None
+        self.activities: list[UserStatusActivity] = [UserStatusActivity(activity) for activity in status.activities]

osmium_chat-0.1.1/osmium_chat/user/user.py

@@ -0,0 +1,36 @@
+from osmium_protos import PB_User
+
+from osmium_chat.photo import Photo
+from osmium_chat.user.status import UserStatus
+
+
+__all__: tuple[str, ...] = (
+    "User",
+)
+
+
+class User:
+    """An Osmium user, parsed from its protobuf representation."""
+
+    __slots__: tuple[str, ...] = (
+        "id",
+        "name",
+        "username",
+        "status",
+        "photo",
+        "icon",
+        "color",
+    )
+
+    def __init__(self, user: PB_User) -> None:
+        """Build a user from a protobuf payload.
+
+        :param user: The raw ``PB_User`` to read fields from.
+        """
+        self.id: int = user.id
+        self.name: str = user.name
+        self.username: str | None = user.username
+        self.status: UserStatus | None = UserStatus(user.status) if user.status else None
+        self.photo: Photo | None = Photo(user.photo) if user.photo else None
+        self.icon: int | None = user.icon
+        self.color: int | None = user.color

osmium_chat-0.1.1/pyproject.toml

@@ -0,0 +1,35 @@
+[tool.poetry]
+name = "osmium-chat"
+version = "0.1.1"
+description = "A Python API wrapper for Osmium."
+readme = "README.md"
+license = "MIT"
+authors = ["abigail phoebe <abigail@phoebe.sh>"]
+packages = [{ include = "osmium_chat" }]
+
+[tool.poetry.urls]
+Homepage = "https://github.com/ijsbol/osmium-chat"
+"Bug Tracker" = "https://github.com/ijsbol/osmium-chat/issues"
+
+[tool.poetry.dependencies]
+python = ">=3.13,<4.0"
+osmium-protos = ">=2.0.0"
+websockets = ">=16.0"
+
+[tool.poetry.group.dev.dependencies]
+isort = ">=8.0.1"
+ruff = ">=0.15.15"
+twine = ">=6.2.0,<7.0.0"
+build = ">=1.4.0,<2.0.0"
+flake8 = ">=7.3.0,<8.0.0"
+pytest = "^9.0.3"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff.lint]
+select = ["COM812"]
+
+[tool.ruff.format]
+skip-magic-trailing-comma = false