fastapi-interactions 0.0.1__tar.gz

fastapi_interactions-0.0.1/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: fastapi-interactions
+Version: 0.0.1
+Summary: A lightweight framework for discord interactions over http built on FastAPI
+Author-email: Haider Ali <haideralidevnull@gmail.com>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi[standard]>=0.138.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pynacl>=1.6.2
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: loguru>=0.7.3
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+
+<a href='https://fastapi-interactions.readthedocs.io/en/latest/' target='_blank'>Read the docs here</a>
+
+# Install fastapi-interactions
+
+```
+pip install fastapi-interactions
+```
+
+# Quick example
+
+```python
+from fastapi_interactions import Bot
+from fastapi_interactions.commands import (
+    CommandRouter, option,
+)
+
+bot = Bot(app_id='DISCORD_APP_ID',
+          public_key='DISCORD_PUBLIC_KEY',
+          bot_token='DISCORD_BOT_TOKEN')
+
+router = CommandRouter()
+
+
+@router.command('helloworld', 'say hello')
+async def hello(ctx):
+    return 'hello'
+
+
+@router.command('echo', 'echo a phrase back')
+@option('text', 'the text to repeat')
+async def echo(ctx, text: str):
+    return text
+
+bot.attach_router(router)
+
+bot.sync_commands()  # Use only on build time if running on vercel
+app = bot.app
+
+```
+---
+
+> [!WARNING]
+> ### SYNCING COMMANDS
+> If you are on a serverless architecture like Vercel, make sure you only call `bot.sync_commands` during build time. You do not want this being executed every time you receive an interaction in production.
+
+---

fastapi_interactions-0.0.1/README.md

@@ -0,0 +1,46 @@
+<a href='https://fastapi-interactions.readthedocs.io/en/latest/' target='_blank'>Read the docs here</a>
+
+# Install fastapi-interactions
+
+```
+pip install fastapi-interactions
+```
+
+# Quick example
+
+```python
+from fastapi_interactions import Bot
+from fastapi_interactions.commands import (
+    CommandRouter, option,
+)
+
+bot = Bot(app_id='DISCORD_APP_ID',
+          public_key='DISCORD_PUBLIC_KEY',
+          bot_token='DISCORD_BOT_TOKEN')
+
+router = CommandRouter()
+
+
+@router.command('helloworld', 'say hello')
+async def hello(ctx):
+    return 'hello'
+
+
+@router.command('echo', 'echo a phrase back')
+@option('text', 'the text to repeat')
+async def echo(ctx, text: str):
+    return text
+
+bot.attach_router(router)
+
+bot.sync_commands()  # Use only on build time if running on vercel
+app = bot.app
+
+```
+---
+
+> [!WARNING]
+> ### SYNCING COMMANDS
+> If you are on a serverless architecture like Vercel, make sure you only call `bot.sync_commands` during build time. You do not want this being executed every time you receive an interaction in production.
+
+---

fastapi_interactions-0.0.1/fastapi_interactions/__init__.py

@@ -0,0 +1,4 @@
+from .bot import Bot
+from .commands import CommandRouter, Option
+
+__all__ = ["Bot", "CommandRouter", "Option"]

fastapi_interactions-0.0.1/fastapi_interactions/bot.py

