banterbotapi 0.2.2__tar.gz → 0.2.3__tar.gz

{banterbotapi-0.2.2 → banterbotapi-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: banterbotapi
-Version: 0.2.2
+Version: 0.2.3
 Summary: Python SDK for building bots on Banter (banterchat.org) — discord.py-style.
 Author-email: Banter <contact@banterchat.org>
 License-Expression: MIT

{banterbotapi-0.2.2 → banterbotapi-0.2.3}/banterapi/__init__.py

@@ -23,7 +23,7 @@ The library mirrors discord.py conventions where possible. See the Bot,
 Intents, Embed, and Permissions classes for the main entry points.
 """
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 from .client import Bot
 from .intents import Intents
@@ -31,7 +31,13 @@ from .embed import Embed
 from .models import User, Guild, Channel, Member, Role, Message
 from .errors import BanterError, HTTPException, Forbidden, NotFound, RateLimited, GatewayError, LoginFailure, MissingPermissions
 from .permissions import Permissions
-from .commands import has_permissions
+from .commands import (
+    has_permissions,
+    SlashOption,
+    OPTION_STRING, OPTION_INTEGER, OPTION_BOOLEAN,
+    OPTION_USER, OPTION_CHANNEL, OPTION_ROLE,
+)
+from .interactions import Interaction
 
 __all__ = [
     "__version__",
@@ -46,6 +52,12 @@ __all__ = [
     "Message",
     "Permissions",
     "has_permissions",
+    # Slash command support
+    "SlashOption",
+    "OPTION_STRING", "OPTION_INTEGER", "OPTION_BOOLEAN",
+    "OPTION_USER", "OPTION_CHANNEL", "OPTION_ROLE",
+    "Interaction",
+    # Errors
     "BanterError",
     "HTTPException",
     "Forbidden",

{banterbotapi-0.2.2 → banterbotapi-0.2.3}/banterapi/client.py

@@ -117,7 +117,14 @@ class Bot:
         self._gateway = None
         self._handlers = {}
         self._commands = CommandRegistry()
+        # _slash_commands stores registration metadata sent to the server
+        # at sync_commands() time: [{name, description, options}, ...].
+        # _slash_handlers maps command-name → coroutine invoked when the
+        # gateway delivers an interaction_create event for that command.
+        # Separate from _commands because slash handlers take an
+        # Interaction, not a (Context, *args) like prefix handlers.
         self._slash_commands = []
+        self._slash_handlers = {}
         self._loop = None
         if self.help_enabled:
             self._register_default_help()
@@ -150,7 +157,7 @@ class Bot:
         self._handlers[name] = fn
         return fn
 
-    def command(self, name=None, aliases=None, help=None, slash=False, description=""):
+    def command(self, name=None, aliases=None, help=None, slash=False, description="", options=None):
         """Register a prefix command (optionally also as a slash command).
 
         The decorated function is called as ``await fn(ctx, *args)`` —
@@ -172,34 +179,104 @@ class Bot:
                 ``/`` autocomplete dropdown.
             description: Slash-command description. Ignored when
                 ``slash=False``. Falls back to ``help`` or the name.
+            options: Iterable of :class:`~banterapi.SlashOption` to
+                expose as typed slash-command arguments. Only
+                applies when ``slash=True``. When a user invokes the
+                slash command, the server parses the typed options
+                and delivers them to the slash handler as
+                ``interaction.options``. Prefix-invocation is
+                unaffected — prefix args continue to parse from the
+                message text via function-signature introspection.
 
         Usage::
 
             @bot.command(aliases=["p"], slash=True, description="Health check")
             async def ping(ctx):
                 await ctx.reply("pong")
+
+        With typed slash options::
+
+            from banterapi import SlashOption, OPTION_INTEGER
+
+            @bot.command(
+                slash=True, description="Roll a die",
+                options=[SlashOption("sides", type=OPTION_INTEGER, required=False)],
+            )
+            async def roll(ctx, sides: int = 6):
+                await ctx.reply(f"🎲 {sides}")
         """
         def decorator(fn):
             cmd = Command(fn, name=name, aliases=aliases, help=help)
             self._commands.add(cmd)
             if slash:
-                self._slash_commands.append({
+                entry = {
                     "name": cmd.name,
                     "description": description or cmd.help or cmd.name,
-                })
+                }
+                if options:
+                    # Defer import to avoid a circular: commands.py is
+                    # loaded by client.py, and SlashOption lives there.
+                    from .commands import SlashOption as _SO
+                    entry["options"] = [
+                        (o.to_dict() if isinstance(o, _SO) else dict(o))
+                        for o in options
+                    ]
+                self._slash_commands.append(entry)
             return fn
         return decorator
 
-    def slash_command(self, name=None, description=""):
-        """Shortcut for :meth:`command` with ``slash=True``.
+    def slash_command(self, name=None, description="", options=None):
+        """Register a standalone slash command (no prefix twin).
+
+        The decorated function takes a single argument — an
+        :class:`~banterapi.interactions.Interaction` — and responds
+        via ``await interaction.respond(...)``. This differs from
+        :meth:`command` (prefix commands) which takes a
+        :class:`~banterapi.commands.Context` and parses args from
+        message text.
+
+        Use this when the command has structured typed args and makes
+        no sense as a plain-text prefix command, or when you want the
+        command only accessible through the UI autocomplete.
+
+        Args:
+            name: Slash command name. Defaults to the function name.
+            description: Shown in the autocomplete dropdown.
+            options: Iterable of :class:`~banterapi.SlashOption`.
+
+        Usage::
+
+            from banterapi import SlashOption, OPTION_STRING, OPTION_INTEGER
 
-        Use this when you want a command to exist *only* as a slash
-        command (no prefix invocation). The underlying registration is
-        identical; the command is still callable by its registered
-        name if a user types the prefix, but it won't appear in the
-        prefix-command listing by convention.
+            @bot.slash_command(
+                name="greet",
+                description="Greet a user with a custom message",
+                options=[
+                    SlashOption("name", type=OPTION_STRING),
+                    SlashOption("times", type=OPTION_INTEGER, required=False),
+                ],
+            )
+            async def greet(interaction):
+                n = interaction.options["name"]
+                k = interaction.options.get("times", 1)
+                await interaction.respond(f"Hello {n}! " * k)
         """
-        return self.command(name=name, help=description, slash=True, description=description)
+        def decorator(fn):
+            cmd_name = name or fn.__name__
+            entry = {
+                "name": cmd_name,
+                "description": description or cmd_name,
+            }
+            if options:
+                from .commands import SlashOption as _SO
+                entry["options"] = [
+                    (o.to_dict() if isinstance(o, _SO) else dict(o))
+                    for o in options
+                ]
+            self._slash_commands.append(entry)
+            self._slash_handlers[cmd_name] = fn
+            return fn
+        return decorator
 
     def _register_default_help(self):
         from .embed import Embed
@@ -335,6 +412,30 @@ class Bot:
             await self._fire("on_error", payload)
             return
 
+        if event_type == "interaction_create":
+            # Route slash-command invocations to their registered
+            # handlers. Falls back to a no-op (plus on_raw_event) if
+            # the command name isn't known — that shouldn't normally
+            # happen because the server filters by command ownership,
+            # but we don't want to crash the dispatch loop on drift.
+            from .interactions import Interaction
+            interaction = Interaction(payload, client=self)
+            handler = self._slash_handlers.get(interaction.command_name)
+            if handler is not None:
+                try:
+                    result = handler(interaction)
+                    if inspect.isawaitable(result):
+                        await result
+                except Exception:
+                    log.exception("slash handler %r raised", interaction.command_name)
+            else:
+                log.warning(
+                    "received interaction for unknown slash command %r",
+                    interaction.command_name,
+                )
+            await self._fire("on_interaction", interaction)
+            return
+
         await self._fire("on_raw_event", event_type, payload)
 
     async def _fire(self, name, *args):

{banterbotapi-0.2.2 → banterbotapi-0.2.3}/banterapi/commands.py

@@ -407,4 +407,107 @@ class CommandRegistry:
                 continue
             seen.add(cmd.name)
             out.append(cmd)
-        return out
+        return out
+
+
+# -----------------------------------------------------------------
+# Slash command option metadata
+# -----------------------------------------------------------------
+
+# Option type constants. Match the wire strings the server stores in
+# the `options` JSON column for each registered command. Keep these
+# as strings (not enums) so the JSON payload stays human-readable.
+OPTION_STRING = "string"
+OPTION_INTEGER = "integer"
+OPTION_BOOLEAN = "boolean"
+OPTION_USER = "user"
+OPTION_CHANNEL = "channel"
+OPTION_ROLE = "role"
+
+_VALID_OPTION_TYPES = {
+    OPTION_STRING, OPTION_INTEGER, OPTION_BOOLEAN,
+    OPTION_USER, OPTION_CHANNEL, OPTION_ROLE,
+}
+
+
+class SlashOption:
+    """One named argument to a slash command.
+
+    Registered as part of a slash command's options list. The server
+    stores the metadata so the client can render appropriate input
+    widgets (text box, number input, user picker, channel picker).
+    On invocation, option values are parsed server-side into the
+    declared type and delivered to the bot as typed fields on the
+    :class:`Interaction` context.
+
+    Attributes:
+        name: Option identifier (a-z, 0-9, underscore). Used both in
+            the UI and as the key in ``interaction.options[name]``.
+        type: One of the ``OPTION_*`` constants — string, integer,
+            boolean, user, channel, role.
+        description: Human-readable prompt shown under the option.
+        required: If True, the invocation UI blocks submission until
+            the value is set. Defaults to True — explicit optionals
+            are clearer than defaults-by-omission.
+        choices: Optional list of fixed choices. Each is either a
+            plain scalar (``["low", "medium", "high"]``) or a dict
+            ``{"name": "Medium", "value": "medium"}``. Frontend
+            renders as a dropdown when present.
+
+    Example::
+
+        @bot.slash_command(
+            name="kick",
+            description="Kick a member",
+            options=[
+                SlashOption("user", type=OPTION_USER, description="Who to kick"),
+                SlashOption("reason", type=OPTION_STRING, description="Why", required=False),
+            ],
+        )
+        async def kick(interaction):
+            target = interaction.options["user"]   # user ID (str)
+            reason = interaction.options.get("reason", "")
+            ...
+    """
+
+    __slots__ = ("name", "type", "description", "required", "choices")
+
+    def __init__(self, name, *, type=OPTION_STRING, description="", required=True, choices=None):
+        if type not in _VALID_OPTION_TYPES:
+            raise ValueError(
+                f"SlashOption {name!r}: unknown type {type!r}. "
+                f"Use one of: {', '.join(sorted(_VALID_OPTION_TYPES))}"
+            )
+        self.name = name
+        self.type = type
+        self.description = description
+        self.required = bool(required)
+        self.choices = list(choices) if choices else None
+
+    def to_dict(self):
+        """Serialize to the JSON shape the server stores and the
+        frontend consumes. Omits ``choices`` when unset to keep the
+        payload compact."""
+        d = {
+            "name": self.name,
+            "type": self.type,
+            "description": self.description,
+            "required": self.required,
+        }
+        if self.choices is not None:
+            # Allow bare scalars or {name, value} dicts — normalize to
+            # dicts so the frontend doesn't have to branch.
+            normalized = []
+            for c in self.choices:
+                if isinstance(c, dict) and "value" in c:
+                    normalized.append({"name": str(c.get("name", c["value"])), "value": c["value"]})
+                else:
+                    normalized.append({"name": str(c), "value": c})
+            d["choices"] = normalized
+        return d
+
+    def __repr__(self):
+        req = "required" if self.required else "optional"
+        return f"SlashOption({self.name!r}, type={self.type!r}, {req})"
+
+        

{banterbotapi-0.2.2 → banterbotapi-0.2.3}/banterapi/http.py

@@ -41,6 +41,24 @@ _MAX_ATTEMPTS = 2
 _DEFAULT_USER_AGENT = f"BanterPy/{__version__} (+https://banterchat.org)"
 
 
+def _parse_retry_after(raw):
+    """Parse an X-RateLimit-Reset-After header value into seconds.
+
+    Returns 1.0 (a conservative default) for missing, empty, or
+    non-numeric headers. Always returns a positive finite float so
+    callers can safely pass it to :func:`asyncio.sleep`.
+    """
+    if not raw:
+        return 1.0
+    try:
+        value = float(raw)
+    except (TypeError, ValueError):
+        return 1.0
+    if value != value or value <= 0:  # NaN or non-positive
+        return 1.0
+    return value
+
+
 class Route:
     """Describes one REST endpoint: method, path template, and params.
 
@@ -116,25 +134,7 @@ class HTTPClient:
         if self._session and not self._session.closed:
             await self._session.close()
 
-
-def _parse_retry_after(raw):
-    """Parse an X-RateLimit-Reset-After header value into seconds.
-
-    Returns 1.0 (a conservative default) for missing, empty, or
-    non-numeric headers. Always returns a positive finite float so
-    callers can safely pass it to :func:`asyncio.sleep`.
-    """
-    if not raw:
-        return 1.0
-    try:
-        value = float(raw)
-    except (TypeError, ValueError):
-        return 1.0
-    if value != value or value <= 0:  # NaN or non-positive
-        return 1.0
-    return value
-
-    async def request(self, route, json_body=None, params=None):
+    async def request(self, route, json_body=None, params=None, extra_headers=None):
         """Issue a REST call described by ``route`` and translate the response.
 
         Args:
@@ -143,6 +143,10 @@ def _parse_retry_after(raw):
             json_body: Object to serialise as the JSON request body,
                 or ``None`` for no body.
             params: Dict of query-string parameters, or ``None``.
+            extra_headers: Per-request headers merged on top of the
+                session defaults (the session already sets Authorization
+                and User-Agent). Used for one-off headers like
+                X-Interaction-Token that don't belong on every request.
 
         Returns:
             The parsed JSON response body (dict or list), or ``None``
@@ -159,7 +163,7 @@ def _parse_retry_after(raw):
         url = self.base_url + route.url
         method = route.method
         for attempt in range(_MAX_ATTEMPTS):
-            async with self._session.request(method, url, json=json_body, params=params) as resp:
+            async with self._session.request(method, url, json=json_body, params=params, headers=extra_headers) as resp:
                 if resp.status == HTTPStatus.NO_CONTENT:
                     return None
                 text = await resp.text()
@@ -509,6 +513,32 @@ def _parse_retry_after(raw):
             json_body={"commands": commands},
         )
 
