✨ feat: Decode application ID from token during server initialization

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

.github/workflows/publish.yaml

@@ -3,21 +3,21 @@ name: Quality Checks
 on:
   workflow_call:
 
-
 jobs:
   publish:
+    name: Publish to PyPI
     runs-on: ubuntu-latest
     environment: pypi
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: "Install uv"
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v6
         with:
           enable-cache: true
 
       - name: "Set up Python"
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version-file: "pyproject.toml"
 

.github/workflows/quality.yaml

@@ -3,15 +3,15 @@ name: Quality Checks
 on:
   workflow_call:
 
-
 jobs:
   check-license-header:
+    name: License Header Check
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
       - name: Setup Copywrite
-        uses: hashicorp/setup-copywrite@5e3e8a26d7b9f8a508848ad0a069dfd2f7aa5339
+        uses: hashicorp/setup-copywrite@32f9f1c86f661b8a51100768976a06f1b281a035
       - name: Check Header Compliance
         run: copywrite headers --plan --config .copywrite.hcl
 
@@ -24,26 +24,26 @@ jobs:
         include:
           - check: format
             name: "Format Check"
-            command: "uv run ruff format --check src"
+            command: "uv run ruff format --check ."
           - check: lint
             name: "Lint Check"
-            command: "uv run ruff check src"
+            command: "uv run ruff check ."
           - check: basedpyright
             name: "Type Check"
-            command: "uv run basedpyright src"
+            command: "uv run basedpyright ."
 
     name: ${{ matrix.name }}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: "Install uv"
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v6
         with:
           enable-cache: true
 
       - name: "Set up Python"
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version-file: "pyproject.toml"
 

.gitignore

@@ -85,7 +85,7 @@ ipython_config.py
 # pyenv
 #   For a library or package, you might want to ignore these files since the code is
 #   intended to run in multiple environments; otherwise, check them in:
-# .python-version
+.python-version
 
 # pipenv
 #   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
@@ -165,11 +165,9 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
 
 # PyPI configuration file
 .pypirc
 
-.python-version
-.idea
 _version.py

.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+# Copyright (c) NiceBots
+# SPDX-License-Identifier: MIT
+
+ci:
+  autoupdate_commit_msg: ":construction_worker: pre-commit autoupdate"
+  autofix_commit_msg: ":art: auto fixes from pre-commit.com hooks"
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: \.(po|pot|yml|yaml)$
+      - id: end-of-file-fixer
+        exclude: \.(po|pot|yml|yaml)$
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+        args: [--prose-wrap=always, --print-width=88]
+        exclude: \.(po|pot|yml|yaml)$
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.11.11
+    hooks:
+      # Run the linter.
+      - id: ruff
+        args: [ --fix ]
+      # Run the formatter.
+      - id: ruff-format
+  - repo: https://github.com/bhundven/copywrite # waiting for https://github.com/hashicorp/copywrite/pull/120 to be merged
+    rev: 937f17f09c46992447dfa8977bb96eda512588c4
+    hooks:
+      - id: add-headers

README.md

@@ -1,14 +1,63 @@
-# Pycord REST
+<div align="center">
+  <h1>Pycord REST</h1>
 
-A lightweight wrapper for Discord's HTTP interactions using py-cord and FastAPI. This library enables you to build Discord bots that work exclusively through Discord's HTTP interactions, without requiring a WebSocket gateway connection.
+<!-- badges -->
 