@@ -0,0 +1,314 @@
+from fastapi import FastAPI, Request
+from .middleware import VerifySignatureMiddleware
+from .responses import InteractionResponse, PongResponse, MessageResponse
+from .context import Context
+from .models import (
+    InteractionType,
+    ApplicationCommandData,
+    Interaction,
+    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
+
+
+async def call_with_options(callback: callable, ctx: Context) -> Any:
+    """Invoke a command callback with option values bound to parameters.
+
+    Inspects the callback's signature and matches each parameter name to a registered
+    option in the interaction context. Values are passed as keyword arguments to the
+    callback. Parameters with default values are optional; missing required parameters
+    raise an error.
+
+    Args:
+        callback: The async command function to invoke.
+        ctx: The interaction context containing option values.
+
+    Returns:
+        The awaited result of the callback invocation.
+
+    Raises:
+        TypeError: If a required parameter has no matching option value in the context.
+    """
+    sig = inspect.signature(callback)
+    kwargs = {}
+
+    params = list(sig.parameters.values())[1:]
+    for param in params:
+        value = ctx.get_option_value(param.name)
+
+        if value is not None:
+            kwargs[param.name] = value
+        elif param.default is not inspect.Parameter.empty:
+            kwargs[param.name] = param.default
+        else:
+            raise TypeError(
+                f"Command {callback.__name__!r} has required parameter "
+                f"{param.name!r} but no matching option was provided"
+            )
+
+    return await callback(ctx, **kwargs)
+
+
+class Bot:
+    def __init__(
+        self,
+        app_id: int,
+        public_key: str,
+        bot_token: str,
+        interactions_path: str = "/interactions",
+    ):
+        """Initialize a new Discord HTTP webhook bot.
+
+        Args:
+            app_id (int): The Discord Application ID.
+            public_key (str): Public key used to validate incoming webhook signatures
+                from Discord.
+            bot_token (str): Bot token used for authenticated API calls to Discord
+                (command registration, message sending, etc.).
+            interactions_path (str, optional): The route path where the bot listens
+                for interaction webhooks. Defaults to "/interactions".
+        """
+        self.app_id: int = app_id
+        self.public_key: str = public_key
+        self.bot_token: str = bot_token
+        self.interactions_path: str = interactions_path
+        self.base_url: str = f"https://discord.com/api/v10/applications/{app_id}"
+        self.commands: dict[str, Command] = {}
+
+        self.http = httpx.AsyncClient()
+
+        self.app = FastAPI(openapi_url=None)
+        self._register_routes()
+
+    async def process_interactions(self, request: Request):
+        payload = json.loads(request.state.raw_body)
+
+        if payload["type"] == InteractionType.PING:
+            return await PongResponse()
+
+        if payload["type"] == InteractionType.APPLICATION_COMMAND:
+            """Construct Context"""
+            try:
+                interaction = Interaction.model_validate(payload)
+                application_command = ApplicationCommandData.model_validate(
+                    interaction.data
+                )
+            except (ValidationError, Exception):
+                # print(e.errors())
+                return await MessageResponse("Unexpected error", ephemeral=True)
+
+            context = Context(
+                interaction=interaction, options=application_command, http=self.http
+            )
+
+            return await self.dispatch(
+                command_name=application_command.name, ctx=context
+            )
+
+        return await MessageResponse("Unsupported interaction received", ephemeral=True)
+
+    def _register_routes(self) -> None:
+        """Set up middleware and the interactions endpoint.
+
+        Registers the signature verification middleware and configures the route handler
+        for the interactions endpoint. Called during initialization.
+        """
+        self.app.add_middleware(VerifySignatureMiddleware, public_key=self.public_key)
+        self.app.add_api_route(
+            self.interactions_path, endpoint=self.process_interactions, methods=["POST"]
+        )
+
+    def attach_router(self, router: CommandRouter) -> None:
+        """Attach a CommandRouter to the bot.
+
+        Registers a CommandRouter with this Discord webhook bot, enabling it to
+        handle slash commands, message components, modals, and other interactions
+        defined within the router.
+
+        Args:
+            router (CommandRouter): The router instance containing command
+                registrations and handler mappings.
+
+        Raises:
+            TypeError: If the provided router is not an instance of CommandRouter.
+        """
+        if not isinstance(router, CommandRouter):
+            raise TypeError(f"Expected a CommandRouter, got {type(router).__name__!r}")
+        self.commands.update(router.commands)
+        logger.info(
+            f"Router {router.name!r} attached with {len(router)} commands - {str(router)}"
+        )
+
+    def __load_routers_from_module(self, module: types.ModuleType) -> None:
+        """Discover and register routers from a module.
+
+        Checks for an explicit __routers__ list first. If not found, scans the module
+        for all CommandRouter instances and registers them automatically.
+
+        Args:
+            module: The module to scan for routers.
+
+        """
+        routers = getattr(module, "__routers__", None)
+
+        if routers is None:
+            routers = [
+                obj for obj in vars(module).values() if isinstance(obj, CommandRouter)
+            ]
+
+        if not routers:
+            logger.warning(f"No routers configured in {module.__name__!r}")
+            return
+
+        logger.debug(f"{len(routers)} routers discovered in {module.__name__!r}")
+        for router in routers:
+            self.attach_router(router)
+
+    def load_extension(self, path: str) -> None:
+        """Load extension(s) from a module or package.
+
+        Dynamically imports the given Python path and registers all `CommandRouter`
+        instances by calling the internal `__load_routers_from_module` method.
+
+        Behavior:
+            - If `path` points to a **module**: Loads routers from that single module.
+            - If `path` points to a **package**: Recursively discovers and loads
+              all non-package modules within it (and its subpackages).
+
+        Args:
+            path (str): Dot-separated import path to a module or package.
+
+        Raises:
+            ModuleNotFoundError: If the module or package does not exist.
+            ImportError: If an error occurs while importing any module.
+
+        Examples:
+            Load a single module:
+            ```python
+            bot.load_extension("my_bot.extensions.moderation")
+            ```
+            Load all modules from a package(recursive):
+            ```python
+            bot.load_extension('my_bot.extensions')
+            ```
+        """
+        module = importlib.import_module(path)
+        if hasattr(module, "__path__"):
+            # This is a package, lets recurisvely find modules
+            logger.info(f"Scanning packages {path!r} for extensions")
+            walked_packages = pkgutil.walk_packages(
+                module.__path__, module.__name__ + "."
+            )
+            for _, module_name, is_package in walked_packages:
+                if not is_package:
+                    imported = importlib.import_module(module_name)
+                    self.__load_routers_from_module(imported)
+        else:
+            self.__load_routers_from_module(module)
+
+    def sync_commands(self) -> None:
+        """Sync all registered commands with Discord's API.
+
+        Sends a bulk overwrite of the bot's slash commands using the Discord
+        Application Commands endpoint.
+
+        Raises:
+            Exception: If the API request fails.
+        """
+        global_payloads = []
+        guild_payloads: dict[int, list] = {}
+
+        for command in self.commands.values():
+            if command.guild_id is not None:
+                guild_payloads.setdefault(command.guild_id, []).append(
+                    command.meta.as_payload()
+                )
+            else:
+                global_payloads.append(command.meta.as_payload())
+
+        if global_payloads:
+            self.__put__commands(f"{self.base_url}/commands", global_payloads)
+
+        for guild_id, payload in guild_payloads.items():
+            self.__put__commands(f"{self.base_url}/guilds/{guild_id}/commands", payload)
+
+    def __put__commands(self, url: str, payload: list) -> None:
+        """Send a batch of commands to Discord's API.
+
+        Makes a PUT request to the specified Discord endpoint with the command payload.
+        Handles both global and guild-scoped command registration.
+
+        Args:
+            url: The Discord API endpoint (global or guild-scoped).
+            payload: List of command definitions to register.
+
+        Raises:
+            Exception: If the HTTP response status is not 200.
+        """
+        headers = {"Authorization": f"Bot {self.bot_token}"}
+        with httpx.Client() as client:
+            response = client.put(url, headers=headers, json=payload)
+        if response.status_code != 200:
+            raise Exception(
+                {"error": "registering commands failed", "data": response.json()}
+            )
+        logger.info(f"Synced {len(payload)} commands to {url!r}")
+
+    async def dispatch(self, command_name: str, ctx: Context) -> InteractionResponse:
+        """Invoke a command and return its response.
+
+        Looks up the command by name and invokes its callback with the provided context.
+        Option values are automatically bound to the callback's parameters.
+
+        Args:
+            command_name (str): The name of the command to invoke.
+            ctx (Context): The interaction context.
+
+        Returns:
+            An InteractionResponse instance
+        """
+        command = self.commands.get(command_name)
+        if command is None:
+            return await MessageResponse("Unknown command", ephemeral=True)
+
+        result = await call_with_options(command.callback, ctx)
+
+        if not isinstance(result, InteractionResponse):
+            result = MessageResponse(str(result))
+
+        return await result
+
+    def delete_all_commands(self, guild_id: Snowflake = None) -> None:
+        """
+        Delete all application commands by replacing the command set with an empty list.
+
+        This performs a bulk overwrite operation. If ``guild_id`` is not
+        provided, all global commands are deleted. Otherwise, all commands
+        registered for the specified guild are deleted.
+
+        Parameters
+        ----------
+        guild_id : Snowflake, optional
+            The guild ID to target. If ``None``, the global command scope
+            is used.
+
+        Returns
+        -------
+        None
+        """
+        if not guild_id:
+            url = f"{self.base_url}/commands"
+        else:
+            url = f"{self.base_url}/guilds/{guild_id}/commands"
+
+        self.__put__commands(url, [])

fastapi_interactions-0.0.1/fastapi_interactions/commands.py

@@ -0,0 +1,366 @@
+from dataclasses import dataclass, field
+from .models import Snowflake, ApplicationCommandOptionType
+from typing import Optional
+import sys
+
+OptionType = ApplicationCommandOptionType
+
+
+@dataclass
+class CommandOption:
+    name: str
+    description: str
+    type: OptionType = OptionType.STRING
+    required: bool = True
+
+    def as_payload(self):
+        return {
+            "name": self.name,
+            "description": self.description,
+            "type": self.type,
+            "required": self.required,
+        }
+
+
+@dataclass(slots=True)
+class CommandMeta:
+    name: str
+    description: str
+    options: list[CommandOption] = field(default_factory=list)
+    type: int = 1
+
+    def as_payload(self):
+        return {
+            "name": self.name,
+            "description": self.description,
+            "type": self.type,
+            "options": [option.as_payload() for option in self.options],
+        }
+
+
+@dataclass(slots=True)
+class Command:
+    callback: callable
+    meta: CommandMeta
+    guild_id: Optional[Snowflake] = None
+
+
+class CommandRouter:
+    def __init__(self, name: str = None, guild_id: Optional[Snowflake] = None):
+        self.name = name or self.__infer_name()
+        self.guild_id: Optional[Snowflake] = guild_id
+        self.commands: dict[str, Command] = {}
+
+    def __infer_name(self) -> str:
+        frame = sys._getframe(2)
+        return frame.f_globals.get("__name__", "Unknown")
+
+    def __len__(self) -> int:
+        return len(list(self.commands.keys()))
+
+    def __str__(self) -> str:
+        return f"{list(self.commands.keys())}"
+
+    def command(self, name: str, description: str) -> None:
+        """
+        Add a slash command to this router.
+
+        The decorated function is registered as the handler for the command
+        and will be included when the router is attached to the application.
+
+        Args:
+            name: Unique command name.
+            description: User-facing command description.
+
+        Example:
+            ```python
+            @router.command("hello", "Say hello")
+            async def hello(ctx):
+                return "Hello!"
+            ```
+        """
+
+        def decorator(func):
+            meta = getattr(
+                func, "_command_meta", CommandMeta(name="", description="", type=1)
+            )
+            meta.name = name
+            meta.description = description
+            self.commands[name] = Command(
+                callback=func, meta=meta, guild_id=self.guild_id
+            )
+            func.__dict__.pop("_command_meta", None)
+            return func
+
+        return decorator
+
+
+class Option:
+    @staticmethod
+    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)
+            )
+
+            meta.options.insert(
+                0,
+                CommandOption(
+                    name=name,
+                    description=description,
+                    type=option_type,
+                    required=required
+                )
+            )
+            func._command_meta = meta
+            return func
+        return decorator
+
+    @staticmethod
+    def string(name: str, description: str, required: bool = True):
+        """Register a string option on a command.
+
+        Decorates a command callback to add a string option parameter. The option name
+        must match a parameter name in the callback for automatic value binding.
+
+        Args:
+            name: The option name. Must match a callback parameter name.
+            description: Human-readable description shown to Discord users.
+            required: Whether the option is required. Defaults to True.
+
+        Returns:
+            A decorator that attaches the option metadata to the function.
+
+        Example:
+        ```python
+        @router.command(name="echo", description="Echo text")
+        @Option.string(name="text", description="Text to echo", required=True)
+        async def echo(ctx, text: str):
+            return text
+        ```
+        """
+        return Option.__create_operation_decorator(
+            name=name,
+            description=description,
+            option_type=OptionType.STRING,
+            required=required
+        )
+
+    @staticmethod
+    def integer(name: str, description: str, required: bool = True):
+        """Register an integer option on a command.
+
+        Decorates a command callback to add an integer option parameter. The option name
+        must match a parameter name in the callback for automatic value binding.
+
+        Args:
+            name: The option name. Must match a callback parameter name.
+            description: Human-readable description shown to Discord users.
+            required: Whether the option is required. Defaults to True.
+
+        Returns:
+            A decorator that attaches the option metadata to the function.
+
+        Example:
+        ```python
+        @router.command(name="echo", description="Echo integer")
+        @Option.integer(name="number", description="Integer to echo", required=True)
+        async def echo(ctx, number: int):
+            return int
+        ```
+        """
+        return Option.__create_operation_decorator(
+            name=name,
+            description=description,
+            option_type=OptionType.INTEGER,
+            required=required
+        )
+
+    @staticmethod
+    def user(name: str, description: str, required: bool = True):
+        """Register a user option on a command.
+
+        Decorates a command callback to add a user option parameter. The option name
+        must match a parameter name in the callback for automatic value binding.
+
+        Args:
+            name: The option name. Must match a callback parameter name.
+            description: Human-readable description shown to Discord users.
+            required: Whether the option is required. Defaults to True.
+
+        Returns:
+            A decorator that attaches the option metadata to the function.
+
+        Example:
+        ```python
+        @router.command(name="kick", description="Kick a user")
+        @Option.user(name="user", description="Target user to kick", required=True)
+        async def kick(ctx, user: Snowflake):
+            ...
+            return 'User kicked'
+        ```
+        """
+        return Option.__create_operation_decorator(
+            name=name,
+            description=description,
+            option_type=OptionType.USER,
+            required=required
+        )
+
+    @staticmethod
+    def channel(name: str, description: str, required: bool = True):
+        """Register a channel option on a command.
+
+        Decorates a command callback to add a channel option parameter. The option name
+        must match a parameter name in the callback for automatic value binding.
+
+        Args:
+            name: The option name. Must match a callback parameter name.
+            description: Human-readable description shown to Discord users.
+            required: Whether the option is required. Defaults to True.
+
+        Returns:
+            A decorator that attaches the option metadata to the function.
+
+        Example:
+        ```python
+        @router.command(name="purge", description="Purge a channel")
+        @Option.user(name="channel", description="Target channel to purge", required=True)
+        async def purge(ctx, channel: Snowflake):
+            ...
+            return 'Channel purged'
+        ```
+        """
+        return Option.__create_operation_decorator(
+            name=name,
+            description=description,
+            option_type=OptionType.CHANNEL,
+            required=required
+        )
+
+    @staticmethod
+    def role(name: str, description: str, required: bool = True):
+        """Register a role option on a command.
+
+        Decorates a command callback to add a channel option parameter. The option name
+        must match a parameter name in the callback for automatic value binding.
+
+        Args:
+            name: The option name. Must match a callback parameter name.
+            description: Human-readable description shown to Discord users.
+            required: Whether the option is required. Defaults to True.
+
+        Returns:
+            A decorator that attaches the option metadata to the function.
+
+        Example:
+        ```python
+        @router.command(name="rmrole", description="Delete a role")
+        @Option.role(name="role", description="role to delete", required=True)
+        async def purge(ctx, role: Snowflake):
+            ...
+            return 'Role purged'
+        ```
+        """
+        return Option.__create_operation_decorator(
+            name=name,
+            description=description,
+            option_type=OptionType.ROLE,
+            required=required
+        )
+
+    @staticmethod
+    def mentionable(name: str, description: str, required: bool = True):
+        """Register a mentionable option on a command.
+
+        Decorates a command callback to add a channel option parameter. The option name
+        must match a parameter name in the callback for automatic value binding.
+
+        Args:
+            name: The option name. Must match a callback parameter name.
+            description: Human-readable description shown to Discord users.
+            required: Whether the option is required. Defaults to True.
+
+        Returns:
+            A decorator that attaches the option metadata to the function.
+
+        Example:
+        ```python
+        @router.command(name="warn", description="Warn a user or role")
+        @Option.mentionable(name="target", description="User or role to warn", required=True)
+        async def warn(ctx, target: Snowflake):
+            return f"⚠️ Warning issued to <@&{target}>"
+        ```
+        """
+        return Option.__create_operation_decorator(
+            name=name,
+            description=description,
+            option_type=OptionType.MENTIONABLE,
+            required=required
+        )
+
+    @staticmethod
+    def boolean(name: str, description: str, required: bool = True):
+        """Register a boolean option on a command.
+
+        Decorates a command callback to add a boolean option parameter. The option name
+        must match a parameter name in the callback for automatic value binding.
+
+        Args:
+            name: The option name. Must match a callback parameter name.
+            description: Human-readable description shown to Discord users.
+            required: Whether the option is required. Defaults to True.
+
+        Returns:
+            A decorator that attaches the option metadata to the function.
+
+        Example:
+        ```python
+        @router.command(name="ban", description="Ban a user")
+        @Option.user(name="target", description="User to ban", required=True)
+        @Option.boolean(name="soft", description="Is this a softban", required=True)
+        async def warn(ctx, target: Snowflake, soft: bool):
+            if soft:
+                ...
+            else:
+                ...
+            return 'Command executed'
+        ```
+        """
+        return Option.__create_operation_decorator(
+            name=name,
+            description=description,
+            option_type=OptionType.BOOLEAN,
+            required=required
+        )
+
+    @staticmethod
+    def number(name: str, description: str, required: bool = True):
+        """Register a number option on a command.
+
+        Decorates a command callback to add a number option parameter. The option name
+        must match a parameter name in the callback for automatic value binding.
+        This is a float in python.
+
+        Args:
+            name: The option name. Must match a callback parameter name.
+            description: Human-readable description shown to Discord users.
+            required: Whether the option is required. Defaults to True.
+
+        Returns:
+            A decorator that attaches the option metadata to the function.
+
+        Example:
+        ```python
+        @router.command(name="rate", description="Rate something")
+        @Option.number(name="score", description="Rating from 0 to 10", required=True)
+        async def rate(ctx, score: float):
+            return f"Rating: {score}/10 ⭐"
+        ```
+        """
+        return Option.__create_operation_decorator(
+            name=name,
+            description=description,
+            option_type=OptionType.NUMBER,
+            required=required
+        )