+    async def respond_interaction(self, interaction_id, token, body):
+        """POST /interactions/{id}/respond — reply to a slash-command invocation.
+
+        Args:
+            interaction_id: The server-assigned ID from the incoming
+                ``interaction_create`` event.
+            token: The interaction token from the same event; sent as
+                ``X-Interaction-Token`` so the server can validate the
+                caller actually owns the interaction.
+            body: One of:
+                - ``{"kind": "reply",    "content": ..., "embed": ..., "ephemeral": bool}``
+                - ``{"kind": "defer",    "ephemeral": bool}``
+                - ``{"kind": "followup", "content": ..., "embed": ..., "ephemeral": bool}``
+
+        Called indirectly via :meth:`Interaction.respond` / ``defer`` /
+        ``followup`` — users shouldn't touch this directly.
+        """
+        # Token rides in a header so URL routing doesn't care about it
+        # and so logging / rate-limit keying sees only the interaction ID.
+        extra_headers = {"X-Interaction-Token": token}
+        return await self.request(
+            Route("POST", "/interactions/{interaction_id}/respond", interaction_id=interaction_id),
+            json_body=body,
+            extra_headers=extra_headers,
+        )
+
     async def list_commands(self):
         """GET /applications/@me/commands — current slash cmd set."""
         return await self.request(Route("GET", "/applications/@me/commands"))

