fastapi-interactions 0.0.1__tar.gz → 0.1.1__tar.gz

{fastapi_interactions-0.0.1 → fastapi_interactions-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-interactions
-Version: 0.0.1
+Version: 0.1.1
 Summary: A lightweight framework for discord interactions over http built on FastAPI
 Author-email: Haider Ali <haideralidevnull@gmail.com>
 Requires-Python: >=3.13

{fastapi_interactions-0.0.1 → fastapi_interactions-0.1.1}/fastapi_interactions/__init__.py

@@ -1,3 +1,5 @@
+"""A lightweight Discord HTTP interactions framework built on FastAPI."""
+
 from .bot import Bot
 from .commands import CommandRouter, Option
 

{fastapi_interactions-0.0.1 → fastapi_interactions-0.1.1}/fastapi_interactions/bot.py

@@ -1,24 +1,40 @@
+"""The bot application: routing, command dispatch, and Discord API syncing.
+
+A :class:`Bot` wraps a FastAPI application, verifies Discord webhook signatures,
+routes interaction payloads to registered commands, and registers commands with
+Discord's API.
+"""
+
+import importlib
+import inspect
+import json
+import pkgutil
+import types
+from typing import Any
+
+import httpx
 from fastapi import FastAPI, Request
-from .middleware import VerifySignatureMiddleware
-from .responses import InteractionResponse, PongResponse, MessageResponse
+from fastapi.responses import JSONResponse
+from loguru import logger
+from pydantic import ValidationError
+from starlette.background import BackgroundTask
+
+from .commands import Command, CommandRouter
 from .context import Context
+from .middleware import VerifySignatureMiddleware
 from .models import (
-    InteractionType,
     ApplicationCommandData,
     Interaction,
+    InteractionType,
     Snowflake,
 )
-from typing import Any
-from .commands import Command
-from pydantic import ValidationError
-from .commands import CommandRouter
-import json
-import httpx
-import importlib
-import pkgutil
-from loguru import logger
-import inspect
-import types
+from .responses import (
+    DeferResponse,
+    InteractionResponse,
+    MessageResponse,
+    PongResponse,
+    _JSONResponse,
+)
 
 
 async def call_with_options(callback: callable, ctx: Context) -> Any:
@@ -60,6 +76,14 @@ async def call_with_options(callback: callable, ctx: Context) -> Any:
 
 
 class Bot:
+    """A Discord HTTP interactions bot built on FastAPI.
+
+    The bot exposes a single interactions endpoint (``/interactions`` by
+    default) and keeps commands in an internal registry. Use
+    :meth:`attach_router` or :meth:`load_extension` to register commands, then
+    sync them with Discord using :meth:`sync_commands`.
+    """
+
     def __init__(
         self,
         app_id: int,
@@ -94,7 +118,7 @@ class Bot:
         payload = json.loads(request.state.raw_body)
 
         if payload["type"] == InteractionType.PING:
-            return await PongResponse()
+            return _JSONResponse(PongResponse())
 
         if payload["type"] == InteractionType.APPLICATION_COMMAND:
             """Construct Context"""
@@ -103,9 +127,8 @@ class Bot:
                 application_command = ApplicationCommandData.model_validate(
                     interaction.data
                 )
-            except (ValidationError, Exception):
-                # print(e.errors())
-                return await MessageResponse("Unexpected error", ephemeral=True)
+            except (ValidationError, Exception) as e:
+                return _JSONResponse(MessageResponse("Unexpected error", ephemeral=True))
 
             context = Context(
                 interaction=interaction, options=application_command, http=self.http
@@ -115,7 +138,13 @@ class Bot:
                 command_name=application_command.name, ctx=context
             )
 
-        return await MessageResponse("Unsupported interaction received", ephemeral=True)
+        return _JSONResponse(MessageResponse("Unsupported interaction received", ephemeral=True))
+
+    async def add_error_handler(self, exc: Exception, func: callable):
+        pass
+
+    async def _handle_exception(self, request: Request, exc: Exception):
+        return _JSONResponse(MessageResponse(str(exc), ephemeral=True))
 
     def _register_routes(self) -> None:
         """Set up middleware and the interactions endpoint.
@@ -124,6 +153,7 @@ class Bot:
         for the interactions endpoint. Called during initialization.
         """
         self.app.add_middleware(VerifySignatureMiddleware, public_key=self.public_key)
+        self.app.add_exception_handler(Exception, self._handle_exception)
         self.app.add_api_route(
             self.interactions_path, endpoint=self.process_interactions, methods=["POST"]
         )
@@ -279,14 +309,24 @@ class Bot:
         """
         command = self.commands.get(command_name)
         if command is None:
-            return await MessageResponse("Unknown command", ephemeral=True)
+            return _JSONResponse(MessageResponse("Unknown command", ephemeral=True))
 
         result = await call_with_options(command.callback, ctx)
 
-        if not isinstance(result, InteractionResponse):
-            result = MessageResponse(str(result))
+        background = None
+        if isinstance(result, DeferResponse) and result.finish:
+            background = BackgroundTask(self._run_finish, result.finish, ctx=ctx)
+        if isinstance(result, str):
+            result = MessageResponse(result)
+
+        return _JSONResponse(result, background=background)
 
-        return await result
+    async def _run_finish(self, finish, ctx: Context) -> None:
+        try:
+            await finish()
+        except Exception as e:
+            logger.exception('Defer handler failed')
+            # await self._report_failure(ctx)
 
     def delete_all_commands(self, guild_id: Snowflake = None) -> None:
         """

{fastapi_interactions-0.0.1 → fastapi_interactions-0.1.1}/fastapi_interactions/commands.py

@@ -1,13 +1,28 @@
-from dataclasses import dataclass, field
-from .models import Snowflake, ApplicationCommandOptionType
-from typing import Optional
+"""Command registration, routing, and option decorators.
+
+Routers group commands and carry settings such as guild scope, integration
+types, and interaction contexts. The :class:`Option` decorators attach option
+metadata that is later bound to command callback parameters.
+"""
+
 import sys
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from .models import (
+    ApplicationCommandOptionType,
+    IntegrationType,
+    InteractionContext,
+    Snowflake,
+)
 
 OptionType = ApplicationCommandOptionType
 
 
 @dataclass
 class CommandOption:
+    """A single option declared on a command."""
+
     name: str
     description: str
     type: OptionType = OptionType.STRING
@@ -24,31 +39,86 @@ class CommandOption:
 
 @dataclass(slots=True)
 class CommandMeta:
+    """Registration metadata sent to Discord for a command.
+
+    ``integration_types`` and ``contexts`` control where the command can be
+    installed and invoked. They are only valid for globally scoped commands.
+    """
+
     name: str
     description: str
     options: list[CommandOption] = field(default_factory=list)
     type: int = 1
+    integration_types: IntegrationType | None = None
+    contexts: InteractionContext | None = None
 
     def as_payload(self):
-        return {
+        payload = {
             "name": self.name,
             "description": self.description,
             "type": self.type,
             "options": [option.as_payload() for option in self.options],
         }
+        if self.integration_types is not None:
+            payload["integration_types"] = self.integration_types.to_api()
+        if self.contexts is not None:
+            payload["contexts"] = self.contexts.to_api()
+        return payload
 
 
 @dataclass(slots=True)
 class Command:
+    """A command callback paired with its registration metadata."""
+
     callback: callable
     meta: CommandMeta
-    guild_id: Optional[Snowflake] = None
+    guild_id: Snowflake | None = None
 
 
 class CommandRouter:
-    def __init__(self, name: str = None, guild_id: Optional[Snowflake] = None):
+    """A collection of commands that can be attached to a bot.
+
+    Args:
+        name: Optional router name used in logs. Inferred from the caller's
+            module when omitted.
+        guild_id: Scope every command in the router to a single guild. Guild
+            scoped commands cannot set ``integration_types`` or ``contexts``.
+        integration_types: Where commands can be installed. Use
+            :class:`~fastapi_interactions.models.IntegrationType` flags.
+        contexts: Where commands can be invoked. Use
+            :class:`~fastapi_interactions.models.InteractionContext` flags.
+
+    Raises:
+        ValueError: If a guild-scoped router also sets ``integration_types`` or
+            ``contexts``, or if either flag value is empty.
+    """
+
+    def __init__(
+        self,
+        name: str | None = None,
+        guild_id: Snowflake | None = None,
+        *,
+        integration_types: IntegrationType | None = None,
+        contexts: InteractionContext | None = None,
+    ):
         self.name = name or self.__infer_name()
-        self.guild_id: Optional[Snowflake] = guild_id
+        self.guild_id = guild_id
+
+        if guild_id is not None and (
+            integration_types is not None or contexts is not None
+        ):
+            raise ValueError(
+                f"Router {self.name} is guild scoped. Cannt bind integration/interaction types"
+            )
+
+        if integration_types is not None and not integration_types:
+            raise ValueError("integration types cannot be empty;")
+
+        if contexts is not None and not contexts:
+            raise ValueError("contexts cannot be empty")
+
+        self.integration_types = integration_types
+        self.contexts = contexts
         self.commands: dict[str, Command] = {}
 
     def __infer_name(self) -> str:
@@ -86,6 +156,8 @@ class CommandRouter:
             )
             meta.name = name
             meta.description = description
+            meta.integration_types = self.integration_types
+            meta.contexts = self.contexts
             self.commands[name] = Command(
                 callback=func, meta=meta, guild_id=self.guild_id
             )
@@ -96,11 +168,20 @@ class CommandRouter:
 
 
 class Option:
+    """Decorators that attach typed options to command callbacks.
+
+    Each static method registers one Discord option type. Decorate the command
+    below ``@router.command(...)`` so the option metadata is collected before
+    the command is registered.
+    """
+
     @staticmethod
-    def __create_operation_decorator(name: str, description: str, option_type: OptionType, required: bool = True):
+    def __create_operation_decorator(
+        name: str, description: str, option_type: OptionType, required: bool = True
+    ):
         def decorator(func):
             meta = getattr(
-                func, '_command_meta', CommandMeta(name='', description='', type=1)
+                func, "_command_meta", CommandMeta(name="", description="", type=1)
             )
 
             meta.options.insert(
@@ -109,15 +190,16 @@ class Option:
                     name=name,
                     description=description,
                     type=option_type,
-                    required=required
-                )
+                    required=required,
+                ),
             )
             func._command_meta = meta
             return func