fastapi_interactions-0.0.1/fastapi_interactions/context.py

@@ -0,0 +1,43 @@
+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/middleware.py

@@ -0,0 +1,46 @@
+from fastapi import Request
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+from nacl.signing import VerifyKey
+from nacl.exceptions import BadSignatureError
+
+
+def verify_signature(
+    public_key: str, signature: str, timestamp: str, body: bytes
+) -> bool:
+    try:
+        VerifyKey(bytes.fromhex(public_key)).verify(
+            timestamp.encode() + body, bytes.fromhex(signature)
+        )
+        return True
+    except (BadSignatureError, ValueError):
+        return False
+
+
+class VerifySignatureMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, public_key: str, interaction_path: str = "/interactions"):
+        super().__init__(app)
+        self.public_key = public_key
+        self.interaction_path = interaction_path
+
+    async def dispatch(self, request: Request, call_next):
+        if request.url.path != self.interaction_path:
+            return await call_next(request)
+
+        signature = request.headers["x-signature-ed25519"]
+        timestamp = request.headers["x-signature-timestamp"]
+        if not signature or not timestamp:
+            return JSONResponse({"detail": "Missing headers"}, status_code=401)
+
+        body = await request.body()
+        verified_signature = verify_signature(
+            public_key=self.public_key,
+            signature=signature,
+            timestamp=timestamp,
+            body=body,
+        )
+        if not verified_signature:
+            return JSONResponse({"detail": "Invalid signature"}, status_code=401)
+        else:
+            request.state.raw_body = body
+            return await call_next(request)