banterbotapi-0.2.3/banterapi/interactions.py

@@ -0,0 +1,161 @@
+"""Slash-command interaction context.
+
+When a user invokes a slash command, the server emits an
+``interaction_create`` gateway event to the owning bot. The SDK wraps
+the payload in an :class:`Interaction` and dispatches it to the
+registered ``@bot.slash_command`` handler.
+
+Unlike prefix commands (which deliver a :class:`~banterapi.Message`
+via ``on_message``), slash commands deliver an :class:`Interaction`
+with pre-parsed, typed options and a response-correlation token.
+
+Handler usage::
+
+    @bot.slash_command(
+        name="roll",
+        description="Roll an N-sided die",
+        options=[SlashOption("sides", type=OPTION_INTEGER, required=False)],
+    )
+    async def roll(interaction):
+        sides = interaction.options.get("sides", 6)
+        await interaction.respond(f"🎲 {sides}-sided die")
+
+Responding to an interaction:
+
+* :meth:`Interaction.respond` — send the visible reply. The invocation
+  stays on screen as a header; this message lands below.
+* :meth:`Interaction.defer` — acknowledge that a response is coming
+  "soon" (within the interaction timeout, typically 15 minutes). Use
+  before long-running work so the UI can show a thinking state.
+* :meth:`Interaction.followup` — send additional messages after the
+  initial response. Can be called multiple times.
+
+The ``ephemeral`` flag makes a response visible only to the invoker.
+Follows Discord's semantics: ephemeral messages are dropped by
+clients that aren't the invoker, even though they transit the same
+gateway for everyone else.
+"""
+
+
+class Interaction:
+    """One slash-command invocation delivered to the bot.
+
+    Constructed by :class:`~banterapi.Bot._dispatch` when an
+    ``interaction_create`` event arrives. Do not instantiate manually.
+
+    Attributes:
+        id: Server-assigned interaction ID. Used to correlate the
+            bot's response back to this invocation.
+        token: Short-lived bearer token the server issued for this
+            interaction. Included on every follow-up call.
+        command_name: The slash command's registered name (without
+            the leading ``/``).
+        options: Dict of ``{option_name: parsed_value}``. Values are
+            typed per the option's declared type:
+              - string → str
+              - integer → int
+              - boolean → bool
+              - user, channel, role → the target ID as str
+        guild_id: Guild the interaction was invoked in, or ``""`` for
+            a DM.
+        channel_id: Channel ID it was invoked in.
+        user_id: Invoking user's ID.
+        _client: The :class:`Bot` that owns this interaction, kept for
+            routing responses. Never serialized.
+    """
+
+    __slots__ = (
+        "id", "token", "command_name", "options",
+        "guild_id", "channel_id", "user_id", "_client", "_responded",
+    )
+
+    def __init__(self, payload, client=None):
+        self.id = payload.get("id", "")
+        self.token = payload.get("token", "")
+        self.command_name = payload.get("command_name", "")
+        self.options = payload.get("options", {}) or {}
+        self.guild_id = payload.get("guild_id", "")
+        self.channel_id = payload.get("channel_id", "")
+        self.user_id = payload.get("user_id", "")
+        self._client = client
+        # Track whether we've sent the first response. Subsequent calls
+        # must go through followup() since the server distinguishes
+        # "initial response" from "follow-up" on the wire.
+        self._responded = False
+
+    async def respond(self, content="", *, embed=None, ephemeral=False):
+        """Send the visible reply to the invocation.
+
+        May only be called once per interaction. After this,
+        additional messages must go through :meth:`followup`.
+
+        Args:
+            content: Message text.
+            embed: Optional :class:`~banterapi.Embed`.
+            ephemeral: If True, only the invoking user sees this
+                message. Defaults to False (public).
+
+        Raises:
+            RuntimeError: If called more than once on the same
+                interaction — use :meth:`followup` for subsequent
+                messages.
+        """
+        if self._responded:
+            raise RuntimeError(
+                "respond() was already called on this interaction. "
+                "Use interaction.followup(...) for additional messages."
+            )
+        if self._client is None:
+            raise RuntimeError("Interaction has no attached client.")
+        body = {
+            "kind": "reply",
+            "content": content,
+            "ephemeral": bool(ephemeral),
+        }
+        if embed is not None:
+            body["embed"] = embed.to_dict() if hasattr(embed, "to_dict") else embed
+        await self._client._http.respond_interaction(self.id, self.token, body)
+        self._responded = True
+
+    async def defer(self, *, ephemeral=False):
+        """Acknowledge the interaction without replying yet.
+
+        Shows a thinking indicator in the client until :meth:`respond`
+        or :meth:`followup` lands. Use for handlers that may exceed
+        the client's immediate-response timeout (~3s). The ephemeral
+        flag here determines whether the eventual response will be
+        ephemeral too.
+        """
+        if self._responded:
+            raise RuntimeError("interaction already responded to")
+        if self._client is None:
+            raise RuntimeError("Interaction has no attached client.")
+        await self._client._http.respond_interaction(self.id, self.token, {
+            "kind": "defer",
+            "ephemeral": bool(ephemeral),
+        })
+        self._responded = True
+
+    async def followup(self, content="", *, embed=None, ephemeral=False):
+        """Send an additional message after the initial response.
+
+        Callable repeatedly. Unlike :meth:`respond` there's no
+        once-only limit — use for streaming progress updates, paginated
+        results, or multi-part replies.
+        """
+        if self._client is None:
+            raise RuntimeError("Interaction has no attached client.")
+        body = {
+            "kind": "followup",
+            "content": content,
+            "ephemeral": bool(ephemeral),
+        }
+        if embed is not None:
+            body["embed"] = embed.to_dict() if hasattr(embed, "to_dict") else embed
+        await self._client._http.respond_interaction(self.id, self.token, body)
+
+    def __repr__(self):
+        return (
+            f"Interaction(id={self.id!r}, command={self.command_name!r}, "
+            f"user={self.user_id!r}, channel={self.channel_id!r})"
+        )

{banterbotapi-0.2.2 → banterbotapi-0.2.3}/banterbotapi.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: banterbotapi
-Version: 0.2.2
+Version: 0.2.3
 Summary: Python SDK for building bots on Banter (banterchat.org) — discord.py-style.
 Author-email: Banter <contact@banterchat.org>
 License-Expression: MIT

{banterbotapi-0.2.2 → banterbotapi-0.2.3}/banterbotapi.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ banterapi/errors.py
 banterapi/gateway.py
 banterapi/http.py
 banterapi/intents.py
+banterapi/interactions.py
 banterapi/models.py
 banterapi/permissions.py
 banterbotapi.egg-info/PKG-INFO

{banterbotapi-0.2.2 → banterbotapi-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "banterbotapi"
-version = "0.2.2"
+version = "0.2.3"
 description = "Python SDK for building bots on Banter (banterchat.org) — discord.py-style."
 readme = "README.md"
 requires-python = ">=3.9"