+
         return decorator
 
     @staticmethod
-    def string(name: str, description: str, required: bool = True):
+    def string(name: str, description: str, required: bool = True) -> Callable:
         """Register a string option on a command.
 
         Decorates a command callback to add a string option parameter. The option name
@@ -143,11 +225,11 @@ class Option:
             name=name,
             description=description,
             option_type=OptionType.STRING,
-            required=required
+            required=required,
         )
 
     @staticmethod
-    def integer(name: str, description: str, required: bool = True):
+    def integer(name: str, description: str, required: bool = True) -> Callable:
         """Register an integer option on a command.
 
         Decorates a command callback to add an integer option parameter. The option name
@@ -173,11 +255,11 @@ class Option:
             name=name,
             description=description,
             option_type=OptionType.INTEGER,
-            required=required
+            required=required,
         )
 
     @staticmethod
-    def user(name: str, description: str, required: bool = True):
+    def user(name: str, description: str, required: bool = True) -> Callable:
         """Register a user option on a command.
 
         Decorates a command callback to add a user option parameter. The option name
@@ -204,11 +286,11 @@ class Option:
             name=name,
             description=description,
             option_type=OptionType.USER,
-            required=required
+            required=required,
         )
 
     @staticmethod
-    def channel(name: str, description: str, required: bool = True):
+    def channel(name: str, description: str, required: bool = True) -> Callable:
         """Register a channel option on a command.
 
         Decorates a command callback to add a channel option parameter. The option name