fastapi_interactions-0.0.1/fastapi_interactions/models.py

@@ -0,0 +1,146 @@
+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

@@ -0,0 +1,61 @@
+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()

fastapi_interactions-0.0.1/fastapi_interactions.egg-info/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: fastapi-interactions
+Version: 0.0.1
+Summary: A lightweight framework for discord interactions over http built on FastAPI
+Author-email: Haider Ali <haideralidevnull@gmail.com>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi[standard]>=0.138.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pynacl>=1.6.2
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: loguru>=0.7.3
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+
+<a href='https://fastapi-interactions.readthedocs.io/en/latest/' target='_blank'>Read the docs here</a>
+
+# Install fastapi-interactions
+
+```
+pip install fastapi-interactions
+```
+
+# Quick example
+
+```python
+from fastapi_interactions import Bot
+from fastapi_interactions.commands import (
+    CommandRouter, option,
+)
+
+bot = Bot(app_id='DISCORD_APP_ID',
+          public_key='DISCORD_PUBLIC_KEY',
+          bot_token='DISCORD_BOT_TOKEN')
+
+router = CommandRouter()
+
+
+@router.command('helloworld', 'say hello')
+async def hello(ctx):
+    return 'hello'
+
+
+@router.command('echo', 'echo a phrase back')
+@option('text', 'the text to repeat')
+async def echo(ctx, text: str):
+    return text
+
+bot.attach_router(router)
+
+bot.sync_commands()  # Use only on build time if running on vercel
+app = bot.app
+
+```
+---
+
+> [!WARNING]
+> ### SYNCING COMMANDS
+> If you are on a serverless architecture like Vercel, make sure you only call `bot.sync_commands` during build time. You do not want this being executed every time you receive an interaction in production.
+
+---