-## About
+[![PyPI - Version](https://img.shields.io/pypi/v/pycord-rest-bot)](https://pypi.org/project/pycord-rest-bot/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pycord-rest-bot)](https://pypi.org/project/pycord-rest-bot/)
+[![PyPI - Types](https://img.shields.io/pypi/types/pycord-rest-bot)](https://pypi.org/project/pycord-rest-bot/)
+[![PyPI - License](https://img.shields.io/pypi/l/pycord-rest-bot)](https://pypi.org/project/pycord-rest-bot/)
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Paillat-dev/pycord-rest/CI.yaml)](https://github.com/Paillat-dev/pycord-rest/actions/workflows/CI.yaml)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/Paillat-dev/pycord-rest/main.svg)](https://results.pre-commit.ci/latest/github/Paillat-dev/pycord-rest/main)
 
-Pycord REST allows you to build Discord bots that respond to interactions via HTTP endpoints as described in [Discord's interaction documentation](https://discord.com/developers/docs/interactions/receiving-and-responding) and [interaction overview](https://discord.com/developers/docs/interactions/overview#preparing-for-interactions).
+<!-- end badges -->
 
-This project is built on:
-- **FastAPI** - For handling the HTTP server
-- **py-cord** - Leveraging Discord command builders and interaction handling
+<!-- short description -->
+
+A lightweight wrapper for Discord's HTTP interactions and webhook events using py-cord
+and FastAPI.
+
+<!-- end short description -->
+
+</div>
+
+<!-- toc -->
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+  - [How It Works](#how-it-works)
+  - [Discord Application Setup](#discord-application-setup)
+- [Features](#features)
+  - [Interaction Handling](#interaction-handling)
+  - [Webhook Events](#webhook-events)
+  - [Type Safety](#type-safety)
+- [Usage Examples](#usage-examples)
+  - [Basic Commands](#basic-commands)
+  - [Event Handling](#event-handling)
+  - [Custom Routes](#custom-routes)
+- [Configuration](#configuration)
+- [Limitations](#limitations)
+- [Getting Help](#getting-help)
+- [Development](#development)
+  - [Local Testing](#local-testing)
+  - [Contributing](#contributing)
+- [License](#license)
+
+## Overview
+
+Pycord REST enables you to build Discord applications that respond to:
+
+- **Interactions** via HTTP endpoints (slash commands, components, modals)
+- **Webhook events** such as application authorization and entitlements
+
+Built on:
+
+- **FastAPI** - For handling HTTP requests
+- **py-cord** - For Discord command builders and interaction handling
 - **uvicorn** - ASGI server implementation
 
 ## Installation
@@ -17,13 +66,15 @@ This project is built on:
 pip install pycord-rest-bot
 ```
 
+<!-- quick-start -->
+
 ## Quick Start
 
 ```python
 from pycord_rest import App
 import discord
 
-app = App(intents=discord.Intents.default())
+app = App()
 
 @app.slash_command(name="ping", description="Responds with pong!")
 async def ping(ctx):
@@ -40,25 +91,77 @@ if __name__ == "__main__":
     )
 ```
 
-## Usage
+## Core Concepts
 
-### Setting up your bot on Discord
+### How It Works
 
-1. Create a bot on the [Discord Developer Portal](https://discord.com/developers/applications)
-2. Enable the "Interactions Endpoint URL" for your application 
-3. Set the URL to your public endpoint where your bot will receive interactions
-4. Copy your public key from the Developer Portal to verify signatures
+Pycord REST creates an HTTP server that:
 
-### Features
+1. Listens for Discord interaction requests and webhook events
+2. Verifies request signatures using your application's public key
+3. Routes events to appropriate handlers
+4. Returns responses back to Discord
 
-- Slash Commands
-- UI Components (buttons, select menus)
-- Modal interactions
-- Autocomplete for commands
+Unlike traditional WebSocket-based Discord bots, HTTP-based applications:
 
-### Similarities to py-cord
+- Only wake up when receiving interactions or webhook events
+- Don't maintain a persistent connection to Discord's gateway
+- Don't receive most real-time Discord events
 
-Syntax is equivalent to py-cord, as it is what is being used under the hood, making it easy to adapt existing bots:
+### Discord Application Setup
+
+1. Create an application on the
+   [Discord Developer Portal](https://discord.com/developers/applications)
+2. Copy your public key to verify signatures
+3. Run the Pycord REST app
+4. Configure the endpoints:
+
+- **Interactions Endpoint URL** - For slash commands and component interactions
+  (`https://example.com`)
+- **Webhook URL** - For receiving application events (e.g.,
+  `https://example.com/webhook`)
+
+<!-- prettier-ignore -->
+> [!IMPORTANT]
+> Don't forget to run your FastAPI server **before** setting up the application on Discord, or else Discord won't be able to verify the endpoints.
+
+## Features
+
+### Interaction Handling
+
+Respond to Discord interactions such as:
+
+- **Slash Commands** - Create and respond to application commands
+- **UI Components** - Buttons, select menus, and other interactive elements
+- **Modal Forms** - Pop-up forms for gathering user input
+- **Autocomplete** - Dynamic option suggestions as users type
+
+### Webhook Events
+
+Handle Discord webhook events such as:
+
+- **Application authorization** - When your app is added to a guild or authorized by a
+  user
+- **Entitlement creation** - When a user subscribes to your app's premium features
+
+### Type Safety
+
+Pycord REST is fully type-annotated and type-safe. It uses `basedpyright` for type
+checking.
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> While Pycord REST itself is fully typed, the underlying py-cord library has limited type annotations, which may affect type checking in some areas.
+
+## Usage Examples
+
+<!-- prettier-ignore -->
+> [!TIP]
+> For complete examples, check out the [examples directory](/examples).
+
+### Basic Commands
+
+Commands use the familiar py-cord syntax:
 
 ```python
 @app.slash_command(name="hello", description="Say hello")
@@ -73,39 +176,28 @@ async def button(ctx):
     await ctx.respond("Press the button!", view=view)
 ```
 
-## Limitations
+### Event Handling
 
-This library works differently than traditional bots because it does not use Discord's WebSocket gateway:
+The possible events are:
 
-- **No Cache**: Since there's no gateway connection, there's no cache of guilds, channels, users, etc.
-- **Limited API Methods**: Many standard py-cord methods that rely on cache won't work properly:
-  - `app.get_channel()`, `app.get_guild()`, `app.get_user()`, etc.
-  - Presence updates
-  - Voice support
-  - Member tracking
-- **Event-Based Functions**: Only interaction-based events work; message events, etc. don't work
+- `on_application_authorized` - When your app is added to a guild or authorized by a
+  user
+- `on_entitlement_create` - When a user subscribes to your app's premium features
 
-Remember that this is an HTTP-only bot that responds exclusively to interactions triggered by users.
-
-## Configuration Options
+<!-- prettier-ignore -->
+> [!NOTE]
+> For application installation events, use `on_application_authorized` instead of `on_guild_join`.
 
 ```python
-app.run(
-    token="YOUR_BOT_TOKEN",
-    public_key="YOUR_PUBLIC_KEY",
-    uvicorn_options={
-        "host": "0.0.0.0",
-        "port": 8000,
-        "log_level": "info",
-        # Any valid uvicorn server options
-    },
-    health=True  # Enable /health endpoint
-)
+@app.listen("on_application_authorized")
+async def on_application_authorized(event: ApplicationAuthorizedEvent):
+    # Triggers when app is added to a guild OR when a user authorizes your app
+    print(f"Authorization received: Guild={event.guild}, User={event.user}")
 ```
 
-## Advanced Usage
+### Custom Routes
 
-### Adding Custom FastAPI Routes
+Add your own FastAPI routes:
 
 ```python
 from fastapi import Request
@@ -115,25 +207,95 @@ async def custom_endpoint(request: Request):
     return {"message": "This is a custom endpoint"}
 ```
 
-## Contributing
+## Configuration
 
-Contributions are welcome! This project is in early development, so there might be bugs or unexpected behaviors.
+```python
+app.run(
+    token="YOUR_BOT_TOKEN",
+    public_key="YOUR_PUBLIC_KEY",
+    uvicorn_options={
+        "host": "0.0.0.0",  # Listen on all network interfaces
+        "port": 8000,        # Port to listen on
+        "log_level": "info", # Uvicorn logging level
+    },
+    health=True  # Enable /health endpoint for monitoring
+)
+```
+
+### Integration Options
+
+1. **Stand-alone HTTP Interaction Bot** - Commands and components only
+2. **Webhook Event Handler Only** - Process application events alongside a separate
+   gateway bot
+3. **Full HTTP Application** - Handle both interactions and webhook events
+
+## Limitations
+
+Since Pycord REST doesn't use Discord's WebSocket gateway:
+
+- **No Cache** - No local storage of guilds, channels, or users
+- **Limited API Methods** - Functions that rely on cache won't work:
+  - `app.get_channel()`, `app.get_guild()`, `app.get_user()`
+  - Presence updates
+  - Voice support
+  - Member tracking
+- **Limited Events** - Only interaction-based and webhook events work
+
+## Getting Help
+
+If you encounter issues or have questions about pycord-rest:
+
+- **GitHub Issues**:
+  [Submit a bug report or feature request](https://github.com/Paillat-dev/pycord-rest/issues)
+- **Discord Support**:
+  - For py-cord related questions: Join the
+    [Pycord Official Server](https://discord.gg/pycord)
+  - For pycord-rest specific help: Join the
+    [Pycord Official Server](https://discord.gg/pycord) and mention `@paillat`
+
+<!-- prettier-ignore -->
+> [!TIP]
+> Before asking for help, check if your question is already answered in the [examples directory](/examples) or existing GitHub issues.
+
+## Development
+
+### Local Testing
+
+Use tunneling tools to expose your local development server:
+
+- **ngrok**:
+
+  ```bash
+  # Install ngrok
+  npm install -g ngrok
+
+  # Expose your local server
+  ngrok http 8000
+  ```
+
+- **Cloudflare Tunnel** or **localtunnel** - Alternative tunneling options
+
+These tools provide temporary URLs for testing without deploying to production.
+
+### Contributing
 
 1. Fork the repository
 2. Create a feature branch
 3. Make your changes
-4. Run tests and linting: `ruff check` and `ruff format`
+4. Run linter, formatter and type checker: `ruff check .`,`ruff format .`,
+   `basedpyright .`
 5. Submit a pull request
 
-### Development Tools
+**Development Tools**:
 
+- **uv**: For dependency management
 - **Ruff**: For linting and formatting
 - **HashiCorp Copywrite**: For managing license headers
 - **basedpyright**: For type checking
 
-## Disclaimer
-
-This is an early-stage project and may have unexpected behaviors or bugs. Please report any issues you encounter.
+<!-- prettier-ignore -->
+> [!NOTE]
+> This is an early-stage project and may have unexpected behaviors or bugs. Please report any issues you encounter.
 
 ## License
 
@@ -141,4 +303,4 @@ MIT License - Copyright (c) 2025 Paillat-dev
 
 ---
 
-Made with ❤️ by Paillat-dev
+Made with ❤ by Paillat-dev

examples/basic_bot.py

@@ -0,0 +1,48 @@
+# Copyright (c) Paillat-dev
+# SPDX-License-Identifier: MIT
+
+"""Basic Discord bot example using Pycord REST.
+
+This is a minimal example showing how to create slash commands.
+"""
+
+import os
+
+import discord
+from dotenv import load_dotenv
+
+from pycord_rest import App
+
+# Load environment variables from .env file
+load_dotenv()
+
+app = App()
+
+
+# Simple ping command
+@app.slash_command(name="ping", description="Responds with pong!")
+async def ping(ctx: discord.ApplicationContext) -> None:
+    await ctx.respond("Pong!")
+
+
+# Command with parameters
+@app.slash_command(name="greet", description="Greets a user")
+@discord.option("name", input_type=str, description="The name of the user to greet", required=False)
+async def greet(ctx: discord.ApplicationContext, name: str | None = None) -> None:
+    if name:
+        await ctx.respond(f"Hello, {name}!")
+    else:
+        await ctx.respond(f"Hello, {ctx.author.display_name}!")
+
+
+# Run the app
+if __name__ == "__main__":
+    app.run(
+        token=os.environ["DISCORD_TOKEN"],
+        public_key=os.environ["DISCORD_PUBLIC_KEY"],
+        uvicorn_options={
+            "host": "0.0.0.0",  # noqa: S104
+            "port": 8000,
+            "log_level": "info",
+        },
+    )

examples/button_example.py

@@ -0,0 +1,55 @@
+# Copyright (c) Paillat-dev
+# SPDX-License-Identifier: MIT
+
+"""Example demonstrating how to use buttons with Pycord REST."""
+
+import os
+from typing import Any
+
+import discord
+from dotenv import load_dotenv
+
+from pycord_rest import App
+
+# Load environment variables from .env file
+load_dotenv()
+
+app = App()
+
+
+class MyView(discord.ui.View):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.add_item(
+            discord.ui.Button(  # pyright: ignore[reportUnknownArgumentType]
+                style=discord.ButtonStyle.link, label="GitHub", url="https://github.com/Paillat-dev/pycord-rest"
+            )
+        )
+
+    @discord.ui.button(label="Green", style=discord.ButtonStyle.success)
+    async def green_button(self, button: "discord.ui.Button[MyView]", interaction: discord.Interaction) -> None:
+        await interaction.respond("You clicked the green button!", ephemeral=True)
+
+    @discord.ui.button(label="Red", style=discord.ButtonStyle.danger)
+    async def red_button(self, button: "discord.ui.Button[MyView]", interaction: discord.Interaction) -> None:
+        await interaction.respond("You clicked the red button!", ephemeral=True)
+
+
+# Create a slash command that shows buttons
+@app.slash_command(name="buttons", description="Shows interactive buttons")
+async def buttons(ctx: discord.ApplicationContext) -> None:
+    # Create a view with buttons
+    view = MyView()
+    await ctx.respond("Choose a button:", view=view)
+
+
+if __name__ == "__main__":
+    app.run(
+        token=os.environ["DISCORD_TOKEN"],
+        public_key=os.environ["DISCORD_PUBLIC_KEY"],
+        uvicorn_options={
+            "host": "0.0.0.0",  # noqa: S104
+            "port": 8000,
+            "log_level": "info",
+        },
+    )

examples/modal_example.py

@@ -0,0 +1,62 @@
+# Copyright (c) Paillat-dev
+# SPDX-License-Identifier: MIT
+
+"""Example showing how to work with modals in Pycord REST."""
+
+import os
+from typing import Any
+
+import discord
+from dotenv import load_dotenv
+
+from pycord_rest import App
+
+# Load environment variables from .env file
+load_dotenv()
+
+app = App()
+
+
+class MyModal(discord.ui.Modal):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(
+            discord.ui.InputText(
+                label="Name", placeholder="Enter your name", style=discord.InputTextStyle.short, custom_id="name_input"
+            ),
+            discord.ui.InputText(
+                label="Feedback",
+                placeholder="Please provide your feedback here...",
+                style=discord.InputTextStyle.paragraph,
+                custom_id="feedback_input",
+            ),
+            *args,
+            **kwargs,
+        )
+
+    async def callback(self, interaction: discord.Interaction) -> None:
+        name = self.children[0].value
+
+        await interaction.respond(
+            f"Thank you for your feedback, {name}! Your submission has been received.", ephemeral=True
+        )
+
+
+# Command that shows a form modal
+@app.slash_command(name="feedback", description="Submit feedback through a form")
+async def feedback(ctx: discord.ApplicationContext) -> None:
+    # Create a modal
+    modal = MyModal(title="Feedback Form")
+    await ctx.send_modal(modal)
+    await ctx.respond("Opening feedback form...", ephemeral=True)
+
+
+if __name__ == "__main__":
+    app.run(
+        token=os.environ["DISCORD_TOKEN"],
+        public_key=os.environ["DISCORD_PUBLIC_KEY"],
+        uvicorn_options={
+            "host": "0.0.0.0",  # noqa: S104
+            "port": 8000,
+            "log_level": "info",
+        },
+    )

examples/webhook_events.py

@@ -0,0 +1,41 @@
+# Copyright (c) Paillat-dev
+# SPDX-License-Identifier: MIT
+
+"""Example showing how to work with webhook events in Pycord REST."""
+
+import os
+
+from dotenv import load_dotenv
+
+from pycord_rest import App, ApplicationAuthorizedEvent
+
+# Load environment variables from .env file
+load_dotenv()
+
+app = App()
+
+
+# Register the event handler
+@app.listen("on_application_authorized")
+async def on_application_authorized(event: ApplicationAuthorizedEvent) -> None:
+    if not event.guild:
+        print(f"User {event.user.display_name} ({event.user.id}) installed the application.")
+
+    else:
+        print(
+            f"Bot {event.user.display_name} ({event.user.id}) installed the application"
+            + f" to guild {event.guild.name} ({event.guild.id})."
+        )
+
+
+# Run the app
+if __name__ == "__main__":
+    app.run(
+        token=os.environ["DISCORD_TOKEN"],
+        public_key=os.environ["DISCORD_PUBLIC_KEY"],
+        uvicorn_options={
+            "host": "0.0.0.0",  # noqa: S104
+            "port": 8000,
+            "log_level": "info",
+        },
+    )

pyproject.toml

@@ -1,26 +1,30 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs", "hatch-fancy-pypi-readme"]
+build-backend = "hatchling.build"
+
 [project]
 name = "pycord-rest-bot"
-dynamic = ["version", "urls"]
-description = "A discord rest-bot wrapper for pycord"
-readme = "README.md"
+dynamic = ["version", "urls", "readme"]
+description = "A lightweight wrapper for Discord's HTTP interactions and webhook events using py-cord and FastAPI"
 authors = [
     { name = "Paillat-dev", email = "me@paillat.dev" }
 ]
 license = "MIT"
-requires-python = "==3.12.*"
+requires-python = ">=3.12, <4.0"
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12"
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+    "Operating System :: OS Independent",
 ]
 keywords = ["discord", "bot", "rest", "pycord"]
 dependencies = [
     "fastapi>=0.115.11",
     "orjson>=3.10.15",
-    "py-cord==2.6.1",
+    "py-cord>=2.7.0rc1",
     "pynacl>=1.5.0",
     "uvicorn>=0.34.0",
 ]
@@ -32,10 +36,6 @@ dev = [
     "ruff>=0.9.9",
 ]
 
-[build-system]
-requires = ["hatchling", "hatch-vcs"]
-build-backend = "hatchling.build"
-
 [tool.hatch.version]
 source = "vcs"
 
@@ -46,24 +46,60 @@ version-file = "src/pycord_rest/_version.py"
 Homepage = "https://github.com/Paillat-dev/pycord-rest"
 source_archive = "https://github.com/Paillat-dev/pycord-rest/archive/{commit_hash}.zip"
 
+[tool.hatch.metadata.hooks.fancy-pypi-readme]
+content-type = "text/markdown"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.md"
+start-after = "<!-- badges -->\n"
+end-before = "\n<!-- end badges -->"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+text = "\n\n---\n"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.md"
+start-after = "## Overview\n"
+end-before = "\n## Installation"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.md"
+start-after = "<!-- quick-start -->"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '\[(.+?)\]\(((?!https?://)\S+?)\)'
+replacement = '[\1](https://github.com/Paillat-dev/pycord-rest/tree/main\g<2>)'
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]'
+replacement = '**\1**:'
+
 [tool.hatchling]
 name = "pycord-rest-bot"
 
 [tool.hatch.build]
+include = [
+    "src/pycord_rest/",
+]
 exclude = [
     ".copywrite.hcl",
     ".github",
     ".python-version",
     "uv.lock",
 ]
-include = [
-    "src/pycord_rest/",
-]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pycord_rest"]
 
 [tool.pyright]
 pythonVersion = "3.12"
+typeCheckingMode = "all"
+reportUnusedCallResult = false
 reportAny = false
-executionEnvironments = [{ root = "src/pycord_rest/_version.py", reportDeprecated = false }]
+executionEnvironments = [
+    { root = "src/pycord_rest/_version.py", reportDeprecated = false },
+    { root = "examples", reportExplicitAny = false, reportUnknownMemberType = false, reportUnusedParameter = false, reportImplicitOverride = false, reportAttributeAccessIssue = false, reportUnknownVariableType = false },
+]
 
 [tool.ruff]
 target-version = "py312"
@@ -83,6 +119,7 @@ exclude = [
 
 [tool.ruff.lint]
 select = ["ALL"]
+per-file-ignores = { "examples/**/*" = ["INP001", "ARG002", "T201"] }
 extend-ignore = [
     "N999",
     "D104",
@@ -108,5 +145,6 @@ extend-ignore = [
     "FBT002",
     "PLR2004",
     "PLR0913",
-    "C901"
+    "C901",
+    "ISC003" # conflicts with basedpyright reportImplicitStringConcatenation
 ]

renovate.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "local>nicebots-xyz/renovate-config",
+    ":semanticPrefixFixDepsChoreOthers",
+    ":dependencyDashboard"
+  ],
+  "forkProcessing": "enabled",
+  "baseBranchPatterns": ["main"],
+  "lockFileMaintenance": {
+    "enabled": true
+  }
+}

src/pycord_rest/__init__.py

@@ -1,8 +1,7 @@
 # Copyright (c) Paillat-dev
 # SPDX-License-Identifier: MIT
-from discord import *  # noqa: F403, I001  # pyright: ignore [reportWildcardImportFromLibrary]
-from .app import App
+from .app import App, ApplicationAuthorizedEvent
 
 Bot = App
 
-__all__ = ["App", "Bot"]
+__all__ = ["App", "ApplicationAuthorizedEvent", "Bot"]

src/pycord_rest/app.py

@@ -1,7 +1,10 @@
 # Copyright (c) Paillat-dev
 # SPDX-License-Identifier: MIT
 
+import base64
+import functools
 import logging
+import warnings
 from collections.abc import Callable, Coroutine
 from functools import cached_property
 from typing import Any, Never, override
@@ -9,40 +12,82 @@ from typing import Any, Never, override
 import aiohttp
 import discord
 import uvicorn
-from discord import Interaction, InteractionType
-from fastapi import APIRouter, Depends, FastAPI, HTTPException, Request
-from fastapi.exceptions import FastAPIError
+from discord import Entitlement, Interaction, InteractionType
+from fastapi import APIRouter, Depends, FastAPI, HTTPException, Request, Response
 from nacl.exceptions import BadSignatureError
 from nacl.signing import VerifyKey
 
+from .errors import InvalidCredentialsError
+from .models import EventType, WebhookEventPayload, WebhookType
+
 logger = logging.getLogger("pycord.rest")
 
 
+class ApplicationAuthorizedEvent:
+    def __init__(self, user: discord.User, guild: discord.Guild | None, type: discord.IntegrationType) -> None:  # noqa: A002
+        self.type: discord.IntegrationType = type
+        self.user: discord.User = user
+        self.guild: discord.Guild | None = guild
+
+    @override
+    def __repr__(self) -> str:
+        return (
+            f"<ApplicationAuthorizedEvent type={self.type} user={self.user}"
+            + (f" guild={self.guild}" if self.guild else "")
+            + ">"
+        )
+
+
+def not_supported[T, U](func: Callable[[T], U]) -> Callable[[T], U]:
+    @functools.wraps(func)
+    def inner(*args: T, **kwargs: T) -> U:
+        logger.warning(f"{func.__qualname__} is not supported by REST apps.")
+        warnings.warn(
+            f"{func.__qualname__} is not supported by REST apps.",
+            SyntaxWarning,
+            stacklevel=2,
+        )
+        return func(*args, **kwargs)
+
+    return inner
+
+
 class App(discord.Bot):
-    def __init__(self, *args: Any, **options: Any) -> None:  # pyright: ignore [reportExplicitAny]
+    _UvicornConfig: type[uvicorn.Config] = uvicorn.Config
+    _UvicornServer: type[uvicorn.Server] = uvicorn.Server
+    _FastAPI: type[FastAPI] = FastAPI
+    _APIRouter: type[APIRouter] = APIRouter
+
+    def __init__(self, *args: Any, path_prefix: str = "", **options: Any) -> None:  # pyright: ignore [reportExplicitAny]
         super().__init__(*args, **options)  # pyright: ignore [reportUnknownMemberType]
-        self.app: FastAPI = FastAPI(openapi_url=None, docs_url=None, redoc_url=None)
-        self.router: APIRouter = APIRouter()
-        self.public_key: str | None = None
+        self._app: FastAPI = self._FastAPI(openapi_url=None, docs_url=None, redoc_url=None)
+        self.router: APIRouter = self._APIRouter(prefix=path_prefix)
+        self._public_key: str | None = None
+
+    @property
+    @override
+    @not_supported
+    def latency(self) -> float:
+        return 0.0
 
     @cached_property
     def _verify_key(self) -> VerifyKey:
-        if self.public_key is None:
-            raise FastAPIError("No public key provided")
-        return VerifyKey(bytes.fromhex(self.public_key))
+        if self._public_key is None:
+            raise InvalidCredentialsError("No public key provided")
+        return VerifyKey(bytes.fromhex(self._public_key))
 
     async def _dispatch_view(self, component_type: int, custom_id: str, interaction: Interaction) -> None:
         # Code taken from ViewStore.dispatch
         self._connection._view_store._ViewStore__verify_integrity()  # noqa: SLF001  # pyright: ignore [reportUnknownMemberType, reportAttributeAccessIssue, reportPrivateUsage]
         message_id: int | None = interaction.message and interaction.message.id
         key = (component_type, message_id, custom_id)
-        value = self._connection._view_store._views.get(key) or self._connection._view_store._views.get(  # pyright: ignore [reportUnknownVariableType, reportUnknownMemberType, reportPrivateUsage]  # noqa: SLF001
+        value = self._connection._view_store._views.get(key) or self._connection._view_store._views.get(  # pyright: ignore [reportPrivateUsage]  # noqa: SLF001
             (component_type, None, custom_id)
         )
         if value is None:
             return
 
-        view, item = value  # pyright: ignore [reportUnknownVariableType]
+        view, item = value
         item.refresh_state(interaction)
 
         # Code taken from View._dispatch_item
@@ -52,7 +97,7 @@ class App(discord.Bot):
         if interaction.message:
             view.message = interaction.message
 
-        await view._scheduled_task(item, interaction)  # noqa: SLF001  # pyright: ignore [reportPrivateUsage, reportUnknownMemberType]
+        await view._scheduled_task(item, interaction)  # noqa: SLF001 # pyright: ignore [reportPrivateUsage]
 
     async def _verify_request(self, request: Request) -> None:
         signature = request.headers["X-Signature-Ed25519"]
@@ -93,6 +138,7 @@ class App(discord.Bot):
     async def process_application_commands(  # noqa: PLR0912
         self, interaction: Interaction, auto_sync: bool | None = None
     ) -> None:
+        # Code taken from super().process_application_commands
         if auto_sync is None:
             auto_sync = self._bot.auto_sync_commands  # pyright: ignore [reportUnknownVariableType, reportUnknownMemberType]
         # TODO: find out why the isinstance check below doesn't stop the type errors below  # noqa: FIX002, TD002, TD003
@@ -162,6 +208,50 @@ class App(discord.Bot):
 
         return health
 
+    async def _handle_webhook_event(self, data: dict[str, Any] | None, event_type: EventType) -> None:  # pyright: ignore [reportExplicitAny]
+        if not data:
+            raise HTTPException(status_code=400, detail="Missing event data")
+
+        match event_type:
+            case EventType.APPLICATION_AUTHORIZED:
+                event = ApplicationAuthorizedEvent(
+                    user=discord.User(state=self._connection, data=data["user"]),
+                    guild=(discord.Guild(state=self._connection, data=data["guild"]) if data.get("guild") else None),
+                    type=discord.IntegrationType.guild_install
+                    if data.get("guild")
+                    else discord.IntegrationType.user_install,
+                )
+                logger.debug("Dispatching application_authorized event")
+                self.dispatch("application_authorized", event)
+                if event.type == discord.IntegrationType.guild_install:
+                    self.dispatch("guild_join", event.guild)
+            case EventType.ENTITLEMENT_CREATE:
+                entitlement = Entitlement(data=data, state=self._connection)  # pyright: ignore [reportArgumentType]
+                logger.debug("Dispatching entitlement_create event")
+                self.dispatch("entitlement_create", entitlement)
+            case _:
+                logger.warning(f"Unsupported webhook event type received: {event_type}")
+
+    async def _webhook_event(self, payload: WebhookEventPayload) -> Response | dict[str, Any]:  # pyright: ignore [reportExplicitAny]
+        match payload.type:
+            case WebhookType.PING:
+                return Response(status_code=204)
+            case WebhookType.Event:
+                if not payload.event:
+                    raise HTTPException(status_code=400, detail="Missing event data")
+                await self._handle_webhook_event(payload.event.data, payload.event.type)
+
+        return {"ok": True}
+
+    def _webhook_event_factory(
+        self,
+    ) -> Callable[[WebhookEventPayload], Coroutine[Any, Any, Response | dict[str, Any]]]:  # pyright: ignore [reportExplicitAny]
+        @self.router.post("/webhook", dependencies=[Depends(self._verify_request)], response_model=None)
+        async def webhook_event(payload: WebhookEventPayload) -> Response | dict[str, Any]:  # pyright: ignore [reportExplicitAny]
+            return await self._webhook_event(payload)
+
+        return webhook_event
+
     @override
     async def connect(  # pyright: ignore [reportIncompatibleMethodOverride]
         self,
@@ -170,16 +260,18 @@ class App(discord.Bot):
         uvicorn_options: dict[str, Any] | None = None,  # pyright: ignore [reportExplicitAny]
         health: bool = True,
     ) -> None:
-        self.public_key = public_key
+        self._public_key = public_key
         _ = self._process_interaction_factory()
-        self.app.include_router(self.router)
+        _ = self._webhook_event_factory()
         if health:
             _ = self._health_factory()
-        self.app.include_router(self.router)
+        self._app.include_router(self.router)
         uvicorn_options = uvicorn_options or {}
         uvicorn_options["log_level"] = uvicorn_options.get("log_level", logging.root.level)
-        config = uvicorn.Config(self.app, **uvicorn_options)
-        server = uvicorn.Server(config)
+        uvicorn_options["server_header"] = uvicorn_options.get("server_header", False)
+        config = self._UvicornConfig(self._app, **uvicorn_options)
+        server = self._UvicornServer(config)
+        self._connection.application_id = int(base64.b64decode(token.split(".")[0] + "==").decode("utf-8"))
         try:
             self.dispatch("connect")
             await server.serve()
@@ -189,7 +281,10 @@ class App(discord.Bot):
 
     @override
     async def close(self) -> None:
-        pass
+        self._closed: bool = True
+
+        await self.http.close()
+        self._ready.clear()
 
     @override
     async def start(  # pyright: ignore [reportIncompatibleMethodOverride]
@@ -199,6 +294,10 @@ class App(discord.Bot):
         uvicorn_options: dict[str, Any] | None = None,  # pyright: ignore [reportExplicitAny]
         health: bool = True,
     ) -> None:
+        if not token:
+            raise InvalidCredentialsError("No token provided")
+        if not public_key:
+            raise InvalidCredentialsError("No public key provided")
         await self.login(token)
         await self.connect(
             token=token,

src/pycord_rest/errors.py

@@ -0,0 +1,12 @@
+# Copyright (c) Paillat-dev
+# SPDX-License-Identifier: MIT
+
+import discord
+
+
+class PycordRestError(discord.DiscordException):
+    pass
+
+
+class InvalidCredentialsError(PycordRestError):
+    pass

src/pycord_rest/models.py

@@ -0,0 +1,32 @@
+# Copyright (c) Paillat-dev
+# SPDX-License-Identifier: MIT
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class WebhookType(Enum):
+    PING = 0
+    Event = 1
+
+
+class EventType(Enum):
+    APPLICATION_AUTHORIZED = "APPLICATION_AUTHORIZED"
+    ENTITLEMENT_CREATE = "ENTITLEMENT_CREATE"
+    QUEST_USER_ENROLLMENT = "QUEST_USER_ENROLLMENT"
+
+
+class EventBody(BaseModel):
+    type: EventType
+    timestamp: datetime
+    data: dict[str, Any] | None = None  # pyright: ignore [reportExplicitAny]
+
+
+class WebhookEventPayload(BaseModel):
+    version: int
+    application_id: int
+    type: WebhookType
+    event: EventBody | None = None