@@ -235,11 +317,11 @@ class Option:
             name=name,
             description=description,
             option_type=OptionType.CHANNEL,
-            required=required
+            required=required,
         )
 
     @staticmethod
-    def role(name: str, description: str, required: bool = True):
+    def role(name: str, description: str, required: bool = True) -> Callable:
         """Register a role option on a command.
 
         Decorates a command callback to add a channel option parameter. The option name
@@ -266,11 +348,11 @@ class Option:
             name=name,
             description=description,
             option_type=OptionType.ROLE,
-            required=required
+            required=required,
         )
 
     @staticmethod
-    def mentionable(name: str, description: str, required: bool = True):
+    def mentionable(name: str, description: str, required: bool = True) -> Callable:
         """Register a mentionable option on a command.
 
         Decorates a command callback to add a channel option parameter. The option name
@@ -296,11 +378,11 @@ class Option:
             name=name,
             description=description,
             option_type=OptionType.MENTIONABLE,
-            required=required
+            required=required,
         )
 
     @staticmethod
-    def boolean(name: str, description: str, required: bool = True):
+    def boolean(name: str, description: str, required: bool = True) -> Callable:
         """Register a boolean option on a command.
 
         Decorates a command callback to add a boolean option parameter. The option name
@@ -331,11 +413,11 @@ class Option:
             name=name,
             description=description,
             option_type=OptionType.BOOLEAN,
-            required=required
+            required=required,
         )
 
     @staticmethod
-    def number(name: str, description: str, required: bool = True):
+    def number(name: str, description: str, required: bool = True) -> Callable:
         """Register a number option on a command.
 
         Decorates a command callback to add a number option parameter. The option name
@@ -362,5 +444,5 @@ class Option:
             name=name,
             description=description,
             option_type=OptionType.NUMBER,
-            required=required
-        )
+            required=required,
+        )

fastapi_interactions-0.1.1/fastapi_interactions/context.py

@@ -0,0 +1,83 @@
+"""The interaction context passed to command handlers.
+
+A :class:`Context` bundles the parsed interaction, the command's option values,
+and an async HTTP client for followup webhook requests.
+"""
+
+from dataclasses import dataclass
+from .models import Interaction, ApplicationCommandData, User, Snowflake
+from typing import Optional, Any
+import httpx
+from .responses import MessageResponse
+
+
+@dataclass
+class Context:
+    """State and helpers for a single interaction.
+
+    Attributes:
+        interaction: The parsed interaction payload from Discord.
+        options: The application command data, including supplied option values.
+        http: Async HTTP client used for followup webhook requests.
+    """
+
+    interaction: Interaction
+    options: ApplicationCommandData
+    http: httpx.AsyncClient
+
+    @property
+    def user(self) -> User:
+        """The user who invoked the interaction.
+
+        Guild interactions expose the user through ``member.user``; direct
+        message interactions expose it directly on the interaction.
+
+        Raises:
+            ValueError: If the payload contains neither ``user`` nor ``member.user``.
+        """
+        if self.interaction.user is not None:
+            return self.interaction.user
+        if (
+            self.interaction.member is not None
+            and self.interaction.member.user is not None
+        ):
+            return self.interaction.member.user
+        raise ValueError("Interaction does not contain `user` or `member.user`")
+
+    @property
+    def guild_id(self) -> Optional[Snowflake]:
+        """The guild ID where the interaction occurred, or ``None`` in DMs."""
+        return self.interaction.guild_id
+
+    @property
+    def channel_id(self) -> Optional[Snowflake]:
+        """The channel ID where the interaction occurred, if present."""
+        return self.interaction.channel_id
+
+    @property
+    def _webhook_base(self) -> str:
+        return f"https://discord.com/api/v10/webhooks/{self.interaction.application_id}/{self.interaction.token}"
+
+    async def send(self, content: str, ephemeral: bool = False) -> None:
+        """Send a followup message through the interaction webhook.
+
+        Args:
+            content: The message text to send.
+            ephemeral: Whether the message should only be visible to the
+                invoking user. Defaults to ``False``.
+        """
+        message = MessageResponse(content, ephemeral=ephemeral)
+        await self.http.post(url=self._webhook_base, json=message.to_payload())
+
+    def get_option_value(self, name: str, default: Any = None) -> Any:
+        """Return the value of a command option by name.
+
+        Args:
+            name: The option name to look up.
+            default: Value returned when the option was not supplied.
+
+        Returns:
+            The option value, or ``default`` when it is missing.
+        """
+        option = self.options.options_by_name.get(name)
+        return option.value if option is not None else default