fastapi_interactions-0.0.1/fastapi_interactions.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+fastapi_interactions/__init__.py
+fastapi_interactions/bot.py
+fastapi_interactions/commands.py
+fastapi_interactions/context.py
+fastapi_interactions/middleware.py
+fastapi_interactions/models.py
+fastapi_interactions/responses.py
+fastapi_interactions.egg-info/PKG-INFO
+fastapi_interactions.egg-info/SOURCES.txt
+fastapi_interactions.egg-info/dependency_links.txt
+fastapi_interactions.egg-info/requires.txt
+fastapi_interactions.egg-info/top_level.txt

fastapi_interactions-0.0.1/fastapi_interactions.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fastapi_interactions-0.0.1/fastapi_interactions.egg-info/requires.txt

@@ -0,0 +1,10 @@
+fastapi[standard]>=0.138.0
+pydantic>=2.13.4
+pynacl>=1.6.2
+httpx>=0.28.1
+loguru>=0.7.3
+
+[docs]
+mkdocs
+mkdocstrings[python]
+mkdocs-material

fastapi_interactions-0.0.1/fastapi_interactions.egg-info/top_level.txt

@@ -0,0 +1 @@
+fastapi_interactions

fastapi_interactions-0.0.1/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ['setuptools>=82.0.1']
+build-backend = 'setuptools.build_meta'
+
+[project]
+name = 'fastapi-interactions'
+version = '0.0.1'
+description='A lightweight framework for discord interactions over http built on FastAPI'
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    'fastapi[standard]>=0.138.0',
+    'pydantic>=2.13.4',
+    'pynacl>=1.6.2',
+    'httpx>=0.28.1',
+    'loguru>=0.7.3'
+]
+authors = [
+    { name = "Haider Ali", email = "haideralidevnull@gmail.com" }
+]
+
+[project.optional-dependencies]
+docs = [
+    "mkdocs",
+    "mkdocstrings[python]",
+    "mkdocs-material"
+]
+
+[tool.setuptools.packages.find]
+include = ['fastapi_interactions*']
+exclude = ['docs*', 'exts*', 'tests*']

fastapi_interactions-0.0.1/setup.cfg

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