{fastapi_interactions-0.0.1 → fastapi_interactions-0.1.1}/fastapi_interactions/middleware.py

@@ -1,3 +1,10 @@
+"""Middleware for verifying Discord webhook signatures.
+
+Discord signs every interaction request with Ed25519. The middleware validates
+the signature before the bot parses or acts on the payload, and stores the raw
+body on ``request.state.raw_body`` for handlers that need it.
+"""
+
 from fastapi import Request
 from fastapi.responses import JSONResponse
 from starlette.middleware.base import BaseHTTPMiddleware
@@ -8,6 +15,17 @@ from nacl.exceptions import BadSignatureError
 def verify_signature(
     public_key: str, signature: str, timestamp: str, body: bytes
 ) -> bool:
+    """Verify a Discord interaction signature.
+
+    Args:
+        public_key: The application's public key as a hex string.
+        signature: The ``x-signature-ed25519`` header value.
+        timestamp: The ``x-signature-timestamp`` header value.
+        body: The raw request body that was signed.
+
+    Returns:
+        ``True`` if the signature is valid, otherwise ``False``.
+    """
     try:
         VerifyKey(bytes.fromhex(public_key)).verify(
             timestamp.encode() + body, bytes.fromhex(signature)
@@ -18,6 +36,13 @@ def verify_signature(
 
 
 class VerifySignatureMiddleware(BaseHTTPMiddleware):
+    """Reject interaction requests whose Discord signature is invalid.
+
+    Requests to paths other than ``interaction_path`` pass through unchanged.
+    Valid interaction requests have their raw body stored on
+    ``request.state.raw_body`` for downstream handlers.
+    """
+
     def __init__(self, app, public_key: str, interaction_path: str = "/interactions"):
         super().__init__(app)
         self.public_key = public_key

fastapi_interactions-0.1.1/fastapi_interactions/models.py

@@ -0,0 +1,286 @@
+"""Enums and Pydantic models for Discord interaction payloads.
+
+This module mirrors the parts of Discord's interaction and application command
+objects that the framework needs. Enums use the same integer values Discord sends
+and expects, while Pydantic models parse incoming payloads with unknown fields
+ignored.
+"""
+
+from enum import IntEnum, IntFlag
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+Snowflake = str
+
+
+class _ApiFlag(IntFlag):
+    """Base class for flags that are serialized as Discord's integer lists.
+
+    Each flag value is a bit position rather than the API integer itself. For
+    example, the first flag in a subclass is ``1 << 0`` and is sent to Discord
+    as ``0``. Use :meth:`to_api` to convert a combination of flags into the
+    list of integers Discord expects.
+    """
+
+    def to_api(self) -> list[int]:
+        """Bit positions set in this flag, e.g. GUILD|PRIVATE_CHANNEL -> [0, 2]."""
+        return [i for i in range(self.bit_length()) if self & (1 << i)]
+
+
+class IntegrationType(_ApiFlag):
+    """Where a command can be installed and used.
+
+    Discord calls these *integration types*. Combine values with ``|`` when a
+    command should support more than one installation surface, or use
+    :attr:`ALL` as a shorthand. The selected flags are serialized to the
+    ``integration_types`` field when commands are registered.
+
+    Attributes:
+        GUILD_INSTALL: The command can be installed on a guild (API value ``0``).
+        USER_INSTALL: The command can be installed on a user account (API value ``1``).
+        ALL: Both guild and user installation (API values ``[0, 1]``).
+    """
+
+    GUILD_INSTALL = 1 << 0  # API VALUE 0
+    USER_INSTALL = 1 << 1  # API VALUE 1
+    ALL = GUILD_INSTALL | USER_INSTALL
+
+
+class InteractionContext(_ApiFlag):
+    """Where an application command can be invoked.
+
+    Combine values with ``|`` to allow a command in several places, or use
+    :attr:`ALL` as a shorthand. The selected flags are serialized to the
+    ``contexts`` field when commands are registered.
+
+    Attributes:
+        GUILD: Usable in guild channels (API value ``0``).
+        BOT_DM: Usable in direct messages with the bot (API value ``1``).
+        PRIVATE_CHANNEL: Usable in private channels such as group DMs (API value ``2``).
+        ALL: Usable in every supported context (API values ``[0, 1, 2]``).
+    """
+
+    GUILD = 1 << 0  # API VALUE 0
+    BOT_DM = 1 << 1  # API VALUE 1
+    PRIVATE_CHANNEL = 1 << 2  # VALUE VALUE 2
+    ALL = GUILD | BOT_DM | PRIVATE_CHANNEL
+
+
+class InteractionType(IntEnum):
+    """Type of interaction delivered to the bot's webhook endpoint.
+
+    Attributes:
+        PING: Discord's endpoint verification request.
+        APPLICATION_COMMAND: A slash command invocation.
+        MESSAGE_COMPONENT: A button or select menu interaction.
+        APPLICATION_COMMAND_AUTOCOMPLETE: An autocomplete request for a command option.
+        MODAL_SUBMIT: A submitted modal dialog.
+    """
+
+    PING = 1
+    APPLICATION_COMMAND = 2
+    MESSAGE_COMPONENT = 3
+    APPLICATION_COMMAND_AUTOCOMPLETE = 4
+    MODAL_SUBMIT = 5
+
+
+class CommandType(IntEnum):
+    """Type of application command registered with Discord.
+
+    Attributes:
+        CHAT_INPUT: A slash command (API value ``1``).
+        USER: A user context menu command (API value ``2``).
+        MESSAGE: A message context menu command (API value ``3``).
+        PRIMARY_ENTRY_POINT: The application's primary entry point command (API value ``4``).
+        CHAT: Alias for :attr:`CHAT_INPUT`.
+        ENTRY: Alias for :attr:`PRIMARY_ENTRY_POINT`.
+    """
+
+    CHAT_INPUT = 1
+    USER = 2
+    MESSAGE = 3
+    PRIMARY_ENTRY_POINT = 4
+
+    CHAT = 1
+    ENTRY = 4
+
+
+class InteractionCallbackType(IntEnum):
+    """Response type sent back to Discord for an interaction.
+
+    Attributes:
+        PONG: Acknowledge a PING interaction.
+        CHANNEL_MESSAGE_WITH_SOURCE: Send a message in the interaction's channel.
+        DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE: Acknowledge and send a message later.
+        DEFERRED_UPDATE_MESSAGE: Acknowledge a component interaction and update later.
+        UPDATE_MESSAGE: Update the message a component is attached to.
+        APPLICATION_COMMAND_AUTOCOMPLETE_RESULT: Return autocomplete choices.
+        MODAL: Open a modal dialog.
+        PREMIUM_REQUIRED: Tell the user a premium upgrade is required.
+        LAUNCH_ACTIVITY: Launch an embedded activity.
+        MESSAGE: Alias for :attr:`CHANNEL_MESSAGE_WITH_SOURCE`.
+        DEFER: Alias for :attr:`DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE`.
+        UPDATE: Alias for :attr:`UPDATE_MESSAGE`.
+        AUTOCOMPLETE: Alias for :attr:`APPLICATION_COMMAND_AUTOCOMPLETE_RESULT`.
+    """
+
+    PONG = 1
+    CHANNEL_MESSAGE_WITH_SOURCE = 4
+    DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE = 5
+    DEFERRED_UPDATE_MESSAGE = 6
+    UPDATE_MESSAGE = 7
+    APPLICATION_COMMAND_AUTOCOMPLETE_RESULT = 8
+    MODAL = 9
+    PREMIUM_REQUIRED = 10
+    LAUNCH_ACTIVITY = 12
+
+    MESSAGE = CHANNEL_MESSAGE_WITH_SOURCE
+    DEFER = DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE
+    UPDATE = UPDATE_MESSAGE
+    AUTOCOMPLETE = APPLICATION_COMMAND_AUTOCOMPLETE_RESULT
+
+
+class MessageFlags(IntFlag):
+    """Bit flags describing special message properties."""
+
+    CROSSPOSTED = 1 << 0
+    IS_CROSSPOST = 1 << 1
+    SUPPRESS_EMBEDS = 1 << 2
+    SOURCE_MESSAGE_DELETED = 1 << 3
+    URGENT = 1 << 4
+    HAS_THREAD = 1 << 5
+    EPHEMERAL = 1 << 6
+    LOADING = 1 << 7
+    FAILED_TO_MENTION_SOME_ROLES_IN_THREAD = 1 << 8
+
+    SUPPRESS_NOTIFICATIONS = 1 << 12
+    IS_VOICE_MESSAGE = 1 << 13
+    HAS_SNAPSHOT = 1 << 14
+    IS_COMPONENTS_V2 = 1 << 15
+
+
+class ApplicationCommandOptionType(IntEnum):
+    """Type of value accepted by an application command option.
+
+    Attributes:
+        SUB_COMMAND: A nested subcommand.
+        SUB_COMMAND_GROUP: A group of related subcommands.
+        STRING: A free-form string.
+        INTEGER: A whole number.
+        BOOLEAN: A true/false value.
+        USER: A Discord user.
+        CHANNEL: A Discord channel.
+        ROLE: A Discord role.
+        MENTIONABLE: A user or role mention.
+        NUMBER: A floating-point number.
+        ATTACHMENT: A file attachment.
+    """
+
+    SUB_COMMAND = 1
+    SUB_COMMAND_GROUP = 2
+    STRING = 3
+    INTEGER = 4
+    BOOLEAN = 5
+    USER = 6
+    CHANNEL = 7
+    ROLE = 8
+    MENTIONABLE = 9
+    NUMBER = 10
+    ATTACHMENT = 11
+
+
+class DiscordModel(BaseModel):
+    """Base model for Discord payload objects.
+
+    Unknown fields are ignored so payloads can gain new properties without
+    breaking existing bots.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+
+class User(DiscordModel):
+    """A Discord user."""
+
+    id: Snowflake
+    username: str
+    descriminator: Optional[str] = None
+    global_name: Optional[str] = None
+    avatar: Optional[str] = None
+    bot: Optional[bool] = None
+
+
+class Member(DiscordModel):
+    """A guild member and their guild-specific attributes."""
+
+    user: Optional[User] = None
+    nick: Optional[str] = None
+    roles: list[Snowflake] = Field(default_factory=list)
+    permissions: Optional[str] = None
+
+
+class ApplicationCommandInteractionOption(DiscordModel):
+    """A command option value supplied with an interaction.
+
+    Options may contain nested options for subcommands and subcommand groups.
+    """
+
+    name: str
+    type: ApplicationCommandOptionType
+    value: Optional[str | int | float | bool] = None
+    options: list["ApplicationCommandInteractionOption"] = Field(default_factory=list)
+    focused: Optional[bool] = None
+
+    @property
+    def options_by_name(self) -> dict[str, "ApplicationCommandInteractionOption"]:
+        return {opt.name for opt in self.options}
+
+    def get_option_value(self, name: str, default: Any = None) -> Any:
+        option = self.options_by_name.get(name)
+        return option.value if option is not None else default
+
+
+ApplicationCommandInteractionOption.model_rebuild()
+
+
+class ApplicationCommandData(DiscordModel):
+    """The command data attached to an application command interaction."""
+
+    id: Snowflake
+    name: str
+    type: CommandType
+    guild_id: Optional[Snowflake] = None
+    target_id: Optional[Snowflake] = None
+    options: list[ApplicationCommandInteractionOption] = Field(default_factory=list)
+
+    @property
+    def options_by_name(self) -> dict[str, "ApplicationCommandInteractionOption"]:
+        return {opt.name: opt for opt in self.options}
+
+    def get_option_value(self, name: str, default: Any = None) -> Any:
+        option = self.options_by_name.get(name)
+        return option.value if option is not None else default
+
+
+class Interaction(DiscordModel):
+    """An interaction payload received from Discord.
+
+    The framework validates the raw webhook body into this model before building
+    a :class:`fastapi_interactions.context.Context` for command handlers.
+    """
+
+    id: Snowflake
+    application_id: Snowflake
+    type: InteractionType
+    token: str
+    version: int
+
+    data: Optional[dict[str, Any]] = None
+
+    guild_id: Optional[Snowflake] = None
+    channel_id: Optional[Snowflake] = None
+    member: Optional[Member] = None
+    user: Optional[User] = None
+    locale: Optional[str] = None
+    guild_locale: Optional[str] = None

fastapi_interactions-0.1.1/fastapi_interactions/responses.py

@@ -0,0 +1,104 @@
+"""Interaction response objects returned by command handlers.
+
+Each response serializes itself into the callback payload Discord expects. The
+bot converts returned strings into :class:`MessageResponse` instances and wraps
+responses in a JSON HTTP response.
+"""
+
+import asyncio
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import InitVar, dataclass, field
+from typing import Any
+
+from fastapi.responses import JSONResponse
+
+from .models import (
+    InteractionCallbackType,
+    MessageFlags,
+)
+
+
+class _JSONResponse(JSONResponse):
+    """A JSON response that serializes :class:`InteractionResponse` objects."""
+
+    def render(self, content: Any) -> bytes:
+        if isinstance(content, InteractionResponse):
+            content = content.to_dict()
+        return super().render(content)
+
+
+class InteractionResponse(ABC):
+    """Base class for all interaction callback responses."""
+
+    @abstractmethod
+    def to_dict(self):
+        """Return the Discord callback payload for this response."""
+        pass
+
+    async def __call__(self) -> dict:
+        return self.to_dict()
+
+
+class PongResponse(InteractionResponse):
+    """Acknowledge a PING interaction.
+
+    The bot sends this automatically when Discord verifies the interactions
+    endpoint, so handlers normally never need to create it.
+    """
+
+    callback_type = InteractionCallbackType.PONG
+
+    def to_dict(self):
+        return {"type": self.callback_type}
+
+
+@dataclass(slots=True)
+class MessageResponse(InteractionResponse):
+    """Send a message in the interaction's channel.
+
+    Args:
+        content: The message text.
+        ephemeral: Whether only the invoking user can see the message.
+            Defaults to ``False``.
+    """
+
+    callback_type = InteractionCallbackType.MESSAGE
+    content: str
+    ephemeral: InitVar[bool] = False
+    flags: MessageFlags = field(init=False)
+
+    def __post_init__(self, ephemeral: bool):
+        self.flags = MessageFlags.EPHEMERAL if ephemeral else MessageFlags(0)
+
+    def to_payload(self):
+        return {"content": self.content, "flags": int(self.flags)}
+
+    def to_dict(self):
+        return {"type": self.callback_type, "data": self.to_payload()}
+
+
+@dataclass(slots=True)
+class DeferResponse(InteractionResponse):
+    """Acknowledge an interaction now and deliver the real response later.
+
+    The bot sends the defer acknowledgement before running ``finish`` as a
+    background task. Use :meth:`fastapi_interactions.context.Context.send`
+    inside ``finish`` to deliver followup messages.
+
+    Args:
+        ephemeral: Whether followup messages should be ephemeral. Defaults to
+            ``False``.
+        finish: Optional callback run in the background after the defer is sent.
+    """
+
+    callback_type = InteractionCallbackType.DEFER
+    ephemeral: InitVar[bool] = False
+    finish: Callable | None = field(default=None, repr=None, compare=None)
+    flags: MessageFlags = field(init=False)
+
+    def __post_init__(self, ephemeral: bool):
+        self.flags = MessageFlags.EPHEMERAL if ephemeral else MessageFlags(0)
+
+    def to_dict(self):
+        return {"type": self.callback_type, "data": {"flags": int(self.flags)}}

{fastapi_interactions-0.0.1 → fastapi_interactions-0.1.1}/fastapi_interactions.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-interactions
-Version: 0.0.1
+Version: 0.1.1
 Summary: A lightweight framework for discord interactions over http built on FastAPI
 Author-email: Haider Ali <haideralidevnull@gmail.com>
 Requires-Python: >=3.13

{fastapi_interactions-0.0.1 → fastapi_interactions-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = 'setuptools.build_meta'
 
 [project]
 name = 'fastapi-interactions'
-version = '0.0.1'
+version = '0.1.1'
 description='A lightweight framework for discord interactions over http built on FastAPI'
 readme = "README.md"
 requires-python = ">=3.13"
@@ -28,4 +28,4 @@ docs = [
 
 [tool.setuptools.packages.find]
 include = ['fastapi_interactions*']
-exclude = ['docs*', 'exts*', 'tests*']
+exclude = ['docs*', 'exts*', 'tests*']

fastapi_interactions-0.0.1/fastapi_interactions/context.py

@@ -1,43 +0,0 @@
-from dataclasses import dataclass
-from .models import Interaction, ApplicationCommandData, User, Snowflake
-from typing import Optional, Any
-import httpx
-from .responses import MessageResponse
-
-
-@dataclass
-class Context:
-    interaction: Interaction
-    options: ApplicationCommandData
-    http: httpx.AsyncClient
-
-    @property
-    def user(self) -> User:
-        if self.interaction.user is not None:
-            return self.interaction.user
-        if (
-            self.interaction.member is not None
-            and self.interaction.member.user is not None
-        ):
-            return self.interaction.member.user
-        raise ValueError("Interaction does not contain `user` or `member.user`")
-
-    @property
-    def guild_id(self) -> Optional[Snowflake]:
-        return self.interaction.guild_id
-
-    @property
-    def channel_id(self) -> Optional[Snowflake]:
-        return self.interaction.channel_id
-
-    @property
-    def _webhook_base(self) -> str:
-        return f"https://discord.com/api/v10/webhooks/{self.interaction.application_id}/{self.interaction.token}"
-
-    async def send(self, content: str, ephemeral: bool = False) -> None:
-        message = MessageResponse(content, ephemeral=ephemeral)
-        await self.http.post(url=self._webhook_base, json=message.to_payload())
-
-    def get_option_value(self, name: str, default: Any = None) -> Any:
-        option = self.options.options_by_name.get(name)
-        return option.value if option is not None else default

fastapi_interactions-0.0.1/fastapi_interactions/models.py

@@ -1,146 +0,0 @@
-from pydantic import BaseModel, ConfigDict, Field
-from typing import Optional, Any
-from enum import IntEnum, IntFlag
-
-Snowflake = str
-
-
-class InteractionType(IntEnum):
-    PING = 1
-    APPLICATION_COMMAND = 2
-    MESSAGE_COMPONENT = 3
-    APPLICATION_COMMAND_AUTOCOMPLETE = 4
-    MODAL_SUBMIT = 5
-
-
-class CommandType(IntEnum):
-    CHAT_INPUT = 1
-    USER = 2
-    MESSAGE = 3
-    PRIMARY_ENTRY_POINT = 4
-
-    CHAT = 1
-    ENTRY = 4
-
-
-class InteractionCallbackType(IntEnum):
-    PONG = 1
-    CHANNEL_MESSAGE_WITH_SOURCE = 4
-    DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE = 5
-    DEFERRED_UPDATE_MESSAGE = 6
-    UPDATE_MESSAGE = 7
-    APPLICATION_COMMAND_AUTOCOMPLETE_RESULT = 8
-    MODAL = 9
-    PREMIUM_REQUIRED = 10
-    LAUNCH_ACTIVITY = 12
-
-    MESSAGE = CHANNEL_MESSAGE_WITH_SOURCE
-    DEFER = DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE
-    UPDATE = UPDATE_MESSAGE
-    AUTOCOMPLETE = APPLICATION_COMMAND_AUTOCOMPLETE_RESULT
-
-
-class MessageFlags(IntFlag):
-    """Bit flags describing special message properties."""
-
-    CROSSPOSTED = 1 << 0
-    IS_CROSSPOST = 1 << 1
-    SUPPRESS_EMBEDS = 1 << 2
-    SOURCE_MESSAGE_DELETED = 1 << 3
-    URGENT = 1 << 4
-    HAS_THREAD = 1 << 5
-    EPHEMERAL = 1 << 6
-    LOADING = 1 << 7
-    FAILED_TO_MENTION_SOME_ROLES_IN_THREAD = 1 << 8
-
-    SUPPRESS_NOTIFICATIONS = 1 << 12
-    IS_VOICE_MESSAGE = 1 << 13
-    HAS_SNAPSHOT = 1 << 14
-    IS_COMPONENTS_V2 = 1 << 15
-
-
-class ApplicationCommandOptionType(IntEnum):
-    SUB_COMMAND = 1
-    SUB_COMMAND_GROUP = 2
-    STRING = 3
-    INTEGER = 4
-    BOOLEAN = 5
-    USER = 6
-    CHANNEL = 7
-    ROLE = 8
-    MENTIONABLE = 9
-    NUMBER = 10
-    ATTACHMENT = 11
-
-
-class DiscordModel(BaseModel):
-    model_config = ConfigDict(extra="ignore")
-
-
-class User(DiscordModel):
-    id: Snowflake
-    username: str
-    descriminator: Optional[str] = None
-    global_name: Optional[str] = None
-    avatar: Optional[str] = None
-    bot: Optional[bool] = None
-
-
-class Member(DiscordModel):
-    user: Optional[User] = None
-    nick: Optional[str] = None
-    roles: list[Snowflake] = Field(default_factory=list)
-    permissions: Optional[str] = None
-
-
-class ApplicationCommandInteractionOption(DiscordModel):
-    name: str
-    type: ApplicationCommandOptionType
-    value: Optional[str | int | float | bool] = None
-    options: list["ApplicationCommandInteractionOption"] = Field(default_factory=list)
-    focused: Optional[bool] = None
-
-    @property
-    def options_by_name(self) -> dict[str, "ApplicationCommandInteractionOption"]:
-        return {opt.name for opt in self.options}
-
-    def get_option_value(self, name: str, default: Any = None) -> Any:
-        option = self.options_by_name.get(name)
-        return option.value if option is not None else default
-
-
-ApplicationCommandInteractionOption.model_rebuild()
-
-
-class ApplicationCommandData(DiscordModel):
-    id: Snowflake
-    name: str
-    type: CommandType
-    guild_id: Optional[Snowflake] = None
-    target_id: Optional[Snowflake] = None
-    options: list[ApplicationCommandInteractionOption] = Field(default_factory=list)
-
-    @property
-    def options_by_name(self) -> dict[str, "ApplicationCommandInteractionOption"]:
-        return {opt.name: opt for opt in self.options}
-
-    def get_option_value(self, name: str, default: Any = None) -> Any:
-        option = self.options_by_name.get(name)
-        return option.value if option is not None else default
-
-
-class Interaction(DiscordModel):
-    id: Snowflake
-    application_id: Snowflake
-    type: InteractionType
-    token: str
-    version: int
-
-    data: Optional[dict[str, Any]] = None
-
-    guild_id: Optional[Snowflake] = None
-    channel_id: Optional[Snowflake] = None
-    member: Optional[Member] = None
-    user: Optional[User] = None
-    locale: Optional[str] = None
-    guild_locale: Optional[str] = None

fastapi_interactions-0.0.1/fastapi_interactions/responses.py

@@ -1,61 +0,0 @@
-from dataclasses import dataclass
-from abc import ABC, abstractmethod
-from .models import (
-    InteractionCallbackType,
-    MessageFlags,
-)
-import asyncio
-
-
-class InteractionResponse(ABC):
-
-    @abstractmethod
-    def to_dict(self):
-        pass
-
-    async def __call__(self) -> dict:
-        return self.to_dict()
-
-    def __await__(self):
-        return self.__call__().__await__()
-
-
-class PongResponse(InteractionResponse):
-    callback_type = InteractionCallbackType.PONG
-
-    def to_dict(self):
-        return {"type": self.callback_type}
-
-
-@dataclass(slots=True)
-class MessageResponse(InteractionResponse):
-    callback_type = InteractionCallbackType.MESSAGE
-    content: str
-    ephemeral: bool = False
-
-    def __init__(self, content: str, ephemeral: bool = False):
-        self.content = content
-        self.flags = MessageFlags.EPHEMERAL if ephemeral else MessageFlags(0)
-
-    def to_payload(self):
-        return {"content": self.content, "flags": int(self.flags)}
-
-    def to_dict(self):
-        return {"type": self.callback_type, "data": self.to_payload()}
-
-
-@dataclass(slots=True)
-class DeferResponse(InteractionResponse):
-    callback_type = InteractionCallbackType.DEFER
-
-    def __init__(self, ephemeral: bool = False, finish: callable = None):
-        self.flags = MessageFlags.EPHEMERAL if ephemeral else MessageFlags(0)
-        self.finish = finish
-
-    def to_dict(self):
-        return {"type": self.callback_type, "data": {"flags": int(self.flags)}}
-
-    async def __call__(self):
-        if self.finish:
-            asyncio.create_task(self.finish())
-        return self.to_dict()